@ttsc/wasm 0.30.4 → 0.31.0

package/lib/src/structures/ITtscSnapshotResult.d.ts

@@ -1,4 +1,25 @@
-/** Payload inside `ITtscResult.result` for `snapshot`. */
+/**
+ * Payload inside `ITtscResult.result` for `snapshot`.
+ *
+ * The caller owns the returned snapshot and must release it when queries
+ * finish.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Returning an opaque handle keeps retained Go program objects behind the
+ *   native registry while allowing several queries to share one snapshot.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A single opaque handle transfers query access to the caller; registry state
+ *   and Program cleanup remain with the host instead of entering the payload.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The handle refers to a real registered program, without encoding a consumer
+ *   path or fabricated query result into the public identity.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Separate JSDoc paragraphs explain the envelope and release ownership, and
+ *   the member names its consumers, following the documentation skill's guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSnapshotResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSnapshotResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSnapshotResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSnapshotResult {
     /** Opaque handle; pass back to fountain verbs and to `releaseSnapshot`. */
     handle: string;

package/lib/src/structures/ITtscSnapshotsResult.d.ts

@@ -1,4 +1,22 @@
-/** Payload inside `ITtscResult.result` for `snapshots`. */
+/**
+ * Payload inside `ITtscResult.result` for `snapshots`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A string array mirrors the registry listing without exposing program objects
+ *   or implying an ordering that the native map does not provide.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A flat list exposes live registry identities without a second snapshot
+ *   descriptor layer or ownership information already supplied by its API.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Entries are current registry identities rather than an expected debug list.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc identifies the envelope, empty state and unspecified order using the
+ *   documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSnapshotsResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSnapshotsResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSnapshotsResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSnapshotsResult {
+    /** Live handles in unspecified order; empty when none are registered. */
     handles: string[];
 }

package/lib/src/structures/ITtscSourceFileTextResult.d.ts

@@ -1,4 +1,22 @@
-/** Payload inside `ITtscResult.result` for `getSourceFileText`. */
+/**
+ * Payload inside `ITtscResult.result` for `getSourceFileText`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A required text field mirrors the native successful response; missing files
+ *   use the error envelope rather than overloading an empty source string.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The selected file's text is the only payload field; request identity and
+ *   error status remain in the existing request and transport envelope.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Text comes from the retained program, without substituting the caller's
+ *   editor buffer or a separately loaded approximation of the snapshot.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc names the endpoint and retained-program provenance, following
+ *   the documentation skill's rule to explain the facts needed by a consumer.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSourceFileTextResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSourceFileTextResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSourceFileTextResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSourceFileTextResult {
     /** Current source text held by the snapshot's program. */
     text: string;

package/lib/src/structures/ITtscSourceFilesResult.d.ts

@@ -1,5 +1,26 @@
-/** Payload inside `ITtscResult.result` for `getSourceFiles`. */
+/**
+ * Payload inside `ITtscResult.result` for `getSourceFiles`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A string array carries the native program's source-file keys without making
+ *   the JavaScript consumer depend on Go AST objects.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The payload exposes only source identities; source text and semantic queries
+ *   remain separate operations instead of inflating every file-list response.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The program supplies file identity; the response does not invent a fixed
+ *   entry file or hide files according to a consumer name.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc identifies the endpoint, declaration-file exclusion and path convention,
+ *   following the documentation skill's usage-context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSourceFilesResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSourceFilesResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSourceFilesResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSourceFilesResult {
-    /** Project-relative paths of non-declaration source files. */
+    /**
+     * Non-declaration source paths: project-relative inside cwd, absolute
+     * outside.
+     */
     files: string[];
 }

package/lib/src/structures/ITtscSymbolAtPositionResult.d.ts

@@ -1,5 +1,22 @@
 import type { ITtscSymbolInfo } from "./ITtscSymbolInfo";
-/** Payload inside `ITtscResult.result` for `getSymbolAtPosition`. */
+/**
+ * Payload inside `ITtscResult.result` for `getSymbolAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The nullable symbol follows native pointer JSON encoding, keeping successful
+ *   absence distinct from a failed query envelope.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A nullable symbol field holds the lookup outcome; reusable symbol metadata
+ *   and transport failure are represented separately without another status flag.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Absence is explicit rather than filled with a guessed identifier or symbol.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc names the envelope and null meaning, following the documentation
+ *   skill's requirement to explain absence rather than repeat the field type.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSymbolAtPositionResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSymbolAtPositionResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSymbolAtPositionResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSymbolAtPositionResult {
     /** `null` when no touching token has an associated symbol. */
     symbol: ITtscSymbolInfo | null;

package/lib/src/structures/ITtscSymbolDeclaration.d.ts

@@ -1,7 +1,30 @@
-/** A single declaration site for a symbol. */
+/**
+ * A single declaration site for a symbol.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Nullable file identity and byte ranges preserve the native AST declaration
+ *   projection, including declarations without an associated source file.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Source identity and a byte interval are sufficient for a declaration site;
+ *   this value contains no redundant source text or compiler object references.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   A missing source file remains null; neither a placeholder filename nor a
+ *   guessed JavaScript character range is inserted into the declaration.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Member JSDoc explains path provenance and interval units, following the
+ *   documentation skill's guidance for absent state and coordinates.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSymbolDeclaration is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSymbolDeclaration is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSymbolDeclaration is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSymbolDeclaration {
-    /** Project-relative or absolute path; `null` for synthetic declarations. */
+    /** Project-relative or absolute path; null when no source file is associated. */
     file: string | null;
