Merge pull request #3 from mist-go/complete-documentation

Complete documentation
2026-05-12 04:37:38 +02:00
parent 0e40ef32ca d82fad7457
commit 844b95d642
19 changed files with 862 additions and 135 deletions
@@ -0,0 +1,16 @@
 # Stage 1: Build the application
 FROM node:20-alpine AS builder
 WORKDIR /app
 COPY package*.json ./
 RUN npm install
 COPY . .
 RUN npm run build
 # Stage 2: Serve the static files with Nginx
 FROM nginx:alpine
 # Copy the build files from the builder stage to the Nginx web directory
 COPY --from=builder /app/dist /usr/share/nginx/html
 # Expose port 80 where the Nginx server runs
 EXPOSE 80
 # Command to start Nginx server
 CMD ["nginx", "-g", "daemon off;"]
@@ -0,0 +1,64 @@
 ---
 title: Classes
 description: Unified data and behavior with Java-style organization and Rust-powered execution.
 icon: Shapes
 ---
 Classes in Mist bridge the gap between Java's organizational structure and Rust's performance. They allow you to define data fields, constructors, instance methods, and trait implementations within a single, cohesive block.
 ## Basic Syntax
 A class groups fields and methods together. Fields follow the `type name` convention, and methods define their logic directly within the class body.
 ```cpp
 public class Logger {
    String prefix;
    public void info(self*, str* message) {
        self.log(LogLevel::Info, message);
    }
    void log(self*, LogLevel level, str* message) {
        println!("{level} {} {}", self.prefix, message);
    }
 }
 ```
 ## The Constructor
 Unlike languages that use the class name for initialization, Mist uses the explicit `constructor` keyword. This makes the entry point of the class unmistakable.
 ```cpp
 public constructor(str* prefix) {
    self.prefix = prefix.to_string();
 }
 ```
 ## Instance Methods & `self`
 Mist maintains Rust's explicit context handling. Any method that needs to access or modify class data must include `self*` (or `self mut*` for mutations) as its first parameter.
 ```cpp
 public void warning(self*, str* message) {
    self.log(LogLevel::Warning, message);
 }
 ```
 ## Trait Implementations
 One of Mist's most powerful features is the ability to nest trait implementations directly within the class block. This keeps the logic for how a type behaves (e.g., how it is displayed) physically coupled with the type definition.
 ```cpp
 impl fmt::Display {
    std::fmt::Result fmt(self*, std::fmt::Formatter<'_> mut* f) {
        return write!(f, "logger ({})", self.prefix);
    }
 }
 ```
 ## Key Characteristics
 - **Unified Scope**: Data, behavior, and trait logic live in one place, eliminating the friction of jumping between `struct` and `impl` blocks.
 - **Explicit Context**: The use of `self*` ensures that the relationship between a method and its instance is always transparent.
 - **Encapsulation**: Visibility modifiers (`public`) allow you to expose a clean API while keeping internal helper methods and state private to the class.
 - **Zero-Cost Classes**: Under the hood, Mist desugars these into idiomatic Rust structs and implementation blocks, ensuring no runtime overhead compared to raw Rust.
@@ -0,0 +1,57 @@
 ---
 title: Enums
 description: Defining algebraic data types with Mist's type-first convention.
 icon: Layers
 ---
 Enums in Mist serve as powerful algebraic data types (ADTs), maintaining the exact behavior and safety of Rust enums while applying the language-wide `type name` convention for variants that contain data.
 ## Basic Syntax
 An enum can contain unit variants, tuple variants, or struct-like variants. Following Mist's core philosophy, struct-like variants place the type before the identifier.
 ```rust
 public enum TaskState {
    Pending,
    InProgress,
    Completed,
    // Struct-like variant using 'type name'
    Failed {
        String reason,
        i32 code,
    },
 }
 ```
 ## Variant Types
 Mist supports all standard variant shapes, ensuring a 1:1 mapping to the underlying Rust execution model.
 ```rust
 enum Message {
    Quit,                          // Unit
    Move(i32, i32),                // Tuple
    Write(String),                 // Tuple
    ChangeColor {                  // Struct-like
        u8 r, u8 g, u8 b,
    },
 }
 ```
 ## Generics & Lifetimes
 Just like structs and functions, enums declare generics and lifetimes in a unified block. This is particularly useful for defining custom Result or Option types that handle references.
 ```rust
 public enum Validation<'a, T> {
    Valid(T),
    Invalid {
        str'a* message,
        u32 error_id,
    },
 }
 ```
 ## Key Characteristics
 - **Consistent Member Declaration**: Struct-like variants maintain the `type name` order, ensuring that data modeling feels identical whether you are defining a top-level `struct` or an `enum` variant.
 - **Rust-Native ADTs**: Enums compile directly to Rust enums, allowing for exhaustive pattern matching and zero-cost abstraction.
 - **Shared Visibility**: The `public` modifier at the enum level exports all variants for use in other modules, matching Rust's visibility rules for enums.
 - **Comma-Separated Members**: Fields within struct-like variants are separated by commas, mirroring the syntax used in standard Mist structs.
