fax-lang 0.0.1

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Create a file with code '...'
+2. Run 'fax build file.fx'
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots/Logs**
+If applicable, add screenshots or compiler logs to help explain your problem.
+
+**Environment:**
+ - OS: [e.g. Linux, macOS]
+ - Node version: [e.g. 20.x]
+ - LLVM version: [e.g. 18]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature Request
+about: Suggest an idea for Fax-lang
+title: '[FEAT] '
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Description
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
+
+Fixes # (issue)
+
+## Type of change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## How Has This Been Tested?
+Please describe the tests that you ran to verify your changes.
+
+## Checklist:
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes

package/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          
+      - name: Install LLVM
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y llvm clang lld
+          
+      - name: Install Dependencies
+        run: npm install
+        
+      - name: Lint
+        run: npm run lint
+        
+      - name: Run Tests
+        run: npm test

package/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'book/**'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install mdBook
+        run: |
+          mkdir bin
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.37/mdbook-v0.4.37-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C bin
+          echo "$(pwd)/bin" >> $GITHUB_PATH
+
+      - name: Build Documentation
+        run: |
+          mdbook build book
+          # Copy the root landing page and assets into the site folder for deployment
+          cp index.html site/
+          cp -r assets site/
+          # Ensure .nojekyll exists
+          touch site/.nojekyll
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/CNAME

@@ -0,0 +1 @@
+fax-lang.js.org

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luvion1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,37 @@
+# Fax-lang Makefile
+
+PREFIX ?= /usr/local
+BINDIR = $(PREFIX)/bin
+
+.PHONY: all build test clean install uninstall docs
+
+all: build
+
+build:
+	npm run build
+
+test:
+	npm test
+
+clean:
+	rm -rf dist/
+	find . -name "*.tmp.ll" -delete
+	find . -name "*.tmp.o" -delete
+	rm -f examples/mvp examples/logic examples/logic_if
+
+docs-serve:
+	cd book && mdbook serve --open
+
+docs-build:
+	cp assets/logo.svg book/src/logo.svg
+	cd book && mdbook build
+
+install: build
+	mkdir -p $(BINDIR)
+	cp dist/index.js $(BINDIR)/fax
+	chmod +x $(BINDIR)/fax
+	@echo "Fax-lang installed to $(BINDIR)/fax"
+
+uninstall:
+	rm -f $(BINDIR)/fax
+	@echo "Fax-lang removed."

package/README.md

@@ -0,0 +1,97 @@
+<p align="center">
+  <img src="assets/logo.svg" width="180" height="180" />
+</p>
+
+<h1 align="center">Fax-lang</h1>
+
+<p align="center">
+  <strong>A Modern Systems Programming Language with Life-Force Memory Management</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Luvion1/Fax-lang/actions"><img src="https://github.com/Luvion1/Fax-lang/workflows/CI/badge.svg" alt="CI Status"></a>
+  <a href="https://github.com/Luvion1/Fax-lang/actions"><img src="https://github.com/Luvion1/Fax-lang/workflows/Deploy%20Docs/badge.svg" alt="Docs Status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</p>
+
+---
+
+## 🦊 What is Fax-lang?
+
+Fax-lang is a high-performance systems programming language built on top of LLVM. It introduces a revolutionary approach to memory safety called **Life-Force Tracking**, allowing for deterministic memory management without the overhead of a Garbage Collector or the complexity of a traditional Borrow Checker.
+
+## ✨ Core Pillars
+
+### 1. Life-Force Memory System (Rule 2)
+Every variable is born with "energy" that decays through usage.
+- **Read**: -0.02 | **Write**: -0.08
+- When life-force reaches zero, the variable is automatically reclaimed. This ensures memory safety through a deterministic, usage-based lifecycle.
+
+### 2. Contractual State Machines (Rule 4)
+State machines are first-class citizens. Transitions are verified at compile-time to prevent illegal states.
+```fax
+state_machine Connection {
+    state Closed {
+        fn connect() -> Connecting { ... }
+    }
+}
+```
+
+### 3. Shadow & Mirroring (Rule 1)
+Manage data access via **Shadows** (read-only views) that lazily create **Mirrors** only for modified segments, optimizing cache locality and performance.
+
+### 4. Unified Memory Space (Rule 3)
+The compiler automatically analyzes access patterns to decide whether data should reside on the **Stack**, **Heap**, or a **Hybrid** of both.
+
+---
+
+## 🛠 Getting Started
+
+### Prerequisites
+- **Node.js** (v18 or newer)
+- **LLVM** (llc & clang v14/18)
+
+### Installation
+```bash
+git clone https://github.com/Luvion1/Fax-lang.git
+cd Fax-lang
+npm install
+```
+
+---
+
+## 🚀 Usage
+
+### Compiling Programs
+```bash
+# Build a binary from a .fx file
+npm run dev build examples/mvp.fx
+
+# Execute the output
+./examples/mvp
+```
+
+### AST Visualization
+```bash
+npm run dev ast examples/mvp.fx
+```
+
+---
+
+## 📖 Documentation
+The official documentation is built with **mdBook** and is available in the `book/` directory.
+
+To serve documentation locally:
+```bash
+cd book
+mdbook serve --open
+```
+
+## 🤝 Contributing
+Contributions are welcome! Please feel free to submit a Pull Request or open an Issue to discuss potential changes.
+
+---
+
+<p align="center">
+  Built with ❤️ by <a href="https://github.com/Luvion1">Luvion1</a>
+</p>

