@ttsc/wasm 0.30.3 → 0.31.0

package/host/api.go

@@ -16,50 +16,22 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
-// APIResult is the stdout/stderr capture returned by InvokePlugin. 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"`
-  Stderr string `json:"stderr"`
-}
-
-// CompileResult mirrors `ttsc api-compile`. Field names are TypeScript-style
-// so JS callers can use it directly without remapping.
-type CompileResult struct {
-  Diagnostics []CompileDiagnostic `json:"diagnostics,omitempty"`
-  // Output maps cwd-relative paths to emitted JS / d.ts text. Empty when
-  // the program produced no files (e.g. `noEmit` projects).
-  Output map[string]string `json:"output"`
-}
-
-// TransformResult is the no-emit companion. The `typescript` map keys files
-// the same way `output` does in compile mode.
-type TransformResult struct {
-  Diagnostics []CompileDiagnostic `json:"diagnostics,omitempty"`
-  TypeScript  map[string]string   `json:"typescript"`
-}
-
-// CompileDiagnostic is the public TypeScript-side diagnostic DTO. Mirrors the
-// shape `ttsc api-compile` writes so the JS host can render it without
-// remapping fields.
-type CompileDiagnostic struct {
-  File        *string `json:"file"`
-  Category    string  `json:"category"`
-  Code        int32   `json:"code"`
-  Start       *int    `json:"start,omitempty"`
-  Length      *int    `json:"length,omitempty"`
-  Line        int     `json:"line,omitempty"`
-  Character   int     `json:"character,omitempty"`
-  MessageText string  `json:"messageText"`
-}
-
 // Build runs `ttsc build`-shaped emit: load the project, emit JS, return the
 // emitted text map + diagnostics as JSON. `cwd` must be an absolute path
 // inside the host filesystem; `tsconfigPath` may be relative to cwd.
