MIRROR: javascript for 馃悳's, a tiny runtime with big ambitions
1# Architecture
2
3Status: active
4Last reviewed: 2026-04-09
5Owner: theMackabu
6
7This document is the top-level map for Ant's runtime and build graph. It is
8meant to answer "where should this change live?" before anyone starts editing.
9
10## Design Priorities
11
12- Keep the runtime small and fast to start.
13- Prefer explicit, in-repo implementations over opaque build-time magic.
14- Isolate third-party code under `vendor/` and keep Ant-owned logic in `src/`,
15 `include/`, `meson/`, `tools/`, and `tests/`.
16
17## Runtime Layers
18
19### Process and startup
20
21- `src/main.c` is the CLI executable entrypoint.
22- `src/ant.c` and `src/runtime.c` handle runtime initialization and shared
23 process setup.
24- `src/cli/` contains command-line specific behavior such as version and package
25 commands.
26
27### JavaScript engine
28
29- `src/silver/` contains the language pipeline: lexer, parser, compiler,
30 directives, VM glue, and bytecode operations.
31- `src/gc/` contains memory management primitives and object/string handling.
32- Files like `src/errors.c`, `src/descriptors.c`, and `src/shapes.c` support
33 core engine behavior shared across subsystems.
34
35### Host platform surface
36
37- `src/modules/` implements built-in modules and runtime-facing JS APIs.
38- `src/builtins/` holds bundled JavaScript shims and Node-compatible modules.
39- `src/http/`, `src/net/`, and `src/streams/` provide protocol, networking, and
40 streaming support.
41- `src/esm/` handles module loading, export wiring, and built-in bundle access.
42
43### Tooling and generated inputs
44
45- `src/tools/` generates bundled sources such as the builtin bundle and JS
46 snapshot.
47- `src/core/` stores TypeScript sources and runtime metadata that feed
48 generation steps.
49- `src/pkg/` is the Zig package manager.
50- `src/strip/` is the Rust type-stripper used during builds.
51- `meson/` and the root [meson.build](meson.build) describe the build graph,
52 dependency setup, and custom code generation targets.
53
54## Tests and Validation
55
56- `tests/` contains focused runtime tests.
57- `examples/spec/` is the main spec regression suite.
58- `test262/`, and `tools/wpt/` support broader conformance and standards work.
59- See [docs/repo/testing.md](docs/repo/testing.md) for the recommended command
60 set by change type.
61
62## Change Placement Guidelines
63
64- Parser, bytecode, execution semantics, or JIT-adjacent work belongs under
65 `src/silver/`.
66- Heap, string, or lifetime bugs usually belong under `src/gc/`.
67- Built-in API behavior should land in `src/modules/`, `src/builtins/`, or
68 `src/esm/` depending on whether the change is C runtime code, bundled JS, or
69 module-loader plumbing.
70- Networking and protocol work should stay in `src/http/`, `src/net/`, or
71 `src/streams/` unless it is only wiring.
72- Build graph changes should prefer `meson/` or `meson.build`; avoid burying
73 build logic in ad-hoc shell scripts.
74
75## Boundaries To Preserve
76
77- Do not hand-edit third-party code in `vendor/` unless the task is explicitly a
78 vendored dependency change.
79- Do not check durable architecture knowledge into `todo/`; use
80 [docs/exec-plans/index.md](docs/exec-plans/index.md) for multi-step work and
81 `docs/repo/` for stable reference docs.
82- Keep generated outputs reproducible. If a generated file changes, update or
83 document the generator path in the same change.