package/assets/logo.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <defs>
+    <linearGradient id="kawaiiGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#FFB347;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#FF8C00;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  
+  <!-- Soft Shadow for Kawaii Sticker Look -->
+  <circle cx="256" cy="270" r="230" fill="#000" opacity="0.05"/>
+
+  <!-- Fluffy Big Tail -->
+  <path d="M360 300c60-20 120 20 120 90s-50 100-110 100-90-40-90-80c0-50 40-90 80-110z" fill="#FF8C00" />
+  <path d="M480 390c0 40-30 70-70 80 20-10 40-30 40-50s-10-40-40-50c40 10 70 20 70 20z" fill="#FFFFFF" />
+
+  <!-- Round Chibi Body -->
+  <circle cx="256" cy="380" r="100" fill="url(#kawaiiGrad)" />
+  <path d="M256 460c-40 0-70-20-70-50s30-20 70-20 70 10 70 20-30 50-70 50z" fill="#FFFFFF" opacity="0.8"/>
+
+  <!-- Oversized Kawaii Head -->
+  <circle cx="256" cy="220" r="160" fill="url(#kawaiiGrad)" />
+
+  <!-- Big Rounded Ears -->
+  <path d="M140 100l-50-60c-10-15 15-20 25-10l65 50" fill="#FF8C00" stroke="#E67E22" stroke-width="8" stroke-linejoin="round"/>
+  <path d="M372 100l50-60c10-15-15-20-25-10l-65 50" fill="#FF8C00" stroke="#E67E22" stroke-width="8" stroke-linejoin="round"/>
+  <path d="M150 90l-20-25c-3-4 5-8 8-4l30 20" fill="#FFD1DC"/>
+  <path d="M362 90l20-25c3-4-5-8-8-4l-30 20" fill="#FFD1DC"/>
+
+  <!-- Fluffy White Cheeks -->
+  <path d="M110 240c0 50 60 80 146 80s146-30 146-80-60-60-146-60-146 10-146 60z" fill="#FFFFFF"/>
+
+  <!-- Large Sparkling Kawaii Eyes -->
+  <g>
+    <circle cx="180" cy="230" r="40" fill="#2C3E50"/>
+    <circle cx="165" cy="215" r="15" fill="#FFFFFF"/> 
+    <circle cx="195" cy="245" r="7" fill="#FFFFFF" opacity="0.6"/>
+  </g>
+  <g>
+    <circle cx="332" cy="230" r="40" fill="#2C3E50"/>
+    <circle cx="317" cy="215" r="15" fill="#FFFFFF"/> 
+    <circle cx="347" cy="245" r="7" fill="#FFFFFF" opacity="0.6"/>
+  </g>
+
+  <!-- Blush (Pink Ovals) -->
+  <ellipse cx="120" cy="280" rx="30" ry="18" fill="#FFB6C1" opacity="0.7"/>
+  <ellipse cx="392" cy="280" rx="30" ry="18" fill="#FFB6C1" opacity="0.7"/>
+
+  <!-- Tiny Nose and 'w' Mouth -->
+  <path d="M256 250l-6 8h12z" fill="#1a1a1b"/>
+  <path d="M230 275c10 10 20 10 26 0s16 10 26 0" fill="none" stroke="#1a1a1b" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/book/book.toml

