Land
	Dependency 🖇️		Cargo 📦 Land 🏞️
	Dependency 🖇️ Land 🏞️		NPM 📦 Land 🏞️
	Echo 📣		Land 🏞️
	Editor 🏞️		Element 🌱
	Mountain ⛰️		River 🌊
	Sky 🌌		Sun ☀️
		Wind 🌬️

Land 🏞️ — The Next-Generation Code Editor

Welcome to Land! We are building a high-performance, resource-efficient, and cross-platform code editor inspired by the best of VS Code. Land is engineered with a modern stack – Rust for the backend (Mountain) and Tauri for the native shell – to deliver a lightning-fast, memory-conscious, and deeply familiar editing experience for developers.

Our vision is to create a truly adaptable editor. It will not only match VS Code's core functionality but also offer a flexible foundation for running extensions in various environments. This approach optimizes for performance, security, and specific use cases, giving developers the power and flexibility they need.

Key Features (MVP Focus)

The Minimum Viable Product (MVP) aims to deliver a foundational yet functional editor demonstrating Land's core architecture and capabilities. Key deliverables include:

1. Core Editor Functionality: A runnable Land application where the Sky frontend (UI) communicates with the Mountain backend (Rust) via the Echo interface and Track dispatcher.
2. File System Operations: Users will be able to browse directories, and open, edit, and save text files. This is powered by the Native Logic Flow in Mountain, utilizing the River (read) and Sun (write) libraries.
3. WebSocket Communication: Essential real-time communication pathways will be functional, handled by the Mist component (either native in Mountain or as a sidecar).
4. OS Protocol Handling: The application will handle OS-level vscode:// protocol invocations, allowing Land to be opened from external links or tools.
5. Basic Extension Support: A foundational Extension Host will be implemented (either Cocoon for Node.js extensions or an initial Grove for native Rust/WASM extensions). This will allow a limited subset of simpler extensions to load and operate, demonstrating the chosen pathway.
6. Custom Runner Integration: A custom auxiliary process (Runner) will be reliably managed by Mountain for specific background tasks.
7. Basic Build System: A functional build process will compile all components and package a runnable Tauri application for development and testing.

What this means for users at MVP: You'll be able to install and run Land, open and edit files, and see the groundwork for future extension support and advanced features. The focus is on validating the core architecture and providing a stable base for future development.

Our Journey: Phased Evolution 🗺️

Land's development is a phased journey towards its full vision:

1. MVP Path A (Current Focus - Cocoon Sidecar): Establish a functional core editor with a Node.js sidecar (Cocoon). This approach allows us to leverage the vast VS Code extension ecosystem quickly by running existing extensions, while Mountain and Sky benefit from Tauri's native performance.

2. MVP Path B (Future Goal - Grove Native Host): Develop a Rust-native extension host (Grove). This aims to provide a highly optimized, secure, and performant environment for extensions, potentially enabling extensions written in Rust or compiled to WASM.

3. Exploring Alternative Runtimes (Future Research): Investigate and potentially support other lightweight JavaScript runtimes (e.g., Deno, LLRT) as specialized extension sidecars where their unique benefits like security or startup speed are paramount.

This README primarily details the current MVP Path A architecture and goals, with an eye towards these future evolutions.

---

Core Architecture Principles 🏗️

No matter the extension host flavor, Land's core architecture (Mountain, Sky, Echo, Track, Vine, River, Sun, Mist) is designed for modularity and performance:

Component	Role & Key Responsibilities	Primary Technologies
Mountain	The native Rust/Tauri backend. Manages the app lifecycle, OS operations, UI windows (via Tauri), the Track command dispatcher, and Vine IPC for communication with any sidecar extension hosts.	Rust, Tauri
Sky	The user interface, built with Astro (or similar web tech), running in Tauri's native webview. Reuses VS Code UI components for a familiar experience. Interacts with Mountain via the Echo API contract.	Astro, JS/TS, HTML/CSS
Echo	The Action System Interface Definition. It's the API contract defining actions and data structures for Sky <-> Mountain communication.	Rust
Track	Mountain's central Command Dispatcher. It routes Echo actions from Sky and RPC requests from sidecars to the appropriate Rust handlers in Mountain.	Rust
Vine	The primary IPC Transport Layer (stdio JSON) for Mountain to communicate with any sidecar-based extension host (Cocoon, potential Mist sidecar, Deno/LLRT sidecars, or a process-isolated Grove).	Rust (Mountain), JS (Sidecar)
River/Sun	Native Rust libraries (River for reads, Sun for writes) providing efficient, asynchronous filesystem operations, used by Mountain's Native Logic Flow handlers.	Rust
Mist	Handles WebSocket communication logic. This might be native in Mountain or a separate sidecar communicating via Vine.	Rust / JS (if sidecar)