@@ -0,0 +1,69 @@
 ---
 title: Functions
 description: Defining execution blocks with C-style ergonomics and Rust-powered safety.
 icon: SquareFunction
 ---
 Functions are the primary unit of execution in Mist. They prioritize a traditional declaration order, placing the return type before the identifier to ensure signatures remain easy to scan in complex systems.
 ## Basic Syntax
 A standard function requires a return type, a name, and a body. Use the `void` keyword for functions that do not return a value.
 ```cpp
 i32 add(i32 a, i32 b) {
    return a + b;
 }
 void log_status(str* message) {
    println!("{}", message);
 }
 ```
 ## Visibility & Exports
 Functions are private to their module by default. The `public` modifier exports the function for cross-module access.
 ```cpp
 public i32 get_version() {
    return 1;
 }
 ```
 ## Mutable Parameters
 Parameters follow Rust’s ownership rules but use Mist’s local variable syntax. Use `mut` to allow a function to modify its local binding of a value.
 ```cpp
 void update_score(i32 mut current_score, i32 bonus) {
    current_score = current_score + bonus;
 }
 ```
 ## Generics & Lifetimes
 Mist integrates type abstraction and memory management into a single generic block. Lifetimes and type parameters share the `< >` bracket following the identifier.
 ```rust
 public str'a* choose_longer<'a, T: Display>(str'a* s1, str'a* s2, T meta) {
    println!("Metadata: {}", meta);
    return if (s1.len() > s2.len()) { s1 } else { s2 };
 }
 ```
 ## Attributes & Metadata
 Metadata is applied via the `#[attr]` syntax directly above the declaration for compiler hints or testing.
 ```cpp
 #[inline]
 public bool is_active(u32 id) {
    return id > 0;
 }
 ```
 ## Key Characteristics
 * **Scannable Signatures:** Placing return types first allows for rapid identification of a function's output.
 * **Unified Abstraction:** Lifetimes and type constraints are declared in one location, reducing signature noise.
 * **Zero-Cost Mapping:** Every function maps directly to a Rust `fn`, maintaining performance and ecosystem compatibility.
@@ -0,0 +1,37 @@
 ---
 title: Pointers & References
 description: Explicit memory access with C-style ergonomics and Rust-native safety.
 icon: MousePointer2
 ---
 Mist simplifies Rust’s reference system by using a pointer-style syntax. While the symbols look like C-style pointers, they adhere strictly to Rust’s ownership and borrowing rules.
 ## Basic Syntax
 References are defined by placing a `*` after the type. By default, pointers are immutable (shared). To allow modification of the underlying data, use the `mut*` modifier.
 ```cpp
 void increment(i32 mut* value, i32* limit) {
    if (value < limit) {
        value = value + 1;
    }
 }
 ```
 ## Lifetimes
 Lifetimes are attached directly to the type before the pointer symbol. This maintains a clean visual flow where the "type-contract" (identity, duration, and mutability) is read from left to right.
 ```cpp
 public struct Inspector<'a> {
    public str'a* target,
    public u32'a mut* counter,
 }
 ```
 ## Key Characteristics
 - **Explicit Intent:** The `mut*` syntax clearly distinguishes between a reference that can read and one that can write, mapping 1:1 to Rust's `&` and `&mut`.
 - **Visual Consistency:** Lifetimes (`'a`) and mutability modifiers are integrated into the type declaration, keeping function signatures and struct fields compact.
 - **Safety Guaranteed:** Despite the "pointer" appearance, the Mist compiler enforces Rust’s borrow checker. You cannot have multiple `mut*` references to the same data, and references cannot outlive their owners.
 - **Zero Overhead:** Mist pointers are "thin" or "fat" exactly like Rust references; they carry no extra runtime metadata and compile to identical machine code.