@@ -0,0 +1,14 @@
+[book]
+authors = ["Luvion1"]
+language = "en"
+src = "src"
+title = "The Fax-lang Book"
+
+[build]
+build-dir = "../site/book"
+
+[output.html]
+git-repository-url = "https://github.com/Luvion1/Fax-lang"
+edit-url-template = "https://github.com/Luvion1/Fax-lang/edit/main/book/{path}"
+
+[preprocessor.links]

package/book/src/README.md

@@ -0,0 +1,20 @@
+# Introduction to Fax-lang
+
+<img src="logo.svg" alt="Fax Logo" width="100">
+
+Welcome to the **Fax Programming Language** documentation.
+
+Fax is a systems programming language designed for **extreme memory safety** and **deterministic state transitions** without a garbage collector or traditional borrow checker.
+
+## Core Philosophy
+
+Fax-lang is built on four fundamental pillars:
+
+1.  **Contractual State Machines**: State transitions are first-class citizens and are verified at compile-time.
+2.  **Life-Force Tracking**: Every variable has an "energy" level that decays with usage, preventing over-use and ensuring deterministic cleanup.
+3.  **Shadow & Mirroring**: Data access is managed through read-only views (shadows) that lazily create mirrors for modifications.
+4.  **Unified Memory Space**: The compiler automatically decides whether data lives on the stack, heap, or a hybrid of both based on access patterns.
+
+## Why Fax?
+
+Traditional languages either use garbage collection (which introduces latency) or manual memory management/borrow checking (which can be complex). Fax-lang introduces a **probabilistic yet deterministic** approach to memory safety through the concept of **Life-Force**.

package/book/src/SUMMARY.md

@@ -0,0 +1,26 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Getting Started](guide/getting_started.md)
+- [Installation](guide/installation.md)
+
+# Language Basics
+
+- [Variables & Mutability](guide/variables.md)
+- [Data Types](guide/types.md)
+- [Functions](guide/functions.md)
+- [Control Flow](guide/control_flow.md)
+
+# Advanced Concepts
+
+- [The Four Rules](concepts/the_four_rules.md)
+- [State Machines (Contractual States)](concepts/state_machines.md)
+- [Memory Management: Life-Force](concepts/life_force.md)
+- [Shadow & Mirroring](concepts/shadow_mirroring.md)
+- [Unified Memory Space](concepts/unified_memory.md)
+
+---
+
+- [Compiler Internals](concepts/internals.md)
+- [Syntax Reference](syntax.md)

package/book/src/concepts/internals.md

@@ -0,0 +1,15 @@
+# Compiler Internals
+
+The Fax-lang compiler is built with a modular architecture using TypeScript and LLVM.
+
+## Compilation Pipeline
+
+1.  **Lexer**: Tokenizes the source code.
+2.  **Parser**: Generates an Abstract Syntax Tree (AST).
+3.  **Semantic Checker**: Validates memory rules (Life-Force, State Transitions).
+4.  **Code Generator**: Produces LLVM IR (`.ll` files).
+5.  **LLVM Backend**: `llc` converts IR to object files, and `clang` links them to a native binary.
+
+## Unique Checks
+
+The **Semantic Checker** is the heart of Fax-lang. It maintains a metadata map of every variable to track its energy level and current state machine status at compile-time.