---

Current Focus: MVP Path A - The Cocoon (Node.js Sidecar) 🦋

Our immediate goal is to deliver a functional Land editor by running existing VS Code extensions within Cocoon, a dedicated Node.js sidecar process. This allows us to tap into the rich ecosystem of VS Code extensions early on.

Cocoon Architecture (Path A):

Component within Path A	Role
Cocoon Process	A Node.js process launched by Mountain. It hosts VS Code's ExtHostExtensionService using pre-bundled platform code. This is where extensions actually run.
Shims (in Cocoon)	JavaScript modules within Cocoon that mimic VS Code's internal ExtHost* services. They intercept API calls from extensions and proxy them to Mountain via Vine IPC for native execution or UI updates.
Rest (JS Bundler)	A build-time process (e.g., esbuild/webpack) that bundles necessary VS Code platform JavaScript (from Land/Dependency/.../Editor) into a format Cocoon can load.

How it Works (Simplified for Path A):

1. Mountain (the main Rust application) launches the Cocoon Node.js sidecar.
2. Cocoon initializes, loading the bundled VS Code platform code and the ExtHostExtensionService.
3. An extension in Cocoon calls a vscode.* API (e.g., vscode.workspace.fs.readFile).
4. A Shim in Cocoon intercepts this call.
5. The Shim sends a request via Vine (JSON over stdio) to Mountain.
6. Mountain's Track dispatcher routes this request to the appropriate Rust handler (e.g., using River to read the file).
7. Mountain sends the result back to Cocoon via Vine.
8. The Shim returns the result to the extension, completing the API call.

This approach aims for high compatibility with existing Node.js-based VS Code extensions by providing them with a familiar environment and API surface.

---

Future Extension Host Paths & Feature Parity 🚀

While Cocoon (Node.js sidecar) is our Path A for MVP, Land is designed with future flexibility in mind to achieve greater performance, security, and potentially support different classes of extensions.

Path B: Grove - The Native Rust Extension Host 🌳

• Concept: A complete rewrite of the VS Code extension host logic in Rust. Grove aims to run extensions (potentially those recompiled to WASM or new extensions written in Rust/WASM) in a highly performant and secure native environment.
• Goal: Drastically reduce the overhead of a Node.js runtime, improve security through Rust's safety and WASM sandboxing, and enable deeper integration with Mountain.
• Status: A longer-term vision. This involves reimplementing the entire vscode.* API surface in Rust.

Alternative Runtimes (Conceptual Exploration) 🧪

• Deno Sidecar: Explore Deno for its security model and TypeScript-first approach.
• LLRT Sidecar: Investigate LLRT for ultra-lightweight, fast-startup extensions.

Achieving Feature Parity: Our long-term ambition is to achieve a high degree of feature parity with VS Code. This will be an iterative process:

1. Core Editing & MVP Extensions (Path A): Ensuring basic text editing, file management (River/Sun), and core extension APIs function reliably via Cocoon.
2. Expanding API Coverage (Path A/B): Incrementally implementing more shims (Path A) or native API implementations (Path B - Grove) to support a wider range of extensions.
3. Native Feature Implementation: Re-implementing complex VS Code features (Debugging, SCM, Tasks, Rich UI Panels) natively in Mountain and Sky.
4. Performance & Stability: Continuously optimizing all components.

(Tracking feature parity is a manual process involving extensive testing and comparison against VS Code.)

---

