@ttsc/playground 0.30.3 → 0.31.0

package/src/structures/IPlaygroundDependencyRequest.ts

@@ -1,9 +1,18 @@
-/** One active npm range that selected a mounted playground dependency. */
+/**
+ * One active npm range that selected a mounted playground dependency.
+ *
+ * @evidence contracts/common.md#principled-implementation Range, requester and optionality preserve the constraint and its origin so mounted-version compatibility can be assessed.
+ * @evidence contracts/common.md#clear-and-simple-design A constraint record separates dependency edges from mounted package identity.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Optionality explicitly permits omission; a missing required edge is not disguised as successful reuse.
+ * @evidence contracts/common.md#meaningful-documentation Member JSDoc explains declared range, origin and omission meaning, following documentation-skill member spacing.
+ */
 export interface IPlaygroundDependencyRequest {
   /** Declared npm range or tag. */
   range: string;
+
   /** Package or source entry that declared the range. */
   requester: string;
+
   /** Whether an unsatisfied request may be omitted. */
   optional: boolean;
 }

package/src/structures/IPlaygroundExample.ts

@@ -2,12 +2,18 @@
  * 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`.
+ *
+ * @evidence contracts/common.md#principled-implementation Stable id selects source independently of visible title and optional grouping metadata.
+ * @evidence contracts/common.md#clear-and-simple-design Example content and presentation stay in a site-owned record without compiler configuration mixed in.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Sites supply examples; ids do not choose hidden compiler behavior.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies site ownership and the group default, following documentation-skill paragraph and tag separation.
  */
 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.

package/src/structures/IPlaygroundInstalledDependency.ts

@@ -1,13 +1,23 @@
 import type { IPlaygroundDependencyRequest } from "./IPlaygroundDependencyRequest";
 
-/** Exact identity and active constraints of one dependency already mounted. */
+/**
+ * Exact identity and active constraints of one dependency already mounted.
+ *
+ * @evidence contracts/common.md#principled-implementation Mount name, registry name, exact version and active requests jointly represent the installed graph's compatibility witness.
+ * @evidence contracts/common.md#clear-and-simple-design Identity and its selecting constraints remain one record while artifact contents belong to result maps.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit exact identities replace name-only guesses about whether later requests are satisfied.
+ * @evidence contracts/common.md#meaningful-documentation Member comments distinguish exposed name, alias target, exact version and requests, with documentation-skill member spacing.
+ */
 export interface IPlaygroundInstalledDependency {
   /** Exposed package name under `node_modules`. */
   name: string;
+
   /** Package name queried from the registry, which differs for npm aliases. */
   registryName: string;
+
   /** Exact mounted version. */
   version: string;
+
   /** Active requests that the mounted version satisfies. */
   requests: IPlaygroundDependencyRequest[];
 }

package/src/structures/IPlaygroundShellProps.ts

@@ -10,6 +10,11 @@ import type { ITransformOptions } from "./ITransformOptions";
  * 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.
+ *
+ * @evidence contracts/common.md#principled-implementation Site-owned runtime URL, initial content, presentation and execution policy distinguish required inputs from optional UI features.
+ * @evidence contracts/common.md#clear-and-simple-design Explicit props keep site policy outside shell lifecycle implementation; option metadata and example records have their own types.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Site policy enters through declared props and callbacks rather than consumer-specific branches.
+ * @evidence contracts/common.md#meaningful-documentation Member prose explains defaults, runtime-file namespace and cancellation limits, with documentation-skill paragraphs and member spacing.
  */
 export interface IPlaygroundShellProps {
   /**
@@ -23,11 +28,13 @@ export interface IPlaygroundShellProps {
 
   /** 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}`.
