Add README and core design docs (architecture, roadmap, scene model, loop ownership, ML direction)

README.md

@@ -0,0 +1,45 @@
+# Bleue Mer
+
+Bleue Mer is a bachelor-thesis-era game engine/editor prototype exploring a compact C++ runtime, a Unity-inspired object model, and a Processing-like creative coding API. The current repository contains:
+
+- a C++ OpenGL/GLUT engine layer with math primitives, render helpers, input, and `GameObject` abstractions;
+- Python/PyQt editor prototypes for project creation, scene browsing, hierarchy display, assets, terminal, inspector, and scene view panels;
+- several experimental C++ projects and demos.
+
+The project is best understood as a prototype for a future architecture rather than a finished engine. Its strongest direction is a C++ engine/editor stack where scenes are authored as data, loaded into runtime `GameObject`s, and rendered either natively or on the web.
+
+## Documentation map
+
+Start with these documents:
+
+1. [Architecture Vision](docs/architecture-vision.md) — the high-level direction for the engine, editor, data model, and web deployment.
+2. [Scene and JSON Model](docs/scene-json-model.md) — how Processing-style code, Unity-like objects, and JSON scene files fit together.
+3. [Runtime Loop Ownership](docs/runtime-loop-ownership.md) — how Qt, native runtime, and browser hosts should drive the engine without the engine owning the main loop.
+4. [ML-Native Engine Direction](docs/ml-native-direction.md) — how native C++ machine-learning primitives could become first-class engine components.
+5. [Modernization Roadmap](docs/modernization-roadmap.md) — an implementation sequence for turning the prototype into a coherent next-generation system.
+6. [Editor CLI and Process Boundary Debt](docs/editor-cli-debt.md) — why the old GUI subprocess/argv communication should be retired in favor of typed services.
+7. [Branch and Pull Request Plan](docs/branch-pr-plan.md) — ordered future branch/PR sequence for engine, editor, runtime, ML, web, and cleanup work.
+
+## Current architectural center
+
+The current C++ engine already has the vocabulary of the future system:
+
+- `Vector3` and `Color` define basic value types.
+- `RenderEngine` exposes a small immediate drawing API.
+- `GameEngine::GameObject` owns component-like data: `Transform`, `Rigidbody`, `Renderer`, and `Collider`.
+- input is abstracted behind `GameEngine::Input`.
+
+The current editor prototype already points toward the authoring side:
+
+- projects contain `ProjectData.json`;
+- scenes are placed under `Assets/Scenes`;
+- the hierarchy reads scene JSON and displays scene/game-object names;
+- the project page sketches a Unity-like editor layout.
+
+The next architectural milestone is to make these two halves share a formal scene model.
+
+## Recommended future identity
+
+> Bleue Mer should become a C++/Qt game and simulation editor with a Processing-like drawing layer, Unity-like `GameObject` behavior, JSON-authored scenes, native C++ ML components, and eventual WebAssembly/WebGL deployment.
+
+That identity keeps the original elegance of the engine while giving the project a clear path forward.

docs/architecture-vision.md

