You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+94-2Lines changed: 94 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
# Arcadia
2
2
3
-
**One Rust core. Three surfaces. Zero rent.**
3
+
**One Rust core. One Python SDK. An infinite extension surface. Zero rent.**
4
4
5
-
Arcadia is a multi-platform runtimeand shell: a single `arcadia-core` crate owns every module, command, navigation structure, LAN protocol, and config schema — then two native surfaces (a GPUI desktop app and a SwiftUI iOS app) plus a CLI consume it. Business logic lives once. Surfaces read, render, and dispatch.
5
+
Arcadia is a multi-platform runtime, shell, and — ultimately — an **open platform for building system-integrated applications**. Today: a single `arcadia-core` crate owns every module, command, navigation structure, LAN protocol, and config schema, consumed by two native surfaces (GPUI desktop, SwiftUI iOS) plus a CLI. Tomorrow: a Python library that gives any developer full OS reach and a first-class extension SDK for building apps — menu bar tools, custom IDEs, file explorers, widgets, shells — that run everywhere and belong to no vendor.
6
6
7
7
Built on the same DNA as **[Holos](https://github.com/stack-node/holos)** — *utility over monetization, ownership over subscriptions* — but with a harder engineering mandate: **no duplicated truth between platforms, no hardcoded IDs in surface code, no growing if-else chains that break the next time a module is added.**
8
8
@@ -12,6 +12,7 @@ Built on the same DNA as **[Holos](https://github.com/stack-node/holos)** — *u
12
12
13
13
-[Why Arcadia exists](#why-arcadia-exists)
14
14
-[What Arcadia is](#what-arcadia-is)
15
+
-[The vision — where this is going](#the-vision--where-this-is-going)
15
16
-[What you can do with it now](#what-you-can-do-with-it-now)
16
17
-[Development status](#development-status)
17
18
-[Philosophy](#philosophy)
@@ -70,6 +71,97 @@ If something's missing, you add a module or extend `surface.snapshot` / `surface
70
71
71
72
---
72
73
74
+
## The vision — where this is going
75
+
76
+
What Arcadia is *right now* is the foundation. What it's *becoming* is something more deliberate:
77
+
78
+
**A platform where anyone can build system-integrated applications — without a vendor, without a subscription, without a degree in native systems programming.**
79
+
80
+
### The Python library
81
+
82
+
The next major layer is a Python SDK that exposes the full power of `arcadia-core` to any developer who can write a script. Not a watered-down scripting layer — full OS reach:
83
+
84
+
-**File system** — read, write, watch, index
85
+
-**Processes** — spawn, manage, pipe, monitor
86
+
-**Networking** — LAN discovery, routing, peer communication
87
+
-**Display** — render into Arcadia's native surfaces (Desktop GUI, iOS) from Python
-**Config** — read and write module state, preferences, thin-client config
90
+
-**Events** — hook into system events, timers, window focus, LAN peer state changes
91
+
92
+
The goal is parity with what you'd get writing native Rust or Swift — but with a workflow where you open a file, write twenty lines, and have a running extension.
93
+
94
+
### Extensions: the real product
95
+
96
+
The Python SDK powers an **extension system**. Extensions are the unit of user-created capability in Arcadia. An extension can be:
97
+
98
+
| Type | Examples |
99
+
|------|---------|
100
+
|**Internal app**| A custom shell, a task manager, a log viewer — rendered inside Arcadia's native UI just like the built-in Shell page |
101
+
|**Widget**| A persistent overlay — system stats, a clock, a scratchpad, a LAN activity feed |
102
+
|**Tool**| A headless background process — file watcher, sync agent, notification hook, cron-style automator |
103
+
|**Surface extension**| A sidebar panel, a top-bar chip, a custom modal — extending the host UI without forking it |
104
+
|**Device bridge**| Cross-machine extensions that route commands to LAN peers via the existing `remote-session` + `surface.*` protocol |
105
+
106
+
Extensions register into the same `MODULE_REGISTRY` and `PAGE_DEFINITIONS` systems that built-in modules use. There is no separate "plugin API" — extensions are first-class modules. A menu bar tool is a module. A custom IDE panel is a navigation page. A background sync agent is a headless module with no UI. They all follow the same patterns the core enforces.
107
+
108
+
### What this makes possible
109
+
110
+
**For individuals:** build the exact tool you want. Bartender-style menu bar manager? Thirty lines of Python registering a widget module and a tray handler. A file explorer that opens on a keyboard shortcut and talks to your NAS over LAN? That's two extensions and a LAN peer config. A custom IDE with your own keybindings, your own terminal, your own sidebar? That's a surface extension composing built-in shell + your panels.
111
+
112
+
**For teams:** share extension bundles instead of paying for another SaaS tool. A shared monitoring dashboard, a deployment helper, a standup widget — all running locally, all owned by you, all talking to each other over the same LAN protocol Arcadia already ships.
113
+
114
+
**For the open-source community:** an ecosystem of extensions that anyone can fork, modify, and publish. No app store approval. No revenue split. No "premium tier." You write it, you run it, you share it if you want.
115
+
116
+
### Why Python for the SDK
117
+
118
+
Three reasons:
119
+
120
+
1.**Reach** — more people can write Python than can write Rust or Swift. Lowering the barrier to extension authorship is the whole point.
121
+
2.**Speed of iteration** — a Python extension reloads without a rebuild. The feedback loop for building a new tool should be seconds, not minutes.
122
+
3.**Ecosystem** — the Python package index is enormous. An extension that needs to parse PDFs, call an API, process images, or run ML inference can reach for a pip package instead of re-implementing everything.
123
+
124
+
The Rust core stays Rust. Performance-critical paths, protocol handling, LAN networking, config I/O, FFI to native surfaces — none of that moves to Python. The Python layer sits above it, calling into `arcadia-core` through a clean API boundary.
125
+
126
+
### The development workflow target
127
+
128
+
The experience we're building toward:
129
+
130
+
```
131
+
1. arcadia ext new my-tool # scaffold a new extension
132
+
2. edit my_tool/main.py # write your logic
133
+
3. arcadia ext dev my-tool # hot-reload development mode
134
+
4. arcadia ext install my-tool # register with the local runtime
135
+
5. share my_tool/ with anyone # they install it the same way
136
+
```
137
+
138
+
No Xcode. No Cargo. No native toolchain required to write an extension. The native layer is already compiled and shipped — extension authors build *on top of it*, not inside it.
139
+
140
+
### Cross-platform by design
141
+
142
+
Extensions written against the Python SDK run on every surface Arcadia targets:
143
+
144
+
-**macOS** — GPUI desktop, menu bar, CLI
145
+
-**iOS** — SwiftUI surface (where the extension's UI contract is met)
146
+
-**Linux** — headless or desktop
147
+
-**Windows** — headless or desktop
148
+
149
+
An extension that declares it renders a navigation page gets that page on every surface that supports pages. An extension that declares it's headless-only runs as a background service everywhere. Surface capabilities are declared, not assumed.
150
+
151
+
### The priority order
152
+
153
+
Building toward this in stages:
154
+
155
+
1.**Now:** bulletproof the core — registry patterns, test coverage, CI, revision semantics *(done / in progress)*
156
+
2.**Next:** Python bridge — `arcadia-core` callable from Python, initial OS API surface (file, process, shell, config)
157
+
3.**Then:** extension loader — Python extensions register as modules at runtime; dev-mode hot reload
158
+
4.**Then:** widget and surface extension contracts — render Python-driven UI into native surfaces
159
+
5.**Then:** extension registry — discover, install, and share extensions; no central gatekeeper
160
+
161
+
Each stage ships usable capability. Nothing waits for the whole roadmap to be done.
0 commit comments