@ttsc/wasm 0.13.1 → 0.14.0-dev.20250530.1

package/README.md

@@ -6,7 +6,7 @@ In-browser ttsc playground scaffolding. Compose ttsc + typescript-go with your o
 
 ## What you get
 
-- A base `ttsc.wasm` (under `dist/`) that exposes vanilla `build` / `check` / `transform` — no plugins linked. Useful as a sanity test or a no-plugin baseline.
+- A base `ttsc.wasm` (under `dist/`) that exposes vanilla `build` / `check` / `transform`, no plugins linked. Useful as a sanity test or a no-plugin baseline.
 - A Go helper package (`host/`) plugin authors import from their own `main_wasm.go` to bind a wasm to `globalThis[yourApiName]`.
 - A JS runtime (`bootTtsc`, `createMemFS`, typed `ITtscApi` surface) that loads any host-built wasm into a Web Worker.
 
@@ -39,11 +39,7 @@ func main() {
 }
 ```
 
-The native sibling `main.go` is recommended when you want `go run ./cmd/your-wasm`
-to smoke-test the same `host.Plugin` dispatchers without the browser MemFS
-bridge. See `packages/wasm/cmd/ttsc-wasm/main.go` and
-`website/compiler/cmd/playground/main.go` in the repo for reference layouts.
-A minimal custom plugin dispatcher looks like this:
+The native sibling `main.go` is recommended when you want `go run ./cmd/your-wasm` to smoke-test the same `host.Plugin` dispatchers without the browser MemFS bridge. See `packages/wasm/cmd/ttsc-wasm/main.go` and `website/compiler/cmd/playground/main.go` in the repo for reference layouts. A minimal custom plugin dispatcher looks like this:
 
 ```go
 //go:build !js
@@ -81,11 +77,7 @@ GOOS=js GOARCH=wasm go build -trimpath -ldflags "-s -w" \
 cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" public/wasm_exec.js
 ```
 
-Keep `wasm_exec.js` from the same Go toolchain that built your wasm. The
-prebuilt `dist/ttsc.wasm` and `dist/wasm_exec.js` pair already match each
-other; custom binaries should copy the loader from their own toolchain. Older
-Go installs may keep the loader under `$(go env GOROOT)/misc/wasm/wasm_exec.js`
-instead of `lib/wasm`.
+Keep `wasm_exec.js` from the same Go toolchain that built your wasm. The prebuilt `dist/ttsc.wasm` and `dist/wasm_exec.js` pair already match each other; custom binaries should copy the loader from their own toolchain. Older Go installs may keep the loader under `$(go env GOROOT)/misc/wasm/wasm_exec.js` instead of `lib/wasm`.
 
 ### Stamping version metadata at link time
 
@@ -99,7 +91,7 @@ GOOS=js GOARCH=wasm go build -trimpath \
 
 The `version`, `commit`, and `date` variables in `host/host.go` are all overridable. `globalThis[apiName].version()` reads from them.
 
-4. Boot it from JS (a Web Worker is **required** — Go's `syscall/js` blocks the runtime while the wasm is alive; running on the main thread freezes the page). Use a classic Worker or a bundler target that still exposes `importScripts`; `bootTtsc` imports `wasm_exec.js` before starting Go.
+4. Boot it from JS (a Web Worker is **required**: Go's `syscall/js` blocks the runtime while the wasm is alive; running on the main thread freezes the page). Use a classic Worker or a bundler target that still exposes `importScripts`; `bootTtsc` imports `wasm_exec.js` before starting Go.
 
 ```ts
 import { bootTtsc } from "@ttsc/wasm";