@@ -0,0 +1,180 @@
+# Architecture Vision
+
+## One-sentence direction
+
+Bleue Mer should evolve into a C++/Qt game and simulation editor built around a loop-agnostic C++ engine core, a Processing-like immediate drawing API, a Unity-like `GameObject` scene model, JSON serialization, native ML components, and eventual web deployment through WebAssembly/WebGL.
+
+## Why this direction fits the existing project
+
+The current codebase already contains two compatible halves:
+
+1. **C++ runtime and engine vocabulary**
+   - math primitives;
+   - color primitives;
+   - immediate render helpers;
+   - input abstraction;
+   - `GameObject` with component-like fields.
+
+2. **Python/PyQt editor prototype vocabulary**
+   - project creation;
+   - project data;
+   - scene files;
+   - hierarchy panel;
+   - scene view;
+   - assets panel;
+   - inspector concept;
+   - run/build action.
+
+The missing bridge is not conceptual. The missing bridge is a formal shared runtime/editor model:
+
+```text
+ProjectData.json
+    -> active scene JSON
+        -> C++ SceneLoader
+            -> Scene
+                -> GameObjects
+                    -> Components
+                        -> rendering, physics, input, ML behavior
+```
+
+## Target dependency direction
+
+The clean dependency direction is:
+
+```text
+EditorQt  ---> Engine
+Runtime   ---> Engine
+WebHost   ---> Engine
+Engine    -X-> EditorQt
+Engine    -X-> Runtime
+Engine    -X-> WebHost
+```
+
+The engine should not know whether it is running inside a Qt editor, a native executable, or a browser canvas. It should expose initialization, update, render, serialization, and component APIs. Hosts decide when and where to call those APIs.
+
+## Core layers
+
+A future version could be organized like this:
+
+```text
+Engine/
+  Core/
+    Application
+    Scene
+    GameObject
+    Component
+    Behaviour
+    Time
+  Math/
+    Vector2
+    Vector3
+    Color
+    Matrix
+  Rendering/
+    Renderer
+    RenderCommand
+    PrimitiveRenderer
+    OpenGLBackend
+    WebGLBackend
+  Input/
+    Input
+    KeyCode
+    Mouse
+  Serialization/
+    ProjectSerializer
+    SceneSerializer
+    ModelSerializer
+  ML/
+    Dataset
+    Model
+    LinearRegression
+    KMeans
+    DecisionTree
+    MLBehaviour
+
+EditorQt/
+  MainWindow
+  SceneViewport
+  HierarchyPanel
+  InspectorPanel
+  AssetsPanel
+  ConsolePanel
+  MLPanel
+
+Runtime/
+  main.cpp
+  NativeWindow
+
+Web/
+  index.html
+  wasm bootstrap
+  asset manifest
+```
+
+## Engine core responsibilities
+
+The engine core should own:
+
+- scene data;
+- game object identity and hierarchy;
+- component data;
+- behavior update ordering;
+- render command generation;
+- input state representation;
+- serialization of engine-owned data;
+- optional ML model execution.
+
+The engine core should **not** own:
+
+- the Qt application loop;
+- the browser event loop;
+- editor widgets;
+- platform-specific window creation policy;
+- editor-only selection state, gizmo state, or dock layout.
+
+## Editor responsibilities
+
+The C++/Qt editor should own:
+
+- project opening/creation UI;
+- hierarchy display;
+- inspector editing;
+- asset browsing;
+- scene viewport hosting;
+- edit/play/pause state;
+- saving and loading scenes through engine serializers;
+- visual tools for ML datasets/models;
+- build/export commands.
+
+The editor should manipulate actual engine `Scene` and `GameObject` instances in memory, not constantly shell out to separate helper programs.
+
+The previous subprocess-heavy GUI communication model should be treated as prototype glue. A C++/Qt rewrite should centralize project, scene, asset, and build operations behind typed services instead of routing internal editor state through command-line arguments and parsed stdout.
+
+## Runtime responsibilities
+
+A standalone runtime should own:
+
+- creating a native window;
+- loading a project/scene;
+- running the game loop;
+- forwarding input into the engine;
+- calling `engine.update(dt)` and `engine.render()`;
+- packaging assets for native distribution.
+
+## Web host responsibilities
+
+The web host should own:
+
+- loading the WASM module;
+- fetching or mounting scene/assets files;
+- connecting browser input to engine input;
+- using the browser animation loop;
+- rendering through WebGL or a WebGL-compatible backend.
+
+## Architectural rule of thumb
+
+If a feature is needed by editor, runtime, and web deployment, it belongs in `Engine`.
+
+If a feature is only a tool for authoring, visualization, docking, selection, or editing workflow, it belongs in `EditorQt`.
+
+If a feature only starts a platform-specific executable/window/canvas, it belongs in a host layer.