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

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.

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 (named 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.

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.

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

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):

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.

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.)

Our codebase is organized into "Elements," each with a distinct purpose. Many Elements that link to separate repositories are managed as Git submodules within the main Land repository.

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 all "Element" submodules and the VS Code source code dependency.

   git clone ssh://git@github.com/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:

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 and Tauri configuration). Run this executable to start the optimized version of Land.

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!)

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 (Submodule at 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, Auxiliary Runners)"]:::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 -- Manages --> RunnerProcess["Runner Process(es)"];
            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;

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

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