@ttsc/playground 0.14.0-dev.20250530.1

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@ttsc/playground",
+  "version": "0.14.0-dev.20250530.1",
+  "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",
+  "files": [
+    "lib",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/src/index.d.ts",
+      "default": "./lib/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/samchon/ttsc"
+  },
+  "author": "Jeongho Nam",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/samchon/ttsc/issues"
+  },
+  "homepage": "https://ttsc.dev",
+  "dependencies": {
+    "lz-string": "^1.5.0"
+  },
+  "peerDependencies": {
+    "@monaco-editor/react": "^4.6.0",
+    "monaco-editor": "^0.52.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tgrid": "^1.0.3",
+    "@ttsc/wasm": "^0.14.0-dev.20250530.1"
+  },
+  "devDependencies": {
+    "@monaco-editor/react": "^4.6.0",
+    "@types/node": "^25.3.0",
+    "@types/react": "^18.3.1",
+    "@typescript/native-preview": "7.0.0-dev.20260527.2",
+    "monaco-editor": "^0.52.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.1.2",
+    "tgrid": "^1.0.3",
+    "@ttsc/wasm": "^0.14.0-dev.20250530.1"
+  },
+  "keywords": [
+    "ttsc",
+    "playground",
+    "typescript",
+    "browser",
+    "wasm",
+    "react"
+  ],
+  "scripts": {
+    "build": "rimraf lib && tsgo -p ."
+  }
+}

package/src/compiler/DEFAULT_ENTRY_FILE.ts

@@ -0,0 +1,2 @@
+/** Default entry source file inside the work dir. */
+export const DEFAULT_ENTRY_FILE = "src/playground.ts";

package/src/compiler/DEFAULT_LINT_PLUGIN_NAME.ts

@@ -0,0 +1,5 @@
+/**
+ * Default plugin id for the `@ttsc/lint` check verb. Override via the
+ * `lintPlugin.name` option of {@link createWorkerCompiler}.
+ */
+export const DEFAULT_LINT_PLUGIN_NAME = "@ttsc/lint";

package/src/compiler/DEFAULT_PLAYGROUND_COMPILER_OPTIONS.ts

@@ -0,0 +1,19 @@
+/**
+ * The compiler options every playground tsconfig opts into by default. Sites
+ * pass these straight to `buildTsconfigJSON`; consumer code that needs a tweak
+ * spreads the constant and overrides individual fields.
+ *
+ * `target` and `module` are TypeScript's numeric enum values (99 = ESNext, 199
+ * = NodeNext, …). They are spelled numerically here because the wasm doesn't
+ * run the TS configuration parser through a string→enum step before Go reads
+ * the JSON; passing the canonical numbers avoids version-drift.
+ */
+export const DEFAULT_PLAYGROUND_COMPILER_OPTIONS = {
+  target: 99,
+  esModuleInterop: true,
+  forceConsistentCasingInFileNames: true,
+  moduleResolution: 100,
+  strict: true,
+  skipLibCheck: true,
+  experimentalDecorators: true,
+} as const;

package/src/compiler/DEFAULT_TSCONFIG_PATH.ts

@@ -0,0 +1,2 @@
+/** Default tsconfig path inside the work dir. */
+export const DEFAULT_TSCONFIG_PATH = "tsconfig.json";

package/src/compiler/DEFAULT_TYPIA_PLUGIN_NAME.ts

@@ -0,0 +1,6 @@
+/**
+ * Default plugin id for the typia transformer. Sites that wire a renamed typia
+ * plugin override via the `typiaPlugin.name` option of
+ * {@link createWorkerCompiler}.
+ */
+export const DEFAULT_TYPIA_PLUGIN_NAME = "typia";

package/src/compiler/DEFAULT_WORK_DIR.ts

@@ -0,0 +1,2 @@
+/** Default in-MemFS project root mounted by {@link createWorkerCompiler}. */
+export const DEFAULT_WORK_DIR = "/work";

package/src/compiler/buildTsconfigJSON.ts

