@loopdive/js2 0.57.0

package/LICENSE

@@ -0,0 +1,189 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the possibility
+of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability incurred
+by, or claims asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+Exceptions to the Apache 2.0 License
+
+As an exception, if, as a result of your compiling your source code, portions of
+this Software are embedded into an Object form of such source code, you may
+redistribute such embedded portions in such Object form without complying with
+the conditions of Sections 4(a), 4(b), and 4(d) of the License.

package/README.md

@@ -0,0 +1,451 @@
+# js2wasm
+
+Direct AOT compilation from JavaScript and TypeScript to WebAssembly GC.
+
+> **Status: early-stage research prototype — a tech demo, not a production-ready compiler.**
+> `js2wasm` is an experimental ahead-of-time JavaScript/TypeScript-to-WasmGC compiler under active development. It explores one specific point in the design space: full ECMAScript backwards compatibility via direct AOT compilation, with no JavaScript engine or interpreter bundled into the output. It does **not** claim production readiness, full language coverage, or stable APIs — expect rough edges, gaps, and breaking changes. Live conformance and benchmark figures are in **[STATUS.md](./STATUS.md)** (numbers change frequently and are not duplicated in this README).
+
+`js2wasm` compiles source code into WasmGC binaries without embedding a JavaScript interpreter or shipping a bundled runtime. That avoids the runtime tax common in the interpreter-based and engine-embedding approaches — where a JavaScript interpreter or full engine is compiled to Wasm and shipped inside every module — and keeps the output aligned with Wasm-native deployment models.
+
+`js2wasm` is a free and open-source project developed by **Loopdive GmbH** and released under the **Apache License 2.0 with LLVM Exceptions**. It is a freely-licensed, open-source technical foundation and reusable building block, developed fully in the open, including its agentic engineering workflow. The repository contains the compiler source, the complete planning surface (`plan/`), and the agent coordination infrastructure (`.claude/`) that a small team uses to ship fixes in parallel.
+
+## Value Proposition
+
+Most JavaScript-on-Wasm systems work by putting a JavaScript engine inside a Wasm module. That approach inherits good compatibility, but it also inherits the cost of shipping and initializing the engine.
+
+`js2wasm` takes the opposite approach:
+
+- **Direct AOT compilation to WasmGC** instead of interpreter bundling
+- **No embedded JS engine** in the deployed module
+- **No bundled interpreter or engine tax** just to execute application code
+- **Wasm-native deployment model** for runtimes, serverless platforms, and embedded hosts
+
+This matters for infrastructure workloads where artifact size, cold start, density, and host integration are first-order constraints.
+
+It also matters for security boundaries. In browsers, Node.js, and other JavaScript-capable hosts, compiling modules to Wasm introduces an isolation boundary that can limit how much third-party dependencies and user-provided code can affect the surrounding process. That is relevant for supply-chain defense, plugin systems, and multi-tenant execution.
+
+## Why This Architecture
+
+`js2wasm` is being built for environments where bundling a JavaScript engine is the wrong tradeoff:
+
+- edge and serverless runtimes
+- Wasm-first infrastructure platforms
+- plugin and extension systems
+- embedders that want JavaScript semantics without shipping an interpreter
+- desktop applications that want a lighter and safer alternative to Electron-style runtime bundling
+
+That includes practical combinations with hosts like Tauri, where compiler output can be shipped as executable Wasm artifacts instead of bundling a full browser-plus-JS-engine runtime into the application.
+
+The current public benchmark and conformance work exists to test an open question: whether direct AOT compilation can become a viable alternative to bundling a runtime for these workloads. That has not been settled yet — it is what the project is investigating.
+
+Many alternatives in adjacent spaces solve the problem by narrowing the language instead:
+
+- supporting only a constrained subset of TypeScript or JavaScript
+- introducing a new language or dialect that compiles to Wasm more easily
+
+`js2wasm` is aimed at a harder target: targeting mainstream JavaScript semantics through direct compilation rather than changing the language model to fit the compiler.
+
+Projects in this category usually take years to reach meaningful semantic coverage. A large part of the Loopdive thesis is that an AI-native compiler workflow can compress that timeline substantially without giving up on the harder target.
+
+Current Test262 conformance and benchmark numbers are tracked in one place and
+change frequently — see **[STATUS.md](./STATUS.md)** for the live figures, the
+[Playground](https://js2.loopdive.com/playground/), and the
+[Roadmap](./ROADMAP.md). The single auto-updated conformance figure (refreshed
+by CI on every merge) is for the JS-host path; everything else links to
+STATUS.md rather than duplicating numbers that go stale. Standalone
+(no-JS-host) pass-rate and benchmark figures are intentionally omitted from the
+README until the current standalone regression is fixed.
+
+<!-- AUTO:conformance-start -->
+**test262 conformance**: 32,456 / 43,135 (75.2 %)
+<!-- AUTO:conformance-end -->
+
+## Current Status
+
+`js2wasm` is an early-stage research prototype: an experimental compiler under
+active development, not a production-ready tool. It is being explored as a
+public, in-the-open project, and the conformance story, runtime boundary, and
+standalone path are all still hardening. What exists today:
+
+- a JS-hosted compilation path passing a substantial subset of Test262 (see
+  [STATUS.md](./STATUS.md) for the current figure)
+- a public browser playground
+- continuous conformance and benchmark reporting on every change
+- a standalone (no-JS-host) path that is in progress; its public numeric
+  baselines are paused here until the current regression is fixed
+
+Treat it as a tech demo to evaluate the approach, not as something to deploy.
+
+## The AOT JavaScript compilation landscape
+
+There are several established ways to get JavaScript running on WebAssembly.
+Each makes a different, reasonable trade-off, and most have years of engineering
+behind them. The point of this map is not to rank them — it is to locate the
+specific gap `js2wasm` is exploring. Described by architecture rather than by
+product:
+
+- **Interpreter-based approach** — compile a JavaScript *interpreter* to Wasm
+  and run the user's program on top of it. Gets broad ECMAScript compatibility
+  more or less for free, because a real interpreter is doing the work. The cost:
+  every deployed module ships and initializes the interpreter, which adds size
+  and startup overhead and means application code runs interpreted rather than
+  compiled.
+
+- **Engine-embedding approach** — compile a full production JavaScript *engine*
+  to Wasm (optionally specialized per-script, e.g. via partial evaluation).
+  Inherits mature, battle-tested engine semantics and very high compatibility.
+  The cost: the engine is large, and even when specialized the engine itself is
+  still part of what ships.
+
+- **Typed JS/TS subset languages** — a statically typed language with
+  JavaScript-like or TypeScript-like syntax that compiles ahead of time to
+  compact Wasm. Output is small and fast precisely *because* it deliberately
+  does **not** accept full ECMAScript: dynamic semantics are excluded by design
+  and the type system is the contract. Excellent when you can write to that
+  language; not a path to running existing JavaScript unchanged.
+
+- **Linear-memory AOT compilers** — compile JavaScript ahead of time to Wasm
+  using linear memory, implementing object model, allocation, and (typically) a
+  garbage collector inside the module. This shares the "compile, don't embed a
+  runtime" goal; the distinguishing axis from `js2wasm` is the lowering target
+  (linear memory and a self-managed heap vs. host-managed WasmGC) and, in
+  current projects, how much of full ECMAScript compatibility is an explicit
+  goal.
+
+**Where `js2wasm` sits.** Direct AOT compilation to **WasmGC** (objects,
+closures, and arrays lower to host-managed GC structs/arrays/references), with
+**full ECMAScript backwards compatibility as the explicit goal**, and **no
+JavaScript engine or interpreter bundled into the output**. Where the compiler
+can prove stable types and shapes it lowers them directly; where JavaScript
+stays dynamic it inserts guards, boxed representations, or host fallbacks.
+
+The structural observation behind the project is that this *combination* of
+trade-offs is largely unoccupied: the typed-subset languages excluded full
+ECMAScript compatibility on purpose; the linear-memory AOT compilers do not
+currently center it; and the interpreter-based and engine-embedding approaches
+reach compatibility only by shipping a runtime (paying in size and startup).
+Targeting WasmGC + full backwards compatibility + no bundled runtime is a point
+that has not been seriously attempted. `js2wasm` is testing whether it is
+viable — that is an open question, not a settled result, and the honest answer
+today is "we don't know yet."
+
+## Quick Start
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Compile a file:
+
+```bash
+npx js2wasm input.ts -o output.wasm
+```
+
+Programmatic API:
+
+> **Breaking change (#1757):** `compile()` (and `compileMulti`, `compileFiles`,
+> `compileToWat`, `compileProject`, `createIncrementalCompiler().compile`) now
+> return a `Promise` — `await` them. This lets the optional Binaryen optimizer
+> load lazily only when `optimize` is requested, without forcing standalone
+> bundles to embed Binaryen (GH #986).
+
+```ts
+import { compile } from "js2wasm";
+
+const result = await compile(
+  `
+  export function add(a: number, b: number): number {
+    return a + b;
+  }
+`,
+  { target: "standalone" },
+);
+
+if (result.success) {
+  // standalone modules have no host imports, so {} is sufficient
+  const { instance } = await WebAssembly.instantiate(result.binary, {});
+  console.log((instance.exports as any).add(2, 3)); // → 5
+}
+```
+
+Standalone CLI bundle:
+
+```bash
+pnpm run build:standalone-cli -- --minify
+deno compile -A --no-check -o js2wasm dist/js2wasm-standalone.mjs
+# or:
+bun build --compile --target=node --outfile js2wasm dist/js2wasm-standalone.mjs
+```
+
+`build:standalone-cli` creates a relocatable `dist/js2wasm-standalone.mjs`
+bundle for native-executable workflows. Unlike the normal npm library build, it
+bundles the core compiler dependencies and embeds TypeScript's `lib.*.d.ts`
+declarations, so the generated file does not need to remain next to
+`node_modules/typescript/lib` after it is moved or compiled. The `--ts7`
+preview backend and Binaryen optimizer remain development/optimization opt-ins
+and are not bundled into this standalone artifact. If you use `-O` with the
+standalone CLI, install `binaryen` next to the runner or put `wasm-opt` on PATH;
+you can also run `wasm-opt` directly on the emitted `.wasm` afterward.
+
+### Compile modes and imports
+
+The imports a module needs depend on the compile target:
+
+- **Default (JS-host) mode** (no `target`, or `target: "gc"`) emits runtime
+  imports — a `string_constants` module plus `env.*` helpers such as
+  `__box_number`, `__extern_get`, and `__throw_reference_error`. These are
+  supplied by the js2wasm JS runtime, so instantiating with an empty `{}`
+  throws `Import #0 "string_constants": module is not an object or function`.
+  Use this mode when you run the output alongside the JS runtime that provides
+  those imports. The result carries a ready-to-pass `result.importObject` that
+  wires those host helpers for you — pass it straight to
+  `WebAssembly.instantiate` with no hand-wiring:
+
+  ```ts
+  const r = await compile(`
+    export function add(a: number, b: number): number { return a + b; }
+  `);
+  const { instance } = await WebAssembly.instantiate(r.binary, r.importObject);
+  (instance.exports as any).add(2, 3); // → 5
+  ```
+- **Standalone mode** (`target: "standalone"`, also `target: "wasi"`) emits a
+  pure WasmGC module with Wasm-native intrinsics and **no host imports**, so it
+  instantiates with `WebAssembly.instantiate(binary, {})` and runs anywhere
+  WasmGC is available. Prefer this for portable, host-independent output — it is
+  what the snippet above uses.
+
+Useful local commands:
+
+```bash
+pnpm typecheck
+pnpm lint
+npm test
+pnpm run test:262
+pnpm dev
+```
+
+## Running compiled output
+
+`js2wasm` emits WasmGC modules that use several post-MVP WebAssembly proposals.
+Most are on by default in current engines, but **WasmGC and typed function
+references are not enabled by default in stable Wasmtime**, so a bare
+`wasmtime out.wasm` fails with a validation error until they are turned on.
+
+Enable exactly the proposals the compiler emits:
+
+```bash
+wasmtime -W gc=y,function-references=y,tail-call=y,exceptions=y out.wasm
+```
+
+The proposals the compiler actually relies on are:
+
+| Proposal | Wasmtime `-W` flag | Why js2wasm needs it |
+| --- | --- | --- |
+| Garbage collection | `gc=y` | objects, arrays, closures lower to GC structs/arrays |
+| Typed function references | `function-references=y` | required by GC; typed `call_ref` for closures |
+| Exception handling | `exceptions=y` | `throw` / `try` / `catch` lowering |
+| Tail calls | `tail-call=y` | `return_call` optimization in tail position |
+
+Bulk memory, sign-extension, saturating float-to-int, multi-value, mutable
+globals, and reference types are also emitted but are enabled by default in
+current Wasmtime, so they do not need explicit flags. `js2wasm` deliberately
+avoids the custom-descriptors proposal, which stable Wasmtime does not yet
+accept.
+
+**Do not use `-W all-proposals=y`.** It also enables the **stack-switching**
+proposal, which Wasmtime 44/45 does not support in its compiler configuration —
+the runtime then fails at module load with `the wasm_stack_switching feature is
+not supported on this compiler configuration` and exits before running anything,
+regardless of module content (js2wasm output contains zero stack-switching
+opcodes). Stick to the targeted flag set above.
+
+**Minimum version:** Wasmtime **44+** (the first release with a stable WasmGC
+implementation). Older versions reject the GC types.
+
+Other standalone runtimes: WasmGC support in WAMR and WasmEdge is still
+maturing, so compiled output is not guaranteed to run there yet. Browser hosts
+(Chrome 119+, Firefox 120+) and Node.js 22+ run the JS-host target without extra
+flags.
+
+For reading STDIN and writing STDOUT/STDERR from standalone (`--target wasi`)
+output, see [docs/standalone-io.md](./docs/standalone-io.md).
+
+## Current coverage and limitations
+
+In a JS host, `js2wasm` passes a substantial subset of Test262 — enough that a
+large, useful slice of the language works — but there are real gaps, and you
+will hit them. The current pass rate lives in [STATUS.md](./STATUS.md) and the
+full [Test262 report](./benchmarks/results/report.html); this section is the
+qualitative high-level shape, and the report is the authoritative per-feature
+detail. Note that Test262 measures conformance to the ECMAScript *language*
+specification — it does not cover Web APIs, Node.js host behavior, or whether an
+arbitrary real-world npm package runs unchanged.
+
+**Solid** (broadly works):
+
+- arithmetic, comparison, and scalar operations
+- functions, closures, recursion, and most control-flow forms
+- classes, inheritance, methods, and object operations
+- arrays and array methods, destructuring, spread, template literals
+- strings and common string methods
+- `try`/`catch`/`finally` and `throw`
+- `async`/`await`, generators, and iterators
+
+**Partial** (works in common cases, with gaps):
+
+- standard-library built-ins — many are implemented, but not the full surface;
+  some methods are missing or only handle the common overloads
+- `Map`, `Set`, `RegExp`, `JSON` — present but not fully spec-complete
+- standalone (no-JS-host) mode — actively in progress; standalone numeric
+  baselines are temporarily omitted here while the current regression is fixed
+- getters/setters and other highly dynamic patterns — limited
+
+**Not yet** (intentionally unsupported or out of scope today):
+
+- `eval`, `with`, and dynamic `Function` construction
+- `Proxy` and `Reflect`-driven metaprogramming
+- `SharedArrayBuffer` / threads, `WeakRef` / `FinalizationRegistry`, `Temporal`
+- dropping in an arbitrary npm package unchanged
+
+If a pattern you rely on does not work, check the [Test262 report](./benchmarks/results/report.html)
+or open an issue. This is an actively developed compiler with a growing
+compatibility baseline and a clear infrastructure target — but it is a research
+prototype, not yet a "drop in any npm package" story.
+
+## FAQ
+
+**Why not embed an existing interpreter or engine?**
+That is the interpreter-based / engine-embedding approach, and it is a perfectly
+reasonable way to get compatibility — but every deployed module then ships and
+initializes a runtime, which is exactly the size and startup cost `js2wasm` is
+trying to avoid. The bet here is that *compiling* the code, rather than shipping
+something to run it, is worth pursuing for size- and cold-start-sensitive
+deployments. Whether that bet holds across enough real code is the open
+question.
+
+**Isn't the Test262 conformance still incomplete?**
+Yes, and the live figure is in [STATUS.md](./STATUS.md) and the
+[Test262 report](./benchmarks/results/report.html) rather than rounded up here.
+Two caveats matter more than the number: Test262 measures the ECMAScript
+*language* spec, **not** Web APIs, host/Node.js behavior, or whether an arbitrary
+npm package runs unchanged; and standalone (no-JS-host) figures are omitted here
+until the current regression is fixed. A high pass rate is necessary but not
+sufficient for "runs real JavaScript."
+
+**Won't you eventually re-implement a JavaScript engine?**
+That is the real risk, treated as an empirical question, not a solved one. The
+design is compiled-code-first: resolve what can be resolved statically and lower
+it directly, with no interpreter on the common paths. The genuinely unstatic
+corners (`eval`, dynamic `Function`) would need a small interpreter fallback that
+runs only on those paths — not a full engine in every module. Whether that
+fallback stays small, and how much real code avoids it, is what the prototype is
+testing. If compatibility turns out to require shipping an engine, that is a
+negative result worth knowing.
+
+**Why not extend an existing typed JS/TS subset language?**
+Typed JS/TS subset languages produce small, fast Wasm *because* they deliberately
+exclude full ECMAScript — dynamic semantics are dropped by design and the static
+type system is the contract. Extending one toward full backwards compatibility
+means re-adding the dynamics it was built to avoid. `js2wasm` instead targets
+existing JavaScript semantics directly, so existing code is the input rather than
+a rewrite into a new dialect.
+
+**Why WasmGC rather than linear memory?**
+WasmGC gives the compiler host-managed structs, arrays, references, and function
+references, which map onto JavaScript objects, closures, and arrays fairly
+directly and let the host GC manage memory instead of shipping a collector inside
+the module. Linear-memory AOT compilation is a legitimate alternative with its
+own trade-offs (more control, broader runtime support today, but a self-managed
+heap); `js2wasm` keeps a linear-memory backend for WASI-oriented targets, so this
+is a per-target choice rather than a one-way bet. See the
+[ADRs](./docs/adr/README.md) for the reasoning.
+
+**What is the realistic timeline to production-ready?**
+Unknown. This is research-stage work, and a firm date would be a guess dressed up
+as a commitment. The viability of the core bet — full ECMAScript backwards
+compatibility, AOT-compiled to WasmGC, no bundled runtime — is still being
+established. The conformance and benchmark trends are public so progress can be
+judged from data. Until they say otherwise, treat it as something to evaluate,
+not to deploy.
+
+## The Methodology
+
+Loopdive develops `js2wasm` with an **Automated Agile Team** model. The goal is not novelty for its own sake. The goal is to compress the feedback loop between product intent, compiler implementation, and conformance verification.
+
+### Operating Roles
+
+- **Product Owner**: defines goals with the human stakeholder, plans sprints, prioritizes work, and keeps the backlog aligned with the product surface.
+- **Technical Delivery Lead**: orchestrates sprint execution, coordinates task flow, manages merge discipline, and keeps implementation work moving through the pipeline.
+- **Compiler Engineer (AI)**: implements ECMA-262 behavior, compiler pipeline changes, WasmGC lowering, and code generation details.
+- **QA Engineer (Automated)**: runs CI-based conformance and regression feedback loops, especially around Test262 trend tracking and behavioral drift.
+- **Architect (Human / Loopdive)**: owns system design, strategic constraints, runtime boundaries, and platform-facing product decisions.
+
+### Why It Matters
+
+This model is a bet that a tight, automated feedback loop lets a small team
+iterate on a hard compatibility target faster than a conventional one would.
+Whether that bet pays off is part of what this prototype is testing.
+
+The workflow is optimized for:
+
+- short implementation-to-validation cycles
+- continuous spec-aligned compiler iteration
+- rapid backlog triage from conformance data
+- keeping product direction, engineering execution, and QA tightly coupled
+
+### Open Agentic Development
+
+The workflow is not hidden behind a consultancy. It is **in this repository**:
+
+- `plan/issues/` — architect-written implementation specs for every open and completed work item
+- `plan/log/dependency-graph.md` — current priorities and what's blocked on what
+- `plan/issues/sprints/` — sprint plans and retrospectives
+- `.claude/agents/` — agent role definitions (product owner, architect, developer, scrum master)
+- `.claude/hooks/` — safety scripts (pre-commit gates, path checks)
+- `.claude/skills/` — reusable workflow protocols (test-and-merge, self-merge, harvest-errors)
+- `.claude/memory/` — accumulated feedback and learnings shared across sessions
+
+Anyone with a [Claude Code](https://docs.claude.com/claude-code) subscription can clone the repo, spawn a `developer` agent from `.claude/agents/developer.md`, point it at a `status: ready` issue under `plan/issues/sprints/`, and contribute a real fix through the same pipeline the core team uses. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the agentic contribution path.
+
+### How this is built
+
+For a long-form, technical account of the agentic development methodology — how the team is structured, how correctness is anchored across multiple test suites, where the decision boundaries between human and agent are drawn, what has gone wrong, and how the methodology has evolved — see [`docs/methodology.md`](./docs/methodology.md).
+
+The document is intended for senior engineers who are skeptical but curious. It cites concrete numbers (sprint count, PR count, test262 pass rate), names the failure modes the team has hit, and discusses honest tradeoffs versus a traditional engineering team. It synthesizes the raw planning material in `plan/` for an external reader without contradicting it; if the two ever diverge, `plan/` is the primary source.
+
+## Licensing
+
+This repository is licensed under the **Apache License 2.0 with LLVM Exceptions**. See [LICENSE](./LICENSE).
+
+- Source code in this repository is available under **Apache-2.0 WITH LLVM-exception**
+- Community contributions are accepted under the contributor terms described in [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## Testing
+
+`js2wasm` validates correctness through three complementary test layers:
+
+- **Unit & equivalence tests** — `npm test` (vitest). Targeted regression coverage and JS↔Wasm equivalence assertions. See `tests/equivalence/`.
+- **Test262 conformance** — `pnpm run test:262` runs the official ECMAScript test suite (~48k tests) and reports per-edition / per-path pass rates. CI runs this sharded on every PR; the [report](./benchmarks/results/report.html) is regenerated on each merge.
+- **Differential testing vs V8** — `pnpm run test:diff` (#1203). For each program in `tests/differential/corpus/`, the harness runs Node-V8 directly and the compiled `.wasm` and compares stdout. test262 measures spec compliance; differential testing measures whether real programs actually produce the right answer. CI gates each PR on a delta against `benchmarks/results/diff-test-baseline.json` — no new mismatches allowed. Use `pnpm run test:diff:triage` to bucket mismatches by category for follow-up filing.
+
+## Development
+
+Additional contributor workflow details, including CLA terms, are in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Architecture decisions
+
+The foundational design choices behind `js2wasm` — why WasmGC instead of linear memory, why AOT instead of an embedded engine, how TypeScript annotations are treated, how closures are lowered — are documented as Architecture Decision Records in [`docs/adr/`](./docs/adr/README.md). Each record states the context, the decision, and the consequences in 200–600 words. Start with [ADR-002 (architectural approach)](./docs/adr/0002-architectural-approach.md) and [ADR-001 (hybrid compilation strategy)](./docs/adr/0001-hybrid-compilation-strategy.md); the rest are sub-decisions within that frame.
+
+## Further Reading
+
+- [Playground](https://js2.loopdive.com/playground/)
+- [Roadmap](./ROADMAP.md)
+- [Architecture Decisions](./docs/adr/README.md)
+- [Architecture Notes](./CLAUDE.md)
+- [Contributing](./CONTRIBUTING.md)
+
+## Trademark Disclaimer
+
+JavaScript is a trademark or registered trademark of Oracle in the United States and other countries. This project is independent from Oracle and is not endorsed by, sponsored by, or affiliated with Oracle.