conjure-js 0.0.12 → 0.0.13

package/src/core/session.ts

@@ -1,508 +1,185 @@
-import { isKeyword, isList, isSymbol, isVector } from './assertions'
-import { loadCoreFunctions } from './core-env'
-import { define, internVar, lookup, lookupVar, makeEnv, makeNamespace, tryLookup } from './env'
-import { valueToString } from './transformations'
-import { createEvaluationContext, RecurSignal } from './evaluator'
+import { builtInNamespaceSources } from '../clojure/generated/builtin-namespace-registry'
 import { CljThrownSignal, EvaluationError, ReaderError } from './errors'
-import { cljNativeFunction, cljNil } from './factories'
+import { createEvaluationContext, RecurSignal } from './evaluator'
+import { internVar, makeEnv } from './env'
+import { v } from './factories'
+import { jsToClj } from './evaluator/js-interop'
+import type { RuntimeModule } from './module'
+import { cljToJs as _cljToJs } from './conversions'
 import { formatErrorContext } from './positions'
 import { printString } from './printer'
 import { readForms } from './reader'
+import type { Runtime, RuntimeSnapshot } from './runtime'
+import { createRuntime, restoreRuntime } from './runtime'
+import { extractAliasMapFromTokens, extractNsNameFromTokens } from './ns-forms'
 import { tokenize } from './tokenizer'
-import type { CljNamespace, CljValue, Env, Token, TokenSymbol } from './types'
-import { builtInNamespaceSources } from '../clojure/generated/builtin-namespace-registry'
+import type { CljNamespace, CljValue, Env } from './types'
 
-type NamespaceRegistry = Map<string, Env>
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
 