@@ -0,0 +1,22 @@
+import type { IBuildTsconfigOptions } from "../structures/IBuildTsconfigOptions";
+import { DEFAULT_PLAYGROUND_COMPILER_OPTIONS } from "./DEFAULT_PLAYGROUND_COMPILER_OPTIONS";
+
+/**
+ * Serialize a tsconfig JSON document the wasm-side compiler can consume.
+ *
+ * `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.
+ */
+export function buildTsconfigJSON(options: IBuildTsconfigOptions): string {
+  return JSON.stringify({
+    compilerOptions: {
+      ...DEFAULT_PLAYGROUND_COMPILER_OPTIONS,
+      module: options.module,
+      outDir: options.outDir ?? "dist",
+      rootDir: options.rootDir ?? "src",
+      ...(options.compilerOptions ?? {}),
+    },
+    include: options.include ?? ["src"],
+  });
+}

package/src/compiler/createTypiaSourcePackMount.ts

@@ -0,0 +1,32 @@
+import type { IMemFSHost } from "@ttsc/wasm";
+
+import type { IInstallTypiaSourcePackOptions } from "../structures/IInstallTypiaSourcePackOptions";
+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.
+ */
+export function createTypiaSourcePackMount(
+  options: IInstallTypiaSourcePackOptions,
+): (host: IMemFSHost, workDir?: string) => Promise<void> {
+  return async (host: IMemFSHost, workDir?: string) => {
+    // Honor the caller's workDir when the site did not pin mountRoot
+    // explicitly. Otherwise a `createWorkerCompiler({workDir: '/foo'})`
+    // would still mount typia under `/work/node_modules/` and tsgo would
+    // never resolve `typia` from the project root.
+    //
+    // `workDir` is intentionally optional so callers built against the
+    // previous single-arg signature (`mount(host)`) keep working — when
+    // both mountRoot and workDir are absent, installTypiaSourcePack falls
+    // back to its own default (`/work/node_modules`).
+    const mountRoot =
+      options.mountRoot ??
+      (workDir ? `${workDir.replace(/\/+$/, "")}/node_modules` : undefined);
+    await installTypiaSourcePack(host, { ...options, mountRoot });
+  };
+}

package/src/compiler/createWorkerCompiler.ts

