# Volith

**An experimental design language for editable 3D, built for AI-driven workflows.**

Build a shape from a program, inspect its geometry, then revise the design—not just
the mesh. Today's native `.vl` files preserve the selected executable source, exact
inputs and geometry for replay and later edits.

![An authored curved surface captured by the Volith viewer in normals mode](viewer/tests/fixtures/observation/render.png)

*Stored viewer observation fixture in normals mode. This is not an automatic
image-to-3D reconstruction or the panel/leaf quickstart output.
[Capture metadata](viewer/tests/fixtures/observation/metadata.json).*

**Early development · Windows x64 · Apache-2.0**

[Quickstart](#quickstart) · [Examples](examples/README.md)
· [Documentation](docs/README.md)
· [Connect an AI through MCP](docs/MCP.md)
· [Implementation status](docs/IMPLEMENTATION.md)
· [Contributing](#a-project-to-contribute-to)

## Why Volith

The goal is to let an AI turn its understanding of a form into a design it can
execute, observe and revise. Volith explores that workflow through a programming
language and native MCP tools, rather than treating a finished mesh as the only
result.

- **Keep the design editable.** Save executable source and exact inputs alongside
  geometry, then replay and change the selected program.
- **Inspect what actually ran.** Use MCP to execute a program, export its surface
  and work with observations of the result.
- **Make changes checkable.** The connected examples share real boundary indices;
  tests check that a bridge edit preserves its parent surfaces.

For now, this is an early project for developers working on AI tools, geometry and
programming languages—not a finished CAD application. The broader goal includes
parts, guides, relationships, constraints and preserved design decisions.
See the [vision](docs/VISION.md) and [roadmap](docs/ROADMAP.md).

## What runs today

The [panel and leaf examples](examples/README.md) use the same reusable
`design.patch_graph` operation with different authored inputs. They demonstrate
construction and correction, not trained reconstruction or accepted reference
reproduction.

<details>
<summary>Technical components</summary>

| Component | Implemented scope |
| --- | --- |
| Language runtime | Windows x64 machine-code seed, typed compiler and bounded VM written in Volith |
| Native MCP | Eighteen `core_*` tools for compilation, execution, surface export, observation and native replay |
| Geometry | Authored bicubic patches, affine instances and Hermite bridges with shared parent boundary indices |
| Computational reasoning | Dependency closure and a bounded affine soft-residual solver with hard boxes |
| Native projects | Selected-program `.vl` save/replay with exact inputs and geometry, including a later edit |
| Viewer | Tauri/Rust/Three.js surface display, camera/observation interactions and native project replay through MCP |

</details>

**Not implemented yet:** arbitrary reference reconstruction, accepted reference
fidelity, general nonlinear constraints, separately compiled module imports, or the
full native design/reference/history graph. The complete AI interpretation and
design-preservation workflow remains a goal, not a delivered product.

[Current capabilities and limits](docs/IMPLEMENTATION.md) are tracked separately
from the [Revision-3 design](docs/next/README.md).

## Quickstart

### 1. Run an authored example

Requirements: **Windows x64, PowerShell 7, Node.js 22+**. This scripted example and
the native tests need no cloud account, model weights or API key; connecting an AI
client is a separate step.

```powershell
git clone https://github.com/higongback/Volith.git
cd Volith
pwsh -File tools/build.ps1
node tools/run-example.mjs examples/design-graph/panel-bridge.json .work/panel
```

The build packages the seed and literal Volith source. The example sends real MCP
requests and writes a native `.vl` project, a derived surface and an explicit viewer
connection into a **new** workspace. Use a fresh destination for each run.
The JSON input and exported mesh are not native projects.

To verify the native path, run this from the repository root:

```powershell
node tests/native-design.test.mjs
```

The tests use Node built-ins and retain a report in a new temporary directory.
They check geometry, dependencies, solver cases, native replay and a later edit.
See [verification details](docs/IMPLEMENTATION.md#verification).

### 2. Inspect the result in 3D

The viewer additionally requires **Rust, Windows C++ build tools and WebView2**.
Starting from the repository root after creating `.work/panel`:

```powershell
$env:VOLITH_WORKSPACE = (Resolve-Path .work/panel).Path
cd viewer
npm ci
npm run tauri dev
```

Choose **Load surface** to inspect the example or **Open** to replay a native `.vl`
project. The first Rust build takes longer because it compiles viewer dependencies.

The browser-only display shell does not execute native modeling; use the Tauri
viewer for that path. See [viewer setup](viewer/README.md) and
[authored examples](examples/README.md).

### 3. Connect an AI through MCP

Once the local example works, follow [the MCP setup guide](docs/MCP.md).
Keep the distinction between the tools that run today and the broader design
workflow described in the vision.

## Documentation

Use [the documentation index](docs/README.md) to navigate the repository without
mixing current implementation claims with proposed architecture or retained research.
The short version is:

- [Implementation status](docs/IMPLEMENTATION.md) — what runs now.
- [Vision](docs/VISION.md) and [roadmap](docs/ROADMAP.md) — direction and planned work.
- [Revision 3 design](docs/next/README.md) — broader proposed architecture and retained contracts.
- [Source layout](docs/LAYOUT.md) — directory responsibilities and publication boundaries.

## A project to contribute to

We welcome language engineers, geometry and numerical-computing specialists,
artists, designers and systems developers. You do not need to understand every
layer to help.

Useful first contributions include an independent checker, a reproducible failure
case, clearer setup instructions, a reusable spatial operation or a better
observation workflow. [Starter tasks](docs/community/START_HERE.md) describe concrete
entry points and the evidence expected for each.

Read [CONTRIBUTING.md](CONTRIBUTING.md) for development boundaries, validation and
the pull-request process. Bug and design-proposal templates are included.

## Repository layout

| Directory | Purpose |
| --- | --- |
| [`runtime/`](runtime/README.md) | Active Volith compiler, VM, native MCP/persistence and machine-code seed |
| [`runtime/library/`](runtime/library/) | Reusable operations with operands, applicability and limitations |
| [`viewer/`](viewer/README.md) | Tauri/Rust/Three.js display and MCP client shell |
| [`examples/`](examples/README.md) | Explicit authored design inputs, separate from common runtime behavior |
| [`tests/`](tests/) | Reproducible native MCP and independent geometry/reasoning checks |
| [`tools/`](tools/) | Build packaging, transport and contributor utilities |
| [`docs/`](docs/README.md) | Documentation index, status, design, roadmap and verification |

Native projects use **`.vl`**. Volith source uses **`.vlth`**. Production modeling and
language execution remain Volith; PowerShell/Node support packaging, transport and
independent verification. The viewer uses its disclosed host/display stack.
See [layout and boundaries](docs/LAYOUT.md).

## License

[Apache License 2.0](LICENSE). Original Volith source and documentation are open for
use and contribution under these terms. Third-party dependencies retain their own
licenses; see [notices](THIRD_PARTY_NOTICES.md).