add diagrams to docs

Author: hatemhosny

docs/docs/contribution/adding-languages.mdx

@@ -14,6 +14,36 @@ If you still have doubts if the language qualifies, [let's discuss it](https://g
 
 ## Checklist when adding
 
+```mermaid
+flowchart TD
+    A[Add Language] --> B["Create language specs<br/>src/livecodes/languages/"]
+    B --> C["Add to languages.ts<br/>or processors.ts"]
+
+    C --> D{"Compiler needs<br/>separate build?"}
+    D -->|Yes| E["Add to build script<br/>scripts/build.js"]
+    D -->|No| F{"New packages/<br/>static files?"}
+
+    F -->|Yes| G["Add to browser-compilers repo<br/>and CDN"]
+    F -->|No| H["Reference vendors.ts<br/>for CDN links"]
+
+    E --> H
+    G --> H
+
+    H --> I["Add name/aliases<br/>to sdk/models.ts"]
+    I --> J["Add editor support<br/>Monaco/CodeMirror/Prismjs"]
+    J --> K["Add language info<br/>html/language-info.html"]
+    K --> L{"Starter template?"}
+
+    L -->|Yes| M["Create template<br/>Add to TemplateList, command-menu,<br/>language-info"]
+    L -->|No| N["Add e2e tests"]
+
+    M --> N
+    N --> O["Add language docs<br/>docs/docs/languages/"]
+    O --> P["Add to docs slider<br/>LanguageSliders.tsx"]
+    P --> Q["Add licenses<br/>vendor-licenses.mdx"]
+    Q --> R["Update badge<br/>README.mdx"]
+```
+
 - [ ] Add [language specs](https://github.com/live-codes/livecodes/tree/develop/src/livecodes/languages) and include that in the list of [languages](https://github.com/live-codes/livecodes/blob/develop/src/livecodes/languages/languages.ts) or [processors](https://github.com/live-codes/livecodes/blob/develop/src/livecodes/languages/processors.ts).
 - [ ] The compiler +/- formatter should be lazy-loaded.
 - [ ] If the compiler needs a separate build, add it to the [build script](https://github.com/live-codes/livecodes/blob/3a2617850f09487b9af92de862093f082942b8a9/scripts/build.js#L207).

docs/docs/contribution/build-system.mdx

@@ -39,6 +39,17 @@ The main build script is located at [`scripts/build.js`](../../../scripts/build.
 
 ### Build Phases
 
+```mermaid
+flowchart LR
+    A[1. Preparation] --> B[2. ESM Build]
+    B --> C[3. IIFE Build]
+    C --> D[4. Workers Build]
+    D --> E[5. Styles Build]
+    E --> F[6. SDK Build]
+    F --> G[7. I18n Build]
+    G --> H[Post-Build<br/>Hash & CSS Injection]
+```
+
 #### 1. Preparation (`prepareDir`)
 
 - Creates output directories (`build/livecodes/`, `build/sdk/`, `build/tmp/`)

docs/docs/contribution/code-formatting-system.mdx

@@ -8,19 +8,17 @@ LiveCodes uses [Prettier](https://prettier.io/) as the primary code formatter, w
 
 ## Architecture
 
-```
-┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
-│     core.ts      │────▶│  get-formatter.ts │────▶│   formatter.ts   │
-│  (format call)   │     │  (factory)        │     │  (Web Worker)    │
-└──────────────────┘     └──────────────────┘     └──────────────────┘
-                                                          │
-                                                          ▼
-                                                 ┌──────────────────┐
-                                                 │ format.worker.ts │
-                                                 │  - Prettier      │
-                                                 │  - Custom parsers │
-                                                 │  - Custom formatters │
-                                                 └──────────────────┘
+```mermaid
+flowchart LR
+    A[core.ts<br/>format call] --> B[get-formatter.ts<br/>factory]
+    B --> C[formatter.ts<br/>Web Worker]
+    C --> D[format.worker.ts]
+    
+    subgraph "Worker Content"
+        D --> E[Prettier]
+        D --> F[Custom parsers]
+        D --> G[Custom formatters]
+    end
 ```
 
 ## Formatter Interface

docs/docs/contribution/compiler-system.mdx

@@ -18,21 +18,35 @@ The compiler system uses a **worker-based architecture** to perform compilation
 
 ### Key Components
 
-```
-src/livecodes/compiler/
-├── index.ts              # Public API exports
-├── models.ts             # Type definitions
-├── create-compiler.ts    # Main compiler factory
-├── get-compiler.ts       # Compiler instance getter
-├── get-all-compilers.ts  # Compiler registry builder
-├── compile.worker.ts     # Web Worker for compilation
-├── compile.page.ts       # Page-level compilers
-├── compile-in-compiler.ts# Worker communication helper
-├── compile-blocks.ts     # SFC block compilation
-├── compiler-sandbox.ts   # iframe sandbox creation
-├── import-map.ts         # Import resolution utilities
-├── compiler-utils.ts     # iframe initialization
-└── utils.ts              # Utility functions
+```mermaid
+graph TD
+    subgraph "src/livecodes/compiler/"
+        A[index.ts] --> B[models.ts]
+        A --> C[create-compiler.ts]
+        A --> D[get-compiler.ts]
+        A --> E[get-all-compilers.ts]
+        A --> F[compile.worker.ts]
+        A --> G[compile.page.ts]
+        A --> H[compile-in-compiler.ts]
+        A --> I[compile-blocks.ts]
+        A --> J[compiler-sandbox.ts]
+        A --> K[import-map.ts]
+        A --> L[compiler-utils.ts]
+        A --> M[utils.ts]
+    end
+    
+    B["Type definitions"]
+    C["Main compiler factory"]
+    D["Compiler instance getter"]
+    E["Compiler registry builder"]
+    F["Web Worker for compilation"]
+    G["Page-level compilers"]
+    H["Worker communication helper"]
+    I["SFC block compilation"]
+    J["iframe sandbox creation"]
+    K["Import resolution utilities"]
+    L["iframe initialization"]
+    M["Utility functions"]
 ```
 
 ## Core Concepts
@@ -296,17 +310,19 @@ Workers and main thread communicate via typed messages:
 
 ### Example Message Flow
 
-```
-Main Thread                    Worker
-    |                             |
-    |-- init (config) ------------>|
-    |<-- init-success -------------|
-    |                             |
-    |-- load (typescript) -------->|
-    |<-- loaded (typescript) ------|
-    |                             |
-    |-- compile (code, language) ->|
-    |<-- compiled (result) --------|
+```mermaid
+sequenceDiagram
+    participant Main as Main Thread
+    participant Worker as Worker
+    
+    Main->>Worker: init (config)
+    Worker->>Main: init-success
+    
+    Main->>Worker: load (typescript)
+    Worker->>Main: loaded (typescript)
+    
+    Main->>Worker: compile (code, language)
+    Worker->>Main: compiled (result)
 ```
 
 ## Import Resolution (`import-map.ts`)

docs/docs/contribution/config-system.mdx

@@ -16,14 +16,21 @@ For individual configuration properties and their meanings, see the [Configurati
 
 ## Architecture
 
-```
-src/livecodes/config/
-├── index.ts           # Public API exports
-├── default-config.ts  # Default configuration values
-├── build-config.ts    # Configuration builder (merges defaults + user + params)
-├── config.ts          # Config getters/setters and helpers
-├── validate-config.ts # Configuration validation
-└── upgrade-config.ts  # Version upgrade migrations
+```mermaid
+graph TD
+    subgraph "src/livecodes/config/"
+        A[index.ts] --> B[default-config.ts]
+        A --> C[build-config.ts]
+        A --> D[config.ts]
+        A --> E[validate-config.ts]
+        A --> F[upgrade-config.ts]
+    end
+    
+    B["Default configuration values"]
+    C["Configuration builder"]
+    D["Config getters/setters"]
+    E["Configuration validation"]
+    F["Version upgrade migrations"]
 ```
 
 ## Configuration Types
@@ -50,6 +57,19 @@ interface Config extends ContentConfig, AppConfig, UserConfig {}
 
 ## Configuration Flow
 
+```mermaid
+flowchart TD
+    A[Default Configuration<br/>default-config.ts] --> B[merge]
+    C[Saved Project Configuration<br/>from storage] --> B
+    B --> D[merge]
+    E[User Configuration<br/>programmatic/SDK] --> D
+    D --> F[merge]
+    G[URL Query Parameters] --> F
+    F --> H[merge]
+    I[URL Hash Parameters] --> H
+    H --> J["Final Configuration<br/>fixLanguageNames()"]
+```
+
 ### 1. Default Configuration
 
 `default-config.ts` provides the base configuration:

docs/docs/contribution/editor-system.mdx

@@ -14,14 +14,29 @@ All editors implement the `CodeEditor` interface defined in `models.ts`.
 
 ### Editor Selection
 
-- **Headless mode** → `fake` editor
-- **Result mode** (non-console/compiled) → `fake` editor
-- **Simple mode** (inactive editor) → `fake` editor
-- **Simple mode** (active editor) → `codemirror`
-- **Codeblock or Lite mode** → `codejar`
-- **Mobile** → `codemirror` (for auto)
-- **Desktop** → `monaco` (for auto)
-- **Explicit selection** → `monaco`, `codemirror`, or `codejar`
+```mermaid
+flowchart TD
+    A[Mode?] --> B{Headless?}
+    B -->|Yes| C[fake editor]
+    B -->|No| D{Result mode<br/>non-console/compiled?}
+    
+    D -->|Yes| C
+    D -->|No| E{Simple mode?}
+    
+    E -->|Yes| F{Active editor?}
+    F -->|Yes| G[codemirror]
+    F -->|No| C
+    
+    E -->|No| H{Codeblock or Lite mode?}
+    H -->|Yes| I[codejar]
+    
+    H -->|No| J{Explicit selection?}
+    J -->|Yes| K[Selected editor<br/>monaco/codemirror/codejar]
+    
+    J -->|No| L{Mobile?}
+    L -->|Yes| G
+    L -->|No| M[monaco]
+```
 
 ---
 

docs/docs/contribution/i18n.mdx

@@ -185,6 +185,31 @@ Maintainers are responsible for managing the i18n workflow and ensuring the qual
 
 We consider the i18n process to consist of two parts:
 
+```mermaid
+flowchart TD
+    subgraph "No-Source Update"
+        A[Lokalise master branch] --> B[i18n/develop branch]
+        B --> C[Auto PR if changes]
+    end
+    
+    subgraph "Source Update"
+        D[Developers add strings<br/>data-i18n / translateString] --> E[npm run i18n-export]
+        E --> F[Generate .lokalise.json<br/>and .ts files]
+        F --> G[Commit & push]
+        G --> H[PR created & reviewed]
+        H --> I[PR merged]
+        I --> J[Auto comment: .i18n-update-push]
+        J --> K[Comment triggers workflow<br/>Creates i18n/branch]
+        K --> L[Push source to Lokalise]
+        L --> M[Translators work on Lokalise]
+        M --> N[Comment .i18n-update-pull]
+        N --> O[Pull translations<br/>Update .ts files]
+        O --> P[Create PR to develop]
+        P --> Q[Merge to develop]
+        Q --> R[Say merge to master<br/>to sync Lokalise]
+    end
+```
+
 #### No-Source Update
 
 This means there are no changes to the source code/texts, only translations are updated. Adding new languages or updating existing translations are examples of this part.

docs/docs/contribution/language-support-system.mdx

@@ -28,27 +28,21 @@ These compilers and runtimes can be provided either as **JavaScript** or **WebAs
 
 ## Architecture
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                      languages/index.ts                             │
-│   exports: languages, processors, utils, prettier, css-presets      │
-└─────────────────────────────────────────────────────────────────────┘
-                                  │
-          ┌───────────────────────┼───────────────────────┐
-          │                       │                       │
-          ▼                       ▼                       ▼
-┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
-│   languages.ts   │   │  processors.ts   │   │  prettier.ts     │
-│  - Language[]    │   │  - Processor[]   │   │  - parserPlugins │
-└──────────────────┘   └──────────────────┘   └──────────────────┘
-          │                       │
-          ▼                       ▼
-┌───────────────────┐    ┌──────────────────┐
-│ lang-<name>/      │    │   <processor>/   │
-│-lang-*.ts         │    │ - processor-*.ts │
-│-lang-*-script.ts  │    └──────────────────┘
-│-lang-*-compiler.ts│
-└───────────────────┘
+```mermaid
+graph TD
+    A["languages/index.ts<br/>exports: languages, processors, utils, prettier, css-presets"]
+
+    A --> B[languages.ts]
+    A --> C[processors.ts]
+    A --> D[prettier.ts]
+
+    B --> E["lang-{name}/<br/>lang-*.ts<br/>lang-*-script.ts<br/>lang-*-compiler.ts"]
+    C --> F["{processor}/<br/>processor-*.ts"]
+
+    D --> G["parserPlugins"]
+
+    B["Language[]"]
+    C["Processor[]"]
 ```
 
 ---

docs/docs/contribution/release.mdx

@@ -2,6 +2,35 @@
 
 To start a new release:
 
+```mermaid
+flowchart TD
+    A["Checkout develop branch"] --> B["Ensure no uncommitted changes"]
+    B --> C["npm run start-release"]
+    C --> D{App or SDK?}
+    
+    D -->|App| E["Increment appVersion<br/>in package.json"]
+    D -->|SDK| F["Increment version<br/>in src/sdk/package.sdk.json"]
+    
+    E --> G["Generate changelog"]
+    F --> G
+    
+    G --> H["Create release branch<br/>releases/v{version}"]
+    H --> I["Push to GitHub<br/>triggers preview deploy"]
+    I --> J["Create PR to develop"]
+    
+    J --> K["PR merged"]
+    K --> L["GitHub Action workflow"]
+    
+    L --> M["Build app/SDK"]
+    M --> N["Create & push release tag"]
+    N --> O["Compress build to zip/tar"]
+    O --> P["Create GitHub release<br/>with changelog"]
+    
+    P --> Q{App or SDK?}
+    Q -->|App| R["Create permanent URL<br/>v{version}.livecodes.io"]
+    Q -->|SDK| S["Publish to npm"]
+```
+
 - Checkout the branch `develop`.
 - Make sure there are no uncommitted changes.
 - Run `npm run start-release` and answer the prompts. This will:
@@ -25,9 +54,7 @@ To start a new release:
   - If App release -> create a permanent URL (v\{version\}.livecodes.io) which is a proxy to preview deploy.
   - If SDK release -> publish to npm.
 
-:::info
+## Note
 
 App versions are numeric e.g. `v20`  
 SDK versions are semver e.g. `v1.2.3`
-
-:::