cadova

name: cadova description: Reference and cheatsheet for Cadova, a Swift DSL for parametric 3D modeling (3MF output, Manifold-backed). Use when reading or writing Swift files that import Cadova, when working in a directory whose Package.swift depends on github.com/tomasf/Cadova, or when the user asks about Cadova primitives, models, edge profiles, materials, or 3MF generation. user-invocable: true

Swift DSL for parametric 3D modeling. Pre-1.0 — API may shift between minor versions. This skill bundles a snapshot of upstream docs.

Bundled reference (use these first, before WebFetch)

wiki/ — full Cadova wiki, grep-friendly markdown. Key pages:
- wiki/Getting-Started.md — Package.swift template, hello-world
- wiki/Core-Concepts:-1.-Geometry.md through 5.-Model-and-Project.md
- wiki/Working-with-Parts.md — multi-part models, materials
- wiki/Troubleshooting.md
examples.md — copy of the Examples wiki page (Chamfer, materials, swept text, loft, …) for quick scanning
source/Sources/Cadova/ — Cadova source with inline DocC comments. The authoritative API reference. Grep here when uncertain about method names or parameters.

When the user asks about a Cadova type, primitive, or operation: grep source/Sources/Cadova/ first, then fall back to the wiki. Avoid inventing method names — Cadova's pre-1.0 API is too easy to hallucinate.

Hard facts to remember

Units: millimeters only

All Double dimensions are millimeters. There is no Length/Measurement<UnitLength> type.
Measurements2D.area is mm², Measurements3D.volume is mm³.
Inches → multiply by 25.4 yourself.

Entry point: `await Model(...)`

Model is async. Top-level use requires await.
The closure body is a result-builder DSL — no return, just stack shapes.
Running the executable writes <name>.3mf to the working directory.

import Cadova

await Model("widget") {
    Box([10, 10, 5])
        .subtracting {
            Sphere(diameter: 10).translated(z: 5)
        }
}

Required Package.swift bits

// swift-tools-version: 6.1 (minimum)
platforms: [.macOS(.v14)]
Target needs swiftSettings: [.interoperabilityMode(.Cxx)] — Cadova bridges to Manifold (C++)
Pin with .upToNextMinor(from: "X.Y.Z") because Cadova is pre-1.0

Package.resolved

Executable (model) project → commit Package.resolved for reproducible builds.
Library → gitignore it.

API quick-reference (verified against 0.6.1 source)

Always grep source/ to confirm — this list is a starting point, not exhaustive.

2D primitives

Circle(diameter:), Circle(radius:)
Rectangle([x, y]), Rectangle(x:, y:)
RegularPolygon(sideCount:, widthAcrossFlats:) (also circumradius:, inradius:)
Text(_:) with .withFont(_:, style:, size:)

3D primitives

Box([x, y, z]), Box(x:, y:, z:)
Sphere(diameter:), Sphere(radius:)
Cylinder(diameter:, height:), Cylinder(bottomDiameter:, topDiameter:, height:)

Booleans (closures, not arrays)

.subtracting { ... } / .intersecting { ... } / .adding { ... }
Or the free functions Union { }, Difference { }, Intersection { }

Transforms

.translated(x:, y:, z:), .rotated(x:, y:, z:) (angles in Angle type — 90° literal works)
.scaled(_:), .mirrored(in:)
.clonedAt(x:) — places a copy at offset, keeps original

2D → 3D

.extruded(height:) — basic linear extrusion
.extruded(height:, topEdge:, bottomEdge:) — with edge profiles
.revolved() — around Y axis

Edge profiles (for `topEdge:`/`bottomEdge:` on extrude)

.chamfer(depth:), .chamfer(width:, height:)
.fillet(radius:)
.none

Rounding (2D)

.rounded(insideRadius:), .rounded(outsideRadius:), .rounded(radius:)

Layout

Stack(.x, spacing:) { ... } / Stack(.y, …) / Stack(.z, …)
Alignment via .aligned(at: .centerX, .bottom) etc.

Materials & color

.colored(.darkOrange) (CSS color names available)
.withMaterial(.glossyPlastic(.mediumSeaGreen)), .steel, etc.

Conventions for caddy / parts work

The user is building parts in /Users/oliver/Projects/parts/. Each part is its own Swift executable package.
Build via Taskfile.yml — typically task build and task run (which writes the .3mf).
Run the executable to view results; chamfer.3mf and similar are gitignored.
The user opens 3MF in CadovaViewer on macOS for live reload.

Refreshing this skill

bash $CLAUDE_CONFIG_DIR/skills/cadova/update.sh

This re-clones the wiki and Cadova source (defaults to latest main; set CADOVA_VERSION=0.6.1 to pin). Re-run after upstream releases a new minor version.

Useful greps

# Find all public symbols
grep -rE "public (struct|enum|class|func|extension|protocol)" source/Sources/Cadova/

# Find a specific method
grep -rn "func extruded" source/Sources/Cadova/

# Search wiki for a concept
grep -rni "alignment" wiki/