@ttsc/playground 0.30.4 → 0.31.1

package/src/compiler/pickEmittedJS.ts

@@ -1,18 +1,35 @@
 /**
  * Pick the most likely emitted JavaScript file from a compile result's output
- * map. Tries common paths first, then falls back to the first `.js` entry.
- * Returns null when no `.js` was emitted.
+ * map. Tries the default playground layout (`rootDir` `src`, `outDir` `dist`,
+ * which emits `dist/playground.js` for `src/playground.ts`) and other common
+ * paths first, then falls back to the first `.js` entry. Returns null when no
+ * `.js` was emitted.
+ *
+ * @evidence contracts/common.md#principled-implementation The first candidate is the default playground layout (the entry's path below the default `src` root under `dist`), the others cover layouts rooted at the project; the first remaining JavaScript entry is an explicitly heuristic fallback, not a general entrypoint solver.
+ * @evidence contracts/common.md#clear-and-simple-design A small selector separates UI output choice from compiler emit configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Layout candidates are product defaults rather than fixture filenames, and absent JavaScript remains null.
+ * @evidence contracts/common.md#meaningful-documentation Native prose honestly documents priority and heuristic fallback, separated from tags under the documentation skill.
  */
 export function pickEmittedJS(
   output: Record<string, string>,
   entryFile: string,
 ): string | null {
   const base = entryFile.replace(/\.[cm]?tsx?$/i, ".js");
-  const candidates = [`dist/${base}`, `dist/src/${base}`, `src/${base}`, base];
+  // `buildTsconfigJSON` roots sources at `src` and emits to `dist`, so the
+  // default entry `src/playground.ts` is reported as `dist/playground.js`.
+  const underSrcRoot = base.replace(/^src\//, "");
+  const candidates = [
+    `dist/${underSrcRoot}`,
+    `dist/${base}`,
+    `dist/src/${base}`,
+    `src/${base}`,
+    base,
+  ];
   for (const key of candidates) {
     if (output[key] !== undefined) return output[key];
   }
-  const jsKeys = Object.keys(output).filter((k) => k.endsWith(".js"));
-  if (jsKeys.length > 0) return output[jsKeys[0]!] ?? null;
+  for (const key of Object.keys(output)) {
+    if (key.endsWith(".js")) return output[key] ?? null;
+  }
   return null;
 }

package/src/npm/collectExternalPackageNames.ts

@@ -4,6 +4,23 @@ import { packageNameFromSpecifier } from "./packageNameFromSpecifier";
 /**
  * Scan `source` for `import` / `require` specifiers and return the unique
  * sorted list of bare npm package names that are not in `ignoredPackages`.
+ *
+ * This is a lexical discovery pass, not name binding: a locally shadowed direct
+ * require call still looks like a dependency request. Computed strings are
+ * omitted.
+ *
+ * Static arguments are quoted strings and substitution-free, escape-free
+ * templates (`require(`x`)`, `import(`x`)`). Deliberate limits of the
+ * TypeScript-source lane: JSX is not lexed (the playground entry is a `.ts`
+ * file), so quote or `import` text in JSX children can be misread; a type
+ * argument between the callee and its parenthesis (`require<T>("x")`) is not
+ * recognized because `require` is not generic; and a source-phase import
+ * (`import source x from "y"`) collects `y`, the package it loads.
+ *
+ * @evidence contracts/common.md#principled-implementation Tokenization distinguishes executable quoted and static-template specifiers from inert comments, strings and regex bodies; package-name normalization and a Set produce unique sorted install requests. Lexical discovery does not resolve shadowed require bindings.
+ * @evidence contracts/common.md#clear-and-simple-design Lexer, module-construct recognition and package filtering are separate local responsibilities, without importing the full compiler into browser keystroke discovery.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ignored package names are explicit caller policy; source matching does not fabricate dependency results for known examples.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states discovery domain and binding limitations; helper comments explain escaped strings and lexical boundaries under the documentation skill.
  */
 export function collectExternalPackageNames(
   source: string,
@@ -33,14 +50,26 @@ export function collectExternalPackageNames(
 function collectModuleSpecifiers(source: string): string[] {
   const tokens = tokenize(source);
   const out: string[] = [];
+  // A quoted literal only; `import "x"` and `from "x"` cannot take a template.
+  const asQuoted = (token: Token | undefined): string | null =>
+    token && token.kind === "string" && !token.template ? token.value : null;
+  // A call argument may also be a static template: `require(`x`)`.
   const asString = (token: Token | undefined): string | null =>
     token && token.kind === "string" ? token.value : null;
   const isOpenParen = (token: Token | undefined): boolean =>
     token !== undefined && token.kind === "punct" && token.value === "(";
-  const isMemberAccess = (token: Token | undefined): boolean =>
-    token !== undefined &&
-    token.kind === "punct" &&
-    (token.value === "." || token.value === "?.");
+  const isPunct = (token: Token | undefined, value: string): boolean =>
+    token !== undefined && token.kind === "punct" && token.value === value;
+  // `obj.name`, `obj?.name` and `this.#name` are not the free binding. The
+  // three dots of a spread are not a member access.
+  const isMemberAccessAt = (index: number): boolean => {
+    const previous = tokens[index - 1];
+    if (isPunct(previous, "#") || isPunct(previous, "?.")) return true;
+    if (!isPunct(previous, ".")) return false;
+    return !(
+      isPunct(tokens[index - 2], ".") && isPunct(tokens[index - 3], ".")
+    );
+  };
   const isOptionalChain = (token: Token | undefined): boolean =>
     token !== undefined && token.kind === "punct" && token.value === "?.";
 
@@ -50,7 +79,7 @@ function collectModuleSpecifiers(source: string): string[] {
 
     if (token.value === "require") {
       // `obj.require(...)` is an unrelated method call, not CommonJS require.
-      if (isMemberAccess(tokens[i - 1])) continue;
+      if (isMemberAccessAt(i)) continue;
       const optional =
         isOptionalChain(tokens[i + 1]) && isOpenParen(tokens[i + 2]);
       if (isOpenParen(tokens[i + 1]) || optional) {
@@ -62,7 +91,7 @@ function collectModuleSpecifiers(source: string): string[] {
 
     if (token.value === "import" || token.value === "export") {
       // `foo.import(...)` / `import.meta` are not module-loading imports.
-      if (token.value === "import" && isMemberAccess(tokens[i - 1])) continue;
+      if (token.value === "import" && isMemberAccessAt(i)) continue;
       // Dynamic `import("x")`.
       if (token.value === "import" && isOpenParen(tokens[i + 1])) {
         const spec = asString(tokens[i + 2]);
@@ -71,7 +100,7 @@ function collectModuleSpecifiers(source: string): string[] {
       }
       // Side-effect `import "x"`.
       if (token.value === "import") {
-        const bare = asString(tokens[i + 1]);
+        const bare = asQuoted(tokens[i + 1]);
         if (bare !== null) {
           out.push(bare);
           continue;
@@ -103,7 +132,9 @@ function findFromSpecifier(tokens: Token[], start: number): string | null {
       return null;
     if (token.kind === "word" && token.value === "from") {
       const next = tokens[i + 1];
-      return next && next.kind === "string" ? next.value : null;
+      return next && next.kind === "string" && !next.template
+        ? next.value
+        : null;
     }
   }
   return null;
@@ -114,14 +145,16 @@ type Token =
   | { kind: "word"; value: string }
   // A single- or double-quoted string literal, with escapes decoded to their
   // literal characters so a specifier survives unchanged.
-  | { kind: "string"; value: string }
+  | { kind: "string"; value: string; template?: true }
   // A punctuation token; compound forms are retained where lexical state or
   // module-call recognition depends on them.
   | {
       kind: "punct";
       value: string;
+
       /** Whether a slash after this closing delimiter begins a regex literal. */
       regexAllowedAfter?: boolean;
+
       /** Whether this closes a function parameter list for an expression. */
       functionBodyIsExpression?: boolean;
     }
@@ -362,7 +395,7 @@ function tokenize(source: string): Token[] {
     // Line comment.
     if (c === "/" && source[i + 1] === "/") {
       i += 2;
-      while (i < n && source[i] !== "\n") i++;
+      while (i < n && !isLineTerminator(source[i]!)) i++;
       continue;
     }
     // Block comment.
@@ -390,9 +423,12 @@ function tokenize(source: string): Token[] {
     // JavaScript and must receive the same lexical treatment as top-level code.
     if (c === "`") {
       i++;
+      // A template with no substitution and no escape is one static string.
+      let staticValue: string | null = "";
       while (i < n) {
         const d = source[i];
         if (d === "\\") {
+          staticValue = null;
           i += 2;
           continue;
         }
@@ -403,15 +439,20 @@ function tokenize(source: string): Token[] {
         if (d === "$" && source[i + 1] === "{") {
           const start = i + 2;
           const end = findTemplateSubstitutionEnd(source, start);
+          staticValue = null;
           context.pushOther();
-          tokens.push(...tokenize(source.slice(start, end)));
+          for (const entryToAppend of tokenize(source.slice(start, end)))
+            tokens.push(entryToAppend);
           context.pushOther();
           i = end < n ? end + 1 : end;
           continue;
         }
+        if (staticValue !== null) staticValue += d;
         i++;
       }
-      context.pushOther();
+      if (staticValue !== null && source[i - 1] === "`")
+        tokens.push({ kind: "string", value: staticValue, template: true });
+      else context.pushOther();
       continue;
     }
     // Identifier / keyword.
@@ -475,7 +516,7 @@ function findTemplateSubstitutionEnd(source: string, start: number): number {
     }
     if (c === "/" && source[i + 1] === "/") {
       i += 2;
-      while (i < source.length && source[i] !== "\n") i++;
+      while (i < source.length && !isLineTerminator(source[i]!)) i++;
       continue;
     }
     if (c === "/" && source[i + 1] === "*") {

package/src/npm/installPlaygroundDependencies.ts

@@ -32,8 +32,16 @@ const DEFAULT_MAX_UNPACKED_BYTES = 64 * 1024 * 1024;
  * required, optional, and peer dependency fields. Passing a prior call's
  * `resolvedDependencies` validates new edges against the exact mounted graph
  * and reuses compatible packages without downloading their tarballs again. The
- * walk is bounded by `maxPackages` to keep a single keystroke from exhausting
- * the tab's network/memory budget.
+ * walk is bounded by the nonnegative safe-integer `maxPackages` to keep a
+ * single keystroke from exhausting the tab's network/memory budget. The cap
+ * counts distinct names completed in this call, including mounted packages
+ * revalidated and optional packages omitted. Unrequested mounted state does not
+ * consume this call's budget; zero permits no queued package work.
+ *
+ * @evidence contracts/common.md#principled-implementation The queue unifies required ranges per exposed name and registry identity, pins reused exact versions and rejects incompatible required edges. Optional edges refine only compatible solves; verified tar bytes are confined before files enter consumer namespaces.
+ * @evidence contracts/common.md#clear-and-simple-design Graph coordination stays here while registry transport, version selection, archive validation and file mapping have explicit helper boundaries.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional omissions are declared npm semantics; required failures, alias conflicts and integrity failures remain failures instead of fabricated mounted state. Name-only legacy skip state is documented as unable to validate versions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain prior graph reuse and package budgets; queue comments explain late constraints and optional-to-required transitions under the documentation skill.
  */
 export async function installPlaygroundDependencies(
   packageNames: Iterable<string>,
@@ -44,6 +52,10 @@ export async function installPlaygroundDependencies(
     throw new Error("installPlaygroundDependencies requires fetch.");
   }
   throwIfAborted(options.signal);
+  const maxPackages = options.maxPackages ?? DEFAULT_MAX_PACKAGES;
+  if (!Number.isSafeInteger(maxPackages) || maxPackages < 0) {
+    throw new Error("maxPackages must be a non-negative safe integer.");
+  }
 
   const ignored = new Set(
     options.ignoredPackages ?? BUILT_IN_PLAYGROUND_PACKAGES,
@@ -65,9 +77,10 @@ export async function installPlaygroundDependencies(
       );
     }
     if (previous !== undefined) {
-      previous.requests.push(
-        ...dependency.requests.map((request) => ({ ...request })),
-      );
+      for (const entryToAppend of dependency.requests.map((request) => ({
+        ...request,
+      })))
+        previous.requests.push(entryToAppend);
       continue;
     }
     installedDependencies.set(dependency.name, {
@@ -75,7 +88,6 @@ export async function installPlaygroundDependencies(
       requests: dependency.requests.map((request) => ({ ...request })),
     });
   }
-  const maxPackages = options.maxPackages ?? DEFAULT_MAX_PACKAGES;
   const maxTarballBytes = options.maxTarballBytes ?? DEFAULT_MAX_TARBALL_BYTES;
   const maxUnpackedBytes =
     options.maxUnpackedBytes ?? DEFAULT_MAX_UNPACKED_BYTES;

package/src/npm/internal/npmRegistry.ts

@@ -14,6 +14,15 @@ interface IPackageJson {
   peerDependenciesMeta?: Record<string, { optional?: boolean }>;
 }
 
+/**
+ * Version-specific registry manifest; absent dist metadata cannot supply a
+ * tarball.
+ *
+ * @evidence contracts/common.md#principled-implementation Identity, dependency fields and optional distribution witnesses express the registry subset consumed by version selection and authentication.
+ * @evidence contracts/common.md#clear-and-simple-design Registry metadata remains separate from unpacked files and mounted state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional authentication fields represent historical metadata compatibility, not fabricated integrity evidence.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states subset and absent distribution meaning, separated from tags under the documentation skill.
+ */
 export interface INpmVersionMetadata {
   name: string;
   version: string;
@@ -28,17 +37,42 @@ export interface INpmVersionMetadata {
   };
 }
 
+/**
+ * Registry packument subset, indexed by exact version with optional tag
+ * aliases.
+ *
+ * @evidence contracts/common.md#principled-implementation Version entries and dist-tag mappings provide the domain over which semver constraints are resolved.
+ * @evidence contracts/common.md#clear-and-simple-design The packument index is independent of a particular install request or mounted graph.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing entries remain representable instead of inventing a version from a requested tag.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines version indexing and tag purpose with tag separation under the documentation skill.
+ */
 export interface INpmMetadata {
   name: string;
   "dist-tags"?: Record<string, string>;
   versions: Record<string, INpmVersionMetadata | undefined>;
 }
 
+/**
+ * Confined package-relative text files and the decoded manifest subset.
+ *
+ * @evidence contracts/common.md#principled-implementation Files omit the safe archive root while packageJson supplies dependency metadata for graph traversal.
+ * @evidence contracts/common.md#clear-and-simple-design Extraction output is separate from consumer-specific mounted path maps.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Archive contents determine files without consumer-specific manufactured declarations.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines confinement and path namespace with tag separation under the documentation skill.
+ */
 export interface IUnpackedPackage {
   files: Record<string, string>;
   packageJson: IPackageJson;
 }
 
+/**
+ * One exposed package queued for registry solving, retaining all active edges.
+ *
+ * @evidence contracts/common.md#principled-implementation Exposed name and optional registryName distinguish aliases; requests preserve intersecting ranges and origin while optionality describes whether omission is permitted.
+ * @evidence contracts/common.md#clear-and-simple-design Mutable queue coordination is isolated from published immutable identity records.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Explicit edge state prevents silently ignoring a late required constraint.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states queue role and active-edge retention with tag separation under the documentation skill.
+ */
 export interface IQueueItem {
   name: string;
   range: string;
@@ -48,12 +82,28 @@ export interface IQueueItem {
   requests?: IVersionRequest[];
 }
 
+/**
+ * A normalized semver range or registry tag together with requesting origin.
+ *
+ * @evidence contracts/common.md#principled-implementation Range and origin retain the constraint while optional marks whether incompatible omission is allowed.
+ * @evidence contracts/common.md#clear-and-simple-design This edge record is independent of mounted package identity and registry transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Optionality is a declared graph distinction, not guessed from a missing package response.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states range, origin and omission role with tag separation under the documentation skill.
+ */
 export interface IVersionRequest {
   optional: boolean;
   range: string;
   requester: string;
 }
 
+/**
+ * Standard string-URL fetch transport used by registry and tarball requests.
+ *
+ * @evidence contracts/common.md#principled-implementation RequestInit and Response preserve status, headers, abort and body contracts needed by browser installation.
+ * @evidence contracts/common.md#clear-and-simple-design A named callable signature keeps transport injectable without exposing solver state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Injection uses an explicit callback instead of replacing global transport internals.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines transport responsibility with tag separation under the documentation skill.
+ */
 export type FetchLike = (
   input: string,
   init?: RequestInit,
@@ -69,12 +119,30 @@ const TEXT_FILE_REGEXP =
 export const DECLARATION_FILE_REGEXP = /\.d\.[cm]?ts$/i;
 const RUNTIME_FILE_REGEXP = /(^package\.json$|\.([cm]?js|json)$)/i;
 
+/**
+ * Preserve the signal's abort reason; use AbortError only when no reason
+ * exists.
+ *
+ * @evidence contracts/common.md#principled-implementation AbortSignal.aborted gates rejection and its reason remains the deciding thrown value.
+ * @evidence contracts/common.md#clear-and-simple-design One guard centralizes cancellation semantics across transport and archive phases.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cancellation is caller policy rather than a fabricated timeout or successful empty result.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains reason preservation with tag separation under the documentation skill.
+ */
 export function throwIfAborted(signal: AbortSignal | undefined): void {
   if (!signal?.aborted) return;
   if (signal.reason !== undefined) throw signal.reason;
   throw new DOMException("The operation was aborted.", "AbortError");
 }
 
+/**
+ * Fetch the public registry packument; only an optional package's 404 is
+ * omitted.
+ *
+ * @evidence contracts/common.md#principled-implementation Encoded package identity forms the registry URL; status handling distinguishes an allowed optional absence from transport failure and decodes the requested metadata.
+ * @evidence contracts/common.md#clear-and-simple-design Transport and abort helpers serve one metadata request while version solving stays separate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the declared optional-404 contract yields null; other failures cannot masquerade as installed metadata.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies registry ownership and omission semantics with tag separation under the documentation skill.
+ */
 export async function fetchNpmMetadata(
   fetchImpl: FetchLike,
   packageName: string,
@@ -115,6 +183,15 @@ export async function fetchNpmMetadata(
   return metadata;
 }
 
+/**
+ * Select the highest published exact version satisfying every requested range;
+ * tags resolve through registry metadata and missing candidates throw.
+ *
+ * @evidence contracts/common.md#principled-implementation Semver validates ranges and tag mappings, then filters published versions by the intersection before highest-version selection.
+ * @evidence contracts/common.md#clear-and-simple-design This pure selector owns constraint intersection while callers own optional edges and mounted-version pins.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No package-specific version is chosen and incompatible constraints remain an error rather than an arbitrary latest fallback.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines highest-version and failure semantics with tag separation under the documentation skill.
+ */
 export function selectVersion(
   metadata: INpmMetadata,
   ranges: readonly string[] | string,
@@ -145,7 +222,9 @@ export function selectVersion(
       semverRanges.every((range) => satisfies(version, range)) &&
       (taggedVersions.size === 0 || taggedVersions.has(version)),
   );
-  const selected = maxSatisfying(candidates, "*");
+  // Candidates already satisfy every requested constraint, including the
+  // explicit prerelease admission of a range or exact registry tag.
+  const selected = maxSatisfying(candidates, "*", { includePrerelease: true });
   if (selected) return selected;
   throw new Error(
     `No version of ${metadata.name} satisfies ${requested
@@ -154,6 +233,15 @@ export function selectVersion(
   );
 }
 
+/**
+ * Read compressed archive bytes within the validated budget; cancel unused
+ * bodies on status failure, excessive declared length or cancellation.
+ *
+ * @evidence contracts/common.md#principled-implementation Header checks reject obvious excess while streamed accounting enforces actual compressed bytes even when Content-Length is absent or inaccurate.
+ * @evidence contracts/common.md#clear-and-simple-design Fetching and body-budget enforcement delegate cancellation and bounded collection to shared helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every archive receives the same budget and failures remain visible without returning truncated synthetic success.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state byte domain and body disposal with tag separation under the documentation skill.
+ */
 export async function downloadTarball(
   fetchImpl: FetchLike,
   tarball: string,
@@ -190,7 +278,16 @@ export async function downloadTarball(
   );
 }
 
-/** Verify registry authentication metadata against the compressed bytes. */
+/**
+ * Verify registry authentication metadata against compressed bytes. The
+ * strongest supported SRI group wins; absent SRI falls back to shasum, and
+ * absent both is accepted without an authentication claim.
+ *
+ * @evidence contracts/common.md#principled-implementation Web Crypto digests the actual compressed bytes and equalBytes compares against the strongest supported witnesses; malformed metadata or mismatch rejects.
+ * @evidence contracts/common.md#clear-and-simple-design Authentication precedes decompression and keeps digest parsing separate from byte comparison.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Historical unauthenticated metadata is explicitly supported; missing witnesses are not fabricated and weaker hashes cannot override a failing stronger witness.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states hash precedence and unauthenticated compatibility with tag separation under the documentation skill.
+ */
 export async function verifyTarball(
   tgz: ArrayBuffer,
   dist: { integrity?: string; shasum?: string },
@@ -199,7 +296,10 @@ export async function verifyTarball(
   throwIfAborted(signal);
   if (dist.integrity !== undefined) {
     const candidates = parseIntegrity(dist.integrity);
-    const strength = Math.max(...candidates.map(({ rank }) => rank));
+    const strength = candidates.reduce(
+      (maximum, { rank }) => Math.max(maximum, rank),
+      0,
+    );
     const strongest = candidates.filter(
       (candidate) => candidate.rank === strength,
     );
@@ -231,6 +331,16 @@ export async function verifyTarball(
   }
 }
 
+/**
+ * Expand one bounded gzip archive and extract supported text files below one
+ * safe archive root. Unsupported tar entry kinds are omitted; truncated bodies,
+ * unsafe paths and missing end markers reject the archive.
+ *
+ * @evidence contracts/common.md#principled-implementation Safe integer sizes and padded extents bound every tar slice; PAX and GNU path overrides still pass the common confinement gate before text decoding.
+ * @evidence contracts/common.md#clear-and-simple-design The sequential tar reader delegates gzip budgeting, path validation and header decoding to focused local helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported metadata paths use format rules rather than known package names; unsafe entries are rejected instead of redirected into a guessed mount.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state extraction domain and failure boundaries; confinement comments explain variable npm roots under the documentation skill.
+ */
 export async function unpackNpmTarball(
   tgz: ArrayBuffer,
   signal: AbortSignal | undefined,
@@ -336,12 +446,29 @@ async function gunzip(
   );
 }
 
+/**
+ * One package's files mapped to compiler, editor URI and runtime namespaces.
+ *
+ * @evidence contracts/common.md#principled-implementation Distinct string maps carry the path conventions expected by each consumer without changing the source text.
+ * @evidence contracts/common.md#clear-and-simple-design The three named lanes make downstream mounting explicit and avoid repeated namespace inference.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Namespace mapping follows consumer protocols rather than per-package exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines the consumer lanes with tag separation under the documentation skill.
+ */
 export interface IMountedFiles {
   compilerFiles: Record<string, string>;
   editorLibs: Record<string, string>;
   runtimeFiles: Record<string, string>;
 }
 
+/**
+ * Map confined relative files to consumer namespaces, selecting declarations
+ * for Monaco and JavaScript/JSON for the CommonJS runtime pack.
+ *
+ * @evidence contracts/common.md#principled-implementation Each source file gets a compiler key; extension predicates select appropriate editor and runtime content without coercing text.
+ * @evidence contracts/common.md#clear-and-simple-design One traversal constructs all three views while archive confinement stays with extraction.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Extension selection applies uniformly to packages rather than synthesizing missing declarations or runtime code.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines input provenance and view selection with tag separation under the documentation skill.
+ */
 export function mountPackageFiles(
   packageName: string,
   files: Record<string, string>,
@@ -364,6 +491,15 @@ export function mountPackageFiles(
   return { compilerFiles, editorLibs, runtimeFiles };
 }
 
+/**
+ * Publish supported registry edges: optional dependencies override regular
+ * dependencies of the same name; optional peers are not installed.
+ *
+ * @evidence contracts/common.md#principled-implementation npm dependency precedence and peer optionality determine edge requirements; registry range classification excludes unsupported source transports.
+ * @evidence contracts/common.md#clear-and-simple-design This operation emits normalized graph edges while queue deduplication and version solving remain with the installer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Required peers remain required; unsupported non-registry sources are omitted as a declared browser-installer limitation, not silently claimed installed.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states dependency precedence and optional peers; inline comments explain required-peer propagation under the documentation skill.
+ */
 export function enqueuePackageDependencies(
   packageJson: {
     dependencies?: Record<string, string>;
@@ -416,6 +552,14 @@ function isRegistryRange(range: string): boolean {
   return spec.length > 0 && encodeURIComponent(spec) === spec;
 }
 
+/**
+ * Convert an npm identity to DefinitelyTyped spelling, flattening scoped names.
+ *
+ * @evidence contracts/common.md#principled-implementation Unscoped names gain @types/ and valid scoped names use the established scope__name convention.
+ * @evidence contracts/common.md#clear-and-simple-design One name mapping stays separate from whether a declaration fallback is needed.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The convention applies to every package identity rather than maintaining a list of known declaration packages.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines the mapping purpose with tag separation under the documentation skill.
+ */
 export function toTypesPackageName(packageName: string): string {
   if (!packageName.startsWith("@")) return `@types/${packageName}`;
   const [scope, name] = packageName.slice(1).split("/");
@@ -665,7 +809,15 @@ function formatByteLimit(bytes: number): string {
   return `${bytes.toLocaleString("en-US")}-byte`;
 }
 
-/** Validate one public npm archive byte budget before starting related work. */
+/**
+ * Validate an archive byte budget as a positive safe integer before related
+ * work.
+ *
+ * @evidence contracts/common.md#principled-implementation Safe positive integers support exact byte accounting and a branded result distinguishes budgets that passed the numeric gate.
+ * @evidence contracts/common.md#clear-and-simple-design One validation gate serves compressed and expanded budgets without duplicating numeric policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Validation is uniform and rejects invalid limits instead of selecting hidden fixture-specific defaults.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states units, positivity and validation timing with tag separation under the documentation skill.
+ */
 export function validateNpmByteLimit(
   maxBytes: number,
   kind: "compressed" | "expanded",

package/src/npm/packageNameFromSpecifier.ts

@@ -48,6 +48,11 @@ const BUILTIN_MODULES = new Set([
  *
  * Returns `null` for relative paths, hash imports, URL specifiers, and Node
  * built-in modules — the caller doesn't install those from npm.
+ *
+ * @evidence contracts/common.md#principled-implementation Prefix classification removes non-registry inputs and scoped-name slicing keeps both scope and package while discarding subpaths.
+ * @evidence contracts/common.md#clear-and-simple-design One classifier isolates package identity from dependency scanning and installation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The built-in table is the pinned Node built-in module root list, not special cases for individual consumer packages.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs define rejected specifier kinds and npm-install purpose under the documentation skill.
  */
 export function packageNameFromSpecifier(specifier: string): string | null {
   const nodePrefixed = specifier.startsWith("node:");
@@ -65,6 +70,7 @@ export function packageNameFromSpecifier(specifier: string): string | null {
     const firstSlash = bare.indexOf("/");
     if (firstSlash < 0) return null;
     if (firstSlash === 1) return null;
+    if (firstSlash === bare.length - 1) return null;
     const secondSlash = bare.indexOf("/", firstSlash + 1);
     if (secondSlash === firstSlash + 1) return null;
     return secondSlash < 0 ? bare : bare.slice(0, secondSlash);

package/src/react/ConsoleViewer.tsx

@@ -9,6 +9,15 @@ interface ConsoleViewerProps {
   empty?: string;
 }
 
+/**
+ * Render captured console calls in order, with argument values formatted as
+ * React text and nested containers truncated after four levels.
+ *
+ * @evidence contracts/common.md#principled-implementation Console types choose display colors and argument values become escaped React text; depth-limited container recursion handles circular values. Object entry access can invoke getters, so formatting is not a user-code isolation boundary.
+ * @evidence contracts/common.md#clear-and-simple-design Row layout delegates color and value formatting to local helpers while the caller owns captured-message state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Color choices are presentation constants and the depth limit is a general rendering bound, not source-specific output substitution.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states ordering, text rendering and truncation semantics, separated from tags under the documentation skill.
+ */
 export function ConsoleViewer({
   messages,
   empty = "No output yet. Click Execute to run the compiled JavaScript.",
@@ -79,6 +88,7 @@ function formatValue(value: unknown, depth = 0): JSX.Element {
     return <span className="text-slate-500">undefined</span>;
   if (typeof value === "function")
     return <span className="text-slate-500">[Function]</span>;
+  if (depth > 4) return <span className="text-slate-500">[...]</span>;
   if (Array.isArray(value))
     return (
       <span>
@@ -101,7 +111,6 @@ function formatValue(value: unknown, depth = 0): JSX.Element {
   try {
     const entries = Object.entries(value as Record<string, unknown>);
     if (entries.length === 0) return <span>{"{}"}</span>;
-    if (depth > 4) return <span className="text-slate-500">[...]</span>;
     return (
       <span>
         {"{"}

package/src/react/DependencyProgressModal.tsx

@@ -7,6 +7,15 @@ interface DependencyProgressModalProps {
   packages: readonly string[];
 }
 
+/**
+ * Present current installation phase and package-count progress; null hides
+ * the modal and the package chips show at most eight names.
+ *
+ * @evidence contracts/common.md#principled-implementation Completed/total package counts produce a clamped display ratio and optional version joins only present package identity.
+ * @evidence contracts/common.md#clear-and-simple-design The component is a pure progress view; installation and cancellation stay with its owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The minimum visible bar and chip limit are UI presentation policy rather than fabricated install outcomes.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines visibility, count units and chip truncation with tag separation under the documentation skill.
+ */
 export function DependencyProgressModal({
   progress,
   packages,

package/src/react/DiagnosticsPanel.tsx

@@ -4,6 +4,15 @@ import { useState } from "react";
 
 import type { ICompilerService } from "../structures/ICompilerService";
 
+/**
+ * Display severity totals and a collapsible list of supplied diagnostic
+ * locations; expansion changes presentation without rerunning compilation.
+ *
+ * @evidence contracts/common.md#principled-implementation Counts derive from actual severity fields and location text uses the normalized one-based diagnostic contract.
+ * @evidence contracts/common.md#clear-and-simple-design Local expansion state owns presentation only; producers own findings and failure interpretation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Empty presentation derives from the supplied list rather than inventing a successful compiler result.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains totals and expansion ownership, separated from tags under the documentation skill.
+ */
 export function DiagnosticsPanel({
   diagnostics,
 }: {