@ttsc/wasm 0.12.3 → 0.12.4

package/shim-vendor/shim/ast/shim.go

@@ -177,44 +177,68 @@ const (
   ModifierFlagsReadonly  = innerast.ModifierFlagsReadonly
 )
 
+// NewNodeFactory creates an AST node factory with the supplied creation hooks.
+// Pass a zero-value NodeFactoryHooks to get the default factory behaviour.
 func NewNodeFactory(options NodeFactoryHooks) *NodeFactory {
   return innerast.NewNodeFactory(options)
 }
 
+// NewNodeVisitor creates a visitor that calls visit for each node encountered
+// during a tree walk, delegating node recreation to factory using hooks.
 func NewNodeVisitor(visit func(node *Node) *Node, factory *NodeFactory, options NodeVisitorHooks) *NodeVisitor {
   return innerast.NewNodeVisitor(visit, factory, options)
 }
 
+// IsFunctionLike reports whether node is any function-like construct
+// (function declaration, arrow function, method, constructor, accessor, etc.).
 func IsFunctionLike(node *Node) bool {
   return innerast.IsFunctionLike(node)
 }
 
+// IsPropertyAssignment reports whether node is a key:value pair inside an
+// object literal expression.
 func IsPropertyAssignment(node *Node) bool {
   return innerast.IsPropertyAssignment(node)
 }
 
+// IsPropertyDeclaration reports whether node is a class property declaration.
 func IsPropertyDeclaration(node *Node) bool {
   return innerast.IsPropertyDeclaration(node)
 }
 
+// IsModuleBlock reports whether node is the body block of a namespace or
+// module declaration.
 func IsModuleBlock(node *Node) bool {
   return innerast.IsModuleBlock(node)
 }
 
+// IsStringLiteral reports whether node is a string literal token.
 func IsStringLiteral(node *Node) bool {
   return innerast.IsStringLiteral(node)
 }
 
+// IsPropertyAccessExpression reports whether node is a dotted member access
+// (e.g. `a.b`).
 func IsPropertyAccessExpression(node *Node) bool {
   return innerast.IsPropertyAccessExpression(node)
 }
 
+// IsElementAccessExpression reports whether node is a bracket member access
+// (e.g. `a[b]`).
 func IsElementAccessExpression(node *Node) bool {
   return innerast.IsElementAccessExpression(node)
 }
 
+// GetSourceFileOfNode walks up the parent chain to return the SourceFile that
+// owns the given node. Linked from the internal package via go:linkname because
+// the function is unexported there.
+//
 //go:linkname GetSourceFileOfNode github.com/microsoft/typescript-go/internal/ast.GetSourceFileOfNode
 func GetSourceFileOfNode(node *innerast.Node) *innerast.SourceFile
 
+// GetNodeAtPosition returns the deepest AST node whose range covers position
+// in file. When includeJSDoc is true the search descends into JSDoc sub-trees.
+// Linked from the internal package via go:linkname.
+//
 //go:linkname GetNodeAtPosition github.com/microsoft/typescript-go/internal/ast.GetNodeAtPosition
 func GetNodeAtPosition(file *innerast.SourceFile, position int, includeJSDoc bool) *innerast.Node

package/shim-vendor/shim/checker/shim.go

@@ -59,34 +59,50 @@ const (
   ElementFlagsVariadic = innerchecker.ElementFlagsVariadic
 )
 
+// IsTupleType reports whether t is a fixed-length tuple type.
 func IsTupleType(t *innerchecker.Type) bool {
   return innerchecker.IsTupleType(t)
 }
 