@@ -0,0 +1,60 @@
 ---
 title: Structs
 description: Data modeling using Mist's type-first convention.
 icon: Form
 ---
 Structs in Mist follow the same structural logic as Rust, but apply the language-wide `type name` declaration style and allow for comma-separated field grouping.
 ## Basic Syntax
 A struct is defined by its name followed by a block of fields. Each field follows the Mist convention of placing the type before the identifier, separated by commas.
 ```rust
 public struct Task {
    public String name,
    public TaskState state,
    public i32 executions,
 }
 ```
 ## Visibility
 Use the `public` modifier to make the struct or its individual fields accessible from other modules.
 ```cpp
 public struct NetworkNode {
    public u32 id,
    str* address,
 }
 ```
 ## Instantiation
 Structs are instantiated using the standard brace syntax.
 ```cpp
 var task = Task {
    name: "Initialize".to_string(),
    state: TaskState::Pending,
    executions: 0,
 };
 ```
 ## Generics & Lifetimes
 Generics and lifetimes are declared in angle brackets after the struct name. Lifetimes are associated with the reference/pointer type within the field declarations.
 ```cpp
 public struct Buffer<'a, T> {
    public T'a* data,
    public usize len,
 }
 ```
 ## Key Characteristics
 - **Type-First Declaration**: Fields use the `type name` order to match function parameters and variable declarations.
 - **Comma-Separated Members**: Fields are separated by commas, maintaining a clean and consistent delimiter style.
 - **Rust Compatibility**: Maps 1:1 to Rust structs, ensuring zero-cost abstraction and full ecosystem interoperability.
 - **Direct Visibility**: The `public` keyword replaces `pub` for a more consistent modifier language across the codebase.
@@ -0,0 +1,61 @@
 ---
 title: Traits
 description: Defining shared behavior and contracts with Mist's signature ergonomics.
 icon: Sparkles
 ---
 Traits in Mist define a set of methods that a type must implement, facilitating polymorphism and shared behavior. While they mirror the logic of Rust traits, they utilize Mist’s **type-first** declaration style for method signatures.
 ## Defining a Trait
 A trait definition lists method signatures that implementing types must satisfy. Like functions, these signatures place the return type before the method name.
 ```rust
 public trait Drawable {
    void draw(self*);
    str* metadata(self*);
 }
 ```
 ## Implementing a Trait
 To implement a trait for a specific type, use the `impl` keyword followed by the trait name and the target type. This block must contain all required methods defined in the trait.
 ```rust
 impl Drawable for Task {
    void draw(self*) {
        println!("Drawing task: {}", self.name);
    }
    str* metadata(self*) {
        return self.name;
    }
 }
 ```
 ## Default Implementations
 Traits can provide default behavior for methods. Types implementing the trait can choose to override these defaults or use the provided implementation.
 ```rust
 public trait Identifiable {
    u32 get_id(self*);
    bool is_valid(self*) {
        return self.get_id() > 0;
    }
 }
 ```
 ## Super-traits
 Traits can build upon other traits. If a trait requires another trait to be implemented first, use the colon `:` syntax.
 ```rust
 public trait Animated : Drawable {
    void animate(self*, f32 delta_time);
 }
 ```
 ## Key Characteristics
 - **Consistent Signatures**: Method signatures within traits follow the language-wide `return_type name(params)` convention.
 - **Explicit Context**: Methods use `self*` or `self mut*` as the first parameter to define how the instance is accessed, mapping directly to Rust's reference rules.
 - **Static Dispatch**: By default, Mist traits leverage Rust's zero-cost generics and monomorphization, ensuring high performance.
 - **Predictable Contracts**: Traits act as strict blueprints; the Mist compiler ensures every implementation perfectly matches the interface before generating the corresponding Rust code.
@@ -1,66 +0,0 @@
 ---
 title: Get Started
 description: This guide will help you install the Mist CLI, understand its basic commands, and compile your first program.
 icon: Rocket
 ---
 ## Installation
 Mist is distributed through Cargo.
 Install the Mist compiler using:
 ```bash title="Terminal"
 cargo install [email protected]
 ```
 Verify using
 ```bash title="Terminal"
 mist version
 ```
 ---
 ## Usage
 ```bash title="Compiles the project in the current directory"
 mist build
 ```
 ```bash title="Prints the compiler version"
 mist version
 ```
 ```bash title="Shows the help message and available commands"
 mist help
 ```
 ---
 ## Hello World
 On your existing cargo project project (`cargo init` or `cargo new <name>`).
 ```json title="mist.json"
 {
  "src": "src",
  "output": "build"
 }
 ```
 ```toml title="Cargo.toml"
 [[bin]]
 name = "main"
 path = "build/main.rs"
 ```
 ```bash title=".gitignore"
 /build
 ```
 ```cpp title="src/main.mist"
 void main() {
    println!("Hello World!");
 }
 ```
@@ -1,41 +1,97 @@
 ---