@@ -36,44 +43,41 @@ export interface IPlaygroundShellProps {
 
   /**
    * Static extra .d.ts entries to mount in Monaco (e.g. a pre-packed typia type
-   * pack). Merged with dependencies installed at runtime.
+   * pack). Merged with dependencies installed at runtime. Keep the object
+   * identity stable across renders: a new object makes the editor dispose and
+   * register every declaration again.
    */
   staticEditorLibs?: Record<string, string>;
 
   /**
    * Packages the site has already pre-mounted into the wasm. These are skipped
-   * by the runtime npm dependency installer.
+   * by the runtime npm dependency installer. Keep the array identity stable
+   * across renders: a new array restarts the pending compile debounce.
    */
   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.
+   * here. Calls the hook makes on `sandbox.console` are appended to the Console
+   * pane in order; its returned promise carries no messages.
    *
-   * `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.
+   * `sandbox.runtimeFiles` is the current runtime-file map produced by
+   * dependency installation 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.
    *
    * `sandbox.signal` aborts when source or compiler options change, a newer
-   * Execute starts, or the shell unmounts. Implementations must pass it through
-   * to cancellable setup such as runtime-pack fetches. Synchronous evaluated
-   * user code cannot be preempted and still requires an isolated executor when
-   * untrusted code is accepted.
+   * Execute starts, the compiler Worker is replaced, or the shell unmounts.
+   * Implementations must pass it through to cancellable setup such as
+   * runtime-pack fetches. Synchronous evaluated user code cannot be preempted
+   * and still requires an isolated executor when untrusted code is accepted.
    *
    * When omitted, the Execute UI is hidden.
    */
-  executeBundle?: (
-    code: string,
-    sandbox: {
-      console: Record<string, (...args: unknown[]) => void>;
-      runtimeFiles: Record<string, string>;
-      signal: AbortSignal;
-    },
-  ) => Promise<void>;
+  executeBundle?: PlaygroundBundleExecutor;
 
   /**
    * Brand slot in the toolbar (left side). Renders before the Playground label.
@@ -86,5 +90,41 @@ export interface IPlaygroundShellProps {
    * Defaults to `"dist/playground.js"`. Receives the current transform options
    * so sites can append `· typia disabled` etc.
    */
-  resultCaption?: (options: ITransformOptions) => string;
+  resultCaption?: PlaygroundResultCaption;
 }
+
+/**
+ * Execute emitted code with session runtime files and attempt-scoped
+ * cancellation.
+ *
+ * The site owns execution isolation. The abort signal can cancel asynchronous
+ * setup, but cannot preempt synchronous evaluated code.
+ *
+ * @evidence contracts/common.md#principled-implementation Emitted code, package-rooted runtime files and cancellation preserve the shell's real execution inputs and isolation boundary.
+ * @evidence contracts/common.md#clear-and-simple-design One asynchronous hook keeps site execution policy separate from bundling, console presentation and compiler Worker ownership.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A declared hook permits site-owned isolation without patching foreign runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe cancellation limits and ownership before the acknowledgment tags.
+ */
+export type PlaygroundBundleExecutor = (
+  code: string,
+  sandbox: {
+    /** Console methods supplied by the shell for this execution attempt. */
+    console: Record<string, (...args: unknown[]) => void>;
+
+    /** Package-rooted runtime modules in the current dependency graph. */
+    runtimeFiles: Record<string, string>;
+
+    /** Cancellation for setup and asynchronous work, not synchronous user code. */
+    signal: AbortSignal;
+  },
+) => Promise<void>;
+
+/**
+ * Choose a result-pane caption from current transform options.
+ *
+ * @evidence contracts/common.md#principled-implementation Current options select presentation text only, without claiming to select emitted filenames.
+ * @evidence contracts/common.md#clear-and-simple-design A string-returning presentation callback stays independent of compiler configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A caption is a UI label rather than evidence that a particular output was produced.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the display purpose and parameter before the separated tags.
+ */
+export type PlaygroundResultCaption = (options: ITransformOptions) => string;

package/src/structures/ISourceEditorProps.ts

@@ -3,16 +3,35 @@
  * 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`.
+ *
+ * @evidence contracts/common.md#principled-implementation Controlled text, change callback, model URI and optional declaration map describe Monaco's input boundaries.
+ * @evidence contracts/common.md#clear-and-simple-design Editor props contain editing and virtual-library inputs without compiler lifecycle state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Declaration installation uses Monaco's supported extra-lib API rather than mutating editor internals.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains map identity replacement and default URI, with separated paragraphs and member spacing under the documentation skill.
  */
 export interface ISourceEditorProps {
   value: string;
-  onChange: (value: string) => void;
+
+  /** Publish the editor's complete current text to the controlling owner. */
+  onChange: SourceEditorChangeHandler;
+
   /**
    * 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;
 }
+
+/**
+ * Publish the editor's complete text to its controlling owner.
+ *
+ * @evidence contracts/common.md#principled-implementation The full-text parameter matches the controlled value model without requiring edit-delta reconstruction.
+ * @evidence contracts/common.md#clear-and-simple-design One void notification leaves text state with the parent.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The supported event boundary avoids mutating parent state or editor globals.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names the payload and owner, separated from the acknowledgment tags.
+ */
+export type SourceEditorChangeHandler = (value: string) => void;

package/src/structures/ITransformOptions.ts

@@ -4,12 +4,19 @@
  * 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. */
   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

@@ -1,20 +1,44 @@
 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;
+
   /**
    * 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.
+   * 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>;