@tracecode/harness 0.6.6 → 0.7.0-beta7

package/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project are documented here.
 
 This repo uses Git tags as release boundaries. Version notes below summarize what shipped in each tagged release.
 
+## [0.7.0-beta4] - 2026-05-10
+
+### Changed
+
+- Upgraded the C# browser-WASM runtime lane to .NET 10, C# 14, and Roslyn `Microsoft.CodeAnalysis.CSharp` 5.3.0.
+- Added `pnpm update:csharp-runtime` to locally install/update the required .NET SDK channel, publish the C# WASM host, sync vendored assets, and regenerate runtime language info.
+
+### Fixed
+
+- Fixed newer .NET worker startup by registering C# worker messages with `addEventListener('message', ...)` so sidecar boot mode is detected correctly.
+- Fixed local Java trace fixture dynamic input mapping so full runtime trace parity can validate browser-style input files under the host JVM.
+
+## [0.7.0-beta3] - 2026-05-10
+
+### Added
+
+- Added generated runtime language info metadata and public browser/core APIs for language versions, compilers, standards, default imports, and bundled libraries.
+- Added JavaScript and TypeScript runtime library support for lodash and datastructures-js packages.
+- Expanded default import/header coverage for Python, Java, C#, and C++ runtime lanes.
+
+## [0.7.0-beta2] - 2026-05-09
+
+### Changed
+
+- Added explicit browser warmup paths for Java, Python, TypeScript, C#, and C++ so heavy runtimes can stay lazy until the app intentionally warms them.
+- Split C# and Python worker `init()` from runtime loading, preserving lazy first execution while allowing guided/code-assist flows to warm runtimes on demand.
+- Isolated C++ compiler warmup and Java background warmup behavior behind `warmLanguage(...)`.
+- Renamed Python worker-facing client/log labels from Pyodide-specific names to `PythonWorkerClient` and `[PythonWorker]`, while keeping backwards-compatible `PyodideWorkerClient` exports.
+
+### Fixed
+
+- Added a dedicated Java non-trace execution path, including run-only batch execution support.
+- Stopped plain JavaScript non-trace execution from loading the TypeScript compiler just to recover function argument order.
+
+## [0.7.0-beta1] - 2026-05-07
+
+### Added
+
+- Added third-party runtime notices covering CheerpJ, Pyodide/CPython, TypeScript, JavaParser, OpenJDK/JBR, .NET/Roslyn, YoWASP/LLVM, and WASI libc.
+- Added publishable language-split packages for core, browser, Python, JavaScript/TypeScript, Java, C#, and C++.
+- Added Java, C#, and C++ public root subpath exports.
+- Added language-filtered asset sync through `tracecode-harness sync-assets --languages ...`.
+
+### Changed
+
+- The umbrella package remains backwards compatible, while standalone language packages now publish their own generated `workers/` assets.
+- Package builds now generate per-package assets without committing duplicate runtime blobs.
+
 ## [0.6.6] - 2026-04-27
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # TraceCode Harness
 
-Browser-first execution and tracing harness for Python, JavaScript, TypeScript, and an experimental Java lane.
+Browser-first execution and tracing harness for Python, JavaScript, TypeScript, experimental Java, experimental C#, and experimental C++ lanes.
 
 `@tracecode/harness` is a browser-consumable runtime SDK for code execution and tracing: explicit browser runtime creation, package-managed worker assets, and no app-specific storage/bootstrap contract in the public API.
 
@@ -14,9 +14,10 @@ It includes:
 
 - browser-hosted execution for Python, JavaScript, and TypeScript
 - an experimental browser-local Java 17 lane for `function`, `solution-method`, `ops-class`, `script`, and `interviewMode` execution
+- an experimental browser-local C# lane for `function`, `solution-method`, `ops-class`, `script`, and `interviewMode` execution
+- an experimental browser-local C++ lane for `function`, `solution-method`, `ops-class`, `script`, and `interviewMode` execution
 - trace capture and normalized runtime contracts
 - browser worker assets and asset sync tooling
-- runtime-side structural annotations such as object kinds and hash/map payloads
 
 It does not include a full end-user product.
 