-title: Introduction
+title: Get Started
-description: What Mist is and the thinking behind it.
+description: This guide will walk you through installing the Mist CLI, setting up your development environment, and compiling your very first program.
-icon: Brain
+icon: Rocket
 ---
-Mist is a systems programming language that compiles directly into Rust.
+## 1. Installation
-It exists to make Rust-based development feel more direct and less mentally heavy, while preserving Rust’s performance model and ecosystem.
+Mist is currently distributed as a Cargo crate. To get started, you'll need to have the Rust toolchain installed.
-Mist does not replace Rust. It is another way of writing Rust-compatible systems code with a more ergonomic surface layer.
+Run the following command to install the Mist compiler:
 ```bash title="Terminal"
 cargo install [email protected]
 ```
 Once the installation finishes, verify it by checking the version:
 ```bash title="Terminal"
 mist version
 ```
 ---
-## Philosophy
+## 2. Setting Up Your Project
-Mist is built around making systems programming feel calm, predictable, and easy to reason about.
+Mist works alongside Cargo to handle the heavy lifting. Follow these steps to prepare your environment for your first "Hello World" program.
-When working close to the system, developers constantly manage performance, correctness, and structure at the same time. As projects grow, this can create mental friction — not because the system is unclear, but because expressing it can feel heavy.
+### Initialize a New Project
-Mist focuses on reducing that friction in how code is written and read, so attention stays on the problem being solved rather than the mechanics of expression.
+If you haven't already, create a new Cargo project and navigate into the directory:
-The language is shaped around clarity and flow: code should feel direct to write, and easy to understand when revisited.
+```bash title="Terminal"
 cargo new my-mist-app
 cd my-mist-app
 ```
 ### Configure Mist
 Create a `mist.json` file in your root directory. This tells the compiler where to look for your source code and where to place the generated Rust files.
 ```json title="mist.json"
 {
  "src": "src",
  "output": "build"
 }
 ```
 ### Link Cargo to Mist
 Since Mist compiles down to Rust, you need to point Cargo to the generated output. Update your `Cargo.toml` to include the following:
 ```toml title="Cargo.toml"
 [[bin]]
 name = "main"
 path = "build/main.rs"
 ```
 > **Pro Tip:** You’ll probably want to add `/build` to your `.gitignore` file to keep your repository clean!
 ---
-## What Mist Is
+## 3. Your First Program
-Mist is a Rust-compatible systems language with a compiled-to-Rust design.
+Now for the fun part! Create a new file at `src/main.mist` and add the following code:
-This means:
+```cpp title="src/main.mist"
 void main() {
    println!("Hello World!");
 }
 ```
- It integrates directly with the Rust ecosystem
+### Build and Run
 - It compiles into idiomatic Rust code
 - It preserves Rust’s performance characteristics
 - It has no runtime or garbage collector
 - It is designed to stay predictable and close to the metal
-Mist provides a more ergonomic way of authoring systems code while remaining fully grounded in Rust’s type system and execution model.
+To turn your Mist code into an executable, use the `build` command:
-It is especially designed for readability and structure in larger codebases, where Rust’s guarantees remain important but expression overhead becomes noticeable.
+```bash title="Terminal"
 mist build
 ```
 Once the build is successful, you can run your program using standard Cargo commands:
 ```bash title="Terminal"
 cargo run
 ```
 > **Pro Tip:** If you encounter any rust errors, head to the build directory and analyze the output, if you see anything unusual in the output, report the issue at https://github.com/mist-go/mist
 ---
 ## Command Reference
 | Command        | Description                                                      |
 | -------------- | ---------------------------------------------------------------- |
 | `mist build`   | Compiles your `.mist` files into Rust code in the output folder. |
 | `mist version` | Displays the current version of the Mist compiler.               |
 | `mist help`    | Stuck? Use this to see all available commands and options.       |