@@ -0,0 +1,273 @@
+// Worker-side playground compiler factory.
+//
+// This module ships a ready-to-bind `ICompilerService` implementation. The
+// consumer's worker entry boots the wasm once, builds tsconfig variants for
+// the site's chosen module shape, registers the typia/lint plugin verbs (or
+// the site-provided overrides), and serializes every MemFS-mutating call onto
+// a single chain so concurrent compiles never corrupt each other.
+import {
+  type IBootResult,
+  type ITtscCompileResult,
+  bootTtsc,
+  parseResult,
+} from "@ttsc/wasm";
+
+import type { ICompilerService } from "../structures/ICompilerService";
+import type { ICreateWorkerCompilerOptions } from "../structures/ICreateWorkerCompilerOptions";
+import type { ITransformOptions } from "../structures/ITransformOptions";
+import { DEFAULT_ENTRY_FILE } from "./DEFAULT_ENTRY_FILE";
+import { DEFAULT_LINT_PLUGIN_NAME } from "./DEFAULT_LINT_PLUGIN_NAME";
+import { DEFAULT_TSCONFIG_PATH } from "./DEFAULT_TSCONFIG_PATH";
+import { DEFAULT_TYPIA_PLUGIN_NAME } from "./DEFAULT_TYPIA_PLUGIN_NAME";
+import { DEFAULT_WORK_DIR } from "./DEFAULT_WORK_DIR";
+import { buildTsconfigJSON } from "./buildTsconfigJSON";
+import { installDependenciesIntoMemFS } from "./installDependenciesIntoMemFS";
+import { joinUnder } from "./internal/joinUnder";
+import { parseLintDiagnostics } from "./internal/parseLintDiagnostics";
+import { safeParseTypiaTransform } from "./internal/safeParseTypiaTransform";
+import { mapDiagnostic } from "./mapDiagnostic";
+import { normalizeError } from "./normalizeError";
+import { pickEmittedJS } from "./pickEmittedJS";
+
+/**
+ * Build an `ICompilerService` ready to register with tgrid's `WorkerServer`.
+ *
+ * Usage in the worker entry:
+ *
+ * ```ts
+ * import { createWorkerCompiler } from "@ttsc/playground";
+ * import { WorkerServer } from "tgrid";
+ *
+ * const service = createWorkerCompiler({
+ *   wasmUrl: "/compiler/playground.wasm",
+ *   apiName: "ttscPlayground",
+ *   typiaPlugin: { mount: installTypiaPack },
+ * });
+ *
+ * const main = async () => {
+ *   const worker = new WorkerServer();
+ *   await worker.open(service);
+ * };
+ * void main();
+ * ```
+ */
+export function createWorkerCompiler(
+  options: ICreateWorkerCompilerOptions,
+): ICompilerService {
+  const workDir = options.workDir ?? DEFAULT_WORK_DIR;
+  const tsconfigPath = options.tsconfigPath ?? DEFAULT_TSCONFIG_PATH;
+  const entryFile = options.entryFile ?? DEFAULT_ENTRY_FILE;
+
+  const typiaPlugin =
+    options.typiaPlugin === false ? null : (options.typiaPlugin ?? {});
+  const typiaPluginName = typiaPlugin?.name ?? DEFAULT_TYPIA_PLUGIN_NAME;
+  const typiaTransformModule =
+    typiaPlugin?.transformModule ?? "typia/lib/transform";
+
+  const lintPlugin =
+    options.lintPlugin === false ? null : (options.lintPlugin ?? {});
+  const lintPluginName = lintPlugin?.name ?? DEFAULT_LINT_PLUGIN_NAME;
+
+  // 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 }]
+    : [];
+  const extraCompilerOptions = {
+    ...(options.extraCompilerOptions ?? {}),
+    ...(tsconfigPlugins.length > 0 ? { plugins: tsconfigPlugins } : {}),
+  };
+  const tsconfigESM = buildTsconfigJSON({
+    module: "ESNext",
+    compilerOptions: extraCompilerOptions,
+  });
+  const tsconfigCJS = buildTsconfigJSON({
+    module: "CommonJS",
+    compilerOptions: extraCompilerOptions,
+  });
+
+  // Cache the boot promise across calls. If the boot rejects we clear the
+  // cache so the next call retries — otherwise every later compile/bundle/
+  // lint would replay the same rejection forever (page reload required).
+  // Mirrors the createCompilerClient (UI-side) pattern.
+  let boot: Promise<IBootResult> | null = null;
+  function getBoot(): Promise<IBootResult> {
+    if (boot) return boot;
+    boot = (async () => {
+      const result = await bootTtsc({
+        wasmUrl: options.wasmUrl,
+        wasmExecUrl: options.wasmExecUrl,
+        apiName: options.apiName,
+      });
+      if (typiaPlugin?.mount) await typiaPlugin.mount(result.host, workDir);
+      return result;
+    })().catch((err) => {
+      boot = null;
+      throw err;
+    });
+    return boot;
+  }
+
+  // Serialize every MemFS-mutating call. tgrid queues incoming messages, but
+  // the wasm-side host runs them concurrently — a fast keystroke could
+  // interleave a bundle's tsconfig rewrite with a lint pass and corrupt
+  // either result. The chain keeps compile/bundle/lint linear.
+  let busy: Promise<unknown> = Promise.resolve();
+  const enqueue = <T>(fn: () => Promise<T>): Promise<T> => {
+    const next = busy.then(fn, fn);
+    busy = next.catch(() => {});
+    return next;
+  };
+
+  const projectFiles = (
+    source: string,
+    tsconfigText: string,
+  ): Record<string, string> => ({
+    [`${workDir}/${tsconfigPath}`]: tsconfigText,
+    [`${workDir}/${entryFile}`]: source,
+  });
+
+  const writeProject = (
+    host: IBootResult["host"],
+    files: Record<string, string>,
+  ): void => {
+    for (const [path, text] of Object.entries(files)) {
+      host.writeFile(path, text);
+    }
+  };
+
+  // Typia transform — run the registered typia plugin's `transform` verb,
+  // parse its JSON stdout, and write the rewritten TS back into MemFS so the
+  // subsequent `api.build` sees the post-transform text.
+  const applyTypiaTransform = async (
+    api: IBootResult["api"],
+    host: IBootResult["host"],
+  ): Promise<void> => {
+    if (!typiaPlugin) return;
+    try {
+      const raw = await api.plugin({
+        name: typiaPluginName,
+        command: "transform",
+        cwd: workDir,
+        tsconfig: tsconfigPath,
+        output: "ts",
+      });
+      if (!raw.stdout) return;
+      const transformed = safeParseTypiaTransform(raw.stdout);
+      if (!transformed) return;
+      for (const [rel, text] of Object.entries(transformed.typescript)) {
+        host.writeFile(joinUnder(workDir, rel), text);
+      }
+    } catch {
+      // Swallow plugin spawn / JSON parse failures so the user still sees the
+      // tsgo compile diagnostics from the subsequent build call. Real
+      // user-facing errors (e.g. typia rule violations) flow through the
+      // wasm-side diagnostics path.
+    }
+  };
+
+  const runBuildPipeline = async (
+    source: string,
+    runTypia: boolean,
+    tsconfigText: string,
+  ): Promise<ICompilerService.IResult> => {
+    try {
+      const { api, host } = await getBoot();
+      writeProject(host, projectFiles(source, tsconfigText));
+      if (runTypia) await applyTypiaTransform(api, host);
+      const raw = await api.build({
+        cwd: workDir,
+        tsconfig: tsconfigPath,
+      });
+      if (raw.code !== 0 && !raw.result) {
+        return {
+          type: "error",
+          target: "javascript",
+          value: {
+            message:
+              raw.stderr || "ttsc: build failed without a result payload",
+          },
+        };
+      }
+      const parsed = parseResult<ITtscCompileResult>(raw);
+      if (!parsed) {
+        return {
+          type: "error",
+          target: "javascript",
+          value: { message: "ttsc: result JSON could not be parsed" },
+        };
+      }
+      const diagnostics = (parsed.diagnostics ?? []).map((d) =>
+        mapDiagnostic(d, source),
+      );
+      const js = pickEmittedJS(parsed.output ?? {}, entryFile);
+      const errors = diagnostics.filter((d) => d.severity === "error");
+      if (errors.length > 0) {
+        return {
+          type: "failure",
+          target: "javascript",
+          value: js ?? "",
+          diagnostics,
+        };
+      }
+      return { type: "success", target: "javascript", value: js ?? "" };
+    } catch (error) {
+      return {
+        type: "error",
+        target: "javascript",
+        value: normalizeError(error),
+      };
+    }
+  };
+
+  // Lint pipeline. The lint plugin emits tsgo-style pretty diagnostics on
+  // stderr; we parse those lines back into IDiagnostic so the UI can render
+  // them in the Lint tab.
+  const runLintPipeline = async (
+    source: string,
+  ): Promise<ICompilerService.ILintResult> => {
+    if (!lintPlugin) return { diagnostics: [] };
+    try {
+      const { api, host } = await getBoot();
+      writeProject(host, projectFiles(source, tsconfigESM));
+      const raw = await api.plugin({
+        name: lintPluginName,
+        command: "check",
+        cwd: workDir,
+        tsconfig: tsconfigPath,
+      });
+      return { diagnostics: parseLintDiagnostics(raw.stderr, source) };
+    } catch {
+      return { diagnostics: [] };
+    }
+  };
+
+  return {
+    installDependencies: (props) =>
+      enqueue(async () => {
+        const { host } = await getBoot();
+        return installDependenciesIntoMemFS(host, workDir, props);
+      }),
+    compile: (props) =>
+      enqueue(() =>
+        runBuildPipeline(
+          props.source,
+          shouldRunTypia(props.options),
+          tsconfigESM,
+        ),
+      ),
+    bundle: (props) =>
+      enqueue(() =>
+        runBuildPipeline(
+          props.source,
+          shouldRunTypia(props.options),
+          tsconfigCJS,
+        ),
+      ),
+    lint: (props) => enqueue(() => runLintPipeline(props.source)),
+  };
+}
+
+function shouldRunTypia(options?: ITransformOptions): boolean {
+  return options?.typia !== false;
+}

