* File format families: drawings share the design format's versioning (#3890) The format code works for a family of files: its own tag, its own numbers and its own folder of change files, with one reading of a file's format, one refusal of a file a newer build saved and one upgrade for every family. Designs (solidcraft/N) are one family and keep everything they had: FORMAT and FORMATS are as they were, and pending_names, format_string, version_of and read mean what they did. Drawings (solidcraft-drawing/N) are the other, with format 1 as their first record and each later change one file in crates/doc/src/drawing/format/pending/, as design changes are. Nothing saved changes. A design tag never reads as a drawing's or the other way round, and a file that names no format is a design from before format strings, never a drawing. Every refusal names its family; a design's read word for word as before. A design listing a pending change this build doesn't have is now refused as a newer build's before its content is checked, as a newer number already was, so a newer build's fields never read as damage. The list reader is take_names(v, key, noun), the shape #4811 uses for its own list. For the maintainer, the release step changes: scripts/fold-format-pending.sh now folds every family that crates/doc/build.rs lists (FAMILIES), each into its own next number: designs into crates/doc/src/format/v<N>/ as before, drawings into crates/doc/src/drawing/format/v<N>/ from 2. With nothing pending in a family it says so and moves nothing. Its test folds a drawing change into v2 beside the design changes. docs/releasing.md, CONTRIBUTING.md and AGENTS.md say so. build.rs lists each family's changes from its own folder, each folder's versions contiguous from its own base. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Drawing record: format 1 of the drawing family (#3890) A drawing is now a record of its own (crates/doc/src/drawing.rs): its name, the designs it draws (sources: an id and the design file's path, relative to the drawing's folder as a linked design's is), its properties under the design metadata's rules, its units (each design's own, or one length unit of the expression unit table), its content language (a BCP 47 tag) and its sheets. A sheet holds its paper, a copy of its drawing border's profile, the resolution its pictures are rendered at (300 dpi unless it says, 25 to 2400), the component it documents and whether it is left out of the sheet count or of printing. This is format 1 of the drawing family; each later kind of record adds one file in crates/doc/src/drawing/format/pending/. The rules: one id counter for every object, raised above the largest id when a file is read and never rewound; every reference is an id that must resolve, or the file is damaged and refused, never patched; 1 to 1,000 sheets, at most 64 sources, names of 1 to 256 bytes, paths of 1 to 4,096 bytes without NUL. The same drawing always saves as the same bytes. Drawing::from_json reads at most 16 MiB of text, then runs the family's format check, the number check, the upgrade, the typed record (unknown fields refused everywhere) and Drawing::validate. The number check is now one function every family calls, Family::check_numbers, told which field holds other tools' data; a design's refusals read as before. Nothing saves or opens a drawing yet: the container is the next step. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Drawing ids: random and collision-free from format 1 (#3890) A drawing's objects now take random ids, the form jyviko chose on #3890 from #1017: no counter, so objects added on two branches never share an id and never edit one line. The allocator is one module for drawings now and designs later (#626 Phase 3), crates/doc/src/ids.rs: an IdSource gives nonzero u64s by splitmix64 from a seed, each checked against the ids in use and drawn again when it is one, or when it is 0. A run never draws a number twice, so at most one draw per id in use comes before a free one, and a seeded run over a file the same seed made still gets a new id. IdSource::seeded gives the same ids for tests and replays; IdSource::from_entropy seeds a session from the standard library's hash keys, the time and a count, with no new dependency. In a file an id is 13 characters of Crockford base32, lowercase (0000000000001 to fzzzzzzzzzzzz): ids::encode writes it and ids::decode reads only that spelling, case-sensitive, so an id has one form to search for. Anything else, 0 included, makes the drawing damaged. The drawing loses next_id (a file that holds one is refused), and Drawing::new and allocate_id take the IdSource. Messages name ids as the file writes them. The component a sheet documents stays its design's own number until designs move over. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Drawing record: a drawing too large to reopen isn't saved (#3890) from_json reads at most MAX_DRAWING_BYTES (16 MiB), but to_json had no limit. Other tools' properties are kept as they came, and indenting them can grow a drawing read in at about 4 MB past 16 MiB (two million zeros in one array), so the next read refused what the save had just written. 0xlillith found it in review of #3891. to_json now returns a Result and refuses JSON longer than a read takes ("drawing too large to save (at most 16 MiB)"), so every drawing saved opens again. Nothing writes drawing files yet, so the error reaches the future file writer before it publishes anything. Test: that case is refused, and a smaller compact drawing saves and reopens unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Drawing files: a drawing saved as a container or as plain JSON, never read as a design (#3890) K3 of the drawing storage plan (W11.2): the file a drawing is saved in. Nothing writes one from a command yet; opening and saving come with K5. - A drawing container is a design container holding `drawing.json` (Deflate, as `document.json`) in place of `document.json`, and `container.json` says so: {"content": "drawing", "format": "solidcraft-container/1"}. A design's `container.json` is as it was, with no `content`. The plain JSON form is the drawing's own text. Both give the same bytes every save, so a drawing can live in version control as text. - `io::file_kind` tells a design from a drawing by `container.json` or by the JSON's format. The design reader refuses a drawing ("this file is a SolidCraft drawing, not a design: open it as a drawing") and the drawing reader a design; plain JSON only asks when it isn't a design, so reading a design costs nothing more. A container's content this build doesn't know, or a drawing container that also holds a design's `document.json`, is refused. - `read_drawing` (bytes, either form), `read_drawing_file` (one seekable handle, the design reader's checks) and `write_drawing_container`; `DRAWING_EXT` (`scdwg`) and `is_drawing_path` beside the design's. - The container writer's set-up and finish, the file opening and the container sniffing move into one function each, which designs and drawings both use. The container's own checks (budgets, entries, the ZIP directory) are the design container's, word for word. Tests: a drawing round-trips through both forms byte for byte, and the container holds exactly `container.json` and `drawing.json`; `file_kind` on both forms of both kinds; each reader refuses the other's file; unknown content, a stray `document.json`, a missing drawing, an unknown container version and a damaged drawing refused; both forms from disk, and a directory refused; mutation fuzz of both forms (an error or a drawing, never a panic). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
17 KiB
SolidCraft — instructions for agents
SolidCraft is a clean-room, open-source, pure-Rust parametric 3D CAD application: sketches with a constraint solver, a parametric timeline of features, a B-rep kernel, and a desktop UI that agents can drive. Projects published by storytold can serve as references for implementation conventions. Any code adapted from other projects (MIT OR Apache-2.0) is noted in ATTRIBUTION.md.
Product name
SolidCraft everywhere: crates solidcraft-*, binaries solidcraft and solidcraft-cli,
.solidcraft designs, the solidcraft/N format tag, SOLIDCRAFT_* environment variables,
settings and recovery folders, the MCP server name, docs, CI and packaging. The old name
survives only in the explicit compatibility shims listed in docs/compatibility.md; don't add
new uses of it anywhere else. Public docs/web/Flatpak deployments use project Pages
/solidcraft/; do not add permanent old-name Pages aliases.
Start every session here
- Read
plan/STATUS.md(current milestone, next task), then the task inplan/execution-plan.mdand the relevantplan/architecture.mdsection. - Kernel and library decisions:
plan/adr/0001-geometry-kernel.md(what we may depend on, what is rejected for licence reasons). - Follow the autonomous operation protocol (
plan/execution-plan.md§6). Don't stop to ask unless it lists the decision as the owner's.
plan/ is gitignored (local only).
Never crash
People trust SolidCraft with their designs; a crash loses their work. This outranks feature work.
- No panics in non-test code: no
unwrap(),expect(),panic!,unreachable!,todo!,unimplemented!; nounsafe(unsafe_code = "forbid"). The exceptions, in the app crate and incrates/threedx-client(which deny it instead), have no safe API: the macOS-onlycrates/threedx-client/src/macos.rs(loads the 3Dconnexion driver's client framework at run time and calls through its function pointers), two functions inapps/solidcraft/src/open_documents.rs(macOS hands Finder files only to an Objective-C method), the Windows-onlyapps/solidcraft/src/native_crash.rs(the exception filter that records crashes inside native code such as graphics drivers), the Windows-onlyapps/solidcraft/src/native_frame.rs(the window procedure that answers the resize-border hit test of the window without OS decorations) and the Windows-onlyapps/solidcraft/src/space_mouse/windows_hid.rs(asks Plug and Play which HID interfaces are 3D mice, so no other device is sent anything). - Errors are
Result<T, E>through the crate's error type and?. An unfinished feature returns an error ("not supported yet: …"); it never panics. - Input-derived numbers are hostile (command parameters, design files, control-channel
input):
get()not[i], finite checks, caps on sizes and loop counts. - Third-party kernel calls are guarded: everything that calls
truckgoes throughsolidcraft_kernel::guard, which turns a panic intoKernelError::Internal. - Last-resort guard:
Session::executeruns every command undercatch_unwind; an escaped panic restores the design and reportsEngineError::Internal. - Crash reports: the desktop app writes every panic and every unclean exit to a local crash folder,
with the design and the commands that reproduce it (
solidcraft_engine::crash, docs/crash-reports.md). When someone says the app crashed, look there first:solidcraft-cli crashes,crashes show <id>,crashes replay <id>(or thediagnostics.crash_reportscommand / MCPcrash_reportstool). - Prove it: every crash fix lands with a regression test (see
hostile_params_never_panic); a crash report'sdesign.solidcraft+replay.jsonis the test's starting point. - Where tests go: a regression test goes into the existing test file for its area (booleans, blends, shell, sweep, STEP, naming…), never a new file named after the bug (#3226).
- Every production crate root carries
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)].
Non-negotiables
- Independent. SolidCraft is independent. Behaviour is designed from public documentation, general CAD conventions and user feedback. Reference tests use analytic values and open-source tools. Never copy another product's code, icons, artwork, help text, tooltips, templates or materials. File formats come from public specifications.
- No commercial CAD products. Agents must not drive, script, automate or extract data from commercial CAD products (Fusion, SolidWorks, Onshape, …) for this project: no test data, measurements, command lists, ids or files produced with them.
- Never read, copy or link GPL/LGPL/AGPL code: OpenCASCADE, FreeCAD (incl. planegcs),
SolveSpace, CadQuery/OCP, LibreCAD, QCAD — don't even read their sources. (
tools/freecad-oracle/runs FreeCAD as a separate program through its public scripting API to compute reference values; nothing from FreeCAD is linked, vendored or shipped.) The sketch solver and the blend operations are our own. - Assets — absolutely essential. SolidCraft contains no iconography, images, fonts or
artwork from commercial CAD products — ever. Command icons are the original SVG masters in
assets/icons/ui/design/svg/, compiled throughcrates/ui-egui/src/icon_svg.rs. Before any icon, icon assignment or media edit, readassets/AGENTS.md,assets/icons/ui/AGENTS.mdandassets/icons/ui/STYLE_GUIDE.md. Use the canonical bases and named finished references there; never invent a parallel icon style. Any file asset must be original or openly licensed and must have a row in ATTRIBUTION.md (cargo xtask assetsenforces it). Screenshots of commercial CAD software are never committed. Breaking this rule is the most serious mistake you can make in this repo. - Everything is a command. User-visible behaviour = a command in
crates/engine/src/cmd/*(CommandSpec: id = our own dotted, lower-case id<area>.<thing>[.<variant>]such assolid.extrudeorsketch.rectangle.two_point, never another product's command id; label; toolbar tab and panel; icon; shortcut; params doc;enabled; JSONrun) + tests. The toolbar, dialogs, sketch tools, palette, scripts, CLI and control channel all reach the same commands. - Programmatic calls never open dialogs.
engine.executeruns the JSON form; only toolbar clicks (ui.start) start interactive tools and dialogs, which then run commands. - Layering is enforced by
cargo xtask layers: L0geom→ L1sketch,kernel,render→ L2doc→ L3io→ L4engine→ L5ui-egui→ apps. Nothing below L5 depends on egui/eframe/winit/wgpu/rfd. The UI crate is swappable. Onlycrates/kernelmay usetruck. - The UI is thin: panels read engine state and act through
app.run(id, params)/app.start(id). Colours come fromtheme::Tokens. - One outer UI container: all panels, floating sheets, menus, overlays and platform UI
windows use
ui_kit::Container(directly or throughPanel,Window,Confirm,Menu). Declare the semanticSurface; workspace panels use its shared layout policy and chrome. System/report windows useui_kit::Window; its low-level host builder is kit-private. Do not construct raw egui hosts, outer popup/window frames or shadows in feature modules.cargo xtask ui-containersrecursively checks source/examples in all current and future crates and apps. It runs in the fast repository CI job andcargo xtask ci, with no caller allowances. Seedocs/ui-container-audit.mdfor the inventory and legitimate content/native exceptions. - One set of camera controls: every page or canvas with a camera (viewport, Render
preview, future flat pattern or drawing pages) calls
navigation::handlewith itsNavCaps(orbit off for flat 2D pages). New canvases must usenavigation::handle; never hand-roll camera input (a test rejects it). - Application code is Rust only. Units are millimetres and radians internally; Z is up.
Local asset authoring, lint and review tools use Python 3.11+ as documented in
assets/AGENTS.md; Python is not an application runtime dependency. The application exception is JavaScript the browser requires: the service workerapps/solidcraft-web/sw.js(browsers only run service workers as JavaScript) and the small inline scripts inapps/solidcraft-web/index.html. Keep them minimal;cargo xtask web-offline-testcovers the service worker. - Quality gates before every commit:
cargo xtask ci(fmt, clippy -D warnings, tests, assets, layers). Commit after every feature arc that builds. - Publishing: the repository is github.com/tangency-labs/solidcraft. Changes land through
pull requests and the merge queue: push a branch and open a PR. The heavy CI jobs start
when a maintainer adds
approved-for-ciafter reviewing the code. Approved PRs go into the queue withgh pr merge N -R tangency-labs/solidcraft --squash --auto; the queue runs the full suite on each group before it lands onmain. Keep each PR to one topic and one issue, and never force-pushmain. Never commitplan/, build dirs (target*/) or generated reference data; checkgit ls-filesbefore pushing. - Never break wasm: everything below the apps must build for
wasm32-unknown-unknown(cargo xtask wasm, part ofcargo xtask ci).
Showing and following through on changes
- Help reviewers see what is broken or changed. For observable CAD, UI or model behavior, issues and PRs must include actual descriptive screenshots or a short recording from a small reproduction. This includes kernel, geometry, assembly and backend changes whose effects can be shown in the app. Coding agents should run the app and capture this evidence themselves; do not ask a human for evidence the agent can produce. Show the actual failure or result, preferably before and after, with brief reproduction steps, expected/actual behavior and annotations that point out the relevant detail.
- Flowcharts and Mermaid diagrams cannot substitute for screenshots or recordings of visible behavior. Use diagrams for architectural reasoning when actual screenshots cannot illustrate the point. Changes with no useful observable behavior do not need screenshot or video evidence.
- Use a small public-safe example and check for private designs, paths, account details or other sensitive content before sharing. Attach media to the issue/PR or link to an accessible recording; do not commit generated screenshots or videos just to provide review evidence.
- Throughout the work and before handoff, check the relevant PR's merge status. Don't push to
an open PR only to catch up with
main(no merge ofmain, no Update branch, no rebase for that alone): every push restarts the whole CI run, andmain's own run catches what lands in between, to be fixed forward. When you push a change anyway, or GitHub reports a conflict, rebase onto the latestmain(push your own branch with--force-with-lease); never mergemaininto a PR. Resolve conflicts without discarding others' work; never force-pushmain. Don't re-run CI on an unchanged commit: a real failure fails again. Re-run only a job that runner trouble cancelled, with "Re-run failed jobs". Report the PR state you checked and any conflicts resolved. If a PR remains open, keep monitoring it while the task is active and make its pending status clear at handoff; do not claim it merged without checking.
Before you start: look at what is already open
- Work with an authenticated GitHub CLI (
gh auth status) andgit; the checks below need both. - Pull the whole list, not one search:
gh pr list -R tangency-labs/solidcraft --state open --limit 500(drafts included) andgh issue list -R tangency-labs/solidcraft --state open --limit 500. Look for work on the same issue, the same feature under another number, and PRs that change the files you are about to change (gh pr list ... --json number,title,files). - If someone already has it, comment on their PR or issue instead of opening a second one. Two PRs for one change can't both land, and one of them is wasted work and CI.
Claim = a draft PR
- Before working on issue #N, check nobody has it:
gh pr list -R tangency-labs/solidcraft --state open --search "#N". - If none, branch from the latest
origin/main,git commit --allow-empty -m "claim: #N", push, and open a draft PR titled<summary> (#N)right away. The lowest-numbered open PR for an issue wins; if yours lost, close it. Opening the PR is the claim: the bot assigns you and labels the issuein progress(or says on your PR who holds it). Reference#Nin the PR title so the bot can find it. Don't claim by editing files; comment/claimon the issue only to stake a claim before you have a branch. - Push work in progress at least daily. A draft with no pushes for 72 hours may be taken over: comment on it first, then open your own claim (you may start from its branch). This takeover policy is separate from the bot's automatic cleanup deadlines in CONTRIBUTING.md.
- On a shared build machine, check the load before a big build (
cut -d' ' -f1 /proc/loadavg) and wait while it is over 24; build withnice.
Design file format
A change that saves something new in a design adds ONE file, crates/doc/src/format/pending/<name>.rs
(a //! note, and pub fn step if older designs must be rewritten). Never edit FORMAT,
JSON_STEPS, the history in format.rs, another change's file or a v<N>/ folder: the build
works out the number (the next one while anything is pending), and the release folds pending
changes into v<N>/ with scripts/fold-format-pending.sh. See CONTRIBUTING.md. Drawings work the same
way with their own numbers: one file in crates/doc/src/drawing/format/pending/.
Application releases
Development pushes are not application releases. Follow docs/releasing.md when asked to
prepare or ship a release: choose the version from the actual changes, update Cargo.toml and
Cargo.lock, pass the quality gates, advance release without force-pushing, and verify the
resulting draft and its artifacts. When shipping is authorized, publish that verified draft
and confirm its tag and downstream deployment. Do not auto-release every push to main, infer
version bumps solely from commit prefixes, overwrite published versions, or push release tags
before the draft is verified.
Running and looking at the app
cargo run --release -p solidcraft -- --sample --control PORT(sample design + control channel). Pick a free port. Without a display, run it underXvfb :99withDISPLAY=:99.- Drive it with JSON lines on
127.0.0.1:PORT(seedocs/control-protocol.md). The first request on a connection carries the launch's token as"token": read it from~/.local/share/solidcraft/control/PORT.token, or start the app withSOLIDCRAFT_CONTROL_TOKEN=$(openssl rand -hex 32)and send that.{"id":1,"method":"engine.execute","params":{"command":"solid.extrude","params":{"distance":20}}}{"id":2,"method":"ui.start","params":{"command":"sketch.create"}}thenui.click {x, y}{"id":3,"method":"ui.screenshot","params":{"path":"/tmp/shot.png"}}then read the PNG.
- For UI work, look at the result (screenshot, read the PNG). Without a window use
ui.renderorsolidcraft-cli snapshot. - Headless:
solidcraft-cli run script.json --out part.step,solidcraft-cli eval design.solidcraft,solidcraft-cli snapshot script.json --out shot.png,solidcraft-cli commands. - Reference tests:
cargo xtask oraclereplaystests/oracle/*/recipe.jsonand compares with each case'sexpected.json(analytic or FreeCAD values; writesdocs/oracle.md). Expected values never come from a commercial CAD product. - Build with
CARGO_TARGET_DIR=<repo>/target. Windows:cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft.
Roadmap
ROADMAP.md (committed) tracks status, milestones and estimates. Update it whenever a
milestone task lands. docs/features.md (SolidCraft's commands by area, from the registry) and
THIRD-PARTY-LICENSES.txt are regenerated on main after each merge by the Generated files
workflow; never regenerate them in a PR.
Lists many PRs add to
Keep them conflict-free (CONTRIBUTING.md, "Lists many changes add to"): message catalogs sorted
(cargo xtask lists --fix), mod lines in their sorted group, the language list English first
then by id, generated files left to main, and a design-format change as one new file.