@@ -0,0 +1,70 @@
 ---
 title: Status & Limitations
 description: Understanding the Alpha state of Mist and our technical roadmap.
 icon: TriangleAlert
 ---
 Mist is currently in a **Volatile Alpha** stage. Our current priority is exploring **Syntax and Features**. We believe in stabilizing the developer experience and the "feel" of the language before locking in the deep architectural logic of the compiler.
 ---
 ## The "Syntax-First" Philosophy
 Mist is currently in a phase of rapid iteration. We are intentionally keeping the **Semantics** flexible while we finalize the **Syntax**.
 * **The Goal:** Finalize a robust, ergonomic feature set first.
 * **The Reasoning:** Implementing complex semantic analysis while features are still being added is inefficient. By stabilizing the syntax first, we ensure that adding full semantic depth becomes a cohesive, "single-step" process later in development.
 ---
 ## Current Technical Trade-offs
 To allow for this rapid syntax exploration, the compiler currently uses a "Shim" model for certain complex Rust operations.
 ### 1. The Construction Model
 To support Mist's unified **Class and Constructor** model, the compiler uses an experimental memory initialization pattern.
 * **Mechanism:** The compiler generates a "shell" using `MaybeUninit`, allowing `self` to be used inside the constructor logic.
 * **Limitation:** Because full **Definite Assignment Analysis** (semantics) is not yet implemented, the compiler does not verify that every field is assigned. It currently relies on zeroing out memory as a placeholder.
 * **Future Fix:** Once the syntax is frozen, we will implement the semantic checks required to generate standard, safe Rust struct literals.
 ### 2. Inheritance
 Inheritance is a major planned feature but is currently **not implemented**.
 * **Status:** The syntax for inheritance is being designed, but it will not be functional until the semantic analyzer is built to handle v-tables and memory layouts in the emitted Rust code.
 ---
 ## Feature Volatility
 Be aware that because we are focusing on syntax, keywords and structures may change between minor versions. Currently:
 * **Access Modifiers:** `public` and private defaults are being tested for various contexts (classes vs. structs, or `public(crate)`).
 * **Pointers vs. References:** The `*` syntax for references (e.g., `self mut*`) is the current standard but is subject to refinement based on ecosystem feedback.
 * **Trait Implementations:** The "In-Class" `impl` block is a core feature we are prioritizing for ergonomics.
 ---
 > **Alpha Warning:** Mist is currently a playground for defining a better way to write systems code. Expect breaking changes as we finalize the surface layer of the language.
 > 
 > 
@@ -0,0 +1,93 @@
 ---
 title: Control Flow
 description: Directing execution with expression-based logic, pattern matching, and traditional loop structures.
 icon: Split
 ---
 Control flow in Mist provides a bridge between C-style procedural logic and Rust's expression-oriented design. While many structures can return values, they follow a strict syntax for blocks and statements.
 ## Conditionals
 The `if` statement evaluates a boolean expression. It supports multiple `else if` branches and an optional `else` block.
 ```cpp
 if (score > 50) {
    println!("Pass");
 } else if (score == 50) {
    println!("Borderline");
 } else {
    println!("Fail");
 }
 ```
 ## Match
 The `match` statement provides exhaustive pattern matching. Currently, every match arm requires a block `{}` following the `=>` operator.
 ```cpp
 match (task_state) {
    TaskState::Pending => {
        println!("Queued");
    }
    TaskState::Failed { reason, code } => {
        println!("Error {}: {}", code, reason);
    }
    _ => {
        println!("Other state");
    }
 }
 ```
 ## Loops
 Mist supports both functional iteration and traditional low-level loop control.
 ### C-Style For Loop
 For manual iteration control, Mist supports the standard three-part `for` loop: initialization, condition, and post-iteration statement.
 ```cpp
 for (var mut i = 0; i < 10; i = i + 1;) {
    println!("Index: {}", i);
 }
 ```
 ### For-In Loop
 The `for-in` loop iterates over collections or iterators using Mist's pattern matching system.
 ```cpp
 for (var item in collection) {
    process(item);
 }
 // Destructuring within the loop
 for ((i32 x, i32 y) in coordinates) {
    draw_point(x, y);
 }
 ```
 ### While Loop
 The `while` loop continues execution as long as the parenthesized expression evaluates to `true`.
 ```cpp
 while (active) {
    wait_for_event();
 }
 ```
 ## Jump Statements
 Execution flow can be interrupted or redirected using standard jump keywords.
 - **`return`**: Exits the current function, optionally passing back a value.
 - **`break`**: Terminates the innermost looping construct.
 - **`continue`**: Skips the remainder of the current loop iteration and proceeds to the next.
 ## Key Characteristics
 - **Pattern Integration**: Loops and match arms utilize Mist's pattern system, allowing for seamless data destructuring during iteration.
 - **Explicit Scoping**: Match items currently require explicit blocks, ensuring clear boundaries for variable shadowing and local logic.
 - **Familiar Iteration**: The inclusion of C-style `for` loops provides fine-grained control for performance-critical logic where simple iteration is insufficient.
 - **Rust-Native Safety**: Despite the procedural syntax, these structures compile to safe Rust, maintaining exhaustive checking and memory safety.
