@ttsc/playground 0.30.4 → 0.31.0

package/src/sandbox/loadTypiaRuntimePack.ts

@@ -31,6 +31,28 @@ const packCache = new Map<string, RuntimePackEntry>();
  * attempt; rejection removes it from the cache so the next call retries from
  * scratch. Successful packs remain cached. Nothing else ends the load: how long
  * a fetch takes belongs to the network, not to a number chosen here.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Fetch, AbortController and Promise sharing implement the site-selected
+ *   runtime-pack transport. The loader returns source records for the existing
+ *   resolver rather than evaluating packages or introducing another module
+ *   protocol.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The URL map owns shared attempt identity; cancellation helpers isolate
+ *   event cleanup from transport decoding and the resolver owns evaluation.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The URL comes from the caller, and load failures remain failures. Shared
+ *   cancellation is an explicit public policy rather than a fixture-specific
+ *   timeout or a replacement of fetch internals; rejection removes the owned
+ *   entry instead of returning a fabricated empty pack.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native JSDoc separates the per-URL purpose from shared cancellation,
+ *   rejection eviction and network waiting policy. Those reasons follow the
+ *   documentation skill, and ILoadTypiaRuntimePackOptions documents the
+ *   cancellation scope.
  */
 export function loadTypiaRuntimePack(
   url: string,
@@ -62,12 +84,23 @@ export function loadTypiaRuntimePack(
       );
 
     phase = `reading JSON from ${url}`;
-    return (await raceRuntimePackCancellation(
+    const pack: unknown = await raceRuntimePackCancellation(
       response.json(),
       cancellation.promise,
       controller.signal,
       () => phase,
-    )) as Record<string, string>;
+    );
+    if (
+      !pack ||
+      typeof pack !== "object" ||
+      Array.isArray(pack) ||
+      !Object.values(pack).every((value) => typeof value === "string")
+    ) {
+      throw new Error(
+        "loadTypiaRuntimePack: expected a source-text record map.",
+      );
+    }
+    return pack as Record<string, string>;
   })()
     .catch((error) => {
       if (packCache.get(url) === entry) packCache.delete(url);

package/src/structures/IBuildTsconfigOptions.ts

@@ -1,19 +1,31 @@
-/** Options accepted by {@link buildTsconfigJSON}. */
+/**
+ * Options accepted by {@link buildTsconfigJSON}; extra compiler entries override
+ * the module and directory defaults during serialization.
+ *
+ * @evidence contracts/common.md#principled-implementation Required module spelling and optional JSON-compatible overrides express the emitted compiler configuration, not compiler validation.
+ * @evidence contracts/common.md#clear-and-simple-design A flat options record separates compiler entries from project include globs without another configuration layer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Literal module choices are supported compiler settings; callers supply extensions through compilerOptions.
+ * @evidence contracts/common.md#meaningful-documentation JSDoc states override precedence, directory defaults and emit purpose; paragraphs and member spacing follow the documentation skill.
+ */
 export interface IBuildTsconfigOptions {
   /**
    * Module emit shape. Sites preview-render ESM, then re-run as CommonJS for
    * the in-page `new Function` sandbox.
    */
   module: "ESNext" | "CommonJS";
+
   /** Output directory relative to project root. Defaults to `"dist"`. */
   outDir?: string;
+
   /** Source root relative to project root. Defaults to `"src"`. */
   rootDir?: string;
+
   /**
    * Extra entries spliced into `compilerOptions`. Use for plugins, paths, lib
    * overrides, etc.
    */
   compilerOptions?: Record<string, unknown>;
+
   /** Project `include` globs. Defaults to `["src"]`. */
   include?: readonly string[];
 }

package/src/structures/ICompilerService.ts

@@ -7,12 +7,21 @@ 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,
@@ -22,6 +31,11 @@ export interface ICompilerService {
    * 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>;
 
@@ -29,6 +43,11 @@ export interface ICompilerService {
    * 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>;
 
@@ -36,39 +55,115 @@ export interface ICompilerService {
    * 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 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> {
@@ -77,19 +172,41 @@ export namespace ICompilerService {
     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;
+
     /** 1-based column number. */
     column: number;
+
     /** Length of the span in source characters; at least 1. */
     length: number;
+
     severity: "error" | "warning";
     message: string;
+
     /** 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/src/structures/IConsoleMessage.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/src/structures/ICreateCompilerClientOptions.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/src/structures/ICreateWorkerCompilerOptions.ts

@@ -1,12 +1,21 @@
 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;
+
   /** 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.
@@ -15,8 +24,10 @@ export interface ICreateWorkerCompilerOptions {
 
   /** 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;
 
@@ -33,8 +44,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/src/structures/IInstallTypiaSourcePackOptions.ts

@@ -1,20 +1,30 @@
+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. */
   url: string;
+
   /**
    * Where to mount the pack inside the MemFS. Defaults to `/work/node_modules`,
    * matching `DEFAULT_WORK_DIR + "/node_modules"`.
    */
   mountRoot?: string;
+
   /** Cancel the shared in-flight load. */
   signal?: AbortSignal;
+
   /**
    * 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/src/structures/ILintPluginConfig.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/src/structures/ILoadTypiaRuntimePackOptions.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/src/structures/IOptionToggle.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/src/structures/IPlaygroundDependencyInstallOptions.ts

@@ -1,10 +1,18 @@
 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.
    *
@@ -12,16 +20,27 @@ export interface IPlaygroundDependencyInstallOptions {
    * active requests before a tarball is reused.
    */
   installedDependencies?: Iterable<IPlaygroundInstalledDependency>;
+
   /**
    * Legacy name-only skip list.
    *
    * Prefer `installedDependencies`; names alone cannot validate later ranges.
    */
   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.
    *
@@ -29,14 +48,45 @@ export interface IPlaygroundDependencyInstallOptions {
    * response's `Content-Length`.
    */
   maxTarballBytes?: number;
+
   /**
    * Maximum expanded tar bytes accepted for one npm package.
    *
    * Defaults to 64 MiB and is enforced while gzip output is streamed.
    */
   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/src/structures/IPlaygroundDependencyInstallResult.ts

@@ -1,22 +1,33 @@
 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[];
+
   /** Packages whose tarballs were downloaded and unpacked by this call. */
   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.

package/src/structures/IPlaygroundDependencyPackage.ts

@@ -1,8 +1,18 @@
-/** 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. */
   registryName: string;
+
   version: string;
   tarball: string;
   fileCount: number;

package/src/structures/IPlaygroundDependencyProgress.ts

@@ -1,6 +1,14 @@
 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/src/structures/IPlaygroundDependencyProgressPhase.ts

@@ -1,6 +1,11 @@
 /**
- * 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"