+    /**
+     * Inclusive start offset of the declaration's first token in the source's
+     * UTF-8 bytes, after leading whitespace, comments and JSDoc.
+     */
     pos: number;
+    /** Exclusive end offset in the source's UTF-8 bytes. */
     end: number;
 }

package/lib/src/structures/ITtscSymbolInfo.d.ts

@@ -1,5 +1,23 @@
 import type { ITtscSymbolDeclaration } from "./ITtscSymbolDeclaration";
-/** Symbol shape returned by `getSymbolAtPosition`. */
+/**
+ * Symbol shape returned by `getSymbolAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Names, flags and declaration projections match the native checker result;
+ *   separate displayed text avoids confusing raw internal names with presentation.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Identity and presentation are separate, while bounded declaration sites reuse
+ *   one site DTO and their total count explains a truncated projection directly.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The declaration cap is the host's response-size policy, with the original
+ *   total retained rather than pretending the shortened list is complete.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains internal naming, printing and capped versus total declarations,
+ *   following the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscSymbolInfo is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscSymbolInfo is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscSymbolInfo is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscSymbolInfo {
     /** Raw symbol name, including TypeScript's internal prefix markers. */
     name: string;

package/lib/src/structures/ITtscTransformResult.d.ts

@@ -2,11 +2,29 @@ import type { ITtscDiagnostic } from "./ITtscDiagnostic";
 /**
  * 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.
+ * `typescript` maps source paths to post-transform TypeScript text for a
+ * preview before emit. Paths inside `cwd` are relative; outside sources remain
+ * absolute.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A path-keyed string record matches the native transform payload, keeping
+ *   transformed TypeScript distinct from build's emitted JavaScript map.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A source-text map and the shared diagnostic DTO serve transform consumers;
+ *   emitted files belong to the compile result instead of a mixed payload.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The payload exposes actual transformed source, without treating expected
+ *   emitted answers as a replacement for the transform result.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Separate paragraphs identify the envelope and source stage; members explain
+ *   optional diagnostics, following the documentation skill's clarity guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscTransformResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscTransformResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscTransformResult is a data interface and coordinates no shared or repeated computation.
  */
 export interface ITtscTransformResult {
+    /** Present when the native transform includes diagnostic messages. */
     diagnostics?: ITtscDiagnostic[];
+    /** Post-transform source text keyed by source-file paths. */
     typescript: Record<string, string>;
 }

package/lib/src/structures/ITtscTypeAtPositionResult.d.ts

@@ -1,5 +1,22 @@
 import type { ITtscTypeInfo } from "./ITtscTypeInfo";
-/** Payload inside `ITtscResult.result` for `getTypeAtPosition`. */
+/**
+ * Payload inside `ITtscResult.result` for `getTypeAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A nullable type mirrors the native optional semantic result, separately from
+ *   the error code carried by the enclosing request envelope.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The nullable type field carries the semantic result without conflating it
+ *   with request failure or adding a parallel state discriminator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No universal any/error type is fabricated for positions without type semantics.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc identifies the endpoint and meaningful null state, following
+ *   the documentation skill's guidance for consumer-facing context.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscTypeAtPositionResult is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscTypeAtPositionResult is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscTypeAtPositionResult is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscTypeAtPositionResult {
     /** `null` when no touching token has a type. */
     type: ITtscTypeInfo | null;

package/lib/src/structures/ITtscTypeInfo.d.ts

@@ -1,4 +1,22 @@
-/** Type shape returned by `getTypeAtPosition`. */
+/**
+ * Type shape returned by `getTypeAtPosition`.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Printed text and native flag bits project the checker result through JSON
+ *   without exposing Go checker objects or an incomplete parallel type model.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Printed text and native flags provide presentation and classification in a
+ *   small value; structural compiler types remain owned by the native checker.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   TypeToString is the presentation authority; the consumer need not infer
+ *   a type from source spelling or a manually maintained flag lookup.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Member JSDoc names the native printing API and flag provenance, following
+ *   the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscTypeInfo is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscTypeInfo is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscTypeInfo is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscTypeInfo {
     /** Printed type, equivalent to TypeScript's `TypeToString(t)`. */
     text: string;

package/lib/src/structures/ITtscVersion.d.ts

@@ -1,9 +1,36 @@
-/** Build metadata embedded in the wasm by the Go linker at compile time. */
+/**
+ * Build and runtime metadata returned synchronously by the wasm.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   String fields match jsVersion's linker metadata and runtime queries; the
+ *   API can report an unversioned development binary without guessing a release.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Link-time release metadata and runtime target/toolchain identity remain
+ *   explicit fields, without a version-parsing or environment-inference layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Target and toolchain identity come from the binary rather than the browser's
+ *   platform or a consumer-specific version constant.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Members distinguish release metadata from Go runtime/target identity,
+ *   following the documentation skill's concrete context guidance.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ITtscVersion is a data interface and acquires no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ITtscVersion is a data interface and chooses no algorithm or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ITtscVersion is a data interface and coordinates no shared or repeated computation.
+ */
 export interface ITtscVersion {
+    /** Linker-supplied release version, or the development placeholder. */
     version: string;
+    /** Linker-supplied source revision, or the development placeholder. */
     commit: string;
+    /**
+     * Linker-supplied date, or unknown for an unannotated build. The base binary
+     * stamps the date of its source commit rather than the time it was built.
+     */
     date: string;
+    /** Go runtime's toolchain version. */
     go: string;
+    /** Binary target OS, js for the browser build. */
     goos: string;
+    /** Binary target architecture, wasm for the browser build. */
     goarch: string;
 }