@@ -116,7 +108,60 @@ const result = await api.build({ cwd: "/work" });
 console.log(result.result); // JSON: { diagnostics, output }
 ```
 
-Booting two wasms with the same `apiName` panics; pick a unique `apiName` per binary.
+Booting two wasms with the same `apiName` overwrites the previous global binding; pick a unique `apiName` per binary. `bootTtsc` also installs shared `fs` and `process` globals in its Worker, so use separate Workers when binaries need independent filesystems.
+
+## Fountain API (snapshot, AST, type checker)
+
+For embedders that want `embed-typescript`-style raw access to the program, diagnostics, AST nodes, the type checker at a position. The same `globalThis[apiName]` object also exposes fountain verbs. They share the standard `{code, stdout, stderr, result}` envelope; `result` is JSON.
+
+```ts
+import { bootTtsc, parseResult } from "@ttsc/wasm";
+import type {
+  ITtscSnapshotResult,
+  ITtscTypeAtPositionResult,
+} from "@ttsc/wasm";
+
+const { api, host } = await bootTtsc({ wasmUrl, apiName });
+
+host.writeFile("/work/tsconfig.json", "{}");
+host.writeFile("/work/src/index.ts", "export const x: number = 1;");
+
+const snap = parseResult<ITtscSnapshotResult>(
+  await api.snapshot({ cwd: "/work" }),
+);
+const handle = snap!.handle;
+
+try {
+  const typeAt = parseResult<ITtscTypeAtPositionResult>(
+    await api.getTypeAtPosition({
+      handle,
+      path: "src/index.ts",
+      position: 18, // byte offset of `x`
+    }),
+  );
+  console.log(typeAt?.type?.text); // → "number"
+} finally {
+  await api.releaseSnapshot({ handle });
+}
+```
+
+Verbs and payload types:
+
+| Verb | Payload type |
+| --- | --- |
+| `snapshot({ cwd, tsconfig? })` | `ITtscSnapshotResult` `{ handle }` |
+| `releaseSnapshot({ handle })` | `ITtscReleaseSnapshotResult` `{ released }` |
+| `snapshots()` | `ITtscSnapshotsResult` `{ handles }` |
+| `getSourceFiles({ handle })` | `ITtscSourceFilesResult` `{ files }` |
+| `getSourceFileText({ handle, path })` | `ITtscSourceFileTextResult` `{ text }` |
+| `getDiagnostics({ handle, file? })` | `ITtscFountainDiagnosticsResult` `{ diagnostics }` |
+| `getNodeAtPosition({ handle, path, position })` | `ITtscNodeAtPositionResult` `{ node }` |
+| `getTypeAtPosition({ handle, path, position })` | `ITtscTypeAtPositionResult` `{ type }` |
+| `getSymbolAtPosition({ handle, path, position })` | `ITtscSymbolAtPositionResult` `{ symbol }` |
+
+`position` is a **byte offset** into the source text. The same coordinate TypeScript-Go uses internally. JS callers that have a UTF-16 `(line, character)` pair (e.g. From Monaco) must convert it before calling.
+
+**Lifecycle:** JS owns the handle. The wasm keeps the program (parsed AST, checker pool lease, every source file) alive until you call `releaseSnapshot`. Leaking handles leaks memory in the wasm linear heap.
 
 ## Plugin contract
 
@@ -129,7 +174,7 @@ type Plugin interface {
 }
 ```
 
-The host installs `globalThis[apiName].plugin({ name, command, ...opts })` that translates the JS options object into a CLI-shaped argv and calls your plugin's `Run`. Your `Run` body can forward to the same function the native sidecar's `main.go` calls — for example `utility.RunBuild(args)` for plugins backed by `packages/ttsc/utility`.
+The host installs `globalThis[apiName].plugin({ name, command, ...opts })` that translates the JS options object into a CLI-shaped argv and calls your plugin's `Run`. Your `Run` body can forward to the same function the native sidecar's `main.go` calls, for example `utility.RunBuild(args)` for plugins backed by `packages/ttsc/utility`.
 
 ## Published-tarball Go module layout
 
@@ -137,7 +182,7 @@ The published `@ttsc/wasm` tarball ships:
 
 - A rewritten root `go.mod` whose `replace` directives point at `./shim-vendor/shim/*` (vendored at pack time from `packages/ttsc/shim/`).
 - The full `host/`, `cmd/`, `build/` Go source so consumers can `go build -tags '...'` their own wasm against your host helper.