+//
+// The loaded Program is closed on every return after acquisition. Compiler
+// diagnostics still accompany emitted files; code 2 reports compiler errors,
+// while code 3 reports emit or serialization failures.
+//
+// @evidence contracts/common.md#principled-implementation LoadProgram and EmitAll own compiler behavior; encoding/json projects their results through the documented envelope.
+// @evidence contracts/common.md#clear-and-simple-design One emit pipeline owns project acquisition, supported WriteFile capture and diagnostics; shared projection helpers centralize path and diagnostic policy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Emit uses supported compiler hooks, without patching foreign emitters or synthesizing expected outputs.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain paths, ownership and failure stages under the documentation skill's rationale guidance.
+// @evidence contracts/portability.md#os-neutral-implementation LoadProgram owns filesystem access through the driver's supported host. Native filepath.Rel identifies inside/outside destinations, including volume differences, and ToSlash changes JSON spelling without lowercasing identity.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Build closes its Program before returning and transfers the output to the caller, so it retains nothing.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Build delegates parsing, checking and emit to the driver and adds one pass over the diagnostics and the emitted output map.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Build loads a fresh Program per call because the virtual filesystem may have changed; sharing a loaded Program is the snapshot verbs' purpose.
 func Build(cwd, tsconfigPath string) ([]byte, int, error) {
   prog, diags, err := driver.LoadProgram(cwd, tsconfigPath, driver.LoadProgramOptions{
     ForceEmit: true,
@@ -106,6 +78,15 @@ func Build(cwd, tsconfigPath string) ([]byte, int, error) {
 
 // Check runs the typecheck pipeline without emitting JS. The returned JSON
 // has the same shape as Build but with an empty `output` map.
+//
+// @evidence contracts/common.md#principled-implementation ForceNoEmit selects the driver's check pipeline and a deferred Close owns the loaded program.
+// @evidence contracts/common.md#clear-and-simple-design The no-emit entry keeps loading and diagnostic projection explicit while sharing DTO and path helpers with the emit entry.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No-emit is requested from the compiler rather than hiding an unnecessary emit behind an empty result.
+// @evidence contracts/common.md#meaningful-documentation Native comments explain no-emit and payload equivalence under the documentation skill's context guidance.
+// @evidence contracts/portability.md#os-neutral-implementation The driver resolves cwd/config through its filesystem host; diagnostic paths use filepath.ToSlash only for wire spelling. The adapter neither guesses case policy nor constructs a shell command.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Check closes its Program before returning and transfers the diagnostics to the caller, so it retains nothing.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Check delegates loading and checking to the driver and adds one pass over the diagnostics.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Check loads a fresh Program per call because the virtual filesystem may have changed; sharing a loaded Program is the snapshot verbs' purpose.
 func Check(cwd, tsconfigPath string) ([]byte, int, error) {
   prog, diags, err := driver.LoadProgram(cwd, tsconfigPath, driver.LoadProgramOptions{
     ForceNoEmit: true,
@@ -138,6 +119,18 @@ func Check(cwd, tsconfigPath string) ([]byte, int, error) {
 // Transform returns every source file the program saw, keyed by
 // project-relative path. The playground uses this to render the TS view
 // after source rewrites (e.g. paths rewriting) have been applied.
+//
+// Sources inside cwd use relative keys; outside sources retain absolute slash
+// paths. The invocation closes the loaded Program after copying its source text.
+//
+// @evidence contracts/common.md#principled-implementation LoadProgram supplies post-plugin SourceFiles and encoding/json preserves their source-text projection.
+// @evidence contracts/common.md#clear-and-simple-design The source projection is separate from emit, and common path/diagnostic helpers keep their shared representation policy in one place.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The program's own text is authoritative, without a secondary emitter-based reconstruction.
+// @evidence contracts/common.md#meaningful-documentation Separate paragraphs explain stage, path convention and ownership under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Source identities come from LoadProgram, then the shared filepath relative/absolute mapping preserves native case and handles outside/other-volume paths before slash serialization.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Transform closes its Program after copying the source text, so it retains nothing.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Transform delegates loading to the driver and adds one pass over the source files and diagnostics.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Transform loads a fresh Program per call because the virtual filesystem may have changed; sharing a loaded Program is the snapshot verbs' purpose.
 func Transform(cwd, tsconfigPath string) ([]byte, int, error) {
   prog, diags, err := driver.LoadProgram(cwd, tsconfigPath, driver.LoadProgramOptions{
     ForceNoEmit: true,

package/host/doc.go

@@ -3,7 +3,7 @@
 //
 // A consumer wasm looks like this:
 //
-//  //go:build js
+//  //go:build js && wasm
 //  package main
 //
 //  import (
@@ -12,14 +12,15 @@
 //  )
 //
 //  func main() {
-//    // Expose never returns; it installs the JS API and blocks forever.
+//    // A valid registration installs the JS API until Worker termination.
 //    host.Expose("yourApi", host.Config{
 //      Plugins: []host.Plugin{yourplugin.New()},
 //    })
 //  }
 //
 // Expose binds `globalThis[name]` to an object that exposes ttsc's base
-// project commands (build, check, transform, version) plus
+// project commands (build, check, transform, version), the retained-program
+// queries (snapshot and the get* verbs), `plugins()`, and
 // `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
@@ -27,7 +28,7 @@
 // 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
-// to keep CI happy.
+// JavaScript bindings use //go:build js && wasm. A native build selects a
+// no-op Expose with the same signature and the shared project/plugin helpers;
+// checking the bodies of js/wasm-only files requires a js/wasm build.
 package host

package/host/expose.go

@@ -0,0 +1,42 @@
+package host
+
+// API stability: experimental until v1.0; signatures may change between
+// minor releases. Pin exact versions in production playgrounds.
+//
+// Expose installs `globalThis[apiName]` with the base API endpoints and the
+// plugin dispatcher, then keeps the Go runtime alive until Worker termination.
+// Invalid or duplicate registration reports failure and returns before binding.
+// A native build (without js/wasm) selects an alternative that installs nothing
+// and returns immediately, so native entrypoints can import the package.
+//
+// The contract:
+//
+//   - globalThis[apiName].version()                        → { version, commit, date, go, goos, goarch }
+//   - globalThis[apiName].build({ cwd, tsconfig })         → Promise<ITtscResult>
+//   - globalThis[apiName].check({ cwd, tsconfig })         → Promise<ITtscResult>
+//   - globalThis[apiName].transform({ cwd, tsconfig })     → Promise<ITtscResult>
+//   - globalThis[apiName].plugin({ name, command, ...opts}) → Promise<ITtscResult>
+//   - globalThis[apiName].plugins()                        → string[] of registered names
+//
+// The retained-program verbs (snapshot, releaseSnapshot, snapshots,
+// getSourceFiles, getSourceFileText, getDiagnostics, getNodeAtPosition,
+// getTypeAtPosition, getSymbolAtPosition) are installed beside them and return
+// the same envelope.
+//
+// build/check/transform encode their structured payloads as JSON in
+// ITtscResult.result. Plugin stdout/stderr are captured in the envelope streams.
+//
+// A matching readiness resolver is invoked: `globalThis[`${apiName}Ready`]`.
+// JS callers register this BEFORE go.run begins so they can await wasm boot.
+//
+// @evidence contracts/common.md#principled-implementation syscall/js bindings and explicit Ready/Failed callbacks implement the Go wasm host protocol; an atomic gate owns one installation per instance, and build constraints select a no-op native alternative behind the same signature.
+// @evidence contracts/common.md#clear-and-simple-design Expose owns one registration and readiness boundary; project adapters, plugin invocation and fountain queries remain named helpers with their own state instead of duplicating binding policy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Registered plugins use owned invocation streams rather than foreign global-output replacement; rejected duplicate installation is reported through the boot failure boundary.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain setup order, payload channels and runtime lifetime under the documentation skill's context guidance.
+// @evidence contracts/performance.md#efficient-algorithms Registration visits P supplied plugins once with map duplicate checks and creates a fixed set of endpoint bindings. Snapshot lookup uses a map; source lookup uses the driver's existing compiler index, with path normalization and hashing proportional to path length. A relative path may require a second indexed lookup. List/diagnostic queries traverse their requested results; parsing, checking and printing remain driver Program work.
+// @evidence contracts/performance.md#reuse-equivalent-work Fountain queries reuse the explicitly acquired Program and its checker under one opaque handle; registry and entry locks keep queries within that snapshot's lifetime. Editing MemFS does not refresh an existing snapshot, so callers release and reacquire when they need a new project view rather than sharing by path alone.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The wasm instance owns P plugin registrations, pinned js.Func bindings and its keepalive until Worker termination. Each acquired snapshot owns a Program; registry readers finish before release deletes and closes it. Snapshot count, Program bytes and concurrent invocation tasks have no fixed bound. Promise executors release their js.Func after settlement, and InvokePlugin owns its own streams and child work.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Expose binds a JavaScript global in the wasm runtime and performs no native filesystem, path or process operation; the native alternative does nothing.
+func Expose(apiName string, cfg Config) {
+  expose(apiName, cfg)
+}

package/host/fountain.go

@@ -22,6 +22,7 @@ package host
 import (
   "encoding/json"
   "fmt"
+  "math"
   "path/filepath"
   "sync"
   "sync/atomic"
@@ -73,79 +74,234 @@ func fountainAPIMap() map[string]any {
 }
 
 // SnapshotResult is the response shape for `snapshot()`.
+// The caller owns Handle and must pass it to releaseSnapshot after its queries.
+//
+// @evidence contracts/common.md#principled-implementation An opaque string projects registry identity without exposing a Go Program through JSON.
+// @evidence contracts/common.md#clear-and-simple-design One opaque identity transfers query access while the Program and its ownership remain in the native registry.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Identity refers to an actual retained program rather than a reconstructed project path.
+// @evidence contracts/common.md#meaningful-documentation The Go comment explains opaque identity and caller release ownership under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources SnapshotResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms SnapshotResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work SnapshotResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation SnapshotResult is a data type and performs no native filesystem, path or process operation.
 type SnapshotResult struct {
+  // Handle is opaque and valid until released in this wasm instance.
   Handle string `json:"handle"`
 }
 
 // ReleaseSnapshotResult is the response shape for `releaseSnapshot()`.
+//
+// @evidence contracts/common.md#principled-implementation A boolean distinguishes a removed registry entry from idempotent absent-handle release.
+// @evidence contracts/common.md#clear-and-simple-design One outcome bit reports removal without duplicating the request handle or native cleanup state.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts An absent entry is not reported as a fabricated successful removal.
+// @evidence contracts/common.md#meaningful-documentation Native comments explain the release outcome under the documentation skill's absence guidance.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ReleaseSnapshotResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms ReleaseSnapshotResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work ReleaseSnapshotResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation ReleaseSnapshotResult is a data type and performs no native filesystem, path or process operation.
 type ReleaseSnapshotResult struct {
+  // Released is false when the handle was never present or already removed.
   Released bool `json:"released"`
 }
 
 // ListSnapshotsResult is the response shape for `snapshots()`.
+//
+// @evidence contracts/common.md#principled-implementation A string slice projects registry identities without a second public program representation.
+// @evidence contracts/common.md#clear-and-simple-design A flat current-handle list exposes membership without expanding each entry into an unused snapshot descriptor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Current map membership supplies the list rather than a history of expected handles.
+// @evidence contracts/common.md#meaningful-documentation Native member comments identify live state and unspecified order under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ListSnapshotsResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms ListSnapshotsResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work ListSnapshotsResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation ListSnapshotsResult is a data type and performs no native filesystem, path or process operation.
 type ListSnapshotsResult struct {
+  // Handles lists live registry keys in unspecified order; empty encodes as [].
   Handles []string `json:"handles"`
 }
 
 // GetSourceFilesResult is the response shape for `getSourceFiles()`.
+//
+// @evidence contracts/common.md#principled-implementation The program's SourceFiles are projected into path strings through the shared output-key policy.
+// @evidence contracts/common.md#clear-and-simple-design File identities are separate from source text and semantic metadata, keeping listing focused on program membership.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler membership determines files instead of a guessed filesystem glob.
+// @evidence contracts/common.md#meaningful-documentation The member comment explains path bases and declaration exclusion under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GetSourceFilesResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GetSourceFilesResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GetSourceFilesResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetSourceFilesResult is a data type and performs no native filesystem, path or process operation.
 type GetSourceFilesResult struct {
+  // Files excludes declarations; paths outside cwd remain absolute slash paths.
   Files []string `json:"files"`
 }
 
 // GetSourceFileTextResult is the response shape for `getSourceFileText()`.
+//
+// @evidence contracts/common.md#principled-implementation A required string projects program text while file lookup failures use the error envelope.
+// @evidence contracts/common.md#clear-and-simple-design One text field represents the selected file; request identity and transport status remain in their existing shapes.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Text comes from the snapshot instead of a separately read file that may have changed.
+// @evidence contracts/common.md#meaningful-documentation The member comment names retained-program provenance under the documentation skill's context guidance.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GetSourceFileTextResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GetSourceFileTextResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GetSourceFileTextResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetSourceFileTextResult is a data type and performs no native filesystem, path or process operation.
 type GetSourceFileTextResult struct {
+  // Text is the source currently held by the retained Program, including rewrites.
   Text string `json:"text"`
 }
 
 // GetDiagnosticsResult is the response shape for `getDiagnostics()`.
+//
+// @evidence contracts/common.md#principled-implementation The shared CompileDiagnostic slice preserves the compiler's public diagnostic projection.
+// @evidence contracts/common.md#clear-and-simple-design The selected messages reuse the compile diagnostic DTO rather than introducing a snapshot-specific message model.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Queries return compiler messages rather than source-pattern approximations of diagnostics.
+// @evidence contracts/common.md#meaningful-documentation Native comments identify the payload and empty-array meaning under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GetDiagnosticsResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GetDiagnosticsResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GetDiagnosticsResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetDiagnosticsResult is a data type and performs no native filesystem, path or process operation.
 type GetDiagnosticsResult struct {
+  // Diagnostics is an initialized slice, so no selected messages encodes as [].
   Diagnostics []CompileDiagnostic `json:"diagnostics"`
 }
 
 // NodeInfo is the serialized AST node returned by `getNodeAtPosition`.
+//
+// @evidence contracts/common.md#principled-implementation Kind metadata and native byte ranges project a token without exposing Go AST objects.
+// @evidence contracts/common.md#clear-and-simple-design A flat kind/range/spelling value carries syntax information without mutable AST links or another token hierarchy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Native ranges remain byte coordinates rather than guessed JavaScript character indices.
+// @evidence contracts/common.md#meaningful-documentation Member comments explain native identity, units and optional text under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources NodeInfo is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms NodeInfo is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work NodeInfo is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation NodeInfo is a data type and performs no native filesystem, path or process operation.
 type NodeInfo struct {
-  Kind     int    `json:"kind"`
+  // Kind is the numeric TypeScript-Go AST kind.
+  Kind int `json:"kind"`
+
+  // KindName is its human-readable Stringer name.
   KindName string `json:"kindName"`
-  Pos      int    `json:"pos"`
-  End      int    `json:"end"`
-  Text     string `json:"text,omitempty"`
+
+  // Pos is the inclusive UTF-8 byte offset of the token's first byte, after any
+  // leading whitespace and comments.
+  Pos int `json:"pos"`
+
+  // End is the exclusive UTF-8 byte offset.
+  End int `json:"end"`
+
+  // Text is omitted when the scanner has no nonempty source spelling.
+  Text string `json:"text,omitempty"`
 }
 
 // GetNodeAtPositionResult is the response shape for `getNodeAtPosition()`.
+//
+// @evidence contracts/common.md#principled-implementation A nullable pointer distinguishes successful absence from the query's error envelope.
+// @evidence contracts/common.md#clear-and-simple-design One nullable token projection conveys lookup outcome without another status flag or duplicated source identity.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No fabricated node fills whitespace or an absent token.
+// @evidence contracts/common.md#meaningful-documentation The member comment explains null token absence under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GetNodeAtPositionResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GetNodeAtPositionResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GetNodeAtPositionResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetNodeAtPositionResult is a data type and performs no native filesystem, path or process operation.
 type GetNodeAtPositionResult struct {
+  // Node encodes as null when no syntax token touches the queried position.
   Node *NodeInfo `json:"node"`
 }
 
 // TypeInfo is the serialized type returned by `getTypeAtPosition`.
+//
+// @evidence contracts/common.md#principled-implementation Checker-printed text and native flags avoid a parallel incomplete public type model.
+// @evidence contracts/common.md#clear-and-simple-design Presentation text and native classification bits are sufficient for this query; structural compiler types stay behind the checker boundary.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The checker supplies type presentation rather than inferring it from token spelling.
+// @evidence contracts/common.md#meaningful-documentation Native comments identify printing authority and flag provenance under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources TypeInfo is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms TypeInfo is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work TypeInfo is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation TypeInfo is a data type and performs no native filesystem, path or process operation.
 type TypeInfo struct {
-  Text  string `json:"text"`
-  Flags int    `json:"flags"`
+  // Text is the checker's TypeToString presentation.
+  Text string `json:"text"`
+
+  // Flags is the numeric TypeScript-Go TypeFlags bitmask.
+  Flags int `json:"flags"`
 }
 
 // GetTypeAtPositionResult is the response shape for `getTypeAtPosition()`.
+//
+// @evidence contracts/common.md#principled-implementation Nullable semantic output mirrors the TypeScript request result without overloading an error type.
+// @evidence contracts/common.md#clear-and-simple-design One nullable type field separates semantic absence from transport errors without duplicating the type metadata representation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Positions without type semantics remain absent rather than receiving a fabricated any type.
+// @evidence contracts/common.md#meaningful-documentation The member comment explains null meaning under the documentation skill's absence guidance.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GetTypeAtPositionResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GetTypeAtPositionResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GetTypeAtPositionResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetTypeAtPositionResult is a data type and performs no native filesystem, path or process operation.
 type GetTypeAtPositionResult struct {
+  // Type encodes as null when the touching token has no semantic type result.
   Type *TypeInfo `json:"type"`
 }
 
 // SymbolDeclaration is the serialized declaration site returned by
 // `getSymbolAtPosition`.
+//
+// @evidence contracts/common.md#principled-implementation Nullable source identity and native ranges preserve declaration provenance through JSON.
+// @evidence contracts/common.md#clear-and-simple-design A declaration site contains only file identity and its byte interval; source text and compiler node ownership remain elsewhere.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A source-less declaration keeps nil identity rather than a placeholder filename.
+// @evidence contracts/common.md#meaningful-documentation Member comments explain path identity and byte interval units under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources SymbolDeclaration is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms SymbolDeclaration is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work SymbolDeclaration is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation SymbolDeclaration is a data type and performs no native filesystem, path or process operation.
 type SymbolDeclaration struct {
+  // File is a project-relative or outside absolute path, nil for source-less nodes.
   File *string `json:"file"`
-  Pos  int     `json:"pos"`
-  End  int     `json:"end"`
+
+  // Pos is the inclusive UTF-8 byte offset of the declaration's first token,
+  // after any leading whitespace, comments and JSDoc.
+  Pos int `json:"pos"`
+
+  // End is the declaration's exclusive UTF-8 byte offset.
+  End int `json:"end"`
 }
 
 // SymbolInfo is the serialized symbol returned by `getSymbolAtPosition`.
+//
+// @evidence contracts/common.md#principled-implementation Raw and printed names, flags and declaration projections preserve the native checker result.
+// @evidence contracts/common.md#clear-and-simple-design Identity and display text are distinct, and one capped site list plus its original total explains truncation without separate declaration handles.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The response cap preserves the original total rather than presenting a shortened declaration list as complete.
+// @evidence contracts/common.md#meaningful-documentation Native comments distinguish internal names, display text and capped metadata under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources SymbolInfo is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms SymbolInfo is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work SymbolInfo is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation SymbolInfo is a data type and performs no native filesystem, path or process operation.
 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"`
+  // Name is the raw name, including TypeScript internal prefix markers.
+  Name string `json:"name"`
+
+  // Text is the optional checker-printed symbol representation.
+  Text string `json:"text,omitempty"`
+
+  // Flags is the numeric TypeScript-Go SymbolFlags bitmask.
+  Flags int `json:"flags"`
+
+  // Declarations contains at most 16 sites and is omitted when empty.
+  Declarations []SymbolDeclaration `json:"declarations,omitempty"`
+
+  // DeclarationCount retains the original total and is omitted when zero.
+  DeclarationCount int `json:"declarationCount,omitempty"`
 }
 
 // GetSymbolAtPositionResult is the response shape for `getSymbolAtPosition()`.
+//
+// @evidence contracts/common.md#principled-implementation A nullable symbol pointer distinguishes absent semantics from a failed request.
+// @evidence contracts/common.md#clear-and-simple-design One nullable symbol field expresses the binding outcome while symbol metadata and request status remain separate.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing binding does not produce a symbol guessed from the token's name.
+// @evidence contracts/common.md#meaningful-documentation The member comment explains null result meaning under the documentation skill.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GetSymbolAtPositionResult is a data type and acquires no handle, task or retained state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GetSymbolAtPositionResult is a data type and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GetSymbolAtPositionResult is a data type and coordinates no shared or repeated computation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetSymbolAtPositionResult is a data type and performs no native filesystem, path or process operation.
 type GetSymbolAtPositionResult struct {
+  // Symbol encodes as null when the touching token has no associated symbol.
   Symbol *SymbolInfo `json:"symbol"`
 }
 
@@ -298,7 +454,7 @@ func jsGetDiagnostics(this js.Value, args []js.Value) any {
 func jsGetNodeAtPosition(this js.Value, args []js.Value) any {
   return withSnapshotPosition(args, func(_ *snapshotEntry, file *ast.SourceFile, pos int) any {
     node := tokenAtPosition(file, pos)
-    return fountainOK(GetNodeAtPositionResult{Node: nodeInfoOf(node)})
+    return fountainOK(GetNodeAtPositionResult{Node: nodeInfoOf(file, node)})
   })
 }
 
@@ -391,17 +547,18 @@ func withSnapshotPosition(args []js.Value, fn func(*snapshotEntry, *ast.SourceFi
     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")
+    offset := posVal.Float()
+    if math.IsNaN(offset) || math.IsInf(offset, 0) || math.Trunc(offset) != offset || offset < 0 {
+      return errorResponse(2, "host: \"position\" must be a finite non-negative integer byte offset")
     }
     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 is outside file length %d", pos, len(file.Text())))
+    if offset >= float64(len(file.Text())) {
+      return errorResponse(2, fmt.Sprintf("host: \"position\" %v is outside file length %d", offset, len(file.Text())))
     }
+    pos := int(offset)
     return fn(entry, file, pos)
   })
 }
@@ -446,7 +603,7 @@ func resolveSnapshotFile(entry *snapshotEntry, path string) *ast.SourceFile {
   return nil
 }
 
-// snapshotFileKey mirrors apiOutputKey but is exported for use by all
+// snapshotFileKey delegates to apiOutputKey for use by all
 // fountain endpoints that return file paths.
 func snapshotFileKey(cwd, fileName string) string {
   return apiOutputKey(cwd, fileName)
@@ -469,14 +626,18 @@ func fountainOK(payload any) any {
 }
 
 // nodeInfoOf converts a *ast.Node into the JSON-serializable NodeInfo.
-func nodeInfoOf(node *ast.Node) *NodeInfo {
+//
+// Pos is the token's first byte, after leading whitespace and comments.
+// TypeScript-Go's Node.Pos is the full start, which includes that trivia, so
+// reporting it would give an interval wider than the Text it describes.
+func nodeInfoOf(file *ast.SourceFile, node *ast.Node) *NodeInfo {
   if node == nil {
     return nil
   }
   info := &NodeInfo{
     Kind:     int(node.Kind),
     KindName: astKindName(node.Kind),
-    Pos:      node.Pos(),
+    Pos:      tokenStart(file, node),
     End:      node.End(),
   }
   if text := shimscanner.GetTextOfNode(node); text != "" {
@@ -516,6 +677,7 @@ func symbolInfoOf(entry *snapshotEntry, sym *ast.Symbol) *SymbolInfo {
       }
       item := SymbolDeclaration{Pos: d.Pos(), End: d.End()}
       if file := ast.GetSourceFileOfNode(d); file != nil {
+        item.Pos = tokenStart(file, d)
         key := snapshotFileKey(entry.cwd, file.FileName())
         item.File = &key
       }
@@ -527,6 +689,14 @@ func symbolInfoOf(entry *snapshotEntry, sym *ast.Symbol) *SymbolInfo {
   return info
 }
 
+// tokenStart returns the byte offset of node's first token. It skips the leading
+// whitespace and comments that TypeScript-Go's Node.Pos includes; JSDoc attached
+// to a declaration is such a comment, so a declaration starts at its own first
+// token rather than at its documentation.
+func tokenStart(file *ast.SourceFile, node *ast.Node) int {
+  return shimscanner.GetTokenPosOfNode(node, file, false)
+}
+
 // 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 {

package/host/host.go

@@ -3,8 +3,9 @@
 // JS-side bindings for the host package.
 //
 // `Expose` installs `globalThis[apiName]` with the base ttsc endpoints
-// (version, build, check, transform) plus `plugin({ name, command, ...opts })`,
-// routing into the consumer's registered plugins. Every async endpoint returns
+// (version, build, check, transform), the retained-program verbs of
+// fountain.go, and `plugin({ name, command, ...opts })`, routing into the
+// consumer's registered plugins. Every async endpoint returns
 // the JS result envelope so callers can build a single boot helper that works
 // against any host-built binary.
 package host
@@ -14,6 +15,7 @@ import (
   "fmt"
   "os"
   "runtime"
+  "strconv"
   "sync/atomic"
   "syscall/js"
   "time"
@@ -27,31 +29,12 @@ var (
   date    = "unknown"
 )
 
-// exposed gates Expose so a duplicate call panics instead of leaking the
+// exposed gates Expose so a duplicate call reports failure instead of leaking the
 // previous batch of js.Funcs + spawning a second keepalive goroutine.
 var exposed atomic.Bool
 
-// API stability: experimental until v1.0; signatures may change between
-// minor releases. Pin exact versions in production playgrounds.
-//
-// Expose installs `globalThis[apiName]` with the base API endpoints and the
-// plugin dispatcher, then keeps the Go runtime alive forever.
-//
-// The contract:
-//
-//   - globalThis[apiName].version()                        → version banner
-//   - globalThis[apiName].build({ cwd, tsconfig })         → Promise<ITtscResult>
-//   - globalThis[apiName].check({ cwd, tsconfig })         → Promise<ITtscResult>
-//   - globalThis[apiName].transform({ cwd, tsconfig })     → Promise<ITtscResult>
-//   - globalThis[apiName].plugin({ name, command, ...opts}) → Promise<ITtscResult>
-//   - globalThis[apiName].plugins()                        → string[] of registered names
-//
-// build/check/transform encode their structured payloads as JSON in
-// ITtscResult.result. Plugin stdout/stderr are captured in the envelope streams.
-//
-// A matching readiness resolver is invoked: `globalThis[`${apiName}Ready`]`.
-// JS callers register this BEFORE go.run begins so they can await wasm boot.
-func Expose(apiName string, cfg Config) {
+// expose is the js/wasm implementation behind Expose.
+func expose(apiName string, cfg Config) {
   // Refuse double-Expose: the second call would leak every js.FuncOf from
   // the first batch (Go pins js.Funcs and they're not GC'd), spin a second
   // keepalive goroutine forever, and overwrite the ready resolver so JS
@@ -258,7 +241,9 @@ func buildPluginArgv(opts js.Value) []string {
         out = append(out, "--"+key)
       }
     case js.TypeNumber:
-      out = append(out, fmt.Sprintf("--%s=%v", key, value.Float()))
+      // 'f' with the shortest precision that round-trips keeps an integer such
+      // as 1234567 as "1234567"; `%v` would spell it "1.234567e+06".
+      out = append(out, "--"+key+"="+strconv.FormatFloat(value.Float(), 'f', -1, 64))
     }
   }
   return out

package/host/host_native.go

@@ -5,11 +5,9 @@
 // without GOOS=js, which native CI jobs need.
 package host
 
-// Expose is a no-op on native targets. Consumers can `go build ./...` to
-// type-check their wasm entry point without GOOS=js; the function symbol
-// stays in scope but the body short-circuits so it's safe to call from a
-// non-wasm sanity-test entrypoint.
-func Expose(apiName string, cfg Config) {
+// expose is the native alternative behind Expose: it installs no JavaScript API
+// and returns immediately.
+func expose(apiName string, cfg Config) {
   _ = apiName
   _ = cfg
 }