package/book/src/concepts/life_force.md

@@ -0,0 +1,41 @@
+# Memory Management: Life-Force
+
+The most unique feature of Fax-lang is its **Life-Force** system (Rule 2).
+
+## What is Life-Force?
+
+Every variable in Fax-lang is born with a life-force of `1.0`. As you use the variable, its life-force decays.
+
+- **Read Access**: Decays by `0.02`.
+- **Write Access**: Decays by `0.08`.
+- **Heavy Operations**: Decays by `0.15`.
+
+When a variable's life-force reaches `0.0`, the variable is considered **exhausted** and can no longer be accessed.
+
+## Why this system?
+
+This system prevents "hot-spot" memory access from becoming bottlenecks and encourages efficient code. It also provides a unique way to handle cleanup: when life-force is depleted, the compiler can deterministically schedule memory reclamation.
+
+## Boosting Life-Force
+
+You can "boost" a variable's life-force through certain operations, representing the "feeding" of data back into the hot path of the application.
+
+```fax
+let x = 10;
+// After many reads, x is low on energy.
+// The compiler tracks this semantically.
+```
+
+## Compilation Errors
+
+If you attempt to access a variable that the compiler determines *could* be exhausted, it will throw an `E002` error:
+
+```text
+error[E002]: variable `x` has been exhausted
+  --> main.fx:10:5
+   |
+10 |     let y = x;
+   |             ^~
+   |
+   = help: Energy depleted. Reading from this variable costs 0.02 Life-Force.
+```

package/book/src/concepts/shadow_mirroring.md

@@ -0,0 +1,33 @@
+# Shadow & Mirroring
+
+Fax-lang implements **Rule 1: Shadow & Mirroring with Page-based Copy**. This is a high-performance alternative to traditional Copy-on-Write (CoW).
+
+## Shadows
+
+A `shadow` is a read-only view of a variable. It shares the same **Life-Force** as the original variable.
+
+```fax
+let mut x = BigData::new();
+shadow y = x; // y is a read-only view of x
+```
+
+- Shadows are **read-only**.
+- Shadows share the energy consumption of the source.
+- Shadows do not move or copy data upon creation.
+
+## Mirroring (Differential Copy)
+
+When data is modified through a shadow (in more complex data structures like structs), Fax-lang uses **Differential Mirroring**.
+
+Unlike traditional CoW which might copy an entire object or large buffer, Fax-lang's mirroring works on a **page-level** (typically 4KB).
+
+1. **Access Tracking**: The compiler tracks which segments of the data are accessed through the shadow.
+2. **Lazy Mirroring**: Only when a segment is actually modified does the compiler create a "Mirror" of that specific page.
+3. **Reconciliation**: When the shadow is merged back or the original data is updated, only the mirrored pages are synchronized.
+
+This optimization ensures that even with massive data structures, small updates remain constant-time and cache-friendly.
+
+## Why not just use References?
+
+References in other languages often require complex lifetime tracking (like Rust) or garbage collection (like Java). Shadows provide a middle ground: they are safe, read-only views that are semantically tied to the original data's life-cycle, without the overhead of tracking every pointer's validity.
+

package/book/src/concepts/state_machines.md

@@ -0,0 +1,49 @@
+# State Machines (Contractual States)
+
+Fax-lang treats state machines as first-class citizens (Rule 4).
+
+## Definition
+
+A state machine is defined using the `state_machine` keyword. Unlike simple enums, Fax-lang state machines enforce **valid transitions** at compile-time.
+
+```fax
+state_machine Connection {
+    state Closed {
+        fn connect() -> Connecting {
+            // transition logic
+        }
+    }
+    
+    state Connecting {
+        fn established() -> Connected { ... }
+        fn timeout() -> Closed { ... }
+    }
+    
+    state Connected {
+        fn disconnect() -> Closed { ... }
+    }
+}
+```
+
+## The `any` Block
+
+The `any` block allows you to define transitions that are valid from **any** state. This is useful for error handling or global resets.
+
+```fax
+any {
+    fn emergency_shutdown() -> Closed {
+        // cleanup
+    }
+}
+```
+
+## Compile-time Safety
+
+The Fax-lang compiler ensures that you cannot call a transition function if the machine is not in the correct state.
+
+```fax
+let conn = Connection::Closed::new();
+conn.established(); // ERROR: 'established' is only valid in 'Connecting' state.
+```
+
+This prevents a whole class of bugs related to illegal state transitions in systems programming.

