From dcd109beed21bf4571e053b82551198bd6806c32 Mon Sep 17 00:00:00 2001 From: Suylang Sok Date: Fri, 24 Apr 2026 15:22:52 +1000 Subject: [PATCH 1/7] docs: update overview and ignore rules --- .gitignore | 2 +- Documentation/overview.md | 90 ++++++++++++++++++++++++++++++++------- 2 files changed, 76 insertions(+), 16 deletions(-) diff --git a/.gitignore b/.gitignore index c3f7ccf3..0cedd288 100644 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,4 @@ out/ splashkit/splashkit_autocomplete.json generated/ __pycache__/ -_framework/ \ No newline at end of file +_framework/.DS_Store diff --git a/Documentation/overview.md b/Documentation/overview.md index fea9acc5..65274f80 100644 --- a/Documentation/overview.md +++ b/Documentation/overview.md @@ -3,7 +3,7 @@ ## Purpose -Explains how each JavaScript file fits into the IDE startup, loading, and runtime process. Shows how the pieces interact to build the editor and initialize the environment. This documentation aims to explain the softwares architecture so that it can be understood better making the system easier to navigate, extend, and debug +Explains how each JavaScript file fits into the IDE startup, loading, and runtime process. Shows how the pieces interact to build the editor and initialize the environment. This documentation explains the software architecture of the IDE, helping developers better understand how the system works. This makes it easier to navigate, extend, and debug. ## Files Overview @@ -17,14 +17,14 @@ Explains how each JavaScript file fits into the IDE startup, loading, and runtim | `compiler.js` | Compiler controller class | Creates compiler class to initialize, register and track compilers | | `languageDefinitions.js` | Language metadata | Provides metadata for supported programming languages | | `moduleEventTarget.js` | EventTarget wrapper | Wraps a global `EventTarget` | -| `loadSplashKit.js` | WASM runtime bootstrapper | Loads SplashKit backend binaries, sets up `Module`, dispatches runtime and output events | +| `loadsplashkit.js` | WASM runtime bootstrapper | Loads SplashKit backend binaries, sets up `Module`, dispatches runtime and output events | | `fsevents.js` | FS event dispatcher | Wraps `EventTarget` to emit file operation events from Emscripten’s virtual FS (read, write, etc.) | -| `executionEnvironment_CodeProcessor.js` | Code transformer & runtime patcher | Makes user code async-safe and pausable using Babel transforms. | -| `executionEnvironment_Internal.js` | Sandbox execution controller | Runs, pauses, resets, and manages user programs inside the iframe sandbox. | +| `executionEnvironmentCodeProcessor.js` | Code transformer & runtime patcher | Makes user code async-safe and pausable using Babel transforms. | +| `executionEnvironmentInternal.js` | Sandbox execution controller | Runs, pauses, resets, and manages user programs inside the iframe sandbox. | | `HTMLBuilderUtil.js` | HTML utility functions | Generates or modifies HTML snippets dynamically | | `executionEnvironment.js` | Sandbox runtime controller | Manages iframe-based execution environment for running user code | | `executionEnvironment_Page.js` | Terminal & UI Output Handler | Renders output in the IDE terminal, formats escape sequences, displays errors, manages canvas-terminal layout | -| `ExecutionEnvironmentInternalLoader.js` | Runtime Bootstrap Loader | Loads language runtime scripts, registers service worker, tracks init progress, and sends ready state to parent window | +| `ExecutionEnvironmentInternalLoader.js` | Runtime bootstrap loader | Loads language runtime scripts, registers service worker, tracks init progress, and sends ready state to parent window | | `SKOservice-worker.js` | Program event relay worker | Acts as a service worker queue for program input events like keyboard/mouse. | | `AppStorage.js` | Local storage interface | Provides direct access to browser storage APIs | | `IDBStoredProject.js` | IndexedDB file storage | Handles saving/loading of project files using IndexedDB | @@ -33,7 +33,6 @@ Explains how each JavaScript file fits into the IDE startup, loading, and runtim | `modal.js` | Modal controller | Manages modal windows for alerts, file dialogs, etc. | | `notifications.js` | Notification system | Displays notifications in designated notification area for inline IDE alerts and error messages | | `treeview.js` | File tree UI manager | Renders the sidebar file explorer and handles file selection | -| `fallibleMessage.js` | Bidiirectional messaging class | Provides execution enviornment and the editor bidirectional communication | | `editorMain.js` | Code editor integrator | Boots up and configures the CodeMirror editor instance and acts as a high level class | | `fileview.js` | File panel UI manager | Uses `TreeView` to create the interactivity of the file panel UI | | `projectLoadUI.js` | Project UI feedback handler | Shows UI for loading demo projects and provides indicators or errors during project load | @@ -57,7 +56,7 @@ index.html   ↳ Loads client-side external packages    ↳ Codemirror assets (browser code editor)    ↳ Bootstrap -   ↳ Jzip +   ↳ JSZip   ↳ Loads stylesheets    ↳ baseTheme.css    ↳ colours.css @@ -100,12 +99,12 @@ index.html ## Server Side Component Interactions ### Server.js -- Includes necessary libraries and demo project files. +- Includes required libraries and demo project assets. - Serves the `index.html` content to clients on port 8000, acting as the entry point for the IDE web app. - **Triggers `setup.js`** at server startup to ensure all backend dependencies are available before the client IDE loads. ### Setup.js -- Checks for required pre-built dependency files locally. +- Checks for required pre-built dependency files in the local environment. - Downloads missing dependencies such as: - `splashkit_autocomplete.json` - `SplashKitBackendWASM.js` @@ -154,7 +153,7 @@ index.html - Estimated size of assets (`runtimeSizeAprox`, `compilerSizeAprox`) - Environment flags like `needsSandbox`, `compiled`, or `supportHotReloading` - Default project setup function (`getDefaultProject`) -- Used by files like `compiler.js` to determine which files and actions to do based on the selected language. +- Used by components like `compiler.js` to determine which files to load and which actions to perform based on the selected language. - Builds `SplashKitOnlineLanguageAliasMap`, allowing any component to retrieve full language definitions using either the language name or any alias. ### moduleEventTarget.js @@ -165,7 +164,7 @@ index.html - Defines a global Module object with definitions for `onRuntimeInitialized`, `print`, `preRun`, `canvas`, and `totalDependencies`. - Dispatches events like `onRuntimeInitialized` via `moduleEvents` and output via a custom "print" event which intends to write to terminal in `executionEnvironment_Page.js`. - Handles download and injection of the .wasm and .js runtime binaries using `DownloadSet` into the document. -- Allows access to the canvas in the DOM via `Module` allowing a Object Oriented approach. +- Allows access to the canvas in the DOM via `Module` allowing an object-oriented approach. ### fsevents.js - Acts as a wrapper around `EventTarget` to listen for file system (FS) events. @@ -179,7 +178,7 @@ index.html - Registers Babel plugins: `asyncify`, `makeFunctionsAsyncAwaitTransform`, and `findGlobalDeclarationsTransform`. - Used by `processCodeForExecutionEnvironment()` to prepare code for sandboxed execution. #### Deeper look into executionEnvironment_CodeProcessor -Credits to the developers of splashkit online for documenting this function deeply. This comes from the JS file direcly but is added here for clarity on the functionality as it provides an excellent overview. +Credits to the developers of splashkit online for documenting this function deeply. This comes directly from the JavaScript file but is added here for clarity on the functionality as it provides an excellent overview. - In order to run the code the user writes well, there are two main challenges. 1. We want the user to be able to run loops - for example the 'main' loop. However, Javascript executed in the same thread as the browser's interface, @@ -206,7 +205,7 @@ Credits to the developers of splashkit online for documenting this function deep To reset the globals, we just delete all the variables in findGlobalDeclarationsTransform__userScope (`delete window[globalVar];`) ### executionEnvironment_Internal.js -- Manages execution control, reset logic, and exception handling for the users code. +- Manages execution control, reset logic, and exception handling for the user's code. - Provides `runProgram()`, `stopProgram()`, and `pauseProgram()` for runtime control. - Cleans global scope and memory between runs using `ResetExecutionScope()`. - Parses stack traces to map error lines back to user code for accurate error reporting with `parseErrorStack`. @@ -254,7 +253,7 @@ Credits to the developers of splashkit online for documenting this function deep - Clears events when instructed via `clearEvents` message. ### AppStorage.js -- When using the filesystem make sure to use `unifiedfs.js` instead of `AppStorage` to ensure transient and persistent filesystems stay in sync +- When working with the filesystem, `unifiedfs.js` should be used instead of directly using `AppStorage.js` to ensure consistency between transient and persistent storage. - Handles saving and loading app-level data using IndexedDB. This includes things like project names and which project was last opened. - The `AppStorage` class manages attach/detach events and gives other modules access to the storage through its `access()` method. - Uses a helper class (`__AppStorageRW`) to do all the actual reads/writes with IndexedDB. @@ -273,7 +272,7 @@ Credits to the developers of splashkit online for documenting this function deep - Manages the local file system and metadata for a single project using IndexedDB. - `IDBStoredProject` handles high-level project operations like attaching, detaching, and checking for write conflicts by taking advantage of `AppStorage.js`. - Automatically restores the last opened project if no ID is provided. - - Creates a new project if one doesn’t exist. + - Creates a new project if one does not exist. - Uses `__IDBStoredProjectRW` as an internal class to handle low-level DB access and file operations. - Supports project-wide file system methods like `mkdir`, `writeFile`, `readFile`, `rename`, `unlink`, and `rmdir`. - Provides helpers for listing files (`getFileTree`, `getFlatFileList`, `getAllFilesRaw`). @@ -366,4 +365,65 @@ Credits to the developers of splashkit online for documenting this function deep --- +--- + +## File Changes + +### Summary +No files or folders were added or removed as part of this task. The purpose of this documentation is to analyse and describe the existing project structure. + +--- + +## Structure + +### Root Directory + +This directory contains all the core files required to run the SplashKit Online IDE. This includes server-side scripts, client-side JavaScript files, and the main HTML entry point. + +#### Key Files +- `server.js` – Entry point for the backend server +- `setup.js` – Handles dependency setup and downloads +- `index.html` – Main frontend entry point of the IDE + +--- + +### Browser IDE Components + +These files are responsible for the functionality of the in-browser IDE, including the editor, execution environment, UI, and file system. + +#### Core Areas +- **Execution Environment** + Handles sandboxed code execution using an iframe and WebAssembly. + +- **Editor System** + Manages CodeMirror integration, tabs, syntax highlighting, and user interaction. + +- **File System** + Uses IndexedDB and a unified virtual file system to manage project files. + +- **UI Components** + Includes modals, notifications, file tree view, and project loading UI. + +--- + +### SplashKit Runtime & Dependencies + +These components handle loading and running SplashKit in the browser. + +- WebAssembly (`.wasm`) binaries +- JavaScript runtime loaders +- Compiler files and language setups + +These are dynamically loaded depending on the selected programming language. + +--- + +### Demo Projects + +Contains predefined example projects that users can load into the IDE. These are used for testing and demonstration purposes. + +--- + + + From 1d559db17e98b62973ca458f929a2986074c8ed8 Mon Sep 17 00:00:00 2001 From: Suylang Sok Date: Fri, 24 Apr 2026 15:34:04 +1000 Subject: [PATCH 2/7] chore: ignore generated wwwroot build output --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 0cedd288..c0bb8e26 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ splashkit/splashkit_autocomplete.json generated/ __pycache__/ _framework/.DS_Store +CSharpWasmExpo/wwwroot/ From f5113aa4ca429e20493b87f71fc08726d0355737 Mon Sep 17 00:00:00 2001 From: Suylang Sok Date: Sat, 25 Apr 2026 00:37:31 +1000 Subject: [PATCH 3/7] Update file responsibilities in overview.md --- Documentation/overview.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/Documentation/overview.md b/Documentation/overview.md index 65274f80..f4f44b7b 100644 --- a/Documentation/overview.md +++ b/Documentation/overview.md @@ -14,30 +14,30 @@ Explains how each JavaScript file fits into the IDE startup, loading, and runtim | `setup.js` | Dependency manager | Checks for and downloads missing backend WASM and JSON dependencies | | `splashKitOnlineEnvParams.js` | Runtime config initializer | Sets global runtime environment variables and IDE parameters | | `downloadHandler.js` | File download utility | Handles user-initiated project/file downloads | -| `compiler.js` | Compiler controller class | Creates compiler class to initialize, register and track compilers | -| `languageDefinitions.js` | Language metadata | Provides metadata for supported programming languages | -| `moduleEventTarget.js` | EventTarget wrapper | Wraps a global `EventTarget` | -| `loadsplashkit.js` | WASM runtime bootstrapper | Loads SplashKit backend binaries, sets up `Module`, dispatches runtime and output events | -| `fsevents.js` | FS event dispatcher | Wraps `EventTarget` to emit file operation events from Emscripten’s virtual FS (read, write, etc.) | -| `executionEnvironmentCodeProcessor.js` | Code transformer & runtime patcher | Makes user code async-safe and pausable using Babel transforms. | -| `executionEnvironmentInternal.js` | Sandbox execution controller | Runs, pauses, resets, and manages user programs inside the iframe sandbox. | +| `compiler.js` | Compiler controller class | Registers available compilers and provides a unified interface to invoke language-specific compilation | +| `languageDefinitions.js` | Language metadata | Defines supported languages, file extensions, and compiler/runtime mappings | +| `moduleEventTarget.js` | EventTarget wrapper | Provides a centralized event dispatch/listen mechanism used across modules | +| `loadsplashkit.js` | WASM runtime bootstrapper | Loads SplashKit WASM modules, initializes runtime environment, and connects output/input event handling | +| `fsevents.js` | FS event dispatcher | Emits filesystem-related events (read/write/update) from the virtual FS to sync UI and storage | +| `executionEnvironmentCodeProcessor.js` | Code transformer & runtime patcher | Transforms user code (via Babel) to support async execution, pausing, and safe runtime integration | +| `executionEnvironmentInternal.js` | Sandbox execution controller | Core engine for executing user programs; manages lifecycle (run, pause, stop, reset) inside sandbox | | `HTMLBuilderUtil.js` | HTML utility functions | Generates or modifies HTML snippets dynamically | -| `executionEnvironment.js` | Sandbox runtime controller | Manages iframe-based execution environment for running user code | -| `executionEnvironment_Page.js` | Terminal & UI Output Handler | Renders output in the IDE terminal, formats escape sequences, displays errors, manages canvas-terminal layout | -| `ExecutionEnvironmentInternalLoader.js` | Runtime bootstrap loader | Loads language runtime scripts, registers service worker, tracks init progress, and sends ready state to parent window | -| `SKOservice-worker.js` | Program event relay worker | Acts as a service worker queue for program input events like keyboard/mouse. | +| `executionEnvironment.js` | Sandbox runtime controller | Bridges IDE and iframe sandbox; sends commands and receives execution state/output | +| `executionEnvironment_Page.js` | Terminal & UI Output Handler | Handles rendering program output, terminal text, errors, and canvas display inside execution environment | +| `ExecutionEnvironmentInternalLoader.js` | Runtime bootstrap loader | Loads runtime scripts inside sandbox, initializes environment, and signals readiness to parent IDE | +| `SKOservice-worker.js` | Program event relay worker | Captures and forwards user input events (keyboard/mouse) to the running program via service worker | | `AppStorage.js` | Local storage interface | Provides direct access to browser storage APIs | | `IDBStoredProject.js` | IndexedDB file storage | Handles saving/loading of project files using IndexedDB | -| `unifiedfs.js` | Virtual filesystem bridge | Unifies memory-based and persistent file storage into one virtual FS | +| `unifiedfs.js` | Virtual filesystem bridge | Integrates in-memory FS with persistent storage, providing a unified file system interface | | `projectInitializer.js` | Project loader/initializer | Loads files into editor, sets up project state | | `modal.js` | Modal controller | Manages modal windows for alerts, file dialogs, etc. | | `notifications.js` | Notification system | Displays notifications in designated notification area for inline IDE alerts and error messages | | `treeview.js` | File tree UI manager | Renders the sidebar file explorer and handles file selection | | `editorMain.js` | Code editor integrator | Boots up and configures the CodeMirror editor instance and acts as a high level class | -| `fileview.js` | File panel UI manager | Uses `TreeView` to create the interactivity of the file panel UI | +| `fileview.js` | File panel UI manager | Coordinates file selection, opening, and syncing between tree view and editor | | `projectLoadUI.js` | Project UI feedback handler | Shows UI for loading demo projects and provides indicators or errors during project load | | `actionQueue.js` | Action sequencing engine | Manages async task execution, ordering, cancellation, and dependency in the form of a queue | -| `IDEStartupMain.js` | IDE bootstrap coordinator | Central script that initializes components and kicks off IDE startup sequence | +| `IDEStartupMain.js` | IDE bootstrap coordinator | Orchestrates full IDE startup sequence, initializing UI, storage, compilers, and execution environment | | `themes.js` | Theme manager | Defines and applies color themes by modifying CSS variables; updates UI via dropdown | --- From a34f40ae409d11b2075afc554965c84119193a52 Mon Sep 17 00:00:00 2001 From: Suylang Sok Date: Sat, 25 Apr 2026 12:19:55 +1000 Subject: [PATCH 4/7] update Files Overview by removing outdated files, adding new files, and correcting responsibilities --- Documentation/overview.md | 207 +++++++++++++++++++++----------------- 1 file changed, 114 insertions(+), 93 deletions(-) diff --git a/Documentation/overview.md b/Documentation/overview.md index f4f44b7b..0be12af4 100644 --- a/Documentation/overview.md +++ b/Documentation/overview.md @@ -5,40 +5,123 @@ Explains how each JavaScript file fits into the IDE startup, loading, and runtime process. Shows how the pieces interact to build the editor and initialize the environment. This documentation explains the software architecture of the IDE, helping developers better understand how the system works. This makes it easier to navigate, extend, and debug. +--- ## Files Overview -| File | Role | Responsibilities | -|-----------------------------------------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| `server.js` | Server entry point | Serves `index.html` and assets on port 8000; starts the web server | -| `setup.js` | Dependency manager | Checks for and downloads missing backend WASM and JSON dependencies | -| `splashKitOnlineEnvParams.js` | Runtime config initializer | Sets global runtime environment variables and IDE parameters | -| `downloadHandler.js` | File download utility | Handles user-initiated project/file downloads | -| `compiler.js` | Compiler controller class | Registers available compilers and provides a unified interface to invoke language-specific compilation | -| `languageDefinitions.js` | Language metadata | Defines supported languages, file extensions, and compiler/runtime mappings | -| `moduleEventTarget.js` | EventTarget wrapper | Provides a centralized event dispatch/listen mechanism used across modules | -| `loadsplashkit.js` | WASM runtime bootstrapper | Loads SplashKit WASM modules, initializes runtime environment, and connects output/input event handling | -| `fsevents.js` | FS event dispatcher | Emits filesystem-related events (read/write/update) from the virtual FS to sync UI and storage | -| `executionEnvironmentCodeProcessor.js` | Code transformer & runtime patcher | Transforms user code (via Babel) to support async execution, pausing, and safe runtime integration | -| `executionEnvironmentInternal.js` | Sandbox execution controller | Core engine for executing user programs; manages lifecycle (run, pause, stop, reset) inside sandbox | -| `HTMLBuilderUtil.js` | HTML utility functions | Generates or modifies HTML snippets dynamically | -| `executionEnvironment.js` | Sandbox runtime controller | Bridges IDE and iframe sandbox; sends commands and receives execution state/output | -| `executionEnvironment_Page.js` | Terminal & UI Output Handler | Handles rendering program output, terminal text, errors, and canvas display inside execution environment | -| `ExecutionEnvironmentInternalLoader.js` | Runtime bootstrap loader | Loads runtime scripts inside sandbox, initializes environment, and signals readiness to parent IDE | -| `SKOservice-worker.js` | Program event relay worker | Captures and forwards user input events (keyboard/mouse) to the running program via service worker | -| `AppStorage.js` | Local storage interface | Provides direct access to browser storage APIs | -| `IDBStoredProject.js` | IndexedDB file storage | Handles saving/loading of project files using IndexedDB | -| `unifiedfs.js` | Virtual filesystem bridge | Integrates in-memory FS with persistent storage, providing a unified file system interface | -| `projectInitializer.js` | Project loader/initializer | Loads files into editor, sets up project state | -| `modal.js` | Modal controller | Manages modal windows for alerts, file dialogs, etc. | -| `notifications.js` | Notification system | Displays notifications in designated notification area for inline IDE alerts and error messages | -| `treeview.js` | File tree UI manager | Renders the sidebar file explorer and handles file selection | -| `editorMain.js` | Code editor integrator | Boots up and configures the CodeMirror editor instance and acts as a high level class | -| `fileview.js` | File panel UI manager | Coordinates file selection, opening, and syncing between tree view and editor | -| `projectLoadUI.js` | Project UI feedback handler | Shows UI for loading demo projects and provides indicators or errors during project load | -| `actionQueue.js` | Action sequencing engine | Manages async task execution, ordering, cancellation, and dependency in the form of a queue | -| `IDEStartupMain.js` | IDE bootstrap coordinator | Orchestrates full IDE startup sequence, initializing UI, storage, compilers, and execution environment | -| `themes.js` | Theme manager | Defines and applies color themes by modifying CSS variables; updates UI via dropdown | +--- + +## Server Layer + +| File | Role | Responsibilities | +|------|------|------------------| +| `server.js` | Server entry point | Starts Express server, serves `index.html` and static assets | +| `setup.js` | Dependency bootstrapper | Ensures backend dependencies and WASM assets are available | +| `setup.py` | Python setup helper | Supports build/setup automation for tooling | +| `package.json` | Node project definition | Defines dependencies and scripts | +| `package-lock.json` | Dependency lockfile | Ensures consistent installs | +| `node_modules/` | Dependency ecosystem | Contains installed Node.js packages used by the server | + +--- + +## Startup & Orchestration Layer + +| File | Role | Responsibilities | +|------|------|------------------| +| `javascript/startup/IDEStartupMain.js` | IDE bootstrapper | Coordinates full IDE initialization flow | +| `javascript/startup/projectInitializer.js` | Project loader | Loads or creates initial workspace/project | +| `javascript/startup/projectLoadUI.js` | Project selection UI | Handles demo/project selection interface | +| `javascript/startup/splashKitOnlineEnvParams.js` | Runtime config | Sets environment parameters for IDE runtime | +| `javascript/middleware/actionQueue.js` | Task scheduler | Manages ordered async initialization tasks | +| `javascript/middleware/downloadHandler.js` | Asset downloader | Handles downloading and extracting project/assets | +| `javascript/communication/communication.js` | Messaging layer | Handles inter-module messaging system | +| `javascript/layout/layout.js` | Layout manager | Controls IDE layout structure and panels | +| `javascript/languages/languageDefinitions.js` | Language registry | Defines supported languages and configuration | +| `compilers/compiler.js` | Compiler coordinator | Central registry and dispatch for language compilers | + +--- + +## Compiler System + +| File | Role | Responsibilities | +|------|------|------------------| +| `compilers/compiler.js` | Compiler controller | Registers and manages all language compilers | +| `compilers/javascript/javascriptCompiler.js` | JavaScript compiler | Executes JavaScript code in browser runtime | +| `compilers/cxx/cxxCompiler.js` | C++ compiler frontend | Interfaces with WASM/Clang backend | +| `compilers/cxx/cxxCompilerClangBackend.js` | WASM backend bridge | Connects compiler to Clang WebAssembly toolchain | +| `compilers/cxx/cxxCompilerClangWebWorker.js` | Background compiler worker | Runs C++ compilation in separate thread | +| `compilers/javascript/executionEnvironmentCodeProcessor.js` | Code transformer | Transforms JavaScript code for execution environment | +| `compilers/csharp/csharpCompiler.js` | C# compiler | Handles C# compilation via WASM runtime | + +--- + +## Execution Environment System + +| File | Role | Responsibilities | +|------|------|------------------| +| `javascript/executionEnviroment/executionEnvironment.js` | Execution controller | Manages sandbox/iframe execution lifecycle | +| `javascript/executionEnviroment/executionEnvironment_Page.js` | Output renderer | Displays runtime output, logs, and errors | +| `compilers/javascript/executionEnvironmentInternal.js` | Execution bridge engine | Executes transformed JavaScript within controlled runtime context | +| `moduleEventTarget.js` | Event system | Central pub/sub event dispatcher | +| `loadsplashkit.js` | WASM bootstrapper | Loads SplashKit WebAssembly runtime | +| `fsevents.js` | FS event dispatcher | Syncs file system events with UI and runtime systems | + +--- + +## Runtime Systems + +| File | Role | Responsibilities | +|------|------|------------------| +| `runtimes/ExecutionEnvironmentInternal.js` | Core runtime engine | Manages execution lifecycle (run, stop, reset) | +| `runtimes/ExecutionEnvironmentInternalLoader.js` | Runtime loader | Loads and initializes execution runtime | +| `runtimes/cxx/cxxRuntime.js` | C++ runtime | Executes compiled WebAssembly C++ output | +| `runtimes/csharp/csharpRuntime.js` | C# runtime | Executes compiled C# programs via WASM | +| `runtimes/javascript/` | JavaScript runtime | Executes JavaScript programs in browser environment | + +--- + +## Storage & Filesystem Layer + +| File | Role | Responsibilities | +|------|------|------------------| +| `javascript/storage/appStorage/` | App storage | IndexedDB-based persistent storage system | +| `javascript/storage/unifiedfs.js` | Virtual filesystem | Unifies persistent storage and runtime filesystem | +| `javascript/storage/fileview.js` | File UI sync | Synchronizes filesystem with file explorer UI | +| `javascript/storage/fsevents.js` | FS event system | Emits file system change events for UI/runtime sync | + +--- + +## UI Layer + +| File | Role | Responsibilities | +|------|------|------------------| +| `javascript/UI/editorMain.js` | Editor controller | Manages CodeMirror editor instance and editing lifecycle | +| `javascript/UI/treeview.js` | File explorer | Displays and manages project file hierarchy | +| `javascript/UI/modal.js` | Modal system | Handles dialogs, popups, and confirmations | +| `javascript/UI/notifications.js` | Notification system | Displays IDE alerts and messages | +| `javascript/UI/themes.js` | Theme manager | Applies and switches UI themes | +| `javascript/UI/HTMLBuilderUtil.js` | DOM utilities | Helper functions for UI construction | +| `javascript/layout/layout.js` | Layout engine | Controls panel layout, resizing, and IDE structure | + +--- + +## Service Worker Layer + +| File | Role | Responsibilities | +|------|------|------------------| +| `SKOservice-worker.js` | Service worker | Handles caching, offline support, and request interception | + +--- + +## External Runtime / WASM Systems + +| Folder/File | Role | Responsibilities | +|-------------|------|------------------| +| `SplashKitWasm/` | WASM engine | Builds and compiles SplashKit C++ WebAssembly runtime | +| `CSharpWasm/` | C# WASM bridge | Compiles and binds C# code to WebAssembly runtime | +| `CSharpWasmExpo/` | WASM output runtime | Hosts compiled C# runtime artifacts | +| `assets/` | Static assets | Images, icons, logos, and static resources | +| `DemoProjects/` | Sample projects | Prebuilt example projects and metadata for demos | --- ## Loading & Initialization Flow @@ -365,65 +448,3 @@ Credits to the developers of splashkit online for documenting this function deep --- ---- - -## File Changes - -### Summary -No files or folders were added or removed as part of this task. The purpose of this documentation is to analyse and describe the existing project structure. - ---- - -## Structure - -### Root Directory - -This directory contains all the core files required to run the SplashKit Online IDE. This includes server-side scripts, client-side JavaScript files, and the main HTML entry point. - -#### Key Files -- `server.js` – Entry point for the backend server -- `setup.js` – Handles dependency setup and downloads -- `index.html` – Main frontend entry point of the IDE - ---- - -### Browser IDE Components - -These files are responsible for the functionality of the in-browser IDE, including the editor, execution environment, UI, and file system. - -#### Core Areas -- **Execution Environment** - Handles sandboxed code execution using an iframe and WebAssembly. - -- **Editor System** - Manages CodeMirror integration, tabs, syntax highlighting, and user interaction. - -- **File System** - Uses IndexedDB and a unified virtual file system to manage project files. - -- **UI Components** - Includes modals, notifications, file tree view, and project loading UI. - ---- - -### SplashKit Runtime & Dependencies - -These components handle loading and running SplashKit in the browser. - -- WebAssembly (`.wasm`) binaries -- JavaScript runtime loaders -- Compiler files and language setups - -These are dynamically loaded depending on the selected programming language. - ---- - -### Demo Projects - -Contains predefined example projects that users can load into the IDE. These are used for testing and demonstration purposes. - ---- - - - - From 213034d21506a17ae5c236b21ce096a9797d4ffb Mon Sep 17 00:00:00 2001 From: Suylang Sok Date: Sat, 25 Apr 2026 13:06:08 +1000 Subject: [PATCH 5/7] Update server/client initialization flow documentation --- Documentation/overview.md | 100 ++++++++++++++++++++++++++------------ 1 file changed, 68 insertions(+), 32 deletions(-) diff --git a/Documentation/overview.md b/Documentation/overview.md index 0be12af4..3fd0c5e5 100644 --- a/Documentation/overview.md +++ b/Documentation/overview.md @@ -126,57 +126,93 @@ Explains how each JavaScript file fits into the IDE startup, loading, and runtim --- ## Loading & Initialization Flow +--- + ### Server Side server.js ↳ setup.js +↳ node_modules (dependency ecosystem injected at runtime via npm install) +↳ Node.js module resolution system + ↳ injects dependencies using require() at runtime + ↳ resolves Express, middleware, build tools, and setup utilities + +↳ Static folder injection + ↳ assets/ (images, icons, UI resources) + ↳ DemoProjects/ (prebuilt project templates) + ↳ SplashKitWasm/ (WASM runtime and build artifacts served to client) --- + ### Client Side index.html +↳ Client entry point (triggers full IDE initialization sequence) +  ↳ Header   ↳ Loads client-side external packages -   ↳ Codemirror assets (browser code editor) +   ↳ CodeMirror assets (browser code editor)    ↳ Bootstrap    ↳ JSZip +   ↳ Loads stylesheets    ↳ baseTheme.css    ↳ colours.css    ↳ stylesheet.css -   ↳ (Includes bootstrap & codemirror styles) +   ↳ (Includes Bootstrap & CodeMirror styles) +   ↳ splashkit-javascript-hint.js - ↳ Footer -  ↳ splashKitOnlineEnvParams.js -  ↳ downloadHandler.js -  ↳ compiler.js -  ↳ languageDefinitions.js -   ↳ moduleEventTarget.js -   ↳ loadsplashkit.js -   ↳ fsevents.js -   ↳ executionEnvironment_CodeProcessor.js -   ↳ executionEnvironment_Internal.js -  ↳ HTMLBuilderUtil.js -  ↳ executionEnvironment.js -   ↳ executionEnvironment.html -    ↳ executionEnvironment_Page.js -    ↳ ExecutionEnvironmentInternalLoader.js -     ↳ SKOservice-worker.js -  ↳ AppStorage.js -  ↳ IDBStoredProject.js -  ↳ unifiedfs.js -  ↳ projectInitializer.js -  ↳ modal.js -  ↳ notifications.js -  ↳ treeview.js -  ↳ fallibleMessage.js -  ↳ editorMain.js -  ↳ fileview.js -  ↳ projectLoadUI.js -  ↳ actionQueue.js -  ↳ IDEStartupMain.js -  ↳ themes.js +--- + + ↳ Footer (Initialization Pipeline Order) + +  1. Environment Configuration +   ↳ splashKitOnlineEnvParams.js + +  2. Asset + Runtime Download System +   ↳ downloadHandler.js + +  3. Compiler System Initialization +   ↳ compiler.js +   ↳ languageDefinitions.js + +    ↳ moduleEventTarget.js +    ↳ loadsplashkit.js +    ↳ fsevents.js +    ↳ executionEnvironment_CodeProcessor.js +    ↳ executionEnvironment_Internal.js + +  4. UI + DOM Utilities +   ↳ HTMLBuilderUtil.js + +  5. Execution Environment Setup +   ↳ executionEnvironment.js +    ↳ executionEnvironment.html +     ↳ executionEnvironment_Page.js +     ↳ ExecutionEnvironmentInternalLoader.js +      ↳ SKOservice-worker.js + +  6. Storage & Filesystem Layer +   ↳ AppStorage.js +   ↳ IDBStoredProject.js +   ↳ unifiedfs.js +   ↳ projectInitializer.js + +  7. UI Layer Initialization +   ↳ modal.js +   ↳ notifications.js +   ↳ treeview.js +   ↳ fallibleMessage.js + +  8. Editor + IDE Interface +   ↳ editorMain.js +   ↳ fileview.js +   ↳ projectLoadUI.js +   ↳ actionQueue.js +   ↳ IDEStartupMain.js +   ↳ themes.js + --- ## Server Side Component Interactions From ffe512688883c9243694d0ab155a83bfddef4c06 Mon Sep 17 00:00:00 2001 From: Suylang Sok Date: Sat, 25 Apr 2026 14:33:22 +1000 Subject: [PATCH 6/7] Verify existing document interactions, add missing references, remove outdated entries, and ensure ordering consistency. --- Documentation/overview.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/Documentation/overview.md b/Documentation/overview.md index 3fd0c5e5..399f35dd 100644 --- a/Documentation/overview.md +++ b/Documentation/overview.md @@ -35,7 +35,6 @@ Explains how each JavaScript file fits into the IDE startup, loading, and runtim | `javascript/middleware/actionQueue.js` | Task scheduler | Manages ordered async initialization tasks | | `javascript/middleware/downloadHandler.js` | Asset downloader | Handles downloading and extracting project/assets | | `javascript/communication/communication.js` | Messaging layer | Handles inter-module messaging system | -| `javascript/layout/layout.js` | Layout manager | Controls IDE layout structure and panels | | `javascript/languages/languageDefinitions.js` | Language registry | Defines supported languages and configuration | | `compilers/compiler.js` | Compiler coordinator | Central registry and dispatch for language compilers | @@ -59,8 +58,8 @@ Explains how each JavaScript file fits into the IDE startup, loading, and runtim | File | Role | Responsibilities | |------|------|------------------| -| `javascript/executionEnviroment/executionEnvironment.js` | Execution controller | Manages sandbox/iframe execution lifecycle | -| `javascript/executionEnviroment/executionEnvironment_Page.js` | Output renderer | Displays runtime output, logs, and errors | +| `javascript/executionEnvironment/executionEnvironment.js` | Execution controller | Manages sandbox/iframe execution lifecycle | +| `javascript/executionEnvironment/executionEnvironment_Page.js` | Output renderer | Displays runtime output, logs, and errors | | `compilers/javascript/executionEnvironmentInternal.js` | Execution bridge engine | Executes transformed JavaScript within controlled runtime context | | `moduleEventTarget.js` | Event system | Central pub/sub event dispatcher | | `loadsplashkit.js` | WASM bootstrapper | Loads SplashKit WebAssembly runtime | @@ -180,14 +179,14 @@ index.html     ↳ moduleEventTarget.js     ↳ loadsplashkit.js     ↳ fsevents.js -    ↳ executionEnvironment_CodeProcessor.js -    ↳ executionEnvironment_Internal.js +    ↳ executionEnvironmentCodeProcessor.js +    ↳ executionEnvironmentInternal.js   4. UI + DOM Utilities    ↳ HTMLBuilderUtil.js   5. Execution Environment Setup -   ↳ executionEnvironment.js +   ↳ executionEnvironnment.js     ↳ executionEnvironment.html      ↳ executionEnvironment_Page.js      ↳ ExecutionEnvironmentInternalLoader.js @@ -203,7 +202,6 @@ index.html    ↳ modal.js    ↳ notifications.js    ↳ treeview.js -   ↳ fallibleMessage.js   8. Editor + IDE Interface    ↳ editorMain.js @@ -323,13 +321,13 @@ Credits to the developers of splashkit online for documenting this function deep For example `let a = 10;` becomes `window.a = 10;`. `function func(){}` becomes `window.func = function func(){}`. To reset the globals, we just delete all the variables in findGlobalDeclarationsTransform__userScope (`delete window[globalVar];`) -### executionEnvironment_Internal.js +### ExecutionEnvironmentInternal.js - Manages execution control, reset logic, and exception handling for the user's code. - Provides `runProgram()`, `stopProgram()`, and `pauseProgram()` for runtime control. - Cleans global scope and memory between runs using `ResetExecutionScope()`. - Parses stack traces to map error lines back to user code for accurate error reporting with `parseErrorStack`. - Attaches to FS events using `FSEvents` to report back file system changes. -- Dispatches execution state (started, stopped, paused) to the parent page. +- Dispatches execution state (started, stopped, paused) to the parent page. ### HTMLBuilderUtil.js - Provides helper functions for dynamically creating and manipulating HTML elements. @@ -360,7 +358,7 @@ Credits to the developers of splashkit online for documenting this function deep - Registers event listeners for output messages and error reporting. - Implements basic loading UI: progress bar, failure message, and visibility toggles. -### ExecutionEnvironmentInternalLoader.js +### executionEnvironmentInternalLoader.js - Loads language-specific runtime JS files dynamically using `