Project Structure Overview (Land/Element/*) 🗺️

Our codebase is organized into "Elements," each with a distinct purpose:

Path Prefix	Component / Purpose
Land/Element/Cocoon/	Node.js sidecar for Path A (index.js, shims/, cocoon-ipc.js).
Land/Element/Echo/	Rust crate defining the Echo API contract (command names, shared data structures) between Sky and Mountain.
Land/Element/Grove/	(Future - Path B) Planned Rust-based WASM/Native extension runtime.
Land/Element/Mist/	Component for WebSocket communication logic (native or sidecar).
Land/Element/Mountain/	The core Rust/Tauri backend application (Track dispatcher, Vine IPC, native handlers).
Land/Element/Output/	Default directory for build artifacts.
Land/Element/Rest/	Scripts and configuration for the JS Bundler (bundling VS Code platform code for Cocoon).
Land/Element/River/	Rust library for native filesystem read operations.
Land/Element/Shim/	TypeScript definitions (vscode.ts) for the VS Code API surface targeted by Cocoon shims.
Land/Element/Sky/	Astro-based frontend UI application.
Land/Element/Sun/	Rust library for native filesystem write operations.
Land/Element/Document/	Project documentation (ARCHITECTURE.md, Glossary.md, planning docs like MoU_MVP.md, etc.).
Land/Element/Maintain/	Build scripts (GritQL queries here), CI/CD configuration, development utilities.
Land/Element/Wind/	(Conceptual) Potentially a UI component library or design system for Sky.
Land/Element/Worker/	(Conceptual) For web worker implementations used by Sky.
Land/Dependency/.../Editor	Contains a copy of the VSCode source, used by Rest and GritQL.

---

Getting Started 🚀

Follow these steps to get Land up and running on your system.

1. Clone the Repository: This command downloads the Land project files. The --recurse-submodules flag is crucial as it fetches external dependencies like the VS Code source code, which is needed for Cocoon.

git clone ssh://[email protected]/CodeEditorLand/Land.git --recurse-submodules

2. Install Dependencies: This command uses pnpm (a Node.js package manager) to install all JavaScript dependencies required for building the Sky frontend, the Cocoon sidecar, and various development tools.

pnpm install

3. Build the Application: The build process is multi-stage: it prepares VS Code dependencies (using Rest), bundles JavaScript for Cocoon, compiles the Rust backend (Mountain and other Rust Elements), and finally builds the Tauri application.

Build Variables Explained: These variables control aspects of the build:

Variable	Purpose
Browser=true	Influences JS build targets, ensuring web compatibility for Sky running in Tauri's webview.
Bundle=true	Crucial for Path A! Triggers Rest to bundle VS Code platform JS required for Cocoon.
Clean=true	Clears previous build artifacts from Land/Element/Output/ for a completely fresh build.
Dependency=Microsoft/VSCode	Specifies the VS Code source (from Land/Dependency/.../Editor) to use for Cocoon's JS bundle.
NODE_ENV=development or production	Controls build optimizations (minification, debug info). production is smaller and faster.
NODE_OPTIONS=--max-old-space-size=16384	Increases Node.js memory limit, often needed for the resource-intensive Rest bundling step.

Development Build: This command creates a development version of Land, which usually includes more debugging information and might build faster by skipping some optimizations.

pnpm cross-env Browser=true Bundle=true Clean=true Dependency=Microsoft/VSCode NODE_ENV=development NODE_OPTIONS=--max-old-space-size=16384 pnpm tauri build

Production Build (Release): This command creates an optimized release version of Land, suitable for distribution.

pnpm cross-env Browser=true Bundle=true Clean=true Dependency=Microsoft/VSCode NODE_ENV=production NODE_OPTIONS=--max-old-space-size=16384 pnpm tauri build --release

4. Run Land:

Development Mode: This command starts Land in development mode. It typically enables hot-reloading for the Sky frontend, allowing UI changes to be seen quickly without a full rebuild. This is the recommended way to run Land during active development.

pnpm run tauri dev

Production Build: After a production build, the executable will be located in Land/Element/Mountain/target/release/ (or a bundle subdirectory, depending on your OS). Run this executable to start the optimized version of Land.

---

Usage Guide 🛠️

When you run Land:

1. Mountain (the Tauri app / Rust backend) starts up.
2. For Path A (MVP), Mountain automatically launches the Cocoon Node.js sidecar process.
3. The Sky UI loads in the Tauri webview, presenting the editor interface.
4. The MVP aims to demonstrate core functionality, such as opening files and loading a basic "Hello World" type extension via Cocoon, proving the Track/Echo/Vine communication pathways are working.

(Refer to the detailed Mermaid diagram below or in ARCHITECTURE.md for a deeper dive into component interactions!)

---

System Architecture Diagram (MVP Path A) 🗺️

This diagram illustrates the build-time and runtime components for the MVP focused on Path A (Cocoon sidecar).

 graph TD
     %% Styling
     classDef mountain fill:#f9f,stroke:#333,stroke-width:2px;
     classDef cocoon fill:#ccf,stroke:#333,stroke-width:2px;
     classDef sky fill:#9cf,stroke:#333,stroke-width:2px;
     classDef ipc fill:#ff9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
     classDef build fill:#ddd,stroke:#666;
     classDef data fill:#eee,stroke:#666;
     classDef lib fill:#cfc,stroke:#333,stroke-width:1px;

     subgraph "Build Time Process"
         direction LR
         VSCodeSource["VS Code Source (Land/Dependency/.../Editor)"]:::build
         RestBuild["JS Bundler (Rest Element)"]:::build
         CocoonBundleJS(Cocoon JS Bundle):::data
         SkyBuildProcess["Sky Build (Astro/Vite - Sky Element)"]:::build
         SkyAssets(Sky Frontend Assets):::data

         VSCodeSource --> RestBuild;
         VSCodeSource -- Uses UI code --> SkyBuildProcess;
         RestBuild --> CocoonBundleJS;
         SkyBuildProcess --> SkyAssets;
     end

     subgraph "Runtime: Land Application"
        subgraph "Mountain (Rust/Tauri Backend - Mountain Element)"
            TauriRuntime[Tauri Runtime]:::mountain;
            TrackDispatcher[Track Dispatcher]:::mountain;
            MountainHandlers["Native Handlers (FS: River/Sun, WS: Mist)"]:::mountain;
            VineRustIPC["Vine (Rust IPC Layer)"]:::mountain;
            ProcessMgmtSystem["Process Management (Cocoon, Runner)"]:::mountain;
            RiverLib["River Lib"]:::lib;
            SunLib["Sun Lib"]:::lib;

            TauriRuntime -- Manages --> TrackDispatcher;
            TrackDispatcher -- Routes to --> MountainHandlers;
            MountainHandlers -- Uses --> RiverLib;
            MountainHandlers -- Uses --> SunLib;
            ProcessMgmtSystem -- Launches/Pipes --> CocoonSidecar;
            ProcessMgmtSystem -- Uses --> VineRustIPC;
        end

        subgraph "Sky (Frontend - Tauri Webview - Sky Element)"
            SkyUI["Sky UI (Astro/JS/TS)"]:::sky
            EchoFrontend["Echo API Client (JS)"]:::sky
        end

        subgraph "Cocoon (Node.js Sidecar - Cocoon Element)"
            NodeJSProcess[Node.js Process]:::cocoon;
            CocoonBootstrap["index.js (Bootstrap)"]:::cocoon;
            CocoonVineIPC["cocoon-ipc.js (Vine JS Layer)"]:::cocoon;
            CocoonShims[Shims/*.js]:::cocoon;
            BundledVSCodeJS["Loaded VSCode Platform JS (from Rest)"]:::cocoon;
            ExtHostServiceJS[ExtHostExtensionService]:::cocoon;
            ExtensionCode[Extension Code]:::cocoon;

            NodeJSProcess -- Runs --> CocoonBootstrap;
            CocoonBootstrap -- Loads --> BundledVSCodeJS;
            CocoonBootstrap -- Initializes --> CocoonShims;
            CocoonBootstrap -- Initializes --> CocoonVineIPC;
            CocoonBootstrap -- Initializes --> ExtHostServiceJS;
            ExtHostServiceJS -- Uses --> CocoonShims;
            ExtHostServiceJS -- Activates --> ExtensionCode;
            CocoonShims -- Uses --> CocoonVineIPC;
        end

        SkyUI -- Uses --> EchoFrontend;
        EchoFrontend -- Tauri `invoke` (Echo Action) --> TrackDispatcher;
        VineRustIPC -- Vine Protocol (JSON/stdio) <--> CocoonVineIPC; class VineRustIPC,CocoonVineIPC ipc;

        MountainHandlers -- Can send RPC via Vine --> CocoonVineIPC;
        %% Extension making an API call implies CocoonShim intercepts and sends it out via Vine
     end

     CocoonBundleJS -- Packaged with --> CocoonSidecar;
     SkyAssets -- Packaged into --> Mountain;

Loading

---

Changelog 📜

Stay updated with our progress! See CHANGELOG.md for a history of changes.

Funding & Acknowledgements 🙏

Land is proud to be an open-source endeavor. Our journey is significantly supported by:

This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

Land	PlayForm	NLnet	NGI0 Commons Fund