@@ -0,0 +1,83 @@
 ---
 title: Expressions
 description: The building blocks of logic, from literals to complex postfix chains.
 icon: Binary
 ---
 Expressions in Mist are the fundamental units that evaluate to a value. The syntax follows a clean **prefix → primary → postfix** chain, providing a predictable structure that maps closely to Rust's mental model.
 ## Primary Expressions
 Primary expressions are the starting point of any logic chain. These include literal values, paths to static members, or grouped expressions in tuples.
 ```java
 // Literals and paths
 var x = 42;
 var y = Math::PI;
 // Tuples
 var coordinates = (10, 20, 30);
 ```
 ## Postfix Operations
 Postfix expressions allow you to build on a primary value. This includes calling functions, accessing fields, indexing arrays, or initializing structs.
 ```java
 // Field access and method/function calls
 var len = list.length();
 // Struct initialization
 var task = Task {
    name: "Drafting",
    priority: 1,
 };
 // Indexing and Macro calls
 var first = items[0];
 println!("Value: {}", first); // Macro call via '!'
 ```
 ## Prefix Operations
 Prefixes modify the primary expression that follows them. Mist uses these for logical negation, dereferencing, and creating references.
 ```java
 var mut value = 10;
 var ref = &value;         // Reference
 var mref = &mut value;    // Mutable reference
 var val = *ref;           // Dereference
 var is_false = !true;     // Logical NOT
 ```
 ## Binary Operations
 Binary operations are applied as postfixes to an expression, following a `bin_op ~ expr` pattern. This supports all standard arithmetic, comparison, and logical operators.
 ```java
 var sum = 10 + 20;
 var is_equal = (x == y);
 var complex = (a + b) * (c / d);
 ```
 ## Operator Table
 Mist supports the following binary operators for comparisons and arithmetic:
 | Category       | Operators                        |
 | -------------- | -------------------------------- |
 | **Arithmetic** | `+`, `-`, `*`, `/`, `%`          |
 | **Comparison** | `==`, `!=`, `<`, `>`, `<=`, `>=` |
 | **Logical**    | `&&`, `\|\|`                     |
 ## Key Characteristics
 - **Predictable Chaining**: The `prefix* ~ primary ~ postfix*` grammar ensures that complex expressions are parsed consistently, whether you are dereferencing a function call or indexing a struct field.
 - **Rust-Style References**: While the pointer syntax `type*` is used in declarations, expressions use `&` and `&mut` to create references, maintaining compatibility with Rust's borrow checker.
 - **Macro Integration**: Macros are treated as a postfix operation (`!`), allowing them to be called on identifiers just like standard functions.
 - **Unified Tuples**: Tuples are primary expressions, allowing them to be passed, returned, or destructured seamlessly within the expression tree.
@@ -0,0 +1,65 @@
 ---
 title: Variables
 description: Local state management with type inference and explicit mutability.
 icon: Variable
 ---
 In Mist, variables follow the language-wide `type name` convention. For local scope, the `var` keyword provides type inference, while explicit types can be used for clarity or strictness.
 ## Basic Declaration
 Variables are declared using the `var` keyword for automatic type inference. Like Rust, variables are immutable by default.
 ```java
 var message = "Hello Mist"; // Inferred as str*
 var count = 42;             // Inferred as i32
 ```
 ## Mutability
 To allow a variable to be reassigned, use the `mut` modifier after the `var` keyword or the explicit type.
 ```rust
 var mut score = 0;
 score = 100;
 f32 mut price = 19.99;
 price = 14.99;
 ```
 ## Explicit Typing
 While `var` handles inference, you can explicitly define the type before the identifier. This is often used for clarity in complex logic or when the specific numeric width (e.g., `u8` vs `i32`) matters.
 ```rust
 u64 large_id = 1000234;
 bool is_active = true;
 ```
 ## Pattern Destructuring
 Because variable declarations are patterns, you can destructure tuples or structures directly. This keeps data extraction clean and avoids manual indexing.
 ```rust
 // Destructuring a tuple into local variables
 (i32, i32) (x, y) = get_coordinates();
 // Using 'var' within a pattern for inference
 (String, i32) (name, age) = get_user_info();
 ```
 ## Constants
 Constants are immutable values that are evaluated at compile time. They require an explicit type and follow the `const` keyword.
 ```rust
 const i32 MAX_RETRIES = 5;
 const str* VERSION = "1.0.4";
 ```
 ## Key Characteristics
 - **Predictable Order**: Whether using `var` or an explicit type, the name of the variable always follows the "source" of its data.
 - **Safety First**: Immutability by default prevents accidental state changes, mapping directly to Rust's memory safety model.
 - **Zero-Cost Inference**: Type inference is handled entirely at compile time, ensuring there is no runtime performance penalty.
 - **Shadowing**: Mist supports variable shadowing, allowing you to reuse variable names within the same scope to transform data without changing mutability.