package/book/src/concepts/the_four_rules.md

@@ -0,0 +1,18 @@
+# The Four Rules of Fax-lang
+
+Fax-lang is built upon four fundamental rules that govern memory, state, and execution. These rules ensure performance and safety without a traditional garbage collector or complex borrow checker.
+
+## Rule 1: Shadow & Mirroring (Differential Copy)
+Data access is managed through read-only **Shadows**. When a modification is requested, instead of copying the entire data structure, the compiler creates a **Mirror** of only the modified segments (pages).
+
+## Rule 2: Life-Force (Adaptive Decay)
+Every variable has an energy level called **Life-Force**.
+- Accessing data consumes Life-Force.
+- When Life-Force reaches zero, the variable is exhausted.
+- This enforces efficient access patterns and enables deterministic cleanup.
+
+## Rule 3: Unified Memory Space (Context-Agnostic Allocation)
+The compiler, not the developer, decides where data lives (Stack, Heap, or Hybrid). This decision is based on the data's size, lifetime, and access frequency, optimizing for cache locality automatically.
+
+## Rule 4: Contractual States (State Machines)
+State machines are first-class citizens. Transitions are checked at compile-time, ensuring that a resource can only be used when it is in a valid state. This replaces many runtime checks and complex error handling logic.

package/book/src/concepts/unified_memory.md

@@ -0,0 +1,19 @@
+# Unified Memory Space
+
+Fax-lang employs **Rule 3: Context-Agnostic Allocation**.
+
+## The Concept
+
+In traditional systems languages, the developer must explicitly choose between the Stack and the Heap. Fax-lang removes this cognitive load by analyzing data usage patterns at compile-time.
+
+## How it Works
+
+The compiler builds an **Access Graph** for every variable:
+
+1.  **Stack Placement**: Small data (≤ 64 bytes) with short lifetimes and high-frequency access.
+2.  **Heap Placement**: Large data structures or variables that must persist beyond the current scope.
+3.  **Hybrid Placement**: A unique Fax-lang feature where "hot" parts of a structure stay on the stack for speed, while "cold" or large parts are transparently moved to the heap.
+
+## Topology Optimization
+
+The Unified Allocator also considers cache locality. If two variables are frequently accessed together, the compiler will attempt to place them in adjacent memory locations to minimize cache misses.

package/book/src/guide/control_flow.md

@@ -0,0 +1,44 @@
+# Control Flow
+
+Fax-lang provides standard control flow structures, but many of them function as **expressions**.
+
+## If Expressions
+
+In Fax-lang, `if` is an expression, meaning it returns a value.
+
+```fax
+let x = 10;
+let y = 20;
+
+let result = if x > y {
+    x
+} else {
+    y
+};
+```
+
+## Loops
+
+### While Loop
+The `while` loop continues as long as a condition is met. Note that every operation inside the loop consumes **Life-Force** from the involved variables.
+
+```fax
+let mut i = 0;
+while i < 10 {
+    i = i + 1;
+}
+```
+
+## Match Expressions (Experimental)
+
+> **Note:** `match` expressions are currently in the experimental phase and may not be fully supported by all backends.
+
+`match` provides powerful pattern matching, especially useful when working with **State Machines** or Enums.
+
+```fax
+match connection_state {
+    Closed => println("Retry?"),
+    Connected => println("Online"),
+    _ => println("Unknown")
+}
+```