-type SessionOptions = {
+export type SessionOptions = {
+  /** Primary output channel — wired to ctx.io.stdout (println, print, pr, prn, pprint, newline). */
   output?: (text: string) => void
+  /** Secondary error channel — wired to ctx.io.stderr. */
+  stderr?: (text: string) => void
   entries?: string[]
   sourceRoots?: string[]
   readFile?: (filePath: string) => string
+  modules?: RuntimeModule[]
+  /**
+   * Ambient JS globals injected into the `js` namespace as CljJsValue vars.
+   * Each key becomes accessible as `js/<key>` in Clojure code without any require.
+   * Example: `{ Math, console, fetch }` → `js/Math`, `js/console`, `js/fetch`.
+   */
+  hostBindings?: Record<string, unknown>
+  /**
+   * Called when (:require ["specifier" :as Alias]) is encountered.
+   * Must return (or resolve to) the module object, which is boxed as CljJsValue
+   * and bound to Alias in the current namespace.
+   * Only usable via evaluateAsync() — string requires are inherently async.
+   * Examples:
+   *   Node/Bun:  importModule: (s) => import(s)
+   *   Vite:      importModule: (s) => import(s)   // Vite resolves statically at build time
+   *   Tests:     importModule: (s) => fakeModules[s]
+   */
+  importModule?: (specifier: string) => unknown | Promise<unknown>
 }
 
 export type Session = {
-  registry: NamespaceRegistry
+  /** The underlying runtime — exposed for snapshot access and advanced embedding. */
+  readonly runtime: Runtime
+  /** Passthrough to runtime.registry. Used by nREPL and tooling for namespace lookup. */
+  readonly registry: Runtime['registry']
   readonly currentNs: string
   setNs: (namespace: string) => void
   getNs: (namespace: string) => CljNamespace | null
   loadFile: (source: string, nsName?: string, filePath?: string) => string
-  evaluate: (source: string, opts?: { lineOffset?: number; colOffset?: number; file?: string }) => CljValue
+  /** Async variant of loadFile — handles string requires ((:require ["pkg" :as X])). */
+  loadFileAsync: (source: string, nsName?: string, filePath?: string) => Promise<string>
+  evaluate: (
+    source: string,
+    opts?: { lineOffset?: number; colOffset?: number; file?: string }
+  ) => CljValue
+  evaluateAsync: (
+    source: string,
+    opts?: { lineOffset?: number; colOffset?: number; file?: string }
+  ) => Promise<CljValue>
   evaluateForms: (forms: CljValue[]) => CljValue
+  /**
+   * Call a CljFunction or CljNativeFunction using this session's evaluation context.
+   * Unlike the bare `applyFunction` export from `core/index`, this resolves namespaces
+   * through the session's runtime registry — required for any CLJ code that references
+   * qualified symbols like `js/Math` or `:require`-d aliases.
+   */
+  applyFunction: (fn: CljValue, args: CljValue[]) => CljValue
+  /**
+   * Convert a CljValue to a plain JS value using this session's evaluation context.
+   * CLJ functions are wrapped as JS callbacks that invoke via session.applyFunction,
+   * ensuring namespace resolution works for js/Math and other runtime namespaces.
+   */
+  cljToJs: (value: CljValue) => unknown
   addSourceRoot: (path: string) => void
   getCompletions: (prefix: string, nsName?: string) => string[]
 }
 
-// Lightweight token scan to extract the namespace name before full parsing.
-// Looks for the pattern: LParen Symbol("ns") Symbol(name) at the top of the token stream.
-function extractNsNameFromTokens(tokens: Token[]): string | null {
-  const meaningful = tokens.filter((t) => t.kind !== 'Comment')
-  if (meaningful.length < 3) return null
-  if (meaningful[0].kind !== 'LParen') return null
-  if (meaningful[1].kind !== 'Symbol' || meaningful[1].value !== 'ns')
-    return null
-  if (meaningful[2].kind !== 'Symbol') return null
-  return meaningful[2].value
-}
-
-// Lightweight token scan to extract :as alias pairs from the ns form's :require clauses.
-// Returns Map { 'alias' -> 'full.ns.name' } for all [some.ns :as alias] specs found.
-// This runs before readForms so the reader can expand ::alias/foo at read time.
-function extractAliasMapFromTokens(tokens: Token[]): Map<string, string> {
-  const aliases = new Map<string, string>()
-  const meaningful = tokens.filter(
-    (t) => t.kind !== 'Comment' && t.kind !== 'Whitespace'
-  )
-  // Must start with (ns ...)
-  if (meaningful.length < 3) return aliases
-  if (meaningful[0].kind !== 'LParen') return aliases
-  if (meaningful[1].kind !== 'Symbol' || meaningful[1].value !== 'ns')
-    return aliases
-
-  // Walk the top-level ns form tracking paren depth.
-  // For each [ vector ] we encounter, check for ns-sym :as alias-sym.
-  let i = 3 // skip ( ns <name>
-  let depth = 1
-  while (i < meaningful.length && depth > 0) {
-    const tok = meaningful[i]
-    if (tok.kind === 'LParen') {
-      depth++
-      i++
-      continue
-    }
-    if (tok.kind === 'RParen') {
-      depth--
-      i++
-      continue
-    }
-    if (tok.kind === 'LBracket') {
-      // Scan through this vector for: first Symbol (ns name) + :as + Symbol (alias)
-      let j = i + 1
-      let nsSym: string | null = null
-      while (j < meaningful.length && meaningful[j].kind !== 'RBracket') {
-        const t = meaningful[j]
-        if (t.kind === 'Symbol' && nsSym === null) {
-          nsSym = t.value
-        }
-        if (
-          t.kind === 'Keyword' &&
-          (t.value === ':as' || t.value === ':as-alias')
-        ) {
-          j++
-          if (
-            j < meaningful.length &&
-            meaningful[j].kind === 'Symbol' &&
-            nsSym
-          ) {
-            aliases.set((meaningful[j] as TokenSymbol).value, nsSym)
-          }
-        }
-        j++
-      }
-    }
-    i++
-  }
-  return aliases
-}
-
-function findNsForm(forms: CljValue[]) {
-  const nsForm = forms.find(
-    (f) => isList(f) && isSymbol(f.value[0]) && f.value[0].name === 'ns'
-  )
-  if (!nsForm || !isList(nsForm)) return null
-  return nsForm
-}
-
-function extractRequireClauses(forms: CljValue[]): CljValue[][] {
-  const nsForm = findNsForm(forms)
-  if (!nsForm) return []
-  const clauses: CljValue[][] = []
-  for (let i = 2; i < nsForm.value.length; i++) {
-    const clause = nsForm.value[i]
-    if (
-      isList(clause) &&
-      isKeyword(clause.value[0]) &&
-      clause.value[0].name === ':require'
-    ) {
-      clauses.push(clause.value.slice(1))
-    }
-  }
-  return clauses
-}
-
-function processRequireSpec(
-  spec: CljValue,
-  currentEnv: Env,
-  registry: NamespaceRegistry,
-  resolveNamespace?: (nsName: string) => boolean
-): void {
-  if (!isVector(spec)) {
-    throw new EvaluationError(
-      'require spec must be a vector, e.g. [my.ns :as alias]',
-      { spec }
-    )
-  }
-
-  const elements = spec.value
-  if (elements.length === 0 || !isSymbol(elements[0])) {
-    throw new EvaluationError(
-      'First element of require spec must be a namespace symbol',
-      { spec }
-    )
-  }
-
-  const nsName = elements[0].name
-
-  // :as-alias creates a reader alias without loading the namespace.
-  // The namespace need not exist — the alias is only used for ::alias/foo expansion.
-  const hasAsAlias = elements.some(
-    (el) => isKeyword(el) && el.name === ':as-alias'
-  )
-  if (hasAsAlias) {
-    let i = 1
-    while (i < elements.length) {
-      const kw = elements[i]
-      if (!isKeyword(kw)) {
-        throw new EvaluationError(
-          `Expected keyword in require spec, got ${kw.kind}`,
-          { spec, position: i }
-        )
-      }
-      if (kw.name === ':as-alias') {
-        i++
-        const alias = elements[i]
-        if (!alias || !isSymbol(alias)) {
-          throw new EvaluationError(':as-alias expects a symbol alias', {
-            spec,
-            position: i,
-          })
-        }
-        currentEnv.ns!.readerAliases.set(alias.name, nsName)
-        i++
-      } else {
-        throw new EvaluationError(
-          `:as-alias specs only support :as-alias, got ${kw.name}`,
-          { spec }
-        )
-      }
-    }
-    return
-  }
-
-  let targetEnv = registry.get(nsName)
-  if (!targetEnv && resolveNamespace) {
-    resolveNamespace(nsName)
-    targetEnv = registry.get(nsName)
-  }
-  if (!targetEnv) {
-    throw new EvaluationError(
-      `Namespace ${nsName} not found. Only already-loaded namespaces can be required.`,
-      { nsName }
-    )
-  }
-
-  let i = 1
-  while (i < elements.length) {
-    const kw = elements[i]
-    if (!isKeyword(kw)) {
-      throw new EvaluationError(
-        `Expected keyword in require spec, got ${kw.kind}`,
-        { spec, position: i }
-      )
-    }
-
-    if (kw.name === ':as') {
-      i++
-      const alias = elements[i]
-      if (!alias || !isSymbol(alias)) {
-        throw new EvaluationError(':as expects a symbol alias', {
-          spec,
-          position: i,
-        })
-      }
-      currentEnv.ns!.aliases.set(alias.name, targetEnv.ns!)
-      i++
-    } else if (kw.name === ':refer') {
-      i++
-      const symsVec = elements[i]
-      if (!symsVec || !isVector(symsVec)) {
-        throw new EvaluationError(':refer expects a vector of symbols', {
-          spec,
-          position: i,
-        })
-      }
-      for (const sym of symsVec.value) {
-        if (!isSymbol(sym)) {
-          throw new EvaluationError(':refer vector must contain only symbols', {
-            spec,
-            sym,
-          })
-        }
-        const v = lookupVar(sym.name, targetEnv)
-        if (v !== undefined) {
-          currentEnv.ns!.vars.set(sym.name, v)
-        } else {
-          let value: CljValue
-          try {
-            value = lookup(sym.name, targetEnv)
-          } catch {
-            throw new EvaluationError(
-              `Symbol ${sym.name} not found in namespace ${nsName}`,
-              { nsName, symbol: sym.name }
-            )
-          }
-          define(sym.name, value, currentEnv)
-        }
-      }
-      i++
-    } else {
-      throw new EvaluationError(
-        `Unknown require option ${kw.name}. Supported: :as, :refer`,
-        { spec, keyword: kw.name }
-      )
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Clone helpers — used by snapshotSession / createSessionFromSnapshot
-// ---------------------------------------------------------------------------
-
-function cloneBindings(bindings: Map<string, CljValue>): Map<string, CljValue> {
-  const out = new Map<string, CljValue>()
-  for (const [k, v] of bindings) {
-    out.set(k, v.kind === 'var' ? { ...v } : v)
-  }
-  return out
-}
-
-function cloneEnv(env: Env, memo: Map<Env, Env>): Env {
-  if (memo.has(env)) return memo.get(env)!
-  const cloned: Env = {
-    bindings: cloneBindings(env.bindings),
-    outer: null,
-  }
-  if (env.ns) {
-    cloned.ns = {
-      name: env.ns.name,
-      vars: new Map([...env.ns.vars].map(([k, v]) => [k, { ...v }])),
-      aliases: new Map(), // wired in cloneRegistry pass 2
-      readerAliases: new Map(env.ns.readerAliases),
-    }
-  }
-  memo.set(env, cloned)
-  if (env.outer) cloned.outer = cloneEnv(env.outer, memo)
-  return cloned
-}
-
-function cloneRegistry(registry: NamespaceRegistry): NamespaceRegistry {
-  const memo = new Map<Env, Env>()
-  const next = new Map<string, Env>()
-  // Pass 1: clone all envs (ns.aliases left empty)
-  for (const [name, env] of registry) next.set(name, cloneEnv(env, memo))
-  // Pass 2: wire ns.aliases to the cloned CljNamespace objects
-  for (const [name, env] of registry) {
-    const clonedEnv = next.get(name)!
-    if (env.ns && clonedEnv.ns) {
-      for (const [alias, origNs] of env.ns.aliases) {
-        const targetCloned = next.get(origNs.name)
-        if (targetCloned?.ns) clonedEnv.ns.aliases.set(alias, targetCloned.ns)
-      }
-    }
-  }
-  return next
-}
-
-// ---------------------------------------------------------------------------
-// SessionState — the minimal data a session operates on
-// ---------------------------------------------------------------------------
-
-type SessionState = {
-  registry: NamespaceRegistry
+export type SessionSnapshot = {
+  runtimeSnapshot: RuntimeSnapshot
   currentNs: string
 }
 
 // ---------------------------------------------------------------------------
-// buildSessionApi — single source of truth for all session behavior.
-// Accepts a pre-populated registry (fresh or cloned) and wires up all
-// closures + the public API. Always re-wires resolveNs and require since
-// both must close over the specific registry instance they receive.
+// buildSessionFacade — thin evaluation facade over a Runtime.
+// All namespace mechanics are delegated to the runtime.
 // ---------------------------------------------------------------------------
 
-function buildSessionApi(
-  state: SessionState,
+function buildSessionFacade(
+  runtime: Runtime,
+  initialNs: string,
   options?: SessionOptions
 ): Session {
-  const registry = state.registry
-  let currentNs = state.currentNs
-
-  const coreEnv = registry.get('clojure.core')!
-  coreEnv.resolveNs = (name: string) => registry.get(name) ?? null
-
-  // Always re-wire print/println so snapshot-derived sessions get the right
-  // emit target. Falls back to console.log when no output callback is provided.
-  const emitFn = options?.output ?? ((text: string) => console.log(text))
-  internVar(
-    'println',
-    cljNativeFunction('println', (...args: CljValue[]) => {
-      emitFn(args.map(valueToString).join(' '))
-      return cljNil()
-    }),
-    coreEnv
-  )
-  internVar(
-    'print',
-    cljNativeFunction('print', (...args: CljValue[]) => {
-      emitFn(args.map(valueToString).join(' '))
-      return cljNil()
-    }),
-    coreEnv
-  )
-
-  // Mutable source roots — seeded from options, growable via addSourceRoot.
-  const sourceRoots = new Set<string>(options?.sourceRoots ?? [])
-
-  function addSourceRoot(path: string) {
-    sourceRoots.add(path)
-  }
+  let currentNs = initialNs
 
   // One shared evaluation context for the lifetime of this session.
   const ctx = createEvaluationContext()
-
-  function resolveNamespace(nsName: string): boolean {
-    const builtInLoader = builtInNamespaceSources[nsName]
-    if (builtInLoader) {
-      loadFile(builtInLoader(), nsName)
-      return true
-    }
-    if (!options?.readFile || sourceRoots.size === 0) {
-      return false
-    }
-    for (const root of sourceRoots) {
-      const filePath = `${root.replace(/\/$/, '')}/${nsName.replace(/\./g, '/')}.clj`
-      try {
-        const source = options.readFile(filePath)
-        if (source) {
-          loadFile(source)
-          return true
-        }
-      } catch {
-        continue
-      }
-    }
-    return false
-  }
-
-  function ensureNs(name: string): Env {
-    if (!registry.has(name)) {
-      const nsEnv = makeEnv(coreEnv)
-      nsEnv.ns = makeNamespace(name)
-      registry.set(name, nsEnv)
-    }
-    return registry.get(name)!
+  ctx.resolveNs = (name: string) => runtime.getNs(name)
+  ctx.io = {
+    stdout: options?.output ?? ((text) => console.log(text)),
+    stderr: options?.stderr ?? ((text) => console.error(text)),
   }
-
-  function setNs(name: string) {
-    ensureNs(name)
+  ctx.importModule = options?.importModule
+  ctx.setCurrentNs = (name: string) => {
+    runtime.ensureNamespace(name)
     currentNs = name
+    runtime.syncNsVar(name)
   }
 
-  function getNs(name: string): CljNamespace | null {
-    return registry.get(name)?.ns ?? null
-  }
+  const session: Session = {
+    get runtime() {
+      return runtime
+    },
 
-  // Internal: returns the full Env (with lexical chain) for a namespace name.
-  function getNsEnv(name: string): Env | null {
-    return registry.get(name) ?? null
-  }
+    get registry() {
+      return runtime.registry
+    },
 
-  internVar(
-    'require',
-    cljNativeFunction('require', (...args: CljValue[]) => {
-      const currentEnv = registry.get(currentNs)!
-      for (const arg of args) {
-        processRequireSpec(arg, currentEnv, registry, resolveNamespace)
-      }
-      return cljNil()
-    }),
-    coreEnv
-  )
-
-  internVar(
-    'resolve',
-    cljNativeFunction('resolve', (sym: CljValue) => {
-      if (!isSymbol(sym)) return cljNil()
-      const slashIdx = sym.name.indexOf('/')
-      if (slashIdx > 0) {
-        const nsName = sym.name.slice(0, slashIdx)
-        const symName = sym.name.slice(slashIdx + 1)
-        const nsEnv = registry.get(nsName) ?? null
-        if (!nsEnv) return cljNil()
-        return tryLookup(symName, nsEnv) ?? cljNil()
-      }
-      const currentEnv = registry.get(currentNs)!
-      return tryLookup(sym.name, currentEnv) ?? cljNil()
-    }),
-    coreEnv
-  )
-
-  function processNsRequires(forms: CljValue[], env: Env) {
-    const requireClauses = extractRequireClauses(forms)
-    for (const specs of requireClauses) {
-      for (const spec of specs) {
-        processRequireSpec(spec, env, registry, resolveNamespace)
-      }
-    }
-  }
+    get currentNs() {
+      return currentNs
+    },
 
-  function loadFile(source: string, nsName?: string, filePath?: string): string {
-    const tokens = tokenize(source)
-    const targetNs = extractNsNameFromTokens(tokens) ?? nsName ?? 'user'
-    const aliasMap = extractAliasMapFromTokens(tokens)
-    const forms = readForms(tokens, targetNs, aliasMap)
-    const env = ensureNs(targetNs)
-    ctx.currentSource = source
-    ctx.currentFile = filePath
-    ctx.currentLineOffset = 0
-    ctx.currentColOffset = 0
-    processNsRequires(forms, env)
-    try {
-      for (const form of forms) {
-        const expanded = ctx.expandAll(form, env)
-        ctx.evaluate(expanded, env)
-      }
-    } finally {
-      ctx.currentSource = undefined
-      ctx.currentFile = undefined
-    }
-    return targetNs
-  }
+    setNs(name: string) {
+      runtime.ensureNamespace(name)
+      currentNs = name
+      runtime.syncNsVar(name)
+    },
 
-  const api: Session = {
-    registry,
-    get currentNs() {
+    getNs(name: string): CljNamespace | null {
+      return runtime.getNs(name)
+    },
+
+    loadFile(source: string, nsName?: string, filePath?: string): string {
+      return runtime.loadFile(source, nsName, filePath, ctx)
+    },
+
+    async loadFileAsync(source: string, nsName?: string, filePath?: string): Promise<string> {
+      // If there is no ns declaration in the source, pre-set the namespace from
+      // the hint so the forms evaluate in the right context.
+      if (nsName) {
+        const tokens = tokenize(source)
+        if (!extractNsNameFromTokens(tokens)) {
+          runtime.ensureNamespace(nsName)
+          currentNs = nsName
+          runtime.syncNsVar(nsName)
+        }
+      }
+      await session.evaluateAsync(source, { file: filePath })
       return currentNs
     },
-    setNs,
-    getNs,
-    loadFile,
-    addSourceRoot,
-    evaluate(source: string, opts?: { lineOffset?: number; colOffset?: number; file?: string }) {
+
+    addSourceRoot(path: string): void {
+      runtime.addSourceRoot(path)
+    },
+
+    evaluate(
+      source: string,
+      opts?: { lineOffset?: number; colOffset?: number; file?: string }
+    ): CljValue {
       ctx.currentSource = source
       ctx.currentFile = opts?.file
       ctx.currentLineOffset = opts?.lineOffset ?? 0
-      ctx.currentColOffset  = opts?.colOffset  ?? 0
+      ctx.currentColOffset = opts?.colOffset ?? 0
       try {
         const tokens = tokenize(source)
         // If source opens with an ns declaration, switch to that namespace
         // so requires resolve against the right env and currentNs is updated.
-        // This mirrors what loadFile does, making eval and load-file consistent.
         const declaredNs = extractNsNameFromTokens(tokens)
         if (declaredNs) {
-          ensureNs(declaredNs)
+          runtime.ensureNamespace(declaredNs)
           currentNs = declaredNs
+          runtime.syncNsVar(declaredNs)
         }
-        const env = getNsEnv(currentNs)!
+        const env = runtime.getNamespaceEnv(currentNs)!
         // Seed alias map from tokens (new aliases declared in this source) and
         // from ns.aliases/:as (prior require calls) and ns.readerAliases/:as-alias.
         const aliasMap = extractAliasMapFromTokens(tokens)
@@ -513,8 +190,8 @@ function buildSessionApi(
           aliasMap.set(alias, nsName)
         })
         const forms = readForms(tokens, currentNs, aliasMap)
-        processNsRequires(forms, env)
-        let result: CljValue = cljNil()
+        runtime.processNsRequires(forms, env, ctx)
+        let result: CljValue = v.nil()
         for (const form of forms) {
           const expanded = ctx.expandAll(form, env)
           result = ctx.evaluate(expanded, env)
@@ -538,7 +215,78 @@ function buildSessionApi(
         ) {
           e.message += formatErrorContext(source, e.pos, {
             lineOffset: ctx.currentLineOffset,
-            colOffset:  ctx.currentColOffset,
+            colOffset: ctx.currentColOffset,
+          })
+        }
+        throw e
+      } finally {
+        ctx.currentSource = undefined
+        ctx.currentFile = undefined
+      }
+    },
+
+    async evaluateAsync(
+      source: string,
+      opts?: { lineOffset?: number; colOffset?: number; file?: string }
+    ): Promise<CljValue> {
+      ctx.currentSource = source
+      ctx.currentFile = opts?.file
+      ctx.currentLineOffset = opts?.lineOffset ?? 0
+      ctx.currentColOffset = opts?.colOffset ?? 0
+      try {
+        const tokens = tokenize(source)
+        const declaredNs = extractNsNameFromTokens(tokens)
+        if (declaredNs) {
+          runtime.ensureNamespace(declaredNs)
+          currentNs = declaredNs
+          runtime.syncNsVar(declaredNs)
+        }
+        const env = runtime.getNamespaceEnv(currentNs)!
+        const aliasMap = extractAliasMapFromTokens(tokens)
+        env.ns?.aliases.forEach((ns, alias) => {
+          aliasMap.set(alias, ns.name)
+        })
+        env.ns?.readerAliases.forEach((nsName, alias) => {
+          aliasMap.set(alias, nsName)
+        })
+        const forms = readForms(tokens, currentNs, aliasMap)
+        await runtime.processNsRequiresAsync(forms, env, ctx)
+        let result: CljValue = v.nil()
+        for (const form of forms) {
+          const expanded = ctx.expandAll(form, env)
+          result = ctx.evaluate(expanded, env)
+        }
+        if (result.kind !== 'pending') return result
+        try {
+          return await result.promise
+        } catch (e) {
+          if (e instanceof CljThrownSignal) {
+            throw new EvaluationError(
+              `Unhandled throw: ${printString(e.value)}`,
+              { thrownValue: e.value }
+            )
+          }
+          throw e
+        }
+      } catch (e) {
+        if (e instanceof CljThrownSignal) {
+          throw new EvaluationError(
+            `Unhandled throw: ${printString(e.value)}`,
+            { thrownValue: e.value }
+          )
+        }
+        if (e instanceof RecurSignal) {
+          throw new EvaluationError('recur called outside of loop or fn', {
+            args: e.args,
+          })
+        }
+        if (
+          (e instanceof EvaluationError || e instanceof ReaderError) &&
+          e.pos
+        ) {
+          e.message += formatErrorContext(source, e.pos, {
+            lineOffset: ctx.currentLineOffset,
+            colOffset: ctx.currentColOffset,
           })
         }
         throw e
@@ -547,10 +295,19 @@ function buildSessionApi(
         ctx.currentFile = undefined
       }
     },
-    evaluateForms(forms: CljValue[]) {
+
+    applyFunction(fn: CljValue, args: CljValue[]): CljValue {
+      return ctx.applyCallable(fn, args, makeEnv())
+    },
+
+    cljToJs(value: CljValue): unknown {
+      return _cljToJs(value, { applyFunction: (fn, args) => ctx.applyCallable(fn, args, makeEnv()) })
+    },
+
+    evaluateForms(forms: CljValue[]): CljValue {
       try {
-        const env = getNsEnv(currentNs)!
-        let result: CljValue = cljNil()
+        const env = runtime.getNamespaceEnv(currentNs)!
+        let result: CljValue = v.nil()
         for (const form of forms) {
           const expanded = ctx.expandAll(form, env)
           result = ctx.evaluate(expanded, env)
@@ -571,8 +328,9 @@ function buildSessionApi(
         throw e
       }
     },
+
     getCompletions(prefix: string, nsName?: string): string[] {
-      let env: Env | null = registry.get(nsName ?? currentNs) ?? null
+      let env: Env | null = runtime.registry.get(nsName ?? currentNs) ?? null
       const seen = new Set<string>()
       while (env) {
         for (const key of env.bindings.keys()) seen.add(key)
@@ -584,7 +342,8 @@ function buildSessionApi(
       return candidates.filter((k) => k.startsWith(prefix)).sort()
     },
   }
-  return api
+
+  return session
 }
 
 // ---------------------------------------------------------------------------
@@ -592,25 +351,42 @@ function buildSessionApi(
 // ---------------------------------------------------------------------------
 
 export function createSession(options?: SessionOptions): Session {
-  const registry: NamespaceRegistry = new Map()
-
-  const coreEnv = makeEnv()
-  coreEnv.ns = makeNamespace('clojure.core')
-  loadCoreFunctions(coreEnv, options?.output)
-  registry.set('clojure.core', coreEnv)
+  const modules = options?.modules ?? []
+  const runtime = createRuntime({
+    sourceRoots: options?.sourceRoots,
+    readFile: options?.readFile,
+  })
 
-  const userEnv = makeEnv(coreEnv)
-  userEnv.ns = makeNamespace('user')
-  registry.set('user', userEnv)
-
-  const session = buildSessionApi({ registry, currentNs: 'user' }, options)
+  const session = buildSessionFacade(runtime, 'user', options)
 
+  // Bootstrap: load clojure.core source (uses session's ctx via session.loadFile)
   const coreLoader = builtInNamespaceSources['clojure.core']
   if (!coreLoader) {
     throw new Error('Missing built-in clojure.core source in registry')
   }
   session.loadFile(coreLoader(), 'clojure.core')
 
+  if (modules.length > 0) {
+    session.runtime.installModules(modules)
+  }
+
+  // Intern host bindings into the js namespace as CljJsValue vars.
+  // Guard: built-in utility names (js/get, js/set!, js/call, etc.) must not be
+  // clobbered — they are already installed by makeJsModule() above.
+  if (options?.hostBindings) {
+    const jsEnv = runtime.getNamespaceEnv('js')
+    if (jsEnv) {
+      for (const [name, rawValue] of Object.entries(options.hostBindings)) {
+        if (jsEnv.ns?.vars.has(name)) {
+          throw new Error(
+            `createSession: hostBindings key '${name}' conflicts with built-in js/${name} — choose a different key`
+          )
+        }
+        internVar(name, jsToClj(rawValue), jsEnv)
+      }
+    }
+  }
+
   for (const source of options?.entries ?? []) {
     session.loadFile(source)
   }
@@ -619,24 +395,14 @@ export function createSession(options?: SessionOptions): Session {
 }
 
 /**
- * A snapshot of a session's registry + current namespace.
+ * A snapshot of a session's runtime state + current namespace.
  * Produced by snapshotSession; consumed by createSessionFromSnapshot.
  * CljValue objects are shared (they are immutable); only the Env containers
  * are deep-copied so each derived session gets independent namespace state.
  */
-export type SessionSnapshot = {
-  registry: NamespaceRegistry
-  currentNs: string
-}
-
-/**
- * Capture a deep clone of the session's env state.
- * Typically called once after createSession() and before any user code is
- * evaluated, to produce a pristine snapshot that can be cloned cheaply per test.
- */
 export function snapshotSession(session: Session): SessionSnapshot {
   return {
-    registry: cloneRegistry(session.registry),
+    runtimeSnapshot: session.runtime.snapshot(),
     currentNs: session.currentNs,
   }
 }
@@ -645,17 +411,17 @@ export function snapshotSession(session: Session): SessionSnapshot {
  * Create a new session from a previously captured snapshot.
  * Skips the core.clj bootstrap — the cloned registry already contains the
  * fully-expanded core environment. Re-wires all registry-dependent closures
- * (resolveNs, require) to the new registry instance.
+ * (resolveNs, require, IO fns) to the new registry instance.
  */
 export function createSessionFromSnapshot(
   snapshot: SessionSnapshot,
   options?: SessionOptions
 ): Session {
-  const registry = cloneRegistry(snapshot.registry)
-  const session = buildSessionApi(
-    { registry, currentNs: snapshot.currentNs },
-    options
-  )
+  const runtime = restoreRuntime(snapshot.runtimeSnapshot, {
+    sourceRoots: options?.sourceRoots,
+    readFile: options?.readFile,
+  })
+  const session = buildSessionFacade(runtime, snapshot.currentNs, options)
   for (const source of options?.entries ?? []) {
     session.loadFile(source)
   }