Skip to content

Commit 2df8aab

Browse files
feat(WebSite): Add 21 new documentation pages with hierarchical sidebar navigation
Add comprehensive documentation for all 15 Land elements (Air, Cocoon, Common, Echo, Grove, Maintain, Mist, Mountain, Output, Rest, SideCar, Sky, Vine, Wind, Worker) and 6 technology rationale articles (Why CC0, Why Effect-TS, Why gRPC, Why Rust, Why Tauri, Why WebAssembly). Each doc page follows a problem-solution narrative explaining what pain point the element or technology solves. Update DynamicDocSidebar.tsx to link to dedicated /Doc/{slug} pages instead of anchor links (#SectionId). Group all documentation pages by section (Start, Architecture, Usage, Development, Community, Support, Element, Technology, License) for hierarchical sidebar navigation. Update Doc.astro and Doc/[Slug].astro to render grouped sections and link to individual pages. Sync homepage copy in HomePage.tsx and Home.json: rewrite hero subtitle, CTA buttons, feature titles/descriptions, roadmap tiers, and download section. All 21 doc pages and supporting files are staged.
1 parent 6dec60d commit 2df8aab

26 files changed

Lines changed: 1395 additions & 218 deletions

Source/Component/Dynamic/DynamicDocSidebar.tsx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ const DynamicDocSidebar = ({
5959
return (
6060
<li key={Child.Id}>
6161
<a
62-
href={`#${Child.Id}`}
62+
href={`/Doc/${Child.Id}`}
6363
aria-current={
6464
IsChildActive
6565
? "page"
@@ -85,7 +85,7 @@ const DynamicDocSidebar = ({
8585
return (
8686
<li key={Section.Id}>
8787
<a
88-
href={`#${Section.Id}`}
88+
href={`/Doc/${Section.Id}`}
8989
aria-current={IsActive ? "page" : undefined}
9090
className={`block px-3 py-2 text-sm transition-colors hover:bg-[var(--ColorSecondary)] focus:outline-2 focus:outline-offset-2 focus:outline-[var(--ColorPrimary)] ${
9191
IsActive

Source/Component/Dynamic/HomePage.tsx

Lines changed: 67 additions & 135 deletions
Large diffs are not rendered by default.

Source/Content/doc/air.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Air"
3+
section: "Element"
4+
order: 15
5+
description: "The background daemon that pre-stages updates and eliminates cold starts"
6+
---
7+
8+
# Air
9+
10+
## The Problem Air Solves
11+
12+
VS Code cold-starts slowly because everything initializes fresh each launch: extension host, language servers, file index. Updates require a full restart that kills open terminals and in-progress work. There is no mechanism to pre-stage work between sessions.
13+
14+
## How Air Eliminates It
15+
16+
Air is a persistent background daemon (like macOS Spotlight or Windows Search Indexer) that keeps running after you close the editor. It pre-downloads and PGP-verifies the next update between sessions. It pre-indexes workspace changes that happened while the editor was closed. It keeps language server warm caches available for instant load.
17+
18+
When you launch Land, Air has already done the expensive work. The update was staged, verified, and ready.
19+
20+
## What You Experience
21+
22+
Cold start times under 200 ms. Updates apply between sessions with no interruption. You never see a workspace that "hasn't loaded yet." The next version is already downloaded and verified before you decide to update.
23+
24+
## Key Technologies
25+
26+
Air is written in Rust and communicates with Mountain through Vine's gRPC protocol. PGP signature verification ensures update integrity.
27+
28+
## See Also
29+
30+
- [Architecture Overview](/Doc/architecture)
31+
- [Mountain: Native Backend](/Doc/mountain)
32+
- [Local-First Protocol](/Doc/local-first-protocol)
33+
- [Source Code](https://github.com/CodeEditorLand/Air)

Source/Content/doc/cocoon.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: "Cocoon"
3+
section: "Element"
4+
order: 12
5+
description: "The extension host that runs every VS Code extension unchanged on Effect-TS fibers"
6+
---
7+
8+
# Cocoon
9+
10+
## The Problem Cocoon Solves
11+
12+
VS Code's extension host is a single Node.js process. One extension's activation event fires, takes 400 ms, and the entire editor freezes. One extension's `onDidChangeTextDocument` handler never resolves: every other handler in the process waits. One language server crashes and the extension host tries to restart it, blocking the event loop. Your cursor stops moving.
13+
14+
Everything competes on one thread. There is no way to cancel an in-flight extension operation. There is no back-pressure. Extensions cannot be preempted.
15+
16+
## How Cocoon Eliminates It
17+
18+
Cocoon intercepts `require` and `import` at the Node.js module level and routes all VS Code API calls through a complete Effect-TS service layer. Extensions call `vscode.workspace.openTextDocument()` and get back a `Thenable<TextDocument>` exactly as documented. Internally, that call is a typed Effect running on a fiber scheduler that can be interrupted, raced with a timeout, run concurrently with other operations, and traced for performance diagnostics.
19+
20+
Extensions are isolated into separate fiber scopes. One extension's hung Promise does not block another's fiber.
21+
22+
## What You Experience
23+
24+
50+ extensions activate concurrently. Language server crashes are handled in supervised scopes with automatic restart. No extension can freeze the editor. The full VS Code marketplace works without modification.
25+
26+
## Key Technologies
27+
28+
Cocoon runs on Node.js with Effect-TS providing the fiber runtime. It communicates with Mountain through Vine's gRPC protocol. TypeScript types are enforced end-to-end.
29+
30+
## See Also
31+
32+
- [Architecture Overview](/Doc/architecture)
33+
- [Extension Development](/Doc/extension-development)
34+
- [Mountain: Native Backend](/Doc/mountain)
35+
- [Source Code](https://github.com/CodeEditorLand/Cocoon)

Source/Content/doc/common.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: "Common"
3+
section: "Element"
4+
order: 19
5+
description:
6+
"The abstract foundation that makes every element testable in isolation."
7+
---
8+
9+
# Common
10+
11+
Every Element in Code Editor Land depends on shared contracts: data types,
12+
error enums, configuration schemas, trait definitions. Common is the crate
13+
that holds all of them, and it holds nothing else. No concrete
14+
implementations, no runtime behavior, no side effects.
15+
16+
## The Problem
17+
18+
VS Code modules import concrete implementations directly. Testing a single
19+
component means mocking entire subsystems: the file system, the window
20+
manager, the extension host. A unit test that should take milliseconds
21+
instead launches half the editor.
22+
23+
This tight coupling also means that changing one module can silently break
24+
another. There is no compile-time guarantee that a contract is being
25+
respected, because there is no formal contract to begin with.
26+
27+
## How Common Eliminates It
28+
29+
Common defines pure abstract traits for every cross-element boundary. Each
30+
trait specifies inputs, outputs, and error types. Zero concrete code lives
31+
in this crate.
32+
33+
When Element A depends on Element B, it depends on the trait defined in
34+
Common, not on B's implementation. The Rust compiler enforces the contract
35+
at build time. If B changes its signature, every consumer fails to compile
36+
immediately, not at runtime six months later.
37+
38+
## What You Experience
39+
40+
You can test any Element in complete isolation. Mock any trait, inject it
41+
into the component under test, and verify behavior without launching a
42+
window, a WebView, or a sidecar process. Tests run in milliseconds.
43+
44+
Refactoring becomes safe. Rename a method on a trait and the compiler tells
45+
you every call site that needs updating. No grep, no "find all references"
46+
in an editor that may miss dynamic calls.
47+
48+
## Key Technologies
49+
50+
Rust, Trait Objects, Zero-Cost Abstractions, Compile-Time Contract
51+
Enforcement.
52+
53+
## See Also
54+
55+
- [Architecture Overview](/Doc/architecture)
56+
- [Mountain](/Doc/mountain)
57+
- [Source Code](https://github.com/CodeEditorLand/Common)

Source/Content/doc/echo.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "Echo"
3+
section: "Element"
4+
order: 16
5+
description: "The work-stealing scheduler that runs indexing, search, and builds on every CPU core"
6+
---
7+
8+
# Echo
9+
10+
## The Problem Echo Solves
11+
12+
VS Code's background tasks (file indexing, symbol scanning, git blame, search) run in a single-threaded Node.js process. Heavy indexing blocks all other activity on that thread. The only escape is spawning more processes, which adds memory overhead and inter-process communication costs.
13+
14+
## How Echo Eliminates It
15+
16+
Echo is a lock-free concurrency runtime built on Rust's crossbeam-deque work-stealing scheduler. Every task submitted to Echo runs inside a supervised worker pool that spans all CPU cores. Tasks are work-stolen (idle threads pick up tasks from busy threads), supervised (every task has a parent scope with controlled crash propagation), and gracefully shut down (no task can outlive its scope).
17+
18+
## What You Experience
19+
20+
A 20-file refactor, a workspace-wide symbol search, and a test run can all happen in true parallel on separate CPU cores. The editor stays responsive throughout. Indexing, search, and builds run on every core in parallel while the UI thread never blocks.
21+
22+
## Key Technologies
23+
24+
Echo is written in Rust using crossbeam-deque for lock-free work stealing and tokio for async I/O.
25+
26+
## See Also
27+
28+
- [Architecture Overview](/Doc/architecture)
29+
- [Mountain: Native Backend](/Doc/mountain)
30+
- [Source Code](https://github.com/CodeEditorLand/Echo)

Source/Content/doc/grove.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "Grove"
3+
section: "Element"
4+
order: 18
5+
description: "The WASM sandbox that isolates extensions with capability-based security"
6+
---
7+
8+
# Grove
9+
10+
## The Problem Grove Solves
11+
12+
VS Code extensions run with full Node.js capabilities in a shared process. A malicious extension can read the file system, make network requests, and access other extensions' state. The "extension sandbox" is a policy document, not a technical boundary.
13+
14+
## How Grove Eliminates It
15+
16+
Grove runs extensions compiled to WebAssembly inside WASMtime with capability-based security. An extension can only touch resources explicitly granted to it: a specific directory, a network endpoint, a named IPC channel. No implicit ambient authority. The WASM sandbox is a technical boundary, not a policy document.
17+
18+
## What You Experience
19+
20+
The path to a marketplace where extensions can be run safely with zero trust, the same way mobile apps work on iOS and Android. An extension can only touch what you explicitly grant. The sandbox is enforced by the runtime, not by hope.
21+
22+
## Key Technologies
23+
24+
Grove is written in Rust using WASMtime for WebAssembly execution. It implements the VS Code API surface for WASM-compiled extensions.
25+
26+
## See Also
27+
28+
- [Architecture Overview](/Doc/architecture)
29+
- [Cocoon: Extension Host](/Doc/cocoon)
30+
- [Source Code](https://github.com/CodeEditorLand/Grove)

Source/Content/doc/maintain.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "Maintain"
3+
section: "Element"
4+
order: 25
5+
description:
6+
"The build orchestrator with Rhai scripting and deterministic output."
7+
---
8+
9+
# Maintain
10+
11+
Maintain is the build orchestrator for Code Editor Land. It coordinates
12+
Rest, Output, SideCar, and every other build-time Element into a single
13+
reproducible pipeline. Build logic is written in Rhai scripts, not shell
14+
scripts, and every configuration is validated at compile time.
15+
16+
## The Problem
17+
18+
Build pipelines that depend on environment variables, shell conditionals,
19+
and platform-specific scripts become impossible to debug. A build passes on
20+
one machine and fails on another because of a missing `$PATH` entry or a
21+
difference in how `sed` handles newlines on macOS versus Linux. VS Code's
22+
build system spans Gulp tasks, shell scripts, and Node.js scripts scattered
23+
across dozens of files. Reproducing a failure requires replicating the exact
24+
environment, which is rarely documented.
25+
26+
## How Maintain Eliminates It
27+
28+
Maintain replaces shell scripts with Rhai, an embedded scripting language
29+
designed for Rust applications. Rhai scripts are sandboxed, deterministic,
30+
and cross-platform by design. They cannot access the file system, network,
31+
or environment variables unless explicitly granted permission through
32+
Maintain's capability system.
33+
34+
Build configurations are Rust structs validated at compile time. A typo in
35+
a configuration key fails the build before any artifact is produced, not
36+
after twenty minutes of compilation.
37+
38+
Maintain orchestrates the full pipeline: Rest compiles TypeScript, Output
39+
stores artifacts, SideCar selects binaries. Each step receives typed
40+
inputs and produces typed outputs. If a step fails, the error message
41+
identifies the exact input that caused the failure.
42+
43+
## What You Experience
44+
45+
You run a single command and the build either succeeds or fails with a
46+
clear, actionable error. The same command produces the same result on
47+
macOS, Linux, and Windows. No environment-specific workarounds. No "works
48+
on my machine" mysteries.
49+
50+
Build scripts are readable. Rhai's syntax is close to Rust, so anyone who
51+
can read the application code can read the build logic.
52+
53+
## Key Technologies
54+
55+
Rust, Rhai Scripting, Compile-Time Configuration Validation, Deterministic
56+
Orchestration, Capability-Based Sandboxing.
57+
58+
## See Also
59+
60+
- [Architecture Overview](/Doc/architecture)
61+
- [Output](/Doc/output)
62+
- [Source Code](https://github.com/CodeEditorLand/Maintain)

Source/Content/doc/mist.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: "Mist"
3+
section: "Element"
4+
order: 20
5+
description:
6+
"The DNS sandbox that resolves *.editor.land locally."
7+
---
8+
9+
# Mist
10+
11+
Mist is the network boundary between Code Editor Land and the outside
12+
world. It creates a fully sandboxed DNS zone that resolves every
13+
`*.editor.land` domain to `127.0.0.1`. Nothing leaves your machine unless
14+
you explicitly allow it.
15+
16+
## The Problem
17+
18+
VS Code extensions, update checks, and telemetry endpoints all resolve
19+
against public DNS. Even with telemetry disabled, DNS queries still leak
20+
metadata about which extensions are installed, when the editor starts, and
21+
how often it phones home. There is no clean boundary between editor traffic
22+
and internet traffic.
23+
24+
Developers working on airgapped machines or behind strict firewalls face a
25+
different failure mode: DNS resolution hangs for seconds before timing out,
26+
and the editor stutters while it waits.
27+
28+
## How Mist Eliminates It
29+
30+
Mist intercepts all DNS queries for the `*.editor.land` zone before they
31+
reach the system resolver. Every query resolves instantly to `127.0.0.1`.
32+
The editor's internal services (authentication, extension marketplace,
33+
update checks) communicate over loopback without any packet leaving the
34+
network interface.
35+
36+
For domains outside the `*.editor.land` zone, Mist passes queries through
37+
to the system resolver unchanged. Your browser, terminal, and every other
38+
application behave exactly as before.
39+
40+
## What You Experience
41+
42+
The editor starts and operates without any public DNS dependency. No
43+
metadata leaks. No firewall warnings. No timeout delays on restricted
44+
networks.
45+
46+
On airgapped machines, the editor works at full speed because it never
47+
waits for a DNS response that will never come. On corporate networks, IT
48+
sees zero outbound traffic from the editor process.
49+
50+
## Key Technologies
51+
52+
Rust, DNS-over-Loopback, Sandboxed Zone Resolution, Zero-Leak Network
53+
Boundary.
54+
55+
## See Also
56+
57+
- [Architecture Overview](/Doc/architecture)
58+
- [Air](/Doc/air)
59+
- [Source Code](https://github.com/CodeEditorLand/Mist)

Source/Content/doc/mountain.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: "Mountain"
3+
section: "Element"
4+
order: 11
5+
description: "The native Rust backend that replaces Electron's main process with Tauri"
6+
---
7+
8+
# Mountain
9+
10+
## The Problem Mountain Solves
11+
12+
VS Code runs on Electron: a bundled Chromium instance plus Node.js. Every window adds another renderer process heap. Three open windows means three Chromium processes, each carrying a full heap. Every OS interaction (file dialog, clipboard, window move) crosses a serialized JSON IPC pipe.
13+
14+
The memory tax is not optional. Open VS Code with a medium project: 500 MB to 1.5 GB of RAM. Switch to another app: the memory stays allocated. The garbage collector fights a losing battle on a gigabyte heap.
15+
16+
## How Mountain Eliminates It
17+
18+
Mountain replaces Electron's main process entirely with a Rust binary using Tauri. The operating system's own WebView renders the UI: WKWebView on macOS, WebView2 on Windows, WebKitGTK on Linux. No bundled Chromium. No Node.js in the host process.
19+
20+
Window management, file system access, process lifecycle, and authentication tokens all happen in Rust with zero IPC overhead. Auth tokens live in the OS keychain, not in a renderer process heap.
21+
22+
## What You Experience
23+
24+
Cold start in under 200 ms. RAM footprint 60-80% smaller per window. File operations respond in microseconds, not milliseconds. Where Electron takes 200 ms to open a dialog, Mountain takes 2.
25+
26+
## Key Technologies
27+
28+
Mountain is built with Rust and Tauri 2.0. It communicates with Cocoon and other sidecars through Vine's gRPC protocol. The Cargo workspace manages all native dependencies.
29+
30+
## See Also
31+
32+
- [Architecture Overview](/Doc/architecture)
33+
- [Cocoon: Extension Host](/Doc/cocoon)
34+
- [Vine: gRPC Protocol](/Doc/vine)
35+
- [Source Code](https://github.com/CodeEditorLand/Mountain)

0 commit comments

Comments
 (0)