@@ -0,0 +1,21 @@
 {
    "pages": [
        "---[Rocket]Introduction---",
        "index",
        "philosophy",
        "limitations",
        "---[Box]Components---",
        "components/functions",
        "components/structs",
        "components/enums",
        "components/classes",
        "components/traits",
        "components/pointers-references",
        "---[ArrowDownUp]Logic---",
        "logic/variables",
        "logic/control-flow",
        "logic/expressions"
    ]
 }
@@ -0,0 +1,43 @@
 ---
 title: Philosophy
 description: The mindset, ergonomics, and feeling of writing Mist.
 icon: Brain
 ---
 **Mist** is a systems programming language designed for those who value the "craft" of software. It is built to provide a serene, tactile authoring environment that stays out of your way, allowing you to focus entirely on the architecture of your solution.
 By compiling directly to Rust, Mist offers a refined surface layer that maintains industrial-grade safety and performance while prioritizing a flow state that is often lost in modern systems development.
 ---
 ## The Philosophy of Ergonomics
 Writing Mist should feel intentional and deeply satisfying. It is built on the belief that systems programming is at its best when it is **calm, predictable, and direct**.
 ### Reducing Expression Overhead
 Complexity often arises from "expression overhead"—the mental energy spent navigating intricate syntax and symbols. Mist reduces this friction by:
 * **Predictable Flow:** By adopting a consistent `type name` convention, code follows a natural rhythm that is easy to write and instantly scannable.
 * **Structural Clarity:** Features like unified `class` blocks and explicit `constructor` keywords provide a clear, organized home for your logic, reducing the need to jump between disparate files or implementation blocks.
 * **Tactile Precision:** Every symbol, from `mut*` pointers to pattern-based variables, is designed to feel physically connected to the data it represents, making the "mechanics" of the language feel like a well-calm tool in your hand.
 ---
 ## A Transparent Surface Layer
 Mist is not a replacement for Rust; it is a **ergonomic interface** for it. It provides a way to interact with the world’s most powerful systems model through a cleaner lens.
 * **Zero-Cost Abstractions:** Every high-level structure in Mist—whether it’s a class, an enum variant, or a trait implementation—maps directly to an optimized Rust primitive. There is no "magic," no hidden runtime, and no garbage collector.
 * **Grounded Safety:** Mist doesn't hide memory safety; it makes it easier to express. You retain the full power of the borrow checker, but with a syntax that feels like a classic, high-performance toolkit.
 * **Native Fluency:** Because Mist compiles to idiomatic, readable Rust, it is a first-class citizen of the ecosystem. You can utilize any existing crate while writing code that feels uniquely "Mist".
 ---
 ## Why Mist?
 Mist is for the developer who needs the rigor of a systems language but wants the comfort of a modern, streamlined environment.
 * **Mental Longevity:** Designed for large-scale codebases where readability is paramount to long-term maintenance.
 * **Direct Control:** You stay close to the metal, but the language handles the "noise" of idiomatic expression.
 * **Craftsmanship:** Mist is where the discipline of systems programming meets the comfort of a high-end workshop.
@@ -0,0 +1,7 @@
 .no-scrollbar::-webkit-scrollbar {
  display: none;
 }
 .no-scrollbar {
  -ms-overflow-style: none;
  scrollbar-width: none;
 }
