@ttsc/playground 0.30.4 → 0.31.0

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

@@ -4,6 +4,11 @@
  * verbs `createWorkerCompiler` calls by default; sites that wire additional
  * plugins can extend this interface via TypeScript declaration merging or pass
  * a richer shape through `[key: string]: boolean | undefined`.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional boolean flags distinguish default integration behavior from explicit disabling; the index signature permits additional boolean site flags.
+ * @evidence contracts/common.md#clear-and-simple-design Per-call flags stay independent of factory plugin registration and UI labels.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Extensible keys pass through the declared option boundary instead of adding site-specific dispatcher branches.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains extension, default enablement and forwarding, with documentation-skill paragraphs and member spacing.
  */
 export interface ITransformOptions {
     /** Enable the typia transform plugin. Defaults to true. */

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

@@ -1,5 +1,12 @@
 import type { IMemFSHost } from "@ttsc/wasm";
-/** Options for the typia integration of {@link createWorkerCompiler}. */
+/**
+ * Options for the typia integration of {@link createWorkerCompiler}.
+ *
+ * @evidence contracts/common.md#principled-implementation Host registration id, transform module and source mounting callback represent the three distinct integration inputs.
+ * @evidence contracts/common.md#clear-and-simple-design Typia-specific settings are nested away from runtime boot and per-call enablement.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Default identities are supported typia configuration and remain explicitly replaceable by the site.
+ * @evidence contracts/common.md#meaningful-documentation Members explain host identity, transform module and forwarded virtual work directory, with documentation-skill paragraphs and spacing.
+ */
 export interface ITypiaPluginConfig {
     /** Plugin id registered with `host.Expose` (default: `"typia"`). */
     name?: string;
@@ -9,11 +16,22 @@ export interface ITypiaPluginConfig {
      */
     transformModule?: string;
     /**
-     * Optional hook to mount typia source files into the MemFS during boot. The
-     * site fetches its pre-built typia pack and writes it under
-     * `<workDir>/node_modules/`. `workDir` is forwarded from
-     * `createWorkerCompiler` so the mount can honor a non-default project root
-     * without the site rewiring the URL.
+     * Optional hook to mount typia source files into the MemFS once the wasm
+     * runtime is ready, before the first request runs. The site fetches its
+     * pre-built typia pack and writes it under `<workDir>/node_modules/`. A
+     * rejected mount is retried by the next request without starting another
+     * runtime. `workDir` is forwarded from `createWorkerCompiler` so the mount
+     * can honor a non-default project root without the site rewiring the URL.
      */
-    mount?: (host: IMemFSHost, workDir: string) => Promise<void>;
+    mount?: TypiaSourceMount;
 }
+/**
+ * Mount typia sources into the live virtual host after boot at the actual work
+ * directory.
+ *
+ * @evidence contracts/common.md#principled-implementation Host and workDir identify the filesystem and project root that compilation actually uses.
+ * @evidence contracts/common.md#clear-and-simple-design One asynchronous mount hook leaves boot and serial compilation with the worker factory.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Mounting uses IMemFSHost without patching compiler internals or guessing the project root.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names timing, filesystem and directory ownership before the separated tags.
+ */
+export type TypiaSourceMount = (host: IMemFSHost, workDir: string) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/playground",
-  "version": "0.30.4",
+  "version": "0.31.0",
   "description": "Reusable React + Web Worker scaffolding for in-browser ttsc playgrounds built on @ttsc/wasm.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",
@@ -39,9 +39,10 @@
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
     "tgrid": "^1.0.3",
-    "@ttsc/wasm": "^0.30.4"
+    "@ttsc/wasm": "^0.31.0"
   },
   "devDependencies": {
+    "@wrtnlabs/evidence": "^0.3.1",
     "@monaco-editor/react": "^4.6.0",
     "@types/semver": "^7.7.1",
     "@types/node": "^25.3.0",
@@ -52,7 +53,7 @@
     "rimraf": "^6.1.2",
     "tgrid": "^1.0.3",
     "typescript": "^7.0.2",
-    "@ttsc/wasm": "^0.30.4"
+    "@ttsc/wasm": "^0.31.0"
   },
   "keywords": [
     "ttsc",
@@ -63,6 +64,7 @@
     "react"
   ],
   "scripts": {
-    "build": "rimraf lib && tsc -p ."
+    "build": "rimraf lib && tsc -p .",
+    "evidence": "evidence"
   }
 }