+// Checker_getIndexInfosOfType returns the index signatures (string/number/symbol
+// index infos) declared on t.
 func Checker_getIndexInfosOfType(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.IndexInfo {
   return recv.GetIndexInfosOfType(t)
 }
 
+// Checker_getPropertiesOfType returns the named property symbols of t. For
+// union and intersection types this is the set of properties visible on every
+// member.
 func Checker_getPropertiesOfType(recv *innerchecker.Checker, t *innerchecker.Type) []*innerast.Symbol {
   return recv.GetPropertiesOfType(t)
 }
 
+// Checker_getApparentProperties returns the properties visible on t after
+// resolving primitive wrapper types (e.g. string → String).
 func Checker_getApparentProperties(recv *innerchecker.Checker, t *innerchecker.Type) []*innerast.Symbol {
   return recv.GetApparentProperties(t)
 }
 
+// Checker_getTypeArguments returns the type arguments of a generic reference
+// type, or nil when t is not a reference.
 func Checker_getTypeArguments(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.Type {
   return recv.GetTypeArguments(t)
 }
 
+// Checker_getTypeOfSymbol returns the declared type of symbol, resolving
+// aliases and following late-bound types.
 func Checker_getTypeOfSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerchecker.Type {
   return recv.GetTypeOfSymbol(symbol)
 }
 
+// Checker_getTypeOfSymbolAtLocation returns the contextual type of symbol as
+// observed at the given AST node (useful for narrowed types in control flow).
 func Checker_getTypeOfSymbolAtLocation(recv *innerchecker.Checker, symbol *innerast.Symbol, node *innerast.Node) *innerchecker.Type {
   return recv.GetTypeOfSymbolAtLocation(symbol, node)
 }
 
+// Checker_getTypeOfPropertyOfType looks up the type of the named property on t
+// and returns nil when no such property exists.
 func Checker_getTypeOfPropertyOfType(recv *innerchecker.Checker, t *innerchecker.Type, name string) *innerchecker.Type {
   return recv.GetTypeOfPropertyOfType(t, name)
 }
@@ -94,6 +110,8 @@ func Checker_getTypeOfPropertyOfType(recv *innerchecker.Checker, t *innerchecker
 //go:linkname checkerGetAliasSymbolForTypeNode github.com/microsoft/typescript-go/internal/checker.(*Checker).getAliasSymbolForTypeNode
 func checkerGetAliasSymbolForTypeNode(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol
 
+// Checker_getAliasSymbolForTypeNode returns the alias symbol that a type node
+// refers to when the node is itself a type alias reference (e.g. `type Foo = ...`).
 func Checker_getAliasSymbolForTypeNode(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol {
   return checkerGetAliasSymbolForTypeNode(recv, node)
 }
@@ -101,6 +119,8 @@ func Checker_getAliasSymbolForTypeNode(recv *innerchecker.Checker, node *inneras
 //go:linkname checkerGetDeclarationOfAliasSymbol github.com/microsoft/typescript-go/internal/checker.(*Checker).getDeclarationOfAliasSymbol
 func checkerGetDeclarationOfAliasSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Node
 
+// Checker_getDeclarationOfAliasSymbol resolves an import/export alias symbol to
+// its original declaration node.
 func Checker_getDeclarationOfAliasSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Node {
   return checkerGetDeclarationOfAliasSymbol(recv, symbol)
 }
@@ -108,6 +128,8 @@ func Checker_getDeclarationOfAliasSymbol(recv *innerchecker.Checker, symbol *inn
 //go:linkname checkerGetTargetOfImportSpecifier github.com/microsoft/typescript-go/internal/checker.(*Checker).getTargetOfImportSpecifier
 func checkerGetTargetOfImportSpecifier(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol
 
+// Checker_getTargetOfImportSpecifier resolves an import specifier node to the
+// exported symbol it binds. Returns nil if recv or node is nil.
 func Checker_getTargetOfImportSpecifier(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol {
   if recv == nil || node == nil {
     return nil
@@ -115,6 +137,8 @@ func Checker_getTargetOfImportSpecifier(recv *innerchecker.Checker, node *innera
   return checkerGetTargetOfImportSpecifier(recv, node)
 }
 
+// Checker_getAliasedSymbol follows an alias chain to its final target symbol.
+// Returns nil if recv or symbol is nil.
 func Checker_getAliasedSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Symbol {
   if recv == nil || symbol == nil {
     return nil
@@ -132,6 +156,11 @@ func checkerResolveEntityName(
   location *innerast.Node,
 ) *innerast.Symbol
 
+// Checker_resolveEntityName resolves a dotted entity name (identifier or
+// qualified name) to the symbol it denotes, filtered by meaning flags.
+// When ignoreErrors is true, resolution failures are silent. When
+// dontResolveAlias is true, the returned symbol may still be an alias.
+// Returns nil if recv or name is nil.
 func Checker_resolveEntityName(
   recv *innerchecker.Checker,
   name *innerast.Node,
@@ -149,6 +178,9 @@ func Checker_resolveEntityName(
 //go:linkname checkerGetTypeNameSymbol github.com/microsoft/typescript-go/internal/checker.getTypeNameSymbol
 func checkerGetTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol
 
+// Type_getTypeNameSymbol returns the symbol attached to t's type name field,
+// or nil when t has no name symbol or t is nil. Linked via go:linkname because
+// getTypeNameSymbol is a package-level unexported function in the checker.
 func Type_getTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol {
   if t == nil {
     return nil
@@ -159,6 +191,7 @@ func Type_getTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol {
 //go:linkname checkerIsArrayType github.com/microsoft/typescript-go/internal/checker.(*Checker).isArrayType
 func checkerIsArrayType(recv *innerchecker.Checker, t *innerchecker.Type) bool
 
+// Checker_isArrayType reports whether t is the built-in Array<T> reference type.
 func Checker_isArrayType(recv *innerchecker.Checker, t *innerchecker.Type) bool {
   return checkerIsArrayType(recv, t)
 }
@@ -166,6 +199,8 @@ func Checker_isArrayType(recv *innerchecker.Checker, t *innerchecker.Type) bool
 //go:linkname checkerGetBaseTypes github.com/microsoft/typescript-go/internal/checker.(*Checker).getBaseTypes
 func checkerGetBaseTypes(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.Type
 
+// Checker_getBaseTypes returns the list of base types (from `extends` clauses)
+// for a class or interface type. Returns nil if recv or t is nil.
 func Checker_getBaseTypes(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.Type {
   if recv == nil || t == nil {
     return nil

package/shim-vendor/shim/core/shim.go

@@ -1,17 +1,34 @@
+// Package core re-exports the subset of typescript-go's internal/core types
+// and constants that plugins and the ttsc driver need. It provides compiler
+// options, script-kind discrimination, tri-state booleans, and text-range
+// primitives without exposing the full internal surface.
 package core
 
 import innercore "github.com/microsoft/typescript-go/internal/core"
 
+// CompilerOptions holds the parsed tsconfig compiler options passed to the
+// TypeScript-Go program host.
 type CompilerOptions = innercore.CompilerOptions
+
+// Tristate is a three-valued boolean: TSFalse, TSTrue, or TSUnknown. Used by
+// CompilerOptions fields that can be explicitly unset.
 type Tristate = innercore.Tristate
+
+// TextPos is a zero-based byte offset into a source file's text.
 type TextPos = innercore.TextPos
+
+// TextRange is a half-open [Pos, End) byte range inside a source file.
 type TextRange = innercore.TextRange
+
+// ScriptKind identifies the syntactic flavour of a source file.
 type ScriptKind = innercore.ScriptKind
 
 const (
+  // TSFalse and TSTrue are the explicit-false and explicit-true Tristate values.
   TSFalse = innercore.TSFalse
   TSTrue  = innercore.TSTrue
 
+  // ScriptKind* constants enumerate the file flavours typescript-go recognises.
   ScriptKindUnknown  = innercore.ScriptKindUnknown
   ScriptKindJS       = innercore.ScriptKindJS
   ScriptKindJSX      = innercore.ScriptKindJSX

package/shim-vendor/shim/diagnosticwriter/shim.go

@@ -1,3 +1,7 @@
+// Package diagnosticwriter re-exports the subset of typescript-go's
+// internal/diagnosticwriter surface that the ttsc driver uses. It provides
+// FormatASTDiagnosticsWithColorAndContext for rendering pure tsgo diagnostics
+// and delegates the mixed lint+tsgo rendering path to the adjacent lint.go.
 package diagnosticwriter
 
 import (

package/shim-vendor/shim/lsp/shim.go

@@ -8,10 +8,10 @@
 package lsp
 
 import (
-	"io"
-	_ "unsafe"
+  "io"
+  _ "unsafe"
 
-	innerlsp "github.com/microsoft/typescript-go/internal/lsp"
+  innerlsp "github.com/microsoft/typescript-go/internal/lsp"
 )
 
 // Server is the opaque LSP server type from tsgo.

package/shim-vendor/shim/printer/shim.go

@@ -1,3 +1,7 @@
+// Package printer re-exports the typescript-go internal/printer types and
+// wraps the three functions that the ttsc driver and transform plugins need
+// to emit source text from an AST. The surface is intentionally narrow: only
+// the construction and single-file emit path are exposed.
 package printer
 
 import (
@@ -5,19 +9,35 @@ import (
   innerprinter "github.com/microsoft/typescript-go/internal/printer"
 )
 
+// PrintHandlers provides optional hooks (e.g. substituteNode) called during
+// AST emission.
 type PrintHandlers = innerprinter.PrintHandlers
+
+// Printer holds the stateful emitter produced by NewPrinter.
 type Printer = innerprinter.Printer
+
+// PrinterOptions configures newline style, source-map generation, and other
+// emission knobs.
 type PrinterOptions = innerprinter.PrinterOptions
+
+// EmitContext accumulates per-emit metadata (source maps, comment positions)
+// and must be created fresh for each emit round via NewEmitContext.
 type EmitContext = innerprinter.EmitContext
 
+// NewPrinter creates an emitter with the supplied options, substitution hooks,
+// and emit context. Callers must pass the same EmitContext to all operations
+// in a single emit round.
 func NewPrinter(options PrinterOptions, handlers PrintHandlers, emitContext *EmitContext) *Printer {
   return innerprinter.NewPrinter(options, handlers, emitContext)
 }
 
+// NewEmitContext allocates a fresh EmitContext for a new emit round.
 func NewEmitContext() *EmitContext {
   return innerprinter.NewEmitContext()
 }
 
+// EmitSourceFile renders the full source file through the printer and returns
+// the emitted text.
 func EmitSourceFile(p *Printer, sourceFile *ast.SourceFile) string {
   return p.EmitSourceFile(sourceFile)
 }

package/src/MemFS.ts

@@ -20,6 +20,15 @@ const S_IFREG = 0o100000;
 const DEFAULT_FILE_MODE = S_IFREG | 0o644;
 const DEFAULT_DIR_MODE = S_IFDIR | 0o755;
 
+/**
+ * Subset of the Node.js `fs` module that `wasm_exec.js` calls into.
+ *
+ * Go's js/wasm runtime routes all `syscall/js` filesystem operations through
+ * `globalThis.fs`. In a browser there is no real `fs`, so a MemFS
+ * implementation fulfils this interface. Only the operations that
+ * typescript-go's compiler exercises are required; the rest are no-ops or
+ * return `EPERM`/`EINVAL`.
+ */
 export interface IWasmExecFS {
   constants: Record<string, number>;
   writeSync(fd: number, buf: Uint8Array): number;
@@ -37,7 +46,10 @@ export interface IWasmExecFS {
     mode: number,
     callback: (err: NodeJS.ErrnoException | null, fd: number) => void,
   ): void;
-  close(fd: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+  close(
+    fd: number,
+    callback: (err: NodeJS.ErrnoException | null) => void,
+  ): void;
   read(
     fd: number,
     buffer: Uint8Array,
@@ -67,7 +79,10 @@ export interface IWasmExecFS {
     fd: number,
     callback: (err: NodeJS.ErrnoException | null, stats: IFileStats) => void,
   ): void;
-  fsync(fd: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+  fsync(
+    fd: number,
+    callback: (err: NodeJS.ErrnoException | null) => void,
+  ): void;
   unlink(
     path: string,
     callback: (err: NodeJS.ErrnoException | null) => void,
@@ -152,6 +167,12 @@ export interface IWasmExecFS {
   ): void;
 }
 
+/**
+ * Stat-like object returned by `stat`, `lstat`, and `fstat`.
+ *
+ * Mirrors the subset of `fs.Stats` that `wasm_exec.js` reads. Fields not
+ * relevant to Go's `os.FileInfo` (e.g. ownership) are zeroed.
+ */
 export interface IFileStats {
   isDirectory(): boolean;
   isFile(): boolean;
@@ -170,12 +191,19 @@ export interface IFileStats {
   blocks: number;
 }
 
+/** Internal filesystem tree node. Directories carry an empty `data` buffer. */
 interface INode {
   kind: "file" | "dir";
   data: Uint8Array;
   mtimeMs: number;
 }
 
+/**
+ * Filesystem error with a POSIX error code and numeric `errno`.
+ *
+ * Matches the shape of `NodeJS.ErrnoException` so Go's os package interprets it
+ * as a proper `os.PathError` with a numeric error code.
+ */
 export class MemFSError extends Error {
   public code: string;
   public errno: number;
@@ -190,6 +218,7 @@ export class MemFSError extends Error {
   }
 }
 
+/** Map a POSIX error name to its Linux numeric errno (negative by convention). */
 function errnoForCode(code: string): number {
   switch (code) {
     case "ENOENT":
@@ -207,6 +236,11 @@ function errnoForCode(code: string): number {
   }
 }
 
+/**
+ * Handle returned by `createMemFS`. Provides the `fs` shim to install on
+ * `globalThis` plus convenience methods for seeding the virtual filesystem
+ * before booting the wasm.
+ */
 export interface IMemFSHost {
   fs: IWasmExecFS;
   writeFile(path: string, data: string | Uint8Array): void;
@@ -222,6 +256,12 @@ export interface IMemFSHost {
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
+/**
+ * Resolve a path to an absolute, normalized POSIX path.
+ *
+ * Collapses `.` and `..` segments and converts backslashes. Returns `"/"` for
+ * empty input.
+ */
 function normalize(p: string): string {
   if (!p) return "/";
   const parts = p.replace(/\\/g, "/").split("/").filter(Boolean);
@@ -237,6 +277,15 @@ function normalize(p: string): string {
   return "/" + stack.join("/");
 }
 
+/**
+ * Create an in-memory filesystem suitable for use as `globalThis.fs` inside a
+ * Go/wasm runtime.
+ *
+ * The returned host exposes the low-level `fs` object (install it on
+ * `globalThis.fs` before loading `wasm_exec.js`) and convenience helpers
+ * (`writeFile`, `readFile`, `mkdirp`, …) for seeding source files and reading
+ * compiler output without touching the real filesystem.
+ */
 export function createMemFS(): IMemFSHost {
   const nodes = new Map<string, INode>();
   nodes.set("/", { kind: "dir", data: new Uint8Array(), mtimeMs: Date.now() });
@@ -271,6 +320,10 @@ export function createMemFS(): IMemFSHost {
   }
   const pipes = new Map<number, IPipeState>();
 
+  /**
+   * Drain buffered pipe data into `buffer[offset..offset+length]`. Returns
+   * bytes copied.
+   */
   function drainPipeInto(
     state: IPipeState,
     buffer: Uint8Array,
@@ -289,19 +342,29 @@ export function createMemFS(): IMemFSHost {
     return written;
   }
 
+  /**
+   * Satisfy any pending blocked readers using available pipe data or EOF
+   * signal.
+   */
   function flushPipeReaders(state: IPipeState): void {
     while (
       state.pendingReaders.length > 0 &&
       (state.buffers.length > 0 || state.writeClosed)
     ) {
       const reader = state.pendingReaders.shift()!;
-      const n = drainPipeInto(state, reader.buffer, reader.offset, reader.length);
+      const n = drainPipeInto(
+        state,
+        reader.buffer,
+        reader.offset,
+        reader.length,
+      );
       // Even at EOF (writeClosed && empty buffers) we satisfy with n=0 which
       // signals EOF to the Go-side caller.
       reader.callback(null, n);
     }
   }
 
+  /** Silently create any missing ancestor directories for path `p`. */
   function ensureParentDirs(p: string): void {
     const segments = normalize(p).split("/").filter(Boolean);
     segments.pop();
@@ -358,6 +421,7 @@ export function createMemFS(): IMemFSHost {
     return nodes.has(normalize(p));
   }
 
+  /** Synchronously stat `p`; throws `MemFSError("ENOENT")` if not found. */
   function statSync(p: string): IFileStats {
     const norm = normalize(p);
     const node = nodes.get(norm);
@@ -365,6 +429,7 @@ export function createMemFS(): IMemFSHost {
     return makeStats(node);
   }
 
+  /** Build an `IFileStats` object from a filesystem node. */
   function makeStats(node: INode): IFileStats {
     const isDir = node.kind === "dir";
     return {
@@ -386,6 +451,12 @@ export function createMemFS(): IMemFSHost {
     };
   }
 
+  /**
+   * Return immediate children of directory `p`, sorted alphabetically.
+   *
+   * Uses a linear scan over the node map and a `Set` to deduplicate nested
+   * paths into direct-child names — O(n) in the number of total nodes.
+   */
   function readdirSync(p: string): string[] {
     const norm = normalize(p);
     const node = nodes.get(norm);
@@ -438,9 +509,12 @@ export function createMemFS(): IMemFSHost {
       if (entry) {
         const node = nodes.get(entry.path);
         if (node && node.kind === "file") {
+          // subarray(0) is a zero-copy view over the full incoming buffer.
           const incoming = buf.subarray(0);
           const existing = node.data;
-          const next = new Uint8Array(existing.byteLength + incoming.byteLength);
+          const next = new Uint8Array(
+            existing.byteLength + incoming.byteLength,
+          );
           next.set(existing, 0);
           next.set(incoming, existing.byteLength);
           node.data = next;
@@ -455,7 +529,11 @@ export function createMemFS(): IMemFSHost {
       stderr.buffer += decoder.decode(buf);
       // eslint-disable-next-line no-console
       console.error(
-        "[wasm] writeSync to unknown fd " + fd + " (" + buf.byteLength + " bytes); routed to stderr buffer",
+        "[wasm] writeSync to unknown fd " +
+          fd +
+          " (" +
+          buf.byteLength +
+          " bytes); routed to stderr buffer",
       );
       return buf.length;
     },
@@ -599,7 +677,10 @@ export function createMemFS(): IMemFSHost {
       try {
         callback(null, statSync(p));
       } catch (err) {
-        callback(err as NodeJS.ErrnoException, undefined as unknown as IFileStats);
+        callback(
+          err as NodeJS.ErrnoException,
+          undefined as unknown as IFileStats,
+        );
       }
     },
 
@@ -614,7 +695,11 @@ export function createMemFS(): IMemFSHost {
       if (pipes.has(fd)) {
         callback(
           null,
-          makeStats({ kind: "file", data: new Uint8Array(), mtimeMs: Date.now() }),
+          makeStats({
+            kind: "file",
+            data: new Uint8Array(),
+            mtimeMs: Date.now(),
+          }),
         );
         return;
       }

package/src/api.ts

@@ -3,28 +3,40 @@
 // `playground.wasm`, typia's `ttsc-typia.wasm`) exposes the same surface, so
 // one set of types covers them all.
 
+/**
+ * API object that every host-built wasm binds to `globalThis[apiName]`.
+ *
+ * Obtain an instance via `bootTtsc`, which waits for the wasm to signal
+ * readiness and returns the typed handle together with its `IMemFSHost`.
+ */
 export interface ITtscApi {
   /** Build metadata reported by the wasm. Useful for diagnostics. */
   version(): ITtscVersion;
 
-  /** Compile a project: typecheck + emit. `result` is JSON; `parseResult<ITtscCompileResult>` deserializes it. */
+  /**
+   * Compile a project: typecheck + emit. `result` is JSON;
+   * `parseResult<ITtscCompileResult>` deserializes it.
+   */
   build(opts: ITtscBuildOpts): Promise<ITtscResult>;
 
-  /** Typecheck without emit. `result` is JSON; `parseResult<ITtscCompileResult>` deserializes it. */
+  /**
+   * Typecheck without emit. `result` is JSON; `parseResult<ITtscCompileResult>`
+   * deserializes it.
+   */
   check(opts: ITtscBuildOpts): Promise<ITtscResult>;
 
   /**
-   * Return every source file the program saw, keyed by project-relative
-   * path. Used by playgrounds that want to render the TypeScript view after
-   * a source rewriter (e.g. paths) has run. `result` is JSON; use
+   * Return every source file the program saw, keyed by project-relative path.
+   * Used by playgrounds that want to render the TypeScript view after a source
+   * rewriter (e.g. paths) has run. `result` is JSON; use
    * `parseResult<ITtscTransformResult>` to deserialize.
    */
   transform(opts: ITtscBuildOpts): Promise<ITtscResult>;
 
   /**
    * Dispatch a registered plugin's subcommand. Returns the captured stdout /
-   * stderr (the same streams the native sidecar binary would write to)
-   * together with the exit code.
+   * stderr (the same streams the native sidecar binary would write to) together
+   * with the exit code.
    */
   plugin(opts: ITtscPluginOpts): Promise<ITtscResult>;
 
@@ -32,6 +44,7 @@ export interface ITtscApi {
   plugins(): string[];
 }
 
+/** Build metadata embedded in the wasm by the Go linker at compile time. */
 export interface ITtscVersion {
   version: string;
   commit: string;
@@ -41,13 +54,15 @@ export interface ITtscVersion {
   goarch: string;
 }
 
+/** Options shared by `build`, `check`, and `transform`. */
 export interface ITtscBuildOpts {
   /** Absolute virtual path the project lives at inside the MemFS. */
   cwd: string;
-  /** tsconfig path, relative to `cwd`. Defaults to `tsconfig.json`. */
+  /** Tsconfig path, relative to `cwd`. Defaults to `tsconfig.json`. */
   tsconfig?: string;
 }
 
+/** Options for dispatching a named plugin subcommand via `api.plugin`. */
 export interface ITtscPluginOpts {
   /** Plugin id registered with `host.Expose` (e.g. `@ttsc/banner`). */
   name: string;
@@ -61,6 +76,7 @@ export interface ITtscPluginOpts {
   [key: string]: string | boolean | number | undefined;
 }
 
+/** Envelope returned by every `ITtscApi` method. */
 export interface ITtscResult {
   /** Exit code. 0 = success, 2 = usage error, 3 = runtime error. */
   code: number;
@@ -69,23 +85,40 @@ export interface ITtscResult {
   /** Anything the wasm wrote to its stderr stream. */
   stderr: string;
   /**
-   * For the base endpoints, the JSON-encoded compile/transform result. For
-   * the plugin endpoint, this is empty — the plugin's own output sits in
+   * For the base endpoints, the JSON-encoded compile/transform result. For the
+   * plugin endpoint, this is empty — the plugin's own output sits in
    * stdout/stderr. Use `parseResult<T>` to deserialize.
    */
   result: string;
 }
 
+/**
+ * Structured payload inside `ITtscResult.result` for `build` and `check`.
+ *
+ * `output` maps emit-destination paths (relative to `outDir`) to file contents.
+ * It is empty when `check` is called without emit.
+ */
 export interface ITtscCompileResult {
   diagnostics?: ITtscDiagnostic[];
   output: Record<string, string>;
 }
 
+/**
+ * Structured payload inside `ITtscResult.result` for `transform`.
+ *
+ * `typescript` maps source file paths (relative to `cwd`) to their
+ * post-transform TypeScript text — useful for playgrounds that want to show the
+ * rewritten source before it is emitted.
+ */
 export interface ITtscTransformResult {
   diagnostics?: ITtscDiagnostic[];
   typescript: Record<string, string>;
 }
 
+/**
+ * A single TypeScript compiler diagnostic emitted during `build`, `check`, or
+ * `transform`. `line` and `character` are 0-based.
+ */
 export interface ITtscDiagnostic {
   file: string | null;
   category: "error" | "warning";
@@ -98,9 +131,9 @@ export interface ITtscDiagnostic {
 }
 
 /**
- * Parse the `result` field of an ITtscResult into the structured payload.
- * The wasm returns JSON as a string because js.ValueOf does not handle large
- * nested maps efficiently. Callers JSON.parse exactly once at the boundary.
+ * Parse the `result` field of an ITtscResult into the structured payload. The
+ * wasm returns JSON as a string because js.ValueOf does not handle large nested
+ * maps efficiently. Callers JSON.parse exactly once at the boundary.
  */
 export function parseResult<T>(result: ITtscResult): T | null {
   if (!result.result) return null;

package/src/index.ts

@@ -9,11 +9,7 @@ export { bootTtsc } from "./instantiate";
 export type { IBootTtscOptions, IBootResult } from "./instantiate";
 
 export { createMemFS, MemFSError } from "./MemFS";
-export type {
-  IMemFSHost,
-  IWasmExecFS,
-  IFileStats,
-} from "./MemFS";
+export type { IMemFSHost, IWasmExecFS, IFileStats } from "./MemFS";
 
 export type {
   ITtscApi,