package/src/compiler/installDependenciesIntoMemFS.ts

@@ -0,0 +1,28 @@
+import type { IMemFSHost } from "@ttsc/wasm";
+
+import type { ICompilerService } from "../structures/ICompilerService";
+import { normalizeNodeModulePath } from "./normalizeNodeModulePath";
+
+/**
+ * Mount external npm package files into the worker's MemFS under
+ * `<workDir>/node_modules/...`.
+ *
+ * Used by `createWorkerCompiler` to implement the `installDependencies` verb of
+ * `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.
+ */
+export function installDependenciesIntoMemFS(
+  host: IMemFSHost,
+  workDir: string,
+  props: ICompilerService.IInstallDependenciesProps,
+): ICompilerService.IInstallDependenciesResult {
+  let fileCount = 0;
+  for (const [rel, text] of Object.entries(props.files)) {
+    const normalized = normalizeNodeModulePath(rel);
+    if (!normalized) continue;
+    host.writeFile(`${workDir}/${normalized}`, text);
+    fileCount++;
+  }
+  return { installed: props.packages, fileCount };
+}

package/src/compiler/installTypiaSourcePack.ts

@@ -0,0 +1,24 @@
+import type { IMemFSHost } from "@ttsc/wasm";
+
+import type { IInstallTypiaSourcePackOptions } from "../structures/IInstallTypiaSourcePackOptions";
+import { loadTypiaSourcePack } from "./loadTypiaSourcePack";
+
+/**
+ * Mounts typia + @typia/* source trees into the in-browser MemFS so the
+ * 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).
+ */
+export async function installTypiaSourcePack(
+  host: IMemFSHost,
+  options: IInstallTypiaSourcePackOptions,
+): Promise<void> {
+  const mountRoot = options.mountRoot ?? "/work/node_modules";
+  const pack = await loadTypiaSourcePack(options);
+  host.mkdirp(mountRoot);
+  for (const [rel, content] of Object.entries(pack)) {
+    host.writeFile(`${mountRoot}/${rel}`, content);
+  }
+}