-- `dist/ttsc.wasm` + `dist/wasm_exec.js` — the no-plugin sanity binary and the Go runtime loader.
+- `dist/ttsc.wasm` + `dist/wasm_exec.js`: the no-plugin sanity binary and the Go runtime loader.
 
 The tarball intentionally drops the `replace github.com/samchon/ttsc/packages/ttsc => ../ttsc` directive that the in-repo `go.mod` carries: consumers of the published module who want to rebuild the wasm must supply their own `replace` (or vendor `packages/ttsc` themselves). The published `dist/ttsc.wasm` is plug-and-play for runtime use; the Go module is for **plugin authors extending the host**, not for vanilla consumers.
 

package/host/api.go

@@ -16,10 +16,11 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// APIResult is the JSON shape every plugin-dispatch endpoint returns to the
-// JS host. `code` follows the native CLI exit-code contract (0 success, 2
-// usage error, 3 runtime error). `stdout` / `stderr` are raw strings the
-// caller can render in a console panel.
+// APIResult is the stdout/stderr capture returned by runWithCapturedIO. The
+// js/wasm binding wraps it in the same JS result envelope that build/check/
+// transform use, adding `result` when an endpoint has a JSON payload. `code`
+// follows the native CLI exit-code contract (0 success, 2 compiler/config/
+// usage error, 3 runtime error).
 type APIResult struct {
   Code   int    `json:"code"`
   Stdout string `json:"stdout"`

package/host/doc.go

@@ -19,11 +19,13 @@
 //  }
 //
 // Expose binds `globalThis[name]` to an object that exposes ttsc's base
-// project commands (build, check, transform, version) plus a `plugin(name,
-// command, opts)` dispatcher that routes into a Plugin's CLI-shaped Run
-// callback. Plugins keep ttsc's existing argv-based contract — the same
-// shape the native sidecars implement — so the wasm and the native CLI can
-// share their Run* entry points byte-for-byte.
+// project commands (build, check, transform, version) plus
+// `plugin({ name, command, ...opts })`, which routes into a Plugin's
+// CLI-shaped Run callback. Every async endpoint returns the JS result envelope;
+// build/check/transform place JSON payloads in `result`, while plugin output
+// is captured in stdout/stderr. Plugins keep ttsc's existing argv-based
+// contract — the same shape the native sidecars implement — so the wasm and
+// the native CLI can share their Run* entry points byte-for-byte.
 //
 // The package is browser-agnostic: every JS-facing helper sits behind
 // //go:build js, so a consumer can `go build ./...` natively without GOOS=js

package/host/fountain.go

@@ -0,0 +1,505 @@
+//go:build js && wasm
+
+// Fountain-style JS endpoints for the host package.
+//
+// These verbs let JS callers hold a TypeScript-Go Program in memory across
+// multiple queries — diagnostics, AST lookup, type-checker queries — without
+// re-loading and re-checking the project on every call. The shape mirrors the
+// `embed-typescript` `fountain()` escape hatch over the legacy TS API, adapted
+// to ttsc's TypeScript-Go driver.
+//
+// Lifecycle: JS owns the handle. `snapshot` returns an opaque string handle;
+// callers MUST call `releaseSnapshot` to free the Program's checker pool lease
+// and let Go GC reclaim the AST. Unreleased handles leak memory in the wasm
+// linear heap.
+//
+// Result envelope: every verb returns the standard `{code, stdout, stderr,
+// result}` shape used by build/check/transform. The structured payload is
+// JSON-encoded into `result`; JS callers parse it with the same `parseResult`
+// helper they use for the base endpoints.
+package host
+
+import (
+  "encoding/json"
+  "fmt"
+  "path/filepath"
+  "sync"
+  "sync/atomic"
+  "syscall/js"
+
+  "github.com/microsoft/typescript-go/shim/ast"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// snapshotEntry pairs a Program with the cwd it was loaded against so we can
+// rewrite file paths to project-relative keys uniformly across all queries.
+//
+// `mu` serializes Checker-touching paths. driver.LoadProgram pins one
+// Checker via forceSingleChecker, and TypeScript-Go's Checker is not
+// documented thread-safe. On js/wasm cooperative scheduling normally
+// prevents two goroutines from running concurrently, but any Go→JS bridge
+// call (file read, Promise await) can yield mid-operation; without `mu`
+// two fountain verbs invoked in the same frame could land their Checker
+// reads on opposite sides of an internal mutation and corrupt state.
+type snapshotEntry struct {
+  mu   sync.Mutex
+  prog *driver.Program
+  cwd  string
+}
+
+var (
+  snapshotsMu sync.RWMutex
+  snapshots   = map[string]*snapshotEntry{}
+  nextHandle  atomic.Uint64
+)
+
+// fountainAPIMap returns the verb → js.Func map appended to globalThis[apiName]
+// during Expose. Kept in a helper so host.go's API map stays scannable.
+func fountainAPIMap() map[string]any {
+  return map[string]any{
+    "snapshot":            js.FuncOf(jsSnapshot),
+    "releaseSnapshot":     js.FuncOf(jsReleaseSnapshot),
+    "snapshots":           js.FuncOf(jsListSnapshots),
+    "getSourceFiles":      js.FuncOf(jsGetSourceFiles),
+    "getSourceFileText":   js.FuncOf(jsGetSourceFileText),
+    "getDiagnostics":      js.FuncOf(jsGetDiagnostics),
+    "getNodeAtPosition":   js.FuncOf(jsGetNodeAtPosition),
+    "getTypeAtPosition":   js.FuncOf(jsGetTypeAtPosition),
+    "getSymbolAtPosition": js.FuncOf(jsGetSymbolAtPosition),
+  }
+}
+
+// SnapshotResult is the response shape for `snapshot()`.
+type SnapshotResult struct {
+  Handle string `json:"handle"`
+}
+
+// ReleaseSnapshotResult is the response shape for `releaseSnapshot()`.
+type ReleaseSnapshotResult struct {
+  Released bool `json:"released"`
+}
+
+// ListSnapshotsResult is the response shape for `snapshots()`.
+type ListSnapshotsResult struct {
+  Handles []string `json:"handles"`
+}
+
+// GetSourceFilesResult is the response shape for `getSourceFiles()`.
+type GetSourceFilesResult struct {
+  Files []string `json:"files"`
+}
+
+// GetSourceFileTextResult is the response shape for `getSourceFileText()`.
+type GetSourceFileTextResult struct {
+  Text string `json:"text"`
+}
+
+// GetDiagnosticsResult is the response shape for `getDiagnostics()`.
+type GetDiagnosticsResult struct {
+  Diagnostics []CompileDiagnostic `json:"diagnostics"`
+}
+
+// NodeInfo is the serialized AST node returned by `getNodeAtPosition`.
+type NodeInfo struct {
+  Kind     int    `json:"kind"`
+  KindName string `json:"kindName"`
+  Pos      int    `json:"pos"`
+  End      int    `json:"end"`
+  Text     string `json:"text,omitempty"`
+}
+
+// GetNodeAtPositionResult is the response shape for `getNodeAtPosition()`.
+type GetNodeAtPositionResult struct {
+  Node *NodeInfo `json:"node"`
+}
+
+// TypeInfo is the serialized type returned by `getTypeAtPosition`.
+type TypeInfo struct {
+  Text  string `json:"text"`
+  Flags int    `json:"flags"`
+}
+
+// GetTypeAtPositionResult is the response shape for `getTypeAtPosition()`.
+type GetTypeAtPositionResult struct {
+  Type *TypeInfo `json:"type"`
+}
+
+// SymbolDeclaration is the serialized declaration site returned by
+// `getSymbolAtPosition`.
+type SymbolDeclaration struct {
+  File *string `json:"file"`
+  Pos  int     `json:"pos"`
+  End  int     `json:"end"`
+}
+
+// SymbolInfo is the serialized symbol returned by `getSymbolAtPosition`.
+type SymbolInfo struct {
+  Name             string              `json:"name"`
+  Text             string              `json:"text,omitempty"`
+  Flags            int                 `json:"flags"`
+  Declarations     []SymbolDeclaration `json:"declarations,omitempty"`
+  DeclarationCount int                 `json:"declarationCount,omitempty"`
+}
+
+// GetSymbolAtPositionResult is the response shape for `getSymbolAtPosition()`.
+type GetSymbolAtPositionResult struct {
+  Symbol *SymbolInfo `json:"symbol"`
+}
+
+// jsSnapshot({cwd, tsconfig?}) → Promise<ITtscResult>.
+//
+// Loads the project once and retains the Program for follow-up queries. The
+// returned handle is opaque; treat it as a string.
+func jsSnapshot(this js.Value, args []js.Value) any {
+  opts := optionsArg(args)
+  return makePromise(func() any {
+    cwd := stringProp(opts, "cwd")
+    tsconfig := stringProp(opts, "tsconfig")
+    if cwd == "" {
+      return errorResponse(2, "host.snapshot: \"cwd\" is required")
+    }
+    if tsconfig == "" {
+      tsconfig = "tsconfig.json"
+    }
+    prog, diags, err := driver.LoadProgram(cwd, tsconfig, driver.LoadProgramOptions{
+      ForceNoEmit: true,
+    })
+    if err != nil {
+      return errorResponse(2, err.Error())
+    }
+    if prog == nil {
+      msg := "host.snapshot: project load failed"
+      if len(diags) > 0 {
+        msg = diags[0].Message
+      }
+      return errorResponse(2, msg)
+    }
+    handle := fmt.Sprintf("snap-%d", nextHandle.Add(1))
+    snapshotsMu.Lock()
+    snapshots[handle] = &snapshotEntry{prog: prog, cwd: cwd}
+    snapshotsMu.Unlock()
+    return fountainOK(SnapshotResult{Handle: handle})
+  })
+}
+
+// jsReleaseSnapshot({handle}) → Promise<ITtscResult>.
+//
+// `released=false` indicates the handle was not present (already released or
+// never created). The endpoint never errors on unknown handles so callers can
+// release idempotently.
+//
+// Holds the write lock for the full delete+Close so any in-flight read
+// (withSnapshot's RLock) finishes before the Program is closed. This is the
+// pair of the TOCTOU guarantee documented on withSnapshot.
+func jsReleaseSnapshot(this js.Value, args []js.Value) any {
+  opts := optionsArg(args)
+  return makePromise(func() any {
+    handle := stringProp(opts, "handle")
+    if handle == "" {
+      return errorResponse(2, "host.releaseSnapshot: \"handle\" is required")
+    }
+    snapshotsMu.Lock()
+    defer snapshotsMu.Unlock()
+    entry, ok := snapshots[handle]
+    if !ok {
+      return fountainOK(ReleaseSnapshotResult{Released: false})
+    }
+    delete(snapshots, handle)
+    if entry.prog != nil {
+      // Recover from any panic inside Close so the rest of the wasm
+      // instance survives; the entry has already been removed from
+      // the table so the handle is effectively released either way.
+      func() {
+        defer func() { _ = recover() }()
+        _ = entry.prog.Close()
+      }()
+    }
+    return fountainOK(ReleaseSnapshotResult{Released: true})
+  })
+}
+
+// jsListSnapshots() → Promise<ITtscResult>. Debug aid — lets a JS embedder
+// verify it has released what it thinks it has.
+func jsListSnapshots(this js.Value, args []js.Value) any {
+  return makePromise(func() any {
+    snapshotsMu.RLock()
+    handles := make([]string, 0, len(snapshots))
+    for h := range snapshots {
+      handles = append(handles, h)
+    }
+    snapshotsMu.RUnlock()
+    return fountainOK(ListSnapshotsResult{Handles: handles})
+  })
+}
+
+// jsGetSourceFiles({handle}) → Promise<ITtscResult>. Lists the non-
+// declaration source files in the program, keyed by project-relative path
+// (same convention as build/transform output).
+func jsGetSourceFiles(this js.Value, args []js.Value) any {
+  return withSnapshot(args, func(entry *snapshotEntry, _ js.Value) any {
+    files := entry.prog.SourceFiles()
+    out := make([]string, 0, len(files))
+    for _, f := range files {
+      out = append(out, snapshotFileKey(entry.cwd, f.FileName()))
+    }
+    return fountainOK(GetSourceFilesResult{Files: out})
+  })
+}
+
+// jsGetSourceFileText({handle, path}) → Promise<ITtscResult>. Returns the
+// current source text the Program is holding for the file. After transform
+// plugins have run, this reflects the post-transform text.
+func jsGetSourceFileText(this js.Value, args []js.Value) any {
+  return withSnapshot(args, func(entry *snapshotEntry, opts js.Value) any {
+    path := stringProp(opts, "path")
+    if path == "" {
+      return errorResponse(2, "host.getSourceFileText: \"path\" is required")
+    }
+    file := resolveSnapshotFile(entry, path)
+    if file == nil {
+      return errorResponse(2, fmt.Sprintf("host.getSourceFileText: file not found: %q", path))
+    }
+    return fountainOK(GetSourceFileTextResult{Text: file.Text()})
+  })
+}
+
+// jsGetDiagnostics({handle, file?}) → Promise<ITtscResult>. Returns the same
+// diagnostic shape as build/check/transform. When `file` is set, results are
+// filtered to that project-relative path.
+func jsGetDiagnostics(this js.Value, args []js.Value) any {
+  return withSnapshot(args, func(entry *snapshotEntry, opts js.Value) any {
+    filter := stringProp(opts, "file")
+    diags := entry.prog.Diagnostics()
+    out := make([]CompileDiagnostic, 0, len(diags))
+    for _, d := range diags {
+      api := toAPIDiagnostic(d)
+      if filter != "" {
+        if api.File == nil {
+          continue
+        }
+        rel := snapshotFileKey(entry.cwd, *api.File)
+        if rel != filter && *api.File != filter {
+          continue
+        }
+      }
+      out = append(out, api)
+    }
+    return fountainOK(GetDiagnosticsResult{Diagnostics: out})
+  })
+}
+
+// jsGetNodeAtPosition({handle, path, position}) → Promise<ITtscResult>.
+// `position` is a byte offset into the source text (the same coordinate the
+// AST uses internally). JS callers that have a UTF-16 line/character pair
+// should resolve it to a byte offset before calling (the @ttsc/playground
+// helper does this).
+func jsGetNodeAtPosition(this js.Value, args []js.Value) any {
+  return withSnapshotPosition(args, func(_ *snapshotEntry, file *ast.SourceFile, pos int) any {
+    node := ast.GetNodeAtPosition(file, pos, false)
+    return fountainOK(GetNodeAtPositionResult{Node: nodeInfoOf(node)})
+  })
+}
+
+// jsGetTypeAtPosition({handle, path, position}) → Promise<ITtscResult>.
+// Resolves the node at position via GetNodeAtPosition and asks the Program's
+// pinned single checker for its type. Returns `{type: null}` when there is no
+// node at that position or no checker is available.
+func jsGetTypeAtPosition(this js.Value, args []js.Value) any {
+  return withSnapshotPosition(args, func(entry *snapshotEntry, file *ast.SourceFile, pos int) any {
+    node := ast.GetNodeAtPosition(file, pos, false)
+    if node == nil || entry.prog.Checker == nil {
+      return fountainOK(GetTypeAtPositionResult{Type: nil})
+    }
+    t := entry.prog.Checker.GetTypeAtLocation(node)
+    if t == nil {
+      return fountainOK(GetTypeAtPositionResult{Type: nil})
+    }
+    return fountainOK(GetTypeAtPositionResult{
+      Type: &TypeInfo{
+        Text:  entry.prog.Checker.TypeToString(t),
+        Flags: int(t.Flags()),
+      },
+    })
+  })
+}
+
+// jsGetSymbolAtPosition({handle, path, position}) → Promise<ITtscResult>.
+// Returns `{symbol: null}` when the node at position has no associated
+// symbol (e.g. punctuation, whitespace).
+func jsGetSymbolAtPosition(this js.Value, args []js.Value) any {
+  return withSnapshotPosition(args, func(entry *snapshotEntry, file *ast.SourceFile, pos int) any {
+    node := ast.GetNodeAtPosition(file, pos, false)
+    if node == nil || entry.prog.Checker == nil {
+      return fountainOK(GetSymbolAtPositionResult{Symbol: nil})
+    }
+    sym := entry.prog.Checker.GetSymbolAtLocation(node)
+    if sym == nil {
+      return fountainOK(GetSymbolAtPositionResult{Symbol: nil})
+    }
+    return fountainOK(GetSymbolAtPositionResult{Symbol: symbolInfoOf(entry, sym)})
+  })
+}
+
+// withSnapshot is the shared envelope for every read-only fountain verb. It
+// parses the JS arg, resolves the handle, holds the snapshot table's read
+// lock + the per-entry mutex, and runs `fn`. Two layered locks:
+//
+//   - snapshotsMu (RLock): pairs with jsReleaseSnapshot's write lock so
+//     the entry's prog isn't Close()d under the caller. Closes the prior
+//     TOCTOU between "found the entry" and "used entry.prog".
+//   - entry.mu: serializes Checker-touching paths. TS-Go's Checker is
+//     single-instance (forceSingleChecker) and not documented
+//     thread-safe; two fountain verbs invoked in the same frame could
+//     otherwise interleave Checker state mutations.
+func withSnapshot(args []js.Value, fn func(*snapshotEntry, js.Value) any) any {
+  opts := optionsArg(args)
+  return makePromise(func() any {
+    handle := stringProp(opts, "handle")
+    if handle == "" {
+      return errorResponse(2, "host: \"handle\" is required")
+    }
+    snapshotsMu.RLock()
+    defer snapshotsMu.RUnlock()
+    entry := snapshots[handle]
+    if entry == nil {
+      return errorResponse(2, fmt.Sprintf("host: snapshot %q not found (already released or never created)", handle))
+    }
+    entry.mu.Lock()
+    defer entry.mu.Unlock()
+    return fn(entry, opts)
+  })
+}
+
+// withSnapshotPosition is the shared envelope for the 3 position-bound
+// fountain verbs. Same read-lock lifecycle as withSnapshot, plus parses
+// {path, position} and bounds-checks position against the file length so an
+// out-of-range offset reaches `ast.GetNodeAtPosition` only as a clean
+// error response instead of an internal panic.
+func withSnapshotPosition(args []js.Value, fn func(*snapshotEntry, *ast.SourceFile, int) any) any {
+  return withSnapshot(args, func(entry *snapshotEntry, opts js.Value) any {
+    path := stringProp(opts, "path")
+    if path == "" {
+      return errorResponse(2, "host: \"path\" is required")
+    }
+    posVal := opts.Get("position")
+    if posVal.Type() != js.TypeNumber {
+      return errorResponse(2, "host: \"position\" must be a number (byte offset)")
+    }
+    pos := posVal.Int()
+    if pos < 0 {
+      return errorResponse(2, "host: \"position\" must be non-negative")
+    }
+    file := resolveSnapshotFile(entry, path)
+    if file == nil {
+      return errorResponse(2, fmt.Sprintf("host: file %q not found in snapshot", path))
+    }
+    if pos > len(file.Text()) {
+      return errorResponse(2, fmt.Sprintf("host: \"position\" %d exceeds file length %d", pos, len(file.Text())))
+    }
+    return fn(entry, file, pos)
+  })
+}
+
+// resolveSnapshotFile finds a SourceFile by path, accepting either an
+// absolute path or a path relative to the snapshot's cwd.
+func resolveSnapshotFile(entry *snapshotEntry, path string) *ast.SourceFile {
+  if file := entry.prog.SourceFile(path); file != nil {
+    return file
+  }
+  if !filepath.IsAbs(path) {
+    abs := filepath.Join(entry.cwd, path)
+    if file := entry.prog.SourceFile(abs); file != nil {
+      return file
+    }
+  }
+  return nil
+}
+
+// snapshotFileKey mirrors apiOutputKey but is exported for use by all
+// fountain endpoints that return file paths.
+func snapshotFileKey(cwd, fileName string) string {
+  return apiOutputKey(cwd, fileName)
+}
+
+// fountainOK wraps a JSON-able payload in the standard `{code, stdout,
+// stderr, result}` envelope. The payload is JSON-encoded into `result`; JS
+// callers `parseResult<T>` it the same way they do for build/check/transform.
+func fountainOK(payload any) any {
+  data, err := json.Marshal(payload)
+  if err != nil {
+    return errorResponse(3, fmt.Sprintf("host: fountain result marshal failed: %v", err))
+  }
+  return js.ValueOf(map[string]any{
+    "code":   0,
+    "stdout": "",
+    "stderr": "",
+    "result": string(data),
+  })
+}
+
+// nodeInfoOf converts a *ast.Node into the JSON-serializable NodeInfo.
+func nodeInfoOf(node *ast.Node) *NodeInfo {
+  if node == nil {
+    return nil
+  }
+  info := &NodeInfo{
+    Kind:     int(node.Kind),
+    KindName: astKindName(node.Kind),
+    Pos:      node.Pos(),
+    End:      node.End(),
+  }
+  if text := shimscanner.GetTextOfNode(node); text != "" {
+    info.Text = text
+  }
+  return info
+}
+
+// symbolInfoOf converts a *ast.Symbol into the JSON-serializable SymbolInfo,
+// including up to a few declaration sites so callers can implement "go to
+// definition" without follow-up snapshot queries.
+func symbolInfoOf(entry *snapshotEntry, sym *ast.Symbol) *SymbolInfo {
+  if sym == nil {
+    return nil
+  }
+  info := &SymbolInfo{
+    Name:  sym.Name,
+    Flags: int(sym.Flags),
+  }
+  if entry.prog.Checker != nil {
+    info.Text = entry.prog.Checker.SymbolToString(sym)
+  }
+  decls := sym.Declarations
+  if len(decls) > 0 {
+    // Cap at 16 to keep merged-namespace symbols (e.g. global lib types)
+    // from ballooning the response.
+    const maxDecls = 16
+    n := len(decls)
+    capped := n
+    if n > maxDecls {
+      capped = maxDecls
+    }
+    out := make([]SymbolDeclaration, 0, capped)
+    for _, d := range decls[:capped] {
+      if d == nil {
+        continue
+      }
+      item := SymbolDeclaration{Pos: d.Pos(), End: d.End()}
+      if file := ast.GetSourceFileOfNode(d); file != nil {
+        key := snapshotFileKey(entry.cwd, file.FileName())
+        item.File = &key
+      }
+      out = append(out, item)
+    }
+    info.Declarations = out
+    info.DeclarationCount = n
+  }
+  return info
+}
+
+// astKindName renders an ast.Kind to its string representation. ast.Kind has
+// a Stringer impl in tsgo (`%v` produces "FunctionDeclaration" etc.).
+func astKindName(k ast.Kind) string {
+  return fmt.Sprintf("%v", k)
+}