kiru 1.0.1 → 1.1.0

package/src/env.ts

@@ -4,3 +4,6 @@ if (NODE_ENV !== "development" && NODE_ENV !== "production") {
 }
 
 export const __DEV__ = NODE_ENV === "development"
+
+export const isBrowser = "window" in globalThis && typeof window !== "undefined"
+export const isServer = !isBrowser

package/src/globalContext.ts

@@ -1,17 +1,16 @@
 import { __DEV__ } from "./env.js"
-import { createHMRContext } from "./hmr.js"
+import { createHmrContext } from "./hmr.js"
 import { createProfilingContext } from "./profiling.js"
 import { fileRouterInstance } from "./router/globals.js"
 import type { FileRouterController } from "./router/fileRouterController"
 import type { AppHandle } from "./appHandle"
-import type { requestUpdate } from "./index.js"
 
 export { createKiruGlobalContext, type GlobalKiruEvent, type KiruGlobalContext }
 
 type Evt =
   | {
       name: "mount"
-      data?: typeof requestUpdate
+      data?: undefined
     }
   | {
       name: "unmount"
@@ -28,10 +27,6 @@ type Evt =
 
 type GlobalKiruEvent = Evt["name"]
 
-interface SchedulerInterface {
-  requestUpdate: (vNode: Kiru.VNode) => void
-}
-
 export type DebuggerEntry = {
   label: string
   signal: Kiru.Signal<unknown>
@@ -53,17 +48,15 @@ interface KiruGlobalContext {
     untrack: (signal: Kiru.Signal<unknown>) => void
     subscribe: (callback: (entries: Set<DebuggerEntry>) => void) => () => void
   }
-  HMRContext?: ReturnType<typeof createHMRContext>
+  HMRContext?: ReturnType<typeof createHmrContext>
   profilingContext?: ReturnType<typeof createProfilingContext>
   fileRouterInstance?: {
     current: FileRouterController | null
   }
-  getSchedulerInterface?: (app: AppHandle) => SchedulerInterface | null
 }
 
 function createKiruGlobalContext(): KiruGlobalContext {
   const apps = new Set<AppHandle>()
-  const appToSchedulerInterface = new WeakMap<AppHandle, SchedulerInterface>()
   const listeners = new Map<
     GlobalKiruEvent,
     Set<(app: AppHandle, data?: Evt["data"]) => void>
@@ -103,23 +96,13 @@ function createKiruGlobalContext(): KiruGlobalContext {
   }
 
   // Initialize event listeners
-  on("mount", (app, requestUpdate) => {
-    apps.add(app)
-    if (requestUpdate && typeof requestUpdate === "function") {
-      appToSchedulerInterface.set(app, { requestUpdate })
-    }
-  })
-  on("unmount", (app) => {
-    apps.delete(app)
-    appToSchedulerInterface.delete(app)
-  })
+  on("mount", (app) => apps.add(app))
+  on("unmount", (app) => apps.delete(app))
+
   if (__DEV__) {
-    globalContext.HMRContext = createHMRContext()
+    globalContext.HMRContext = createHmrContext()
     globalContext.profilingContext = createProfilingContext()
     globalContext.fileRouterInstance = fileRouterInstance
-    globalContext.getSchedulerInterface = (app) => {
-      return appToSchedulerInterface.get(app) ?? null
-    }
 
     const debuggerEntries = new Set<DebuggerEntry>()
     const subscribers = new Set<(debuggerEntries: Set<DebuggerEntry>) => void>()

package/src/globals.ts

@@ -1,13 +1,36 @@
-export { node, renderMode, hydrationMode }
+import { Setup } from "./hooks/index.js"
+import { isBrowser } from "./env.js"
+export { node, renderMode, hydrationMode, setups, postEffectCleanups }
 
+/**
+ * A reference to the current VNode (always a component) being rendered.
+ */
 const node = {
   current: null as Kiru.VNode | null,
 }
 
+/**
+ * The current render mode. Can be "dom" "string", "stream", or "hydrate".
+ */
 const renderMode = {
-  current: ("window" in globalThis ? "dom" : "string") as Kiru.RenderMode,
+  current: (isBrowser ? "dom" : "string") as Kiru.RenderMode,
 }
 
+/**
+ * The current hydration mode. Can be "static" or "dynamic".
+ * Used to indicate whether the page being hydrated will contain streamed content.
+ */
 const hydrationMode = {
   current: "dynamic" as "static" | "dynamic",
 }
+
+/**
+ * A map of VNodes (components) to their setup functions.
+ */
+const setups: WeakMap<Kiru.VNode, Setup<any>> = new WeakMap()
+
+/**
+ * Cleanup functions from onMount() that run after components
+ * have been unmounted and the browser has painted.
+ */
+const postEffectCleanups: (() => void)[] = []

package/src/hmr.ts

@@ -13,7 +13,7 @@ export type HMRAccept<T = {}> = {
 export type GenericHMRAcceptor<T = {}> = {
   [$HMR_ACCEPT]: HMRAccept<T>
 }
-type HotVar = Kiru.FC | Signal<any> | Kiru.ContextBase<any>
+type HotVar = Kiru.FC | Signal<any> | Kiru.Context<any>
 
 type HotVarDesc = {
   type: string
@@ -42,6 +42,7 @@ export function isGenericHmrAcceptor(
 type ModuleMemory = {
   hotVars: Map<string, HotVarDesc>
   unnamedEffects: Array<Effect>
+  hmrCallbacks: Array<() => void>
 }
 
 type HotVarRegistrationEntry = {
@@ -50,7 +51,7 @@ type HotVarRegistrationEntry = {
   link: string
 }
 
-export function createHMRContext() {
+export function createHmrContext() {
   type FilePath = string
   const moduleMap = new Map<FilePath, ModuleMemory>()
   let currentModuleFilePath: string | null = null
@@ -59,9 +60,13 @@ export function createHMRContext() {
   const isReplacement = () => isModuleReplacementExecution
   let isWaitingForNextEffect = false
 
-  const onHmrCallbacks: Array<() => void> = []
+  const globalHmrCallbacks: Array<() => void> = []
   const onHmr = (callback: () => void) => {
-    onHmrCallbacks.push(callback)
+    if (currentModuleMemory) {
+      currentModuleMemory.hmrCallbacks.push(callback)
+      return
+    }
+    globalHmrCallbacks.push(callback)
   }
 
   const prepare = (filePath: string) => {
@@ -71,10 +76,12 @@ export function createHMRContext() {
       mod = {
         hotVars: new Map(),
         unnamedEffects: [],
+        hmrCallbacks: [],
       }
       moduleMap.set(filePath, mod)
     } else {
-      while (onHmrCallbacks.length) onHmrCallbacks.shift()!()
+      while (mod.hmrCallbacks.length) mod.hmrCallbacks.shift()!()
+      while (globalHmrCallbacks.length) globalHmrCallbacks.shift()!()
       for (const effect of mod.unnamedEffects) {
         effect.stop()
       }
@@ -165,3 +172,23 @@ export function createHMRContext() {
     },
   }
 }
+
+/**
+ * Queues a callback to be fired when HMR is triggered. This is a no-op in non-browser environments or in production.
+ * - If called during current module evaluation, the callback will be fired the next time the current module is evaluated.
+ * - If called at any other time, the callback will be fired the next time HMR is triggered.
+ * @see https://kirujs.dev/docs/api/lifecycles#onHmr
+ * 
+ * ```ts
+ * import { onHmr } from "kiru"
+ * // start an interval in the module scope
+ * const interval = setInterval(() => {...}, 1000)
+ * // stop the interval when this file is reloaded
+ * onHmr(() => clearInterval(interval))
+ ```
+ */
+export function onHmr(callback: () => void): void {
+  if ("window" in globalThis && window.__kiru.HMRContext) {
+    window.__kiru.HMRContext.onHmr(callback)
+  }
+}

package/src/hooks/index.ts

@@ -1,4 +1,5 @@
 export * from "./onCleanup.js"
 export * from "./onMount.js"
 export * from "./onBeforeMount.js"
+export * from "./setup.js"
 export * from "./utils.js"

package/src/hooks/onBeforeMount.ts

@@ -1,12 +1,18 @@
-import { queueSetupEffect } from "./utils.js"
+import { sideEffectsEnabled } from "../utils/index.js"
+import { getVNodeLifecycleHooks, wrapLifecycleHookCallback } from "./utils.js"
 
 /**
  * Registers a callback that runs after the component is first mounted to the DOM, but before the DOM is painted.
  * Optionally returns a cleanup function that will run when the component unmounts.
  * Intended for use during component setup when the component returns a render function.
  *
- * @see https://kirujs.dev/docs/hooks/onBeforeMount
+ * @see https://kirujs.dev/docs/api/lifecycles#onBeforeMount
  */
 export function onBeforeMount(fn: () => (() => void) | void): void {
-  queueSetupEffect(fn, { immediate: true })
+  if (!sideEffectsEnabled()) return
+  const hooks = getVNodeLifecycleHooks()
+  if (!hooks) {
+    throw new Error("Cannot queue beforeMount effect outside of a component")
+  }
+  hooks.pre.push(wrapLifecycleHookCallback(fn, hooks.preCleanups))
 }

package/src/hooks/onCleanup.ts

@@ -1,15 +1,21 @@
 import { node } from "../globals.js"
-import { generateRandomID, registerVNodeCleanup } from "../utils/index.js"
+import {
+  generateRandomID,
+  registerVNodeCleanup,
+  sideEffectsEnabled,
+} from "../utils/index.js"
 
 /**
  * Registers a cleanup function that runs when the component unmounts.
  * Intended for use during component setup when the component returns a render function.
  *
- * @see https://kirujs.dev/docs/hooks/onCleanup
+ * @see https://kirujs.dev/docs/api/lifecycles#onCleanup
  */
 export function onCleanup(fn: () => void): void {
+  if (!sideEffectsEnabled()) return
   const vNode = node.current!
-  if (!vNode)
-    throw new Error("Cannot queue cleanup effect outside of a component")
+  if (!vNode) {
+    throw new Error("Cannot queue onCleanup effect outside of a component")
+  }
   registerVNodeCleanup(vNode, generateRandomID(10), fn)
 }

package/src/hooks/onMount.ts

@@ -1,12 +1,18 @@
-import { queueSetupEffect } from "./utils.js"
+import { sideEffectsEnabled } from "../utils/index.js"
+import { getVNodeLifecycleHooks, wrapLifecycleHookCallback } from "./utils.js"
 
 /**
  * Registers a callback that runs after the component is first mounted to the DOM.
- * Optionally returns a cleanup function that will run when the component unmounts.
+ * Optionally returns a cleanup function that will run after the component unmounts.
  * Intended for use during component setup when the component returns a render function.
  *
- * @see https://kirujs.dev/docs/hooks/onMount
+ * @see https://kirujs.dev/docs/api/lifecycles#onMount
  */
 export function onMount(fn: () => (() => void) | void): void {
-  queueSetupEffect(fn)
+  if (!sideEffectsEnabled()) return
+  const hooks = getVNodeLifecycleHooks()
+  if (!hooks) {
+    throw new Error("Cannot queue onMount effect outside of a component")
+  }
+  hooks.post.push(wrapLifecycleHookCallback(fn, hooks.postCleanups))
 }

package/src/hooks/setup.ts

@@ -0,0 +1,70 @@
+import { node, setups } from "../globals.js"
+import { signal } from "../signals/index.js"
+import type { Signal } from "../signals/base.js"
+import { createVNodeId } from "../utils/vdom.js"
+import { __DEV__ } from "../env.js"
+
+export interface Setup<Props extends {}> {
+  readonly derive: <T>(
+    selector: (props: Props extends Kiru.FC<infer P> ? P : Props) => T
+  ) => Signal<T>
+  readonly id: Signal<string>
+}
+
+/**
+ * Creates a per‑VNode setup context that can be used during
+ * component setup to derive props into signals.
+ *
+ * @see https://kirujs.dev/docs/api/lifecycles#setup
+ */
+export function setup<Props extends {}>(): Setup<Props> {
+  const vNode = node.current!
+  if (__DEV__) {
+    if (!vNode) {
+      throw new Error("setup() must be called inside a Kiru component")
+    }
+    if (vNode.render) {
+      throw new Error("setup() cannot be used inside a render function")
+    }
+  }
+
+  if (setups.has(vNode)) {
+    return setups.get(vNode)!
+  }
+
+  const setup = createSetup<Props>(vNode)
+  setups.set(vNode, setup)
+  return setup
+}
+
+function createSetup<Props extends {}>(vNode: Kiru.VNode): Setup<Props> {
+  let id: Signal<string>
+
+  type InferredProps = Props extends Kiru.FC<infer R> ? R : Props
+  const propSyncs = (vNode.propSyncs = []) as ((props: InferredProps) => void)[]
+
+  let prevIndex = -1
+
+  return {
+    derive(selector) {
+      const props = { ...vNode.props } as InferredProps
+      const sig = signal(selector(props))
+      propSyncs.push((p) => (sig.value = selector(p)))
+      return sig
+    },
+    get id() {
+      if (!id) {
+        id = signal(createVNodeId(vNode))
+        prevIndex = vNode.index
+        propSyncs.push(() => {
+          if (prevIndex !== vNode.index) {
+            id.value = createVNodeId(vNode)
+            prevIndex = vNode.index
+          }
+        })
+      }
+
+      return id
+    },
+  }
+}

package/src/hooks/utils.ts

@@ -1,32 +1,27 @@
 import { node } from "../globals.js"
-import { sideEffectsEnabled } from "../utils/index.js"
 
-export function queueSetupEffect(
-  effect: Kiru.LifecycleHookCallback,
-  opts?: { immediate?: boolean }
-): void {
-  if (!sideEffectsEnabled()) return
+export function getVNodeLifecycleHooks(): null | NonNullable<
+  Kiru.VNode["hooks"]
+> {
   const vNode = node.current!
-  if (!vNode)
-    throw new Error("Cannot queue setup effect outside of a component")
+  if (!vNode) return null
 
-  const hooks = (vNode.hooks ??= {
+  return (vNode.hooks ??= {
     pre: [],
     preCleanups: [],
     post: [],
     postCleanups: [],
   })
+}
 
-  const [bag, cleanups] = opts?.immediate
-    ? [hooks.pre, hooks.preCleanups]
-    : [hooks.post, hooks.postCleanups]
-
-  const wrapped = () => {
-    const ret = effect()
-    if (typeof ret === "function") {
-      cleanups.push(ret)
+export function wrapLifecycleHookCallback(
+  callback: Kiru.LifecycleHookCallback,
+  cleanups: (() => void)[]
+): Kiru.LifecycleHookCallback {
+  return () => {
+    const cleanup = callback()
+    if (typeof cleanup === "function") {
+      cleanups.push(cleanup)
     }
   }
-
-  bag.push(wrapped)
 }

package/src/index.ts

@@ -1,4 +1,5 @@
 import { createKiruGlobalContext } from "./globalContext.js"
+import { isBrowser } from "./env.js"
 
 export type * from "./types"
 export * from "./signals/index.js"
@@ -10,6 +11,7 @@ export * from "./customEvents.js"
 export * from "./devtools.js"
 export * from "./element.js"
 export * from "./error.js"
+export { onHmr } from "./hmr.js"
 export * from "./hooks/index.js"
 export type { ProfilingEvent, AppStats } from "./profiling.js"
 export * from "./renderToString.js"
@@ -23,6 +25,6 @@ export {
 export * from "./statefulPromise.js"
 export * from "./viewTransitions.js"
 
-if ("window" in globalThis) {
-  globalThis.window.__kiru ??= createKiruGlobalContext()
+if (isBrowser) {
+  window.__kiru ??= createKiruGlobalContext()
 }

package/src/reconciler.ts

@@ -7,7 +7,7 @@ import {
   propsChanged,
 } from "./utils/index.js"
 import { Signal } from "./signals/base.js"
-import { __DEV__ } from "./env.js"
+import { __DEV__, isBrowser } from "./env.js"
 import type { AppHandle } from "./appHandle.js"
 import { createVNode as createBaseVNode } from "./vNode.js"
 
@@ -376,7 +376,7 @@ function updateFromMap(
 }
 
 function dev_emitUpdateNode() {
-  if (!("window" in globalThis)) return
+  if (!isBrowser) return
   window.__kiru.profilingContext?.emit("updateNode", app)
 }
 
@@ -479,7 +479,7 @@ function createVNode(
   const node = createBaseVNode(type, parent, props, key, index)
   node.flags |= FLAG_PLACEMENT
 
-  if (__DEV__ && "window" in globalThis) {
+  if (__DEV__ && isBrowser) {
     window.__kiru.profilingContext?.emit("createNode", app)
   }
   return node

package/src/router/head.ts

@@ -1,7 +1,7 @@
 import { Signal } from "../signals/base.js"
 import { isValidTextChild, isVNode } from "../utils/index.js"
 import { createElement } from "../element.js"
-import { __DEV__ } from "../env.js"
+import { __DEV__, isBrowser } from "../env.js"
 import { KiruError } from "../error.js"
 import { node } from "../globals.js"
 
@@ -28,7 +28,7 @@ function HeadContent({ children }: { children: JSX.Children }): JSX.Element {
       })
     }
   }
-  if ("window" in globalThis) {
+  if (isBrowser) {
     const asArray = Array.isArray(children) ? children : [children]
     const titleNode = asArray.find(
       (c) => isVNode(c) && c.type === "title"

package/src/router/pageConfig.ts

@@ -1,9 +1,9 @@
-import { __DEV__ } from "../env.js"
+import { __DEV__, isBrowser } from "../env.js"
 import { fileRouterInstance } from "./globals.js"
 import type { PageConfig } from "./types"
 
 export function definePageConfig<T>(config: PageConfig<T>): PageConfig<T> {
-  if (__DEV__ && "window" in globalThis) {
+  if (__DEV__ && isBrowser) {
     const filePath = window.__kiru?.HMRContext?.getCurrentFilePath()
     const fileRouter = fileRouterInstance.current
     if (filePath && fileRouter) {