Docs rewrite

content/docs/internals/transpiler.mdx

@@ -0,0 +1,61 @@
+---
+title: Transpilation Pipeline
+description: How Mist source files are discovered, transpiled to Rust, and cached.
+icon: Repeat
+---
+
+The transpiler (`transpiler.mist` in `mist_api`) orchestrates the full pipeline.
+
+### Pipeline
+
+1. Read `Mist.toml` configuration
+2. Build a `Module` tree from the filesystem (discovering `package.mist` files)
+3. For each module:
+   a. Parse Mist source
+   b. Run semantic checks
+   c. Generate Rust code and position mapping
+   d. Write `.rs` file and `.map.json` file
+4. Recursively transpile included crates
+
+### Module Tree
+
+The `Module` struct represents the file-to-module mapping:
+
+```rust
+pub class Module {
+    pub String name;
+    pub PathBuf path;
+    pub Vec<Module> children;
+
+    pub constructor(PathBuf mist_path, MistConfig& config) { ... }
+    pub bool is_package(&self) { ... }
+    pub PathBuf output_dir(&self, PathBuf& parent_dir) { ... }
+    pub PathBuf output_path(&self, PathBuf& parent_dir, ...) { ... }
+}
+```
+
+### Transpilation Mapping Rules
+
+| Mist Source                | Rust Output                     |
+|----------------------------|----------------------------------|
+| `src/main.mist`            | `.mist/src/main.rs`              |
+| `src/foo.mist`             | `.mist/src/foo.rs`               |
+| `src/bar/package.mist`     | `.mist/src/bar/mod.rs`           |
+| `src/bar/baz.mist`         | `.mist/src/bar/baz.rs`           |
+
+A `package.mist` file generates `mod.rs` in the output directory and contains `pub mod <child>;` declarations for its children.
+
+### Caching
+
+The transpiler implements basic caching via file modification times:
+
+```rust
+fn is_source_newer(source: &Path, output: &Path) -> io::Result<bool> {
+    if !output.exists() { return Ok(true); }
+    let source_time = fs::metadata(source)?.modified()?;
+    let output_time = fs::metadata(output)?.modified()?;
+    Ok(source_time > output_time)
+}
+```
+
+If a source file has not changed since the last transpilation, the `.rs` file is not regenerated.