@ttsc/playground 0.14.0-dev.20250530.1

package/src/structures/ICreateCompilerClientOptions.ts

@@ -0,0 +1,13 @@
+/** Options for {@link createCompilerClient}. */
+export interface ICreateCompilerClientOptions {
+  /**
+   * URL of the bundled worker script (the site's rspack output of its
+   * `compiler/index.ts` worker entry, which calls `createWorkerCompiler`).
+   *
+   * The Worker is constructed by tgrid's `WorkerConnector` with classic- worker
+   * semantics. A custom Worker factory hook is intentionally not exposed — the
+   * upstream tgrid v1 API only accepts a URL. File an issue if you need module
+   * workers, named workers, or custom credentials.
+   */
+  workerUrl: string;
+}

package/src/structures/ICreateWorkerCompilerOptions.ts

@@ -0,0 +1,40 @@
+import type { ILintPluginConfig } from "./ILintPluginConfig";
+import type { ITypiaPluginConfig } from "./ITypiaPluginConfig";
+
+/** Options for {@link createWorkerCompiler}. */
+export interface ICreateWorkerCompilerOptions {
+  /** URL of the site's pre-built playground.wasm. */
+  wasmUrl: string;
+  /** URL of the matching wasm_exec.js. Defaults to next to wasmUrl. */
+  wasmExecUrl?: string;
+  /**
+   * `globalThis[apiName]` the wasm binds. Must match the `apiName` passed to
+   * `host.Expose` when the site's wasm was built.
+   */
+  apiName: string;
+
+  /** In-MemFS project root. Defaults to `/work`. */
+  workDir?: string;
+  /** Tsconfig path relative to `workDir`. Defaults to `tsconfig.json`. */
+  tsconfigPath?: string;
+  /** Entry source path relative to `workDir`. Defaults to `src/playground.ts`. */
+  entryFile?: string;
+
+  /**
+   * Typia integration. Pass `false` to disable. When omitted, defaults to `{
+   * name: "typia", transformModule: "typia/lib/transform" }` — and only
+   * actually runs when the per-call `options.typia` is not `false`.
+   */
+  typiaPlugin?: ITypiaPluginConfig | false;
+
+  /** Lint integration. Pass `false` to disable. */
+  lintPlugin?: ILintPluginConfig | false;
+
+  /**
+   * Extra entries spliced into the tsconfig's `compilerOptions`. Use to wire
+   * site-specific plugins, paths, or lib overrides. The typia plugin entry is
+   * appended automatically when `typiaPlugin` is enabled — sites should NOT
+   * include it here.
+   */
+  extraCompilerOptions?: Record<string, unknown>;
+}

package/src/structures/IInstallTypiaSourcePackOptions.ts

@@ -0,0 +1,18 @@
+/**
+ * Options for {@link installTypiaSourcePack} and
+ * {@link createTypiaSourcePackMount}.
+ */
+export interface IInstallTypiaSourcePackOptions {
+  /** URL the site serves the pre-built typia source pack from. */
+  url: string;
+  /**
+   * Where to mount the pack inside the MemFS. Defaults to `/work/node_modules`,
+   * matching `DEFAULT_WORK_DIR + "/node_modules"`.
+   */
+  mountRoot?: string;
+  /**
+   * Optional fetcher. Defaults to `globalThis.fetch`. Override for tests or for
+   * sites that want their own caching strategy.
+   */
+  fetch?: (input: string) => Promise<Response>;
+}

package/src/structures/ILintPluginConfig.ts

@@ -0,0 +1,5 @@
+/** Options for the `@ttsc/lint` integration of {@link createWorkerCompiler}. */
+export interface ILintPluginConfig {
+  /** Plugin id registered with `host.Expose` (default: `"@ttsc/lint"`). */
+  name?: string;
+}

package/src/structures/IOptionToggle.ts

@@ -0,0 +1,12 @@
+/**
+ * Toggle metadata the OptionsPanel renders.
+ *
+ * Sites declare these for whatever transform plugins their wasm registered; the
+ * panel renders one row per entry and bubbles `onChange` with the merged
+ * options object.
+ */
+export interface IOptionToggle {
+  key: string;
+  label: string;
+  description: string;
+}

package/src/structures/IPlaygroundDependencyInstallOptions.ts

@@ -0,0 +1,17 @@
+import type { IPlaygroundDependencyProgress } from "./IPlaygroundDependencyProgress";
+
+/** Options for {@link installPlaygroundDependencies}. */
+export interface IPlaygroundDependencyInstallOptions {
+  /** Defaults to `globalThis.fetch`. Override for tests or for offline runs. */
+  fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+  /** Package names the wasm already has — skip re-installing them. */
+  installedPackages?: Iterable<string>;
+  /** Package names to never install (preinstalled / built-in). */
+  ignoredPackages?: Iterable<string>;
+  /** Safety cap: error out after installing this many packages. */
+  maxPackages?: number;
+  /** Aborts the install when triggered. */
+  signal?: AbortSignal;
+  /** Fires for each phase transition during the install. */
+  onProgress?: (event: IPlaygroundDependencyProgress) => void;
+}