package/src/compiler/internal/joinUnder.ts

@@ -0,0 +1,8 @@
+/**
+ * Join a relative path under a base directory, ignoring base when `rel` is
+ * absolute.
+ */
+export function joinUnder(base: string, rel: string): string {
+  if (rel.startsWith("/")) return rel;
+  return `${base}/${rel}`;
+}

package/src/compiler/internal/parseLintDiagnostics.ts

@@ -0,0 +1,61 @@
+import type { ICompilerService } from "../../structures/ICompilerService";
+
+// Match `file:line:col - severity TS<code>: [rule-name] message` lines from
+// tsgo's pretty diagnostic renderer. ANSI color escapes are stripped first
+// so the matcher works on the exact text rendered in the Lint tab.
+const LINT_LINE_REGEXP =
+  /([^\s:]+):(\d+):(\d+)\s+-\s+(error|warning)\s+TS(\d+):\s+(?:\[([^\]]+)\]\s+)?(.*)$/;
+// Strip real ANSI SGR sequences, which always start with ESC (0x1b). The
+// leading ESC byte is required — `/\[[0-9;]*m/g` would also chew innocuous
+// substrings like "[m" or "[0;1m" inside diagnostic messages, and would
+// fail to actually strip the ESC bytes tsgo writes, leaving the
+// LINT_LINE_REGEXP unable to anchor on the filename column.
+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.
+ */
+export function parseLintDiagnostics(
+  stderr: string,
+  source: string,
+): ICompilerService.IDiagnostic[] {
+  const stripped = stderr.replace(ANSI_REGEXP, "");
+  const lines = stripped.split(/\r?\n/);
+  const out: ICompilerService.IDiagnostic[] = [];
+  for (const line of lines) {
+    const m = line.match(LINT_LINE_REGEXP);
+    if (!m) continue;
+    const [, , lineStr, colStr, sev, codeStr, rule, message] = m;
+    const lineNum = Number(lineStr);
+    const colNum = Number(colStr);
+    if (!Number.isFinite(lineNum) || !Number.isFinite(colNum)) continue;
+    out.push({
+      line: lineNum,
+      column: colNum,
+      length: lengthOfTokenAt(source, lineNum, colNum) ?? 1,
+      severity: sev === "warning" ? "warning" : "error",
+      message: rule ? `[${rule}] ${message ?? ""}` : (message ?? ""),
+      code: `TS${codeStr ?? ""}`,
+    });
+  }
+  return out;
+}
+
+/**
+ * Best-effort length of the identifier-like token starting at (`line`,
+ * `column`) in `source`. Falls back to 1 when no token is found.
+ */
+function lengthOfTokenAt(
+  source: 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);
+  const match = text.slice(start).match(/^[\w$]+/);
+  if (!match) return null;
+  return match[0].length;
+}