package/src/compiler/buildTsconfigJSON.ts

@@ -7,6 +7,11 @@ import { DEFAULT_PLAYGROUND_COMPILER_OPTIONS } from "./DEFAULT_PLAYGROUND_COMPIL
  * `buildTsconfigJSON` is deliberately conservative — it returns a string the
  * caller writes to MemFS as-is, so there's no schema validation here. Bad
  * compiler options surface as wasm-side errors on the next build call.
+ *
+ * @evidence contracts/common.md#principled-implementation Object spread applies documented default-then-caller precedence and JSON.stringify emits the compiler's JSON input; compiler validation remains with the compiler.
+ * @evidence contracts/common.md#clear-and-simple-design This operation only serializes configuration; the caller owns virtual writes and execution.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Defaults are supported project settings and caller overrides remain explicit, without fixture-dependent branches.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains serialization ownership and validation timing in separate paragraphs under the documentation skill.
  */
 export function buildTsconfigJSON(options: IBuildTsconfigOptions): string {
   return JSON.stringify({

package/src/compiler/createTypiaSourcePackMount.ts

@@ -7,9 +7,15 @@ import { installTypiaSourcePack } from "./installTypiaSourcePack";
  * Build a `mount` callback for the `typiaPlugin` config of
  * {@link createWorkerCompiler}.
  *
- * The returned function fetches the pack once (cached per URL by
- * {@link loadTypiaSourcePack}) and writes every entry to the MemFS the first
- * time it is invoked on a given host.
+ * The returned function shares loading by URL and fetch function identity
+ * through {@link loadTypiaSourcePack}, then writes every entry to the MemFS on
+ * each invocation. Network records are cached, but mounting repeats so a caller
+ * can restore files removed from the virtual host.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit mountRoot overrides the actual worker workDir; absent both, installation uses its documented virtual root.
+ * @evidence contracts/common.md#clear-and-simple-design One adapter derives the root and delegates transport and writes to their owning operations.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The optional workDir preserves the supported single-argument callback while supplied project roots are honored instead of patched with fixed paths.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes cached loading from repeated mounting and explains callback compatibility, following documentation-skill paragraph separation.
  */
 export function createTypiaSourcePackMount(
   options: IInstallTypiaSourcePackOptions,

package/src/compiler/createWorkerCompiler.ts

@@ -37,6 +37,11 @@ import { createWorkerCompilerService } from "./internal/createWorkerCompilerServ
  * };
  * void main();
  * ```
+ *
+ * @evidence contracts/common.md#principled-implementation The wrapper supplies the real WASM boot and result parser to the same typed service core exposed over tgrid.
+ * @evidence contracts/common.md#clear-and-simple-design Runtime binding stays in this thin factory while pipeline state and serialization remain in the service core.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Dependency injection is a supported binding seam, without replacement of foreign APIs or test-only production paths.
+ * @evidence contracts/common.md#meaningful-documentation Native JSDoc demonstrates WorkerServer registration and required runtime identity, with descriptive text separated from tags under the documentation skill.
  */
 export function createWorkerCompiler(
   options: ICreateWorkerCompilerOptions,

package/src/compiler/installDependenciesIntoMemFS.ts

@@ -11,6 +11,11 @@ import { normalizeNodeModulePath } from "./normalizeNodeModulePath";
  * `ICompilerService`. The dependency installer (UI side) feeds keys like
  * `node_modules/uuid/dist/index.js`; we normalize, sanity-check, and copy each
  * entry under the project root.
+ *
+ * @evidence contracts/common.md#principled-implementation Every file passes the node_modules-relative path gate before virtual writes; count reports accepted writes and metadata remains the caller's submitted list.
+ * @evidence contracts/common.md#clear-and-simple-design Mounting is one loop with path policy delegated to normalizeNodeModulePath and no registry-resolution responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Malformed paths are uniformly skipped according to the declared mounting contract, without package-specific exemptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines input namespace, project-root mapping and consumer ownership, following documentation-skill paragraphs.
  */
 export function installDependenciesIntoMemFS(
   host: IMemFSHost,

package/src/compiler/installTypiaSourcePack.ts

@@ -8,8 +8,13 @@ import { loadTypiaSourcePack } from "./loadTypiaSourcePack";
  * wasm-side compiler can resolve `import typia, { tags } from "typia"` against
  * the same code the published package uses.
  *
- * Idempotent on the same host (re-writing the same paths is a no-op for the
- * MemFS implementation).
+ * Repeated calls write the same loaded records again; this restores any entries
+ * the caller removed from the virtual host and replaces values at pack paths.
+ *
+ * @evidence contracts/common.md#principled-implementation Source-pack entries are written under the selected virtual mount root after the shared transport completes; the pack is a site-produced trusted record map.
+ * @evidence contracts/common.md#clear-and-simple-design Loading is delegated and this operation owns only root creation and entry writes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The caller supplies the pack URL and root; no consumer or fixture determines which source contents are mounted.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains resolution purpose and repeated-write behavior without claiming MemFS suppresses writes, following documentation-skill paragraphs.
  */
 export async function installTypiaSourcePack(
   host: IMemFSHost,

package/src/compiler/internal/createWorkerCompilerService.ts

@@ -36,9 +36,31 @@ import { safeParseTypiaTransform } from "./safeParseTypiaTransform";
  * `createWorkerCompiler` binds the real implementations; tests bind fakes that
  * resolve a synthetic `IBootResult` so the plugin-envelope handling can be
  * verified without a real WASM boot.
+ *
+ * @evidence contracts/common.md#principled-implementation Boot and generic envelope parsing retain the WASM host signatures and null parse outcome needed by the service.
+ * @evidence contracts/common.md#clear-and-simple-design A two-collaborator record isolates runtime binding from pipeline control flow.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Collaborators are explicit production dependencies, not global replacements or fixture-specific dispatch.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain runtime binding and the injection purpose under the documentation skill.
  */
 export interface IWorkerCompilerDeps {
+  /**
+   * Start the configured WASM runtime and return its ready host and API.
+   *
+   * @evidence contracts/common.md#principled-implementation The host's typed options and ready result preserve runtime identity and boot failure semantics.
+   * @evidence contracts/common.md#clear-and-simple-design This dependency owns runtime startup while the service owns mounting and request serialization.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Injection uses the declared host API rather than replacing runtime globals.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states readiness and ownership with tag separation under the documentation skill.
+   */
   bootTtsc: (options: IBootTtscOptions) => Promise<IBootResult>;
+
+  /**
+   * Decode one host envelope; null denotes absent or unusable payload.
+   *
+   * @evidence contracts/common.md#principled-implementation The generic parser maps the typed host envelope to the requested payload shape while exposing parse failure as null.
+   * @evidence contracts/common.md#clear-and-simple-design Decoding stays distinct from exit-code interpretation in the service.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Null remains failure information and does not fabricate a successful empty compile result.
+   * @evidence contracts/common.md#meaningful-documentation Native prose defines null and decoding responsibility, separated from tags under the documentation skill.
+   */
   parseResult: <T>(result: ITtscResult) => T | null;
 }
 
@@ -48,6 +70,16 @@ type ITransformOutcome = { ok: true } | { ok: false; message: string };
 /**
  * Dependency-injected worker `ICompilerService` factory. See
  * `createWorkerCompiler` for the public entry documentation.
+ *
+ * Runtime boot and source mounting have separate retry state. Requests
+ * serialize every mutation of the shared virtual project; configured transform
+ * or lint failures remain visible instead of yielding untransformed or clean
+ * results.
+ *
+ * @evidence contracts/common.md#principled-implementation A promise chain orders virtual-file mutations; transform envelopes are validated before writes, and compile and lint outcomes preserve producer failure semantics. Post-start boot rejection remains terminal because an existing Go runtime cannot be replaced inside its Worker.
+ * @evidence contracts/common.md#clear-and-simple-design Boot, mounting, project writes and result interpretation are local responsibilities behind one RPC factory; ESM and CommonJS lanes share the build pipeline.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Retry is limited to pre-runtime boot or source mounting; failed configured plugins never silently fall through to successful untransformed emit or a clean lint list.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state serialization and retry boundaries; helper comments explain plugin-envelope failures and the runtime replacement reason under the documentation skill.
  */
 export function createWorkerCompilerService(
   deps: IWorkerCompilerDeps,
@@ -69,12 +101,23 @@ export function createWorkerCompilerService(
 
   // tsconfig variants. ESM for the "Compiled JS" preview lane, CommonJS for
   // the bundle/Execute lane (whose `new Function` driver expects CJS).
-  const tsconfigPlugins = typiaPlugin
-    ? [{ transform: typiaTransformModule }]
+  //
+  // The typia entry is appended after the site's own `plugins` entries, as the
+  // option documents, so enabling typia never discards a site-provided plugin.
+  const siteCompilerOptions = options.extraCompilerOptions ?? {};
+  const sitePlugins: unknown = siteCompilerOptions.plugins;
+  const extraPlugins: unknown[] = Array.isArray(sitePlugins)
+    ? sitePlugins.filter(
+        (entry) =>
+          (entry as { transform?: unknown } | null)?.transform !==
+          typiaTransformModule,
+      )
     : [];
   const extraCompilerOptions = {
-    ...(options.extraCompilerOptions ?? {}),
-    ...(tsconfigPlugins.length > 0 ? { plugins: tsconfigPlugins } : {}),
+    ...siteCompilerOptions,
+    ...(typiaPlugin
+      ? { plugins: [...extraPlugins, { transform: typiaTransformModule }] }
+      : {}),
   };
   const tsconfigESM = buildTsconfigJSON({
     module: "ESNext",

package/src/compiler/internal/joinUnder.ts

@@ -1,6 +1,11 @@
 /**
  * Join a relative path under a base directory, ignoring base when `rel` is
  * absolute.
+ *
+ * @evidence contracts/common.md#principled-implementation Absolute virtual paths retain their meaning and relative paths receive the configured virtual base; this helper is not a confinement check.
+ * @evidence contracts/common.md#clear-and-simple-design A narrow virtual join keeps source mapping independent of host filesystem APIs.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Absolute paths are a supported input form rather than a workaround for a particular package.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states absolute precedence, with tag separation following the documentation skill.
  */
 export function joinUnder(base: string, rel: string): string {
   if (rel.startsWith("/")) return rel;

package/src/compiler/internal/parseLintDiagnostics.ts

@@ -15,6 +15,11 @@ const ANSI_REGEXP = /\x1b\[[0-9;]*m/g;
 /**
  * Parse the lint plugin's stderr (tsgo-style pretty diagnostics) into the
  * playground's normalized diagnostic shape.
+ *
+ * @evidence contracts/common.md#principled-implementation The parser recognizes the supported pretty-diagnostic grammar after removing actual ANSI SGR escapes and carries its one-based line and column unchanged into UI records.
+ * @evidence contracts/common.md#clear-and-simple-design Matching and record construction stay in one pass; token-span inference remains a local helper rather than a second diagnostic protocol.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown lines are omitted as non-diagnostics; the owning pipeline separately reports plugin failure instead of treating every empty parse as success.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies producer format and normalization responsibility; nearby comments explain ANSI matching reasons under the documentation skill.
  */
 export function parseLintDiagnostics(
   stderr: string,
@@ -22,6 +27,7 @@ export function parseLintDiagnostics(
 ): ICompilerService.IDiagnostic[] {
   const stripped = stderr.replace(ANSI_REGEXP, "");
   const lines = stripped.split(/\r?\n/);
+  const sourceLines = source.split(/\r?\n/);
   const out: ICompilerService.IDiagnostic[] = [];
   for (const line of lines) {
     const m = line.match(LINT_LINE_REGEXP);
@@ -33,7 +39,7 @@ export function parseLintDiagnostics(
     out.push({
       line: lineNum,
       column: colNum,
-      length: lengthOfTokenAt(source, lineNum, colNum) ?? 1,
+      length: lengthOfTokenAt(sourceLines, lineNum, colNum) ?? 1,
       severity: sev === "warning" ? "warning" : "error",
       message: rule ? `[${rule}] ${message ?? ""}` : (message ?? ""),
       code: `TS${codeStr ?? ""}`,
@@ -47,11 +53,10 @@ export function parseLintDiagnostics(
  * `column`) in `source`. Falls back to 1 when no token is found.
  */
 function lengthOfTokenAt(
-  source: string,
+  lines: readonly string[],
   line: number,
   column: number,
 ): number | null {
-  const lines = source.split(/\r?\n/);
   if (line < 1 || line > lines.length) return null;
   const text = lines[line - 1] ?? "";
   const start = Math.max(0, column - 1);

package/src/compiler/internal/safeParseTypiaTransform.ts

@@ -1,4 +1,12 @@
-/** Shape of the typia transform plugin's stdout JSON payload. */
+/**
+ * Typia transform stdout envelope; typescript maps virtual paths to source
+ * text.
+ *
+ * @evidence contracts/common.md#principled-implementation A string-valued source map expresses files the host can write; diagnostics are intentionally opaque because this lane does not consume them.
+ * @evidence contracts/common.md#clear-and-simple-design The narrow envelope separates transform payload decoding from compiler result parsing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The map models the registered transform protocol rather than guessed output for a particular source.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines path and text meaning with tag separation under the documentation skill.
+ */
 export interface ITypiaTransformOutput {
   diagnostics?: unknown;
   typescript: Record<string, string>;
@@ -8,13 +16,28 @@ export interface ITypiaTransformOutput {
  * Parse the typia transform plugin's stdout into the expected shape. Returns
  * null on any parse / shape mismatch — the caller treats null as "transform
  * produced no usable output".
+ *
+ * @evidence contracts/common.md#principled-implementation JSON decoding and a non-array object containing only string source values establish the host-write precondition; malformed payloads return null.
+ * @evidence contracts/common.md#clear-and-simple-design One decoder validates the source map before the service mutates MemFS.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Rejected payloads remain failures instead of coercing unknown values into source text.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains null's failure meaning and decoding boundary, separated from tags under the documentation skill.
  */
 export function safeParseTypiaTransform(
   text: string,
 ): ITypiaTransformOutput | null {
   try {
     const parsed = JSON.parse(text) as ITypiaTransformOutput;
-    if (parsed && typeof parsed === "object" && parsed.typescript) {
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed) &&
+      parsed.typescript &&
+      typeof parsed.typescript === "object" &&
+      !Array.isArray(parsed.typescript) &&
+      Object.values(parsed.typescript).every(
+        (value) => typeof value === "string",
+      )
+    ) {
       return parsed;
     }
     return null;

package/src/compiler/lineColumnOf.ts

@@ -1,14 +1,30 @@
-/** Compute 1-based line/column for a 0-based char offset into `source`. */
+/**
+ * Compute one-based line and column from a zero-based UTF-16 source offset.
+ * Missing or negative offsets point to the beginning; offsets past EOF clamp.
+ *
+ * @evidence contracts/common.md#principled-implementation ECMAScript line terminators advance the line, CRLF counts once, and columns count JavaScript UTF-16 units.
+ * @evidence contracts/common.md#clear-and-simple-design A stateless coordinate helper keeps source-location policy separate from diagnostic mapping and rendering.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Beginning and EOF behavior are general coordinate defaults rather than source-specific exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states bases, units and boundary behavior, separated from tags under the documentation skill.
+ */
 export function lineColumnOf(
   source: string,
   start: number | undefined,
 ): { line: number; column: number } {
-  if (typeof start !== "number" || start < 0) return { line: 1, column: 1 };
-  const slice = source.slice(0, Math.min(start, source.length));
-  const newlines = slice.match(/\n/g);
-  const line = newlines ? newlines.length + 1 : 1;
-  const lastNewline = slice.lastIndexOf("\n");
-  const column =
-    lastNewline === -1 ? slice.length + 1 : slice.length - lastNewline;
+  if (typeof start !== "number" || Number.isNaN(start) || start < 0)
+    return { line: 1, column: 1 };
+  const end = Math.min(Math.trunc(start), source.length);
+  let line = 1;
+  let lastNewline = -1;
+  for (let index = 0; index < end; ++index) {
+    const code = source.charCodeAt(index);
+    if (code === 13 || code === 10 || code === 0x2028 || code === 0x2029) {
+      if (code === 13 && source.charCodeAt(index + 1) === 10 && index + 1 < end)
+        ++index;
+      ++line;
+      lastNewline = index;
+    }
+  }
+  const column = end - lastNewline;
   return { line, column };
 }

package/src/compiler/loadTypiaSourcePack.ts

@@ -15,33 +15,65 @@ interface SourcePackCancellation {
   dispose: () => void;
 }
 
-const packCache = new Map<string, SourcePackEntry>();
+const packCaches = new WeakMap<
+  NonNullable<IInstallTypiaSourcePackOptions["fetch"]>,
+  Map<string, SourcePackEntry>
+>();
 
 /**
- * Fetch the typia source pack JSON once per URL.
+ * Fetch the typia source pack JSON once per URL and transport identity.
  *
  * Concurrent callers share one load. A caller abort cancels that shared
  * attempt; rejection removes it from the cache so the next call retries from
  * scratch. Nothing else ends the load: how long a fetch takes belongs to the
  * network, not to a number chosen here.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The source-pack loader uses fetch/AbortController and Promise sharing,
+ *   with an explicit fetch injection seam for the same transport contract. It
+ *   supplies source records to the existing mounting operation rather than
+ *   coupling network loading to compiler execution.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One transport-specific URL map owns attempt sharing; cancellation helpers
+ *   keep event ownership separate from response decoding and source mounting.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The site supplies the URL and transport; no package name, test case or
+ *   fixed deadline decides success. The injected transport leaves global fetch
+ *   intact. Rejection evicts only this attempt, preserving the real failure
+ *   instead of inventing a successful empty source pack.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains the once-per-URL purpose, shared cancellation, rejection
+ *   eviction and why an arbitrary timeout is not the network policy. Purpose
+ *   and reasons use separate native paragraphs under the documentation skill;
+ *   IInstallTypiaSourcePackOptions owns option documentation.
  */
 export function loadTypiaSourcePack(
   options: IInstallTypiaSourcePackOptions,
 ): Promise<Record<string, string>> {
-  const cached = packCache.get(options.url);
-  if (cached) {
-    attachSourcePackCancellation(cached, options.signal);
-    return cached.promise;
-  }
-
-  const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  const fetchImpl = options.fetch ?? globalThis.fetch;
   if (!fetchImpl) {
     throw new Error(
       "loadTypiaSourcePack: no fetch implementation available in this environment.",
     );
   }
 
+  let packCache = packCaches.get(fetchImpl);
+  if (!packCache) {
+    packCache = new Map();
+    packCaches.set(fetchImpl, packCache);
+  }
+  const cache = packCache;
+  const cached = cache.get(options.url);
+  if (cached) {
+    attachSourcePackCancellation(cached, options.signal);
+    return cached.promise;
+  }
+
   const url = options.url;
+  const fetchPack = options.fetch ? fetchImpl : fetchImpl.bind(globalThis);
   const controller = new AbortController();
   let phase = `fetching ${url}`;
   const cancellation = createSourcePackCancellation(
@@ -51,7 +83,7 @@ export function loadTypiaSourcePack(
   let entry!: SourcePackEntry;
   const promise = (async () => {
     const response = await raceSourcePackCancellation(
-      fetchImpl(url, { signal: controller.signal }),
+      fetchPack(url, { signal: controller.signal }),
       cancellation.promise,
       controller.signal,
       () => phase,
@@ -63,21 +95,32 @@ export function loadTypiaSourcePack(
     }
 
     phase = `reading JSON from ${url}`;
-    return (await raceSourcePackCancellation(
+    const pack: unknown = await raceSourcePackCancellation(
       response.json(),
       cancellation.promise,
       controller.signal,
       () => phase,
-    )) as Record<string, string>;
+    );
+    if (
+      !pack ||
+      typeof pack !== "object" ||
+      Array.isArray(pack) ||
+      !Object.values(pack).every((value) => typeof value === "string")
+    ) {
+      throw new Error(
+        "loadTypiaSourcePack: expected a source-text record map.",
+      );
+    }
+    return pack as Record<string, string>;
   })()
     .catch((error) => {
-      if (packCache.get(url) === entry) packCache.delete(url);
+      if (cache.get(url) === entry) cache.delete(url);
       throw error;
     })
     .finally(cancellation.dispose);
 
   entry = { controller, promise };
-  packCache.set(url, entry);
+  cache.set(url, entry);
   attachSourcePackCancellation(entry, options.signal);
   return promise;
 }

package/src/compiler/mapDiagnostic.ts

@@ -6,21 +6,81 @@ import { lineColumnOf } from "./lineColumnOf";
 /**
  * Convert a `@ttsc/wasm` diagnostic into the playground's normalized shape.
  *
- * Falls back to computing line/column from the source text when the wasm
- * diagnostic did not carry them (some plugin emitters drop them).
+ * Native positions and spans count UTF-8 bytes; the editor counts UTF-16 units.
+ * Source text converts that boundary, including optional coordinates.
+ *
+ * @evidence contracts/common.md#principled-implementation Native byte offsets and spans are converted against the same source into UTF-16 editor coordinates; optional line/byte-column metadata supplies the start only when the absolute offset is absent.
+ * @evidence contracts/common.md#clear-and-simple-design A single mapping keeps WASM diagnostic fields and UI conventions separate from rendering.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Fallback is based on omitted producer metadata, not special casing a diagnostic code or source fixture.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains producer-to-UI conversion and fallback purpose, following documentation-skill paragraph separation.
  */
 export function mapDiagnostic(
   diag: NonNullable<ITtscCompileResult["diagnostics"]>[number],
   source: string,
 ): ICompilerService.IDiagnostic {
-  const fallback = lineColumnOf(source, diag.start);
+  const start =
+    typeof diag.start === "number" &&
+    Number.isFinite(diag.start) &&
+    diag.start >= 0
+      ? utf16OffsetOfBytes(source, diag.start)
+      : optionalStart(source, diag.line, diag.character);
+  const location = lineColumnOf(source, start);
+  const byteLength =
+    typeof diag.length === "number" && Number.isFinite(diag.length)
+      ? Math.max(0, Math.trunc(diag.length))
+      : 0;
+  const end = utf16OffsetOfBytes(source, byteLength, start);
   return {
-    line: diag.line && diag.line > 0 ? diag.line : fallback.line,
-    column:
-      diag.character && diag.character > 0 ? diag.character : fallback.column,
-    length: typeof diag.length === "number" ? diag.length : 1,
+    line: location.line,
+    column: location.column,
+    length: Math.max(1, end - start),
     severity: diag.category === "warning" ? "warning" : "error",
     message: diag.messageText,
     code: typeof diag.code === "number" ? `TS${diag.code}` : String(diag.code),
   };
 }
+
+/** Convert a UTF-8 byte boundary to its JavaScript string offset. */
+function utf16OffsetOfBytes(source: string, bytes: number, start = 0): number {
+  let offset = start;
+  let consumed = 0;
+  while (offset < source.length && consumed < bytes) {
+    const code = source.codePointAt(offset)!;
+    const width = code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+    if (consumed + width > bytes) break;
+    consumed += width;
+    offset += code > 0xffff ? 2 : 1;
+  }
+  return offset;
+}
+
+/** Optional native line and byte-column metadata uses the same source domain. */
+function optionalStart(
+  source: string,
+  line: number | undefined,
+  character: number | undefined,
+): number {
+  let start = 0;
+  const targetLine =
+    typeof line === "number" && Number.isFinite(line)
+      ? Math.max(1, Math.trunc(line))
+      : 1;
+  for (
+    let current = 1;
+    current < targetLine && start < source.length;
+    ++current
+  ) {
+    while (
+      start < source.length &&
+      ![10, 13, 0x2028, 0x2029].includes(source.charCodeAt(start))
+    )
+      ++start;
+    const code = source.charCodeAt(start++);
+    if (code === 13 && source.charCodeAt(start) === 10) ++start;
+  }
+  const column =
+    typeof character === "number" && Number.isFinite(character)
+      ? Math.max(0, Math.trunc(character) - 1)
+      : 0;
+  return Math.min(source.length, utf16OffsetOfBytes(source, column, start));
+}

package/src/compiler/normalizeError.ts

@@ -1,4 +1,12 @@
-/** Best-effort error normalization for tgrid transport. */
+/**
+ * Normalize native errors to enumerable fields for tgrid transport; preserve
+ * message-bearing records and stringify other thrown values.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit Error field copying preserves non-enumerable message and stack while carrying the terminal-runtime string code across RPC.
+ * @evidence contracts/common.md#clear-and-simple-design One normalization boundary leaves rendering and recovery classification to their consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapper carries actual errors without converting rejection into fabricated compiler success.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states copying and preservation policies, separated from tags under the documentation skill.
+ */
 export function normalizeError(error: unknown): unknown {
   if (error instanceof Error) {
     const normalized: {

package/src/compiler/normalizeNodeModulePath.ts

@@ -4,6 +4,11 @@
  *
  * Returns `null` for paths that don't match the expected shape — the caller
  * skips those entries instead of writing them to the MemFS.
+ *
+ * @evidence contracts/common.md#principled-implementation Separator normalization establishes the virtual namespace, prefix checking restricts writes to node_modules and rejecting parent segments prevents root escape.
+ * @evidence contracts/common.md#clear-and-simple-design One path gate returns a normalized key or null; callers own writes and rejection policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The same structural checks apply to every package entry without allowlisting consumers.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain accepted spelling, confinement and null meaning under the documentation skill.
  */
 export function normalizeNodeModulePath(path: string): string | null {
   const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");