package/src/structures/IPlaygroundDependencyInstallResult.ts

@@ -0,0 +1,21 @@
+import type { IPlaygroundDependencyPackage } from "./IPlaygroundDependencyPackage";
+
+/** Aggregate result returned by {@link installPlaygroundDependencies}. */
+export interface IPlaygroundDependencyInstallResult {
+  packages: IPlaygroundDependencyPackage[];
+  /**
+   * `node_modules/...` keyed map of files to mount inside the wasm-side
+   * compiler MemFS.
+   */
+  compilerFiles: Record<string, string>;
+  /**
+   * `file:///node_modules/...` keyed map of `.d.ts` + `package.json` files to
+   * register with Monaco via `addExtraLib`.
+   */
+  editorLibs: Record<string, string>;
+  /**
+   * Package-rooted runtime files (e.g. `uuid/dist/index.js`) the in-page
+   * execute sandbox `require` can resolve.
+   */
+  runtimeFiles: Record<string, string>;
+}

package/src/structures/IPlaygroundDependencyPackage.ts

@@ -0,0 +1,8 @@
+/** Metadata for one successfully installed npm package. */
+export interface IPlaygroundDependencyPackage {
+  name: string;
+  version: string;
+  tarball: string;
+  fileCount: number;
+  declarationCount: number;
+}

package/src/structures/IPlaygroundDependencyProgress.ts

@@ -0,0 +1,11 @@
+import type { IPlaygroundDependencyProgressPhase } from "./IPlaygroundDependencyProgressPhase";
+
+/** A single progress event emitted while installing playground dependencies. */
+export interface IPlaygroundDependencyProgress {
+  phase: IPlaygroundDependencyProgressPhase;
+  packageName?: string;
+  version?: string;
+  completed: number;
+  total: number;
+  message: string;
+}

package/src/structures/IPlaygroundDependencyProgressPhase.ts

@@ -0,0 +1,12 @@
+/**
+ * Lifecycle phase of a single dependency install reported via the progress
+ * callback.
+ */
+export type IPlaygroundDependencyProgressPhase =
+  | "queued"
+  | "resolve"
+  | "download"
+  | "extract"
+  | "skip"
+  | "error"
+  | "done";

package/src/structures/IPlaygroundExample.ts

@@ -0,0 +1,16 @@
+/**
+ * One pre-canned source script the playground dropdown can load. Sites provide
+ * their own list — typia's site lists `random/is/json/protobuf`, the ttsc site
+ * lists `typia/lint/mixed`.
+ */
+export interface IPlaygroundExample {
+  id: string;
+  title: string;
+  description: string;
+  source: string;
+  /**
+   * Optional grouping bucket. Examples are rendered grouped by this label.
+   * Defaults to "Examples" when omitted.
+   */
+  group?: string;
+}

package/src/structures/IPlaygroundShellProps.ts

