@ttsc/playground 0.30.4 → 0.31.0

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

@@ -6,58 +6,150 @@ import type { ITransformOptions } from "./ITransformOptions";
  * (UI side) returns a tgrid Driver bound to this shape. Sites that need an
  * `extraTabs` lane should layer additional verbs over this base interface in
  * their own ICompilerService subtype.
+ *
+ * @evidence contracts/common.md#principled-implementation Promise-returning install, compile, bundle and lint verbs express the asynchronous Worker RPC boundary and their distinct result shapes.
+ * @evidence contracts/common.md#clear-and-simple-design One base RPC interface separates worker capabilities from React state and site-specific extensions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Extensions use a typed service boundary instead of replacing Worker or compiler internals.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs document both RPC ends and extension ownership; member comments describe transform order and disabled lint behavior under the documentation skill.
  */
 export interface ICompilerService {
     /**
      * Mount external npm package files into the worker's MemFS under
-     * `node_modules/`. Driven by the dependency installer in
-     * `@ttsc/playground/npm`.
+     * `node_modules/`. The package's dependency installer supplies these files.
+     *
+     * @evidence contracts/common.md#principled-implementation Package-relative file keys and metadata produce a virtual mount report; the Worker serializes installation with compilation.
+     * @evidence contracts/common.md#clear-and-simple-design This verb owns mounting while registry fetching stays on the caller side.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Writes use the virtual-host boundary without bypassing path validation for known packages.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the virtual node_modules namespace and caller responsibility, with tag separation under the documentation skill.
      */
     installDependencies(props: ICompilerService.IInstallDependenciesProps): Promise<ICompilerService.IInstallDependenciesResult>;
     /**
      * Compile the user's source into JavaScript with diagnostics. Plugin
      * transforms (typia, when enabled in options) run first; the result is the
      * post-transform emit.
+     *
+     * @evidence contracts/common.md#principled-implementation A discriminated result distinguishes usable emit, compiler findings and operational failure after configured transforms.
+     * @evidence contracts/common.md#clear-and-simple-design The verb takes source and per-call flags; factory configuration owns runtime and plugins.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Configured transform failures remain errors rather than claiming untransformed output fulfills the transform request.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states transform-before-emit ordering with tag separation under the documentation skill.
      */
     compile(props: ICompilerService.IProps): Promise<ICompilerService.IResult>;
     /**
      * Same pipeline as `compile`, but using the bundle-flavored tsconfig
      * (typically `module: "CommonJS"` for in-page `new Function` sandboxing).
      * Sites that don't run user code may treat this identically to `compile`.
+     *
+     * @evidence contracts/common.md#principled-implementation The bundle verb uses the execution-oriented module configuration but shares the same compile result distinctions.
+     * @evidence contracts/common.md#clear-and-simple-design A separate named RPC verb exposes execution emit without requiring clients to supply compiler configuration.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Module format is explicit supported behavior, not a special case based on the user's source.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes this module shape from preview compile, with tag separation under the documentation skill.
      */
     bundle(props: ICompilerService.IProps): Promise<ICompilerService.IResult>;
     /**
      * Run the lint plugin and parse its findings into the same diagnostic shape
      * as `compile`. Returns an empty list when no lint plugin is wired into the
      * worker.
+     *
+     * @evidence contracts/common.md#principled-implementation A diagnostic list carries lint findings; disabled integration legitimately has no findings while operational failures are represented as error diagnostics.
+     * @evidence contracts/common.md#clear-and-simple-design Lint owns findings independently of emit and execution results.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed configured linter cannot masquerade as the documented disabled-linter empty result.
+     * @evidence contracts/common.md#meaningful-documentation Native prose documents findings and absent integration, separated from tags under the documentation skill.
      */
     lint(props: ICompilerService.IProps): Promise<ICompilerService.ILintResult>;
 }
 export declare namespace ICompilerService {
+    /**
+     * Per-call source and transform enablement; omitted flags use service
+     * defaults.
+     *
+     * @evidence contracts/common.md#principled-implementation Text and optional flags capture the complete per-call input without embedding factory runtime identity.
+     * @evidence contracts/common.md#clear-and-simple-design Compile, bundle and lint share one input record rather than duplicate source policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Flags use the declared plugin boundary rather than source-specific dispatch exceptions.
+     * @evidence contracts/common.md#meaningful-documentation Native prose defines per-call and omitted-option meaning with tag separation under the documentation skill.
+     */
     export interface IProps {
         source: string;
         options?: ITransformOptions;
     }
+    /**
+     * Text files and package identities submitted as one virtual installation.
+     *
+     * @evidence contracts/common.md#principled-implementation Relative file keys identify writes and the package array labels that operation's metadata; this is not a registry graph solver.
+     * @evidence contracts/common.md#clear-and-simple-design Files and identities stay in one RPC payload while result counts are a separate response.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Virtual installation uses caller-supplied entries and the host's path gate, not fixture-specific package logic.
+     * @evidence contracts/common.md#meaningful-documentation Member prose defines relative keys and metadata association with blank member lines under the documentation skill.
+     */
     export interface IInstallDependenciesProps {
         /** Node_modules-relative paths to text content. */
         files: Record<string, string>;
         /** Metadata for the packages whose files are in `files`. */
         packages: IInstalledPackage[];
     }
+    /**
+     * Exposed package name and exact installed version for a mounting report.
+     *
+     * @evidence contracts/common.md#principled-implementation Name and version label the mounted package; registry alias identity and active constraints belong to the dependency solver's richer type.
+     * @evidence contracts/common.md#clear-and-simple-design The mounting report carries only the identity its client needs.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The record reports supplied metadata and does not infer compatibility from a name alone.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes mount metadata from solver state, with tags separated under the documentation skill.
+     */
     export interface IInstalledPackage {
         name: string;
         version: string;
     }
+    /**
+     * Submitted package identities and count of accepted virtual-file writes.
+     *
+     * @evidence contracts/common.md#principled-implementation fileCount counts writes accepted by path validation; installed carries the submitted identities rather than asserting a solved dependency graph.
+     * @evidence contracts/common.md#clear-and-simple-design A small mounting response separates accepted-write count from compile output.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Counts arise from actual writes rather than expected answers or skipped malformed paths.
+     * @evidence contracts/common.md#meaningful-documentation Native prose defines counting and metadata limits with tag separation under the documentation skill.
+     */
     export interface IInstallDependenciesResult {
         installed: IInstalledPackage[];
         fileCount: number;
     }
+    /**
+     * Compile outcome discriminated by successful emit, findings or operation
+     * error.
+     *
+     * @evidence contracts/common.md#principled-implementation The type field discriminates string emit from unknown error payload; failure retains both emit and diagnostics.
+     * @evidence contracts/common.md#clear-and-simple-design Named variants centralize result narrowing across Worker and UI.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Operational errors are a distinct variant rather than fabricated successful text.
+     * @evidence contracts/common.md#meaningful-documentation Native prose names all outcome meanings with tag separation under the documentation skill.
+     */
     export type IResult = ISuccess | IFailure | IError;
+    /**
+     * JavaScript emit with no error diagnostics; empty text may mean no emitted
+     * file.
+     *
+     * @evidence contracts/common.md#principled-implementation The success discriminant and string payload represent the compile lane's non-error outcome.
+     * @evidence contracts/common.md#clear-and-simple-design The common envelope is reused without an unnecessary second success structure.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Success does not claim that empty emit proves a file exists or user code is safe.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains the empty-emit limit with tag separation under the documentation skill.
+     */
     export interface ISuccess extends IBase<"success", string> {
     }
+    /**
+     * Compiler findings together with any available JavaScript emit.
+     *
+     * @evidence contracts/common.md#principled-implementation Error findings accompany a string emit payload so the UI can show both even when compilation is unsuccessful.
+     * @evidence contracts/common.md#clear-and-simple-design Only the finding variant adds diagnostics to the shared envelope.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Findings remain explicit rather than converting nonempty emit into unconditional success.
+     * @evidence contracts/common.md#meaningful-documentation Native prose defines simultaneous diagnostics and emit with tag separation under the documentation skill.
+     */
     export interface IFailure extends IBase<"failure", string> {
         diagnostics: IDiagnostic[];
     }
+    /**
+     * Operation failure whose transport payload may be an error record or
+     * message.
+     *
+     * @evidence contracts/common.md#principled-implementation Unknown preserves the permitted error payload domain until the receiver normalizes it.
+     * @evidence contracts/common.md#clear-and-simple-design The error discriminant shares routing fields with other outcomes without pretending its payload is JavaScript.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Failures retain their own outcome rather than inventing emit to satisfy consumers.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains payload variability with tag separation under the documentation skill.
+     */
     export interface IError extends IBase<"error", unknown> {
     }
     interface IBase<Type extends string, Value> {
@@ -65,6 +157,15 @@ export declare namespace ICompilerService {
         target: "javascript";
         value: Value;
     }
+    /**
+     * UI diagnostic with one-based location and a span measured in source
+     * characters.
+     *
+     * @evidence contracts/common.md#principled-implementation Location, severity, text and optional code represent compiler and lint findings without tying them to one producer.
+     * @evidence contracts/common.md#clear-and-simple-design One diagnostic shape is shared by compile and lint result lanes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Producer codes are carried as metadata rather than hardcoded finding decisions.
+     * @evidence contracts/common.md#meaningful-documentation Member JSDoc defines coordinate bases, span units and code purpose, with documentation-skill member spacing.
+     */
     export interface IDiagnostic {
         /** 1-based line number. */
         line: number;
@@ -77,6 +178,15 @@ export declare namespace ICompilerService {
         /** Diagnostic code, e.g. `"TS2322"` or a lint rule id. */
         code?: string;
     }
+    /**
+     * Lint findings, including an error diagnostic when the configured plugin
+     * fails.
+     *
+     * @evidence contracts/common.md#principled-implementation A diagnostic array covers both rule findings and plugin failure reports; absence of configured lint yields an empty array.
+     * @evidence contracts/common.md#clear-and-simple-design The lint lane returns findings without unrelated JavaScript output fields.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Configured-plugin failure is kept visible rather than encoded as a clean empty list.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states failure representation with tag separation under the documentation skill.
+     */
     export interface ILintResult {
         diagnostics: IDiagnostic[];
     }

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

@@ -3,6 +3,11 @@
  * `console.log(...args)`), so `console.log("user:", user)` shows up as a single
  * row with both pieces rendered inline, separated by a space — same as a real
  * DevTools console.
+ *
+ * @evidence contracts/common.md#principled-implementation The finite console-method union labels one captured invocation; unknown arguments preserve values without pretending every value is serializable.
+ * @evidence contracts/common.md#clear-and-simple-design Method and argument list keep event identity separate from renderer policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Console labels are supported invocation kinds, not special cases for particular user output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains argument grouping and display meaning in a separate paragraph under the documentation skill.
  */
 export interface IConsoleMessage {
     type: "debug" | "dir" | "error" | "info" | "log" | "table" | "warn";

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

@@ -1,10 +1,17 @@
-/** Options for {@link createCompilerClient}. */
+/**
+ * Options for {@link createCompilerClient}.
+ *
+ * @evidence contracts/common.md#principled-implementation A script URL is the input accepted by the tgrid Worker connector; this type does not advertise unsupported Worker construction options.
+ * @evidence contracts/common.md#clear-and-simple-design The single client input stays distinct from worker-side compiler configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Worker creation uses tgrid's supported URL boundary instead of replacing its internals.
+ * @evidence contracts/common.md#meaningful-documentation The member comment explains script ownership and classic Worker constraints, following documentation-skill prose separation.
+ */
 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
+     * 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.

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

@@ -1,6 +1,13 @@
 import type { ILintPluginConfig } from "./ILintPluginConfig";
 import type { ITypiaPluginConfig } from "./ITypiaPluginConfig";
-/** Options for {@link createWorkerCompiler}. */
+/**
+ * Options for {@link createWorkerCompiler}.
+ *
+ * @evidence contracts/common.md#principled-implementation Required runtime identity and optional virtual-project paths express boot and compilation inputs; false distinguishes disabled integrations from default integration settings.
+ * @evidence contracts/common.md#clear-and-simple-design Boot inputs, virtual layout and plugin options remain one explicit factory record with nested plugin responsibilities.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Plugin names and defaults describe the supported playground integrations; sites override them through explicit configuration.
+ * @evidence contracts/common.md#meaningful-documentation Member JSDoc explains defaults, registration identity and compiler-option ownership, with blank member lines following the documentation skill.
+ */
 export interface ICreateWorkerCompilerOptions {
     /** URL of the site's pre-built playground.wasm. */
     wasmUrl: string;
@@ -28,8 +35,9 @@ export interface ICreateWorkerCompilerOptions {
     /**
      * 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.
+     * appended automatically after any `plugins` array given here when
+     * `typiaPlugin` is enabled — sites should NOT include it themselves, and an
+     * entry naming the same transform module is replaced by the appended one.
      */
     extraCompilerOptions?: Record<string, unknown>;
 }

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

@@ -1,6 +1,12 @@
+import type { PlaygroundFetch } from "./IPlaygroundDependencyInstallOptions";
 /**
  * Options for {@link installTypiaSourcePack} and
  * {@link createTypiaSourcePackMount}.
+ *
+ * @evidence contracts/common.md#principled-implementation URL, virtual mount root, abort signal and fetch injection represent independent transport and installation inputs.
+ * @evidence contracts/common.md#clear-and-simple-design One shared record serves the mount adapter and installer without a second transport configuration model.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Transport injection is explicit; callers need not monkey-patch global fetch to load a pack.
+ * @evidence contracts/common.md#meaningful-documentation Member prose explains virtual root defaults and shared cancellation, with native paragraphs and spacing from the documentation skill.
  */
 export interface IInstallTypiaSourcePackOptions {
     /** URL the site serves the pre-built typia source pack from. */
@@ -16,5 +22,5 @@ export interface IInstallTypiaSourcePackOptions {
      * Optional fetcher. Defaults to `globalThis.fetch`. Override for tests or for
      * sites that want their own caching strategy.
      */
-    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    fetch?: PlaygroundFetch;
 }

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

@@ -1,4 +1,11 @@
-/** Options for the `@ttsc/lint` integration of {@link createWorkerCompiler}. */
+/**
+ * Options for the `@ttsc/lint` integration of {@link createWorkerCompiler}.
+ *
+ * @evidence contracts/common.md#principled-implementation An optional registration name selects the host's lint verb without conflating its identity with enablement.
+ * @evidence contracts/common.md#clear-and-simple-design The record contains only the integration-owned name; factory options own disabling the integration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The default id is a registered product integration and remains caller-configurable.
+ * @evidence contracts/common.md#meaningful-documentation Native comments identify registration ownership and the default id, with prose separated from tags under the documentation skill.
+ */
 export interface ILintPluginConfig {
     /** Plugin id registered with `host.Expose` (default: `"@ttsc/lint"`). */
     name?: string;

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

@@ -1,4 +1,11 @@
-/** Cancellation policy for `loadTypiaRuntimePack`. */
+/**
+ * Cancellation policy for `loadTypiaRuntimePack`.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional AbortSignal carries the caller's cancellation request without imposing a fabricated network deadline.
+ * @evidence contracts/common.md#clear-and-simple-design Runtime URL is the loader's direct argument; this record contains only cancellation policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Shared cancellation is an explicit supported behavior, not a hidden timeout or global replacement.
+ * @evidence contracts/common.md#meaningful-documentation The member comment states that cancellation ends the shared attempt, following native documentation and tag separation rules.
+ */
 export interface ILoadTypiaRuntimePackOptions {
     /** Cancel the shared in-flight load. */
     signal?: AbortSignal;

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

@@ -4,6 +4,11 @@
  * 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.
+ *
+ * @evidence contracts/common.md#principled-implementation The key identifies a boolean option while label and description supply its visible presentation.
+ * @evidence contracts/common.md#clear-and-simple-design Rendering metadata stays separate from plugin execution and current option values.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Site-provided keys drive the panel instead of consumer-specific option branches.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains site ownership and option merging in separated paragraphs following the documentation skill.
  */
 export interface IOptionToggle {
     key: string;

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

@@ -1,9 +1,16 @@
 import type { IPlaygroundDependencyProgress } from "./IPlaygroundDependencyProgress";
 import type { IPlaygroundInstalledDependency } from "./IPlaygroundInstalledDependency";
-/** Options for {@link installPlaygroundDependencies}. */
+/**
+ * Options for {@link installPlaygroundDependencies}.
+ *
+ * @evidence contracts/common.md#principled-implementation Mounted exact identities, ignore policy, budgets and callbacks express distinct installation inputs; deprecated name-only state cannot establish version compatibility.
+ * @evidence contracts/common.md#clear-and-simple-design One installation record groups transport, prior graph and progress controls without owning compiler mounting.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Fetch injection and explicit built-in exclusions are public policy; byte and package budgets apply to every package.
+ * @evidence contracts/common.md#meaningful-documentation Member prose documents legacy limitations, byte units and streaming enforcement, with separate paragraphs and member spacing under the documentation skill.
+ */
 export interface IPlaygroundDependencyInstallOptions {
-    /** Defaults to `globalThis.fetch`. Override for tests or for offline runs. */
-    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    /** Defaults to `globalThis.fetch`; inject a transport for offline runs. */
+    fetch?: PlaygroundFetch;
     /**
      * Exact package identities already mounted in this session.
      *
@@ -19,7 +26,14 @@ export interface IPlaygroundDependencyInstallOptions {
     installedPackages?: Iterable<string>;
     /** Package names to never install (preinstalled / built-in). */
     ignoredPackages?: Iterable<string>;
-    /** Safety cap: error out after installing this many packages. */
+    /**
+     * Maximum distinct package names completed in one install call (default: 48).
+     *
+     * Must be a nonnegative safe integer. Mounted packages revalidated and
+     * optional packages omitted count toward the cap; unrequested mounted state
+     * does not. Zero allows only calls with no queued packages. Invalid values
+     * reject before input iteration, progress callbacks or network requests.
+     */
     maxPackages?: number;
     /**
      * Maximum compressed bytes accepted for one npm tarball.
@@ -36,6 +50,27 @@ export interface IPlaygroundDependencyInstallOptions {
     maxUnpackedBytes?: number;
     /** Aborts the install when triggered. */
     signal?: AbortSignal;
-    /** Fires for each phase transition during the install. */
-    onProgress?: (event: IPlaygroundDependencyProgress) => void;
+    /**
+     * Fires synchronously for phase transitions; callback failures reject the
+     * install.
+     */
+    onProgress?: PlaygroundDependencyProgressHandler;
 }
+/**
+ * Fetch a playground package or source pack through the caller's transport.
+ *
+ * @evidence contracts/common.md#principled-implementation Standard RequestInit and Response preserve status, cancellation and streamed-body semantics used by the loaders.
+ * @evidence contracts/common.md#clear-and-simple-design Transport stays distinct from registry resolution, archive processing and mounting.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Injection uses an explicit seam without replacing global fetch internals.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies the transport role; optional initialization matches fetch consumers.
+ */
+export type PlaygroundFetch = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Receive synchronous installation progress; thrown errors reject installation.
+ *
+ * @evidence contracts/common.md#principled-implementation A typed event reports the actual install transition without inventing a success result.
+ * @evidence contracts/common.md#clear-and-simple-design A single void notification keeps presentation state outside registry processing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Observer failures are not converted into synthetic installation success.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states delivery timing and error propagation independently of acknowledgment tags.
+ */
+export type PlaygroundDependencyProgressHandler = (event: IPlaygroundDependencyProgress) => void;

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

@@ -1,6 +1,13 @@
 import type { IPlaygroundDependencyPackage } from "./IPlaygroundDependencyPackage";
 import type { IPlaygroundInstalledDependency } from "./IPlaygroundInstalledDependency";
-/** Aggregate result returned by {@link installPlaygroundDependencies}. */
+/**
+ * Aggregate result returned by {@link installPlaygroundDependencies}.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact identities describe the complete graph while downloaded package metadata and file maps describe this call's additions in each consumer's namespace.
+ * @evidence contracts/common.md#clear-and-simple-design Compiler, editor and runtime maps remain explicit lanes instead of requiring consumers to infer path spelling.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Output namespaces represent actual consumer protocols rather than special casing a package or source example.
+ * @evidence contracts/common.md#meaningful-documentation Member prose distinguishes complete state from new downloads and documents each map's path namespace, with documentation-skill member spacing.
+ */
 export interface IPlaygroundDependencyInstallResult {
     /** Complete exact state after merging installed packages with this call. */
     resolvedDependencies: IPlaygroundInstalledDependency[];

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

@@ -1,4 +1,12 @@
-/** Metadata for one successfully installed npm package. */
+/**
+ * Metadata for one successfully installed npm package; counts refer to mounted
+ * text files and declaration files, respectively.
+ *
+ * @evidence contracts/common.md#principled-implementation Mount name, registry identity and exact version distinguish aliases from their targets; counts describe the installed artifact population.
+ * @evidence contracts/common.md#clear-and-simple-design Artifact metadata is separate from active dependency constraints and the downloaded file maps.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Registry identity is explicit rather than inferred from an alias's exposed name.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines count meaning and the registryName distinction, with separate tags under the documentation skill.
+ */
 export interface IPlaygroundDependencyPackage {
     name: string;
     /** Package name queried from the registry, which differs for npm aliases. */

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

@@ -1,5 +1,13 @@
 import type { IPlaygroundDependencyProgressPhase } from "./IPlaygroundDependencyProgressPhase";
-/** A single progress event emitted while installing playground dependencies. */
+/**
+ * One dependency-install progress event. Package identity may be absent for
+ * aggregate completion; completed and total count package work, not bytes.
+ *
+ * @evidence contracts/common.md#principled-implementation Phase and optional package identity express both per-package transitions and aggregate completion without inventing an identity for the latter.
+ * @evidence contracts/common.md#clear-and-simple-design One event record carries display progress without exposing the installer's queue internals.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Progress reflects actual phase transitions and package counts, not fabricated measurement outcomes.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states optional identity and count units; paragraph and tag separation follow the documentation skill.
+ */
 export interface IPlaygroundDependencyProgress {
     phase: IPlaygroundDependencyProgressPhase;
     packageName?: string;

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

@@ -1,5 +1,10 @@
 /**
- * Lifecycle phase of a single dependency install reported via the progress
- * callback.
+ * Lifecycle phase of dependency installation. `done` can describe one package
+ * or the completed install; the shell reports `error` when installation fails.
+ *
+ * @evidence contracts/common.md#principled-implementation The finite union represents queued, transport, extraction and terminal reporting phases shared by the installer and shell.
+ * @evidence contracts/common.md#clear-and-simple-design A named phase union lets event consumers share labels without depending on installer control flow.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Phase constants are supported progress states rather than package-specific cases.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes per-package phases from aggregate completion, with tag separation following the documentation skill.
  */
 export type IPlaygroundDependencyProgressPhase = "queued" | "resolve" | "download" | "extract" | "skip" | "error" | "done";

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

@@ -1,4 +1,11 @@
-/** 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/lib/src/structures/IPlaygroundExample.d.ts

@@ -2,6 +2,11 @@
  * 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;

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

@@ -1,5 +1,12 @@
 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/lib/src/structures/IPlaygroundShellProps.d.ts

@@ -8,6 +8,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 {
     /**
@@ -30,39 +35,39 @@ export interface IPlaygroundShellProps {
     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.
+     * 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.
      * Sites typically pass `<a href="/">SiteName</a>`.
@@ -73,5 +78,34 @@ 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/lib/src/structures/ISourceEditorProps.d.ts

@@ -3,10 +3,16 @@
  * 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
@@ -16,3 +22,12 @@ export interface ISourceEditorProps {
     /** 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;