@ttsc/playground 0.30.4 → 0.31.1

package/src/react/ExamplePicker.tsx

@@ -7,10 +7,20 @@ import type { IPlaygroundExample } from "../structures/IPlaygroundExample";
 interface ExamplePickerProps {
   examples: readonly IPlaygroundExample[];
   onPick: (id: string) => void;
+
   /** Display labels for groups. Maps `group` key → rendered heading. */
   groupLabels?: Record<string, string>;
 }
 
+/**
+ * Group site examples and publish the selected id. Outside clicks and Escape
+ * close the menu; DOM listeners exist only while it is open.
+ *
+ * @evidence contracts/common.md#principled-implementation Group keys index a prototype-free record and label overrides require own properties, so arbitrary site labels remain ordinary groups; picking preserves each example's stable id.
+ * @evidence contracts/common.md#clear-and-simple-design Grouping is memoized from examples while local state owns only menu visibility; the parent owns source changes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Site-provided examples and group labels drive presentation without reserved consumer names or foreign DOM mutation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states id ownership and listener lifetime with tag separation under the documentation skill.
+ */
 export function ExamplePicker({
   examples,
   onPick,
@@ -38,11 +48,14 @@ export function ExamplePicker({
   }, [open]);
 
   const grouped = useMemo(() => {
-    return examples.reduce<Record<string, IPlaygroundExample[]>>((acc, e) => {
-      const key = e.group ?? "Examples";
-      (acc[key] ??= []).push(e);
-      return acc;
-    }, {});
+    return examples.reduce<Record<string, IPlaygroundExample[]>>(
+      (acc, e) => {
+        const key = e.group ?? "Examples";
+        (acc[key] ??= []).push(e);
+        return acc;
+      },
+      Object.create(null) as Record<string, IPlaygroundExample[]>,
+    );
   }, [examples]);
 
   if (examples.length === 0) return null;
@@ -65,7 +78,10 @@ export function ExamplePicker({
               className="border-b border-[#d8e7f4] last:border-b-0"
             >
               <div className="bg-[#f7fbff] px-3 py-1.5 font-mono text-[10px] uppercase tracking-wider text-slate-500">
-                {groupLabels?.[group] ?? group}
+                {groupLabels &&
+                Object.prototype.hasOwnProperty.call(groupLabels, group)
+                  ? (groupLabels[group] ?? group)
+                  : group}
               </div>
               {items.map((item) => (
                 <button

package/src/react/LintPane.tsx

@@ -5,6 +5,11 @@ import type { ICompilerService } from "../structures/ICompilerService";
 /**
  * Renders the lint plugin's findings in a list view. Shown by `PlaygroundShell`
  * when the active tab is "lint". Empty state is the green checkmark.
+ *
+ * @evidence contracts/common.md#principled-implementation Supplied normalized findings map to severity, code, location and message; producer failure interpretation remains outside the renderer.
+ * @evidence contracts/common.md#clear-and-simple-design This view is stateless apart from its props and does not initiate lint work.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Empty-state presentation follows the supplied result and does not discard error diagnostics.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains placement and empty presentation, separated from tags under the documentation skill.
  */
 export function LintPane({
   diagnostics,

package/src/react/OptionsPanel.tsx

@@ -10,12 +10,24 @@ interface OptionsPanelProps {
   options: ITransformOptions;
   onChange: (next: ITransformOptions) => void;
   onClose: () => void;
+
   /** Defaults to the typia + lint pair from `DEFAULT_OPTION_TOGGLES`. */
   toggles?: readonly IOptionToggle[];
+
   /** Dialog heading. Defaults to "Transform Options". */
   title?: string;
 }
 
+/**
+ * Render site-defined boolean toggles in a dialog, merging a changed flag into
+ * the controlled option record. Focus moves to the first control once when the
+ * dialog opens, Escape closes and Tab wraps within the dialog.
+ *
+ * @evidence contracts/common.md#principled-implementation Computed-key copying preserves unrelated options; focus traversal and Escape use DOM events with cleanup on callback replacement or unmount.
+ * @evidence contracts/common.md#clear-and-simple-design Parent callbacks own values and visibility while this component owns dialog focus behavior and toggle presentation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Metadata keys drive all toggles through the same supported callback rather than plugin-specific mutation paths.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states merge and keyboard behavior; prop comments state UI defaults with documentation-skill tag and member separation.
+ */
 export function OptionsPanel({
   options,
   onChange,
@@ -28,7 +40,9 @@ export function OptionsPanel({
   const toggle = (key: string) =>
     onChange({ ...options, [key]: !options[key] });
 
-  // Escape closes. Focus traps inside the dialog.
+  // Escape closes. Focus traps inside the dialog. The listener re-registers
+  // whenever the parent supplies a new `onClose`, which an inline callback does
+  // on every render, so it must not move focus.
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
       if (e.key === "Escape") {
@@ -52,13 +66,17 @@ export function OptionsPanel({
       }
     };
     window.addEventListener("keydown", onKey);
-    // Auto-focus the first focusable on mount.
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  // Auto-focus the first focusable once, when the dialog opens. Toggling an
+  // option re-renders the parent, and focus must stay on the toggled control.
+  useEffect(() => {
     const focusable = dialogRef.current?.querySelector<HTMLElement>(
       'button, input, [tabindex]:not([tabindex="-1"])',
     );
     focusable?.focus();
-    return () => window.removeEventListener("keydown", onKey);
-  }, [onClose]);
+  }, []);
 
   return (
     <div

package/src/react/PlaygroundShell.tsx

@@ -43,6 +43,19 @@ const SHARE_URL_WARN_BYTES = 2000;
 
 type Tab = "javascript" | "lint";
 
+/**
+ * Coordinate the compiler Worker, dependency graph, controlled editors and
+ * site execution hook. Compile epochs and Worker generations fence stale RPC
+ * results; Execute has its own cancellation boundary.
+ *
+ * Source-root removal replaces the Worker and all dependency maps together.
+ * Site execution owns isolation; cancellation cannot preempt synchronous code.
+ *
+ * @evidence contracts/common.md#principled-implementation Epoch and generation checks precede asynchronous state publication; serialized dependency mutations reconcile stale writes before reuse, and removed roots trigger full graph replacement. Execute receives a source snapshot and attempt signal without invalidating independent compile work.
+ * @evidence contracts/common.md#clear-and-simple-design The shell owns React state and delegates Worker transport, dependency solving, lifecycle fencing and display to their named operations; separate compile and Execute boundaries serve their different invalidation rules.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Generation resets correct actual obsolete-worker state rather than wrapping errors with unbounded retry; ordinary plugin and transport errors stay visible and only terminal runtime failures require replacement.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs define ownership, stale-result boundaries and isolation limits; local comments explain dependency replacement and callback dependencies under the documentation skill.
+ */
 export function PlaygroundShell({
   workerUrl,
   defaultScript,
@@ -103,11 +116,10 @@ export function PlaygroundShell({
   // Direct source roots selecting the mounted graph. Removing one requires a
   // full solve and worker replacement so obsolete package files cannot survive.
   const dependencyRoots = useRef<Set<string>>(new Set());
-  // Accumulated runtime-file map produced by every successful
-  // installPlaygroundDependencies call. Threaded through to executeBundle so
-  // the in-page Execute sandbox's require can resolve any npm package the
-  // user installed (without it, `import {v4} from "uuid"` compiles fine but
-  // Execute throws because the worker mounts uuid into the wasm MemFS only).
+  // Runtime-file map for the current dependency graph. Additive installs merge
+  // files; removing a source root replaces the map after a full solve. Pass it
+  // to executeBundle so its require can resolve current npm dependencies.
+  // The compiler's MemFS mount alone does not make them available to Execute.
   const runtimeDependencyFiles = useRef<Record<string, string>>({});
   const sourceVersion = useRef(0);
   const latestSource = useRef(source);

package/src/react/ResultViewer.tsx

@@ -11,13 +11,21 @@ interface ResultViewerProps {
 /**
  * Read-only Monaco pane used to render the compiled / transformed output with a
  * copy button. Wraps `<Editor readOnly>` and adds the toast UI.
+ *
+ * @evidence contracts/common.md#principled-implementation Controlled text and language select a read-only model; copy feedback follows actual clipboard settlement, and attempt identity prevents old or unmounted requests from publishing feedback.
+ * @evidence contracts/common.md#clear-and-simple-design Output viewing and local copy feedback stay separate from compilation and source editing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The read-only editor uses supported Monaco options rather than replacing editor methods.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains viewing and copy presentation; copied and failed labels distinguish actual clipboard outcomes under the documentation skill.
  */
 export function ResultViewer({ language, value }: ResultViewerProps) {
   const [copied, setCopied] = useState(false);
+  const [copyFailed, setCopyFailed] = useState(false);
+  const copyEpoch = useRef(0);
   const copiedTimer = useRef<number | null>(null);
 
   useEffect(
     () => () => {
+      ++copyEpoch.current;
       if (copiedTimer.current !== null)
         window.clearTimeout(copiedTimer.current);
     },
@@ -25,13 +33,26 @@ export function ResultViewer({ language, value }: ResultViewerProps) {
   );
 
   const onCopy = () => {
-    void navigator.clipboard.writeText(value);
-    setCopied(true);
+    const epoch = ++copyEpoch.current;
+    setCopied(false);
+    setCopyFailed(false);
     if (copiedTimer.current !== null) window.clearTimeout(copiedTimer.current);
-    copiedTimer.current = window.setTimeout(() => {
-      setCopied(false);
-      copiedTimer.current = null;
-    }, 1500);
+    copiedTimer.current = null;
+    void Promise.resolve()
+      .then(() => navigator.clipboard.writeText(value))
+      .then(
+        () => {
+          if (copyEpoch.current !== epoch) return;
+          setCopied(true);
+          copiedTimer.current = window.setTimeout(() => {
+            setCopied(false);
+            copiedTimer.current = null;
+          }, 1500);
+        },
+        () => {
+          if (copyEpoch.current === epoch) setCopyFailed(true);
+        },
+      );
   };
 
   return (
@@ -41,7 +62,7 @@ export function ResultViewer({ language, value }: ResultViewerProps) {
           onClick={onCopy}
           className="absolute right-3 top-2 z-10 rounded-md border border-[#b9d5ee] bg-white/90 px-2 py-1 font-mono text-[10px] text-[#235a97] shadow-sm transition-colors hover:bg-[#eaf4ff]"
         >
-          {copied ? "Copied ✓" : "Copy"}
+          {copied ? "Copied ✓" : copyFailed ? "Copy failed" : "Copy"}
         </button>
       )}
       <Editor

package/src/react/SourceEditor.tsx

@@ -6,6 +6,16 @@ import { useCallback, useEffect, useMemo, useRef } from "react";
 import { DEFAULT_PLAYGROUND_COMPILER_OPTIONS } from "../compiler/DEFAULT_PLAYGROUND_COMPILER_OPTIONS";
 import type { ISourceEditorProps } from "../structures/ISourceEditorProps";
 
+/**
+ * Bind controlled source text to Monaco and replace declaration libraries when
+ * their map changes. Owned extra-lib registrations are disposed on replacement
+ * and unmount; this component uses Monaco's shared TypeScript defaults.
+ *
+ * @evidence contracts/common.md#principled-implementation Controlled changes publish full text, virtual URIs identify models, and supported extra-lib disposables replace prior declarations. Monaco preview suppresses unresolved-module diagnostics; the real Worker compile remains authoritative.
+ * @evidence contracts/common.md#clear-and-simple-design Editor presentation and declaration registration stay local while source state and compiler execution remain with the parent.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Monaco's documented defaults and disposable registration APIs provide the integration boundary; suppression is preview policy rather than a change to real compiler errors.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states registration lifetime and shared defaults; inline comments explain preview limitations under the documentation skill.
+ */
 export function SourceEditor({
   value,
   onChange,

package/src/react/createCompilerClient.ts

@@ -12,6 +12,11 @@ import type { ICreateCompilerClientOptions } from "../structures/ICreateCompiler
  * One connection generation owns the cached promise and connector. A reset
  * invalidates that generation before awaiting it, so a late settlement cannot
  * replace a newer connection or clear its retry state.
+ *
+ * @evidence contracts/common.md#principled-implementation Each connection record owns its promise and connector; identity-checked failure eviction and invalidation-before-await prevent old settlements from replacing a newer generation.
+ * @evidence contracts/common.md#clear-and-simple-design A factory closure exposes only connect and reset while keeping transport state private; close sharing prevents duplicate disposal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Worker replacement uses tgrid's connector API; ordinary connection rejection remains failure rather than a synthetic driver.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs define promise ownership and stale-settlement behavior under the documentation skill; reset may wait for an underlying connection that tgrid does not expose cancellation for.
  */
 export function createCompilerClient(options: ICreateCompilerClientOptions): {
   connect(): Promise<ICompilerService>;

package/src/react/internal/PlaygroundCompilerLifecycle.ts

@@ -1,5 +1,20 @@
+/**
+ * Token for the compiler generation captured before asynchronous work.
+ *
+ * @evidence contracts/common.md#principled-implementation A live predicate compares captured epoch identity with the lifecycle's current epoch; the token does not grant ownership of a replacement Worker.
+ * @evidence contracts/common.md#clear-and-simple-design One capability hides epoch storage from callers while permitting stale-work fencing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Generation validity is actual owner identity rather than timing guesses or retries around stale state.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines capture and ownership meaning with tag separation under the documentation skill.
+ */
 export interface IPlaygroundCompilerGeneration {
-  /** Whether this token still owns the active compiler Worker generation. */
+  /**
+   * Whether this token still owns the active compiler Worker generation.
+   *
+   * @evidence contracts/common.md#principled-implementation Equality with the captured epoch determines validity synchronously before a caller publishes state.
+   * @evidence contracts/common.md#clear-and-simple-design A predicate exposes validity without exposing mutable lifecycle state.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Validity depends on ownership rather than a grace period after replacement.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states current ownership with tag separation under the documentation skill.
+   */
   isCurrent(): boolean;
 }
 
@@ -11,11 +26,24 @@ export interface IPlaygroundCompilerGeneration {
  * prevents its queued tasks from starting. New-generation tasks remain
  * serialized behind an active old task so two dependency installers can never
  * mutate the shared compiler filesystem concurrently.
+ *
+ * @evidence contracts/common.md#principled-implementation Monotonic epochs fence old callbacks and one promise chain orders mutations, retaining serialization even when an earlier task rejects.
+ * @evidence contracts/common.md#clear-and-simple-design The lifecycle owns generation and ordering only; callers provide Worker mutation, reset and metadata clearing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Stale work loses publication rights through explicit identity checks instead of compensating retries or fixed timing windows.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain invalidation and old-task serialization; operation comments define reset ordering under the documentation skill.
  */
 export class PlaygroundCompilerLifecycle {
   private epoch: number = 0;
   private queue: Promise<void> = Promise.resolve();
 
+  /**
+   * Capture the current epoch without advancing it.
+   *
+   * @evidence contracts/common.md#principled-implementation A closure over the captured scalar remains valid exactly while the owning epoch is unchanged.
+   * @evidence contracts/common.md#clear-and-simple-design Token creation exposes one predicate and keeps epoch mutation internal.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Capture uses actual generation identity rather than inspecting unrelated Worker internals.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes observation from invalidation with tag separation under the documentation skill.
+   */
   public capture(): IPlaygroundCompilerGeneration {
     const epoch = this.epoch;
     return {
@@ -23,11 +51,27 @@ export class PlaygroundCompilerLifecycle {
     };
   }
 
+  /**
+   * Advance the epoch and return the replacement generation's token.
+   *
+   * @evidence contracts/common.md#principled-implementation Incrementing the epoch makes all prior captured predicates false before replacement work begins.
+   * @evidence contracts/common.md#clear-and-simple-design One operation owns the generation transition and reuses token construction.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Invalidation changes the owning state directly instead of preserving stale assumptions beneath wrappers.
+   * @evidence contracts/common.md#meaningful-documentation Native prose defines transition and return identity with tag separation under the documentation skill.
+   */
   public invalidate(): IPlaygroundCompilerGeneration {
     this.epoch++;
     return this.capture();
   }
 
+  /**
+   * Claim replacement only if the supplied generation still owns the lifecycle.
+   *
+   * @evidence contracts/common.md#principled-implementation Synchronous validity checking and epoch advance prevent a stale claimant from invalidating newer work.
+   * @evidence contracts/common.md#clear-and-simple-design Conditional claiming delegates the actual transition to invalidate.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Stale claims return undefined rather than retrying against a replacement they do not own.
+   * @evidence contracts/common.md#meaningful-documentation Native prose defines the ownership condition with tag separation under the documentation skill.
+   */
   public invalidateIfCurrent(
     generation: IPlaygroundCompilerGeneration,
   ): IPlaygroundCompilerGeneration | undefined {
@@ -43,6 +87,11 @@ export class PlaygroundCompilerLifecycle {
    * its metadata must become empty too. A Worker-generation replacement
    * performs its own synchronous clear and prevents this stale reset from
    * clearing the replacement.
+   *
+   * @evidence contracts/common.md#principled-implementation Validity is checked before and after asynchronous reset; metadata clears only for the same Worker generation even if its source changed.
+   * @evidence contracts/common.md#clear-and-simple-design Callbacks separate Worker disposal from metadata ownership while this method orders both effects.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The reset corrects actual stale Worker contents instead of suppressing source errors or clearing a newer generation's state.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why source-version checking must follow metadata clearing under the documentation skill.
    */
   public async resetWorkerIfCurrent(
     generation: IPlaygroundCompilerGeneration,
@@ -62,6 +111,11 @@ export class PlaygroundCompilerLifecycle {
    * An RPC cannot be cancelled after it has started mutating the Worker's
    * MemFS. If its source becomes stale before completion, reset that Worker and
    * clear the matching dependency metadata before another source can reuse it.
+   *
+   * @evidence contracts/common.md#principled-implementation Both source and Worker identity gate mutation; a source becoming stale after a non-cancellable RPC triggers reset before the generation is reusable.
+   * @evidence contracts/common.md#clear-and-simple-design Mutation and reconciliation share one owning method, delegating reset ordering to the lifecycle helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Obsolete writes are removed at their owner rather than hidden by a stale-result wrapper alone.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the non-cancellable RPC and required reconciliation under the documentation skill.
    */
   public async mutateWorkerIfCurrent(
     generation: IPlaygroundCompilerGeneration,
@@ -78,6 +132,15 @@ export class PlaygroundCompilerLifecycle {
     return false;
   }
 
+  /**
+   * Serialize a task behind prior mutations; stale queued tasks never start.
+   * Rejection propagates to the caller without poisoning later tasks.
+   *
+   * @evidence contracts/common.md#principled-implementation The captured generation gates task start and a fulfilled continuation tail preserves total ordering after either prior settlement.
+   * @evidence contracts/common.md#clear-and-simple-design One queue boundary coordinates every caller instead of duplicating ordering policy.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Queue recovery preserves the original rejection for its caller and does not fabricate a successful mutation.
+   * @evidence contracts/common.md#meaningful-documentation Native prose defines stale-task omission and rejection ownership with tag separation under the documentation skill.
+   */
   public enqueue<T>(
     task: (generation: IPlaygroundCompilerGeneration) => Promise<T>,
   ): Promise<T | undefined> {

package/src/react/internal/PlaygroundExecutionLifecycle.ts

@@ -1,9 +1,33 @@
+/**
+ * Attempt token whose signal and publication rights end on supersession.
+ *
+ * @evidence contracts/common.md#principled-implementation Signal propagates cancellation while isCurrent and finish condition state publication and completion on the same captured owner.
+ * @evidence contracts/common.md#clear-and-simple-design One token bundles the attempt capabilities without exposing the controller or lifecycle state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Attempt rights are explicit rather than guessed from elapsed time or the last completed bundle.
+ * @evidence contracts/common.md#meaningful-documentation Native prose and member comments explain cancellation and ownership with documentation-skill member spacing.
+ */
 export interface IPlaygroundExecutionAttempt {
   /** Signal passed through every cancellable step owned by this attempt. */
   readonly signal: AbortSignal;
-  /** Whether this attempt may still commit messages or state. */
+
+  /**
+   * Whether this attempt may still commit messages or state.
+   *
+   * @evidence contracts/common.md#principled-implementation Current epoch and active controller identity jointly decide publication rights.
+   * @evidence contracts/common.md#clear-and-simple-design The predicate keeps lifecycle storage private while exposing one decision.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Superseded work cannot regain rights through a successful late result.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states publication meaning with tag separation under the documentation skill.
+   */
   isCurrent(): boolean;
-  /** Release the active slot if this is still the current attempt. */
+
+  /**
+   * Release the active slot only while this attempt remains its owner.
+   *
+   * @evidence contracts/common.md#principled-implementation Conditional completion cannot clear a newer attempt's controller and returns whether the caller owned the transition.
+   * @evidence contracts/common.md#clear-and-simple-design One completion capability centralizes active-slot release.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Old finally callbacks cannot force a new attempt into completed state.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states conditional release with tag separation under the documentation skill.
+   */
   finish(): boolean;
 }
 
@@ -13,11 +37,24 @@ export interface IPlaygroundExecutionAttempt {
  * React state stays in `PlaygroundShell`; this small state machine keeps the
  * supersession rules independently testable and makes every invalidation path
  * use the same abort behavior.
+ *
+ * @evidence contracts/common.md#principled-implementation Epoch and controller identity fence stale messages; invalidation clears ownership before dispatching synchronous abort listeners.
+ * @evidence contracts/common.md#clear-and-simple-design This state machine owns attempts only while React owns rendering and the site owns execution isolation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Shared invalidation corrects ownership directly rather than using separate timing-based cancellation wrappers.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state cancellation ownership and shared invalidation purpose under the documentation skill.
  */
 export class PlaygroundExecutionLifecycle {
   private active: AbortController | null = null;
   private epoch = 0;
 
+  /**
+   * Supersede the active attempt and capture a fresh controller and epoch.
+   *
+   * @evidence contracts/common.md#principled-implementation Invalidation aborts the prior owner before the new controller is installed; returned closures compare both epoch and controller.
+   * @evidence contracts/common.md#clear-and-simple-design One constructor supplies cancellation, validity and conditional completion for an attempt.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Supersession uses the common owning transition instead of stacking compensating callbacks.
+   * @evidence contracts/common.md#meaningful-documentation Native prose defines fresh ownership and prior-attempt behavior with tag separation under the documentation skill.
+   */
   public begin(): IPlaygroundExecutionAttempt {
     this.invalidate("a newer Execute started");
     const controller = new AbortController();
@@ -38,6 +75,11 @@ export class PlaygroundExecutionLifecycle {
    * Abort the active attempt and make its callbacks stale.
    *
    * Returns whether an active attempt was canceled.
+   *
+   * @evidence contracts/common.md#principled-implementation Clearing active identity and advancing epoch precede abort notification, preventing reentrant old callbacks from publishing.
+   * @evidence contracts/common.md#clear-and-simple-design One transition handles every invalidation reason and delegates error construction locally.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The actual owner receives cancellation; an absent owner is reported without inventing a task to cancel.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs state abort effect and return meaning under the documentation skill.
    */
   public invalidate(reason: string): boolean {
     const active = this.active;

package/src/react/internal/recoverTerminalCompilerWorker.ts

@@ -1,17 +1,53 @@
 import { BootTtscWorkerTerminationError } from "@ttsc/wasm";
 
+/**
+ * Owner callbacks for replacing a Worker whose Go runtime cannot be restarted.
+ *
+ * @evidence contracts/common.md#principled-implementation Claim, reset and failure publication express the ordered ownership transition while leaving actual Worker identity with the client.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter exposes only the three effects recovery needs, independently of React state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Recovery is limited to terminal runtime identity rather than a universal retry wrapper around ordinary failures.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states terminal scope and member ownership, with documentation-skill member spacing.
+ */
 export interface ITerminalCompilerWorkerRecovery {
-  /** Atomically claim and fence the failed Worker generation. */
+  /**
+   * Atomically claim and fence the failed Worker generation.
+   *
+   * @evidence contracts/common.md#principled-implementation A boolean reports whether this caller obtained replacement ownership before asynchronous disposal.
+   * @evidence contracts/common.md#clear-and-simple-design The client retains generation state while recovery consumes a narrow claim decision.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Stale claimants cannot reset another caller's replacement.
+   * @evidence contracts/common.md#meaningful-documentation Native prose defines atomic claim and fencing with tag separation under the documentation skill.
+   */
   claim(): boolean;
-  /** Close and clear that Worker generation. */
+
+  /**
+   * Close and clear the claimed Worker generation before failure publication.
+   *
+   * @evidence contracts/common.md#principled-implementation The promise marks the asynchronous disposal boundary for the claimed owner.
+   * @evidence contracts/common.md#clear-and-simple-design Disposal remains the client's responsibility rather than being recreated in the recovery helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposal uses the supported client boundary instead of replacing runtime internals.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states ownership and ordering with tag separation under the documentation skill.
+   */
   reset(): Promise<void>;
-  /** Publish the terminal error after the old Worker is no longer reachable. */
+
+  /**
+   * Publish the terminal error after reset settles, even if reset rejects.
+   *
+   * @evidence contracts/common.md#principled-implementation Publication preserves the actual terminal error independently of whether disposal succeeded.
+   * @evidence contracts/common.md#clear-and-simple-design State presentation remains with the owner callback, separated from error classification.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposal failure does not erase the deciding runtime failure or invent readiness.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states finally-path behavior with tag separation under the documentation skill.
+   */
   fail(error: unknown): void;
 }
 
 /**
  * Replace a compiler Worker after its Go runtime started but boot never became
  * usable. Returns false for ordinary compile, transport, and plugin failures.
+ *
+ * @evidence contracts/common.md#principled-implementation Stable terminal-error classification gates an atomic claim; reset is awaited and original failure publication runs in finally so terminal state is never replaced by ordinary retry.
+ * @evidence contracts/common.md#clear-and-simple-design Classification, ownership and reset effects have separate boundaries, keeping this coordinator independent of UI state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only the runtime's explicit terminal identity triggers replacement; ordinary failures do not accumulate reset-and-retry compensation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states terminal scope and false return meaning; callback prose defines reset rejection behavior under the documentation skill.
  */
 export async function recoverTerminalCompilerWorker(
   error: unknown,
@@ -27,7 +63,15 @@ export async function recoverTerminalCompilerWorker(
   return true;
 }
 
-/** Recognize both local errors and their plain tgrid/JSON transport shape. */
+/**
+ * Recognize the terminal runtime's stable code or message prefix after
+ * transport.
+ *
+ * @evidence contracts/common.md#principled-implementation The host-owned code matches both enumerable error records and prefixed string messages without relying on cross-realm instanceof.
+ * @evidence contracts/common.md#clear-and-simple-design One classifier centralizes local and transported identity for every recovery caller.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Classification uses a supported error identity rather than arbitrary message fragments or consumer names.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the stable transport witness with tag separation under the documentation skill.
+ */
 export function requiresCompilerWorkerReplacement(error: unknown): boolean {
   const code = BootTtscWorkerTerminationError.CODE;
   const prefix = `[${code}] `;

package/src/sandbox/createSandboxRequire.ts

@@ -45,9 +45,18 @@ class InvalidPackageTargetLoadError extends Error {}
 class InvalidPackageConfigError extends Error {}
 
 /**
- * Build a sandboxed `require` function over a runtime pack. Resolves typia /
- * `@typia/*` / randexp specifiers from the pack; throws on anything else so the
- * caller sees the unsupported dependency.
+ * Build a CommonJS resolver and evaluator over a caller-owned runtime pack.
+ * Missing modules throw; package exports use require/default conditions and
+ * legacy packages retain file-and-directory resolution.
+ *
+ * The pack must remain unchanged while this resolver is used. Evaluation uses
+ * new Function in the current realm; this is not a security isolation
+ * boundary.
+ *
+ * @evidence contracts/common.md#principled-implementation Target selection precedes loading, conditional exports preserve manifest order, validated targets stay under the package mount, and provisional module caching exposes partial exports for cycles. Evaluation assumes CommonJS source in an unchanged pack.
+ * @evidence contracts/common.md#clear-and-simple-design Manifest interpretation, specifier resolution and evaluation have local boundaries; the caller owns code isolation and transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported exports and legacy resolution decide module access uniformly; missing targets cannot trigger a second exports candidate, and failed evaluation evicts its provisional module instead of fabricating exports.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs define resolver scope, pack immutability and absent isolation; helper comments explain exports priority and cycle semantics under the documentation skill.
  */
 export function createSandboxRequire(
   pack: Record<string, string>,
@@ -55,6 +64,7 @@ export function createSandboxRequire(
 ): (specifier: string) => unknown {
   type ModuleObj = { exports: unknown };
   const cache = new Map<string, ModuleObj>();
+  const manifests = new Map<string, IPackJson>();
 
   const has = (key: string): boolean =>
     Object.prototype.hasOwnProperty.call(pack, key);
@@ -65,6 +75,7 @@ export function createSandboxRequire(
   };
 
   const readPackageJson = (mount: string): IPackJson | null => {
+    if (manifests.has(mount)) return manifests.get(mount)!;
     const key = `${mount}/package.json`;
     if (!has(key)) return null;
     try {
@@ -76,6 +87,7 @@ export function createSandboxRequire(
       ) {
         throw new Error("package.json must contain an object");
       }
+      manifests.set(mount, parsed as IPackJson);
       return parsed as IPackJson;
     } catch {
       throw new InvalidPackageConfigError(
@@ -337,18 +349,19 @@ function resolvePackageExports(
       ) {
         target = entries[request];
       } else {
-        const patterns = Object.entries(entries)
-          .map(([pattern, candidate]) => ({
-            pattern,
-            replacement: exportPatternReplacement(pattern, request),
-            target: candidate,
-          }))
-          .filter(
-            (entry): entry is typeof entry & { replacement: string } =>
-              entry.replacement !== undefined,
-          )
-          .sort((a, b) => compareExportPatternKeys(a.pattern, b.pattern));
-        const selected = patterns[0];
+        let selected:
+          | { pattern: string; replacement: string; target: unknown }
+          | undefined;
+        for (const [pattern, candidate] of Object.entries(entries)) {
+          const replacement = exportPatternReplacement(pattern, request);
+          if (replacement === undefined) continue;
+          if (
+            selected === undefined ||
+            compareExportPatternKeys(pattern, selected.pattern) < 0
+          ) {
+            selected = { pattern, replacement, target: candidate };
+          }
+        }
         if (selected === undefined) return { type: "unresolved" };
         return resolvePackageTarget(
           mount,