@@ -0,0 +1,83 @@
+import type { ReactNode } from "react";
+
+import type { IOptionToggle } from "./IOptionToggle";
+import type { IPlaygroundExample } from "./IPlaygroundExample";
+import type { ITransformOptions } from "./ITransformOptions";
+
+/**
+ * Props for the full playground shell.
+ *
+ * The shell is intentionally configurable rather than configurable-by-context:
+ * every changing field is an explicit prop, so wrappers can spread their own
+ * defaults without a Provider in between.
+ */
+export interface IPlaygroundShellProps {
+  /**
+   * URL of the bundled worker script (rspack output of the site's worker
+   * entry).
+   */
+  workerUrl: string;
+
+  /** Source code shown on first mount (and on Reset). */
+  defaultScript: string;
+
+  /** Examples available in the dropdown. Empty array hides the dropdown. */
+  examples?: readonly IPlaygroundExample[];
+  /** Display labels for example groups. */
+  exampleGroupLabels?: Record<string, string>;
+
+  /** Toggles rendered in the Options modal. Defaults to typia + lint. */
+  optionToggles?: readonly IOptionToggle[];
+  /**
+   * Initial values for the transform options. Defaults to `{typia: true, lint:
+   * true}`.
+   */
+  defaultOptions?: ITransformOptions;
+
+  /**
+   * Static extra .d.ts entries to mount in Monaco (e.g. a pre-packed typia type
+   * pack). Merged with dependencies installed at runtime.
+   */
+  staticEditorLibs?: Record<string, string>;
+
+  /**
+   * Packages the site has already pre-mounted into the wasm. These are skipped
+   * by the runtime npm dependency installer.
+   */
+  preinstalledPackages?: readonly string[];
+
+  /**
+   * Optional execute hook. When provided, the shell renders an "Execute"
+   * button; on click it calls `service.bundle(...)` to get the JS and passes it
+   * here. The returned messages are appended to the Console pane.
+   *
+   * `sandbox.runtimeFiles` is the accumulated runtime-file map produced by
+   * every `installPlaygroundDependencies` call so far in this session
+   * (package-rooted keys like `uuid/dist/index.js`). The site's executeBundle
+   * typically merges these on top of its own typia-runtime pack and feeds the
+   * union to `createSandboxRequire` — without this channel the in-page Execute
+   * sandbox cannot resolve any npm dependency the user installed.
+   *
+   * When omitted, the Execute UI is hidden.
+   */
+  executeBundle?: (
+    code: string,
+    sandbox: {
+      console: Record<string, (...args: unknown[]) => void>;
+      runtimeFiles: Record<string, string>;
+    },
+  ) => Promise<void>;
+
+  /**
+   * Brand slot in the toolbar (left side). Renders before the Playground label.
+   * Sites typically pass `<a href="/">SiteName</a>`.
+   */
+  brand?: ReactNode;
+
+  /**
+   * Caption shown on the result pane when the active tab is "javascript".
+   * Defaults to `"dist/playground.js"`. Receives the current transform options
+   * so sites can append `· typia disabled` etc.
+   */
+  resultCaption?: (options: ITransformOptions) => string;
+}

package/src/structures/ISourceEditorProps.ts

@@ -0,0 +1,18 @@
+/**
+ * Props for the Monaco-based source editor. The site provides `extraLibs` —
+ * typically the typia `.d.ts` pack and any installed npm package `.d.ts` files
+ * — and the editor mounts them via
+ * `monaco.languages.typescript.typescriptDefaults.addExtraLib`.
+ */
+export interface ISourceEditorProps {
+  value: string;
+  onChange: (value: string) => void;
+  /**
+   * Map of file path → declaration text. Mounted into Monaco's TypeScript
+   * extra-libs registry. Hot-replaceable: the editor disposes the previous libs
+   * and re-mounts when the map identity changes.
+   */
+  extraLibs?: Record<string, string>;
+  /** Editor model URI. Defaults to `file:///src/playground.ts`. */
+  path?: string;
+}

package/src/structures/ITransformOptions.ts

@@ -0,0 +1,15 @@
+/**
+ * Toggle flags the UI surfaces in the Options panel and forwards to the worker
+ * on every compile. The built-in `typia` and `lint` keys mirror the two plugin
+ * 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`.
+ */
+export interface ITransformOptions {
+  /** Enable the typia transform plugin. Defaults to true. */
+  typia?: boolean;
+  /** Enable the `@ttsc/lint` preview rule pass. Defaults to true. */
+  lint?: boolean;
+  /** Additional site-specific toggles. */
+  [key: string]: boolean | undefined;
+}

package/src/structures/ITypiaPluginConfig.ts

@@ -0,0 +1,20 @@
+import type { IMemFSHost } from "@ttsc/wasm";
+
+/** Options for the typia integration of {@link createWorkerCompiler}. */
+export interface ITypiaPluginConfig {
+  /** Plugin id registered with `host.Expose` (default: `"typia"`). */
+  name?: string;
+  /**
+   * Module specifier the typia transform receives via `compilerOptions.plugins`
+   * (default: `"typia/lib/transform"`).
+   */
+  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.
+   */
+  mount?: (host: IMemFSHost, workDir: string) => Promise<void>;
+}

package/src/structures/index.ts

@@ -0,0 +1,18 @@
+export * from "./IBuildTsconfigOptions";
+export * from "./ICompilerService";
+export * from "./IConsoleMessage";
+export * from "./ICreateCompilerClientOptions";
+export * from "./ICreateWorkerCompilerOptions";
+export * from "./IInstallTypiaSourcePackOptions";
+export * from "./ILintPluginConfig";
+export * from "./IOptionToggle";
+export * from "./IPlaygroundDependencyInstallOptions";
+export * from "./IPlaygroundDependencyInstallResult";
+export * from "./IPlaygroundDependencyPackage";
+export * from "./IPlaygroundDependencyProgress";
+export * from "./IPlaygroundDependencyProgressPhase";
+export * from "./IPlaygroundExample";
+export * from "./IPlaygroundShellProps";
+export * from "./ISourceEditorProps";
+export * from "./ITransformOptions";
+export * from "./ITypiaPluginConfig";