package/src/compiler/internal/safeParseTypiaTransform.ts

@@ -0,0 +1,24 @@
+/** Shape of the typia transform plugin's stdout JSON payload. */
+export interface ITypiaTransformOutput {
+  diagnostics?: unknown;
+  typescript: Record<string, string>;
+}
+
+/**
+ * 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".
+ */
+export function safeParseTypiaTransform(
+  text: string,
+): ITypiaTransformOutput | null {
+  try {
+    const parsed = JSON.parse(text) as ITypiaTransformOutput;
+    if (parsed && typeof parsed === "object" && parsed.typescript) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/compiler/lineColumnOf.ts

@@ -0,0 +1,14 @@
+/** Compute 1-based line/column for a 0-based char offset into `source`. */
+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;
+  return { line, column };
+}

package/src/compiler/loadTypiaSourcePack.ts

@@ -0,0 +1,37 @@
+import type { IInstallTypiaSourcePackOptions } from "../structures/IInstallTypiaSourcePackOptions";
+
+const packCache = new Map<string, Promise<Record<string, string>>>();
+
+/**
+ * Fetch the typia source pack JSON. Cached per URL across calls. On rejection
+ * the cache entry is cleared so the next call retries — otherwise a transient
+ * fetch failure during the first boot would wedge every later boot through
+ * `getBoot`'s typiaPlugin.mount path.
+ */
+export function loadTypiaSourcePack(
+  options: IInstallTypiaSourcePackOptions,
+): Promise<Record<string, string>> {
+  const cached = packCache.get(options.url);
+  if (cached) return cached;
+  const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (!fetchImpl) {
+    throw new Error(
+      "loadTypiaSourcePack: no fetch implementation available in this environment.",
+    );
+  }
+  const url = options.url;
+  const promise = (async () => {
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+      throw new Error(
+        `loadTypiaSourcePack: failed to fetch ${url}: ${response.status}`,
+      );
+    }
+    return (await response.json()) as Record<string, string>;
+  })().catch((err) => {
+    packCache.delete(url);
+    throw err;
+  });
+  packCache.set(url, promise);
+  return promise;
+}

package/src/compiler/mapDiagnostic.ts

@@ -0,0 +1,26 @@
+import type { ITtscCompileResult } from "@ttsc/wasm";
+
+import type { ICompilerService } from "../structures/ICompilerService";
+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).
+ */
+export function mapDiagnostic(
+  diag: NonNullable<ITtscCompileResult["diagnostics"]>[number],
+  source: string,
+): ICompilerService.IDiagnostic {
+  const fallback = lineColumnOf(source, diag.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,
+    severity: diag.category === "warning" ? "warning" : "error",
+    message: diag.messageText,
+    code: typeof diag.code === "number" ? `TS${diag.code}` : String(diag.code),
+  };
+}