@@ -1,6 +1,13 @@
-import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { HomeLayout } from "fumadocs-ui/layouts/home";
-import { baseOptions } from '@/lib/layout.shared';
+import { baseOptions } from "@/lib/layout.shared";
-export default function Layout({ children }: LayoutProps<'/'>) {
+export default function Layout({ children }: LayoutProps<"/">) {
-  return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
+  return (
    <HomeLayout
      {...baseOptions()}
      className="h-full overflow-hidden no-scrollbar"
    >
      {children}
    </HomeLayout>
  );
 }
@@ -6,6 +6,8 @@ import Link from "next/link";
 import { useEffect, useRef, useState } from "react";
 import { motion, Variants } from "framer-motion";
 import "./Home.css";
 const MotionLink = motion(Link);
 export const mistShowcase = [
@@ -73,24 +75,12 @@ public class PluginRegistry<T> {
        self.prefix = prefix.to_string();
    }
-    public void log(self*, LogLevel level, str* message) {
+    void log(self*, LogLevel level, str* message) {
-        match(level) {
+        println!("{level} {} {}", self.prefix, message);
            LogLevel::Info => {
                println!("{level} {} {}", self.prefix, message);
            }
            LogLevel::Warning => {
                println!("{level} {} {}", self.prefix, message);
            }
            LogLevel::Error => {
                println!("{level} {} {}", self.prefix, message);
            }
        }
    }
    impl fmt::Display {
-        fmt::Result fmt(self*, std::fmt::Formatter<'_> mut* f) {
+        std::fmt::Result fmt(self*, std::fmt::Formatter<'_> mut* f) {
            return write!(f, "logger ({})", self.prefix);
        }
    }
@@ -152,7 +142,7 @@ function ShowSection({
  return (
    <motion.section
      ref={ref}
-      className="h-svh p-10 md:p-20 w-full flex flex-col items-center justify-center"
+      className="h-svh p-10 md:p-20 w-full flex flex-col items-center justify-center snap-center"
    >
      <motion.div
        className="flex flex-col gap-2 items-center justify-center"
@@ -175,7 +165,7 @@ function ShowSection({
            <MotionLink
              variants={item}
              className="bg-fd-primary/15 text-fd-primary/90 p-3 px-4.5 rounded-xl cursor-pointer hover:bg-fd-primary/20 hover:text-fd-primary flex gap-2 items-center"
-              href="/docs/get-started"
+              href="/docs"
            >
              <RocketIcon className="w-5 h-5" />
              Get Started
@@ -200,51 +190,45 @@ export default function HomePage() {
  const [currentText, setCurrentText] = useState(mistShowcase[0]?.code || "");
  return (
-    <div className="flex w-full flex-col xl:flex-row">
+    <div className="h-[calc(100vh-58px)] overflow-auto snap-y snap-mandatory scroll-smooth no-scrollbar relative flex flex-col xl:flex-row">
-      <div className="flex fixed xl:top-0 xl:right-0 w-svw xl:w-[40vw] h-svh xl:items-center mt-10 justify-center z-50 pointer-events-none">
+      <div className="hidden pointer-events-none sticky top-0 right-0 z-50 md:flex order-first xl:order-last w-full xl:w-[40vw] h-svh items-center justify-center p-10 no-scrollbar">
-        <div className="xl:w-full overflow-hidden">
+        <div className="w-full max-w-2xl overflow-hidden no-scrollbar">
          <motion.div
-            className="w-max h-auto border border-fd-border p-5 rounded-xl min-h-24 backdrop-blur bg-black dark:bg-black/20"
+            className="will-change-transform transform-gpu w-full h-auto border border-fd-border p-5 rounded-xl min-h-24 backdrop-blur bg-black dark:bg-black/20 pointer-events-auto"
            variants={item}
            initial="hidden"
            animate="show"
          >
-            <MorphCode code={currentText} />
+            <MorphCode code={currentText} key="morph-code-logic" />
          </motion.div>
        </div>
      </div>
-      <div className="flex-1">
+      <div className="flex-1 w-full xl:w-[60vw]">
-        <div className="mt-10 xl:mt-0">
+        {mistShowcase.map((show) => (
-          {mistShowcase.map((show) => (
+          <ShowSection
-            <ShowSection
+            key={show.title}
-              key={show.title}
+            show={show}
-              show={show}
+            setActiveCode={setCurrentText}
-              setActiveCode={setCurrentText}
+          />
-            />
+        ))}
          ))}
        </div>
      </div>
-      <div className="xl:w-[40vw]" />
+
      {/* <div className="absolute left-1/2 bottom-1">
      </div> */}
      <motion.div
        initial={{ opacity: 0, y: -8 }}
        animate={{ opacity: 1, y: 0 }}
        transition={{ duration: 0.6 }}
-        className="absolute bottom-8 left-1/2 -translate-x-1/2"
+        className="fixed bottom-8 left-1/2 -translate-x-1/2 pointer-events-none z-50"
      >
        <motion.div
          animate={{ y: [0, 10, 0] }}
-          transition={{
+          transition={{ duration: 1.5, repeat: Infinity, ease: "easeInOut" }}
            duration: 1.5,
            repeat: Infinity,
            ease: "easeInOut",
          }}
          className="flex flex-col items-center gap-1 text-muted-foreground"
        >
-          <ChevronsDownIcon className="h-6 w-6 text-fd-primary" strokeWidth={1.5} />
+          <ChevronsDownIcon
            className="h-6 w-6 text-fd-primary"
            strokeWidth={1.5}
          />
        </motion.div>
      </motion.div>
    </div>
@@ -39,7 +39,7 @@ export default function MorphCode({ code, lang = "rust" }: Props) {
  }, [code, lang]);
  return (
-    <pre className="text-sm">
+    <pre className="text-sm overflow-x-scroll overflow-y-hidden">
      <code>
        <AnimatePresence mode="popLayout">
          {lines.map((line, lineIndex) => (