@@ -36,12 +37,12 @@ Specifically, this package does not ship:
 - a white-labeled teaching product
 - a higher-level pedagogy or visualization-planning layer
 
-Consuming apps are expected to own their own UI, persistence, product logic, and any higher-order visualization behavior built on top of the runtime payloads.
+Consuming apps are expected to own their own UI, persistence, product logic, and any higher-order visualization behavior built on top of neutral runtime trace facts.
 
 ## What You Get
 
 - shared runtime contract types and trace adapters
-- browser runtime clients for Python, JavaScript, TypeScript, and Java
+- browser runtime clients for Python, JavaScript, TypeScript, Java, C#, and C++
 - published worker assets plus a CLI to copy them into your app
 - capability profiles for honest per-language support claims
 - regression coverage for runtime parity, packaging, and consumer smoke tests
@@ -50,10 +51,26 @@ This is not a general workflow engine. It is an opinionated execution harness de
 
 ## Installation
 
+The umbrella package keeps the backwards-compatible all-in-one install:
+
 ```bash
 pnpm add @tracecode/harness
 ```
 
+For smaller installs, use the language packages you actually ship:
+
+```bash
+pnpm add @tracecode/harness-core @tracecode/harness-browser @tracecode/harness-python
+pnpm add @tracecode/harness-javascript
+pnpm add @tracecode/harness-java
+pnpm add @tracecode/harness-csharp
+pnpm add @tracecode/harness-cpp
+```
+
+Each language package publishes only its own worker assets under `workers/`.
+That keeps license/runtime exposure scoped to the languages a consuming app
+chooses to distribute.
+
 If your app bundles dependencies, transpiling the package is usually the safest option. For Next.js:
 
 ```ts
@@ -124,9 +141,25 @@ The package publishes built ESM and CommonJS entrypoints plus `.d.ts` files.
 - `@tracecode/harness/core`
   Shared runtime contracts, result types, and trace helpers.
 - `@tracecode/harness/python`
-  Python harness generation helpers and snippet artifacts.
+  Python runtime helpers, worker client, and snippet artifacts.
 - `@tracecode/harness/javascript`
-  JavaScript and TypeScript execution helpers.
+  JavaScript and TypeScript execution helpers and worker client.
+- `@tracecode/harness/java`
+  Java runtime client and worker client.
+- `@tracecode/harness/csharp`
+  C# runtime client and worker client.
+- `@tracecode/harness/cpp`
+  C++ runtime client and worker client.
+
+The same surfaces are available as standalone language packages:
+
+- `@tracecode/harness-core`
+- `@tracecode/harness-browser`
+- `@tracecode/harness-python`
+- `@tracecode/harness-javascript`
+- `@tracecode/harness-java`
+- `@tracecode/harness-csharp`
+- `@tracecode/harness-cpp`
 
 The browser entrypoint is intentionally narrow. Low-level worker constructors, language gates, and isolation helpers are internal implementation details, not public SDK surface.
 
@@ -137,6 +170,7 @@ The browser package centers on `createBrowserHarness(options)`.
 ```ts
 import {
   createBrowserHarness,
+  getLanguageRuntimeInfo,
   getLanguageRuntimeProfile,
   isLanguageSupported,
   SUPPORTED_LANGUAGES,
@@ -148,15 +182,21 @@ The returned harness exposes:
 - `getClient(language)`
 - `getProfile(language)`
 - `getSupportedLanguageProfiles()`
+- `getLanguageInfo(language)`
+- `getSupportedLanguageInfos()`
 - `isLanguageSupported(language)`
+- `warmLanguage(language)`
 - `disposeLanguage(language)`
 - `dispose()`
 
 Configuration:
 
 - `assetBaseUrl?: string`
-- `assets?: Partial<{ pythonWorker; pythonRuntimeCore; pythonSnippets; javascriptWorker; typescriptCompiler; javaWorker; javaHelperJar; javaPracticeRewriterJar; javaRewriteBridgeJar; javaParserJar; javaCompilerJar }>`
+- `assets?: Partial<{ pythonWorker; pythonRuntimeCore; pythonSnippets; javascriptWorker; typescriptCompiler; javaWorker; csharpWorker; csharpAssetBaseUrl; cppWorker; cppCompilerFrame; cppCompilerWorker; cppCompilerBundle; cppRuntimeHeader }>`
 - `debug?: boolean`
+- `java?: { workerIdleTimeoutMs?: number }`
+- `csharp?: { workerIdleTimeoutMs?: number }`
+- `cpp?: { workerIdleTimeoutMs?: number }`
 
 Example:
 
@@ -166,41 +206,98 @@ const harness = createBrowserHarness({
 });
 
 const profile = harness.getProfile('typescript');
+const info = harness.getLanguageInfo('typescript');
+const pythonInfo = getLanguageRuntimeInfo('python');
 
 if (profile.capabilities.tracing.supported) {
   // show trace controls
 }
+
+console.log(info.versionLabel);
+console.log(info.description);
+console.log(pythonInfo.versionLabel);
 ```
 
+Runtime info is generated from worker constants, package manifests, and vendored runtime
+metadata. Each info object also includes `description`, a natural-language runtime
+summary suitable for product UI. Run `pnpm generate:runtime-info` after runtime
+dependency changes, or `pnpm test:runtime-info-sync` to check whether the
+generated SDK data is current.
+
+For Java, `init()` only performs a light CheerpJ initialization. Call `warmLanguage('java')`
+after the user selects Java, or after editor-driven assist work, to warm the heavier javac
+path in the background. The hot Java worker idles for 5 minutes by default; call
+`disposeLanguage('java')` when the editor closes or the user switches away to release it
+immediately.
+
+For C#, `init()` records the worker asset URL without loading the .NET runtime. Call
+`warmLanguage('csharp')` after the user selects C# to load the runtime and warm Roslyn in
+the background. Execution still works without an explicit warmup; the first request pays the
+runtime load cost.
+
+For C++, `init()` only records the worker asset URLs. Call `warmLanguage('cpp')` after the
+user selects C++ to load and warm the browser-local Clang/WASI toolchain in the background.
+The default browser client compiles through a disposable compiler frame/worker so the hot
+compiler context can be released after compilation; warmup uses that external compiler path
+when the frame or nested compiler worker is available, so the main C++ worker keeps only the
+compiled program cache. Hosting `cppCompilerFrame` on a separate process-isolated origin
+gives Chrome the strongest cleanup boundary. If the compiler frame is on another origin,
+serve `cppCompilerWorker`, `cppCompilerBundle`, `cppRuntimeHeader`, and the YoWASP assets
+from that origin too, or serve them with CORS headers. The hot C++ worker keeps its shorter
+default idle timeout; call `disposeLanguage('cpp')` when C++ is no longer active.
+
 ## Worker Assets
 
 `tracecode-harness sync-assets <target-dir>` copies the canonical browser asset set:
 
+- `THIRD_PARTY_NOTICES.md`
 - `pyodide-worker.js`
 - `generated-python-harness-snippets.js`
 - `pyodide/runtime-core.js`
 - `javascript-worker.js`
 - `vendor/typescript.js`
+- `vendor/javascript-libraries.js`
 - `java-worker.js`
-- `vendor/java-browser-spike-helper.jar`
-- `vendor/java-practice-rewriter.jar`
-- `vendor/java-rewrite-bridge.jar`
+- `vendor/java-browser-helper.jar`
+- `vendor/java-rewriter.jar`
 - `vendor/javaparser-core-3.25.10.jar`
 - `vendor/jdk.compiler-17.jar`
+- `csharp-worker.js`
+- `vendor/csharp/**`
+- `cpp-worker.js`
+- `cpp-compiler-frame.html`
+- `cpp-compiler-worker.js`
+- `cpp/tracecode_runtime.hpp`
+- `vendor/cpp/yowasp/**`
+
+You can copy a smaller set from the umbrella CLI:
+
+```bash
+pnpm exec tracecode-harness sync-assets public/workers --languages python,javascript
+```
+
+Standalone language packages publish their own `workers/` directories with the
+same target layout, so consumers can copy only the package assets they install.
 
 By default, `createBrowserHarness({ assetBaseUrl: '/workers' })` resolves those assets as:
 
+- `/workers/THIRD_PARTY_NOTICES.md`
 - `/workers/pyodide-worker.js`
 - `/workers/generated-python-harness-snippets.js`
 - `/workers/pyodide/runtime-core.js`
 - `/workers/javascript-worker.js`
 - `/workers/vendor/typescript.js`
+- `/workers/vendor/javascript-libraries.js`
 - `/workers/java-worker.js`
-- `/workers/vendor/java-browser-spike-helper.jar`
-- `/workers/vendor/java-practice-rewriter.jar`
-- `/workers/vendor/java-rewrite-bridge.jar`
+- `/workers/vendor/java-browser-helper.jar`
+- `/workers/vendor/java-rewriter.jar`
 - `/workers/vendor/javaparser-core-3.25.10.jar`
 - `/workers/vendor/jdk.compiler-17.jar`
+- `/workers/csharp-worker.js`
+- `/workers/vendor/csharp`
+- `/workers/cpp-worker.js`
+- `/workers/cpp/tracecode_runtime.hpp`
+- `/workers/vendor/cpp/yowasp`
 
 Advanced consumers can override individual asset URLs through the `assets` option.
 
@@ -220,7 +317,6 @@ Capability domains:
 - `tracing`
 - `diagnostics`
 - `structures`
-- `visualization`
 
 That lets the package be explicit about partial support and fail closed for unsupported requests.
 
@@ -230,12 +326,18 @@ Current language status:
 - `javascript`: stable
 - `typescript`: stable
 - `java`: experimental, browser-local Java 17 lane
+- `csharp`: experimental, browser-local .NET WASM + Roslyn lane
 
 Current Java scope:
 
-- supported: `function`, `solution-method`, `ops-class`, `script`, `interviewMode`, tracing, compile diagnostics, structural visualization payloads
+- supported: `function`, `solution-method`, `ops-class`, `script`, `interviewMode`, tracing, compile diagnostics, and neutral runtime trace facts
 - script mode uses an empty function name with `executionStyle: "function"` and reads the top-level `result` variable
 
+Current C# scope:
+
+- supported: named `function` execution, script-style `function` execution with an empty function name and top-level `result`, `interviewMode` execution with sanitized timeout responses, `solution-method` execution for `public class Solution`, `ops-class` execution with JS/TS/Java-style operation-output arrays, generated drivers including `void` methods, `ListNode`/`TreeNode` prelude classes and JSON hydration including linked `__id__`/`__ref__` cycle refs, neutral graph-like map/list serialization, stdout capture, runtime errors, mapped Roslyn compile diagnostics, soft loop timeouts, trace budgets (`maxTraceSteps`, `maxLineEvents`, `maxSingleLineHits`, `maxStoredEvents`, `minimalTrace`), call-stack attachment for traced frames, `List<T>`/`Dictionary<K,V>`/`HashSet<T>`/array return-value serialization, block-bodied and expression-bodied method tracing, block-bodied and expression-bodied lambda tracing, basic line/call/return-value/simple-write tracing, one-dimensional array indexed read/write tracing including simple compound writes, and `List<T>`/`Dictionary<K,V>`/`HashSet<T>`/`Queue<T>`/`PriorityQueue<TElement,TPriority>`/`Stack<T>` wrapper tracing for `var`, explicit local declarations, target-typed `new()`, collection initializers, common collection constructors, comparer constructor overloads, and priority-queue capacity/comparer constructors
+- not yet supported: NuGet packages, async/threading APIs, project files, multiple source files, unsafe code, expression-tree lambda rewriting, or full expression/value tracing fidelity
+
 ## Example Consumer
 
 A minimal reference browser IDE lives in [examples/web-ide](./examples/web-ide). It is intentionally small and exists to prove that a third-party app can:
@@ -275,6 +377,17 @@ If you change Python harness templates or generated snippets, regenerate artifac
 pnpm generate:python-harness
 ```
 
+To update the vendored C# browser-WASM runtime, run:
+
+```bash
+pnpm update:csharp-runtime
+```
+
+The updater reads the C# host `TargetFramework`, installs or updates the matching
+.NET SDK channel under `.dotnet/`, installs `wasm-tools`, republishes the host,
+replaces `workers/vendor/csharp`, and regenerates runtime language info. Set
+`TRACECODE_DOTNET_VERSION` to pin an exact SDK version for a repeatable refresh.
+
 ## Releases
 
 This repo uses explicit versioned release boundaries.
@@ -290,6 +403,12 @@ This repo uses explicit versioned release boundaries.
 
 Detailed release notes live in [CHANGELOG.md](./CHANGELOG.md).
 
+## Third-Party Runtime Notices
+
+Runtime dependencies and license notes are tracked in
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md). Keep that file with any
+redistribution of worker assets.
+
 ## License
 
 AGPL-3.0-only

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,170 @@
+# Third Party Notices
+
+This project is licensed under AGPL-3.0-only. The browser runtimes also use
+third-party runtime, compiler, parser, and standard-library components. This
+file is an attribution and redistribution inventory for those components.
+
+It is not legal advice. Before a commercial release, verify the current upstream
+license text and any use-case-specific terms against the linked upstream
+sources.
+
+## Python Runtime
+
+### Pyodide
+
+- Use: Python runtime loaded by `workers/python/pyodide-worker.js`.
+- Version: the worker currently loads Pyodide `0.29.0` from public CDNs; the
+  workspace package resolves `pyodide` `0.29.3`.
+- License: MPL-2.0.
+- Source: https://github.com/pyodide/pyodide
+- Deployment docs: https://pyodide.org/en/stable/usage/downloading-and-deploying.html
+
+### CPython and Python Standard Library
+
+- Use: Python interpreter and standard library distributed as part of Pyodide.
+- License: Python Software Foundation License Agreement and historical Python
+  license stack.
+- Source: https://github.com/python/cpython
+- License summary: https://www.python.org/psf/summary/
+
+## JavaScript and TypeScript Runtime
+
+### TypeScript
+
+- Use: TypeScript transpilation and diagnostics for the JavaScript/TypeScript
+  worker lane.
+- Vendored asset: `workers/vendor/typescript.js`.
+- Version: `5.9.3` in the local workspace asset; the worker keeps CDN fallbacks
+  for `5.9.2`.
+- License: Apache-2.0.
+- Source: https://github.com/microsoft/TypeScript
+- Upstream notice: TypeScript distributes `ThirdPartyNoticeText.txt`; preserve
+  that upstream notice when updating the vendored compiler asset.
+
+### Lodash
+
+- Use: JavaScript/TypeScript helper exposed as `_`, `lodash`, and through the
+  worker-local `require("lodash")` shim.
+- Vendored asset: `workers/vendor/javascript-libraries.js`.
+- Version: `lodash` `4.17.21`.
+- License: MIT.
+- Source: https://github.com/lodash/lodash
+
+### datastructures-js
+
+- Use: JavaScript/TypeScript helper packages exposed through the worker-local
+  `require("@datastructures-js/...")` shim.
+- Vendored asset: `workers/vendor/javascript-libraries.js`.
+- Versions: `@datastructures-js/binary-search-tree` `5.4.0`,
+  `@datastructures-js/deque` `1.0.8`, `@datastructures-js/graph` `5.3.1`,
+  `@datastructures-js/heap` `4.3.7`, `@datastructures-js/linked-list`
+  `6.1.4`, `@datastructures-js/priority-queue` `6.3.5`,
+  `@datastructures-js/queue` `4.3.0`, `@datastructures-js/set` `4.2.2`,
+  `@datastructures-js/stack` `3.1.6`, and `@datastructures-js/trie` `4.2.3`.
+- License: MIT.
+- Source: https://github.com/datastructures-js
+
+## Java Runtime
+
+### CheerpJ Core
+
+- Use: browser-hosted JVM runtime loaded by the Java worker.
+- Runtime URL: `https://cjrtnc.leaningtech.com/4.2/loader.js`.
+- Provider: Leaning Technologies.
+- Terms: CheerpJ Community License or CheerpJ Commercial License depending on
+  the user's use case.
+- Licensing docs: https://cheerpj.com/docs/licensing
+- Version/changelog docs: https://cheerpj.com/docs/changelog
+
+CheerpJ is not vendored in this package; it is loaded from Leaning Technologies'
+`cjrtnc.leaningtech.com` runtime domain. The Community License currently covers
+individuals, one-person companies, FOSS projects, and technical evaluations.
+Uses outside that scope can require a commercial license.
+
+### JavaParser
+
+- Use: Java source parsing and rewriting support.
+- Vendored asset: `workers/vendor/javaparser-core-3.25.10.jar`.
+- Version: `3.25.10`.
+- License: dual licensed LGPL-3.0 or Apache-2.0. This project uses it under
+  Apache-2.0.
+- Source: https://github.com/javaparser/javaparser
+
+### OpenJDK / JetBrains Runtime Compiler Module
+
+- Use: Java compiler module consumed by the browser Java lane.
+- Vendored asset: `workers/vendor/jdk.compiler-17.jar`.
+- Local manifest: `Created-By: 17.0.14 (JetBrains s.r.o.)`.
+- License: GPL-2.0-only WITH Classpath-exception-2.0.
+- OpenJDK GPLv2 + Classpath Exception text: https://openjdk.org/legal/gplv2+ce.html
+- JetBrains Runtime source: https://github.com/JetBrains/JetBrainsRuntime
+
+Redistributing this asset should preserve the GPLv2 + Classpath Exception text
+and provide the corresponding source location or source offer required by the
+license.
+
+## C# Runtime
+
+### .NET Runtime for WebAssembly
+
+- Use: browser WebAssembly runtime and base class libraries for the C# lane.
+- Vendored assets: `workers/vendor/csharp/**`.
+- Target: `net10.0`, `browser-wasm`.
+- License: MIT, plus .NET third-party notices for bundled components.
+- Source: https://github.com/dotnet/runtime
+- Upstream notices: https://github.com/dotnet/runtime/tree/main/src/installer/pkg/sfx/Microsoft.NETCore.App/THIRD-PARTY-NOTICES.TXT
+
+### Roslyn / Microsoft.CodeAnalysis.CSharp
+
+- Use: C# parsing, compilation, and diagnostics in the C# worker.
+- Version: `Microsoft.CodeAnalysis.CSharp` `5.3.0`.
+- License: MIT.
+- NuGet package: https://www.nuget.org/packages/Microsoft.CodeAnalysis.CSharp/5.3.0
+- Source: https://github.com/dotnet/roslyn
+
+## C++ Runtime
+
+### YoWASP Clang
+
+- Use: browser C++ compiler bundle and LLVM resource bundle.
+- Vendored/copied assets: `vendor/cpp/yowasp/bundle.js`,
+  `vendor/cpp/yowasp/llvm-resources.tar`, and `vendor/cpp/yowasp/*.wasm`.
+- Version: `@yowasp/clang` `22.0.0-git20542-10`.
+- Local package metadata license: ISC.
+- Upstream README license statement: Apache-2.0, matching the base LLVM license.
+- Source: https://github.com/YoWASP/clang
+
+The local package metadata and README identify different license labels. Until
+that is clarified upstream, preserve both the package metadata notice and the
+README/source license reference when redistributing these assets.
+
+### LLVM / Clang / LLD
+
+- Use: underlying compiler and linker components inside the YoWASP bundle.
+- License: Apache-2.0 WITH LLVM-exception.
+- Source: https://github.com/llvm/llvm-project
+- License policy: https://llvm.org/docs/DeveloperPolicy.html#copyright-license-and-patents
+
+### WASI libc and Sysroot Materials
+
+- Use: libc/sysroot inputs included in the C++ compiler resources.
+- License: mixed permissive licenses, including Apache-2.0 WITH LLVM-exception,
+  Apache-2.0, MIT, BSD-2-Clause, and CC0-1.0.
+- Source: https://github.com/WebAssembly/wasi-libc
+
+## Project-Authored Runtime Helpers
+
+The following runtime helpers are authored for this project and are covered by
+the project AGPL-3.0-only license unless otherwise noted by their embedded
+third-party dependencies:
+
+- `workers/python/runtime-core.js`
+- `workers/python/generated-python-harness-snippets.js`
+- `workers/javascript/javascript-worker.js`
+- `workers/java/java-worker.js`
+- `workers/java/java-source-augmentations.js`
+- `workers/vendor/java-browser-helper.jar`
+- `workers/vendor/java-rewriter.jar`
+- `workers/csharp/csharp-worker.js`
+- `workers/cpp/cpp-worker.js`
+- `workers/cpp/tracecode_runtime.hpp`