SolidCraft

SolidCraft is an open-source parametric 3D CAD application written in pure Rust. Sketch on a plane, constrain and dimension the sketch, turn profiles into solids with features on a timeline, and change a parameter to watch the whole timeline rebuild.

It runs as:

• a desktop app for Windows and Linux (egui + wgpu);
• a web app in the browser (wasm, WebGPU or WebGL2), try it here;
• a headless CLI, solidcraft-cli, that runs command scripts, measures and exports;
• an MCP server that AI agents model with, headless or driving the running app.

Everything the user can do is a command with JSON parameters. The toolbar, the dialogs, scripts, the CLI, the control channel and MCP all run the same commands, so anything you can click you can also script, test or hand to an agent.

SolidCraft is early. Sketching, solid modelling, parameters, components with joints, sheet metal and a plastic-enclosure subset work; surfaces, drawings, CAM and simulation are deferred. The roadmap has the details, and the feature list lists every command by area, and the reference tests check modelling results against analytic and FreeCAD values.

Existing .solidcraft designs and solidcraft-cli commands keep their names and behavior.

This book has two halves: the user guide for people modelling with SolidCraft, and the developer guide for people working on it. The command reference is generated from the code on every build.

SolidCraft is licensed MIT OR Apache-2.0. It is independent: behaviour is designed from public documentation, general CAD conventions and user feedback, and reference tests use analytic values and open-source tools. SolidCraft is not affiliated with Autodesk, Dassault Systèmes, PTC or any other CAD vendor; product names such as Fusion, SolidWorks and Onshape are trademarks of their respective owners, named only to describe compatibility.

Getting started

The desktop executable is solidcraft, the CLI is solidcraft-cli, and designs are saved as .solidcraft. Designs, settings and setups from builds released under the previous product name keep working (see the compatibility notes).

Desktop

Download the installer for your system from the Download section of the README or the releases page, or build it yourself with stable Rust (1.95 or newer):

git clone https://github.com/bherbruck/solidcraft && cd solidcraft
cargo run --release -p solidcraft -- --sample   # opens with a sample part

solidcraft part.step opens a STEP, IGES, 3MF, STL or OBJ file as a new design, and solidcraft design.solidcraft opens a saved design. Windows builds cross-compile from Linux with cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft.

macOS

Open the release .dmg and drag SolidCraft.app onto Applications.

The macOS build is signed ad-hoc and not notarized, so macOS blocks the first launch with “SolidCraft can’t be opened, because Apple can’t verify if the app is vulnerable”. Open System Settings › Privacy & Security, scroll down to the message about SolidCraft, click Open Anyway and confirm: the app opens normally from then on. From a terminal, remove the quarantine flag instead:

xattr -dr com.apple.quarantine /Applications/SolidCraft.app

When updating from a build released under the previous product name, follow the macOS upgrade notes so you replace it rather than install a second copy.

Linux AppImage

The first time you open the AppImage it adds a menu entry and icons under ~/.local/share (applications/ai.storyteller.solidcraft.desktop, icons/hicolor), so the desktop shows the right name and icon. It adds nothing if appimaged already made an entry for the file, or if a launcher such as Gear Lever or AppImageLauncher started it (and removes the entry SolidCraft added before). To turn it off for good, create an empty file ~/.local/share/solidcraft/no-desktop-integration, or start the AppImage with SOLIDCRAFT_NO_DESKTOP_INTEGRATION=1.

If the AppImage doesn’t start and prints a FUSE message followed by execv error: No such file or directory, AppImageLauncher 2.x is intercepting it: it can’t start AppImages built on the static runtime, as SolidCraft’s is. Update AppImageLauncher to 3.0 (so far only published as betas; 3.0.0-beta-3 or newer works), or remove it.

Linux Flatpak

Install Flatpak using your distribution’s package manager. For an installation that receives updates, add Flathub for the required Freedesktop runtime and the SolidCraft application feed to the same user installation:

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak remote-add --user --if-not-exists solidcraft https://docs.solidcraft.io/flatpak/solidcraft.flatpakrepo
flatpak install --user solidcraft ai.storyteller.solidcraft
flatpak run ai.storyteller.solidcraft

A SolidCraft remote added before the project moved to docs.solidcraft.io (from bherbruck.github.io) no longer finds updates. Point it at the new address, then update: flatpak remote-modify --user --url=https://docs.solidcraft.io/flatpak/repo/ solidcraft and flatpak update --user.

Releases up to 0.7 used the application ID ai.storyteller.solvecraft. If you installed one of those from the SolidCraft remote, flatpak update --user reports it as end-of-life and offers to replace it with ai.storyteller.solidcraft; accept, and your settings and autosaves move with it. If you installed a .flatpak bundle, install the new bundle, launch it once (it copies your settings), then run flatpak uninstall --user ai.storyteller.solvecraft (see the compatibility notes).

Alternatively, download the release’s .flatpak file for your architecture and run flatpak install --user ./solidcraft-VERSION-linux-ARCH.flatpak. The bundle supplies the Flathub runtime repository address; installation still needs internet access to fetch any missing runtime. Launch with flatpak run ai.storyteller.solidcraft, rather than looking for a host solidcraft binary. Files chosen through Open/Save use the desktop file-chooser portal; command-line paths outside Documents may need a specific additional filesystem permission.

Linux Snap

On Ubuntu and other distributions with snapd:

sudo snap install solidcraft
solidcraft                # or open SolidCraft from the app menu
solidcraft.cli --version  # the CLI, for scripts and `solidcraft.cli mcp`

The snap can open designs in your home folder (not hidden folders) and, through the file chooser, anywhere else. For USB drives and other mounted disks, run sudo snap connect solidcraft:removable-media once. A release’s .snap file installs without the store with sudo snap install --dangerous ./solidcraft-VERSION-linux-ARCH.snap; it then doesn’t update automatically.

Web

The same app runs in the browser: open SolidCraft on the web (?sample opens the sample part, ?webgl forces WebGL2 where WebGPU is missing or misbehaves; the browser remembers it until ?webgpu, and an app installed from Chrome or Edge starts with it too). Designs are saved in the browser’s private file storage, which needs HTTPS or localhost. Planned worker and tiered-storage integration is described in web-runtime.md (design; not yet wired in the shipped wasm build).

After the first visit the web app works offline: the browser keeps a copy of it. Online, each launch gets the latest published build (the browser downloads it once when it changes); offline, when the network doesn’t answer within a few seconds, or when a new build can’t be downloaded whole, the kept copy starts (and the download carries on for the next launch).

Browsers that can install web apps add Install app… to the File menu: it installs SolidCraft as an app with its own window and launcher icon, working offline like the page. In Chrome, Edge and other Chromium browsers it shows the browser’s install prompt, and once SolidCraft is installed the item is gone. Safari has no such prompt, so the item shows its steps instead: Share › Add to Home Screen on iPhone and iPad, File › Add to Dock on a Mac (Safari 17 or later).

To build it yourself:

rustup target add wasm32-unknown-unknown
cd apps/solidcraft-web && trunk serve --release --no-autoreload

Offline use needs --no-autoreload: Trunk’s live reload changes the page as it serves it, so it no longer matches the build the browser would keep. Debug builds (trunk serve) never keep a copy.

Design links and embeds

Use ?open=<encoded HTTPS URL> to open a hosted .solidcraft design as an unsaved copy, including its history, constraints, and joints. Encode the URL with encodeURIComponent when it contains query parameters. The host must allow CORS requests from the app’s origin. Downloads, including redirected URLs, must use HTTPS or stay on the app’s own origin, and fit within the File > Open design size limit. Failed downloads and invalid designs show an error and leave the empty design.

For self-hosting, ?open=/dutchman/jobs/abc/part.solidcraft resolves against the page’s origin, using its scheme and port, including plain HTTP on a LAN. A full URL on that same origin is also accepted; other absolute URLs still require HTTPS. For example, expose a reverse-proxy service in Compose, routing / to solidcraft:8080 and /dutchman/ to a converter service. The converter can link to /?open=/dutchman/jobs/abc/part.solidcraft without a separate origin or CORS setup. Paths must start with one /; protocol-relative paths (//), backslashes, control characters, and decoded .. segments are refused. Redirects must end at HTTPS or the page’s own origin. Embed mode and Open in SolidCraft preserve the path.

Add embed to show the viewport, timeline, browser tree, and joint controls without the ribbon, file menus, or start page:

<iframe src="https://docs.solidcraft.io/app/?embed&open=https://example.org/arm.solidcraft"
        width="960" height="540" title="Arm design"></iframe>

Embedded designs do not save designs, preferences, or recovery copies to browser storage and do not ask before unloading. Open in SolidCraft opens the same link in the full app in a new tab. ?embed without open keeps the normal app layout.

Self-hosting with Docker

The web app is also a container image, ghcr.io/tangency-labs/solidcraft-web, for Linux on x86_64 and ARM64: latest is the latest release, 0.14.0 or 0.14 a release, edge the newest main. It serves the app with nginx on port 8080 and keeps nothing on the server: designs stay in each visitor’s browser.

docker run -d --name solidcraft -p 8080:8080 --restart unless-stopped ghcr.io/tangency-labs/solidcraft-web:latest

Or with Docker Compose, using packaging/docker/compose.yaml (SOLIDCRAFT_PORT picks another port):

docker compose -f packaging/docker/compose.yaml up -d      # start
docker compose -f packaging/docker/compose.yaml pull && docker compose -f packaging/docker/compose.yaml up -d   # update
docker compose -f packaging/docker/compose.yaml up -d --build   # build the image from your checkout instead

Then open http://localhost:8080/. On another machine the browser only saves designs over HTTPS, so put a reverse proxy with a certificate in front (Caddy, Traefik, nginx); the app works under any URL path, such as https://example.com/cad/. To build the image without Compose, from the repository root: docker build -f packaging/docker/Dockerfile -t solidcraft-web .

3D mouse in the browser

The web app reads a 3Dconnexion SpaceMouse or SpaceNavigator through the browser’s Gamepad API, with the same switch and speed in Preferences › Navigation as the desktop app. Edge and Chrome read the device as it is. A browser shows a gamepad to a page only once it has been moved there, so if nothing happens at first, push the cap firmly once. 3DxWare also turns the cap into mouse-wheel zoom in browsers; while the cap moves, the web app ignores the wheel and reads the cap itself. Before the browser shows the cap to the page, that zoom still gets through, so the first push after opening the page may zoom a little.

Firefox doesn’t list 3D mice (Mozilla bug 1226575). On Windows it does list 3DxWare’s virtual joystick, which can carry the cap instead. Save this as %APPDATA%\3Dconnexion\3DxWare\Cfg\Firefox.xml, then restart Firefox (and 3DxWare, if the cap still only zooms). It changes Firefox only: there 3DxWare sends the cap’s six axes to the joystick instead of the mouse wheel. Delete the file to undo it.

<?xml version="1.0" encoding="UTF-8"?>
<AppCfg Default="false" xmlns="" CfgFormatVersion="1.3" ThisFileVersion="1.1">
  <AppInfo>
    <Signature>
      <Name>STR_FIREFOX</Name>
      <ExecutableName>FIREFOX.EXE</ExecutableName>
      <Transport>KMJ</Transport>
    </Signature>
    <Options/>
  </AppInfo>
  <CfgProperties>
    <ID>ID_STR_FIREFOX</ID>
    <Name>STR_FIREFOX</Name>
    <InheritsFromID>ID_STR_FIREFOX</InheritsFromID>
  </CfgProperties>
  <Devices>
    <Device>
      <ID>ID_Standard_3D_Mouse</ID>
      <AxisBank>
        <Name>STR_DEFAULT_BANK</Name>
        <ID>Default</ID>
        <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_X</ActionID><Min>-512</Min><Max>511</Max><Deadband>0</Deadband></Input><Output><ActionID>HIDJoystick_X</ActionID></Output></Axis>
        <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Y</ActionID><Min>-512</Min><Max>511</Max><Deadband>0</Deadband></Input><Output><ActionID>HIDJoystick_Y</ActionID></Output></Axis>
        <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Z</ActionID><Min>-512</Min><Max>511</Max><Deadband>0</Deadband></Input><Output><ActionID>HIDJoystick_Z</ActionID></Output></Axis>
        <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Rx</ActionID><Min>-512</Min><Max>511</Max><Deadband>0</Deadband></Input><Output><ActionID>HIDJoystick_Rx</ActionID></Output></Axis>
        <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Ry</ActionID><Min>-512</Min><Max>511</Max><Deadband>0</Deadband></Input><Output><ActionID>HIDJoystick_Ry</ActionID></Output></Axis>
        <Axis><Enabled>true</Enabled><Input><ActionID>HIDMultiAxis_Rz</ActionID><Min>-512</Min><Max>511</Max><Deadband>0</Deadband></Input><Output><ActionID>HIDJoystick_Rz</ActionID></Output></Axis>
      </AxisBank>
    </Device>
  </Devices>
</AppCfg>

CLI

solidcraft-cli runs the same commands without a window:

cargo run --release -p solidcraft-cli -- commands                       # every command, as JSON
cargo run --release -p solidcraft-cli -- run examples/bracket.json --out bracket.step
cargo run --release -p solidcraft-cli -- eval examples/bracket.json     # volume, area, faces…
cargo run --release -p solidcraft-cli -- snapshot examples/bracket.json --out bracket.png
cargo run --release -p solidcraft-cli -- exec solid.box '{"length": 20, "width": 10, "height": 5}'
cargo run --release -p solidcraft-cli -- run mechanism.json --in arm.solidcraft  # with a motion.export_animation step: a GIF

A script is a list of commands:

{"commands": [
  {"command": "sketch.create", "params": {"plane": "XY"}},
  {"command": "sketch.rectangle.two_point", "params": {"p0": [0, 0], "p1": [40, 30]}},
  {"command": "sketch.finish", "params": {}},
  {"command": "solid.extrude", "params": {"distance": 20}},
  {"command": "solid.fillet", "params": {"edges": [[0, 0, 10]], "radius": 3}}
]}

snapshot looks at the model from the iso view. --view NAME takes another standard view (front, back, top, bottom, left, right) or the name of a view saved in the design with view.save. --camera JSON takes any camera, as the MCP screenshot tool does (its conventions are in the MCP page). A script that applies a view itself with view.apply sets the camera too. The ground grid lies on Z 0, so it cuts through a part that straddles it: --no-grid leaves it out of the picture, and --no-axes the origin’s axes. The picture is drawn on the GPU with the viewport’s own pipelines, so it shows what the window would (a surface analysis such as inspect.zebra included); a machine without a GPU uses a software one (Mesa’s lavapipe on Linux, WARP on Windows), and with neither (a Mac without usable Metal, a Linux box without Mesa’s Vulkan) the CPU rasterizer draws it, without surface analysis colours, and the reply’s renderer says cpu with a warning. SOLIDCRAFT_GPU=auto|hardware|software|cpu chooses (hardware and software fail rather than fall to the CPU), and solidcraft-cli gpu lists the adapters and the tier a snapshot would use.

solidcraft-cli snapshot part.solidcraft --out photo.png --view Photo
solidcraft-cli snapshot part.solidcraft --out close-up.png --no-grid --no-axes --camera '{"target": [30, -20, 0], "yaw": 0.6, "pitch": 0.25, "distance": 60}'

Seeing what a cut or a join is about to do

A picture answers in a glance what a volume cannot: does the tool body reach through the material, and is it where you meant it to be? --body NAME:opacity=0.3 draws that body see-through, so whatever is inside it shows; --body NAME:color=#cc3333 gives it a colour. Either key on its own keeps what the design says about the other, and the option is a shortcut for appearance.assign, the command the Appearance dialog runs — the picture is the one the window would show with the same appearance assigned.

--tool NAME is the common case in one option: that body solid in the tool colour, every other body see-through around it. --section z=27 cuts the model at a plane so the inside shows, as inspect.section does: an axis and the world coordinate to cut at, ,flip to keep the other side, XY, XZ or YZ for a plane through the origin, or the command’s own JSON.

# The pin the cut would remove, inside the plate it stops 6 mm short of.
solidcraft-cli snapshot plate.solidcraft --out preview.png --tool Pin
solidcraft-cli snapshot plate.solidcraft --out cut.png --tool Pin --section z=12
solidcraft-cli snapshot plate.solidcraft --out glass.png --body "Plate:opacity=0.25" --body "Pin:color=#1a7f4b"

A body drawn see-through is drawn see-through everywhere a picture is drawn, not only here: an appearance with an opacity below 1 (Glass - Clear in the library, or any opacity you assign) now reads as glass in snapshot, in MCP screenshots and in a design’s thumbnail, as it always has in the window. A face painted with a see-through look of its own still draws at its body’s opacity.

Windows PowerShell 5.1 drops the double quotes inside an argument it passes to a program: write them as \" there.

A command that fails stops the script. A feature can also fail later, when a parameter change rebuilds it; run then exits with status 1, lists the failing features and writes none of its --out and --save files, because the bodies lack what those features should have made. --allow-errors writes them anyway.

run prints each command’s result with --results (otherwise the measurement), and eval prints the measurement, as JSON on stdout. --json-out FILE writes that JSON to a file instead. The file is plain UTF-8, which is not what a redirect gives you everywhere: Windows PowerShell’s > re-encodes a program’s output, as UTF-16 or as UTF-8 with a byte-order mark depending on its settings, and strict JSON readers such as Python’s json.load then refuse it.

cargo run --release -p solidcraft-cli -- run examples/bracket.json --results --json-out results.json
cargo run --release -p solidcraft-cli -- eval examples/bracket.json --json-out measures.json

To find the slow steps of a script, --timings prints how long each command took instead of the measurement: {"timings": [{"index", "command", "ms"}], "total_ms"}, with index counted from 0. --profile adds each command’s profile: {"boolean_ms", "tessellate_ms", "other_ms"}, its wall time in the kernel’s booleans, in tessellation and in everything else. With --results as well, the results go in the same object as results; --results alone still prints a plain array.

cargo run --release -p solidcraft-cli -- run examples/bracket.json --profile

A design’s history turns into a script that rebuilds it, which makes a bug that only shows on one design a one-file reproduction:

cargo run --release -p solidcraft-cli -- script part.solidcraft --out repro.json
cargo run --release -p solidcraft-cli -- eval repro.json               # the same part

The script starts with the user parameters (parameters.add) and the design’s units, sheet metal and plastic rules and materials, then adds each timeline feature with timeline.add, exactly as the design file holds it: same ids, names and parameter names, so later steps still find the sketches and bodies they use, and a feature that failed in the design fails the same way. Edit a step’s values to try a change, or delete the steps after a feature to see the design as it was there. Appearances, folders, named views and configurations are left out (the CLI notes which), and designs with components or joints are not supported yet. In the app and over MCP the same script comes from timeline.export_script.

Units are millimetres and degrees unless an expression says otherwise ("1 in", "30 deg"), and Z is up.

Name and compatibility

SolidCraft was renamed from an earlier working name. Since 0.5.0 everything uses the new name: the solidcraft and solidcraft-cli programs, .solidcraft designs, SOLIDCRAFT_* environment variables, settings folders and the solidcraft MCP server. Upgrading keeps working: designs, settings, recovery files, environment variables and CLI/MCP setups from earlier builds carry over. Every compatibility shim is listed in the compatibility notes.

Use the SolidCraft documentation and web-app URLs. GitHub redirects links to the renamed repository; old-name Pages and Flatpak URLs are not maintained as permanent aliases.

A tour of the window

• Title bar. On Windows and Linux the application bar is the window’s title bar. On the left: the File menu (New, Open, Save, Save As, Export…), undo and redo, the Home tab (the start page) and one tab per open design (each with its own undo history, selection and camera; a dot marks unsaved changes). On the right: Report a bug, Help (?), Preferences (which hold the theme) and the window’s buttons.

• Toolbar. The workspace switcher (DESIGN) sits on the left. The tabs (MODEL, SURFACE, ASSEMBLE, INSERT, INSPECT, MANAGE, VIEW and SHEET METAL) hold sections of commands. SKETCH appears while editing a sketch; SHEET METAL is always there and is highlighted for the active sheet body. Both select automatically when entered, and the other tabs remain available. Click a panel’s name for all its commands. Drag a command from the dropdown onto a panel’s label or empty space to append it; the insertion line shows its destination. Drop onto an existing button to insert before it. Buttons can also move between panels, and the layout is saved.

• Browser (left). The design as a tree: document settings and units, named views, the origin, bodies, sketches, construction planes, canvases, joints and components. The eye shows or hides an item, a component’s radio button makes it the active component, and right-clicking any row gives that item’s menu. Right-click the design or a component and choose Expand All or Collapse All to open or close every folder under that row (the design row stays visible when the whole tree is collapsed). Rows drag into groups and other components.

• Viewport. Click to select, Shift or Ctrl to add (Preferences › Selection), drag for a window or crossing box. While sketching, Ctrl/Cmd or Alt/Option suppress auto-snap by default; Shift prefers a midpoint; the pointer also snaps to where two curves cross. To reach something under something else (two lines drawn on top of each other, coincident points, an edge in front of a face, overlapping bodies), hold the left button still for half a second (long-press on a touch screen) or right-click › Select Other…: a list of everything under the cursor opens there, the sketch being edited first. Hovering a row lights it up; clicking it selects it (Shift or Ctrl adds), and in a command’s dialog it goes to the active selection box. Esc or a click elsewhere closes the list. Clicking again on the same spot, with nothing changed in between, selects the next thing in that list. The wheel zooms at the cursor, the middle button pans and right-drag orbits freely (the mouse preset in Preferences switches to SolidWorks, Inventor, Alias, Blender, Tinkercad, OpenSCAD or Touchpad style). On a trackpad, pinch zooms and two-finger scroll pans (Navigation › Two-finger scroll pans; off: scroll zooms like the wheel); mouse wheels zoom and the thumb wheel pans sideways. With the Fusion preset and two-finger pan enabled, hold Shift while scrolling with two fingers to orbit freely instead of panning. No click is needed. Releasing Shift returns to panning, even during the same gesture. Shift does not snap this gesture to standard views; orbit gestures do nothing on flat 2D pages. Other presets keep their existing scroll behaviour. Shift+middle orbits freely in the default and Inventor presets. In every preset, Ctrl+left drag (Cmd on macOS) that starts on empty space orbits; a Ctrl+click still adds to the selection. Shift+right-drag snaps to the nearest standard or diagonal view; Shift does not request snapping when the preset already requires it to orbit.

  Enable Preferences → Navigation → Free orbit to rotate the mouse and 3D mouse continuously through both poles, preserving roll. During an orbit drag, Shift snaps the view direction and the picture rotation to the nearest quarter turn; releasing Shift resumes the unsnapped rotation. Free orbit defaults to off for every mouse preset. With SolidWorks navigation, right-click a planar face and choose Normal to Selection to use Look At (also Ctrl+8); repeat to flip the side, preserving scale and projection.

  Mouse gestures (Preferences › Navigation, off by default) work with the SolidWorks mouse preset only (the wheel orbits, Ctrl + wheel pans) and take over the right button, which then no longer orbits: hold it and move the pointer 4 pt to open a ring of tools (280 pt inside, 350 pt outside), even while a tool is active, and touch a tool’s zone to take it. A right-click that does not move still opens the usual context menu. Each studio has its own tools, and Customize… sets how many tools a studio’s ring holds and in which place. Zones alternate between two tints, three when the number of tools is odd. The optional radial context menu is a separate setting, and gestures take the right button from it while they are on.

  With Touchpad selected in Preferences › Navigation, hold Shift and move the pointer to pan, or hold Alt (Option on macOS) and move it to orbit—no mouse button is needed. Vertical two-finger scrolling zooms in this preset, regardless of the saved two-finger pan setting; switching presets restores that setting. Release the modifier to stop navigating. Shift+click and Shift+left-drag still select. Combined Shift+Alt or Ctrl/Cmd modifiers do not start pointer-only navigation. The axis view shows the world’s X/Y/Z directions in SolidCraft’s colors. Click a signed axis tip to look along that axis; click the aligned tip again to look from the opposite side. Drag the axis view to orbit around the view centre, with Shift for snapping. Top and bottom keep the nearest quarter-turn heading. The house, the navigation bar’s Home button and a middle-button double-click in the view go home, framing what is shown now (Navigation › Middle double-click can make it Fit, which keeps the orientation, or turn it off). Interface › OK and Cancel in the view’s corner puts a large check and cross at the view’s top right while a dialog or a sketch is open, and moves the axis view or cube down below them. With a dialog open they do what its OK and Cancel do (the check is grey whenever OK is); in a sketch without a dialog they are Finish Sketch and Cancel Sketch. Right-click for the marking menu: eight commands around the cursor, plus a menu for whatever is under it. Near the window’s bottom or right edge a menu opens above or to the left of the cursor, so it stays in view. Shaded views omit certified smooth joins between spline spans on extruded walls. Real creases, cap outlines and authored face splits remain visible. Wireframe retains its edge presentation, and hiding a join does not remove its CAD identity or change the exported solid. Unsupported or uncertain wall geometry keeps its existing edge presentation.

• Dialogs dock on the right with a live preview. Most features also show drag handles and a value box in the viewport. Preferences › Interface › Dialogs › In the left column opens them in the browser’s place instead (and the History’s, when it is at the left), at least as wide as that column; the column comes back as it was when the dialog closes. Interface › Dialog buttons › Top puts OK, Cancel and Apply in the dialog’s title row, right of the title, where they stay while sections open and close; Cancel then also takes the place of the close button. Enter and Esc work as before.

• Timeline (bottom). Every feature in order. Double-click to edit, drag the marker to roll back, and drag features to reorder them. Preferences can put the timeline vertically at the far left of the viewport, beside the browser. Its seam handle switches between icon chips and compact feature names; the browser can collapse to a rail beside either width. Previous, Play and Next sit at the top. Double-click Previous to roll to the start. Interface › Sketches › Under their feature lists a sketch in the vertical timeline one level in, under the first feature built from it, behind that feature’s fold arrow. Dragging the feature takes its sketch along. A later feature built from the same sketch gets a row that selects it, and while the marker sits between a sketch and its feature, or the two are in different folders, the sketch keeps a row of its own. The timeline along the bottom always lists features in creation order.

• Command search (S). Click the ribbon search field or press S to open the search popup below it. Results group commands by their ribbon path and show matching features and user parameters from this design. With an empty query, recent commands appear first, followed by pinned commands in the Commands group. Up/Down choose, Enter runs, Tab fills the selected name, and Esc closes. A feature opens its existing editor; a parameter opens Change Parameters filtered to its name. To run with explicit values, enter an id and JSON object, for example solid.extrude {"distance": 20}. The popup validates JSON as you type and shows parser errors. Shift+Enter runs it and keeps the popup open. Right-click a command for its existing pin and toolbar actions.

Preferences (File › Preferences) hold the theme, workspace layout, the units of new designs, the mouse preset, the visual style and autosave. Graphics › Colour vision gives the colours that carry a meaning (sketch states, axes, bends, analyses, icons) values for a weak red, green or blue sense: Protan, Deutan or Tritan. In a mode, the faces Draft and Accessibility Analysis mark as failing are striped too. Command messages and errors show for a few seconds in the status chip at the bottom left of the view. Click the chip, or choose Help › Messages…, for every message of the session: newest first, errors in red, each line selectable, with Copy all for a bug report. Help › Keyboard Shortcuts lists every key, and File › Keyboard Shortcuts changes them.

Workspace layout

General › Workspace layout switches between Floating cards and Compact panels. Compact joins the workspace selector and ribbon into one top bar, puts Browser flush underneath with a square join, and docks tool sheets below the compass. Tool sheets remain draggable: their four corners round away from the right edge, and their two right corners square when docked there. Browser keeps only the height its contents need. Assistant remains on the outside edge, and History keeps its chosen bottom, left or shared Browser column. The choice is saved between launches. Switching preserves the current tool, camera, selection and design; Cancel and Restore Defaults work like other preferences.

General › Show text under ribbon icons is a separate, saved option for either layout. Turn it off for shorter icon-only command buttons; tooltips, section names and command menus remain available.

Interface › Layout › Show origin and bodies at the top (off by default) puts the active component’s Bodies folder and the Origin (planes, axes and point) at the top of the History when it sits on the left or under the browser and is wide enough for names. They are the browser’s own rows: the same eyes, folds and right-click menus, so one list is enough for single-part work. The History at the bottom is unchanged.

Colour themes

Interface › Theme lists Dark, Light and System (follows the operating system), the built-in themes and any themes you have imported. A choice applies at once. Under the themes, Viewport draws the 3D view in the Light or Dark theme’s colours whatever the window uses, for example the model on a light view in a dark window (Follow theme, the default, keeps the theme’s own). The built-in themes are Gruvbox (dark and light, each in hard, normal and soft contrast), SolidCraft 95, Platinum 9, Cupertino, Green Phosphor, Amber Phosphor, Blueprint, One Dark, Tokyo Night, Solarized Light, Nord, High Contrast, Graphite, Nosferatu, Catppuccin Mocha, Okibi and Akari (dark and light, from the Okibi design system), Clay and Clay Dark (warm ivory paper and warm charcoal, with a terracotta accent and rounded corners), and 1-bit and 1-bit Dark (pure black and white with square corners: black on white, or white on black, with selections drawn inverted).

A theme is a small JSON file that starts from the Dark or Light palette and changes any of its colours and corner radii by name:

{
  "format": "solidcraft-theme/1",
  "name": "My Theme",
  "base": "dark",
  "colors": {
    "panel": "#282828",
    "text": "#ebdbb2",
    "accent": "#83a598",
    "viewport_top": "#32302f",
    "viewport_bottom": "#32302f",
    "axis_x": "#fb4934",
    "axis_y": "#b8bb26",
    "axis_z": "#83a598"
  },
  "radii": {
    "radius_sm": 2,
    "radius_md": 4,
    "radius_lg": 6,
    "radius_xl": 8,
    "control_radius": 4,
    "sketch_mode_radius": 4
  }
}

Colours are #rrggbb, or #rrggbbaa for translucent ones. A few colours, such as the four Continuity Analysis seams (continuity), take a list. Any colour the file leaves out keeps the base palette’s value. axis_x, axis_y and axis_z colour every X, Y and Z axis: the origin, the view triad, the navigation cube and the Move gizmo. A file from an earlier version may set triad or gizmo instead; it still reads, and those colours now go to every axis.

radii is optional. Its six keys above accept integers from 0 to 32 in logical UI points; zero makes square corners. Omitted keys keep today’s base values: 4, 6, 8, 10, 6 and 7, respectively. The first four style small accents through large surfaces; control_radius styles form controls, and sketch_mode_radius styles sketch creation buttons. Themes own these settings, with matching shapes across light and dark variants. Dock joins remain square, circular controls remain circular, and control sizes and spacing stay the same. Platinum 9, 1-bit, 1-bit Dark, and the phosphor themes use square corners, SolidCraft 95 uses subtle 3-point corners, Blueprint uses the standard radii, Cupertino uses softer corners, and Clay and Clay Dark use rounded corners. Other built-in themes retain the defaults.

Tab accents also have separate fill, small-text ink and tint keys. Sketch uses sketch_accent, sketch_ink, sketch_soft; Surface, Mesh, Sheet Metal and Render use <tab>_fill, <tab>_ink, <tab>_soft (sheet for Sheet Metal). Form uses form_fill, form_tab_ink, form_soft because form_ink names the general form text. Model keeps accent, selected_ink, accent_soft. The older surface_accent, mesh_accent, form_accent and render_accent keys retain their existing roles and values. tab_on_fill_dark is the dark text fallback for tab pills when on_accent has less than 4.5:1 contrast with the fill. See the per-tab token reference for all pairs.

• Import… adds a theme file and turns it on. Importing a file with the same name again updates that theme. A file with an unknown colour name or a malformed colour is refused, and the message names every problem.
• Export… saves the theme on now as a complete file listing every colour and radius. It is a good starting point for your own theme.
• Remove deletes the selected imported theme.

Retired window-band and procedural icon colours in older exports are discarded on import. Command icons use the shared SVG palette.

Imported themes are kept with your preferences, so they work in the browser app too. Colour vision modes still apply on top of any theme.

Graphics › Frame rate shows frames per second in the view’s bottom-right corner. Click it, or turn on Frame rate details, for the performance overlay:

• a graph of the last few seconds of frames, one bar per frame, with lines at 60 and 30 frames per second. The triangles drawn are a line over it, and a tick at the top marks each frame that rebuilt the scene, so you can see how geometry changes the frame time;
• a histogram of frame times, the 1% low (the mean of the slowest 1% of frames) and the worst frame, which show stutters that an average hides;
• what the GPU drew last frame (triangles, line segments, draw calls), the viewport’s size in pixels with its MSAA and supersampling, the time the interface took, the last scene build and the graphics backend and adapter.

While the readout is on, the view redraws every frame. With vertical sync the frame rate tops out at the display’s refresh rate; the interface time and the GPU counts still show the work.

Navigation › Smooth wheel zoom is on by default. Turn it off to apply each wheel or trackpad event immediately, with no smoothing tail. It is independent of Animate view changes, which controls axis views, Look At, Home and Fit. Re-enabling smoothing during a wheel gesture takes effect after that gesture ends, avoiding leftover zoom being replayed.

Navigation › Alias uses Alias’s camera keys: Shift+Alt+left drag orbits, Shift+Alt+middle drag pans and Shift+Alt+right drag zooms (drag down to move away, up to move closer). Without Shift+Alt, a left drag still selects with a box and drags sketch geometry.

Some Linux desktops take Alt+drag for themselves (moving or resizing windows), so the viewport never sees it. To free it:

• KDE Plasma: System Settings › Window Management › Window Behavior › Window Actions, set Modifier key to Meta (or None).
• GNOME: run gsettings set org.gnome.desktop.wm.preferences mouse-button-modifier '<Super>' (or set Tweaks › Windows › Window Action Key to Super).

Shift-orbit snapping includes 45-degree edge views and isometric corner views, with a lightly damped spring transition and a small boundary margin to prevent flicker.

On desktop, Ctrl/Cmd+Plus (or Equals) enlarges the interface, Ctrl/Cmd+Minus reduces it, and Ctrl/Cmd+0 restores 100%. These shortcuts update the UI scale preference. The UI scale slider in Preferences applies the new layout when released, so it stays still while dragging.

Theme files can also define borders: primary outer outlines, secondary major section rules, tertiary small dividers, container solid preview/card/keycap outlines, and independent control outlines. Each accepts a width from 0 to 4 UI points and a color in hex. Optional primary_inset adds a companion outline inside panel chrome, with a gap from 0 to 12 points. Missing settings keep existing borders. Blueprint uses a single white outer outline, dotted section lines and dark minor dividers. Secondary rules optionally accept pattern: "dotted"; the default is solid. Focus, selection and error outlines retain their semantic colours. See the UI-kit border hierarchy for the schema.

SolidCraft 95 also defines optional borders.bevel: a per-band width and the highlight, light, shadow and dark_shadow colours. The shared UI uses these for raised panels/buttons, recessed fields and reversed pressed-button lighting. Themes that omit this setting keep their existing flat borders.

Theme files may also set icon_palette: opaque colours for SVG display roles, and three-colour pale/medium/strong ramps for Solid, Surface, Mesh, Form, Sketch, constraints and construction. These settings colour the existing command artwork without changing its shapes. Omitted roles keep the default light/dark palette.

Sketching and constraints

A sketch lies on a plane: an origin plane, a construction plane or a planar face. Start one with Create Sketch (sketch.create) and click a plane, or pick a face first. Right-clicking a plane, in the view or on its browser row, offers Create Sketch on that plane too. Finish Sketch returns to the model. Cancel Sketch (sketch.cancel) returns without keeping what changed since the sketch was created or opened for editing: a new sketch is removed, an edited one goes back to how it was, as one step that Undo brings back.

Opening a sketch turns the view to face it. When the sketch ends, the view stays where it is by default. Preferences › Sketch › When a sketch ends changes that: Return to the previous view goes back to the view from before the sketch, and Return unless rotated goes back only when you panned or zoomed the sketch view but didn’t turn it.

In scripts, XY, XZ, YZ and their Top, Front, Right aliases name origin planes. These names are reserved: a construction plane cannot be created with or renamed to one (case-insensitive). If an older design already has a construction plane with such a name, a string argument naming it is ambiguous and is rejected; use the other alias (XY for Top) for the origin plane, the construction feature’s numeric ID to select it, or an explicit {origin: [x,y,z], normal: [x,y,z]} plane. Existing saved references retain their meaning; opening a design does not reinterpret old sketches.

Curves adapt to the current zoom and display scale. Picking and highlighting use the same visible boundary, including small circles at Fit and sketches in rotated components. Profile shading follows those curves while preserving holes. Zooming changes the display without changing sketch geometry, dimensions, or undo history. On short windows or enlarged displays, the Sketch Palette’s options scroll while its constraint status and Finish Sketch button remain visible.

Geometry

Point is available directly on the default Sketch CREATE toolbar. Click it, then click in the sketch to place a point. Existing toolbar customizations are kept; use Reset Toolbar from the toolbar’s context menu to restore the default buttons.

Lines and polylines (L), rectangles (two-point R, three-point, centre), circles (centre C, two-point, three-point, tangent), arcs (three-point, centre, tangent), polygons, slots, ellipses, fit-point and control-point splines, conics, points and text. Construction (X) turns curves into reference geometry that doesn’t form profiles. Modify tools include trim (T), extend, break, fillet, chamfer, offset (O), mirror, patterns, move/copy and scale. With trim on, click a piece to remove it, or press and drag a path across several pieces: the ones it crosses light up and all go when you let go, in one undo step (sketch.trim.path).

Tools with several variants (line and midpoint line; two-point, three-point, centre and rounded rectangle; the circle, arc, slot, polygon and spline variants) share one toolbar button with a drop-down. The button and the family’s shortcut start the variant you picked last, so a shortcut such as L can start a Midpoint Line; pick the variant you want from the drop-down to change it (Keyboard shortcuts).

Once a shape’s first point is down, value boxes (a line’s length and angle, a rectangle’s width and height, a circle’s diameter…) follow the cursor. Typing goes into the first box, Tab moves to the next and Enter places the shape; each typed value becomes a dimension. A value is an expression (25, 1 in, d1 * 2), or width = 20 (also #width = 20), which also adds the user parameter width and dimensions with it, as when placing a dimension. A box that does not become a dimension (a polygon’s sides, a rounded rectangle’s corner radius) takes a value only.

The Sketch Palette’s Construction Geometries option hides construction curves while you work. A hidden construction curve cannot be picked by a click or by a box. Nothing invisible is selectable. The option belongs to one sketch and is saved with the design. Centerlines are a line type of their own and keep showing. Projected geometry that carries the construction line type, such as the trace of a plane, answers to Projected Geometries instead. The option changes display only. Construction curves were already outside every profile.

Polygon tools show their edge outline while positioning the second point, so the orientation can be checked before placement. Inscribed and circumscribed polygons retain their support circle and update the outline when the inline Sides value changes.

Text is set in the built-in font (Liberation Sans) unless it is given another: sketch.text and sketch.edit_text take a font, the family or full name of an installed font (“DejaVu Sans”) or the path of a .ttf / .otf file, and the Edit Text dialog has a Font field for it. An unknown font is an error, and the font is kept with the text in the design, so the text stays editable in it. SOLIDCRAFT_FONT_DIRS adds folders to the ones searched for installed fonts. A text’s height, its angle and each coordinate of its at can be expressions of the design’s parameters, given as strings ("height": "plate_height / 10", "at": ["plate_width / 2", 5]): the text keeps the expression and follows the parameters when they change, and saves it with the design. A number takes the place of an expression, and so does moving the text or dragging its handles (what moves becomes a number; turning a text leaves its height as it was). A string that names no parameter is the number it comes to. The same two commands refuse a text that is not a string, an at that is not two numbers or expressions, a height or angle that is neither (or a height that is not positive) and an expression that cannot be worked out with a message, instead of drawing the text with a default; left out, they keep their defaults.

Right-click a letter’s filled interior or outline and choose Edit Text. You can also start Edit Text first and click the letter. All outlines belonging to that text are highlighted while the dialog is open. A profile bounded by multiple text sources or other geometry cannot identify one text: use Select Other to choose its outline instead. Change the text, font, baseline X/Y, height or angle, then confirm with OK; Cancel keeps the original text. Position and height use the document’s units. The four fields take expressions: one that names a parameter (plate_width / 2) stays an expression, is shown as typed when the dialog is opened again, and keeps the text following the parameter.

To work on the letters’ shapes themselves, right-click the text and choose Explode Text (sketch.break_link with the text’s link). Its outlines stay where they are as ordinary lines, arcs and curves that can be picked, trimmed, dimensioned and extruded one by one; the text itself is gone, so it can no longer be edited as text or follow parameters. Undo brings it back.

A text can follow a curve of its sketch (its Path). That curve becomes construction: the letters stand on it and their descenders cross it, so as a normal curve it would cut them into pieces, and picking the text would pick those pieces. Taking the text off the curve leaves it construction; Normal/Construction turns it back.

Drag a text outline to move all its letters together. Let go to finish in one undo step, or press Esc during the drag to restore the original text. The text stays editable. For an exact displacement, select an outline and choose Move/Copy from its context menu. Enter Distance X, Distance Y and an optional Angle about the text’s baseline; lengths accept document units or explicit units such as 1 in. Enable Create Copy to leave the original in place and create a separately editable text. Cancel leaves the design unchanged. Projected geometry remains protected from ordinary dragging.

Project (P) and Intersect bring model edges into the sketch as linked geometry that follows later changes. Sketching on a face projects its edges automatically. A projected edge stays the edge that was picked, wherever a later change moves it; when that edge no longer exists, the projection keeps its last shape and the sketch says it was lost. For Project, select visible source curves or points from another sketch, model edges, faces, vertices or bodies, or axes and planes, then press P. The entire supported selection is projected in one undo step. A rejected projection keeps the selection for correction; an empty or mixed selection starts the ordinary picking tool. External sketch selections retain their source sketch, even when the active sketch uses the same point or curve names.

A sketch on a construction plane built from the model (through a sketch line, through three points, midway between two faces…) projects, intersects, includes and holds text like a sketch on any other plane, and its links follow when a parameter moves that plane.

Run from a script or the control channel, every command that adds sketch geometry returns the ids of what it added (created: {points, curves, constraints, dimensions}). Ids are stable and never reused within a sketch, even after a delete, so a script can dimension or constrain the new geometry right away.

Extend finds intersections with exact ellipses, rational conics and spline spans. It keeps the original line or circular support and extends only beyond the selected endpoint; conflicting constraints or an ambiguous overlap leave the sketch unchanged.

Closed convex chains of tangent lines and circular arcs support inward offsets that consume a rounded corner. When the offset passes the corner radius, the neighbouring straight supports meet at a sharp corner. The surviving lines and endpoint IDs stay stable; the retired arcs return under their original IDs if a later edit restores their radius. Whole-boundary profile selections follow this transition through save and reopen, so an extruded lip can remain associative. Existing eligible closed analytic offsets upgrade without changing their saved geometry or IDs.

This transition requires a closed convex boundary with tangent junctions and a certified nonempty region. An extinguished arc referenced individually by a constraint or another offset cannot retire. Creating another offset from an already sharp retired boundary also requires breaking its association first. Open, nonconvex and mixed free-form chains keep their existing behavior. Break Offset Association freezes the current boundary, including private arc centres and construction flags, for independent editing.

Offsets of smooth ellipses, conics and splines follow their source after dimension changes, dragging and reopening a design. Their stored cubic spline has a whole-span normal-distance error bound of 0.002 mm. Singular tangents, curvature cusps, possible self-intersections and excessive subdivisions are refused. Offset these curves individually: mixed chain junctions currently require separate geometry. sketch.offset.break releases an offset for independent editing, and undo restores its association. Older independently sampled offsets remain independent. The fit points of such an offset stay hidden, except the two ends of an open one: lines and arcs snap to them and stay coincident with them as the offset follows its source, so the gap between a spline and its offset can be closed into a profile. Smooth open and newly created smooth closed offsets can be offset again, including bounded refinement after a source edit. New closed outputs use a periodic cubic fit with continuous tangent and curvature at the seam. Break Offset Association preserves that interpolation, and its closing point remains joined when dragged. Deleting an output also removes its unused private fit points; deleting a source with a retained dependent is refused.

For explicit closed fit splines, sketch.spline.fit_point accepts periodic: true and at least three distinct cyclic samples. It closes the loop automatically. Existing calls and older saved closed splines retain natural interpolation; older associative closed offsets also retain their saved natural fit. A legacy seam without a unique normal still refuses another offset. Periodic intent is stored on each curve and survives save, reopen and Break. While drawing a fit spline, click its starting point after three distinct samples to close it smoothly. Right-click finishes an ordinary natural fit. Offset accepts both ellipse handles and dense fitted curves; the second click sets the side and distance from the curve.

While drawing in a planar sketch, Construction (X) changes the line type without ending the tool or losing picked points and inline values. The preview and hover feedback keep construction dashes and centerline dash-dot patterns visible. With curves selected, Construction changes those curves as before.

The pointer snaps to existing sketch points, to a line’s midpoint, and to where two curves cross (two lines, a line and a circle or arc, or two circles or arcs). The snap hint shows X. The new point stays on both curves when either one moves. Hold Shift to prefer a line midpoint instead; hold Ctrl/Cmd or Alt/Option (the default suppress chord) to stop snapping for that gesture. Scripts pass "x:<curve>+<curve>:x,y" as a point argument, the same way "mid:<line>" and "on:<curve>:x,y" work.

Enable 3D Sketch in the Sketch Palette to draw lines, fit splines and points off the plane. While placing these points, you can snap to points on other visible sketches. For a bridge line, start Line and click an endpoint on each source sketch; each endpoint uses its source plane, even when that plane differs from the active sketch. These snaps capture positions; they do not create associative links to the source points. New 3D geometry follows its sketch’s component placement, including the selected occurrence and pending position changes. Click a drawn fit point to show its move triad; its arrows move along world X, Y and Z. Scripts also supply world coordinates to sketch.line3d, sketch.spline3d, sketch.point3d and sketch.move3d. Activate the desired occurrence before editing an explicit sketch belonging to a component with multiple placements.

Older drawn or detached 3D wires keep their saved world positions. Included and surface-linked wires with an explicit component marker keep that meaning after the link is broken. Old files whose links became lost after an incorrectly scoped cross-component refresh may require a fresh link once the source is available; their stored point values are preserved on opening.

Constraints and dimensions

Horizontal/Vertical accepts a click on a line or clicks on two distinct sketch points, including the origin, endpoints and circle centres. For two points, it chooses horizontal or vertical alignment from their current positions. Hold Shift near a line’s midpoint to highlight and select it as either point. The midpoint follows both endpoints as the line moves, resizes or rotates. Two line midpoints can also be aligned. Hovering and the first pick are only previews; Esc cancels them without changing the sketch. Accepting the second pick reuses or creates a sketch point with an ordinary Midpoint constraint, then adds the H/V constraint in one undo step. Both constraints can be selected and deleted independently; deleting either keeps the point. After a fillet or chamfer, its Midpoint constraint refers to the original full side, retained as construction geometry, just like a manually constrained midpoint.

Scripts use the same command, with a midpoint reference in the points array:

{"command":"sketch.constraint.horizontal_vertical","params":{"points":[{"midpoint":"l1"},"c1.center"],"mode":"vertical"}}

mode can be horizontal or vertical; omitting it chooses from the current positions.

The solver is SolidCraft’s own (damped Gauss–Newton with degree-of-freedom analysis). Constraints: coincident, horizontal/vertical, parallel, perpendicular, tangent, equal, concentric, collinear, midpoint, symmetry, fix, curvature (G2) and polygon. Sketch Dimension (D) adds linear, aligned, horizontal, vertical, point-to-line, line-to-circle, point-to-circle, circle-to-circle, radius, diameter, arc length and angle dimensions. For an arc’s length, click the arc and then one of its end points. Each is a parameter (d1, d2, …), so it can hold an expression.

Press D, click what you want to measure and type the value: as soon as the click settles the dimension (one line, circle or arc, or the second point or line of a distance or angle), its value box takes the keyboard with the measured value selected, so typing replaces it. Numbers, units (1 in), expressions (2*width) and parameter names all work; letters go into the box, not to tool shortcuts. width = 40 (or #width = 40) defines the user parameter width and dimensions with it, in one step. While you type, the dimension text follows the cursor, and Enter places it there (or in its default place if you haven’t moved the cursor) as one undo step. Esc cancels the dimension.

You can still place the text first. Before you type, a click on empty sketch space puts the text there and keeps the value box focused; a click on another point or line makes the dimension a distance or angle instead; Tab leaves the picks waiting for a click to place the text.

To change a dimension you already have, double-click it, or, with Sketch Dimension on and nothing picked yet, click it once: its value box opens with the value selected, Enter applies, and the tool stays on for the next dimension. The dimension’s text always takes the click; its lines take it only away from sketch points and curves, which still start a new dimension.

Between two points, or on a line, that don’t line up with an axis, where you place the dimension picks what it measures: across from them, the distance between them; above or below them, the horizontal distance; beside them, the vertical distance.

A line and a circle or arc (click the line, then the circle’s edge, or the other way round) measure from the line to the circle’s edge, square to the line: the gap between them, 0 when the circle touches the line. When the line cuts through the circle, the dimension measures how far the edge reaches past the line instead. An arc is measured to the circle it lies on. For the distance to the centre, click the centre point instead of the edge. In scripts: {"command": "sketch.dimension", "params": {"entities": ["l1", "c1"], "value": 5}}.

A point and a circle or arc measure from the point to the circle’s edge, along the radius through the point: 0 puts the point on the circle, and a point inside the circle measures how far within the edge it lies. Two circles or arcs measure between their edges, along the line through their centres: the gap between them (0 when they touch), how far they overlap when they cross, or, when one lies inside the other, the narrowest gap between them (the thinnest part of the wall). For the distance between the centres, click the two centre points instead.

A dimension the sketch can’t take, because the geometry is already fixed by other constraints and dimensions, is added as a driven (reference) dimension instead: it is shown in parentheses, measures the sketch, and has no value to edit.

For Coincident, pick two points, a point and a curve (in either order), or two distinct straight lines. Two lines join their closest pair of endpoints; the first picked line stays in place when the existing constraints allow it. Pick endpoints explicitly when you want to connect a different pair.

Horizontal/Vertical also applies immediately to one selected line or two distinct selected points. Shift-click to add the second point before choosing the constraint.

For Parallel, Perpendicular, Equal, Tangent, Concentric and Collinear, select exactly two sketch curves (Shift-click to add the second) and choose the constraint to apply it immediately. You can also start the constraint first and then pick its curves. An incomplete or mixed selection leaves the tool ready for ordinary picking.

Coincident accepts an exact selection of two points or a point and a curve. Midpoint accepts one point and one line, in either selection order, or two lines: the second line moves (keeping its length) until its midpoint sits on the first line’s midpoint, and stays centred there as either line changes. Symmetry accepts two distinct points and one symmetry line, regardless of where the line occurs in the selection. Successful constraints clear the selection; rejected constraints preserve it.

Under-constrained geometry is blue and fully constrained geometry turns dark, and the status shows the remaining degrees of freedom. A constraint or dimension that would over-constrain the sketch is refused rather than applied. Drag a point to move it; the solver keeps every constraint while you drag.

Profiles

Closed loops become profiles automatically, including regions split by crossing lines and islands inside outlines. Extrude, revolve, sweep and loft pick profiles.

A feature remembers a picked profile by the curves around it, not by where it was clicked: "profiles": [{"curves": ["l1", "l2", "a1", "l3"]}] (or [{"curves": ["c1"]}] for a circle) picks the region whose outer loop is made of exactly those curves, or the pieces of them that other curves cut off. It is found again on every recompute, so the feature keeps the same region when a parameter moves the geometry. Islands inside the region are its holes. When no region, or more than one (both halves of a circle cut by a line), is bounded by exactly those curves, the feature reports an error rather than taking another region. Profiles picked by index or by point ([{"point": [x, y]}]) are stored the same way when the feature is made.

Measurement units

Change the current design through Document Settings > Units in the browser. The units preference applies to new designs. Existing sketch annotations, live drawing lengths and Measure follow the current design units without resizing geometry. Inches display at least three decimal places and retain a meaningful fourth digit; a higher display precision can be selected in Preferences. Bare length values typed in the dimension tool use the current design units. Explicit units such as 25.4 mm remain valid in an inch design. Angular dimensions keep their angular units. Deliberately typed four-place inch literals retain trailing zeros. Component/canvas distance controls and inspection, parts-library and flat-pattern measurements follow design units too; parameter expressions and metric standard names retain their explicit authored units.

Measure shows the currently selected distance (centre, minimum or maximum) and separate X, Y and Z distances on the canvas. The component dimensions follow the world axes and remain visible until the Measure dialog closes. To hide these extra lines and labels, turn off Preferences > Graphics > Show X/Y/Z distances. The choice is saved between runs.

Reviewing mirror, pattern, and offset results

Mirror, rectangular/circular Pattern, and Offset show the active selection step in their shared tool window. Click an input to change it; click a selected object again or Ctrl/Cmd-click it to remove it. Each input has its own Clear button. Source inputs show a count, and single references identify the chosen mirror line, direction, or centre. Box selection also works while the window is open. Sketch modify tools take geometry from the sketch being edited.

Proposed sketch geometry appears green before confirmation. Change the inputs or values to update the preview, then press OK. Cancel discards the preview. A circular pattern centre can be an existing point or a position clicked in empty sketch space.

Sketch patterns keep each instance related to the seed geometry: moving the seed updates the copies, and a copy cannot deform independently. Circle and ellipse radii follow the seed too. Choose a circle’s centre point to keep a circular pattern centred on that circle. A centre placed in empty space becomes a sketch point that can be dimensioned or made coincident. Double-click the pattern badge (at the circular centre or beside the rectangular seed), or right-click a seed or copy and choose Edit Sketch Pattern, to change quantity, spacing, direction or total angle. Confirmed edits preserve surviving instance ids; Cancel discards the preview. Pattern settings survive save/reopen and undo/redo. Deleting a seed, copy or pattern relation breaks that association and leaves the remaining geometry independent. Patterns saved by older versions remain independent copies; recreate them to add associations.

Offset distances are editable driving dimensions: double-click a dimension or change its model parameter to resize the offset without moving its source curves. The selected side, distance, and association survive save/reopen and undo/redo. Symmetric offsets share one driving distance; Two Sides has an independent distance for each side. Disconnected selected curves or chains are all offset. Breaking an association retains its current geometry and removes that association’s driver. Older offsets retain their saved fixed distances.

Solid features

For prerequisites, a readable options table and a first example, open the practical Extrude guide.

Features live on the timeline and rebuild incrementally from the first one that changed. Each one can be edited (double-click), suppressed, renamed, reordered (if nothing it depends on moves after it), rolled back to, and deleted. Deleting asks first when other features depend on it.

Extrude automatically selects Join for additions when the active component already has a solid, including sideways elbow connections and screw bosses that meet only part of a face. Extruding into existing material selects Cut. In an empty component it selects New Body; choose New Body explicitly to keep an addition separate. Changing the default does not alter operations already saved in a design. A Join (of an extrude, revolve, sweep, loft, primitive…) whose material touches none of its target bodies still joins it, to the first one as a separate piece, and the feature’s warning says so: “Body1 is now in 2 separate pieces”. Combine joins the bodies it is given without that warning.

Extrude to a picked target (Preferences › Design, off by default) lets a pick choose the extent. With it on and a profile selected in the solid Extrude dialog, picking a face away from its plane, a curved face, an off-plane vertex or a parallel plane automatically switches Distance to To Object. Coplanar faces still join the profile selection; non-parallel planes are not targets. The extent can still be chosen manually. For a new extrusion without start or end offsets or a From Object input, the target also sets the stored distance and one-sided direction, so returning to Distance keeps that reach. Thin Extrude keeps its existing picks. With the setting off, picks only add profiles, as before.

A positive extrude taper slopes the side walls outward, so the profile grows along the extrusion direction and the far end is larger; a negative taper slopes them inward, making the far end smaller. For example, a 10 × 10 mm square extruded 10 mm with taper: "5 deg" has an approximately 11.75 × 11.75 mm far face; with taper: "-5 deg", it is approximately 8.25 × 8.25 mm.

A taper slopes the sides of any profile, sketch text included: lines, arcs and spline or conic curves move in or out together, and a flat tip shorter than the taper closes to a point. On spline and conic sides the slope is approximate: the moved outline is a curve of the same kind within 2 % of the taper’s offset (or 10 µm) of the true one, a curve that turns too much for that being cut into pieces first; where a curve bends tighter than the offset, the offset folds and is smoothed over. A taper steeper than the profile’s details (a stroke, a curve or a gap narrower than it) is refused with that reason; a smaller taper or distance builds. A taper composes with a start offset (a drafted pocket that starts part way up a part): the offset moves the profile along the normal and the sides are drafted from there, so the profile is the section at the start whatever the offset. A taper with a two-sided or symmetric extent is not built yet and says so.

Thin Extrude (thin: true on solid.extrude, the Thin Extrude box in its dialog) builds a wall of constant thickness along sketch curves instead of filling profiles: open chains (a single wall) and closed loops (a ring), lines, arcs, circles, ellipses and splines. In the dialog, a picked profile stands for the curves around it (its outline and its holes). The wall lies on the curves’ centre, inside, outside, or on both sides with two thicknesses (side: center, inside, outside, two_sides with thickness2). A closed loop’s inside is the area it encloses; an open chain’s is the side it bends toward (the inside of a U), and a straight line’s is the left of its first curve as drawn. Curves that meet end to end are one chain whose corners are mitred; walls that cross or meet (a ring and a cross, a honeycomb) become one piece. Every extent, operation and target of an extrude applies, and a taper for walls of straight lines or of whole circles. A wall thicker than the radius of a curve it follows on the inside is refused. Spline walls follow the exact offset within 0.0001 mm.

Editing an extrusion retains its signed distances, From/To Object inputs, taper expressions and explicit body targets. Revolve edits retain world, sketch, explicit-line and model-edge or face axes, both angle expressions and To Object targets. An unchanged All profiles selection continues to include profiles added later. Cancel restores the complete timeline; a successful edit is one undo step, including downstream parameter changes. Editing a placed component previews the edited feature before its downstream history. Cylindrical Emboss profile guides follow the sketch’s chosen occurrence frame.

Newly selected adaptive profiles store complete outer and hole source identities when the entire boundary can be qualified. Changing an ellipse or periodic offset after extrusion can then change its spline span count while keeping the same selected material region. A partial, intersected or ambiguous boundary cannot satisfy that whole-source reference; changing the hole identities also makes it lost. Older curve-span selections retain their exact stored multisets. If an older feature has already lost its profile after subdivision changed, edit the feature and reselect the intended current region to capture the new identity.

New symmetric solid extrusions treat the entered distance as the total thickness and split it evenly around the start plane: 10 mm spans -5 to +5 mm on an XY sketch. Switching from One Side to Symmetric keeps the entered total thickness. Through All still reaches targets in both directions, and Two Sides retains its independent distances. Symmetric extrusions saved before this change keep their original per-side distances when reopened or edited. Selecting another direction in the feature editor uses the current total-distance convention.

New symmetric revolves split the entered angle evenly around the sketch profile, regardless of which way the selected axis points. Two Sides measures the second angle backward and the first angle forward along the sketch-normal sweep direction. Profiles on opposite sides of an axis each use their own sweep direction. Designs saved before format 11 keep their original angular placement when opened, edited or copied; creating another revolve uses the new behavior. To Object follows that same direction for each selected profile, including curved target faces. Pick a target away from the axis so its angular position is defined.

For cylindrical Emboss, select a supported exterior cylinder face and a tangent sketch profile. Deboss cuts radially into the wall. Orthogonal line profiles, including holes and concave outlines, wrap with exact radial walls; the profile must stay clear of seams and ends. Complete cylinders and coaxial sleeves are supported. Capture pending component positions before applying. The feature stores the selected target and author occurrence paths, so edits and reopening retain the chosen instances. Other curved surfaces and free-form profiles remain unsupported. A new Emboss without an explicit face infers a unique eligible supported cylinder; select the face when the target is ambiguous. Older saved features without a face retain their planar placement.

A Hole with Single placement can also sit at distances from up to two straight edges of its face. After picking the face, click Reference 1 and pick an edge, then pick a second one into Reference 2. Each edge gets a Distance row, measured from where you picked; the canvas shows each one as a dimension from the edge to the hole’s centre, with a box beside it. Type a distance in either place and the hole moves so its centre is that far from the edge, measured in the face’s plane. Moving the hole measures the distances again. The hole keeps its distances when the part changes: it follows its edges, and the distances are parameters like its diameter.

A Hole with Single placement drills where you pick a planar face. A pick on or near a point of a shown sketch that lies on that face, such as a circle’s centre, places the hole exactly at that point, as Multiple placement picks it; Select Other (press and hold) also offers the face where you clicked. The corners of text outlines don’t count, nor do projected points while the sketch hides projected geometry. The hole keeps that place on the face; to have holes follow later edits of the sketch, place them with Multiple.

Two settings under Create Hole in Preferences › Design, both off by default, change how a Single hole is placed:

• Snap to face and edge centres: the face itself offers snap points too: its middle, and the centre of each round edge on it (a boss standing on it, a rounded corner, a hole already in it). While the cursor is over the face they show as small marks; a pick near one, or on or beside one of those round edges, places the hole at that centre, and the mark it takes is named. Hold Alt or Ctrl to place the hole exactly where you click.
• Move holes by clicking or dragging: each placed hole has a handle at its centre. Drag it to move the hole (it snaps when snapping is on), or click it to take the hole out. A pick elsewhere on a face that already has a hole moves the hole there instead of taking it out. Edit Feature shows the handle as well, so a hole can be moved later.

The Hole dialog draws a section through the hole as its options make it (type, extents, drill point, tapped) and puts each size in a field beside the dimension it sets; hovering a field, or typing in it, lights its dimension.

Tapped holes and Thread features have a Thread direction choice: Right-hand (the default) or Left-hand. Editing and reopening keep the chosen direction. Tapped holes carry a cosmetic thread; the separate Thread feature can also cut a Modeled left-hand helix. Cosmetic direction is recorded with the thread annotation and does not change the body. Scripts use handedness: "left" or "right" on solid.hole (with thread) and solid.thread. Existing designs and omitted values remain right-handed. Changing the direction keeps the pitch, thread length and axis; it does not change a hole’s drill size.

Fillets and chamfers handle straight edges between planar faces, whole smooth loops, runs of neighbouring edges with mitred or spherical corners, and closed chains of curved edges (a rolling ball). See the roadmap’s known limitations for the rest.

Curvature (G2) in the Fillet dialog’s Radius Type blends straight edges between two planar faces with an exact quintic section. The tangent plane and curvature match each side face: curvature goes to zero at both contact rails, unlike a circular G1 fillet. Each end must meet one planar face; perpendicular and sloped planar ends are supported. Curved edges/faces, multi-face ends, and intersecting corner blends are not supported; they return an error, not a G1 fallback. Equivalent Radius sets the same contact setback as a circular fillet (for a right angle, setback equals the entered value); it is not a constant curvature radius. Reduce/Taper to Fit are unavailable for this type.

Scripts and MCP use the same command, for example on a 20 mm box:

{"command": "solid.fillet", "params": {"edges": [[20, 0, 10]], "radius": 2, "type": "curvature"}}

type: "g2" is an alias. Existing fillets still default to circular, constant-radius G1 blends.

Feature references to faces and edges are stored by name, so an upstream edit that moves geometry keeps them on the right face (see Persistent naming). When a reference can’t be found, the feature warns instead of silently picking another face.

Plane Along Path accepts one sketch curve (including a drawn 3D wire) or model edge. Pick the path in the viewport and enter Position (0 to 1): 0 starts the path, 1 ends it, and 0.5 places the plane halfway along its length. The plane is perpendicular to the path’s local segment. Preview does not change the design; OK creates one editable timeline feature. The plane follows later path edits. Curved paths use their sampled polyline; absolute distance, reference-object placement and multi-curve chains are not yet available in this dialog.

Comparing two bodies

Compare Bodies (inspect.compare) lays two versions of one part over each other, such as a part and the same part exported by another program, and finds the places where only one of them has material. It works from the two surfaces, not from a boolean of the bodies, so it also compares bodies that share almost every face, the case a boolean (Combine, Interference) handles worst.

{"command": "inspect.compare", "params": {"a": "Bracket", "b": "Bracket (2)", "tolerance": 0.01, "color": true}}

Without a and b it compares the two selected bodies, or the design’s only two. Both bodies are measured (volume, area, centre of mass and box, and difference: b − a of each). Each surface is sampled at the corners of its triangles and at points at most spacing (0.5 mm) apart on larger faces, and every sample measures its distance to the other surface: deviation gives the largest and the mean distance each way. Samples further than tolerance (0.01 mm) form the regions: only_in_a where a has material and b has none, only_in_b the other way round. Each region gives its volume, the deviating surface area, the largest deviation and where it is, its centre and box, and the faces of each body it lies on (faces_a, faces_b, numbered as model.faces lists them), largest volume first. The volume is integrated along a grid of parallel lines through the region (resolution gives their spacing), so a thin sliver is measured as well as a block. identical is true when no region is found, and verdict says it in one line. warnings lists what makes the result less certain: a body whose surface does not enclose the volume it measures (open, or with faces that failed to import), and lines left out of a region’s volume because they crossed a gap. With color, the faces that hold a region turn red where only a has material and green where only b has, on both bodies: the faces mostly beyond the tolerance (a small change on a large face leaves the face alone), or, for a region with none, the face with the largest share. That is one undo step; without color the command changes nothing.

The bodies are meshed within a quarter of the tolerance. The kernel meshes no finer than a millionth of a body’s size, so keep the tolerance at least twice that (0.02 mm for a part 10 m across). Large bodies are sampled more coarsely, at about max_points (eight million) points each; sampling.spacing_mm says what was used, and a larger max_points (up to 50 million) samples them finer, at the cost of time.

Editing a feature from a script

For solid.pattern.circular, axis accepts X, Y, Z, {origin, dir}, or an edge or round face of the model, {edge: [x, y, z]} or {face: [x, y, z]} (a point on it). An explicit origin must contain three finite numeric coordinates in millimetres ([x, y, z] or {x, y, z}); omitting it uses the world origin. Expressions and construction-axis references are not supported. Invalid origins are rejected rather than silently replaced with zero.

Axes and points on round edges and faces

Wherever a 3D command takes an axis (Revolve, Surface Revolve, Circular Pattern, Plane at Angle, and Move’s Rotate) you can pick a circular edge, which gives the axis through its centre along its normal, or a cylinder, cone or torus face, which gives that surface’s axis. Hovering one in an axis input draws the axis as a dashed construction line, and the line stays drawn once the axis is picked. Flat faces and edges that are neither straight nor circular can’t be picked there.

Revolve, Surface Revolve, Circular Pattern and Plane at Angle keep the picked edge or face as a reference ({edge: [x, y, z]} or {face: [x, y, z]} from a script), found again by its persistent name every time the design is evaluated. If a parameter moves the cylinder, the feature turns about it where it is now. The axis always points the same way, with its largest component positive, so a rebuild that reverses the edge doesn’t flip the turn. Straight edges picked as axes keep working as before, as a fixed line.

Where a 3D command takes a point (the construction points, axes and planes built from points, Revolve and Extrude’s To Object, a surface patch’s pass-through points, and Move’s pivot and points), a circular edge stands for its centre. A hovered circle shows a small star at its centre. A construction point keeps the edge, so it follows the circle’s centre as the model changes.

timeline.inspect {feature} returns a feature’s definition: the fields timeline.edit changes, with their current values. timeline.edit {feature, set} merges set into that definition (objects are merged field by field, anything else replaces the value), rebuilds the feature and reports recomputed and restored. The feature’s type cannot change, and sketch geometry is edited with the sketch commands. Expressions are text ("30", "30 mm", "width / 2", "45 deg"); a bare number is a length in the design’s units, or degrees for an angle.

{"command": "timeline.inspect", "params": {"feature": "Slab"}}
→ {"type": "ExtrudeFeature",
   "definition": {"sketch": 1, "profiles": {"type": "all"}, "operation": "new_body",
                  "extent": {"distance": "10", "direction": "positive"}},
   "inputs": [{"label": "Distance", "param": "d1", "expression": "10", "unit": "mm"}], …}
{"command": "timeline.edit", "params": {"feature": "Slab", "set": {"extent": {"distance": "12"}}}}

inputs lists the feature’s named inputs. parameters.change {name: "d1", expression} sets one of those directly. Optional fields that are not set do not appear in the definition; they can still be added through set. The fields of the common features:

For any other feature, timeline.inspect shows the fields.

Where a command takes a face as a point (face.delete, solid.shell, solid.draft, solid.offset_face, solid.split_face, the faces of solid.replace_face, and the face of sheet.convert), a script can give the face’s name instead, as model.faces lists it: {"command": "face.delete", "params": {"faces": ["F2:side#1", "F2:side#2"], "body": "Plate"}}. model.faces also lists a point on each face that picks it (the centroid of a face with a hole in it is in the hole, that of a half cylinder inside the cylinder) and, for a cylindrical face, its cylinder: origin and axis of its axis, and radius. A name that is more than one face (the pieces of a split face, or one face of several bodies) is refused; body says which body to look on.

Press Delete on anything selected (bodies, faces, sketches, features, planes, components, canvases). It runs as one undoable step and lists the features that would go with it or fail.

Face Extrude, face Revolve, and Press Pull retain linked generated profiles. When a modified planar face has no construction certificate, these internal profiles use the legacy named-face attachment and projection behavior so upstream edits still update the plane and outline. This compatibility path is private to those modeling tools: newly attached user sketches require a certified face or an explicitly fixed plane. Legacy internal attachments can follow the nearest matching face after topology changes; inspect their result after major upstream edits. Activate the intended occurrence before generating a face profile from a repeated component; capture a separately moved source position before creating a legacy profile across components.

Negative Press Pull across supported aligned prismatic faces retains round through-holes, including after a joined extrusion and in a rotated component occurrence. The cut partitions the current material into axial sections, preserving the hole through undo, redo, and reopen. Walls that cannot be qualified as a parallel extrusion still use the general Boolean path and may report an unsupported coincident-surface operation atomically.

Parameters and expressions

Every dimension and feature input is a model parameter (d1, d2, …). User parameters are ones you add yourself, with a unit, an expression and an optional comment. Change them in Change Parameters (parameters.change). The timeline rebuilds from the first feature that uses them.

When creating or editing a sketch dimension, its value editor shows its model parameter name (d1, d2, …). Click another driving dimension to use its name: when the value is just a number (such as 10 or 10 mm) the name replaces it; otherwise it goes in at the cursor, replacing selected text and keeping what you typed, so typing 10 + and clicking d1 gives 10 + d1. Add arithmetic such as / 2 to build a dependent dimension. Press Enter to apply the expression or Escape to cancel the edit. When placing a new dimension, width = 40 (or #width = 40) adds the user parameter width with that value (a bare number is in the design’s units) and dimensions with it; a name that is already taken is refused. The value boxes shown while drawing a shape (a line’s length, a rectangle’s width and height, a circle’s diameter) take the same form: the shape is drawn at that size, and its dimension uses the new parameter. Add and edit user parameters through the existing Change Parameters command.

In the MANAGE tab’s PARAMETERS section, click Parameters to open the user and model parameter editor. The Configurations button in CONFIGURATIONS opens the configuration table; Configure remains in the dropdown for configuring columns.

Press Enter in the new parameter’s name, expression or comment field to add it. Valid entries return focus to the name field for the next parameter; invalid entries remain editable. In expression fields, type a parameter or dimension name for autocomplete, or press Ctrl+Space to open suggestions, including in an empty field. Up/Down selects an autocomplete suggestion, Enter/Tab accepts it, and Escape dismisses the suggestions. Accepting a suggestion does not also submit the parameter. When what you typed is already a complete name (width), longer names such as width_extra stay listed without a selection: Enter applies what you typed, and Up/Down picks one of them first. A unit right after a number (10 mm) is left alone; anywhere else a unit is a prefix like any other, so rad followed by Enter gives radius.

With Preferences › Design › Step values with the arrow keys and the wheel on (it is off by default) and no suggestions open, Up/Down step a plain number in any value field (a dialog’s rows, the value box beside the geometry, a sketch dimension, a parameter’s expression) by 1 in the unit it is written in: 20 mm becomes 21 mm, 2,5 mm becomes 3,5 mm. Hold Shift for 10 or Alt/Option for 0.1. The mouse wheel over the focused field does the same, a step a notch, and the preview follows each step. An expression such as width / 2 is left as typed.

Expressions are unit-aware: 2 * width + 5 mm, angle / 2, sqrt(area), 1 in + 3 mm, using + - * / ^, parentheses, sin cos tan asin acos atan atan2 sqrt abs min max floor ceil round mod trunc and unit conversion. A number and the unit after it are one value: 10 mm / 2 mm is 5 and 90 deg / 1 rad is π/2, and a fraction of numbers before a unit is one value too (1/2 in is half an inch; after a / only written without spaces: 1 in / 1/2 in is 2, while width / 10 / 2 mm divides by 10 and then by 2 mm). A decimal comma works too, outside parentheses: 2,5 mm is 2.5 mm (inside a function’s parentheses the comma separates its arguments, so write max(2.5, 3) there). A mixed number is one value, as imperial sizes are written: 2 1/8" and 3 7/16 in are 2.125 in and 3.4375 in (a whole number, a space, then a proper fraction of whole numbers). A length where an angle is expected (or the other way round) is an error, not a silent conversion. Cycles are reported with their path (a → b → a), renaming a parameter updates every expression, dimension and feature input that uses it, and a parameter in use can’t be deleted (the error lists its users).

The design’s units (Document Settings in the browser: mm, cm, m, in or ft) set how a bare number or unitless arithmetic expression typed into a length field is read. In an inch design 0.25 and 1 / 4 mean 0.25 in. Operation dialogs start with lengths in the design’s units, including secondary distances, wall thicknesses, gaps, offsets and radii. Canvas handles and live sketch values use the same units as the operation. Angles, counts and scale factors keep their own units. Preferences selects the default units for new designs; existing designs use their own Document Settings.

Explicit units override that choice: 2 mm is still two millimetres in an inch design. Parameter expressions such as width / 2 remain driving expressions. Editing a saved feature preserves its physical size; an existing millimetre expression can still show mm so accepting an unchanged field cannot reinterpret it. Computed sizes and tolerances keep their full precision when written back into editable fields, independently of display precision.

Parameters export to and import from CSV or JSON (parameters.export, parameters.import). Configurations (config.*) keep a table of rows, each with its own parameter values and suppressed features, physical materials and body appearances, switched with config.activate. The table’s Library picker selects material or appearance values. Choose Follow material to clear an appearance override. Custom looks retain their colour and opacity across activation, undo and save/reopen. See configuration commands and examples.

Checking a design across a parameter’s range

Parameter Sweep (inspect.parameter_sweep) rebuilds a copy of the design at each of a parameter’s values and reports what no longer holds, so a design meant to be driven by its parameters (one template, many sizes) can be checked before it is trusted. The design itself is not changed.

{"command": "inspect.parameter_sweep", "params": {"parameter": "Width", "from": 300, "to": 510, "steps": 21}}

values lists the values instead (numbers or expressions). For each value it gives the rebuild’s time and what changed from the design as it is now: features that fail (failed) or warn (warned), joints whose origin is no longer found (joints_lost) or turned over on its own part (joints_flipped, more than 90°), sketch planes that turned over (sketches_flipped) and sketch solves that fail or only hold by flipping a triangle’s turn or an offset’s side (sketches_failed). summary counts the values that show each.

Components and joints

A design is a tree of components. New Component (component.create) adds one, and Create Components from Bodies (component.from_bodies) turns bodies into components. Each component has its own origin, bodies, sketches and timeline entries. The active component (the radio button in the browser) receives new sketches and features; the others are drawn faded.

A component is placed by its occurrences. Paste creates another instance of the same component, and Paste New creates an independent copy. Move an occurrence with the move triad, then Capture Position to keep it or Revert to put it back. SolidCraft asks before the next command if a move wasn’t captured. Ground fixes an occurrence in place, and Unground (the same row of the browser’s context menu) frees it again.

The design’s first part is grounded when it is made: the first occurrence placed directly in the design by New Component, Create Components from Bodies or an import. Parts made after it, standard parts and copies made with Paste or Paste New start free, so do parts made inside other components. Any number of parts may be grounded, or none; opening a design never grounds anything. A grounded part refuses Move until it is ungrounded, and component.create takes grounded: true or false to choose for itself.

Drag a part to put it somewhere else. With the design active, press the left button on a part and drag: the part follows the pointer, the point you grabbed moving in the plane through it that faces the view, and stays where you let go, with its position captured. The whole drag is one undo step, and Escape during the drag puts the part back. The drag moves the placement of the active component that holds the part, so with the design active a part inside a subassembly moves the whole subassembly; activate the subassembly to move the part inside it. Moving a definition shared by several placements moves it in all of them, as Move does. A grounded part does not move, and a part that joints hold to something grounded moves only as far as its joints allow (below). Dragging any member of a chain joined to nothing grounded moves the whole chain, preserving its joint values. Shared nested definitions move in every instance; the selected instance follows the pointer even when its parent is rotated differently from the first one. A drag that starts on empty space, on a part that can’t move, or with Shift, Ctrl (Cmd) or Alt held draws a selection box instead. Other uncaptured moves stay pending. Scripts and agents do the same with occurrence.drag {occurrence or path, at, point}, which moves the placement by point - at in world coordinates and answers the placements it moved.

Paste New copies nested component definitions, sketches, feature histories and generated dimension parameters. Repeated child instances remain shared within the new copy. Materials, appearances and wholly internal joints/motion records receive copied references. Design-wide user parameters remain shared; retained external links and omitted cross-boundary motion records are reported. Unsupported destructive links refuse the entire copy. See individual-instance and copy details.

Extract to File (component.extract, in a component’s right-click menu) moves a component into a design of its own: its sketches, features, bodies, subcomponents and the joints among them go to the new .solidcraft file at its origin, with the parameters they use, and the component becomes linked to that file, as Insert Design makes it. Its placements and the joints to the rest of the assembly stay. Components whose own history builds the same bodies are offered to become placements of the new link too (component.copies, component.replace_with_link). The menu offers Extract only for a component that can leave: nothing outside uses its sketches or changes its bodies, no bodies were moved into or out of it, and none of its subcomponents is joined to the rest of the design.

Joints (joint.create, J) connect two components by joint origins that snap to faces, edges, circles and vertices: rigid, revolute, slider, cylindrical, pin-slot, planar and ball, with offsets, flip and limits. As-built Joint keeps the current position, Rigid Group locks components together, Drive Joints moves a joint through its values, and Motion Link couples two joints. A rigid joint holds its parts still, so Drive Joints has nothing to drive on it: it says so and offers Edit Joint, where the joint’s type changes to Revolute (rotate), Slider (slide) or Cylindrical (both). Links can be chained (one joint drives a second, which drives a third), and a value is carried through a chain of up to 64 links in whatever order they were made. Contact sets stop motion where bodies would pass through each other, Motion Study keys joint values along a timeline, and Interference shows overlapping volumes in red, lists the pairs closer than its Clearance and each body’s nearest neighbour.

In the Joint and Joint Origin dialogs, picking a straight edge puts the origin at its midpoint with the motion axis along that edge. A revolute joint turns about the picked edge; a slider moves along it. Round edges use their circle’s centre and normal. Existing saved joint origins keep their axes.

A joint origin on a face or a hole keeps the turn it had when it was picked: when the face tilts (a bend angle or a rotation changing with a parameter) the part on it tilts with the face but doesn’t spin about it.

A joint origin can also sit on an edge of a flat face ("edge": [x, y, z]): at the edge’s middle, pointing out of the face with its y into it, or with "corner": [x, y, z] at the corner near that point, its x and y running along the two edges into the face. The edge, the face and the corner are found again by name, so a bracket set 40 mm in from a panel’s corner (a planar joint with values [40, 40, 0]) stays 40 mm in from that corner when the panel changes size.

A joint’s offset, angle and values can be typed as expressions over the design’s parameters ("offset": "gap + 2", "values": ["travel"]). The joint keeps them and works them out again whenever the design changes, so a part seated gap above a panel moves with gap. Renaming a parameter carries into the joints that use it, and deleting one they use is refused. If an expression stops working out (say a parameter becomes an angle), the joint is left out of the solve and joint.solve gives the reason, instead of placing the part from old numbers. Typing a plain number, or driving the value, drops that expression.

Relations are joints that tie only part of a placement, so a part is placed the way a designer describes it, one relation at a time: parallel (z along z, free to move and turn about it), perpendicular and angle (z square to z, or at the joint’s angle from mated), point_on_plane (a point on a face’s plane, offset off it), point_on_line (a point on an axis) and line_on_plane (an axis on a face’s plane: a cylinder’s radius as offset lays it tangent). A relation is made where the parts are: B moves no further than the relation needs. Several relations between the same two parts add up; the solver meets them together, each one’s degrees of freedom come off what is left, and one that can’t be met is reported, not forced:

{"command": "joint.create", "params": {"type": "parallel", "a": "Panel top", "b": "Bracket bottom"}}
{"command": "joint.create", "params": {"type": "point_on_plane", "a": "Panel top", "b": "Bracket corner"}}
{"command": "joint.create", "params": {"type": "parallel", "a": "Panel front", "b": "Bracket face", "flip": true}}
{"command": "joint.create", "params": {"type": "point_on_plane", "a": "Panel front", "b": "Bracket corner", "offset": -40}}
{"command": "joint.create", "params": {"type": "point_on_plane", "a": "Panel end", "b": "Bracket corner", "offset": -40}}

leaves the bracket flat on the panel, square to its front, its corner 40 mm in from the front and the end, wherever the panel’s size takes them. Coincident faces are a planar joint, a distance between faces is planar with an offset, concentric is cylindrical and two points that meet are ball.

The check behind it, inspect.clearance, does all of that in one call for any number of bodies, which suits scripts and agents checking a whole assembly:

{"command": "inspect.clearance", "params": {"clearance": 1, "nearest": 2, "skip_within": "component"}}

It returns overlaps (pairs sharing at least min_volume, 0.01 mm³ by default, with the shared volume, area, box and centre), near (pairs closer than clearance, with the distance and the two nearest points; a contact sharing less than min_volume is listed here at 0 with its overlap_mm3), nearest (each body’s nearest closest bodies) and unchecked (pairs whose overlap could not be worked out, with the reason). against limits the check to pairs with one body in bodies and the other in against, and skip_within leaves out pairs inside one occurrence ("occurrence") or one placed component, its subcomponents included ("component"): the parts of a bought component that touch by design. Distances are measured on the exact faces and edges; the meshes only rule out pairs that are too far apart, and the pairs left are checked in parallel. inspect.interference remains for the overlaps alone: it clears pairs whose meshes stay apart without intersecting them, intersects the rest in parallel, and returns after budget_s seconds (default 240) at most, listing the pairs it had no time for as not checked.

Mesh bodies (STL, 3MF and OBJ imports) are not checked by either command: each is listed in unchecked as {a: name, b: null, reason: "mesh body: not checked"}, so count: 0 or an empty overlaps is not mistaken for “no overlap” when a mesh body was in the design.

Gear, Rack and Pinion and Screw (on the ASSEMBLE panel) are motion links whose ratio comes from the parts rather than a typed number:

• Gear (joint.gear {a, b, ra, rb}) couples two joints that turn. Joint 2 turns ra/rb as far as joint 1, the other way round; Internal gear (one of them is a ring gear) turns both the same way. Pick the round face of each gear, such as its pitch cylinder, or type the radii. Tooth counts work as well as radii, since only their proportion counts. Picking a gear’s face also chooses the joint that gear turns on.
• Rack and Pinion (joint.rack_pinion {a, b, radius}) couples a joint that turns with one that slides: the rack travels the pinion’s pitch radius times its turn in radians (r·θ). Either joint may drive the other. In joint.list the ratio is given per degree, as for any link between an angle and a distance.
• Screw (joint.screw {joint, pitch}, or {a, b, pitch} for a revolute joint and a slider) advances pitch per turn. A cylindrical joint is a screw on its own: its turn drives its travel. The thread is right-handed; Reverse makes it left-handed.

A radius or pitch may be an expression of the design’s parameters, and a picked face is found again whenever the design changes. Change the parameter or the gear’s diameter, and the ratio follows. The new link leaves the driven joint where it is, so teeth modelled in mesh stay in mesh. Reverse turns the driven joint the other way, for joints whose axes point opposite ways. Redefining a link (link: i, such as turning it the other way with Reverse) also leaves the driven joint where it is, so the gears stay in mesh at the pose they are in. These couplings are motion links, so they work in closed loops, with contact sets and in motion studies: a rack can push the piston of a slider-crank, or a pinion can steer through a rack and its tie rods. Drive the joint that drives the coupling (joint 1, the pinion, or the screw’s turn), not the driven one. A joint follows one link at most, and a coupling that would drive its own driver is refused. joint.list lists each coupling’s definition under links with an error when it can’t be worked out (the picked face is gone); the link then keeps its last ratio.

Cam (joint.cam {a, b, profile}, on the ASSEMBLE panel) makes a follower ride a cam. The cam turns on a revolute joint (a); the follower is a slider (b, a translating follower such as a valve tappet) or a revolute joint (b, an oscillating follower such as a rocker arm). The profile is the cam’s outline in a plane square to its axis: a closed profile of a sketch in the cam’s component, or the cam’s edges picked on its body (one click on an edge takes the closed loop it is on in that plane). The follower is:

• a Knife edge: a point on the cam;
• a Roller of a radius, typed or taken from the roller’s round face (picking that face also says where the roller is);
• a Flat face square to a slider’s line, such as a bucket tappet.

A translating follower’s line runs along its slider’s axis, through its Tip when one is picked (its knife’s point or its roller’s centre), so a follower offset from the cam’s axis rides the right flank. An oscillating follower needs its tip, or its roller’s face, to know its arm. The follower rides the cam from the side it is on (Other side takes the other one). The follower’s travel over a turn of the cam is worked out from the profile and kept with the link, one value a degree with a smooth curve between them that never overshoots its samples. It is worked out again whenever the design changes: change the cam’s sketch, a parameter or the roller, and the follower follows. Like the gears, the new link leaves the follower where it is (model it touching the cam), and the cam is a motion link: it drives in Drive Joints, plays in motion studies, works in closed loops (a tappet can be the piston of a slider-crank) and stops at contact sets. The profile may also be on the grounded part, with the follower’s guide on a turret that the cam joint turns. joint.list gives a cam’s link lift (the follower’s lowest and highest values and its rise) instead of a ratio. A profile that is not closed, a line or an arm that misses the cam somewhere, a follower that would jump, and axes that are not square or parallel are refused.

A joint moves one component against another, so its two picks must be on different components. A STEP file with several parts often comes in as bodies of one component, and picks on two of those bodies make no joint. The Joint and As-built Joint dialogs say so under the picks and offer Create Components from Bodies: each picked body gets a component of its own and stays where it is, the picks are kept, and the joint previews. joint.create refuses such origins with the same advice.

Joints may close a loop, as in a four-bar linkage or a slider-crank. When one joint of the loop is driven, the other joints in the loop follow so that every joint still meets, and the mechanism stays in the assembly mode it started in (an open four-bar does not flip to the crossed one). If the motion would take a loop past the point where it can still close, for example driving a rocker beyond its swing, the motion stops at the last position where the loop closes, and the drive reports stopped_by_loop. A loop that cannot close at all is listed under conflicts and nothing in it moves. joint.list reports how many degrees of freedom each part still has with its loops closed: the moving parts of a four-bar have one between them, and a loop locked by a rigid joint has none. A joint a motion link drives adds no freedom of its own: two meshed gears on a fixed housing have one between them, each turning with the driving gear. The Drive Joints dialog says when a drive stops short and why. While it previews, a row under the values gives the value the joint reached and the reason (the loop that can’t close further, or the two parts a contact set keeps apart), and after OK the status line repeats it. The value box keeps what you typed. The dialog opens on the joint picked in the browser, or on the first joint that moves when none is picked.

Drag a part that joints place and it moves as far as its joints allow: the point you grabbed follows the pointer in the plane through it that faces the view, the joints on the part’s chain take the values that bring it nearest, within their limits, through motion links, and with closed loops kept closed, and a four-bar’s rocker stops at the end of its swing. The whole drag is one undo step. A grounded part, or one its joints hold fixed, is not moved; a drag on it draws a selection box. Each frame runs joint.reach, which scripts and agents use directly to put a part’s point somewhere: joint.reach {occurrence, point} moves the joints on its chain from where they are to the nearest pose (the arm keeps its elbow up or down, and a linkage stays on its branch). at picks the part’s point (the centre of its bodies by default), z with axis also turns one of its axes, and joints names the only joints to move (the other joints of a closed loop they are in follow). The answer says whether it reached the point and how close it got (error_mm, error_deg), and when it falls short, the limits it rests on (stopped_by_limit) or the loop that stopped it (stopped_by_loop). Contact sets are not checked by a reach; drive the joints for that.

The solver places what it reaches from the root and from grounded components. A chain of joints that is joined to nothing grounded is never placed, so driving one of its joints moves nothing. The drive says so: joint.drive answers moved: false with a reason and the unconnected part (“Pedestal:1 is not connected to anything grounded”), the Drive Joints dialog shows the same row, motion.play lists such joints under unmoved, and joint.list names every such chain under floating. Ground a part of the chain, or join it to a grounded part (a rigid as-built joint keeps it where it is), and it moves.

joint.drive answers the joint’s values as joint.list gives them, in degrees and millimetres with their units and limits, and moved says whether any part moved. A joint’s origins are mated by default: B’s z axis is turned against A’s, as two faces meet. flip: true lines them up instead, so two origins given at one point with the same z stay as they are. Without an angle, a new joint (other than a relation, which starts where its parts are) takes no turn or a half turn about its axis, whichever turns B less: two faces that already meet, a plate under a panel, stay as they are instead of B spinning about their shared normal. For scripts that drive many steps, quiet: true leaves the per-part degrees of freedom out of joint answers, and motion.play with quiet: true gives the poses of only the parts that moved.

Motion Trace (motion.trace, on the ASSEMBLE panel) draws the path a point of a part takes while a joint is driven or a motion study plays, such as the coupler curve of a four-bar. Pick the point on the part (a face centre, a circle centre, an edge midpoint or a vertex), then either a joint with the values to drive it from and to (a turn of the joint from where it is, at first) or a motion study. The path previews in the viewport as the mechanism would move: closed loops follow, and the path ends where a loop can no longer close or a contact set stops the motion, which the dialog says under the values. OK keeps the path as a 3D sketch spline in a new sketch of the root component (Motion Trace1, …), where no joint moves it, and it can serve as a sweep or pipe path. New traces retain their source and update when the mechanism’s joint origins, limits, motion links or driving conditions change. Playing or dragging the mechanism does not redefine the trace: it keeps the assembly branch from when it was made. Unrelated parameter and display changes do not resample it. A path that comes back to where it started is kept as a closed, smooth spline. motion.trace {occurrence, point, joint, from, to, index?, samples?} (or {occurrence, point, study, samples?}) answers the world points without changing the design, and motion.trace.keep with the same parameters (and name?) keeps them. point_ref can retain a joint-origin snap (such as {occurrence, face: [x,y,z]}), so the point follows its resized face; without it, the point is fixed in the part’s coordinates. The dialog retains its face or circle snap. motion.trace.edit {sketch, from?, to?, samples?} changes a joint trace’s driving conditions; joint with from and to, or study, replaces its motion source. Expressions in from and to follow parameter edits. Study traces follow edits to the referenced study, including its step count when Samples was left at the default. auto_update: false in motion.trace.keep makes a fixed curve; in motion.trace.edit it detaches an existing association, preserving the curve. Curves saved by earlier versions remain fixed. motion.list includes the associations and their errors. If a source is lost, the sketch warns and keeps its last successful curve until the source is restored or the association is detached. Changes and their generated curves undo and redo together. A trace takes 2 to 500 samples: 100 by default for a joint, one per step for a study.

The Chebyshev linkage demo builds a complete four-joint mechanism, plays a saved study and demonstrates the same retained trajectory updating after a link-length or driving-range edit.

Export Animation… in the Motion Study dialog saves the study as an animated GIF, drawn from the viewport’s camera as the study plays (the keys in the dialog count, even before OK). motion.export_animation does the same for scripts, the CLI and agents, without a window: give a study, or a joint with from and to (and index?) to animate a drive, and a path. A path ending in .gif gets an animated GIF that loops; any other path is a folder that gets the frames as frame-0001.png, frame-0002.png, and so on (made if missing; frames of a longer earlier export there are removed), for a video tool. The web app writes GIFs only. samples is the number of frames (one per step for a study by default, 100 for a joint), width and height their size in pixels (800 × 500 by default, at most 4096 a side), and fps the GIF’s speed (20 by default); grid: false and axes: false leave out the ground grid and the origin’s axes. camera takes the reply of the control channel’s ui.camera (or any of its fields; the rest come from the view view.apply chose, or the home view framing the model). The frames are drawn by the same renderer as solidcraft-cli snapshot, on a copy of the design, which is not changed. A GIF keeps one palette for all its frames, so colours don’t flicker, and stores only what changed from one frame to the next. Frames are capped: at most 1000, and a GIF holds at most 2^26 pixels of frames (about 160 frames of 800 × 500). An exploded view animates the same way: give its name or id as view (instead of a study or a joint) and the parts come apart at a steady pace, from the assembled placement to where the view shows them; back: true brings them back together, exploded at the middle frame. That takes 41 frames by default, or 81 with back, and the home view frames the parts both assembled and exploded. As with explode.show, the design keeps its placements.

Motion analysis. The Motion Study dialog’s Study box opens a saved study to edit, and by its timeline the dialog charts what the study does. Plot picks a moving joint value (a joint picked in the Browser is picked here too), or Picked point once a point is picked in the dialog’s Point box, and Quantity whether to show its value, velocity or acceleration; the chart runs over the study’s steps with a cursor at the step shown, and a click or a drag on it moves to that step. Values are in degrees and millimetres; rates are per step, or per second once Duration says how many seconds the whole study takes. A picked point charts its distance from where it starts, its speed and the size of its acceleration. Check collisions plays the study and lists the pairs of parts that pass through each other, with the steps where they do (a click on one shows the first of them); those steps are shaded on the chart. It checks the parts picked in Components (against the ones picked in Against, when there are any), else every component, or the pairs of the design’s contact sets (a choice beside the button once it has any).

motion.plot {study, joints?, occurrence?, point?, samples?, duration?} answers the same numbers: for each joint value its value, velocity and acceleration per sample (with their units), and for a point its position, velocity and acceleration vectors, speed and acceleration_norm. The study plays as motion.play places it (closed loops follow, contact sets stop it), each sample from the one before, on a copy: the design is not changed. Velocities and accelerations are finite differences between samples, central inside and one-sided at the ends, so they are as smooth as the samples are dense (up to 1000, one per step by default). Angles are unwrapped, so a joint that turns on past half a turn keeps counting. motion.interference {study, occurrences?, against?, contact_sets?, samples?} answers each colliding pair with its first_step, last_step, the steps ranges where they overlap, how far into each other (depth_mm, the most at deepest_step) and their shared volume_mm3 there (null when it is not cheap to work out). It plays the study as motion.play does, but contact sets don’t stop it, and parts are tested at the samples only: a part that passes right through another between two samples is missed. Parts are told apart by occurrence, as contact sets tell them apart: an occurrence inside a sub-assembly placed twice is one part, so its two copies are not checked against each other. A check takes at most 256 bodies; on a large design, list the occurrences to check (an arm, with against the parts it must miss). When the work runs out it says truncated and the step it checked_to. joint.sweep {joint, from, to, index?, step?, refine?, occurrences?, against?, contact_sets?, report_gaps?, apply?} drives one joint value from from toward to and answers how far it gets before parts touch: stopped_at (the last value clear of contact), stopped_by (the two parts and the point at which they touch, or "loop" where a closed loop can no longer close, or "limit"), and with report_gaps the nearest gap at every sample and the nearest each part came to another (min_gap). The samples are fine enough that no part passes through another between two (or step apart), and the first contact is bisected until no part moves more than refine (0.01 mm by default) across it. Gaps are distances between the parts’ tessellations (gap_method: "mesh"): exact for flat faces, within gap_tolerance_mm for curved ones. Pairs already touching at from, such as parts joined face to face or a door resting on its frame, are listed in touching_at_start and stop the sweep only once they pass into each other, deeper than they start. The sweep runs on a copy (closed loops follow, contact sets don’t stop it) and leaves the design as it was unless apply is true.

Insert Design (component.insert_design {path, translate?}, on the ASSEMBLE panel and in the File menu) adds a component linked to another saved design, so each part can live in its own document. A STEP or mesh file picked there is inserted as Insert STEP or Insert Mesh would. The part’s solid bodies come in as they sit in that design, and they are kept in the assembly, so it opens even without the part file. The link is stored relative to the assembly’s folder once the assembly is saved. After the part file changes, Update Links (component.update_links) reads it again. To edit the source, right-click a linked component or occurrence in the Browser and choose Open Linked Design. It opens the part in another tab and reports if its file is missing. Break Link (component.break_link) keeps the bodies and forgets the file, and component.links lists the links and whether their files are found. A linked component holds the part’s bodies only: its timeline, parameters and sheet-metal data (flat pattern, bend table) stay in the part’s own design.

If a source file moves or is renamed, right-click its linked component or occurrence in the Browser and choose Relink Source (All Instances)…. Choose the saved .solidcraft design to use. Relinking updates that component’s stored path and solid bodies for all its instances, keeping their identities and placements. Cancelling or choosing a missing, invalid, empty or self-referencing design leaves the assembly unchanged. The operation is one undo step and the new path is saved relative to the assembly when possible.

Scripts use component.relink {component, path}. The reply includes previous_path, path, warnings, joint_errors and joint_conflicts. Changed geometry can invalidate a joint’s face reference: relinking reports those joints in the reply and UI status/message history; repair the joint or undo the relink. Relink does not repair or verify the intended meaning of existing joints. When linked geometry changes and the component has joints, a reminder to check those joints is also shown even if the solver reports no error: a successful solve does not prove that a joint still describes the intended connection.

STEP export writes the component tree as an assembly.

Right-click a component in the Browser and choose Properties to inspect material-aware mass, volume, surface area, centre of mass and world bounds. Descendants and repeated instances contribute to assembly totals; pending moves are included. A component uses its first placement; occurrence.properties selects a specific instance. Root Properties measures the complete assembly. Volumes are summed, including overlapping bodies, rather than measuring their union. The same workflow is available through component.properties and occurrence.properties; see placement and measurement details.

Part properties and the bill of materials

A component definition carries its own part properties: a part number, a description and a revision, other tools’ data under a reverse-DNS key (the same rules as the design’s own properties), and free text properties such as a material grade or a finish. Every occurrence of the component shares them, Paste New copies them, and they are saved with the component. component.metadata {component} reads them and component.metadata.set {component, part_number?, description?, revision?, values?, properties?} changes them in one undo step (an empty value removes a field). The root component is the design itself: its properties are document.metadata’s. Standard parts (parts.insert) get a part number from their standard and size (ISO 4762 M6x20, or a bearing’s designation) and a description; Change Part Size renumbers them, keeping a field you changed yourself.

Bill of Materials (assembly.bom, on the INSPECT panel) counts the placed components:

• levels: "flat" (the default) lists the parts at any depth, each counted through its subassemblies: a part placed once in a subassembly that is placed twice counts 2. A subassembly is listed through its parts, unless it has bodies of its own.
• levels: "top" lists the direct children, a subassembly as one row.
• group_by: ["part_number"] (the default) puts definitions with the same part number in one row; a definition without a part number gets a row of its own. ["definition"] gives every definition its own row.
• group_children: true keeps what is placed inside a part with a part number in that part’s row: a bolt with a washer and a nut placed inside it is one row, the washer and the nut listed under it as children (items 1.1, 1.2…, with each per bolt and count in all) instead of rows of their own. Bolts with different contents (one with a nut, one without) are different rows. total_occurrences counts the children too, so it is the same either way.
• component lists one subassembly’s parts instead of the design’s.

Rows are sorted by part number (rows without one come last) and hold item, part_number, description, revision, count, definition (the component names), components (their ids) and properties, with total_occurrences beside them. path writes them to a .csv file (the columns item, part_number, description, revision, count and definition, every field quoted; children follow their row) or a .json file. The window lists the same rows, switches between the levels and groupings and shows children under their part, edits a picked row’s part number, description and revision, and exports them. Changing part properties changes no geometry, so it doesn’t evaluate the model or re-seat joints again.

Sheet metal

MODEL → MODIFY offers Convert to Sheet Metal. The SHEET METAL tab is always available (it is highlighted and selected when the active body is a sheet), and builds parts from a sheet of constant thickness under a sheet metal rule (thickness, bend radius, K-factor), set in Sheet Metal Rules (sheet.manage_rules).

• Flange: a base flange from a sketch profile, a contour flange from an open sketch, or an edge flange from a part edge.
• Hem returns a sheet edge back toward the sheet; no new sketch is required.
• Fold (sheet.fold) bends the sheet along a sketch line.
• Unfold / Refold (sheet.unfold, sheet.refold) for working on the flat part.
• Convert (sheet.convert) turns a plate of constant thickness into sheet metal, or, with bend edges, a solid or a shelled body.
• Create Flat Pattern (sheet.flat_pattern) shows the flat part with its bend lines and a bend table, and exports it as DXF or a bend-table CSV through the save picker.

Bends follow the rule’s K-factor, so flat lengths match what a press brake will make. Tests check flat lengths against hand-computed bend allowances.

A copy of a sheet metal body is sheet metal too. Mirror (solid.mirror with bodies) makes the opposite hand: its own flat pattern, DXF and bend table, the mirror image of the original’s flat, with the same thickness side, bends and flat lengths, and holes where the mirror puts them. A copy from Move (copy: true) or a body pattern keeps the original’s flat pattern. Every copy takes further sheet metal features of its own. Mirroring with combine joins the two halves into one solid, which has no single sheet model yet; mirroring or patterning flange features themselves is not supported yet.

An edge flange’s height runs along the flange to its far edge. Where it is measured from is the feature’s height_from (Height From in the Flange dialog): outer (the default, Outer Sharp) starts at the outer virtual sharp, where the lines of the base’s and the flange’s outer faces meet, so (R + T)·tan(θ/2) of it is bend before the flat leg starts (θ the bend angle, R the inner radius, T the thickness); inner (Inner Sharp) starts at the inner virtual sharp, R·tan(θ/2) before the leg; tangent is for bends past 90°, where the outer sharp runs far out: it starts at the line square to the flange that touches the outside of the bend, R + T before the leg. Up to 90° tangent is the outer sharp (at 90° the two are the same line, the base’s outer face, so the leg does not jump as the angle passes 90°). A height shorter than what lies before the leg is refused with the smallest one that fits. With a 2 mm sheet and a 2 mm radius, a 90° flange 20 high has a leg of 16 from the outer sharp or the tangent and 18 from the inner sharp; at 120° it has a leg of 13.07 from the outer sharp, 16.54 from the inner sharp and 16 from the tangent.

{"command":"sheet.flange","params":{"edges":[[50,0,2]],"height":20,"height_from":"inner"}}

Where an edge flange’s bend starts is its position (Bend Position in the Flange dialog): how far inside the picked edge the base is cut back. inside (the default) puts the outer virtual sharp on the edge, (R + T)·tan(θ/2) inside it, so at 90° the flange’s outer face is flush with the edge’s face; outside (sheet.flange also takes bend_outside and saves it as outside) starts the bend at the edge, which leaves the base whole and the bend wholly outside; middle cuts back half of inside; material_outside puts the inner virtual sharp on the edge, R·tan(θ/2) inside it, so at 90° the flange’s inner face is flush with the edge’s face and its material is outside; tangent is for bends past 90°: it cuts back R + T, so the outside of the bend is tangent to the edge’s face, touching it a quarter turn into the bend with nothing of the bend past it. At 90° that is inside. Below 90° the outside of the bend never turns parallel to the edge’s face, so tangent cuts back (R + T)·sin θ instead: the bend’s end is on the edge’s face and the leg leans on out past it.

{"command":"sheet.flange","params":{"edges":[[50,0,2]],"height":20,"angle":"120 deg","position":"tangent"}}

An edge flange takes its setback off its own edge only. Where that edge ends at an inside corner of the base (the base runs on past it, like the leg of an L), the rest of the base stays, and the rule’s bend relief (relief_width and relief_depth; Relief Width and Relief Depth in Sheet Metal Rules) is cut into it beside the bend’s end: a slot the relief width wide, from the relief depth before the bend line to the relief width past the flange’s far edge in the flat pattern. The bend and the flange are then free of the base, folded and flat. A relief that can’t be cut (a width under 0.01 mm, one as wide as the base beside the bend, or a slot that would cut the base apart) is left out, and the flange feature reports a warning saying where.

Where a cut-out has taken part of an edge away (a corner cut off the plate, a notch in the middle of an edge), an edge flange picked on that edge runs along the stretch the cut-outs leave nearest the pick, and takes its setback off that stretch only. The base on the other side of a notch keeps its edge, and a pick there, in the same feature or a later one, makes a flange of its own. Where the base is still left beside the bend’s end at such a cut-out, it gets the bend relief as above. An edge that cut-outs have taken whole is refused.

The setback is cut out of the base’s outline as it was drawn: where the bend line crosses an arc of the outline (a plate with rounded corners, bent inside or in the middle), the arc stays an arc and ends there, in the flat pattern and the DXF. A free-form curve (an ellipse, a spline) in an outline that a setback cuts is followed by tangent arcs within 0.001 mm.

Where two bends of one edge flange feature meet at a corner of the base, the rule’s corner relief shape (corner_relief_shape; Corner Relief Shape in Sheet Metal Rules) says what is cut there. notch, the default, cuts nothing more: the bends end square at the corner, which leaves a step in the flat pattern between each bend’s end and its flange’s closed end. tear cuts no relief either, and no step: both bends run to the corner where the two bend lines meet, and each bend’s end is cut straight, in the flat pattern, from that corner to where its flange’s closed end starts. Folded, the two bends touch at the corner and open to the rule’s gap where the flanges start; the bend table lists a torn bend between the middles of its two ends. A tear whose cuts would cross in the flat pattern, or that would run one bend into the other folded (flanges at very different angles), is left out with a warning and the corner keeps its notch. round and rectangular cut a relief the size of the rule’s corner relief across, centred on the corner where the two bend lines meet: out of the base a round with half that size as its radius, or a square with half that size as its side, and both bends stop where it begins, cut straight across. The flange panels keep their ends. The relief is in the folded part, the flat pattern, the bend table (the bends are shorter) and the DXF (a round relief is an arc). At a corner that isn’t square the round follows the angle of the base and the square becomes a kite, its two cuts square to the edges. Changing the shape in a rule changes the parts made with that rule. A relief that doesn’t fit (under 0.01 mm across, leaving nothing of a bend, or reaching as far from its corner as another edge of the base is) is left out, and the flange feature reports a warning saying where. The reliefs at all the corners are cut together, so a corner’s relief does not depend on the order the corners are cut in; two of them that would overlap are both left out, each with a warning saying which the other is.

{"command":"sheet.manage_rules","params":{"name":"Sheet 2 mm","thickness":"2 mm","k_factor":0.5,
 "bend_radius":"1 mm","corner_relief_shape":"round","corner_relief":"8 mm","active":true}}

The rule’s shape and size are the default. An edge flange feature can choose its own for the corners its flanges make: corner_relief_shape (notch, round, rectangular or tear) and corner_relief (the size across, a length or an expression) in sheet.flange, or Corner Relief Shape and Corner Relief in the Flange dialog. In the dialog, Rule as the shape and an empty size take the rule’s; either one left out follows the rule while the other is the feature’s. Corners are relieved only between the flanges of one feature, so a feature’s choice never meets another’s at a corner, and two edge flange features of one part can have different reliefs under one rule. A base or contour flange takes its corners from the rule only and refuses both parameters. The flange gap and the rule’s other values stay with the rule for every flange. The feature’s choice is saved with the design (file format 23).

{"command":"sheet.flange","params":{"edges":[[60,0,2],[120,45,2],[60,90,2],[0,45,2]],
 "height":20,"corner_relief_shape":"round","corner_relief":"6 mm"}}

Where the edge flanges of one feature meet at a corner of the base, their panels are closed toward each other at any bend angle: each end is cut square to the sheet, on a line in the flat chosen so that the edges nearest each other (on the inner faces) run parallel, the rule’s gap apart, either side of the plane halfway between the flanges. Flanges at 72° get slanted ends in the flat; corners that aren’t square close the same way, and at 90° it is the corner the rule always gave. A corner that can’t be closed (a gap under 0.01 mm, flanges bending opposite ways, ends that would overlap in the flat pattern) stays open, and the flange feature reports a warning saying where. A flange added by a later feature leaves the corner as it was: the earlier flange keeps its length and the new one ends at its bend.

The flanges of one edge flange feature can each have an angle and a height of their own. An entry of edges is a point [x, y, z], which takes the feature’s height and angle, or an object {"point": [x, y, z], "angle": "105 deg", "height": "30 mm"} whose angle and height (either one, or both) replace them for that edge. They are expressions like the feature’s own, so parameters work, and each is a feature input of its own (Edge angle, Edge height) after Height and Angle. The corners between such flanges close like those between equal ones: the ends run toward each other the rule’s gap apart, either side of the plane halfway between the two flanges, and a taller flange’s end keeps that line up to its own tip. This is how to close a corner between flanges at different angles, because flanges of separate features don’t close toward each other. In the Flange dialog, picking more than one edge shows a row per edge with an angle and a height box; an empty box takes the value above.

{"command":"sheet.flange","params":{"edges":[[60,0,2],{"point":[120,45,2],"angle":"90 deg"},
 {"point":[60,90,2],"angle":"105 deg","height":"30 mm"},{"point":[0,45,2],"angle":"120 deg","height":"25 mm"}],
 "height":38.6,"angle":"75 deg"}}

An edge flange can bend more than once: then lists further bends, each an angle and a height, and each is a flange on the far edge of the one before it, made in the same command and undone with one step. It is the way to make a flap with two or more bends that is part of the same sheet (a Contour Flange is always a sheet of its own). The example bends the end edge of a wall 45° outward, then 45° again, the second leg 80 mm long. Each bend is a flange feature of its own in the timeline, so each can be edited there. In the Flange dialog, an edge flange has Further Bends under Bend Position: Add bend adds a row with an angle and a height, and the bin beside a row takes it out.

{"command":"sheet.flange","params":{"edges":[[1,0,20]],"height":40,"angle":"45 deg",
 "then":[{"angle":"45 deg","height":80}]}}

A further bend turns the way the one before it did. "flip": true on a bend turns it the other way, which makes an offset (a jog): bend 45° out, then 45° back, and the last leg runs parallel to the first. In the dialog each further bend has a turns choice, Same way or Other way.

When the shape is easier to draw than to count out, Path Flange (sheet.path_flange) makes the same chain from a sketch. Sketch an open chain of lines on a plane across the edge (square to it), starting at the edge, then pick the edge and the lines. Each line becomes a flange as long as the line (measured like an edge flange’s height: to the outer face from the virtual sharp), and each corner a bend. The first line’s angle to the sheet sets the first bend, and the path’s turns set which way each later bend goes, so a jog is just a path that turns back. Changing the sketch changes the flap. It is one feature in the timeline and part of the same sheet. Lines that run straight on from each other count as one; a line that does not turn from the sheet is refused, and so is a line too short for its bend. Arcs are not supported yet.

{"command":"sheet.path_flange","params":{"edge":[1,0,20],"sketch":"Path","curves":["p1","p2"]}}

A flange can also stand on the far edge of another flange: a return, such as a lip turned in along the top of a tray’s walls. It runs along that edge from end to end, so it follows the closed end of the flange it stands on, slanted or not. Two returns of one feature whose flanges meet at a corner of the base are closed toward each other as well, with the rule’s gap. They are mitred either side of a plane that runs along the mean of the two panels’ normals, bisects their bend lines and passes where the lines their panels start on cross. Returns that lie in one plane (level returns on a tray’s walls, whatever the walls’ angle) then meet on the corner’s bisector, like the sides of a picture frame. Each panel ends on a slanted line in the flat. Each bend stops square where all of it keeps half the gap from that plane, at the latest at the end of the flange it stands on, which can leave a short stretch of that flange’s edge bare. Returns turned opposite ways pass each other. A return that meets no other at a corner ends with the flange it stands on; where the flange beside that one leans in over it, the return is cut back until it keeps as clear of that flange as the end of the flange it stands on does. Returns that can’t be closed stay open with a warning, as on the base. Returns of separate features don’t close toward each other either: make the returns round a corner in one feature. A corner relief or a tear changes none of this: it leaves the flanges’ closed ends as they are, so the returns on them close over a relieved or torn corner as over a whole one.

{"command":"sheet.flange","params":{"edges":[[60,2,20],[118,45,20],[60,88,20],[2,45,20]],
 "height":12,"angle":"90 deg"}}

(The four returns of a 120 x 90 tray in 2 mm sheet with 90° walls 20 high: each point is the middle of a wall’s far edge on its inner face, so the returns turn in over the base.)

A flange can stand on a straight side edge of an existing flange as well. Select that edge and the adjoining edge of its supporting panel in one feature to close the new flanges across the existing bend. The panels are mitred with the rule’s gap; round and rectangular corner reliefs cut a rounded or rectangular slot across the existing bend zone in the flat material. The slot’s width is corner_relief, and it survives unfolding, refolding and DXF export. notch keeps the gap without another cut. A tear across an existing bend is not supported yet and leaves the notch with a warning. A mitre that would overlap the flat pattern stays open with a warning. Side-edge setbacks on curved panels or on only part of an edge left by a cut-out are not supported yet. The edge connecting a panel to its existing bend is not a free edge. See examples/regressions/sheet-side-flange-corner.json for a small reproduction.

Convert also takes a solid or a shelled body: pick the face that stays fixed and the sharp edges that become bends (bends; Bend Edges in the dialog). The flat faces reached from the fixed face across those edges become the sheet. A shelled body keeps its walls and their thickness; any other solid’s faces become the outside of the sheet, with the rule’s thickness taken into the body. Each sharp edge stays where the faces of its bend would meet, so the part keeps its envelope and the flat pattern is the outside lengths less a bend deduction per bend, 2·(R + T)·tan(θ/2) − θ·(R + K·T). A bend can be picked on either skin of a shell; bends turn either way, follow one another and take any angle (the walls of a tapered tray at 72°). An edge between two faces of the sheet that is no bend is cut open, each side half the rule’s gap from the plane halfway between the two, like the corners of a tray. A bend drawn as a chamfer (a flat strip between two faces, the chord of the bend’s arc, as models without bend radii draw one) is picked in the middle of the strip: the two faces then meet at their virtual sharp in one bend of the rule’s radius, and the strip is no face of the sheet. A bend modelled with its radius (a cylinder between two flat faces tangent to it, as sheet metal parts from other systems come, or a filleted edge) is picked anywhere on its cylinder, on either skin, and converts the same way: the sheet is bent there with the rule’s radius and K-factor, not the modelled radius, so the flat pattern is the one the rule makes. The result is an ordinary sheet body: edge flanges, cuts, Unfold, the flat pattern and its exports work on it, and it follows the solid when a parameter changes (the edges and the fixed face are found by their names). Without bend edges Convert expects a plate, as before. Either way round walls (holes, slot ends, rounded corners, notches) stay circles and arcs in the flat pattern and the DXF, also where a STEP file writes one in pieces, and the holes and slots of every face of the sheet are its cut-outs, where the bends put them. An engraving in a face of the sheet (a recess with a flat floor, at most half the thickness deep) becomes a pocket of it, as a plate’s does (below), on either skin of a shell. Not converted yet: curved faces other than bends (rolled sheet), with bend edges a hole or an engraving that reaches into a bend or a pocket deeper than half the thickness (cut them after converting), and bends that close a ring.

A plate may carry recesses in one of its faces, such as an engraved label or a counterbore: a recess with a flat floor and walls square to the plate, at most half the plate’s thickness deep. Each becomes a pocket of the sheet (see the pockets below), so the converted part keeps it: the sheet is as thick as the plate, the flat pattern is the whole plate with the recess listed under pockets (its outline, side and depth), and the DXF draws its outline on the pocket layer of its depth, apart from the cut contours, for a laser to mark rather than cut. The face the recesses are in can be the one picked or the other. A recess deeper than half the thickness, recesses in both faces, and a plate whose recesses are larger than the face around them (a thinner plate with raised parts) are refused with the reason. A recess lies in an opening of the face it is cut into, so the faces of a bent part’s legs are none: a bent part is refused as no plate, and converts with its bend edges. A bend across a pocket is refused as for any pocket, so fold or flange clear of an engraving.

{"command":"solid.box","params":{"length":100,"width":60,"height":30,"body_name":"Tray"}}
{"command":"solid.shell","params":{"faces":[[50,30,30]],"thickness":2}}
{"command":"sheet.convert","params":{"body":"Tray","face":[50,30,0],
 "bends":[[50,0,0],[100,30,0],[50,60,0],[0,30,0]]}}

The face can also be the name model.faces lists for it ("face":"F1:+z"), which saves computing a point on a face with holes or a curved outline: model.faces gives every face a point that lies on it.

For a shop drawing or spreadsheet, sheet.export_bend_table returns CSV by default; choose format: "json" for structured data. It includes the sheet rule, thickness, bend angles, radii, allowances and flat centre-line coordinates. Each bend has its bend angle (angle_deg) and its included angle (included_angle_deg, below; the CSV’s last column, so the columns before it keep their places). Lengths use millimetres and angles use degrees. A bend is listed where its centre line has material: one that a cut-out has shortened gives the length and ends it has left, and one that cut-outs split gives a row for every piece, all with the bend’s number (the flat pattern and the DXF draw the same pieces as bend lines). Supply path to save it, or omit path to receive the content through the command response. body defaults to the last sheet body. Exporting does not add a timeline entry or consume an undo step.

{"command":"sheet.export_bend_table","params":{"format":"csv","path":"bracket-bends.csv"}}
{"command":"sheet.export_dxf","params":{"path":"bracket-flat.dxf"}}

The DXF is an AutoCAD 2000 (AC1015) drawing in millimetres, made for a laser-cutting shop’s nesting or CAM software: each kind of line is on a layer of its own, with a colour (AutoCAD’s index) and, for the bends, a linetype that the file defines.

OUTLINE, CUT, BEND_UP and BEND_DOWN are always in the layer table, the others when the sheet has something for them. The inner contours (CUT, TEXT) are written before the outline, so a program that follows the file’s order cuts inside-out.

A round hole is a CIRCLE, a circular arc an ARC, a whole ellipse one ELLIPSE and an arc of an ellipse an elliptical ELLIPSE; the pieces of a spline, the outlines of text and the other conics are SPLINEs of their own degree, so no curve is written as chords. For a machine that reads only lines and arcs, pass "curves": "arcs" to sheet.export_dxf: the free-form curves are then tangent arcs and lines within 0.001 mm.

Letters are told from other cut-outs by where they came from: a cut whose sketch holds text (Sketch Text) marks the cut-outs it makes as letters, counters included, while the design is built; nothing more is saved in the design file. A letter that another cut-out overlaps, or that the sheet’s edge clips, has become one shape with it and stays on CUT.

{"command":"sheet.export_dxf","params":{"path":"tray-flat.dxf","text":"etch","bend_notes":true}}

With "bend_notes": true each bend line gets a note on BEND_NOTES, B1 UP 90° R1 (the bend’s number, its direction, its angle and its inner radius; %%d is AutoCAD’s degree sign). It is 3 mm high ("note_height" changes that), centred half a height beside the middle of the line, parallel to it and readable from below or from the right. A bend that cut-outs split has a note for each piece. Notes are off by default, because a program that cuts or marks every layer would mark them.

For a program that cuts every line it is given, "bend_lines": false leaves the bend lines out (BEND_UP and BEND_DOWN are then empty), and "layers": "single" writes every entity on layer 0 instead of a layer for each role.

A bend’s angle is how far the sheet turns from flat. Many press brakes are set by the included angle instead: the angle left between the bend’s two sides, 180° less the bend angle. A 90° bend is 90° either way, but a 58° bend is set as 122°. The rule’s angle_display (Angle Display in Sheet Metal Rules) says which one the DXF’s bend notes give: bend (Bend, the default) or included (Included). Under an included rule the note of a 58° bend reads B1 UP 122° R1. The bend table gives both angles whatever the rule says, in columns of their own (angle_deg and included_angle_deg), so neither is taken for the other. The setting does not change the flange angle yet: angle in sheet.flange and in the Flange dialog is always the bend angle, so a 122° included angle is a flange at 180 deg - 122 deg. A design keeps the setting in its rule, so templates made from it read their bends the same way.

{"command":"sheet.manage_rules","params":{"name":"Sheet 2 mm","angle_display":"included"}}
{"command":"sheet.flange","params":{"edges":[[50,0,2]],"height":20,"angle":"180 deg - 122 deg"}}
{"command":"sheet.export_dxf","params":{"path":"bracket-flat.dxf","bend_notes":true}}

A design with several sheet bodies exports one file for each with "per_body": true: the files are <path>-<body>.dxf (characters a file name cannot hold become _; two bodies that would share a name get _2, _3…), and the reply lists them in files. Without a path it lists their DXF texts instead.

Base-flange profiles keep their interior holes. Through cuts that cross a sheet edge become notches in the flat outline; overlapping and repeated cuts remove their combined area once. The flat preview, DXF and unfolded solid use the same material boundaries. Lines and circular arcs remain exact. An ellipse, a spline or text stays the curve it was drawn as in the flat pattern and the unfolded solid; the folded solid follows it with tangent arcs within 0.001 mm, and the point lists write it as chords within 0.001 mm (the DXF keeps the curve, see above). Flat-pattern JSON lists each cut-out twice, in the same order: as points (cutouts), and exactly (cutout_shapes): a round hole as {"circle": {"center", "radius"}}, any other as its line, arc (centre, radius, start and sweep in degrees) and polyline segments (one polyline for each ellipse quarter, spline or glyph curve).

Cuts can leave separate material pieces, including the centre of a ring cut. These pieces remain one logical sheet group through Unfold / Refold and export as separate flat outlines. A cut that parts a piece from the base (a flange cut off along its bend, the part of a ring’s inside on a flange’s edge) keeps it too, folded or flat, and its warning says how many pieces are no longer joined to the base, their area and where they lie in the flat pattern. Islands inside other material (a ring’s centre, a letter’s counter) are not counted. Large profiles that exceed the geometry processing budget report an error instead of exporting a partial outline.

A Box cut, or a Cylinder cut whose axis is the sheet’s normal, machines the sheet like the extrude of its footprint: through the sheet it is a cut-out (a cylinder a round one), and part way it is a pocket. A primitive cut at any other angle, or across a folded bend, is refused.

Hole machines the sheet the same way from a flat face of any panel, the base or a flange, on either side, folded or unfolded: square to that panel, a through hole (plain or tapped) is a round cut-out of the flat pattern and a CIRCLE in the DXF, and a counterbore or a blind flat-bottomed hole is a round pocket. A hole slanted to its panel or drilled into the edge of the sheet, a countersink and a drill point are refused.

Parallel, untapered extrude cuts also preserve shallow pockets through Unfold / Refold. The pocket floor and side walls remain solid geometry; overlapping cuts from opposite sides become a through hole wherever they remove the whole thickness. Flat-pattern JSON lists pockets with their side, depth and bottom/top thickness coordinates in millimetres. DXF pocket boundaries use POCKET_BOTTOM_Z…_TO_…_MM, POCKET_TOP_Z…_TO_…_MM, or POCKET_INTERNAL_Z…_TO_…_MM layers. These are machining operations, so do not treat every pocket layer as a through-cut contour when importing the drawing into a CAM tool. (Text machined to a depth is a marking, on ETCH.)

Extrude Intersect on a straight base or an unfolded sheet retains the material inside both the current tool footprint and its depth interval, including interior holes, detached islands and earlier pockets. A shallow intersection records the removed layers above and below the retained material as top and bottom pockets. The sheet rule keeps the original stock gauge; the remaining solid can be thinner. A completely empty intersection removes the sheet and its metadata together. DXF records pocket depth in its layer names; importing that DXF as ordinary sketch geometry does not reconstruct the machining depths automatically. Each positive retained or removed depth layer must meet the kernel’s 0.000001 mm extrusion resolution; smaller layers report an error rather than being rounded away. To Object can retain a tool that trims to a straight prism, using its actual trimmed footprint. A curved tool with varying depth is refused before changing sheet geometry. Pocket profiles can move with planar panels when forming, but a pocket crossing a bend zone cannot yet be refolded. Machining folded bend material, tapered sheet cuts and other unsupported 3D sheet Cut/Intersect operations report an error before changing the design; they cannot silently restore removed material during a later sheet rebuild.

Other features that change a sheet body’s material without the sheet knowing it (a fillet or chamfer on a corner, an extrude joined onto it, a Mirror or Combine joined into it) are not in the flat pattern yet. Such a feature warns, and while the body carries its change the flat pattern, the DXF and the bend table are refused with an error that names it, rather than writing a part that does not match the body. A later sheet metal feature rebuilds the body from its sheet features and says that the change is not kept. Moving the body, splitting its faces and cosmetic threads leave the flat pattern as it is.

A sketch can be drawn on a flat face of the sheet: the base or a flange, on either side. Pick the face (or give sketch.create the point plane: {face: [x, y, z]}) and the sketch attaches to that panel instead of to a certified source face. It keeps the face’s name, sheet:<body>:<panel>:<top|bottom> (the panel is base or the flange’s feature tag), and finds the face again whenever the sheet is rebuilt: after a parameter change such as the thickness or a flange angle, through Unfold / Refold, after the file is reopened and when the body is renamed. Sketch coordinates are the flat pattern’s, so a point drawn on a flange lies where the flat pattern and its DXF have it, and on the bottom face y runs the other way, as seen from below. When the face is gone (its flange is suppressed or deleted) the sketch reports a lost attachment instead of moving to another face; Redefine Sketch Plane attaches it to another face. fixed: true still freezes the picked plane in space.

Every face of a folded sheet has a name of that kind, which model.faces lists as sheet_face: <panel>:top and <panel>:bottom, <panel>:rim.<edge> for a rim (a base sketch line’s id, or a flange’s far, side0, side1; rim.bend0/rim.bend1 for a bend’s flat ends and rim.ext0/rim.ext1 where a flange runs on past its bend toward a neighbour), and <flange>:bend.inner / <flange>:bend.outer for a bend’s curved faces. A command that takes a face name takes it too (sheet:Body1:F3.1:top), and finds the face from the sheet itself, so the name stays with that face while the sheet’s sizes change and other flanges come and go. Faces the sheet does not describe (a hole’s wall) have none.

Plastic parts

MODEL → CREATE lists the plastic enclosure features:

• Boss (plastic.boss): screw bosses with a hole, fillets and optional ribs.
• Lip / Groove (plastic.lip): the mating lip and groove along a shell’s opening.
• Snap Fit (plastic.snap_fit): a cantilever snap hook and its catch.
• Rest (plastic.rest): a pad for a part to rest on.
• Plastic Rules (plastic.manage_rules, plastic.assign_rule): wall thickness, draft and clearance per material, used as the features’ defaults.

Plastic Rules are in MANAGE → RULES. Rib and web in MODEL → CREATE complete the set. These features are checked against hand-computed geometry.

Import and export

Opening a STEP, IGES, FreeCAD or Rhino file creates a design with the file’s bodies as a base feature, and inserting one adds them to the current design. Later features build on them. Mesh bodies render, measure, move and export, but solid features need B-rep bodies.

Every imported file (STEP, IGES, 3MF, STL, OBJ or glTF) comes in as a new component named after the file, so its bodies never mix with yours. A STEP assembly keeps its structure: its parts and sub-assemblies become nested components, and a part used several times is one component with an occurrence for each place. The imported assembly is rigid: moving its component moves everything, and its parts don’t move on their own. Right-click the component and choose Unlock Contents to joint the parts one by one. Undo removes a whole import in one step.

A glTF file (.glb, or .gltf with the .bin files it names in the same folder) comes in the same way: its nodes become nested components, a mesh placed several times is one component with an occurrence for each place, and the whole import is rigid until you unlock it. glTF is in metres with Y up, so the import is scaled to millimetres and turned to stand Z up (up: "z" keeps the file’s axes). Each material’s base colour, metal and roughness become the body’s appearance, so the model looks right in Render; textures, skins and animations are not imported. Scaled or mirrored nodes are baked into their meshes. Compressed meshes (Draco, meshopt) are refused with a message: save the file uncompressed first.

A 3MF project saved by a slicer comes in too, also when it keeps its objects in model parts of their own inside the file (the 3MF Production extension): each object on the build plates becomes one mesh body, with all its volumes merged where the slicer placed them. Each body is named after its object: the name in the model, else the one the slicer keeps in its project settings (Bambu Studio’s Metadata/model_settings.config), else Mesh1, Mesh2, … Other slicer-only data (modifier, negative and support volumes, painting, per-object settings) is not read: modifier and negative volumes come in as ordinary solid geometry.

File → Export STL… and File → Export 3MF… (also Save As Mesh on the Insert tab’s Files panel, and in the right-click menu of a body) open the same dialog with that format chosen; it saves the selected bodies as STL, 3MF or 3MF with face tags (below) to a file you name, and you can change the format there.

File → Send to Slicer (also on the Insert tab’s Files panel, and in the right-click menu of a body) is the short way: it saves the selected bodies as a 3MF in millimetres, without face tags, and sends it to a slicer. It always asks which one and pre-selects the slicer you used last time, so the usual case is one click or Enter. The list shows the slicers found on the computer with their icons; Custom… adds any other program to the top of the list (kept between runs; hover an entry you added and press Delete to remove it). On Linux only, a program whose desktop entry says it opens 3MF or STL files is listed even if SolidCraft doesn’t know it by name. Windows and macOS list the known slicers only, found in the usual program folders and on PATH. It falls back to an STL if the 3MF can’t be written. Scripts and the control channel use file.send_to_slicer with a slicer, which sends without a dialog. They can start only the slicers in the list and programs you added under Custom…; any other program path is refused, and an AI agent’s request to save a mesh or send it to a slicer asks first and names the slicer.

The list also has a plain EasyPrint (Printables, in the browser) row, and it is the one entry that works in the browser build too. EasyPrint is Printables’ slicer, so choosing it uploads the selected bodies (a 3MF, 100 MB at most) to Printables’ servers and opens the model there in your browser. The link expires after 30 minutes, and you need to be signed in to Printables. SolidCraft asks once before the first upload and remembers that you agreed. Nothing is uploaded unless you pick this row. SolidCraft isn’t affiliated with Printables. Scripts use file.open_in_easyprint, which refuses unless it gets consent: true, and an AI agent’s request to use it asks first.

Files sent to a slicer go to a folder only you can read: ~/.cache/solidcraft/slicer on Linux, ~/Library/Caches/SolidCraft/slicer on macOS and %LOCALAPPDATA%\SolidCraft\slicer on Windows. The name stays the same for the same design and the same bodies, so sending again replaces the file the slicer has open: use the slicer’s Reload from disk to pick it up. If Windows won’t let the file be replaced because the slicer holds it, the new copy gets a number (name-2.3mf) and the status line says so. Files older than seven days are deleted the next time SolidCraft starts.

If the slicer is already running, PrusaSlicer, SuperSlicer and Cura load the file in the open window instead of starting another one (they are started with --single-instance). Other slicers, Bambu Studio and OrcaSlicer among them, are started as they are, so they may open a second window. You can turn this off in Preferences → General, except for PrusaSlicer 3.0, whose launcher can’t hand a file to a running window without it. Scripts pass single_instance: false to file.send_to_slicer or file.save_mesh.

PrusaSlicer 2 and 3 behave differently, so SolidCraft reads which one an install is from the version in its installed metadata (a Flatpak’s own files, or the metainfo file of a package); it never runs the program to ask. PrusaSlicer 2 is sent the file with --single-instance. PrusaSlicer 3 is started on its own first, SolidCraft waits up to ten seconds for it to be ready, and then sends the file. If the version can’t be read, the command decides: the slic3r-app-launcher launcher is treated as PrusaSlicer 3, and any other entry is left as it is.

Closed mechanical meshes with a constant cross-section can be rebuilt as solids with the mesh.convert command (command palette, scripts and the control channel).

File → Export 3MF… with the format changed to 3MF with face tags (file.export or file.save_mesh with format: "3mf-tagged") writes an ordinary 3MF in which every triangle also names the B-rep face it lies on and every coordinate is the tessellation’s own double-precision value. Meshing and analysis tools can use the tags to keep a model’s faces (for loads, boundary conditions or feature edges); other 3MF readers ignore them. The format is specified in docs/formats/3mf-face-tags.md.

File → Export URDF… (file.export with a .urdf path) writes the assembly for robot simulators and ROS: a link per component placement with its mesh, mass and inertia, and the assembly’s joints, so the parts move in the simulator as they do in SolidCraft. The meshes are written as STL files next to the .urdf. See docs/urdf.md.

Saves are atomic: a crash at any moment leaves either the old file or the new one, and the replaced version is kept as <file>.bak. A save keeps the file’s permissions, and a design opened through a symbolic link (a synced folder linked into a project) is saved into the file the link points to, so the link stays. Unsaved changes in every open tab are autosaved to separate entries in a recovery folder, and the next launch offers to recover each design. Saving or closing one tab removes only its recovery entry. Older design files are upgraded on open, and files from a newer version are refused with a message.

Save writes a container by default; files named .json keep JSON on subsequent saves. Save As offers a container or plain JSON on desktop; Save As JSON is also available in the File menu on desktop and web. Choose the .json extension for plain JSON. Export Design as JSON writes an independent, self-contained copy without changing the current file. Scripts can explicitly pass "format": "json" to file.save or file.save_as even with a .solidcraft name. Opening detects the format from the contents, so existing JSON designs keep working. Containers favor fast reading and saving by default. Scripts can request "compression": "compact" when file size matters more than CPU time.

Containers deduplicate identical STEP, mesh and image payloads. Mesh coordinates retain their original double precision; this is not a conversion to STL. Geometry still rebuilds from the timeline when opening. When a saved display preview is available, desktop Open shows it while checking geometry; editing starts after the complete rebuild. Cancelling keeps the current design. Previews cannot be edited or measured. Scripts can opt in to a disposable geometry cache with cache: true on warm saves; saving never rebuilds cold geometry just to create one. Ordinary saves and browser downloads default to cache: false. An additional display-mesh cache remains opt-in with preview: true. Unsupported or mismatched caches are ignored. Browser opening still rebuilds synchronously. Warm saves with explicit cache: true can also include a small PNG thumbnail. It travels with the file, so Home can show the recent design without reconstructing it when no local picture is available. Missing or incompatible pictures use the usual thumbnail generation. The default cache: false omits the portable thumbnail too. The repository’s docs/design-container.md describes limits and encoding details.

Designs are saved in the newest format this version of SolidCraft knows ("format": "solidcraft/N" in the file). It opens designs of every older format and upgrades them as they open; a design from a newer version asks you to update instead of being guessed at. Development (nightly) builds save a format number no release reads yet.

Sketch patterns retain their live direction-line references and placement settings when saved. Older patterns keep their fixed vector directions and original placement defaults.

Upgrading keeps what a design meant. Designs keep recorded body transfers, explicit 3D curve coordinate spaces and certified face bindings, alongside semantic configuration styles, associative free-form offsets and cylindrical emboss selections. Older ownership maps, geometry and expressions retain their saved meaning. Legacy 3D curves with retained associations receive their producer’s coordinate-space marker without changing any saved points; detached curves retain world coordinates. A lost cross-component association refreshed by an older build may need an explicit relink or refresh when its source returns. Loading never guesses a numerical correction. Association records, coordinate arrays and placements are bounded and checked.

Design properties

File → Design Properties… (also under Document Settings in the Browser, and on the top component’s right-click menu) records who made a design and what it is: project, part number, revision, author, organization, description and licence. OK applies the changes as one undo step. Scripts and agents use the same commands: document.metadata reads them, document.metadata.set (key and value, or values: {key: value, …}) and document.metadata.remove (key or keys) change them. document.inspect and the MCP inspect_design tool include them.

Exports carry them where the format has a place for them:

The part number and revision have no standard place in these formats and stay in the design.

In the file they are one optional top-level metadata object; a design without properties has none, and is saved exactly as before:

"metadata": {
  "project": "ACME enclosures",
  "part_number": "ACME-1042",
  "revision": "B",
  "author": "Jane Doe",
  "organization": "ACME",
  "description": "Vented case for Raspberry Pi 4",
  "license": "CC-BY-4.0",
  "com.acme.description": { "shop_id": 88123 },
  "org.printfarm": { "slicer_profile": "PETG-0.2", "internal_id": 4 }
}

• SolidCraft’s keys are unprefixed and hold text. Every other unprefixed key is reserved for later SolidCraft versions.
• Other tools keep their data under one reverse-DNS key of their own (com.example.tool: two or more dot-separated labels of letters, digits, - and _), holding an object. A tool writes only under its own key and leaves the others alone.
• SolidCraft keeps every key as it is through open, edit and save, in both the container and plain JSON, and never checks what another tool wrote: a well-known key holding something other than text ("author": 42) is kept, reads as absent, and never stops the design from opening. Typing over it in Design Properties replaces it.
• Other tools’ keys are never exported; Design Properties lists them read-only.
• Keep values small: document.metadata.set refuses text over 4 KiB, an object over 64 KiB or nested more than 32 levels deep, and more than 256 keys or 256 KiB in all. Binary data belongs in a file next to the design.

Design properties are first saved in format 21. Inserting or linking another design doesn’t copy its properties; Save As keeps them. A command script of the design (timeline.export_script) sets them in one step.

Designs in shared or synced folders

A design kept on a network share or in a synced folder (Dropbox, OneDrive, Syncthing, Google Drive) can be open on two computers at once. The desktop app watches for two writers:

• Open elsewhere. While a design is open, SolidCraft keeps a small lock file next to it, .~<file>.lock (computer, user, SolidCraft version, when it was opened), refreshes it every minute and removes it when the design closes. Opening a design that another SolidCraft has open says so: Open Read-Only (look at it; Save asks for a new file), Open Anyway or Cancel. A lock not refreshed for three minutes (left by a crash or a lost connection) is ignored. Lock files never show in Open or the recent lists, and a design in a folder you can’t write to still opens.
• Changed on disk. SolidCraft remembers the file’s size and modification time when it opens or saves a design. If another program or computer wrote the file since, Save asks first: Save a Copy (the default), Overwrite or Cancel.

Scripts, the CLI and the control channel never get these questions. doc.open opens the design and reports open_elsewhere in its result (read_only: true opens it read-only), and file.save over a file that changed on disk fails with an error until it is given overwrite: true.

Saving in the web app

In Chrome, Edge and Opera, Save As opens your browser’s save dialog and writes the .solidcraft file to the folder you choose, and Open opens the browser’s open dialog. Save then writes back to that same file. The browser remembers the file, so after you reload the page the first Save asks once for permission to write to it, and carries on. A design you open from your computer saves back to the file you opened.

In Firefox and Safari, which can’t write to a folder, Save and Save As keep designs in this browser’s private storage instead, and the app says so. Clearing the site’s data can remove those designs. Download a copy to keep it outside the browser or move it to another device.

To get a copy as a download in any browser, choose File → Download design. It holds the current design, including its unsaved changes. In File → Files in this browser… (and in Firefox and Safari, File → Open), Download open design does the same, and Download beside a stored file gives its last saved contents. Whether a folder chooser appears depends on your browser’s download settings.

Use Open from computer… in the same window to open a design from your computer; where the browser can write to a folder it saves back to that file, otherwise it works on a copy kept in the browser. Use Rename beside a stored file to change its name. Autosave and recovery stay in the browser’s private storage in every browser. Exports such as STEP and STL are downloaded.

Keyboard shortcuts

Command shortcuts can be changed in File › Keyboard Shortcuts; these are the defaults.

Click a binding to record a new shortcut. A shortcut can contain Shift, Ctrl/Cmd and Alt/Option modifiers plus exactly one other key. Hold the modifiers, then press the final key; you can take your time assembling the modifiers before that key. The recorder also allows modifiers to arrive after the ordinary key: it previews the chord and waits one second after the last added modifier, and until all keys are released, before confirming. For example, record Shift+Cmd+M for Sketch Mirror on macOS. Escape cancels recording without changing the old binding. Pressing two different ordinary keys cancels the attempt.

The binding button shows modifiers immediately as you press them, even before adding the ordinary key. Releasing a modifier before that key removes it from the preview. A status line tells you to add a key, release all keys, or wait for confirmation; the proposed chord stays visible during confirmation. Nothing is saved while the preview is still pending.

On macOS, the editor, Help list, toolbar hints, context menus and S search display Cmd and Option. Existing settings retain SolidCraft’s Ctrl/Cmd alias for the primary modifier; Control and Command pressed together are recorded explicitly as Ctrl+Cmd. Conflicting bindings still require confirmation, and built-in reserved shortcuts remain reserved. Recording changes app settings, not the design file.

This follows the usual modifier-before-key convention documented by Apple and the key-event and modifier-state model documented by W3C. The one-second grace period is SolidCraft’s recording aid, not a standard-mandated delay; using an already assigned shortcut has no added delay. Operating systems and browsers can intercept reserved combinations before SolidCraft receives them. Choose a different chord if that happens; recording is cancelled if the app loses focus.

L, R and C start their tool family (lines, rectangles, circles) in the variant you used last, as the family’s toolbar button does: after a Midpoint Line, L starts a Midpoint Line again. Pick another variant from the button’s drop-down (or the Sketch Palette) and the key starts that one from then on. The choice is kept across designs and restarts. With Pressing a tool’s shortcut again switches its mode on (Preferences › Sketch), pressing the key again before the first click steps to the family’s next variant.

Keys handled by the window itself:

While a value box has the keyboard (a dimension being added, a dialog field), keys type into it and single-letter shortcuts don’t fire. With Sketch Dimension (D), the box opens as soon as you click a line, circle or arc (or the second point or line), so D, click, type the value, Enter. With Preferences › Design › Step values with the arrow keys and the wheel on, ↑ ↓ in a value box, or the wheel over it, step a plain number by 1 (with Shift by 10, with Alt by 0.1); see Parameters and expressions.

Mouse and touch:

Help › Keyboard Shortcuts in the app lists the current bindings, including any you changed.

With the Touchpad navigation preset, hold Shift while moving the pointer to pan, or Alt/Option to orbit, without pressing a mouse button. Vertical scrolling zooms. These viewport gestures are separate from rebindable command shortcuts; mouse-button selection and editing keep their existing modifiers.

Sketch modifiers

While drawing or dragging a sketch point:

Change the snap-suppress chord in Preferences › Sketch. Selection still uses Shift and Ctrl/Cmd to add or toggle (Preferences › Selection can make Shift add-only).

Updates and privacy

SolidCraft tells you when a newer release is out. It never updates itself without asking, and the check sends nothing about you or your designs.

What you see

When a newer stable release exists, a small accent-coloured pill reading Update to 0.14.0 (the new version) appears in the title bar next to Report a bug. Nothing pops up by itself: clicking the pill opens a small window with the new version, its release notes and three choices. In a narrower window the pill shortens to Update so the document tabs keep their room, then to its icon alone.

• Download opens the file that fits your installation (see the table below) in your browser, or the release page when there isn’t one.
• Skip this version hides the pill until an even newer release comes out.
• Remind me later hides it for three days.

SolidCraft checks every time it starts, so a release that came out since you last opened it shows up straight away, and again once a day while it stays open.

Preferences ▸ General ▸ Updates has Check for updates automatically (on by default) and Check now, which checks right away and shows the window even for a version you skipped.

Updating in one click

Where SolidCraft can replace itself safely, the window also has Update now:

Every download is verified before anything changes: its SHA-256 must match the release’s SHA256SUMS.txt, fetched over HTTPS from the same release, and, once the project signs its releases, that list must carry a valid signature by SolidCraft’s release key that names the release (see releasing). A download that doesn’t verify is deleted and the installed copy is left as it was; Download still gets the package for a manual install. On macOS SolidCraft opens the disk image rather than replacing the app itself, because the app is ad-hoc signed and not notarized: replacing it in the background would install code macOS can’t vouch for without you seeing it.

Update now needs write access to the installed file: an AppImage in a folder you can’t write to fails with a message, and Download is the way to update it.

Updating from 0.11 to 0.14

SolidCraft 0.11.0 to 0.14.0 only accept packages from the project’s old GitHub address. Since the repository moved to github.com/tangency-labs/solidcraft, every release names the new address, so these versions see that a newer release is out but find no package in it: Update now can’t install it, and Download opens the release page.

Download 0.15.0 or later once yourself, from the release page or the download links, and install it over the old version as you first installed it. From 0.15.0 on, SolidCraft accepts either address, and Update now works again. Package managers (Flatpak, Snap, WinGet, .deb, .rpm) aren’t affected.

What is sent

One HTTPS request each time SolidCraft starts, and once a day while it stays open:

GET https://api.github.com/repos/bherbruck/solidcraft/releases/latest
User-Agent: SolidCraft-update-check
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2022-11-28

Update now then downloads SHA256SUMS.txt (and its signature) and the one package from the release’s own github.com/bherbruck/solidcraft/releases/download/… links, with the same User-Agent. That’s all: no version number, no machine or user identifier, no usage data, no cookies. GitHub sees the request like any other visit to the API (your IP address, the time); see GitHub’s privacy statement. SolidCraft compares the answer with its own version on your computer.

• Offline, or GitHub doesn’t answer within 15 seconds: nothing is shown, and the check is tried again an hour later (or at the next start, whichever comes first).
• GitHub’s rate limit for anonymous requests (60 an hour per address) is respected: when GitHub says to wait, SolidCraft waits that long, Check now and the check at start included.
• Turning off Check for updates automatically stops the checks; only Check now asks.
• Setting the environment variable SOLIDCRAFT_UPDATE_CHECK=0 turns all checks off, for example on managed machines.

Builds you compile yourself, the Flatpak and the browser app never check, and Preferences shows no check controls for them. The browser app updates itself: reload the page to get the latest version. When the network is unavailable, or the update can’t finish downloading in time, the saved version opens instead, and the download continues for the next reload.

Which file Download gets

Releases attach the main packages under fixed names (see releasing), and SolidCraft picks the one matching how it was installed:

The window shows the command for Snap, .deb and .rpm installations, with a Copy button. The Flatpak has no network permission and Flatpak itself (or your software center) offers its updates, so it never checks. Release builds compare versions as semver: a nightly build counts as the release it was built after, so it’s offered only a newer stable release, and release candidates are offered their final release.

Troubleshooting: SolidCraft won’t start

0.10.0 closes a few seconds after it starts (Windows)

SolidCraft 0.10.0 crashes at startup on Windows PCs that draw with Direct3D 12 and the system shader compiler. That covers older Intel graphics, PCs without a graphics driver (the “Microsoft Basic Display Adapter”), virtual machines and Remote Desktop sessions. Install 0.10.1 or later, which fixes it. Versions before 0.10.0 don’t have this problem.

Start in safe mode

Safe mode starts with default settings (your own settings stay as they are, for the next normal start), skips the “Recover unsaved design?” offer and draws with the software renderer.

• Windows: run solidcraft.exe --safe-mode from a terminal in the install folder, or add --safe-mode to the end of a shortcut’s Target.
• macOS: open -a SolidCraft --args --safe-mode
• Linux: solidcraft --safe-mode (Flatpak: flatpak run ai.storyteller.solidcraft --safe-mode)

Setting SOLIDCRAFT_SAFE_MODE=1 does the same. From 0.10.2, if two launches in a row stop before the window opens, the next one starts in safe mode by itself. SOLIDCRAFT_RENDERER=cpu uses only the software renderer and keeps your settings.

A design won’t open or hangs while opening

• Open the previous save. Every save keeps the version it replaced next to it as <file>.bak (see Files). Copy it to a new name ending in .solidcraft, for example bracket-previous.solidcraft, and open that. Work saved after the previous save is not in it.
• Check the crash reports. If SolidCraft crashed while the design was open, the newest report in the crashes folder (see the table below) usually holds a design.solidcraft with the design as it was. solidcraft-cli crashes lists the reports.
• Unsaved designs are in the recovery folder, not next to the file.
• Report it. GitHub doesn’t accept .solidcraft attachments, so zip the file (design.solidcraft.zip) and attach it to an issue, with the crash report if there is one.

Reset the settings

SolidCraft keeps its settings and its data in the folders below. All installed versions share them. No version changes anything outside them: no system settings, drivers or registry entries. Quit SolidCraft, then rename (don’t delete) the folders. SolidCraft starts with defaults and makes new ones. Rename them back to restore your settings, or send them to us with a bug report.

On Windows, paste %APPDATA% or %LOCALAPPDATA% into the Explorer address bar to open the folder. Releases before the rename used SolveCraft folders next to these; SolidCraft only reads them, so you can leave them alone.

• The recovery folder holds autosaves of designs that were never saved. Rename the data folder rather than deleting it, so you can still open those autosaves (.solidcraft files) with File > Open.
• The crashes folder holds crash reports. Please attach the newest one to a bug report.

From 0.10.2, SolidCraft also checks the settings files at start. A file it can’t read is renamed to app.ron.bad-<time> or graphics.json.bad-<time>, and SolidCraft starts with defaults instead.

“No graphics adapter” or nothing happens at all

SolidCraft needs Direct3D 12 or Vulkan on Windows, Metal on macOS, and Vulkan or OpenGL on Linux. Without a graphics driver it falls back to the system’s software renderer (WARP on Windows, llvmpipe or lavapipe on Linux), which is slow but works. From 0.10.2, if no window can be opened at all, SolidCraft tries the software renderer once and otherwise shows a message saying what failed (earlier versions closed without a word).

On Windows, if the graphics API cannot create the window’s renderer, SolidCraft tries the remaining APIs in order: Direct3D 12 → Vulkan → OpenGL, then software rendering. The status message and Preferences › Graphics say which API failed and why. The saved graphics preference stays unchanged. With an explicit WGPU_BACKEND, a failed start shows the error and exits without switching; change or remove that variable to try another API.

Things to try:

• Install the graphics driver from the GPU maker (Intel, AMD, NVIDIA) rather than Windows Update.
• In a virtual machine, turn on 3D acceleration. Over Remote Desktop, try it on the machine itself.
• Run solidcraft --crash-log to list recent crash reports, and attach the newest one to an issue.
• On an Intel Mac (Intel Iris graphics, macOS 12), “Parent device is lost” at start comes from the Metal compiler refusing wgpu’s indirect-call validation shader. SolidCraft leaves that validation off on Intel Macs. To change it, set WGPU_VALIDATION_INDIRECT_CALL=1 (on) or 0 (off) before starting; a value you set is always kept.

The desktop stutters or freezes while SolidCraft builds bodies

Some graphics drivers hang on the shader SolidCraft uses to build bodies on the GPU, and the system then resets the GPU. SolidCraft already builds bodies on the CPU on the AMD FirePro D300/D500/D700 (Mac Pro 2013). On another GPU that does this, start SolidCraft with SOLIDCRAFT_CPU_TESS=1 set to build bodies on the CPU, and open an issue with the GPU’s name.

The interface looks blurry on Linux with display scaling

On Linux, SolidCraft runs through XWayland whenever an X display is available, because file drag and drop from a file manager only works there (niri is the exception and stays on native Wayland). A compositor that doesn’t let X11 apps scale themselves draws an XWayland window at 100 % and stretches it to the monitor’s scale, so text and icons look soft. That happens with fractional scaling (125 %, 140 %), and on GNOME 47 (RHEL and Rocky Linux 10) at any scale, 200 % included. The diagnostics in a bug report show it as about 1 physical pixel per point at a scale of 200 %.

Run SolidCraft on native Wayland instead: Preferences › Graphics › Window system › Wayland, which applies at the next start. Versions without that setting (0.21.0 and earlier) take SOLIDCRAFT_WAYLAND=1 in the environment:

SOLIDCRAFT_WAYLAND=1 solidcraft

On native Wayland, dropping files onto the window doesn’t work; use File > Open or pass the file on the command line. Wayland, XWayland and niri has the details.

SolidCraft closes right away on Windows

A graphics driver can crash the app while it starts, before SolidCraft can show anything (an old Intel Vulkan driver, igvk64.dll, did). Windows’ Event Viewer names the driver under Windows Logs › Application (“Faulting module name”).

From 0.11.1, SolidCraft on Windows starts Direct3D 12 first and loads no other graphics API when Direct3D 12 has a graphics card; Vulkan and then OpenGL are tried only on a computer without one. Earlier versions started Vulkan, Direct3D 12 and OpenGL together and preferred Vulkan. To choose the graphics API yourself, in any version, open a Command Prompt and start SolidCraft from it:

set WGPU_BACKEND=dx12
"C:\Program Files\SolidCraft\solidcraft.exe"

vulkan and gl are the other choices. setx WGPU_BACKEND dx12 keeps it for apps started from the Start menu after you sign in again. From 0.11.1 the setting can also live in graphics.json in the settings folder, as {"msaa": 4, "backend": "dx12"} (auto is the order above). Safe mode ignores it and always uses the software renderer.

With OpenGL on Windows, the window has the Windows title bar above SolidCraft’s application bar instead of using the application bar as its title bar. Some OpenGL drivers (older Intel HD and UHD graphics) otherwise show the picture a title bar’s height lower than the window, so clicks land above what they point at.

SolidCraft restarted, saying the graphics device was reset

When the graphics driver stops responding, the system resets it (on Windows, “Display driver stopped responding and has recovered”), and the graphics device SolidCraft draws with is gone for good: the window can’t draw anything more. SolidCraft then closes, keeps your unsaved changes for recovery as it does after a crash, and starts again; the new window says what happened and offers the changes back. If the device is reset again within ten minutes of that restart, the next start uses software rendering, which doesn’t depend on the graphics driver. Updating the graphics driver from the GPU maker usually stops the resets.

A design saved by 0.10 won’t open in an older version

Designs saved by a newer SolidCraft use a newer file format. Older versions refuse them with “this design was saved by a newer SolidCraft” and don’t change the file. Open them with the current version.

Save As says the file can’t be found (Windows)

If saving into Documents (or Pictures, Desktop and other protected folders) fails with a “File not found” message from the Windows save dialog and nothing is saved, Windows Security’s Controlled folder access is probably blocking SolidCraft. Windows usually also shows an “Unauthorized changes blocked” notification. Either save to a folder that isn’t protected, or allow SolidCraft: Windows Security › Virus & threat protection › Ransomware protection › Controlled folder access › Allow an app through Controlled folder access, then add solidcraft.exe.

SolidCraft and AI agents (MCP)

SolidCraft speaks the Model Context Protocol over stdio (JSON-RPC 2.0, one message per line; protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05). An agent models exactly like a person does: every tool runs engine commands, the same ones the toolbar, palette, scripts and control channel use, and never opens a dialog.

Persistent headless and bridged sessions expose asynchronous product images through the ordinary execute tool: render.preflight, render.start, render.status, render.cancel and render.export. Keep the complete returned job ID; image bytes remain in the session until explicit PNG export. See render jobs.

For how the same command surface should work in the browser (workers, tiered storage, in-tab agents), see web-runtime.md. For sandboxed plugins and parametric timeline features that also use run(command, args), see plugins.md. Desktop MCP in this document remains the reference implementation today.

Start it

# Headless: an in-process design session, no window (screenshots are drawn on the GPU).
solidcraft-cli mcp

# Headless, starting from a design file or a command script.
solidcraft-cli mcp --in part.solidcraft

# Bridged to the running app, so you can watch the agent model. The app's control channel is
# on by default (see below), so no flag is needed on either side:
solidcraft &
solidcraft-cli mcp          # finds the running app; headless when none runs (--headless forces that)

# A fixed port, or a second app: name it.
solidcraft --control 7878 &
solidcraft-cli mcp --connect 127.0.0.1:7878

The app listens by default

The desktop app opens its control channel at start-up on 127.0.0.1:27878 (or the next free port when that one is taken), unless Preferences > Assistant > “Let AI agents connect (control channel / MCP)” is off; the setting takes effect at the next start. It is reachable from this computer only, and every connection must show the token made fresh for that launch, readable only by your user account (control-protocol.md). The app writes the port to control/current.port in the same folder as its token file; solidcraft-cli mcp with no arguments reads it. --control PORT and SOLIDCRAFT_CONTROL_PORT still choose the port and apply even when the setting is off. With the setting off and no flag, the app listens on nothing.

Bridged, the server finds the app’s control token in the token file the app wrote for that port (control-protocol.md); --token T or SOLIDCRAFT_CONTROL_TOKEN give it explicitly when the app runs in a sandbox whose data folder the server can’t see (prefer the variable: command-line arguments are visible to other users in the process list).

A bridged server starts even when no app listens on that port yet, so an MCP client that launches it before the app (or after the app was closed) keeps its tools. The server’s instructions then say the app was not running, and every tool call answers with an error that starts no SolidCraft app is listening at HOST:PORT and says how to start it (solidcraft --control PORT). The first call after the app starts connects to it, reading that launch’s token. When the app quits or crashes mid-session, the next call says the same; a call that was running when it went away says the app did not answer and may have quit or crashed, after running the call or not, so inspect the design before sending a change again. A batch that could not be sent says the app is not running, so it is safe to send again.

stdout carries only protocol messages; errors go to stderr. Bridged screenshots are written to a temporary file by the app and read back by the server, so both must run on the same machine.

Parameter checking

Commands with a typed parameter contract (every new command, and more of the older ones as they are converted; describe_command shows a command’s schemas) can be checked as they are called. --param-check off|warn|strict sets the level for a headless session, including a script or recipe given with --in; the default is off, which changes nothing. warn runs the call and adds param_warnings to its result, such as unknown key `operaton`; did you mean `operation`? (a starting script’s warnings go to stderr). strict refuses the call, and the design is left as it was. Calls bridged to the app are not checked yet.

Which files the agent can reach

Tool calls read, write and delete files only inside the server’s folders:

• the folder of the open design (the --in design, or whatever the agent last opened or saved), but only when it lies strictly inside your home folder (or the temporary folder) and not in a hidden folder. Home itself, a folder above it (/, /home, /Users, a drive’s root), hidden folders such as ~/.config and folders elsewhere don’t count. Hidden files and folders inside the design’s folder (.env, .git) are out of reach too;
• SolidCraft’s own recovery folder, so doc.recovery_list, doc.recover and doc.recovery_discard work out of the box (discarding deletes only real recovery entries);
• the server’s own scratch folder (a new private solidcraft-mcp-* folder in the temporary folder), where screenshot without a path goes;
• every --allow-path DIR (repeat it for more). A folder named here is reached in full, hidden files included.

The working folder the server was started in does not count by itself, so ~/.ssh, ~/.aws, ~/.bashrc and other dotfiles are never in reach by default. stderr lists the folders at start-up and says when the --in design’s folder was left out; --allow-path adds it back.

Paths are resolved before they are compared, so .. and symlinks that lead out are refused (saving through a link writes the file it points to, so the link’s target is what counts), and a new file must go into a folder that exists (a missing folder inside an allowed one is reported as missing; it is not created and does not call for a wider --allow-path). On Windows a path must be on a local drive (C:\… or \\?\C:\…): UNC, device and NT paths in any spelling (\\server\share, //server/share, \\?\UNC\…, \??\…, \\.\…), drive-relative paths (C:file), a : in a file name (alternate data streams), reserved device names with any extension (NUL, CON, COM1.txt, …) and short 8.3 names (PROGRA~1) are refused before any file system call, and the resolved path is checked again, so a link or junction that leads to a share is refused too. This includes a sketch.text font given as a file path and the font file a design’s text names when the design is opened; installed fonts named by family still work. The server spells its own folders (scratch, recovery) with long names, so they work when the temporary folder’s path has a short name (…\NAME~1.XYZ\AppData\Local\Temp, as Windows often gives when the user folder’s name is long). A refused path is a tool error saying why.

A hard link inside an allowed folder can’t be told apart from an ordinary file, so a hard link to a file elsewhere is reachable through it; don’t keep such links in a folder you allow.

solidcraft-cli mcp --allow-path ~/designs --allow-path ~/exports
solidcraft-cli mcp --allow-any-path   # no limit (the behaviour before this option existed)

Bridged, the server sends its folders with every request (allow_paths, see control-protocol.md) and the app adds its own recovery folder and the folder of the design open in it, under the same rules, so give absolute paths: a relative one resolves against the app’s working folder, not the server’s. The app’s own file dialogs are never limited.

Tool annotations

Each tool says what it may do, for clients that ask before running tools (or auto-approve on these hints). list_commands, describe_command, inspect_design, measure, body_topology, skill_reference, crash_reports, pending and running are read-only. set_parameter, undo and redo change the design undoably. new_design replaces it (destructive). execute, batch, open, save, export and screenshot (whose path writes a file) can read, write, overwrite or delete files: they are not read-only, destructiveHint and openWorldHint are true.

Client configuration

solidcraft-cli is on PATH after every package install: the Windows installer adds its folder, the deb, rpm and FreeBSD packages install it in /usr/bin, the Homebrew cask links it, the AppImage writes a small solidcraft-cli launcher into ~/.local/bin on its first run, and the macOS app links it into /opt/homebrew/bin or /usr/local/bin when it starts (Help > Install solidcraft-cli command does it with an administrator prompt when those are not writable). Two packages keep it out of PATH by design: Snap exposes it as solidcraft.cli, and Flatpak runs it as flatpak run --command=solidcraft-cli ai.storyteller.solidcraft; use those as the client’s command (with mcp as the arguments).

The quickest way: Help > Connect AI assistants… in the app, or

solidcraft-cli mcp setup            # every client found on this computer
solidcraft-cli mcp setup --dry-run  # show what it would write, change nothing
solidcraft-cli mcp setup --client opencode --live

(mcp install is the same.) It adds a solidcraft server, using the full path of the solidcraft-cli that runs it, so nothing has to be on PATH. A client counts as installed when its configuration folder exists, and no client program is started. Supported:

The files are edited in place: only the solidcraft entries change, everything else in the file (other servers, comments, order) stays as it was, and the file is copied to <name>.bak first. A file that does not parse is left alone. Running it again after an update moves the program only refreshes the path of an entry it wrote; an entry you changed (extra arguments, another program) is left as you have it. --live also adds solidcraft-live, which bridges to the open app (port 7878, see below). Restart the client afterwards.

SolidCraft also does this by itself: when the app starts it adds the solidcraft entry to each installed client (and refreshes its path after an update), and says once which clients it connected. It never touches an entry you changed. Settings > Assistant > Make SolidCraft available to AI apps on this computer turns it off, which removes the entries it added. Runs with --control or SOLIDCRAFT_CONTROL_PORT (automation) leave your clients alone.

To configure a client by hand instead, these are the entries. OpenCode (opencode.json):

{
  "mcp": {
    "solidcraft": { "type": "local", "command": ["/path/to/solidcraft-cli", "mcp"], "enabled": true }
  }
}

Claude Code (project .mcp.json, or claude mcp add solidcraft -- solidcraft-cli mcp; a setup added under the previous name keeps working, see the compatibility notes):

{
  "mcpServers": {
    "solidcraft": { "command": "solidcraft-cli", "args": ["mcp"] }
  }
}

If a terminal doesn’t find solidcraft-cli (older Windows installers don’t put its folder on PATH; see below for where it is), give its full path (by default C:\Program Files\SolidCraft\solidcraft-cli.exe): claude mcp add solidcraft -- "C:\Program Files\SolidCraft\solidcraft-cli.exe" mcp.

Claude Desktop (claude_desktop_config.json), bridged to a running app:

{
  "mcpServers": {
    "solidcraft": { "command": "/path/to/solidcraft-cli", "args": ["mcp", "--connect", "127.0.0.1:7878"] }
  }
}

On Windows the installer puts solidcraft-cli.exe next to solidcraft.exe in C:\Program Files\SolidCraft (the portable zip has both too). Give the full path, with each backslash doubled in JSON. This configuration declares two servers: solidcraft models headless (no window; steadier for timings), solidcraft-live drives the app you have open, so you can watch the agent model. --allow-path names a folder where the agent may save and export; it must already exist.

{
  "mcpServers": {
    "solidcraft": {
      "command": "C:\\Program Files\\SolidCraft\\solidcraft-cli.exe",
      "args": ["mcp", "--allow-path", "C:\\Users\\NAME\\SolidCraft-Agent"]
    },
    "solidcraft-live": {
      "command": "C:\\Program Files\\SolidCraft\\solidcraft-cli.exe",
      "args": ["mcp", "--connect", "127.0.0.1:7878", "--allow-path", "C:\\Users\\NAME\\SolidCraft-Agent"]
    }
  }
}

Start the app with its control channel for solidcraft-live, from PowerShell: & "C:\Program Files\SolidCraft\solidcraft.exe" --control 7878, or once for every launch: setx SOLIDCRAFT_CONTROL_PORT 7878.

Open claude_desktop_config.json with Claude Desktop’s Settings > Developer > Edit Config rather than by its path: the Microsoft Store (MSIX) build of Claude Desktop can keep its data in its own package folder (%LOCALAPPDATA%\Packages\…\LocalCache\Roaming\Claude) instead of %APPDATA%\Claude, and Edit Config opens the file the app actually reads. Quit Claude Desktop completely (from the notification area) and start it again to load the servers.

Agent skills

skills/ holds five Agent Skills for agents that model through this server:

• solidcraft-modeling covers building a new part.
• solidcraft-editing covers changing an existing design.
• solidcraft-checking adds checks for errors SolidCraft does not report, regression tests and porting, next to the other two.
• solidcraft-mechanisms covers assemblies: joints placed by world coordinates, motion links, closed loops such as actuators, contact sets and motion studies, checked against analytic values.
• solidcraft-reporting turns a problem the user hit into a bug report: it reproduces it in a fresh design, shrinks it to a minimal command script, checks the numbers with measure and a screenshot, and searches existing issues first.

They cover the workflow, the command shapes, how to verify with measure, and the known traps. With them an agent builds a part in a few batch calls and reads far less output. To install them for Claude Code, copy the folders into ~/.claude/skills/; skills/README.md has the details.

The skill_reference tool returns these documents from the copies built into SolidCraft, so an agent without file access can follow them: {"skill": "solidcraft-modeling"} returns its reference.md, the default file. Mechanisms also has reference.md, checking has reference/porting.md, and every skill has SKILL.md (editing uses modeling’s reference). It never reads a path from disk, and an unknown skill or file is refused with the available choices. SolidCraft’s own chat turns the agent’s file tools off, so this is how its agent reads the skills there.

Tools

measure with items reports each item under items (length_mm, area_mm2 or position). A circle, arc, hole or other cylindrical face also gives diameter, radius, center and axis, with circumference when it goes all the way round, or arc_length and angle_deg for an arc; round says which (circle, arc, cylinder). A slot (a sketch profile of two half circles and two lines, or one half-cylinder end of a slot in a solid) gives slot: width, center_distance and overall_length. With one item these fields are repeated at the top level. With two items:

• min (also distance_mm, with from, to and delta): the closest distance;
• max (with max_from, max_to): the farthest distance;
• center_distance (with center_from, center_to): when an item is round, from its centre or axis: axis to axis for parallel axes, the closest distance between the axes otherwise, and axis to plane, line or point;
• measure: the distance the Measure panel shows first (center where there is one, else min);
• angle_deg between two planar faces or straight edges.

Earlier fields are unchanged, so older scripts keep working.

To change a feature after it is made, read its definition with execute timeline.inspect ({feature}: id or name) and change fields with timeline.edit ({feature, set}; e.g. {"extent": {"distance": "30"}}). The fields per feature type are listed in the book’s Solid features chapter.

To tell whether the design changed since a call, without reading all of it again, execute document.revision answers {document_id, revision}: revision moves only when the design changes, and document_id names the open design (another one after new_design or open). See control-protocol.md.

Resources: solidcraft://design (inspect JSON with measurements) and solidcraft://commands (the catalog).

Errors: an unknown tool or arguments that don’t match the tool’s schema are JSON-RPC -32602 errors (an unknown argument’s error lists the tool’s arguments); an engine failure (bad command parameters, a feature that fails) is a tool result with isError: true and the engine’s message, which the model can read and correct.

Long-running requests

The app answers a control request that runs longer than 60 seconds (a big fillet, say) with “still running” (control-protocol.md); it has not failed, and was not cancelled. The bridged server then keeps the connection, where the reply will come, and asks the app (control.pending) every half second for up to 240 seconds more, saying on stderr how long it waits; when the request finishes, the tool call returns its real result. If it still runs after that, the tool call fails with an error starting still running: that names the request and says what it still does: it will still apply when it finishes, or will still write the file (an export or a save: the design does not change), or only reads (nothing changes). Don’t send it again: call the pending tool, which waits up to 60 seconds for its result each time. Any other tool call first waits up to 60 seconds for it too, and is not sent while it still runs (so nothing is queued to apply unseen behind it); a request that finishes in that wait keeps its result for pending. If the connection to the app is lost meanwhile, the result is lost with it, and pending says so: inspect the design before sending a change again.

So a single tool call may block for up to 300 seconds (the app’s 60 s wait plus 240 s of polling) before it returns still running:, and a call made while an earlier request still runs for up to 60 seconds more. An MCP client needs a per-call timeout above that (say 330 s) to see that error; a client that gives up sooner only sees its own timeout, though the request goes on running in the app: then call pending (or inspect_design) before sending anything again.

A batch step that is still running stops the batch like a failure. Its rollback first waits for the step (as above), so a restored checkpoint takes the step back too; if it still runs, the reply says rolled_back: false, marks the step still_running and lists it in applied, as it will apply when it finishes.

batch rollback goes back to an engine checkpoint (edit.checkpoint) taken before the first step: the design, the active sketch and the undo history are restored exactly as they were, however long the history is. Batches that call file.new or doc.open get the design back, not its file path. (An older app without checkpoints falls back to undoing as many steps as the batch added to the undo history.)

Camera and close-up recipe

The camera of screenshot (the object view.apply, view.save and solidcraft-cli snapshot --camera take too) is an orbit camera, {target, yaw, pitch, distance, fov?}, in millimetres and radians. Unlike the angle of solid.move, a bare number is not degrees here. The eye is at target + distance * (-sin(yaw) * cos(pitch), -cos(yaw) * cos(pitch), sin(pitch)), looking at target with Z up on the screen. So yaw: 0, pitch: 0 is the front view: the eye at -Y, looking along +Y, with +X to the right. A yaw of π/2 looks from -X, π from +Y and -π/2 from +X. The pitch is the elevation angle up from the XY plane, and π/2 looks straight down with +X to the right and +Y up. fov is the vertical field of view in radians. 0, or no fov, is an orthographic view whose visible half-height is 0.4 × distance; with a perspective fov the half-height at the target is distance * tan(fov / 2). inspect.section removes what lies on the side its normal points to: it keeps the points p with n · p < d, where d = n · origin (flip: true keeps the other side). To look into the cut, put the eye on the removed side.

To look closely at one part of a large model, such as a STEP assembly, work in a headless session. These steps change only the open design in memory:

1. Open the model with solidcraft-cli mcp --in assembly.step (or the open tool, which also takes up and names, see step 4 and STEP import). inspect_design lists the bodies with their names and bounding boxes.
2. Remove what is in the way with solid.remove, e.g. {"bodies": ["Cover"]}.
3. Cut the region out of the rest with solid.box, e.g. {"corner": [40, 0, -45], "length": 20, "width": 50, "height": 45, "operation": "intersect", "targets": ["Housing", "Plate"]}. Each listed body is trimmed to the box, and one that lies wholly outside the box is removed. The box itself is not kept.
4. If the model lies on its back (many STEP files have +Y up), open it with up: "y" (the open tool, doc.open, file.insert_step), which turns the file’s bodies a quarter turn about X (Y becomes Z). One already open is stood Z up with solid.move, listing every body you keep, e.g. {"bodies": ["Housing", "Plate"], "axis": [1, 0, 0], "angle": 90}. It turns the bodies about the world origin, and a bare angle is in degrees. A turn of +90° about X takes +Y to +Z.
5. Colour the parts that matter with appearance.assign, e.g. {"bodies": ["Housing"], "color": "#3a7bd5"}, and hide helper bodies or sketches with browser.visibility, e.g. {"items": ["Plate"], "visible": false}.
6. Cut a section with inspect.section, e.g. {"plane": {"origin": [50, 30, 0], "normal": [0, 1, 0]}} or {"plane": "XY", "at": 5}.
7. Take the picture with screenshot: a camera whose target is the centre of the region and whose eye is on the cut side, source: "model", grid: false if the region straddles Z 0 (the ground grid would cut through it), and path, width and height as needed. An orthographic picture is 0.8 × distance high, so a distance of about 1.5 times the region’s size frames it. Look at the image, adjust yaw, pitch and distance, and shoot again. Headless, the picture is always a render of the model; bridged to the app, source: "model" asks for that render instead of the app’s window.

Compact replies

execute and batch default to verbose: true, preserving the full command results. For long modelling sessions, set verbose: false at the tool-argument level:

{"name": "execute", "arguments": {"command": "solid.box", "params": {"length": 10, "width": 10, "height": 10}, "verbose": false}}

Feature replies omit the full bodies list while keeping feature, name, created_bodies, changed_bodies and removed_bodies. A cut can therefore report a changed body even when no body name was added or removed. Sketch replies keep new IDs under created and omit only identical top-level points, curves, constraints and dimensions lists. Other fields and errors are unchanged; inspection commands still return their complete results. Compaction uses the engine’s reply directly, without an additional design-inspection request.

Demo: an enclosure built over MCP

examples/demo/enclosure_mcp.py is a small MCP client. It drives a running app (solidcraft --control PORT) through solidcraft-cli mcp --connect and builds an electronics enclosure one execute call at a time (enclosure_steps.json): a rounded box, shelled open at the top, a USB port cut through a side wall, four screw bosses, and then a change of the width parameter that the timeline rebuilds. examples/demo/record.sh records the run with ffmpeg, with each step’s caption burnt in.

examples/demo/enclosure_ui_mcp.py (v2) builds the same part the way a person would: the modelling goes through the app’s UI over its control channel. The pointer glides to toolbar buttons and faces and clicks them, the real dialogs open, the sketches go on the model’s faces, and the camera follows. The parameters, the sketch dimensions bound to them and two extrudes go over MCP. With --story v3 (the default) one standoff is patterned 2 × 2 in the Rectangular Pattern dialog with spacings from the parameters, and width and wall are then changed in the Parameters dialog. record_ui.sh records it and draws the pointer and the captions.

A typical session

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"me","version":"1"}}}
→ {"jsonrpc":"2.0","method":"notifications/initialized"}
→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"batch","arguments":{"commands":[
     {"command":"sketch.create","params":{"plane":"XY"}},
     {"command":"sketch.rectangle.two_point","params":{"p0":[0,0],"p1":[40,30]}},
     {"command":"sketch.finish"},
     {"command":"solid.extrude","params":{"distance":20}},
     {"command":"solid.fillet","params":{"edges":[[0,0,10]],"radius":3}},
     {"command":"sketch.create","params":{"plane":"XY"}},
     {"command":"sketch.circle.center","params":{"center":[20,15],"radius":5}},
     {"command":"solid.extrude","params":{"distance":20,"operation":"cut"}}]}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"ok\": true, \"completed\": 8, \"results\": [...]}"}]}}
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"measure","arguments":{}}}
← … "total": {"volume_mm3": 22390.6, …}
→ {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"screenshot","arguments":{"view":"iso"}}}
← {"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"image","mimeType":"image/png","data":"iVBORw0…"},{"type":"text","text":"{\"source\":\"model\",…}"}]}}
→ {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"export","arguments":{"path":"/tmp/part.step"}}}

The tests in crates/mcp/src/tests.rs run sessions like this (box → fillet → hole, parameters, batch rollback, hostile arguments) and check the results only through MCP.

Agent chat

Agent chat is a side panel where you talk to a coding agent you already use (Claude Code, Codex, Google Antigravity, OpenCode, Grok Build and others), or to a model behind an OpenAI-compatible or Anthropic-compatible endpoint you choose (Ollama or LM Studio on your computer, OpenAI, Anthropic, any other URL), and have it work on the design that’s open. A coding agent runs on your computer under your own account with that agent: SolidCraft doesn’t sell or proxy a model and needs no key for it. An endpoint’s key, if it needs one, goes into your system keychain, never into SolidCraft’s settings.

Desktop app only.

Turning it on and off

Everything about it is on one page: Preferences → AI.

• Show AI features (on by default) is the master switch. Turned off, SolidCraft shows nothing of it: no AI button, no shortcut, no menu entry, no panel, and nothing is looked for or started. The page stays, so you can turn it back on.
• Show Assistant button in application bar (on by default): the Assistant icon in the application bar row, which stays there however wide the window is. Turn it off to keep only the shortcut and the menu entry.
• Connect the last-used agent when SolidCraft starts (off by default): each launch starts the agent you connected last (the default one if you never connected), in the background, once SolidCraft has looked for the installed agents. The panel’s header shows Starting…, then Ready, or Connection failed with Retry in place of Connect (the agent is missing, could not start, or ended while starting); the conversation says why. A design opened in place of the empty one SolidCraft starts with keeps the agent connected, as long as nothing was asked in that empty design’s chat.
• Open the Assistant panel when SolidCraft starts (off by default): the panel (or its own window) is shown at each launch.

Neither applies when SolidCraft is started with --control for automation.

With AI features on, the panel opens from:

• the Assistant icon in the application bar;
• Ctrl+Shift+A (Cmd+Shift+A on a Mac), which also works from the chat’s own text box;
• View settings (the last button of the navigation bar under the view) → Agent chat.

Nothing runs until you need it: SolidCraft looks for installed agents (a quick --version each, in the background) when the panel or the AI page first opens, and starts an agent only when you send a message or press Connect (or at launch, when you turned that on above).

The panel

In the floating layout, Assistant fills the viewport height in the shared rounded panel, with space around its edges. The compass and navigation bar move into the remaining space beside it. It overlays the model without changing the viewport projection; clicks and scrolling over the panel stay in the chat. The docked layout retains its side panel.

• Docking: on the left, Assistant is the first panel, before vertical history and the browser. The drag highlight shows the actual destination bounds. Drag the panel’s header (the dotted grip and the title) to the other half of the window and let go. The side it would land on lights up while you drag. You can also pick Left or Right under Preferences → AI → Panel. SolidCraft remembers the side.
• Width: drag the panel’s inner edge. SolidCraft remembers it.
• Its own window: the pop-out button in the header (a window with an arrow) moves the chat into a window of its own, named after the design, which you can move anywhere, including another screen. The window’s own close button closes the chat, which opens there again next time; Dock (the same place in its header) puts it back in the side panel. You can also pick Own window under Preferences → AI → Panel. SolidCraft remembers where the window was and how big.
• Minimise (the line in the header) folds the panel into a small floating strip (a side strip in the docked layout) that keeps the chat icon, the agent’s state, and a count of anything waiting for your answer. Click the icon to unfold it. Close (×) hides the panel. Neither stops the agent; Stop does.
• The agent switcher under the title picks the agent for this conversation; switching stops the one running. Next to it, when the agent has modes of its own (Claude Code has Default, Accept Edits, Plan…), a second drop-down sets the agent’s mode. When the agent reports its models (an ACP agent’s model list, or an endpoint’s /models), a model drop-down shows the one in use and changes it; SolidCraft remembers the last choice for each agent and puts it back on the next session. An endpoint’s agent also keeps it as its default model. An agent that reports no models shows no drop-down. When the models come from more than one provider (Hermes and OpenCode name each model Provider · model, or say Provider: … in its description), a provider drop-down comes first and the model drop-down lists only that provider’s models, without the provider in front. It opens on the provider of the model in use; picking another provider changes nothing until one of its models is chosen. Models with no provider named are listed under Other.

Messages use right-aligned user bubbles and plain assistant text. Consecutive tool calls share an activity group: click a row to inspect its output; failed calls have an error tint. Approval cards retain the agent’s permission choices, and SolidCraft’s own approvals offer Deny, Always allow and Allow once. The composer’s permission menu uses the same Ask / Edits / All policy as Preferences, for the selected agent, and shows the actual changes used against the configured turn limit. Queue, Send now and Stop keep their existing behavior.

Files and pictures

A message can carry up to eight files, to show the agent what you mean: a concept picture, a sketch, a brief, a part to fit around.

• + next to Send has Choose a file… (a file dialog for the types below) and Paste a picture (the picture on the clipboard).
• Drop files on the chat. Files dropped on the panel (or its folded strip) attach to the next message, and the app doesn’t open them too. While files are dragged over the chat, it says so. The window gives no position while something is dragged, so the drop is the chat’s when the pointer was last seen over the chat; + always works.
• The files show as chips above the text box: a picture’s thumbnail, the name, and × to take the file off. A picture is read off the window thread, so a large one never stops the window: its chip shows a spinner meanwhile, and Send waits for it. Send sends files with no text.
• Pictures (PNG, JPEG, GIF, WebP) go to the agent as they are when they are at most 2048 px on the long side and 3.75 MB (a picture’s base64 then stays under 5 MB, so eight still fit in a prompt). Otherwise they are scaled down to 2048 px and re-encoded: as PNG when that fits, as JPEG when the picture has no transparency, halved until it fits; a GIF goes as its first frame. BMP and TIFF go as PNG. HEIC can’t be read: export it as JPEG or PNG first. An agent that takes no pictures gets none, and the message says which were left out.
• Text files (UTF-8, up to 256 KB: Markdown, plain text, JSON, CSV, YAML, TOML, XML, SVG…) go in the message’s text, whole as far as the message’s 100,000-character cap allows: past it a file is cut (and says how much is missing) or named only.
• CAD files (STEP, IGES, FreeCAD, Rhino, STL, 3MF, OBJ, glTF) are imported into the design at once, as components of their own. A file joins the message once its import is in (its chip shows a spinner meanwhile, and Send waits), and the message tells the agent it was added; a failed import says why and the agent is told nothing of it. Taking a part’s chip off the message leaves the part in the design (Undo removes it).
• Every file is named in the message. In the conversation the attached pictures show under it as thumbnails (hold the pointer over one for a bigger preview, click it to open the viewer, where the file’s name is shown and ‹ › step through the message’s pictures, together with the picture of the view); the other files are listed by name. Pictures in any of the formats above are decoded in the background, with a spinner until they are in. A file that can’t be attached says why.

Files stay with their message: one queued while the agent works keeps its files, and one sent again after a sign-in sends them again. When several queued messages go as one prompt, their files go with it, at most eight; the rest are named in the chat and not sent. New chat clears the files waiting on the chips too.

Typing while the agent works

Each design tab has its own conversation, agent session, draft, attachments and queued messages. A new tab starts with an empty chat. Switching away stops the current turn and keeps its completed changes in that design’s undo history. Returning restores the conversation; queued messages wait for Send. Closing a design closes its conversation. Conversations are kept only while the tabs remain open.

The input stays enabled during a turn. Enter queues the message: it shows in the conversation as a Queued bubble that you can Edit or remove (×) until it is sent. Several queued messages go as one prompt, in order, when the turn ends normally.

• Send now (on the bubble, or Ctrl+Enter / Cmd+Enter in the input) stops the current step, waits for the agent to say it stopped, then sends the queue as the next prompt, with a short note that the agent’s previous step was interrupted. What the interrupted message changed undoes as one step, like any other message.
• Stop (the square next to the input, or Esc in the input) stops the agent and keeps the queue: the bubbles wait for Send.
• New chat (the header button, Ctrl+Shift+L / Cmd+Shift+L with the chat focused) stops what runs, clears the conversation, the queue and the files on the chips, and starts a fresh session on the same agent, keeping the agent and its mode. It asks first when a message is running or queued, or files are waiting. The design’s undo history is untouched.

Agents

Preferences → AI → Agents lists every agent the chat can use, each with its kind (a program or an endpoint), version or model, whether it looks signed in, Test, Default (the one a new conversation starts with), its own permission setting, and Remove for the ones you added.

Found by themselves

SolidCraft looks for agents that speak the Agent Client Protocol on your PATH and in the usual install folders a desktop app’s PATH often misses (npm’s global folder, nvm, Volta, bun, ~/.local/bin, ~/.grok/bin, Homebrew, %APPDATA%\npm). For each one it shows its version (from --version, given three seconds) and whether a login was found. Version checks and agent sessions also use those folders on their PATH, so adapters can find runtimes such as Node when SolidCraft is opened from Finder or the Dock. Existing absolute PATH entries keep their order; no shell startup files are run. SolidCraft only checks whether the agent’s own login file (~/.claude/.credentials.json, ~/.codex/auth.json, ~/.gemini/oauth_creds.json, …) or one of its key variables exists. It never reads the file and never starts the agent to find out. On macOS Claude Code keeps its login in the keychain, so SolidCraft doesn’t guess there. A found login file may be expired: Test or a chat connection verifies it. A successful ACP connection shows signed in; an authentication rejection shows not signed in. These results apply to that agent until a newer connection result or Refresh, which checks the installed agents again. An unrelated connection error doesn’t change the last known login state.

The panel lists agents that aren’t installed with their install command and a Copy button. Refresh looks again after you install one. Test starts an agent briefly, asks it for a session and ends it again.

Flatpak

The Flatpak sandbox has no home-folder or network access by default. Agents installed through nvm or ~/.local/bin can therefore work in a terminal while SolidCraft reports that no agent was found. For Claude Code and its ACP adapter, run:

flatpak override --user ai.storyteller.solidcraft --filesystem=~/.nvm:ro --filesystem=~/.local/bin:ro --filesystem=~/.local/share/claude:ro --filesystem=~/.claude --filesystem=~/.claude.json --share=network

These permissions apply to SolidCraft for your user account:

• ~/.nvm:ro exposes Node and globally installed npm adapters read-only.
• ~/.local/bin:ro exposes locally installed executables read-only.
• ~/.local/share/claude:ro exposes Claude Code’s native installation read-only, including the targets of links in ~/.local/bin.
• ~/.claude and ~/.claude.json allow Claude Code to read and update its sign-in and configuration files.
• --share=network lets the adapter reach its service. It also gives SolidCraft network access, including making an enabled control server reachable from the host.

Restart SolidCraft after applying the override. Other agents or installation folders may need different filesystem permissions.

XAI Grok

Install Grok Build and run grok login in a terminal to sign in with your Grok account. In SolidCraft, open AI → Refresh, select XAI Grok, then Connect. You can make it the default under Preferences → AI → Agents.

SolidCraft reuses Grok Build’s sign-in in ~/.grok/auth.json; it checks only whether that file exists and does not read or copy its tokens. If sign-in is needed, the panel offers Grok’s own sign-in methods. You can also run grok login again and reconnect. Grok controls model access and usage limits for your account. This connection does not require an API key in SolidCraft. Grok Build also supports XAI_API_KEY for users who choose API authentication.

Add agent…

• Installed agent: your own entry for an installed agent, for example with other arguments.
• Custom command: any other program that speaks ACP on stdin and stdout, such as my-agent --acp. SolidCraft starts it directly, not through a shell.
• OpenAI-compatible API: a preset (Ollama http://localhost:11434/v1, LM Studio http://localhost:1234/v1, OpenAI, Mammouth AI https://api.mammouth.ai/v1) or a custom URL, the model name, and an optional key.
• Anthropic-compatible API: a preset (Anthropic) or a custom URL, for an endpoint that speaks the Anthropic Messages API ({base}/v1/messages). This covers Anthropic itself and providers that offer an Anthropic-compatible endpoint, such as DeepSeek and Qwen.
• The key goes into the system keychain (Keychain on macOS, Credential Manager on Windows, the Secret Service on Linux) and is only ever sent over HTTPS or to this computer. Test asks an OpenAI-compatible endpoint for its models; an Anthropic-compatible one gets a short message, because not every such endpoint lists models (Qwen’s has no model list). For these agents SolidCraft runs the conversation itself, with the same tools, limits and questions as for a coding agent, and no cap on model requests per message (Stop ends it). Request timeout is how long one model request may take: 300 s by default, from 30 s to an hour. A slow local model (a large model on modest hardware, or a long message with many tool results) may need more; raise it here or in the endpoint’s entry under Agents, where a change applies from the next request. A request that runs out of time ends the message with the limit it hit and where to raise it.

For Ollama, choosing a model checks its reported capabilities in the background. If its capabilities list lacks tools, a warning below the model picker explains that the model can only chat and suggests choosing one with tool support. Results are cached in memory per base URL and model, with a limit of 128 entries. SolidCraft recognises Ollama through /api/version at the endpoint’s origin or the Ollama preset. Failed checks and older servers without a capabilities field show no warning. The check never blocks sending a message.

Local models

Choose a model that supports native tool calling to read or change the design. With Ollama, look for tools in the model’s capabilities; a model that only supports chat cannot operate SolidCraft. Other OpenAI-compatible endpoints also need a model with native tool support.

If tools were available but a completed turn made no tool calls or changes, the panel shows a short notice when the reply was empty, or when an explicit edit request received only text. Ordinary answers to questions do not show it. Edit requests are recognised conservatively from English opening words such as “make”, “rename”, or “can you move”; other phrasing may stay quiet. Cancelled and failed turns keep their existing messages. Text describing a call is never run.

An agent inside WSL (Windows)

An agent installed inside WSL keeps its own settings, skills and sign-in there. Add it as a Custom command that starts it through wsl.exe, for example:

wsl.exe -d Ubuntu -e bash -lc claude-agent-acp

bash -lc runs your login shell’s setup, so the agent is found where your PATH puts it (npm, nvm, Volta). When the command’s program is wsl or wsl.exe, SolidCraft gives the agent its working folder and the solidcraft-app server’s program as WSL shows them (C:\Users\… becomes /mnt/c/Users/…). The server itself still runs on Windows and reaches the app at 127.0.0.1, so this works with WSL’s default networking. If you moved WSL’s drive mounts away from /mnt (automount.root in /etc/wsl.conf), those paths won’t match and the agent can’t start the server.

Signing in

If a coding agent isn’t signed in, it says so and the panel shows Sign in to the agent with the agent’s own ways to sign in:

• A command for a terminal, e.g. claude-agent-acp --cli auth login --claudeai, with a Copy button. Run it in a terminal, sign in there, then press I’ve signed in: connect again.
• A button for agents that sign in by themselves (Codex’s ChatGPT login opens your browser).
• A variable to set for agents that take a key from the environment. The panel has no field for a coding agent’s key, on purpose.

Whatever you typed before signing in is sent once the agent is ready.

What the agent can do

The agent reaches the open design only through SolidCraft’s own tools (the MCP server), which SolidCraft hands it when the chat starts. That server is named solidcraft-app, so an MCP server you set up yourself under the name solidcraft (as in client configuration) doesn’t take its place:

• Read the design: list commands, inspect features, sketches and parameters, measure, take pictures of the view.
• Change the design: run any modelling command, alone or in a batch. Changes show in the window as they happen.
• One undo per message: everything the agent changes while answering one message becomes a single undo step, named after your message. The conversation shows N changes, one undo step with Undo these changes while nothing else has happened since.
• Tool cards: each tool call shows as a card with its state; click it to see what it returned.
• Formatted text: the agent’s answers show as Markdown: headings, lists, quotes, code blocks (with Copy), bold, italic, code and links (web links only; each link is a button that opens it in your browser). What you type, and the agent’s thoughts, stay plain text.
• Attach view: tick it to send a picture of the current view with your message, for agents that take pictures. The picture is taken when the agent starts on the message and then shows as a small thumbnail under it. Hold the pointer over the thumbnail for a bigger preview that stays while you do; click it to open the viewer (the message’s pictures one at a time, with ‹ and › or the arrow keys, closed with Esc or a click outside). A long message scrolls inside its box, so Send and the buttons beside it stay in view.
• Attach selection: tick it to send what is selected in the model with your message, so the agent knows what “this edge” or “that feature” is. The box shows how many things are selected, counted as you clicked them (the two halves of a rim you clicked once are one). Faces and edges go with the names and numbers the agent’s tools take and with their size and place (so they can be found again after an edit), features with their name and kind, bodies with their name. The agent gets them as text after your message; the conversation shows your message as typed with the things as chips below it, grouped (Elements, Features, Bodies) with a count; hover a chip for what the agent was told about it. At most 64 things go with one message; the rest are counted (“+N more”), not dropped silently. The selection is read when you send, also for a message that waits in the queue.
• Pick context: press it to choose what the message is about on purpose. A picker opens with three lists, Elements (faces, edges, vertices), Features (steps of the timeline) and Bodies; click things in the model, the timeline or the browser to put them in the list that is active (click a list to make it active; click a picked thing again to take it out). OK puts them as chips above the message box, each with a ×; they go with the next message like an attached selection (and are shown the same way), and the box is empty again afterwards. Cancel keeps what was picked before.

Permissions

Preferences → AI → Permissions decides what the agent may do without asking, for every agent; each agent can have its own setting in its row.

• Ask every time: every change to the design and every file action waits for Allow, Always allow or Deny in the panel.
• Auto-allow model edits (the default): modelling commands run at once; saving, opening, exporting, importing, starting a new design, any command given a file name, and undoing past the start of your message still ask.
• Allow everything: nothing asks. The page warns you: the agent can then save, overwrite and replace your design.

Always allow remembers that command for that agent. The page lists what you allowed this way, per agent, with Reset.

These settings cover SolidCraft’s tools. A coding agent’s own tools (its shell, its file edits) follow the agent’s own mode, which you pick in the panel’s header. When an agent asks before using one of SolidCraft’s tools, SolidCraft answers for you, since its own gate checks the call, and notes it in the chat as Auto-allowed. With Allow everything, or after Always allow, the agent’s other questions are answered the same way and noted too.

What counts as “a command given a file name”: a parameter that holds a file or folder (file, dir, output, …), or path and source when the value reads like a file name (a separator, ~, a leading dot or a known extension), or any value of those in a command that exports, imports, saves, opens or inserts. A sweep’s or pattern’s path (curve ids) and an occurrence’s path (ids) are geometry and run without a question.

What it can’t do

• Files wait for you unless you chose Allow everything. Cancel or Stop declines everything that’s waiting, and a question nobody answers is declined after four minutes. The MCP server’s folder limits still apply after you allow: the design’s folder, the recovery folder and the server’s own scratch folder.
• An optional limit per message. There’s none by default. Untick Unlimited on the AI page to cap the changes the agent may make per message (it starts at 24). Reading the design doesn’t count. At the limit, it’s told to stop and report what’s left; send another message to let it carry on. Stop always works.
• No crash reports, whatever the permissions. Crash reports can hold other designs and file paths.
• Not the rest of the app. It can’t click the interface, change settings, quit, or drive the chat itself.
• Its own tools stay off where we can turn them off. SolidCraft declares no file system and no terminal to the agent, runs it in an empty working folder of its own, and asks the Claude Code adapter to turn off its shell, file and web tools for the session.

When the panel’s agent is stopped, another agent is picked, or SolidCraft quits, the agent and every program it started (the CLI it wraps, its MCP server) are stopped.

Privacy

Nothing goes anywhere except to the agent you run, or the endpoint you added. SolidCraft starts a coding agent as a program on your computer and talks to it over its standard input and output. What the agent sends to its own service, under your account and that service’s terms, is between you and that service, exactly as when you use the agent in a terminal. SolidCraft never sees, stores or passes on a coding agent’s password, token or key. An endpoint’s key is kept in the system keychain and sent only to that endpoint. SolidCraft’s own connection to the agent’s tools uses a random per-launch token in a file only you can read, which never passes through the agent.

Trying it without an account

A scripted test agent is in the source tree. It makes a block, rounds it and measures it, with no model behind it:

cargo build --release -p solidcraft-ui-egui --example acp_test_agent

Then add it under Preferences → AI → Add agent… → Custom command with the path of target/release/examples/acp_test_agent. Put “save” in your message to see an Allow / Deny card, or “ask” to see the agent ask its own permission.

Benchmarking the Assistant

solidcraft-cli bench-assistant runs the eleven tasks of the standard model test (v1, #4851) against a desktop app that is already running with a control port, and checks each result on the design itself. Use it to see how well a local model drives SolidCraft before you post its results.

solidcraft --control 9271
# In another terminal:
solidcraft-cli bench-assistant --connect 127.0.0.1:9271 \
  --base-url http://localhost:11434/v1 --model qwen2.5:7b \
  --json results.json --markdown results.md

Each task replaces the open design with a new one, so save your work first. The command adds the endpoint as an API agent named “bench”, starts a new chat with All permissions for every task, sends the prompt once, and waits for the turn to end. It runs only the setup the test prescribes (the box some tasks start from) and does none of the modelling itself. When it finishes it stops the agent and puts your permission setting back.

• The control token comes from --token, SOLIDCRAFT_CONTROL_TOKEN, or the app’s token file, in that order.
• --tasks 1,2,5 runs only those tasks, --repeat N runs the test N times, and --timeout-s (default 300) is each turn’s deadline; a turn that runs past it is stopped and fails as “timeout”.
• A failed task gets one of the issue’s failure categories (“wrote the call as text”, “wrong or unknown command”, “wrong arguments”, “the endpoint refused tools”, “an empty reply”, “only talked”, “gave up after errors”, or “hit the request limit”), or “wrong result” when the calls worked but the design is not what the task asks for.
• --markdown writes the issue’s comment template filled in; add the quantization, download size, and runtime before you post it. --json keeps each task’s failed rules, conversation, and design before and after. Both files are rewritten after every task.

Local models with the Assistant

You can use a model running on your computer to work on the open design in SolidCraft’s desktop Assistant. See Agent chat for the panel’s controls.

What you need

• Ollama, LM Studio, or another OpenAI-compatible server running on your computer.
• A model that supports tool calling: this lets it ask SolidCraft to read or change the design. On Ollama’s model page, look for the tools tag, or run ollama show <model> and look for tools under capabilities. Tool support alone does not guarantee good results; see the table below.
• Enough graphics memory (VRAM) for the model and its context (the conversation and tool instructions). See the table below for sizes.

Set it up

1. Start your server and load or download the model you want to use.
2. In SolidCraft, open Preferences > AI > Add agent… and choose the OpenAI-compatible API. Choose Ollama, LM Studio, or a custom URL.
3. Enter the server’s base URL, such as http://localhost:11434/v1 for Ollama, and the model name. Use Test, then add the endpoint.
4. Open the Assistant and select your endpoint. Choose the model in the model list if the server provides one.
5. Choose permissions in Preferences or the chat’s permission menu: Ask asks before changes and file actions; Edits allows model edits but still asks before file actions and replacing the design; All allows actions without approval, including saving, overwriting, and replacing the design.

Which models work?

These results were measured with the standard test (v1) in #4851. The table in that issue is the up-to-date one.

For about 8 GB of graphics memory, start with gemma4 (the default tag, 6.1 GB). With 16 GB, Muse Glimmer 30B or gpt-oss:20b also work well.

Troubleshooting

• The model replies with JSON or code, but nothing happens. It is not calling tools well. Try another model from the results above.
• “HTTP 400 … does not support tools.” The model lacks tool support. Choose one with the tools capability.
• Empty replies. The context may be too small for the tool instructions. Increase the server’s context size (num_ctx in Ollama), then try a new chat.
• Slow answers. The model may be too big for your VRAM and spilling work to the CPU. Try a smaller model or a smaller quantization.

Measure a model yourself

Follow the standard test in #4851 to compare your model with these results. It gives the exact prompts, starting designs, pass rules, and a template for sharing results.

Contributing to SolidCraft

Agents: start from the router in AGENTS.md, which points to a short skill in skills/ for each kind of work. This page stays the full human guide.

SolidCraft is an open-source parametric 3D CAD app written in pure Rust. You sketch on a plane, constrain the sketch, turn profiles into solids, and change a parameter to watch the timeline rebuild. It runs as a desktop app (Windows, macOS, Linux), in the browser (wasm + WebGPU/WebGL2), headless from a CLI, and as an MCP server that AI agents can model with.

Help is welcome, whether that’s a one-line fix or owning a whole area. This page covers how to build it, how the code is laid out, the few rules that aren’t negotiable, and where help is needed most.

Before choosing a task, check the command inventory and roadmap for implemented capabilities and current priorities.

Questions, ideas or want to say what you’re working on? Join the Discord.

Kernel work is paused

We’re evaluating a new geometry kernel. Until that’s decided, please don’t open issues, pull requests or discussions about kernel work: booleans, fillets, chamfers, shell, offsets, sweeps and lofts, threads and holes, STEP/IGES import and export, tessellation, or anything else that changes crates/kernel/. The pinned issue on the tracker explains it. New ones get the kernel-paused label (.github/workflows/kernel-paused.yml) and a maintainer answers them. Crashes and data loss are still taken as issues, and everything outside the kernel carries on as normal.

Get it running (about 10 minutes on a fast machine)

You need stable Rust 1.95 or newer (required by egui/eframe 0.36). For the web build you also need rustup target add wasm32-unknown-unknown and trunk (documentation).

git clone https://github.com/tangency-labs/solidcraft && cd solidcraft
cargo run --release -p solidcraft -- --sample      # desktop app with a sample part
cargo xtask test                                   # unit, engine and UI-scenario tests
cargo xtask ci                                     # everything a PR must pass (see below)

SolidCraft is the product, repository, Cargo package and executable name. Build the desktop app with cargo build --release -p solidcraft, or the CLI with cargo build --release -p solidcraft-cli. Run the CLI with cargo run --release -p solidcraft-cli -- commands (or target/release/solidcraft-cli commands after building). The old name appears only in the compatibility shims listed in docs/compatibility.md; don’t add new uses of it.

Web: cd apps/solidcraft-web && trunk serve --release, then open the printed URL (?sample opens the sample part, ?webgl forces WebGL2). Saving and opening files in the browser needs HTTPS or localhost, because it uses the Origin Private File System.

Windows from Linux: cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft.

NixOS: nix develop

NixOS has no /usr/lib, so nothing is on LD_LIBRARY_PATH and a plain cargo run finds none of the libraries the app loads at run time: the Wayland ones winit opens the window through, the EGL loader wgpu renders through, and libdbus-1, which rfd’s file dialogs reach xdg-desktop-portal through (a dialog then never appears and the pick returns no path):

ERROR solidcraft: winit EventLoopError: ... The wayland library could not be loaded
ERROR eframe::native::run: Exiting because of error: WGPU error: Failed to create surface for any enabled backend: {}
ERROR rfd::backend::xdg_desktop_portal::portal::libdbus: Can't connect to a portal: libdbus-1.so not found

nix develop (the flake.nix in the repository root) supplies Wayland, X11, EGL, Vulkan-loader and D-Bus runtime libraries. It also exposes the NixOS driver manifests in /run/opengl-driver/share, so Vulkan can discover the system drivers. Enable hardware.graphics.enable on NixOS; other Linux distributions may need a matching nixGL wrapper. The default development shell retains the Rust/C toolchain already on PATH; nix develop .#rust supplies the pinned toolchain and builds in target/nix.

To launch, use nix run .#solidcraft -- --sample. To install the app’s terminal commands, desktop entry and generated icons, use nix profile install .#solidcraft. nix build alone creates a build result; it does not install a launcher in your desktop menu. The installed solidcraft command runs the wrapped app; solidcraft-cli is included as well. See Nix installation and troubleshooting for remote-flake commands, desktop integration and how to distinguish an old executable on PATH.

How the code is laid out

The architecture page has the layer table. The short version:

• crates/geom: vectors, planes, meshes, measures.
• crates/sketch: our own constraint solver, plus profile finding.
• crates/kernel: the B-rep kernel boundary. It wraps truck, and it’s the only crate allowed to touch truck. Fillets, chamfers, shell/offset, Delete Face, Split Face, STEP/IGES read and write, and face provenance are our own code here. Patched copies of three truck crates live in vendor/ and are excluded from our fmt/clippy rules.
• crates/doc: the document. It holds parameters and expressions, the feature timeline and its incremental rebuild, components and occurrences, joints, appearances, and persistent naming.
• crates/io: design files and mesh formats (3MF, STL, OBJ).
• crates/engine: the session and the command registry. Everything the user can do is a command, and the toolbar, dialogs, scripts, CLI, control channel and MCP all run the same commands.
• crates/ui-egui: the desktop/web front end (egui + wgpu). It’s swappable; nothing below it depends on egui.
• crates/mcp, apps/solidcraft, apps/solidcraft-cli, apps/solidcraft-web.

cargo xtask layers fails the build if a lower layer depends on a higher one.

Rules that aren’t negotiable

1. 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. We don’t drive, script, automate or extract data from commercial CAD products, and we never copy another product’s code, icons, artwork, help text, tooltips, templates or materials. Command ids are our own (solid.fillet).
2. No GPL/LGPL/AGPL code, not even reading it. That rules out OpenCASCADE, FreeCAD (including planegcs), SolveSpace, CadQuery/OCP, LibreCAD and QCAD. SolidCraft is MIT OR Apache-2.0, and its solver and blends are written from the maths. (Running an open-source application to get reference values for a test is fine; reading its source is not.) Permissive dependencies are fine. Note which one you’re adding and why in the PR. THIRD-PARTY-LICENSES.txt lists it once the change lands: the Generated files workflow rewrites it on main. Nightly/manual CI also scans advisories, bans and sources with cargo-deny; see the local command and coverage limits.
3. Every asset is original or openly licensed and has a row in ATTRIBUTION.md. Icons are drawn in code (crates/ui-egui/src/icons.rs). cargo xtask assets enforces this.
4. Never crash. People trust a CAD app with their work.
   • Non-test code never uses unwrap, expect, panic! or indexing on input-derived data. There’s no unsafe outside apps/solidcraft/src/open_documents.rs (macOS file-open events), apps/solidcraft/src/native_crash.rs (Windows native crash capture) and crates/threedx-client/src/macos.rs (the 3Dconnexion driver’s client API on macOS), and the compiler denies it.
   • An unsupported case returns an error (“not supported yet: …”); it never panics.
   • Every call into truck goes through solidcraft_kernel::guard.
   • Every crash fix comes with a regression test.
5. Everything is a command, with a test. A new feature means a CommandSpec in crates/engine/src/cmd/ with input and output schemas (see Adding a command; a test warns about a command without them, and will fail it once required), engine tests that measure the result (volume, area, face/edge/vertex counts against a value you can derive), and for UI work a scenario (below).
6. One set of camera controls. Every page or canvas that shows a view (the modelling viewport, the Render preview, and any new page such as a flat pattern or drawing) calls navigation::handle (crates/ui-egui/src/navigation.rs) for its camera input, with NavCaps saying whether it can orbit (off for flat 2D pages) and pick. New canvases must use navigation::handle; never read drags, the wheel or pinch to move the camera yourself. The hand_rolled_camera_input_is_rejected test fails if a page does.

Labels, parameter docs, messages and docs use the terms in the glossary: one term for each idea. A change that adds a new idea adds its term there.

AGENTS.md has the long form of these rules. It’s written for AI agents, but it’s the most complete description of the house style.

Tests

A geometry change that changes the robustness goldens re-records them in the same pull request: ROBUSTNESS_GOLDENS_BLESS="why it changed" cargo test --profile ci -p solidcraft-engine --lib robustness_goldens:: (see docs/robustness.md); CI runs every seed on pull requests that touch geometry. docs/mutation-testing.md shows how to find kernel behaviour these black-box suites miss.

UI scenarios drive the real app headless: start a tool, click a plane or a sketch point, press keys, then assert on the result.

[
  {"start": "sketch.create"},
  {"click": {"plane": "XY"}},
  {"start": "sketch.rectangle.two_point"},
  {"click": {"sketch": [0, 0]}},
  {"click": {"sketch": [40, 30]}},
  {"expect": {"errors": 0}}
]

A new .json file in that folder is picked up automatically. To record a bug before it’s fixed, put {"pending": "why"} in the scenario, and remove it in the PR that fixes the bug.

A failing test without its fix can’t merge as-is: it would turn main’s CI red for everyone. Either include the fix in the same PR, or mark the test #[ignore = "fails until #123 is fixed"] (it can then merge right away), and remove that line in the PR that fixes the bug.

Use the ci profile. CI runs the tests with --profile ci: light optimisation, line tables, no LTO, and debug assertions off (truck has debug-only assertions that reject valid geometry). It builds several times faster than --release. If a test fails only in a plain debug build, say so in the PR. cargo xtask test builds the tests with it and then runs every test binary at once (cargo test runs them one after another); arguments after -- go to each binary, e.g. cargo xtask test -- shell. Set SOLIDCRAFT_TEST_JOBS to a positive integer to opt into a shared bound on top-level test/side commands for cargo xtask test and cargo xtask ci. For example, SOLIDCRAFT_TEST_JOBS=2 allows two commands at once; the sequential wasm/doc worker consumes one of those slots. Every binary and side check still runs after failures. Without the variable the existing concurrency is unchanged. With it set, each test binary inherits RUST_TEST_THREADS and ACTION_MATRIX_JOBS of max(1, cpus / jobs) — the machine’s parallelism shared between the binaries in flight — unless you set either one explicitly; explicit caller overrides always win. Cargo’s build-job setting remains an independent caller override; this limit does not change test filters, timeouts or baselines. Tests run beside each other on a busy machine, so a test must not depend on wall-clock timing.

Ready pull requests test what they touch. CI maps changed files to workspace packages and runs Clippy, the test build and tests for those and their dependents. The package selector and CI workflow define which changes require native checks; documentation, packaging, other-workflow and bot-script-only changes run the repository checks only, on pull requests and on main. Workspace-wide changes, merge-queue groups, nightly runs and Run workflow select the full workspace. A push to main reuses a successful merge-queue run for the same commit, and runs only the repository checks when no code changed since the last push to main that passed; otherwise it runs the full suite. Doc tests, reference tests and the Windows jobs run on main and nightly only.

CI shards the tests. One job builds them into a cargo-nextest archive; two shards run on pull requests and four during full validation. Every test runs in its own process: don’t rely on state left by another test. Pull requests skip a few heavy tests (one to twelve minutes each), which run in full validation (the merge queue, nightly, manual runs and pushes to main not already tested by the queue). Check that validation after merging. They are listed in .config/nextest.toml and the testing page:

• solidcraft-engine: tests::hostile_params_never_panic, everything in tests::robustness and the seeds of tests::robustness_goldens (seed_00 … seed_95; pull requests that change the kernel, truck or the goldens run all but the slowest, SLOW_SEEDS in ci.yml), pattern_suppress_tests::enclosure_arc_extinction_keeps_a_real_sharp_inner_lip_after_resize_and_reopen, pattern_suppress_tests::enclosure_datums_follow_wall_height_and_board_depth_with_material_proofs, cmd::plastic::tests::enclosure_snap_fit_follows_resized_front_wall, the atomic_commands contract tests
• solidcraft-kernel: tests::boolean_identity_on_tangent_primitives, tspline::tests::hostile_tsplines_never_panic, and the boolean_props property tests (these run only in the nightly “Property tests” job: their inputs are random, so main skips them too)
• solidcraft-ui-egui scenarios: acceptance_sensor_enclosure

The action matrix tries every ordinary action on every face, edge, vertex and body of a corpus of designs against a checked-in ratchet (docs/action-matrix.md). A pull request that makes an action pass should record it with cargo xtask action-matrix --bless; one that makes a passing action fail fails the sample every CI run checks.

The reference tests live in tests/oracle/, each a recipe.json in our own format with an expected.json beside it. SolidCraft rebuilds the recipe and compares body count, volume, area, centre of mass and bounding box (and, where there is a reference.stl, the surface itself). Expected values are either worked out in closed form (tools/oracle-analytic/) or computed by building the same recipe in FreeCAD, run as a separate program (tools/freecad-oracle/); each file says which. The generated reference test report has the current case count and results. The reference-test CI job runs cargo xtask oracle during full validation; pull-request runs skip it. A case that fails because of a known bug names its issue in expected.json ("known_failure": "#123"); never change an expected value to match SolidCraft’s output.

Changing the design file format

A design file says which format it is in ("format": "solidcraft/N"). If your change saves something new in a design (a field, a feature type, a new kind of name), or makes older designs mean something else, it needs a format change. Add one file, and edit nothing shared:

1. Create crates/doc/src/format/pending/<what-it-is>.rs (lowercase, dashes). Start it with a //! note: what is saved, what older designs get without it, and that the last release asks for an update instead of meeting it.
2. If older designs must be rewritten as they open, put pub fn step(v: &mut Value) -> crate::Result<()> in the same file. Pending steps run in file-name order, after the older formats’ steps.
3. Don’t touch FORMAT, JSON_STEPS, the history in crates/doc/src/format.rs, another change’s file, or any v<N>/ folder: those are fixed once released.

That’s all. The build counts the files: while any are pending it writes the next format number, which no release reads, so a release refuses a design that has your change instead of losing it. A file also lists the pending changes it has (format_pending), so a later development build runs only the steps that file is missing. Two pull requests that each add a change merge without a conflict. crates/doc/src/format/pending/README.md has an example.

At release time the maintainer runs scripts/fold-format-pending.sh, which moves the pending files into crates/doc/src/format/v<N>/ and fixes that number for good (see docs/releasing.md). Never add a file to a v<N>/ folder afterwards.

Lists many changes add to

Some files gain an item in many pull requests at once. They are kept so that two changes that each add an item only meet when their items are neighbours, which spares everyone a conflict and a fresh CI run:

• Message catalogs (assets/locales/*.json): one message per line, sorted by id. Add your message anywhere and run cargo xtask lists --fix; cargo xtask lists (in cargo xtask ci and the Lists workflow) fails on an unsorted catalog or an id that appears twice.
• mod lines: one per line, in the sorted group they belong to (cargo fmt keeps each group sorted). Add a new module into the existing group, not as a new group at the end.
• Commands without schemas (crates/engine/src/schema/unconverted.txt): sorted, one id per line, and it only shrinks. Converting a command removes its line; a new command is never added to it.
• Languages (crates/ui-egui/src/i18n.rs): one per line, English first, then by id (a test checks it).
• Generated files: THIRD-PARTY-LICENSES.txt and docs/features.md are rewritten on main after each merge by the Generated files workflow (cargo xtask licences, cargo xtask features). Don’t regenerate or edit them in a pull request.
• Design format: one file per change, never an edit to a shared number (above).
• New UI strings and attribution rows: one new file per change, assets/locales/pending/<slug>.json and attribution/pending/<slug>.md, instead of editing the catalogs or the ATTRIBUTION.md table; cargo xtask fold-pending folds them on main (see the README in each folder).

Sending a change

1. Work is tracked in GitHub issues, labelled by area (area:kernel, area:sketch, area:doc, area:ui, area:infra). For anything bigger than a bug fix that has no issue yet, open one first. Claim the issue with a draft PR before you start, so two people don’t build the same thing:
   • Check nobody has it: gh pr list -R tangency-labs/solidcraft --state open --search "#N".
   • Branch from the latest main, commit git commit --allow-empty -m "claim: #N", push, and open a draft PR titled <summary> (#N), e.g. Fillet: variable radius along a chain (#123).
   • The lowest-numbered open PR for an issue wins. If yours lost, close it (or offer to help on the other one).
   • The bot records the claim when the PR is opened: it assigns you, adds in progress and says so on the issue. It reads #N in the PR title and Fixes #N in the body. If someone already holds the issue, or an older open PR references it, it says so on your PR instead.
   • Want to stake a claim before you have a branch? Comment /claim on the issue (below).
   • 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.
   • Mark the PR ready for review when it is done.
2. Branch from main and keep the PR to one topic.
3. Run cargo xtask ci before pushing. It runs fmt, the asset, licence and layer checks, clippy (-D warnings), then the tests with the wasm build check alongside. A PR has to pass it. Heavy CI runs after review: a pull request gets the formatting and repository checks and a quick compile (cargo check) when you push. Once a maintainer has reviewed it they add the approved-for-ci label when the PR is ready to merge, which runs the full CI (build, tests, goldens, Clippy); every push after that runs the full set again. Maintainers merge approved PRs in groups by area, so PRs that touch the same code meet a conflict at most once.
4. Reference the issue (Fixes #12). In the PR, say what you tested and how. For geometry work, include the measured numbers (and the expected ones).

Commenting /claim assigns you, adds the in progress label, and replies with its automatic cleanup deadline. It frees a claim with no linked PR after 72 hours, or a claim with a PR after 14 days without pushes. These automatic cleanup deadlines are separate from the daily progress and 72-hour takeover policy above. A draft PR that references the issue claims it the same way. /unclaim releases the bot claim early (only you or a maintainer can). Issues a maintainer has taken are never freed automatically.

Help reviewers see what the words mean. For observable CAD, UI or model behavior, please include actual descriptive screenshots or a short recording in the issue or PR. This evidence is required for changes or bugs that can be demonstrated in the app, including kernel, geometry, assembly and backend work. Coding agents should run a small reproduction and capture the evidence themselves; please don’t ask a human for evidence the agent can produce. Show the actual failure or result, preferably before and after, with brief steps and expected/actual behavior. An arrow or annotation can help identify the detail that matters.

Flowcharts and Mermaid diagrams cannot replace evidence of visible behavior. Diagrams are useful 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 example without private designs or sensitive details; attach the media or link to an accessible recording rather than committing generated review artifacts.

To show a picture without committing it, attach the media to the PR (it goes to the PR’s own attachment storage and renders inline in the comment). A gist is the better home for a log or another text file, and you link it; a gist does not render a picture inline. The review artifacts stay out of the diff that way, and nothing has to be pushed to a branch of its own.

Attaching works in the browser for anyone who can comment: drag the file into a comment on the pull request. A command-line agent without a browser session usually cannot attach a file (the upload needs write access to this repository). Say so in the pull request, and the person running the agent or a maintainer can attach it.

Keep an eye on your PR’s status, but don’t push to it only to catch up with main (no merge of main, no Update branch button, no rebase for that alone): every push restarts the whole CI run for everyone waiting behind it, and main‘s own run catches what lands in between. When you push a change anyway, or GitHub reports a conflict, rebase onto the latest main (push your branch with --force-with-lease) or merge main in once, and resolve conflicts without losing others’ changes. Don’t re-run CI on an unchanged commit either: a real failure fails again. Re-run only a job that runner trouble cancelled, with “Re-run failed jobs”. While a task remains active, follow an open PR through its status changes; at handoff, clearly identify anything still awaiting merge.

Much of SolidCraft so far was written by AI coding agents (Claude) working in parallel, each owning one area, with a human setting direction and reporting bugs. Their working notes are in AGENTS.md. Human contributors are just as welcome. Use whatever tools you like, as long as the change meets the rules above.

Two quick checks run on every pull request (.github/workflows/pr-checks.yml, not required): it fails when a lower-numbered open PR by someone else already closes the same issue (the label not-a-duplicate skips it), or when the description lacks the Changes a default: no / Changes a default: yes — <what>, old behaviour kept behind preference <name> line (docs-only and bot PRs are exempt).

Labels and triage

The triage bot labels every new issue and PR (.github/workflows/triage.yml). It only adds labels; correct them freely and it won’t put them back.

• PRs get area:* from the paths they change (crates/kernel and crates/geom → area:kernel, crates/ui-egui and the apps → area:ui, .github/, scripts/, docs/ → area:infra, and so on).
• Issues get bug (in-app reports and the bug template), enhancement (feature requests), priority:P1 for crashes, and an area:* from the title or the reported command. Until it has a priority, an issue carries needs-triage; setting a priority removes it.
• Maintainers comment /triage area:kernel P1 (any existing label; P0–P3 for a priority, which replaces the old one; -label removes one) to sort an issue or PR.
• Short bug reports without steps to reproduce get needs-info and one comment asking for the steps (and the version, when it’s missing). An app report that arrived empty is asked to paste the report the app copied to the clipboard. The reporter’s reply, or an edit that adds the steps, removes the label; an issue that stays in needs-info for 14 days is closed, and can be reopened any time. Feature requests, app reports with their details, and maintainers’ issues are never asked.
• needs-triage is the queue: open issues with it.

Where help is wanted most

Kernel speed (slow fillets, booleans, STEP): please don’t rewrite the current kernel code for speed; it is being replaced by solidcore (progress). Report slow cases with a file under the kernel-perf label, and put kernel effort into solidcore instead. See #1597.

See the help wanted and good first issue labels. In order of how much they’d help users:

1. Fillet and blend robustness. Fillets are our own code (truck has no fillet operation). Constant, variable-radius and chord fillets work, and so do corners where fillets of different radii meet, including three rounds meeting at a vertex. Next are setback corners, fillets along curved edges between curved faces, and fillets that consume neighbouring faces.
2. Boolean robustness. A random-design fuzzer currently gets about half of its designs through without a kernel error. Each failing seed is a reproducible bug.
3. Drawings, CAM and mesh tools. These are out of scope for now (see ROADMAP.md), but anyone who wants to own one is welcome.

Updating the generated feature list

After adding or renaming commands, run cargo xtask features. The registry is the source of truth for docs/features.md; do not hand-edit the generated rows. The generator sorts commands by ID and omits global and per-section counters, so additions to unrelated areas no longer rewrite shared summary lines.

If two branches still conflict in this file (for example, adjacent additions in the same area), first resolve the command registry and source conflicts, then run cargo xtask features again and stage the regenerated file. Do not use Git’s union merge driver: it can silently retain stale or duplicate command rows. The generator tests cover stable ordering and additions that leave existing lines unchanged. The initial switch to sorted rows is a one-time larger diff.

Licence

By contributing you agree that your contribution is licensed as MIT OR Apache-2.0, like the rest of SolidCraft. SolidCraft isn’t affiliated with any CAD vendor; product names are trademarks of their owners (see NOTICE).

Contributing command guides and resources

The command reference combines the live command registry with reviewed Markdown guides. A guide appears inside its command’s entry, before the collapsed automation syntax. You can improve one entry without rewriting the whole manual. The reference’s Practical guides list automatically links to every available guide; adding a guide does not require editing an index or Rust code.

Add or improve an entry

1. Find the command in the reference. Its ID is in Automation details.
2. Copy the guide template to docs/book/command-guides/<command-id>.md, or edit its existing file. For example, Extrude lives in solid.extrude.md.
3. Explain what the tool does, what must exist or be selected first, the dialog’s choices in a table, a short example, and useful DOs and DON’Ts. Use plain language rather than copying the raw automation parameters.
4. Add related commands and any checked community resources, then open a pull request. Documentation changes are reviewed like code.

Do not edit the generated src/reference/commands.md: rebuilding replaces it. The generator rejects guide filenames whose command is absent from the registry. Names, groups, shortcuts and automation parameters continue to come from that registry; handwritten explanations remain editable independently.

Use fourth-level headings (####) inside an entry so the command remains the parent section. Write image and page paths relative to the generated reference page, docs/book/src/reference/commands.md, not to the input guide file. For example, ../generated/sheet-metal.png and ../guide/sheet-metal.md.

Related commands

Write a command link as {{#command sheet.hem}}. The generator inserts its current name and links directly to that command. Unknown or missing command IDs and unfinished directives fail the book build, helping contributors catch stale links. Normal Markdown links can point to guide pages or external resources.

Community resources

You can add a focused tip, a short demo, a model or an illustrative screenshot to the entry’s resource table. Explain what the reader learns from each link; include author and licence information. Links are reviewed, not automatically collected from the web. A resource need not cover the whole command.

Use original SolidCraft examples or openly licensed resources with permission to share. Do not use designs, screenshots, help text or artwork extracted from commercial CAD products, or GPL/LGPL/AGPL code. Prefer small public-safe examples and remove private designs, paths and account information from evidence.

For a new file asset, follow assets/AGENTS.md and add its attribution in a new attribution/pending/<change>.md file. A reproducible recipe in docs/book/scripts/ can be rendered by the book builder; generated images stay out of Git. Existing examples demonstrate both inline pictures and resource links.

Preview and review

Run cargo xtask book with mdBook installed, inspect the command entry and its links, and check the example in SolidCraft. Confirm the required selection, units, defaults and limitations against the implementation. Show reviewers an actual before/after screenshot of the rendered entry. Repository quality gates still apply before a commit.

Copyable template

One sentence explaining what this command does and when someone would use it.

#### Before you start

- Explain the required body, sketch, region, edge, face or point in ordinary words.
- State whether a selection is required and what cannot be used instead.

#### Options

| Choice in the dialog | Meaning | Example or reason to choose it |
| --- | --- | --- |
| Replace with a real option | Explain the effect without copying parameter syntax. | A useful value with units. |

#### Try it

1. Start from a small reproducible design.
2. Name the selection, command, settings and expected visible result.

#### Tips and common mistakes

- **Do** explain a useful habit and its benefit.
- **Don't** describe an unsupported selection as if it worked.

#### Examples and community resources

Add only rows for resources you have checked. Replace placeholders before
submitting; do not publish an empty resource table.

| Kind | Resource and what it teaches | Author and licence |
| --- | --- | --- |
| Tip | Link to a focused explanation. | Credit and permission to reuse. |
| Demo | Link to a short recording or reproducible recipe. | Credit and licence. |
| Model | Link to an original SolidCraft design or an openly licensed model. | Credit and licence. |
| Screenshot | Link to or embed an actual SolidCraft result, with descriptive alternative text. | Credit and licence. |

#### See also

Use `{{#command solid.extrude}}` with a real related command's ID and explain
why it is related. The generator supplies its current label and a direct link.

Architecture

SolidCraft is a Cargo workspace in layers. A crate only depends on crates in lower layers, and cargo xtask layers fails the build otherwise.

The web app, apps/solidcraft-web, is the desktop front end compiled to wasm with trunk. xtask holds the repository’s own tooling: cargo xtask ci, layers, assets, features, oracle and book.

A few rules follow from the layering:

• Only crates/kernel touches truck. Everything above it sees SolidCraft’s own types: bodies, faces, edges, meshes and measures. See The kernel boundary.
• The document knows nothing about commands or the UI. crates/doc holds the parameters, the feature timeline and the component tree, and evaluates them into a model.
• Everything the user can do is a command in crates/engine. See The command engine.
• The front end is swappable. Nothing below ui-egui depends on egui. The CLI and the MCP server run the same engine without a window. Headless pictures (solidcraft-cli snapshot, MCP screenshots, ui.render, thumbnails) are drawn on the GPU with the viewport’s own pipelines (crates/gpu, capture): the engine describes the scene (view::scene) and the host installs the renderer (engine::capture). The tiers, in order: a hardware GPU, a software adapter (Mesa lavapipe or llvmpipe, WARP), and last crates/render’s CPU rasterizer, which draws no surface analysis, highlights or legends. SOLIDCRAFT_GPU=auto walks all three, hardware and software stay on their tier (an error without one), cpu forces the rasterizer; every picture’s reply names its renderer (gpu, gpu-software, cpu) and a CPU picture carries a warning. solidcraft-cli gpu lists the adapters and the tier the policy lands on.

SolidCraft UI kit

crates/ui-egui/src/ui_kit/ contains the tokenised controls used by feature dialogs, preferences, manager cards, prompts, context menus and the sketch palette. Import through crate::ui_kit::{...}. Most controls are crate-visible; the container API is public so platform apps use the same hosts.

Stage bars

StageBar composes two clipped, horizontally scrollable rows inside the shell’s shared floating Container (Surface::Chrome). Its 36 pt first row contains numbered stage chips with the current workspace accent, shared primary/normal buttons and the existing command-search editor. The second row fills the remaining card height. The feature supplies labels, enabled reasons and command dispatch; the kit owns chip geometry, row spacing, typography and colour. Stage selection is navigation; the kit never invents completion badges. The shared compact workspace card is 104 × 88 pt; its icon, label and caption are centred vertically. The stage bar is 88 pt high with an 8 pt gap from that card. Its 36 pt header and 52 pt tools band share a 1 pt divider. Tools use 8 pt side padding, icon-text segments, icon-label actions and an information chip, all with theme::Tokens colours in both themes. Render retains its Inspector controls outside the bar.

Panel::workspace gives paired floating docks the same bounded vertical span and limits each dock to half the available width with an 8 pt gap. Content clips inside the allocated host, so a small window cannot grow a dock into the stage bar or Shots strip. Docks without usable space are omitted. Render’s default outer widths are 266 pt for Browser and 305 pt for Inspector, retaining the shared minimum/maximum resize rules. Its compass is 110 pt; the 48 pt Shots strip clears the docks by 8 pt.

Composition and rules

• Every outer host uses ui_kit::Container with a semantic Surface. The shell publishes the layout once per frame; Container::floating() and frame() own adaptive placement policy and chrome. Panel, Window, Confirm and Menu compose it. Raw egui hosts and outer shadows are rejected recursively, including platform apps. The mandatory cargo xtask ui-containers gate runs in fast CI and scans new crates/apps automatically, including macro bodies and alias chains. See the container audit and migration inventory.

• Colours, typography, dimensions and spacing come from theme::Tokens.

• Sliders only via ui_kit::slider; Slider options change behaviour, never appearance. Raw sliders and duplicate track/thumb painters are forbidden in the UI and apps.

• scope(ui, add) supplies form styling. row(ui, label, add) aligns labels and controls at control_height (28 pt). Wide manager rows use a 104 pt label basis with a 10 pt gutter, derived from the compact 70 pt basis and spacing tokens. Compact rows retain their 8 pt gutter. Labels widen from the appropriate basis to at most 1.6 times that width and never exceed half the row.

• expr_row, hint_row, text_row and choice_row compose row with the existing expression, hinted expression, plain text and dropdown controls. They preserve row order, labels, focus IDs and completion; callers keep Enter/change ownership and explicit dropdown IDs. count_row composes row with count_field for pattern quantities.

• Panel::workspace owns grip-based left/right placement and bounded width resizing for floating workspace cards, including in Compact ribbon layouts. It reuses the 40 pt Panel/Window header and padded body, with no second top inset below the ribbon. Persistent workspace cards omit the close action. Panel::bottom_strip uses Container::bottom_strip_rect, the same placement as Design History. Container::navigation_card supplies the shared Navigation surface for anchored HUDs. Register measured card rectangles and reserved edges with shell::register_panel so fitting and pointer shielding agree. Feature modules provide content, never outer chrome.

• Panel owns bounded windows, feature/palette composition, scrolling bodies, pinned actions, compute status and keyboard routing. wide() uses three card widths. feature_frame and palette_frame retain docked/floating surfaces. FeatureOptions::apply_label adds Apply; Panel::actions supplies custom labels. With DialogButtons::Top published (Preferences › Interface › Dialog buttons), feature puts the actions in the header row through HeaderActions instead of a footer: the same buttons, enabled states, keyboard and handles, each as wide as its bold label, with Cancel standing in for the close button and the compute status in the title’s place. body_rows caps a manager’s scrolling body independently of its position; short viewports still keep the header and actions visible.

• Window composes the shared Panel frame with a 40 pt icon/title/close header, padded content and optional 48 pt footer. show_with_left pins a left action beside the right-aligned buttons. show_pages accepts declarative WindowPage entries (icon, i18n label key, optional group heading, stable handle, scroll policy and draw callback). Its 188 pt soft page list has 32 pt icon/label rows, selected tint/ink and a divider. Preferences has nine grouped pages; legacy control-channel page names remain aliases. page_rows opts into a taller body while preserving viewport bounds. actions, anchor/placed, cards, fields and keep_open_on_escape retain existing window behavior. Empty action labels omit the footer.

• Confirm is an input-blocking modal using the same card frame and footer controls. It shows a 36 pt icon disc in warning, danger or info tone, a title, caller-supplied message and optional monospace detail, above a 52 pt footer. Glyphs use the construction ramp for warning, the shared shaded danger treatment for danger, and base blue for info; the disc keeps its tint. actions(primary, cancel, left_ghost) places the optional third action at the left. Danger uses form_error with a contrast-selected on-colour; other primaries use blue. Enter invokes the selected answer (primary by default) when valid; Esc cancels. It retains close, answer and message scenario handles. The old Prompt element is removed.

• Callers supply data and enabled state, then dispatch existing commands. Editors leave their established completion, Enter, Tab and commit ownership unchanged.

• Every text input uses the kit’s shared text_input policy: symmetric horizontal form_inset, zero vertical margin and centred galley alignment. Font metrics therefore centre both mono and proportional text within the allocated field, including invalid and attached Library fields, without per-caller offsets. Canvas placement editors retain their native line-height plus space_4 hit target so nearby sketch picks are not intercepted; alignment stays shared.

• Scenario handles and accessible labels are API. Consolidated options preserve the former geometry, wrapping, native metadata and publication keys.

Preference compositions use settings_heading, shared disclosure settings_section headings and settings_pair for responsive controls beside one specimen. option_card supplies the shared illustrated radio control. settings_form and settings_block_hint define aligned label grids; theme_rail keeps the import tile fixed beside a scrollbar-free scrolling row. PreferenceFigure owns theme swatches, orbit pivots, quality, anti-aliasing, contact shading and up-axis figures. layout_preview follows the four workspace choices without opening another viewport. Scale, palette, autosave, mouse and live-axis specimens share tokens and the gallery; live bars show actual calibrated input and introduce no repaint timer.

Elements

Module names below describe implementation locations, not caller import paths. Every inline element/variant has one entry in the light/dark gallery::ELEMENTS table. Panel/Window/Confirm compositions also have dedicated geometry and interaction tests.

History contents are selected from measured panel width. A 56 pt thin strip shows icons and four vertical transport controls: beginning, back, forward and end. The minimum named width is 130 pt; it adds horizontal transport and the same six-dot window grip as Assistant. When the remaining header space fits its measured text, History appears between grip and transport. No names-mode flag or command selects these layouts. The seam snaps between 56 and 130 pt; widths from 130 through 624 pt remain continuous and persist as timeline_left_width.

Drag the grip or title to dock along the bottom, at the full-height left edge, or beneath the browser. Either card’s right edge resizes their shared width. This position divides available column height equally. Folding either card leaves its header visible and gives the remainder to the other. If both are folded, their headers sit together at the top of the column. Expansion and collapse share a smooth cubic transition capped at 120 ms, respecting the interface’s instant-animation setting. Their collapse controls share the same active-tab blue hover tint. Browser resizing also resizes History. The view.history_layout command validates width, docking and collapse requests without altering the design or opening dialogs. Floating mode preserves viewport projection.

The seam handle overlays the strip’s right edge without taking layout space. Its grip is visible at rest; the arrow appears only on hover. Click, double-click the edge, or use Enter/Space on the focused handle to resize between thin and minimum named widths. Drag freely above the named minimum; resizing draws no dotted guide or name label. Header/title dragging and the edge width gesture are separate from feature/folder and rollback dragging. The rollback marker is 12 pt high. Its 2 pt line uses the active tab fill and ends in a 10 pt hollow circle with a 2 pt accent border and the card/panel surface inside. The circle overlaps the line end by 1 pt. The bottom strip uses the same painter, rotated. Folder selection, range selection, context menus, sketch-pattern children, drag reordering and command JSON retain their existing behavior and handles. history_icons, history_names, history_marker and the history_seam_rest/hover/drag states have light/dark gallery references. The CPU board test captures both strip widths with expanded and collapsed browsers (SOLIDCRAFT_HISTORY_EVIDENCE).

text(ui, text, options) supports the existing text behaviors and the new error band:

Examples:

#![allow(unused)]
fn main() {
segmented(ui, &mut mode, &["One", "Two"], Segments::default());
selection_field(ui, "Select", Selection { active: true, filled: false });
value_pair(ui, "Position", [&mut x, &mut y], ["X", "Y"], Some(["Distance X", "Distance Y"]));
button(ui, "Add", Button::Enabled(valid));
footer(ui, "OK", "Cancel", valid, Footer { apply: Some("Apply"), ..Default::default() });
text(ui, report, Text::Report("validation", invalid));
}

Icon surfaces that explicitly choose a palette ramp use icons::paint_accented. None selects base blue, while unknown names retain the icon’s semantic accent. Only active roles change: ink/line outlines, passive faces, guides and knockouts keep normal artwork colours. Existing icon painters retain their semantic-accent behaviour. Danger menu items and danger confirmation glyphs both use icons::paint_danger. It additionally maps passive-1/2/3 faces to constraint active-1/2/3, retaining the shading steps, ink outlines, handle and transparent slat details. The cache distinguishes this whole-glyph treatment from ordinary accent selection and monochrome ink masks. Radial icons follow the active tab (Sketch, Surface, Mesh, Form; other tabs use base blue) in both normal and hovered sectors; the hovered background retains its tab tint.

Extending and checking the kit

Add one implementation, document its tokens/options here, re-export it through mod.rs, and add one table entry in gallery::ELEMENTS. Keep implementation-only helpers private. Add interaction tests when the element introduces an action.

The gallery checks geometry, label alignment, handles and effective paint bounds in both themes. Field/footer/panel tests retain focus, completion and action coverage. ui_kit_guard_tests scans every UI feature module recursively, rejects raw control constructors and methods (including aliases), and rejects removed legacy helpers. The raw-control allowance table is empty and guarded against additions. Standard colour/font guards, Clippy, wasm, i18n, assets, icons and layers still apply.

See remaining coverage boundaries for specialised surfaces that remain outside the kit and why.

Popup presentation and draft rows

Panel and Window use 28 pt controls, a 40 pt title band (14 pt semibold title, 19 pt command icon and 26 pt close/fold targets), and a 48 pt footer with 28 pt actions. Table rows are control_height + space_8 (36 pt), independent of control height. Bodies use 12 pt insets. Width limits and scroll boundaries remain owned by Panel/Window/Confirm. Titles retain the supplied case.

The form_ink, form_dim, form_primary, form_error and form_error_fill colour keys match the approved light cards. Dark values follow existing text, accent and error palette roles; every role is exported by theme files and measured by the colour-vision checks. Invalid fields include both error text and a tinted surface. Long variable-height lists can use Window::placed with a top-left pivot to keep their painted controls and scenario targets aligned as they grow. Completion lists use the approved 230 pt minimum width (derived from card and spacing tokens), show kind labels on the right, selected details beneath the list, and the existing keyboard hint.

Parameters and Configuration Table use this one table grid, including Favorites and each model group. The grid has space_8 horizontal insets within the row highlight, shared by headers and cells, plus space_8 column gaps. Flexible widths are measured inside the scroll viewport and rounded by cumulative column edges; fitting content does not acquire a horizontal scrollbar from independent rounding or inherited scroll margins. Explicit minimum widths still allow genuine overflow. The viewport and measured content width publish dialog:table:TABLE:viewport and dialog:table:TABLE:content_width for geometry checks. Hover uses the clipped row rectangle, including interactive children, while preserving child click ownership. Their add prompts publish dialog:table:TABLE:add, use control_height - space_4 height, a dashed control_radius outline and a pointing-hand cursor. Clicking creates a regular unsaved row, focuses its name and exposes the existing field controls and bin. Enter or valid focus loss commits through the existing commands; abandoning a nameless row drops it. Configuration Enter with an empty name retains ConfigurationN naming and copies the active row. Parameter validity is published as param:new:valid; invalid expressions cannot commit on focus loss. The natural scrolling body height is published as dialog:body:content_height, so geometry tests distinguish content size from the viewport cap. After a successful parameter add, a fresh empty draft retains Name focus for continuous keyboard entry; leaving that empty row drops it. Parameter draft fields retain param:new:name/unit/expression/comment. Configuration drafts publish config:new:name; existing config:cell:ROW:COLUMN, activation, rule and preview handles remain. The header plus retains dialog:menu:Add Column, including the existing menu nesting. The old separate Add forms and column-removal band have been removed.

Crash Reports uses report_list (bordered bounded scroll), report_header (kind, count pill and mono UTC time), path_chip (clipped mono path and adjacent action), empty_box (dashed empty state), and icon_label_button (secondary icon/text, optional danger ink). These use dialog_rule/footer, control_*, form_*, font_label/small and spacing tokens. The report header retains the combined-title cell alias; bins retain the previous Delete handle. Report actions remain immediate. list_frame supplies the same border to virtualised library rows. The list frame owns its border and horizontal padding; the report viewport adds no inherited scroll margin. Report list measurements publish dialog:list:KEY:viewport and dialog:list:KEY:content_width. Reports use vertical scrolling; the horizontal rule beneath each report remains a divider. Appearance uses a 340 pt card derived from card/label/spacing tokens, with the 104 pt label basis where space permits, 10 pt body gaps, and a count on In This Design.

Colour popovers retain dialog:color:ROW and add color:format:U8/F, color:copy, color:channel:R/G/B, color:sv, color:hue, color:current and the color:popover rectangle. Format changes update egui’s global numeric colour presentation without changing RGB. Linear fields edit linear RGB, not normalised gamma bytes. HSV state preserves hue at zero saturation/value and sub-byte precision during drags. Gradient colours are document colour data; all interface chrome uses existing paired light/dark tokens.

Sliders only via ui_kit::slider, everywhere in crates/ui-egui/src and apps. The element owns its form styling even when called from a viewport menu. Slider options select behaviour, never appearance: range and values remain in caller units, step preserves stepping, format preserves suffixes/display mapping, integer rounds manipulation and show_value: false hides the editor. Disabled sliders use ui.add_enabled_ui; tooltips attach to the returned response. Preferences UI scale still applies only after the pointer is released. There are no alternative slider helpers, raw egui::Slider callers, or custom track/thumb painters outside the kit. The source guard scans both trees without an allowance table; the gallery covers continuous, percent/stepped, integer/no-editor and disabled states in both themes. Numeric fields use the existing kit scalar_field, length_field, angle_field or number_field rather than constructing a raw egui::DragValue at a caller.

Parameters retains its bounded header drag offset while the manager is open, including frames without a regular feature dialog. The shared Panel bound reserves header and footer space at the bottom edge. Import and both export actions use icon_label_button with the existing import/export arrow icons and unchanged command routing and scenario identities. The gallery includes all three actions. The Add Column target is form_close_size - space_4 (22 pt) square: idle paint is only form_dim ink; hover adds the selected accent fill and insertion guides. HSV gradients use a rounded mesh silhouette sampled along control_radius arcs; the current-colour strip uses the same rounded radius. Render tests sample all four corner pixels and opaque interiors of all three surfaces at 1× and 2× in both themes.

Checkboxes only via ui_kit::checkbox, everywhere in crates/ui-egui/src and apps. checkbox_row, checkbox_grid and menu checkbox rows share its single box painter and paint_check_glyph path. The box is space_14 square with radius_sm corners, a control_border outline and control_fill background. Checked/mixed boxes use form_primary and on_accent; hover uses hover and an accent border, focus adds a space_2 outset ring, and disabled controls inherit egui’s disabled opacity. Geometry never depends on caller font or native icon size. checkbox_indeterminate represents a mixed selection with a bar and activates to checked. Space/Enter, accessible checked state, tooltips and scenario handles are retained. Exclusive choices use existing kit segments/dropdowns/list pickers; there are no radio controls. The recursive guard rejects native checkbox/radio constructors (including aliases), raw toggle methods and duplicate check glyph painters across both trees without allowances. Offscreen checks compare actual box and tick geometry/pixels across form, grid, palette and menu call sites at 1×/2× in both themes.

Disclosure chevrons point down when open (content visible) and right when closed (content hidden). Only ui_kit::disclosure draws them, using the original chevron / chevron_right SVGs at form_section_icon_size, without animation (as in kit section headers). Sections, nested groups, Browser trees, card headers, window folds and the Assistant strip all follow this rule. Keep existing scenario handles, including dialog:collapse, and translated Collapse/Expand tooltips. Dropdown arrows always point down; submenu arrows point right. Playback, reorder, window management and overflow controls are not disclosures. The source guard scans UI, apps and compiled asset glyphs without caller allowances; render tests inspect the actual icon textures used by sections, card folds and window folds.

Per-tab accent tokens

TabAccent::for_tab supplies three independent theme colours: color (fill) for pills, active-tool borders and the history marker; ink for small text and selected rows; soft for tinted selection/tool backgrounds. These are palette entries, not blends. Browser rows and selected ribbon labels use ink directly.

form_tab_ink is separate from the existing form_ink used for form controls. Sketch reuses its existing fill in both themes. Surface and Form fills match their existing accents in light mode but need independent dark values; Mesh and Render fills also differ from their existing mesh_accent and render_accent values. All existing tokens, including Model’s fill, ink and tint, retain their values. The Model/default mapping preserves its existing appearance rather than adopting the proposed Model colours from the board.

The new palette entries (fill / ink / soft) are:

Each key is supported by solidcraft-theme/1 import/export, including tab_on_fill_dark (#000000 in both themes). TabAccent::on_fill uses on_accent (white in the built-in palettes) when it reaches 4.5:1, otherwise that dark ink. The fallback is black because the board’s dark ink does not reach 4.5:1 on several of the approved fills. It only styles tab pills; global primary actions still use on_accent. Built-in palette tests require WCAG contrast of at least 4.5:1 for ink on the card and panel, ink on soft, and pill text on fill in both themes. Only Mesh separates ink from fill in the light theme.

Context menu adapters retain item IDs, enabled logic and command parameters. Menu owns popup elevation (10 pt corners, 1 pt border), headings, separators, adjacent submenus and bounded arrow navigation. Enter opens a submenu or chooses its row; Right opens, Left returns, and Esc dismisses the menu. Appearance includes document swatches and Remove override through appearance.assign; its original action still opens the full editor. Workspace retains its descriptive cards and scenario handles on the shared surface. Ribbon rows reuse MenuItem::paint while owning drag, focus and pin interactions. History context menus and ribbon overflow use kit popup chrome. Rename uses the shared caption, field policy and Cancel/OK actions with its stable editor ID. No additional translation keys or colour roles are needed.

The menu gallery includes normal, hovered, open, disabled, checked/unchecked, swatch and danger rows, a submenu and rename. Radial geometry tests measure the actual side endpoints at both radii and sample all four rounded corners. Optional CPU-rendered menu evidence can be produced without a window with SOLIDCRAFT_MENU_EVIDENCE=/tmp/menus cargo test -p solidcraft-ui-egui --lib menu_board_in_both_themes. Desktop interaction and visual acceptance still require a reviewer capture.

Command search uses the ribbon field itself (sc_sbox_text); ribbon:search, shortcut:search and palette:search all identify that same field. Opening gives it the accent focus ring, cursor and Esc keycap. The field and the attached results sheet unfold in 120 ms with egui cubic ease-out, capped by egui’s animation time so instant settings remain instant. Esc, click away and command dispatch reverse the animation. Only the visible sheet height participates in layout and hit testing; result content is clipped while unfolding. The sheet’s ribbon:search_popup / palette:outer handles exclude the field. Its footer (ribbon:search_footer) fills the bottom strip edge to edge, with rounded bottom corners and a 1 pt top rule. Ranking, command mode and keyboard routing remain with the caller.

Generate CPU-rendered evidence of all five search states and the actual ribbon’s closed/opening/open/closing transition in both themes with SOLIDCRAFT_SEARCH_EVIDENCE=/tmp/search cargo test -p solidcraft-ui-egui --lib command_search.

Compact workspace composition

Container::gap and Container::frame supply the layout policy for every adaptive surface. Compact has no gaps or shadows between edge-bound panels; floating uses the shared card spacing and frame. Panel bounds draggable compact sheets to the workspace. The shared frame rounds all corners away from the right dock and only the left corners while right-docked; the footer inherits that frame’s bottom corners. Both layouts retain drag offsets. Browser uses the same content renderer and width in both modes, with a square, flush ribbon join in Compact. Non-workspace surfaces keep their roles. DockEdges declares touching edges. The container measures content-hugging cards before rounding their exposed corners, and aligns touching outlines onto a single border strip without changing logical panel allocations. The application bar has an independent surface role. The saved Prefs::layout is changed through view.layout; ui.set may still make a transient automation override.

File/start presentation

FileView owns File surfaces and controls. It accepts translated strings, existing icon ids and cached thumbnail textures; callers retain commands, document state, persistence, thumbnail jobs and recovery decisions.

• page, content and rail own the page background, responsive insets and full-height rail fill/clip. navigation also supports the narrow navigation menu. Callers supply layout rectangles, scrolling and entry order.
• nav_row accepts a stable id, label, shortcut, selection and enabled state. back_to accepts a translated {name} template, paints the document name semibold and reuses the mirrored chevron and outlined keycap. separator supplies grouped rules. Disabled rows cannot activate.
• title, subtitle, detail and section own typography. section accepts a token-based heading/body gap: space_12 for New, space_10 for Recent/Samples. Callers retain semantic section order and the larger file_section_gap.
• grid provides responsive columns with 14 pt gutters and no trailing row gap. action_tile supplies an 84 pt card with 44 pt original artwork and vertically centered label/subtitle. tile_min_width informs responsive columns.
• recent_list owns the rounded border and zero row gap. recent_row accepts a RecentRow, paints internal separators, medium names and workspace dots, and retains title/path at narrow widths. Callers handle unavailable-file actions.
• sample_grid(ui, id, &[SampleCard]) measures each row’s tallest content and stretches cards to equal bottoms without clipping descriptions. Responses stay in sample order, with stable {id}:{index} ids. Artwork inputs remain unchanged.
• recovery_banner accepts RecoveryMessage segments for a bold title, normal message, monospace filename and normal suffix. Actions align right or wrap below at narrow widths. Discard is optional for summaries; the return value is (recover_response, optional_discard_response). recovery_review uses the same geometry with per-design Discard. Callers provide truthful metadata.

The exported file_* colour tokens provide readable light/dark foreground and background pairs, including File-specific secondary text. Thumbnails retain the neutral file_image_tint; icon and text colours do not change their pixels. Spacing, dimensions, fonts and radii come from theme::Tokens.

Gallery and geometry tests cover these components. To capture the actual File view using public temporary fixtures, set SOLIDCRAFT_FILE_EVIDENCE to an output directory and run file_view_application_evidence_in_both_themes_and_widths with --ignored. It produces desktop and 420 pt narrow PNGs in both themes.

button_at(ui, id, rect, label, Button::Primary/Normal) places the same shared native button used by button inside a bounded, centred layout. It preserves stable identity, enabled state and exact caller-owned geometry. Recovery actions use this component rather than custom button painters. The recovery well renders the existing restore artwork through its construction accent ramp.

Theme corner radii

Theme files may override radius_sm, radius_md, radius_lg, radius_xl, control_radius and sketch_mode_radius in an optional radii object (integer UI points, 0–32). Missing entries retain the base palette’s shape. Light and dark variants of a family should use identical values. Import/export and preferences retain these overrides; colour vision modes leave them alone.

Use Tokens for decorative UI corners, including hover, selection, focus, image thumbnails, popups and nested surfaces. Small legacy accents derive their radius from the small token so the default appearance stays unchanged. Expanded outlines use Tokens::outset_radius so square corners stay square. Container continues to own outer surface chrome and square dock contacts. Functional geometry (circles, model selection boxes, plot clipping, manipulator handles and the artwork inside icons) retains its own shape.

Theme border hierarchy

Three structural levels distinguish outer chrome, major section rules and minor dividers. Separate solid container and control roles keep enclosing boxes independent of divider patterns.

Focus, selection, active commands, errors, recovery warnings and status keep their existing semantic strokes. Icon artwork, example mouse diagrams, plots, model edges, manipulator geometry and the compass are content; structural border roles do not recolour them.

solidcraft-theme/1 optionally accepts borders. Each role has a width (finite 0–4 logical UI points; zero hides the stroke) and a color (#rrggbb or #rrggbbaa). primary_inset also requires gap (finite 0–12 points of clear distance inside the primary border). This companion is painted inside panel/ribbon/window/menu chrome, without extra input targets or layout space; tiny surfaces omit it. Compact contacts remain square and collapse adjoining primary strokes. Other ornament, such as the circular compass and native widget-owned tooltip content, does not acquire an inset.

"borders": {
  "primary": {"width": 1, "color": "#ffffff"},
  "secondary": {"width": 1, "color": "#e5efff", "pattern": "dotted"},
  "tertiary": {"width": 1, "color": "#102748"},
  "container": {"width": 1, "color": "#a8c8ed"},
  "control": {"width": 1, "color": "#a8c8ed"}
}

Those are Blueprint’s settings: a single primary outline and dotted secondary rules. Secondary roles optionally accept pattern: solid (default) or dotted; this pattern follows horizontal/vertical section rules. Container outlines remain solid, as do the other roles. Themes without border settings retain their previous appearance. SolidCraft 95 uses silver surfaces and directional two-band bevels: light top/left edges and dark bottom/right edges for raised panels and buttons, reversed for recessed fields and pressed buttons. Inputs use the field colour independently of the neutral button face. Disabled controls fade their bevel; focus, selection and validation keep their semantic indicators. Solid grey rules divide sections.

Optional borders.bevel enables this shared container/control treatment. It accepts width (finite, greater than 0 and at most 2 points per band), highlight, light, shadow and dark_shadow (hex colours). Missing bevel settings preserve flat rendering exactly. The bands paint inside existing rounded or square geometry without changing hit targets or allocation. Ghost controls remain borderless. Missing roles preserve each surface’s existing width and colour, including overrides in colors; exporting keeps omitted roles absent so reimport cannot flatten those legacy surface differences. Dark/Light and the Gruvbox families share border geometry. Imports and direct preference updates reject unknown roles/settings, invalid colours, non-finite/out-of-range numbers and missing required settings. Invalid hand-edited saved border settings safely fall back to legacy styling. The optional field requires no format version change. There is no general border editor in Preferences; theme file import/export and the existing preference/control workflow own this extension.

Theme icon and tab colours

Theme files optionally supply icon_palette SVG roles and semantic ramps. The shared renderer snapshots that palette into the icon look and cache identity; callers continue to request semantic icon IDs and surface-specific monochrome ink. See the shipped-theme colour audit for the schema, workspace assignments, accessibility rules and intentionally monochrome themes.

Material previews and look chains

sphere_thumbnail(ui, id, Sphere { color, kind, opacity }, size) paints a lit sphere using a fixed CPU mesh and the egui painter, without a texture or GPU. FinishKind covers Matte, Satin, Gloss, Metal and Glass. Colour is document data; highlights, shadows, checker and UI chrome use Tokens. Glass shows a four-by-four checker and defaults to 35% opacity; other finishes default to opaque. Explicit opacity is clamped to 0–1; non-finite opacity uses the finish default. Sizes are rounded and bounded to 1–96 logical points (non-finite sizes become 1).

A shared per-egui-context FIFO cache retains at most 64 meshes, keyed by RGBA, finish, byte opacity and bounded size. Hits reuse shading without changing eviction order. Every mesh has 637 vertices and 1,152 triangles, independently of input. Theme highlight/shadow changes clear the cache. No file assets are added.

look_chain(ui, id, labels, looks, active) draws Face → Body → Component → Material as four connected steps. Pass translated labels, [Option<Sphere>; 4] and one LookStep; empty slots use a dashed circle and plus, while filled slots reuse the sphere cache. Exactly one step has a Tokens::render_accent ring. It returns Option<LookStep> on activation; callers own commands and selection. Disabled controls do not activate. Handles/rects are {id}:face, :body, :component, :material; {id} is the full allocation. Long labels clip within their step. These are content widgets; their enclosing surface still belongs to Container.

Gallery entries show all five sphere finishes, a mixed filled/empty look chain with Body active, and an empty chain with Face active in both themes.

For CPU-rendered review images, run SOLIDCRAFT_MATERIAL_WIDGET_EVIDENCE=/tmp/material-widgets cargo test -p solidcraft-ui-egui ui_kit::gallery::material_widgets_board_in_both_themes.

Extensible libraries: materials, appearances and components

The first local scalar-library consumer implements only copied colour/opacity and density/look definitions. Its separate v1 catalog is not the complete resource-pack/provenance/update system proposed below. Texture/environment descriptors remain coordinated with the maintainer’s renderer work.

Proposal for #785, #786 and #787. This page describes planned contracts and acceptance gates, not an implemented pack format or new commands. It does not bring the deferred Simulation or Render workspaces into scope.

Reuse the existing paths

Physical materials already have built-in densities and design-local definitions (material.create, material.edit, material.delete, material.list, material.assign). They drive component.properties, survive reopening and participate in configurations. Appearances have a built-in color/opacity library and body, face and component overrides. parts.library, parts.insert and parts.resize already generate seven families of fasteners, pins and bearing envelopes as editable components.

Extend those routes. A shared catalog supplies identity, discovery and provenance; each entry kind retains its own payload and application rules. A physical material is not a texture, and a reusable component is not executable plugin code.

Portable, independently extensible packs

Use one versioned, offline pack envelope for three kinds: physical material, appearance and component family. Both project contributors and users can author packs without rebuilding SolidCraft. Start with a directory and JSON manifest, not a new archive format or an online marketplace. The exact schema belongs in the bounded-loader PR, accompanied by machine-checked examples; the following are its design requirements:

Pack revisions and schema versions are different: the former identifies content, the latter describes how to read it. Changing content under an existing revision is an error. Unknown schema versions, entry kinds and required capabilities produce a clear refusal; they are never silently interpreted as an older format. Optional extensions need an explicit namespace and preservation rules before being accepted.

Provide three independent scopes:

• Bundled: reviewed with SolidCraft and read-only in the library editor.
• Project: packs explicitly opened for the current project/team; never discovered by silently executing or trusting files beside a design.
• User: local packs the user creates, imports, edits or exports. Native file access belongs in the app; browser users import/export through the web storage/file workflow.

Discovery order is deterministic. Duplicate labels can coexist, with their source shown. Duplicate qualified identities/revisions with different contents are errors, not overrides chosen by scan order. Editing a bundled entry uses Save a copy into a user namespace. Updating a pack is explicit and leaves existing design instances unchanged.

Designs own their selected definitions

On assignment/insertion, copy the definition, chosen revision, parameters, provenance and required resource bytes into the design’s existing container/resource mechanism. Keep the source identity for inspection and an eventual explicit Update action. A saved design must open, rebuild and render the supported appearance without the original pack, network or another user’s home directory. Installing a pack never changes a design or undo history.

Assignment/insertion/update is a normal engine command, atomic and undoable. Preview is non-mutating. A failed import, unresolved dependency, name collision or unsupported recipe leaves the document and undo/redo stacks intact. Existing material names and appearance precedence retain their legacy meaning; introduce stable IDs through a documented migration rather than reinterpret old name-based assignments. Design-format changes need their own version/migration and reopen tests, separate from the pack schema version.

Physical properties (#785)

Keep physical material and appearance selection independent, with an optional default look. Convert imported density units explicitly to the existing g/cm³ representation; geometry continues to use millimetres and radians. Never infer units from magnitudes. Properties need source, edition/date, grade, processing condition and applicable temperature/moisture when relevant. Unknown properties stay unknown, not zero or guessed values.

Start with density and mass integration through the existing commands. Reserve typed extensions for elastic constants, yield/ultimate strength, thermal properties and orthotropic axes, but do not expose these as FEA-ready until their model, units and validation are implemented. A generic wood density is not an engineering material grade. User-measured data can be stored with its own provenance and edited without changing the bundled library.

Wood and sheet appearances (#786)

Begin with body-local mapping, an explicit physical repeat size and a user-editable grain frame. Suggest the longest local body-bound axis once, with X/Y/Z order for equal extents; store the chosen frame rather than recompute it on every resize. Manual rotation and scale survive parameter rebuilds, instance placement, undo and reopening. Shared component instances transform the same definition-local mapping with their placement. Non-finite or degenerate frames refuse; automatic choice remains a suggestion.

Visual grain does not rotate the body, its geometric bounding box or a manufacturing stock frame. Structural grain direction and grain-aware nesting/cut lists are distinct features, coordinated with #137. An anisotropic shading effect also does not imply mechanical anisotropy.

After basic wood mapping, add sheet-specific top/bottom/edge looks: MDF, chipboard, plywood and compact laminate, then melamine, laminate, linoleum and veneer finishes. Appearance layers initially describe presentation only. Physical finish thickness or mass must be explicit modelling/material inputs, never an invisible side effect of paint. Face/edge assignments require durable identities and must refuse a lost association rather than paint a nearby replacement face.

Keep texture role, color space, normal-map convention and physical scale explicit. Coordinate with the render capability contract: the existing color/opacity viewport is not proof of PBR or texture support. A renderer must report what it supports; unavailable maps use a documented preview fallback with a visible notice. Export either preserves supported mapping/resources or reports loss.

Standard and user component families (#787)

Keep the existing fastener insertion/resize path. Add original parameterized BAR, SHS, RHS and CHS recipes first, with explicit length units, parameter bounds, section frames and insertion/connection frames. Validate wall thickness against the outer size and state whether corners are sharp or rounded. Do not label approximate geometry as a certified standard section. UB/UC need actual flange/web radii and tapers; identifying a standard does not grant redistribution rights to its published size tables.

A family revision defines a bounded parameter schema, permitted recipe and optional reviewed size table. A size designation identifies a row, not an arbitrary filename. Changing size rebuilds the same component identity and preserves supported connections. Initial recipes must use a small allowlist of ordinary modelling operations. No embedded native code, shell commands, scripts, arbitrary command IDs or network hooks. Reject cycles, excessive expansion and unsupported operations before mutating the design.

Custom assemblies follow single components: bounded dependencies, named connection frames, explicit shared/independent instance semantics and one-step insertion undo. Store selected parameters and definition snapshots so missing or changed catalogs cannot silently substitute another part. Geometric envelope models, including existing bearing envelopes, must remain distinguishable from detailed/manufacturing-ready models.

Sources and licensing

SolidCraft is MIT OR Apache-2.0. Code and generated recipes must follow the clean-room rules; never copy commercial CAD materials, templates, geometry, icons or catalogs. Third-party assets retain their own licenses. Every bundled resource needs its author, source, license and ATTRIBUTION.md row, even if attribution is optional under CC0. Record hashes and retrieval dates when admitting actual files. A manifest’s claimed license is provenance to review, not automatic evidence of permission.

Sources checked on 2026-10-13; no external assets or datasets are bundled by this proposal:

Prefer CC0 resources for the starter texture pack and original recipes for the starter component pack. Defer uncertain or restrictive data rather than scrape supplier sites, copy standards publications or assume a downloadable CAD file can be redistributed.

Phases and acceptance gates

Each implementation PR references these issues without closing them prematurely.

After phase 1, material/appearance integration and section-family work can advance independently. Wood mapping depends on actual renderer support, not on section families. Phase 5 is several separate PRs, each following its relevant earlier workflow, rather than one change coupling assembly insertion to face painting.

Keep parsing/resource I/O in io, durable selected definitions in doc, application and validation commands in engine, renderer-specific interpretation in render/its adapters, and discovery/editing UI in ui-egui. Lower layers do not depend on the UI or platform file dialogs. Reuse container resource deduplication; avoid a second blob store.

Before allocating/decoding, enforce manifest byte/entry/string/dependency limits, total resource bytes, image dimensions/decoded bytes and recipe expansion bounds. Paths must be relative, normalized and confined to the selected pack, including symlink handling. Phase 1 must publish exact limits and test their boundaries. Do not auto-fetch missing files or install executable extensions. Explicit import/export is enough for the first delivery.

Run cargo xtask ci for each implementation arc and check remote PR results. Geometry tests use analytic values; UI and observable CAD changes include actual app evidence. The three issues remain open until their individual workflows pass these gates.

Local material libraries

The local library transports design-owned appearances and physical-material definitions. Portable catalog v2 preserves opaque PBR parameters and validated engineering cards, including SI values, material-local axes, source records and per-property conditions. It reuses the existing commands, file pickers and library contract. The catalog has its own version; no additional design-format change is needed.

Desktop workflow

1. Apply a named colour/opacity look using Appearance, or define a physical material using Physical Material → New / Edit or the material commands. An appearance does not change physical density.
2. In Appearance → Local library, choose Export design library…. The snapshot contains explicit body/face/component appearance overrides and design-local physical materials, including their default looks. It does not export imported kernel paint, unassigned built-in catalog entries or an unapplied colour-picker draft.
3. Open that library in another design, search its appearance presets, select one and choose Apply library appearance. The normal body/face/component targets are reused. OK after this immediate application does not add a second undo step.
4. To import a physical definition in the same Local library section, enable Physical material definitions, select an entry and review its density/card. Name on import makes a collision explicit: choose another name instead of overwriting existing data. Import material into design copies the definition only. Cancel or OK after copying keeps the import and does not assign either a material or an appearance to any body. Assign the copied material later in Physical Material. Each import is one undo step.
5. Save the design. Its selected definitions are ordinary copied design data; the source library can be moved or removed without changing the saved result.

Export does not edit the design, its dirty state or history. An existing file is refused unless Replace existing library file is explicitly selected. Export is a snapshot of the design definitions, not an automatic merge with entries in an existing catalog. Editing a copied look/material uses the normal commands and does not edit its source.

Copied look labels are inert data even when equal to a starter.* recipe ID. Reopening Appearance or applying the copied look to another target preserves its color, opacity and PBR response. Library body and face targets use the same world selections as ordinary assignment, including displaced component instances; the outer command maps them into the source component exactly once.

The combined render integration uses main’s merged #1127 asynchronous picker. Model edits and tab changes wait for its answer while drawing/resizing continues. Overwrite consent is captured before opening; export snapshots the design when library.export runs after choosing the destination. Document identity is checked, and an old library answer cannot replace another Appearance editor. Cancellation does not read or write a library. The earlier #1114 candidate is no longer a runtime dependency of the refreshed consumer.

The desktop panel applies appearances and imports physical definitions. library.apply also supports explicit body assignment in the same atomic command; imported definitions appear in the existing Physical Material list and can be edited there. The browser can export a library through the existing download service. Interactive local library opening is a desktop feature in this first slice. Browser engine commands can consume a bounded catalog already supplied through VFS; wasm compilation does not prove an interactive browser importer or download workflow.

Commands

All programmatic calls use JSON and never open a file picker:

{"command":"library.export","params":{"path":"my-library.solidcraft-library.json"}}
{"command":"library.inspect","params":{"path":"my-library.solidcraft-library.json"}}

Inspection/export returns a catalog with qualified entry IDs and exact revisions. Use the returned values when applying; do not replace an unknown revision with a guessed one:

{"command":"library.apply","params":{
  "path":"my-library.solidcraft-library.json",
  "entry":"user.local/appearance-<returned-id>",
  "revision":"<returned-64-character-revision>",
  "targets":{"bodies":["Body1"]}
}}

Appearance targets can be bodies, components or faces: [{body, point: [x,y,z]}]. Points are world-space millimetres. At most 1,024 total targets are accepted. Missing objects and invalid targets fail; the importer does not invent a nearby replacement.

A material entry can be copied without targets or assigned to body targets. The optional name explicitly selects a new physical-material name on import. An identical existing definition is reused; a conflicting definition or built-in name is refused. No density, look or configuration cell is silently overwritten. Creation and assignment share one outer undo transaction through the existing material commands. Mass remains the existing volume × density calculation; a generic illustrative density is not an engineering grade.

library.export also accepts id (default user.local), name (default My library), provenance, overwrite (default false) and format (default solidcraft-library/2). Explicit solidcraft-library/1 refuses PBR or engineering-card loss before publishing, including with overwrite enabled. Only explicit assignments/design-local definitions are inspected, without evaluating geometry. Duplicate exact definitions are deduplicated; different values with the same display name remain distinct entries.

Portable catalog v2

solidcraft-library/2 extends the same envelope and definition kinds with optional pbr: {metallic, roughness, dielectric_ior} on appearance values and optional physical_card on material values. PBR uses the bounded opaque contract and requires opacity exactly one. Cards use the existing SI admission and validation rules. Sources and conditions are copied as supplied data, not certification. Card density never replaces assigned mass density. An independent default PBR look and a physical card may coexist in a material.

Applying an appearance is an exact replacement: v1 scalar values and v2 values without PBR clear the target’s prior PBR. V2 values with PBR retain their parameters. Display labels are inert, including labels equal to built-in preset IDs: importing an owned value never selects a different recipe. Undo/redo and native save/reopen preserve the copy after removing the source file.

Absent richer fields are omitted from serialization. Existing v1 scalar bytes, content revisions and identities remain exact; pinned appearance bytes and a material revision cover the writer contract. Changing only the envelope version leaves entry revisions unchanged. PBR and complete card data participate in revisions when present. V1 wire input rejects even null v2-only fields. Older readers refuse v2.

Scalar catalog v1 compatibility

The independent JSON format marker is solidcraft-library/1. It has id, name and an entries array. Each entry has id, revision, provenance and a typed definition:

• appearance: value: {name, color: [r,g,b], opacity}; sRGB bytes and finite opacity 0–1.
• material: value: {name, density_g_cm3, appearance?}; finite density above 0 and at most 1,000 g/cm³, with an optional appearance value of the same scalar shape.

Every object rejects unknown fields. Unsupported kinds (including texture/environment payloads) and versions fail explicitly, rather than dropping fields or pretending that a colour preview is a textured material. Catalog IDs are 1–64 ASCII bytes, beginning with a lowercase letter and continuing with lowercase letters, digits, ., _ or -. An entry ID is <catalog-id>/<local-id> with the same local-ID rules; paths and labels are not IDs.

An entry revision is lowercase SHA-256 of compact v1 serde JSON [provenance, definition]. Derived struct field order, omission of absent optional fields, UTF-8 escaping and f64 round-trip number formatting are part of this writer contract; this is not arbitrary JSON canonicalization. Prefer library.export or the Rust Entry::new/content_revision API when authoring revisions. A future incompatible writer changes the catalog version. The default export IDs contain a kind and 16 hex revision characters; collisions are rejected, never used to overwrite a different definition. Explicitly authored stable local IDs can retain their identity across revisions. Application requires the selected exact revision. Changing another entry does not change the selected definition’s identity.

Provenance contains a required license, optional author and optional source_url. It is supplied metadata, not verified permission or a publisher signature. URLs are never fetched. The default LicenseRef-User-Provided does not claim that user data is openly licensed. No external art/data is bundled in this slice. Catalog provenance/revisions stay in the catalog: values are copied into existing Look/UserMaterial records without a persistent catalog-origin/update receipt. Card source records and property conditions belong to the card and are copied exactly. Resource embedding and explicit update links remain separate work.

Bounds and failure behavior

The reader accepts at most 4 MiB encoded JSON and 1,024 entries. A bounded raw preflight preserves strict v1 wire fields before typed decoding. Entry decoding stops at the count cap with fallible vector growth. Names are trimmed, nonempty and at most 128 UTF-8 bytes; provenance license/author/source URL limits are 128/256/2,048 bytes. Control characters, invalid identifiers, duplicate identities, bad revisions and nonfinite scalar values fail. Export inspects at most 100,000 source references, deduplicating into at most 1,024 entries. Export bounds retained unique definitions before whole-catalog encoding, reserving 4 KiB for the envelope and counting each entry’s pretty bytes plus nested indentation. This conservative admission may refuse a near-limit compact catalog. Physical imports also obey the design’s 1,000-material cap. These are encoded/work limits, not a process-memory or latency guarantee.

Native reads are bounded regular-file reads; browser reads check VFS size before cloning. Native no-clobber writes reuse atomic new-file publication; explicit replacement is atomic without reading/backing up an arbitrarily large old target. All library command paths obey the active MCP/control file scope before reading or publishing, including overwrite. Browser VFS publication is synchronous and reuses the host’s download service. No automatic discovery, asset fetch, relative-resource resolution, executable recipe or plugin is introduced.

Failed application preserves the document and undo/redo history. The source file is read and checked before copying; a stale selected revision needs an explicit reload/reselection. The copied design remains independent after successful assignment, undo/redo and cold reopening. This library has no dependency on the pending render stack and does not change the document format. User-visible evidence and actual native/wasm results are recorded in the PR; geometry/robustness checks remain separate and no reference baseline is weakened.

Scope

The catalog carries the document’s scalar/opaque Look and engineering-card values. It does not transport GPU2 runtime overrides, refractive glass, clearcoat, texture resources, mappings, image files or environment maps. The six starter glass recipes remain recipes; v2 does not turn an IOR or alpha preview into refraction. Unknown resource kinds and fields fail explicitly. A runtime GPU-only look must not be presented as captured by this design-definition export.

The command engine

Every user-visible action is a command: a CommandSpec registered in crates/engine/src/cmd/, with a dotted, lower-case id (solid.extrude, sketch.create, timeline.rollback). The toolbar, dialogs, marking menu, S box, scripts, the CLI, the control channel and MCP all run commands through Session::execute(id, params). Commands take JSON parameters and never open dialogs; a dialog is a front-end form that builds the parameters.

#![allow(unused)]
fn main() {
CommandSpec::new("solid.fillet", "Fillet", fillet)
    .at("SOLID", "MODIFY")      // toolbar tab and panel ("" = not on the toolbar)
    .icon("fillet")             // drawn in code, assets/icons/ui/source/icons.rs
    .key("F")                   // default shortcut
    .params("edges: [[x,y,z] | {body, index}]; radius: expr; …"),
}

run is fn(&mut Session, &Value) -> Result<Value>, and enabled is fn(&Session) -> Result<(), String>; the error string is the disabled-button tooltip. The params string is the one-line documentation shown by solidcraft-cli commands, MCP’s list_commands and the command reference.

A command that changes the design is undoable by default: the session snapshots the document before it runs, and a failing command leaves the document unchanged. Feature commands add a feature to the timeline and let the document evaluate it; they validate their inputs first (units, ranges, references) and return BadParams instead of building a broken feature.

Only the registry’s own dotted ids name commands (matched ignoring case); any other id fails with unknown command, which names up to three close ids: a typo’s (solid.extrud), or one ending in the same word (file.open: did you mean doc.open?).

Adding a command

1. Add a CommandSpec to the right file in crates/engine/src/cmd/ and implement run.
2. Give it input and output schemas: a parameters type (its contract) and a reply type in the module for its command file under crates/engine/src/schema/ (schema/features.rs for cmd/features.rs, and so on; create it for the file’s first contract), built from the shared field types in schema/types.rs. Register them with checked!(…), .contract(…) and .output(…), as solid.extrude does, and add the command to that module’s schemas_and_the_key_check_agree test, with error-message cases and a reply test. The parameters type documents each parameter (keep the .params(…) prose too, for now), and describe_command serves both schemas to agents and scripts. A test (every_command_has_input_and_output_schemas) warns for a command without them, and will fail it once the rule becomes required; the commands that predate the rule are listed in schema/unconverted.txt, which only shrinks. Command schemas walks through it, with the shared types and a checklist.
3. Write engine tests that measure the result: volume, area, and face/edge/vertex counts against values you can derive by hand.
4. The hostile-input test (hostile_params_never_panic in crates/engine/src/tests.rs) runs your command automatically with every documented parameter set to junk. It must return errors, never panic.
5. For UI work, add a scenario (see Test harnesses).

Command schemas

Every command has an input schema and an output schema (JSON Schema 2020-12), generated by schemars from two Rust types:

• a contract: the parameters type, checked in front of the handler (see crates/engine/src/schema/mod.rs); with the session’s check level at warn or strict, a misspelt key or a wrong-typed value is reported or refused instead of silently ignored;
• a reply type: what a successful call returns.

engine.describe and the MCP tool describe_command serve both, so agents and scripts read a command’s exact parameters instead of guessing from prose.

When the check fails

The tests in crates/engine/src/schema/coverage_tests.rs say what to do. A command without schemas is only a warning for now (the test prints the list); it will become required once the PR backlog is down, so give new commands both schemas now. Set SOLIDCRAFT_SCHEMA_RULE_STRICT=1 to make the missing-schema check fail today.

• “x.y has no input or output schema” (or “no input schema”, “no output schema”): a new command. Give it what it lacks, as below. Don’t add it to schema/unconverted.txt: that list holds only the commands that predate the rule.
• “x.y has its schemas now: remove its line from unconverted.txt”: you converted an old command. Delete its line.
• “x.y is a planned! placeholder, which needs no line in unconverted.txt”: delete its line.
• “unconverted.txt names commands that don’t exist”: a command was removed or renamed. Delete its line.
• “unconverted.txt must be sorted, each id once”: keep the list in byte order (LC_ALL=C sort).
• “x.y ran with an unknown key in strict” or “x.y should refuse with …”: it has a contract, but its run isn’t crate::checked!("x.y", <its handler>) (step 5): the wrapper is missing or names another command’s id.

Writing a contract

1. List the keys the handler reads

The contract’s keys are exactly the keys the handler reads, no more and no fewer. Read the handler and everything it passes p to:

• direct reads: p.get("k"), params::expr(p, "k"), req_expr, str_, num, bool_, vec3, string_list and the like;
• features::add_feature (every feature command) reads name, body_name, body_names and participants: take them with FeatureCommon. What participants changes depends on the feature, and for some it changes nothing in the result: check where the feature is evaluated (crates/doc/src/eval.rs). participants takes its description from FeatureCommon, shared by every feature, so say what it does for this one elsewhere: where it and another key override each other (a primitive’s targets gives way to it; an extrude’s targets overrides it), in that key’s description; where it has no effect, in the summary or in the description of the key it might seem to change (bounding solid’s bodies). A feature that makes no body (scale) declares name and participants itself instead, as body_name and body_names would do nothing. It keeps participants because timeline.redefine passes a feature’s own back, though for a scale it changes nothing either; its own description says so. For the primitives (box, cylinder, sphere, torus, cone) add_feature also reads targets; a new primitive must join the primitive match in add_feature_in, and its contract declares targets. The commands that combine bodies read operation (and usually targets) in their own handlers;
• keys read around the command: frames::to_local reads body (and face_body) for commands that take picks;
• live, for a command with .live(…) (today sketch.drag and sketch.edit_text): a call with live: true goes to the live runner, which checked! doesn’t wrap, so live calls aren’t checked yet. Leave those two on the list until the engine checks the live path too. A new command that needs a live runner still gets its contract (declare live as an optional bool); say in its pull request that its live calls aren’t checked.

A key the handler reads only in some situations (thin-wall keys with thin: true) is still a field; its description says when it applies. Contracts don’t check combinations of keys (sketch with face); the handler does.

2. Put it in the module for its command file

Contracts for cmd/features.rs live in schema/features.rs, for cmd/inspect.rs in schema/inspect.rs, and so on, each with its tests in a file next to it (schema/features_tests.rs). For a command file’s first contract, create the module and add its pub mod line, sorted, under “The contracts, by command file” in schema/mod.rs. A new module starts like this (keep the imports it uses):

#![allow(unused)]
fn main() {
//! Contracts and result types for the commands in `cmd/wedge.rs`.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use super::types::{FeatureCommon, LengthExpr, OperationParam, PointExpr3, StringList, feature_common, present};

// …the parameters and reply types…

#[cfg(test)]
#[path = "wedge_tests.rs"]
mod tests;
}

3. Write the parameters type

#![allow(unused)]
fn main() {
/// Add a wedge primitive.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct WedgeParams {
    /// Size along X.
    pub length: LengthExpr,
    /// Size along Y.
    pub width: LengthExpr,
    /// Height at the thick end, along Z.
    pub height: LengthExpr,
    /// The wedge's minimum corner. Default: the origin.
    #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PointExpr3")]
    pub corner: Option<PointExpr3>,
    /// How the wedge combines with existing bodies. Default: new.
    #[serde(default)]
    pub operation: Option<OperationParam>,
    /// The bodies a join, cut or intersect works on. Default: every body in the feature's
    /// component, not its sub-components (an intersect removes those the wedge doesn't meet).
    /// Ignored when `participants` lists bodies.
    #[serde(default)]
    pub targets: Option<StringList>,
    #[serde(flatten, deserialize_with = "feature_common")]
    pub common: FeatureCommon,
}
}

• Descriptions are the documentation. The struct’s doc comment is the command’s summary and each field’s doc comment is its description in the schema, so put nothing else on those lines. Say the unit or form, the default (Default: …) and when the key is ignored. Write for someone who has only the schema. Check what each value does where the feature is evaluated (crates/doc/src/eval.rs and the kernel), not only how the handler reads it: a limit the evaluation enforces (a torus’s minor must be less than its major) or a key it ignores belongs in the description. A scale’s factor, for one, has no effect when factors is given, though it must still evaluate.
• Required or optional follows the handler: a key it can’t do without is a plain field; any other is #[serde(default)] Option<T>.
• null: the common readers (str_, num, bool_, expr, string_list) read null as absent, which a plain #[serde(default)] Option<T> matches. Readers that parse p.get(k) themselves (features::feature_sketch, features::profiles, the pick lists) refuse null; for those keys use #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")] with #[schemars(with = "T")]. The key may then be absent but not null, the schema has no null branch, and skip_serializing_if stops schemars publishing default: null, which the schema itself would refuse.
• Use a shared type for every value it fits (below) rather than String or f64: shared types accept exactly what the handlers’ readers accept, give the handlers’ messages, and publish the matching schema.

4. Write the reply type

A feature command whose handler returns add_feature’s reply unchanged returns FeatureResult (in schema/features.rs): use it, don’t copy it. A command that returns anything else, including a feature command that reshapes the reply (solid.thread returns {feature, name, thread}), gets its own reply type:

#![allow(unused)]
fn main() {
/// What `wedge.measure` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct WedgeMeasureResult {
    /// The wedge's volume, in mm³.
    pub volume: f64,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}
}

• Build the handler’s reply from the type (serde_json::to_value(reply)), as add_feature_in builds FeatureResult, rather than a json! literal next to it. Then the schema can’t drift from what the command returns.
• Warn mode adds param_warnings to a successful reply that is a JSON object, so an object reply type keeps that field. A reply that isn’t an object (a list) is returned unchanged and has no such field.

5. Register them

In the command file, next to its COMMANDS:

#![allow(unused)]
fn main() {
use crate::schema::features::FeatureResult;
use crate::schema::wedge::WedgeParams;
use crate::schema::{TypedContract, output_schema_for};

const WEDGE_CONTRACT: TypedContract<WedgeParams> = TypedContract::new();

// in COMMANDS:
CommandSpec::new("solid.wedge", "Wedge", crate::checked!("solid.wedge", prim_wedge))
    .at("SOLID", "CREATE")
    .icon("wedge")
    .contract(&WEDGE_CONTRACT)
    .output(output_schema_for::<FeatureResult>)
    .params("length, width, height: expr; corner?: [x,y,z] …"),
}

.contract and .output publish the schemas, and checked! checks each call against the contract that its id publishes, in front of the handler, so what is checked is always what is published. The handler itself doesn’t change: it still reads the raw parameters. Keep the .params(…) prose: the command list, the palette and describe_command’s params still show it, until it is generated from the schemas.

6. Test it

In the module’s tests file:

• schemas_and_the_key_check_agree: add assert_keys(input_schema_for::<WedgeParams>(), &[…]) with the keys, sorted, FeatureCommon’s included. The keys then change only on purpose.
• strict_keeps_todays_errors: for calls the handler already refuses (a malformed value, an unknown spelling), add cases to assert_strict_keeps_todays_errors: strict must give the same message as the handler. Leave out the cases its documentation lists as different on purpose, such as a missing required key (strict says `length` is required, the handler something else).
• A reply test: run the command and check the reply matches its output schema with conforms (replies_match_the_output_schema in schema/features_tests.rs shows how; its misspelt-key call checks that a reply carrying warnings still matches). Run every form the command takes (each alternative key, such as corner or center, each operation, one name and a list of names) in Warn, and check those replies have no param_warnings: Warn runs a call the contract refuses anyway, so a matching reply doesn’t show the contract accepts the call. A reply that isn’t an object never carries param_warnings; run those calls in Strict, where a refused call is an error. In the same file, converted_primitives_and_body_commands_reply_with_feature_result shows the Warn and no-param_warnings checks across several commands.

schema_defaults_are_valid checks the default of each top-level parameter on its own; a nested type’s defaults are yours to check.

7. Converting a command that already exists

Do steps 1 to 6, remove its line from schema/unconverted.txt, then check the contract against every caller the tests have: run the whole suite with the audit recorder and summarise it.

mkdir -p audit
SOLIDCRAFT_PARAM_AUDIT=$PWD/audit cargo test --workspace --no-fail-fast --features solidcraft-engine/param-audit
python3 scripts/param_audit.py audit

The recorder doesn’t create the directory, and it writes nothing if it can’t, so check the summary’s first line says at least one file. Each line under “SUCCEEDS TODAY, STRICT WOULD REFUSE” is a call that works today and that strict would refuse: a form the contract is missing (fix the contract) or a caller’s mistake, such as a misspelt key (fix the caller). Put the summary in the pull request.

Shared types

In crates/engine/src/schema/types.rs. Each accepts exactly what its reader accepts, most by calling that reader.

When no shared type fits

Add one to types.rs, next to the reader it mirrors:

• Its Deserialize calls the handler’s own reader, so “the contract accepts it” means “the handler accepts it”. Don’t re-implement the parsing. Many readers are private to their command file or need the design (features::point_param takes the Session). Split out the part that only looks at the JSON as a pub(crate) function, have the handler call it, and re-export it from cmd/mod.rs, as face_ref_form and edge_ref_form are; whether the value finds something in the design stays in the handler.
• On failure it gives the handler’s message. Wrap a message that is already a whole sentence, such as the handler’s unknown operation `x` (…), in whole(…), and the check passes it on as it is. Otherwise start it with “must”: the check names the key, so “must be a point [x, y, z] of numbers” becomes "`corner` must be a point [x, y, z] of numbers". (Any other message comes out as "`corner`: …".)
• Its JsonSchema describes the same values, with a description. Where JSON Schema can’t say something the reader checks (ignoring case, a byte length), say it in the description. A pattern that allows surrounding whitespace must allow exactly what Rust’s trim removes: build it from WHITESPACE, as not_blank_pattern and AxisDir do, rather than writing a regex’s whitespace class by hand (it differs, and the escapes are easy to get wrong). conforms doesn’t read patterns, so pin the pattern’s text in a test.
• Test both: values the reader accepts and refuses are accepted and refused by the type, and they match the schema (the conforms helper in schema/tests.rs; see face_and_edge_refs_match_the_pick_readers).
• A handler that reads a key more leniently than any type can (a wrong-typed value read as if the key were absent) gets the stricter type: that difference is what warn and strict report.

Checklist

1. The contract’s keys are exactly the handler’s reads, including add_feature’s (less body_name and body_names for a feature that makes no body), the frame mapping’s and live.
2. The struct and every field have descriptions, with defaults and when a key is ignored.
3. Shared types wherever they fit; a new type calls the handler’s reader and gives its message.
4. FeatureResult for a command that returns add_feature’s reply unchanged, else a reply type the handler builds its reply from.
5. checked!, .contract and .output on the CommandSpec, and the .params prose kept.
6. assert_keys, error-message cases, a reply test.
7. For an existing command: its unconverted.txt line removed and the audit summary in the PR.

The kernel boundary and truck

crates/kernel is SolidCraft’s B-rep kernel. It wraps truck (Apache-2.0) for topology, NURBS geometry, booleans, tessellation and STEP parsing, and it is the only crate allowed to use truck. Callers get SolidCraft types (Body, face and edge indices, meshes, measures) and a KernelError instead of truck types and panics.

guard

truck can panic on geometry it doesn’t handle. Every call into it goes through solidcraft_kernel::guard, which catches the panic and turns it into KernelError::Internal, leaving the model unchanged:

#![allow(unused)]
fn main() {
pub fn guard<T>(what: &str, f: impl FnOnce() -> Result<T>) -> Result<T>
}

A failing feature shows an error on the timeline; it never takes the app down.

What is our own

truck has no fillets, chamfers, shells or face edits, so these are SolidCraft code in the kernel: constant, chord and variable-radius fillets with corner blends, chamfers, shell and offset, Delete Face, Split Face, Replace Face, sewing, STEP and IGES reading and writing beyond truck’s parser, and face provenance (which input face each output face came from, for persistent naming).

Vendored truck crates

Patched copies of truck-shapeops, truck-stepio and truck-meshalgo live in vendor/, wired in with [patch.crates-io]. The patches fix robustness bugs found by our tests and the STEP corpus. vendor/ is excluded from our fmt and clippy rules, and each patch should go upstream when it can.

Equal cylinders crossing each other (tangent_cylinders.rs) touch at two points, which truck’s mesh-based intersection cannot trace through. When a boolean of such a pair fails, the kernel splits both cylinder faces along the line through the touching points and takes the boolean of the split bodies; the shapeops patch that picks the corner of a face at a vertex several curves end on makes the arms of the crossing connect.

Some truck assertions only run in debug builds and can fail on valid geometry, so tests and CI run with --release.

Persistent naming

A fillet stores the edges it rounds, a sketch the face it sits on, a shell the faces it opens. If those were face and edge indices, an upstream edit that adds a face would move the fillet to another edge. SolidCraft stores names, and finds them again every time the timeline evaluates.

Why names follow the kernel’s history

Names used to be worked out from geometry: sample points of each new face were looked up on the faces of the feature’s input, and the majority won; pieces of a split face were numbered by where their centres lay. That guess is right most of the time, and wrong exactly when it matters: after an upstream edit that splits, merges, mirrors or shrinks a face, points can land on a neighbour, centres can swap order, and a fillet or a sketch quietly re-attaches to a different face. Nothing tells the user, which is the worst thing a CAD tool can do.

The kernel now reports, for every operation, what each face and edge of its result came from (crates/kernel/src/history.rs: a face’s origins and how it changed, an edge’s origin edge or the faces whose meeting made it). Names follow that history, so they are exact and deterministic, and when a reference can no longer be found exactly the feature says so instead of guessing.

How a body’s faces are named

crates/doc/src/lineage.rs composes the histories of the kernel operations a feature runs (a tool built from a sketch, cut from each target, the cut body split into lumps) into one lineage over operands that can be named:

crates/doc/src/history_names.rs names each face of the result from its origins: a kept or trimmed face keeps its origin’s name, a fillet or chamfer face is F<feature>:blend:<edge> of the edge it replaces, a shell’s inner wall F<feature>:inner:<face>. A side’s sketch curve is the curve the profile segment lies on exactly; nothing is sampled.

• Pieces. Faces that end up with one name are pieces of one face, and are told apart by the faces around them that the others lack: F2:top#[F2:side:l4,F4:side:l4] is the piece of the block’s top bounded by its left wall and the slot’s left wall. That survives the slot moving, growing or shrinking. Pieces nothing around them tells apart are numbered (#1, #2): by what they came from when that differs (the two halves of a circle’s wall), else in kernel order and then unverified.
• Merged faces. A face made of several (a join flush with the body) takes the name of the face they are all pieces of, else the target’s; it answers to the others’ names too (aliases).
• Edges are named by the faces they separate, <face A>|<face B>, ~k when several edges run between the same two faces (numbered by where they lie; a reference by such a number is reported when only geometry confirms it).
• Lumps. When a cut leaves a body in pieces, the whole is named first, so pieces of one face in different bodies are told apart, and the bodies (Bar, Bar (1)) are assigned in the order of their least face name, not the kernel’s shell order (which an upstream edit can swap; see Older designs).

Names are worked out lazily, on first request, and shared by a body’s clones.

Linked designs

A linked design (Insert Design) comes in as STEP text, which keeps no names: its faces would be named by their place in the file (face:<k>), and adding a hole to the part can give that place to another face. So when the link is made or updated, each face is matched to the face of the part it was written from (the same geometry, so a point well inside one lies on the other) and the Import feature keeps that face’s name in the part (Feature::link_faces). The face is named F<import>:link:<digest>, a digest of that name (which may hold anything: the part’s feature numbers and @, | mean something else in the assembly), and a piece keeps its qualifier with the faces around it named the same way. A joint or other reference on a linked face therefore stays on it across Update Links exactly as it would inside the part, and says so when the part no longer has the face. Every linked face still answers to face:<k>, so references made before keep finding their face by place; Update Links warns about joints that do.

Where there is no history

A body made by an operation that does not report history yet (some kernel paths return none; see the kernel’s handoff lists, and the doc features that do not compose it yet: sheet metal, plastic and surface features, emboss, rib, replace face, the faceted thread cut), or a face whose role is not known exactly (a loft’s sides, a coil’s or pipe’s generated profile, a hole’s tool), is named the old way, from geometry, and its names are marked unverified (model.faces reports exact: false). A reference that resolves through an unverified name while its stored point no longer lies on the face says so: face ... was found by geometry, not exact history; check it.

How a reference finds its face again

crates/doc/src/name_lookup.rs, in order:

1. the face with that name;
2. the one face answering to it: merged into it (the feature says it was merged), or the named piece, which the faces listed in its name still bound;
3. the pieces of it (it was split, or it is on several bodies): the one nearest the reference’s point, and the feature says it was split;
4. nothing: the feature falls back to the geometry it recorded and says the face no longer exists.

An edge name is found as the edge between the two faces it names, each found as above: when exactly one edge runs between them it is that edge, even after a split of one of its faces.

A sketch’s link to a projected edge (sketch.project {edge: [x, y, z]}, and Intersect and Include 3D Geometry of an edge) keeps the edge’s name beside its point. The link is that edge wherever a change takes it; of an edge that was split it is the piece nearest the link’s point, and the sketch says so. When no edge has the name any more the link is lost and keeps its last geometry, as it does for a face: it does not take whichever edge is nearest now. A link saved without a name, by a build that kept only the point, is found by the edge nearest its point, as it always was, and takes that edge’s name when its sketch is next edited.

A command that takes a face as a point can be given a name model.faces lists instead (face.delete, solid.shell, solid.draft, solid.offset_face, solid.split_face, the faces of solid.replace_face, the face of sheet.convert). It is found with the same lookup (naming::locate_one: the face with that name, or the one face answering to it, on the given body or any body; a name that finds several faces is refused). The command takes a point on that face (naming::named_face_point: the incentre of the face’s roomiest triangle, moved onto the surface of a plane, cylinder, cone, sphere or torus), which the feature stores like a picked one, with the name it then gets as before. Nothing new is stored in the design. model.faces lists that point for every face.

Profiles picked by their curves

A profile picked by a point or an index is stored by the curve ids of its outer loop (ProfileSel::Curves), so it follows dimension and parameter edits exactly. Editing the outline itself can leave no profile bounded by exactly those curves; the feature then falls back to the best match and warns, instead of failing and taking its body and everything after it along (profile_refs::fallback_loop):

1. all the stored curves are still there and still close a loop on their own, but another curve now cuts the region: the pieces inside that loop that touch it, which together are the region that was picked (islands inside stay holes);
2. otherwise the profile whose outer loop shares the most of the stored curves, at least half of them (a side deleted and drawn again, a notch trimmed in); a tie goes to the one with the fewest curves the loop did not have, and a tie left after that is an error, as is a loop that matches nothing.

Loops of offset curves and legacy graph-span multisets keep their exact meaning. Commands still check a pick with the exact rule, so a curve list that names no profile is refused when given. A sketch on such an extrude’s cap falls back the same way: its certificate names the loop, and the cap of the same solid extrude at the same end, from the same sketch and on the same body, that shares the most (at least half) of its curves stands for it, unless the exact cap is still on another body (Document::anchored_face_indices).

A hole placed by a position on a face is the exception to “the point nearest the reference’s point”: its position is a place, not a pick. The hole follows its face along its own axis, so it moves with the face when the face moves, and when the face no longer reaches the position it stays where it was placed and the feature says so, instead of sliding to the face’s edge and drilling half a hole there. (Holes at sketch points follow their sketch.)

Older designs

Designs saved before format 14 stored names worked out from geometry, and a few of them name a face that history names differently (a tube’s outer wall was named after the sketch curve nearest its centre, its inner circle). Migrating such a design marks those names (?F2:top#2), and they are found among the names geometry gives, as the build that saved them found them: an older design evaluates as it was saved. Picking the face again stores its exact name.

Their features also keep naming the pieces they split a body into in the kernel’s shell order (Feature::shell_piece_order, set by the migration): the body names stored after them (fillet and chamfer bodies, targets, participants, materials, appearances, joints) mean the pieces in that order. Features added later name their pieces after their faces.

Not done yet

• Certificates (FaceSource, the strict attachment identities behind sketches on faces and configured face styles) still travel only where the kernel’s planar-source mapping keeps them; carrying them through History::face_sources would let a certified attachment follow a face a later join reshapes, which today is refused on purpose.
• Operations without history, listed above, keep the unverified geometric names.

Test harnesses

cargo xtask ci runs everything a pull request must pass: fmt, xtask assets, xtask licences --check, xtask layers, clippy with -D warnings, the tests with the ci profile and the wasm build check.

Dependency advisories

Scheduled and manually dispatched CI runs have a separate Dependency advisories job; new advisories do not fail unrelated pull requests. To run the same scan locally:

cargo install cargo-deny --version 0.20.2 --locked
cargo deny --locked check --warn unmaintained advisories bans sources

The checked-in deny.toml rejects vulnerabilities and unknown registries/git sources. Unmaintained crates, yanked versions and duplicate versions warn; licences remain covered by cargo xtask licences --check. Review advisory failures and update dependencies rather than adding broad ignores. The first scan prompted an update to quick-xml 0.41.0 for RUSTSEC-2026-0194 and RUSTSEC-2026-0195.

Coverage excludes the version matching of local path patches: truck-shapeops, truck-stepio, truck-meshalgo, matext4cgmath and egui-wgpu in vendor/. Their checked-in code and patches still need comparison with their permissively licensed upstreams; a green scan does not establish their security or incorporate an upstream fix automatically.

UI scenarios

A scenario is a JSON list of steps run against the real app with a headless egui context:

[
  {"start": "sketch.create"},
  {"click": {"plane": "XY"}},
  {"start": "sketch.rectangle.two_point"},
  {"click": {"sketch": [0, 0]}},
  {"click": {"sketch": [40, 30]}},
  {"expect": {"errors": 0}}
]

A new file in crates/ui-egui/tests/scenarios/ is picked up automatically. To record a bug before it’s fixed, add a {"pending": "why"} step; its test is then ignored with that reason, and the fix removes the step.

CI profile

CI runs the tests with --profile ci: light optimisation, line tables, no LTO and debug assertions off. Some truck debug assertions fail on valid geometry; the ci profile disables them while building faster than --release. If a test fails only in a plain debug build, say so in the PR.

Run cargo xtask test to build with this profile and run the test binaries concurrently, with doc tests alongside. Arguments after -- go to each test binary, for example cargo xtask test -- shell. To run the test binaries sequentially instead, use cargo test --workspace --profile ci. On a loaded machine set SOLIDCRAFT_TEST_JOBS=N to bound how many test binaries and side commands run at once; each binary then gets RUST_TEST_THREADS and ACTION_MATRIX_JOBS of max(1, cpus / N) so the binaries in flight share the machine instead of each defaulting to one worker per CPU. Setting RUST_TEST_THREADS or ACTION_MATRIX_JOBS yourself overrides that split, and leaving SOLIDCRAFT_TEST_JOBS unset keeps the original all-at-once behaviour.

Test-level scheduling for full local CI

Install cargo-nextest, then set SOLIDCRAFT_TEST_RUNNER=nextest when running cargo xtask ci. For example, on PowerShell:

$env:SOLIDCRAFT_TEST_RUNNER = 'nextest'
cargo xtask ci

This optional backend builds the workspace tests once, then schedules individual tests using the local-ci nextest profile, which inherits ci. The action matrix runs first, then the longest geometry cases start before the other costly tests, so the ordinary queue does not stall behind an all-slot reservation. It ignores the default filter, so the heavy tests below still run, does not stop after a test failure, and does not retry failures. Tests marked #[ignore] remain ignored, as with the ordinary full local CI. The default concurrency is at most four tests; NEXTEST_TEST_THREADS overrides it. The action matrix’s child workers default to the smaller of that budget and the host CPU count; ACTION_MATRIX_JOBS explicitly overrides this worker count. The local profile reserves CPU slots for the matrix and keeps its scheduling changes separate from GitHub CI. On Windows, the solidcraft-gpu and app packages, plus UI offscreen/GPU tests, use a serial group. The Wasm check and doc tests still run alongside, and the web-offline gate still follows a successful native/Wasm/doc run.

The backend keeps Cargo and binary metadata under target/xtask-nextest/ and reuses it for the native run, freeing Cargo to run the side gates. Nextest prints each test’s result and duration as it finishes. SOLIDCRAFT_TEST_RUNNER=libtest (or leaving it unset) retains the original runner; cargo xtask test and its Cargo/libtest argument forwarding are unchanged. Unknown runner names fail explicitly.

CI sharding and heavy tests

On GitHub, one job builds the tests into a cargo-nextest archive and four jobs run a quarter of the tests each (two halves on a pull request; --partition slice:N/4, settings in .config/nextest.toml), the slowest tests first; doc tests run in their own job. Pull requests skip a few heavy tests (each takes one to twelve minutes); they run on every push to main, nightly, and in cargo xtask test:

• solidcraft-engine: tests::hostile_params_never_panic, everything in tests::robustness and the seeds of tests::robustness_goldens (seed_00 … seed_95; pull requests that change the kernel, truck or the goldens run all but the slowest, SLOW_SEEDS in ci.yml), pattern_suppress_tests::enclosure_arc_extinction_keeps_a_real_sharp_inner_lip_after_resize_and_reopen, pattern_suppress_tests::enclosure_datums_follow_wall_height_and_board_depth_with_material_proofs, cmd::plastic::tests::enclosure_snap_fit_follows_resized_front_wall, the atomic_commands contract tests
• solidcraft-kernel: tests::boolean_identity_on_tangent_primitives, tspline::tests::hostile_tsplines_never_panic, and the boolean_props property tests (these run only in the nightly “Property tests” job: their inputs are random, so main skips them too)
• solidcraft-ui-egui scenarios: acceptance_sensor_enclosure

The action matrix (apps/solidcraft-cli/tests/action_matrix.rs) tries every ordinary action (sketch, offset plane, press pull, hole, draft, shell, fillet, chamfer, construction geometry, move, mirror, pattern) on every face, edge, vertex and body of a corpus of designs and compares with a checked-in baseline: an action that passed there and fails now fails the test. Every run checks a fixed sample; the nightly “Action matrix” job runs it all. After a fix, record what passes now with cargo xtask action-matrix --bless. The results and the causes of the failures are in the action matrix page.

To run exactly what a pull request runs: cargo nextest run --cargo-profile ci --profile ci; add --ignore-default-filter for the full set. A new test that takes over a minute on CI can join the list (the default-filter in .config/nextest.toml) if it guards robustness rather than everyday behaviour.

Control protocol

The control channel is on by default. SolidCraft listens on 127.0.0.1 only, for JSON lines, so agents can drive the app without a launch flag. Every connection still needs this launch’s token (below); nothing else on the machine, and nothing off it, can send a command.

The setting is read at start-up. Old preference files, which don’t have it, load with it on. A launch with --control or the variable behaves as it always did (the start page stays hidden, the window doesn’t ask for the foreground), because a scripted launch expects that; the default channel changes neither for a normal launch.

Finding the port

Each app that opens its channel writes the port to a discovery file beside the token files, control/current.port (same folders and permissions as below), and removes it at exit if no later app has replaced it. It holds only the port, never the token. solidcraft-cli mcp with no arguments reads it, checks that something listens there and bridges to that app; with no app running, or with --headless, it runs a session of its own. --connect HOST:PORT and the other arguments still decide first. With several windows open, the most recently started one is the one found; use --connect for another.

Requests are one line {"id": …, "method": "…", "params": {…}}; replies are described below. Each request is one line {"id": …, "method": "…", "params": {…}}; each reply is one line {"id": …, "ok": true, "result": …} or {"id": …, "ok": false, "error": "…"}. Requests are handled on the UI thread between frames; pointer and keyboard input is injected as real egui events, one pointer event per frame. A connection that sent control.subscribe is also sent event lines {"event": "…", "params": {…}}, which have no id (Following the design).

Token

Every connection must authenticate. At start the app makes a random 256-bit token for this launch and writes it, as one line of hex, to a file only the user can read:

On Unix the folder is 0700 and the file 0600; on Windows the file’s inherited permissions are replaced by a single entry for the user. SOLIDCRAFT_CONTROL_DIR moves the folder. The file is removed when the app exits, and the next launch writes a new token. The token file’s path is printed to stderr at start-up. Beside it, <port>.pid holds the app’s process id (and, on Linux, its start time).

An app that is force-quit can’t remove its files, so a later client may send that launch’s token. When the app refuses it, solidcraft-cli mcp names the token file it read and when it was written, and says the file is stale when the process in <port>.pid has exited. Delete the file or restart SolidCraft. On Windows, an app or client started from inside an MSIX-packaged app (and the tools it launches) has its AppData redirected: it writes and reads %LOCALAPPDATA%\Packages\<package>\LocalCache\Local\SolidCraft\control\ before the folder above.

The first request on a connection must carry the token as a top-level "token" member ({"id": 1, "method": "ui.inspect", "params": {}, "token": "…"}); later requests on the same connection may leave it out. A first line without the right token is answered with {"ok": false, "error": "unauthorized: …"} and the connection is closed, without running anything. Tokens are compared in constant time.

solidcraft-cli mcp --connect 127.0.0.1:PORT reads the token file for that port by itself (--token T or SOLIDCRAFT_CONTROL_TOKEN give one explicitly). For a test harness, or a sandboxed package whose data folder the client can’t see, start the app with SOLIDCRAFT_CONTROL_TOKEN set to at least 32 hex characters (for example openssl rand -hex 32) and the app uses that token instead of making one; the file is still written. A one-line client in Python:

token = (Path.home() / ".local/share/solidcraft/control/7878.token").read_text().strip()
sock.sendall((json.dumps({"id": 1, "method": "ui.inspect", "params": {}, "token": token}) + "\n").encode())

Limits

The channel is untrusted input. A request line may be at most 16 MiB; a longer one is answered with {"ok": false, "error": "request too large"} and the connection is closed, as are connections that send eight lines that are not JSON. At most 16 connections are served at once (further ones get {"ok": false, "error": "too many connections"}), at most 64 queued requests run per frame so a flood cannot starve drawing, and a request that the UI thread has not answered within 60 seconds (3600 seconds for engine.batch) is replied to with {"ok": false, "running": true, "error": "timeout: … is still running …"}. The same 16 MiB line limit applies to the MCP server.

A timed-out request has not failed: it is still running in the app, and a change still applies when it finishes (a long fillet, say), so don’t simply send it again. The timeout’s text says what it still does: a request that only reads (ui.inspect, document.inspect, an inspection command) “only reads: nothing changes”; one that only writes a file (file.export, file.save, file.save_as, file.save_mesh, another export given a path, ui.render, or ui.screenshot with a path) “will still write the file when it finishes” and leaves the design as it is; any other request “will still apply when it finishes”. The connection keeps its reply (#1618). Ask for it with control.pending: {"pending": <id>, "method": …, "done": false} while it runs, then {"pending": <id>, "method": …, "done": true, "reply": {…}} (its own reply, once), and {"pending": null} when nothing is outstanding. Until it lands, any other request on that connection is refused at once with {"ok": false, "busy": true, "error": "busy: …"} and not run, so nothing is queued to apply unseen behind it. control.pending belongs to the connection: a new connection has nothing pending. The bridged MCP server does this itself (mcp.md).

control.pending answers only for its own connection. control.running answers for the whole app, the same on every connection, at once (it never waits behind a running request, and a connection may ask it while it is busy): every request the app has been sent and has not answered yet, oldest first, from any connection, including a timed-out one whose connection has since closed:

{"id":1,"method":"control.running","token":"…"}
→ {"id":1,"ok":true,"result":{"running":[
    {"connection":3,"id":17,"method":"engine.execute","command":"file.export","running_s":312.4,"queued":false},
    {"connection":5,"id":2,"method":"engine.batch","steps":12,"running_s":4.1,"queued":true,"self":true}]}}

running_s counts seconds since the request arrived; queued is true while it still waits its turn behind another. command is the command id of engine.execute (a known one only) and steps the length of engine.batch or engine.script; parameters are never shown, so file paths and expressions stay with the connection that sent them. self marks the asking connection’s own request. {"running": []} when the app is idle.

Any request’s params may carry allow_paths: ["/abs/folder", …]: every file that request reads, writes or deletes (command paths such as file.export’s path or doc.recovery_*’s dir, ui.render, ui.screenshot) must then lie inside one of those folders after .. and symlinks are resolved, or the request fails with … outside the folders this agent may use …. The app adds its own recovery folder and, when it lies safely inside the home folder and not in a hidden folder, the open design’s folder (whose hidden files stay out of reach). The bridged MCP server sends its folders this way on every request (mcp.md). Without allow_paths file paths are not limited: a client holding the token can do what the user can.

Engine

Commands never open dialogs when run this way. solidcraft-cli commands prints the same registry.

Following the design

A program that follows the open design (a renderer kept in step, a live link) asks document.revision, which only reads and does not wait behind design changes (a slow command computing, a file loading, the agent cursor acting one out), and exports only when the answer changes (#6646):

{"id":1,"method":"document.revision","token":"…"}
→ {"id":1,"ok":true,"result":{"document_id":"18f3a0c2d4e5b6a7-1","revision":3}}

• document_id names the active design (its tab) while it stays open, through edits, saves and renames. Two open designs have different ids even with the same name, and each design started or opened gets a new one, also one opened or started in the same tab. Ids of one run never match those of another. Treat it as an opaque string.
• revision moves whenever the design changes: an edit, a parameter, undo or redo, a design opened or started, what is hidden or shown (saved with the design), a component moved and not captured yet. It stays the same for reads, a selection, a camera move, a section or an analysis view. Revisions come from one counter for the whole run, so a revision never names two states, and it never goes back: changes undone before the next ask that end where the design was need no new one (its revision still names that design).

Switching tabs changes document_id; back on a tab its revision is the one it had, if nothing changed it meanwhile. Compare both values, and export when either differs from the last answer. The same answer comes from engine.execute document.revision (and so from scripts and MCP execute), which waits its turn behind design changes like any command.

A client need not ask again and again: after control.subscribe on its connection, the app sends it a line whenever the active design changes (#6985):

{"id":1,"method":"control.subscribe","token":"…"}
→ {"id":1,"ok":true,"result":{"document_id":"18f3a0c2d4e5b6a7-1","revision":3}}
{"event":"design.changed","params":{"document_id":"18f3a0c2d4e5b6a7-1","revision":4}}
{"event":"design.changed","params":{"document_id":"18f3a0c2d4e5b6a7-2","revision":5}}

• The reply is what document.revision answers then (and, like it, does not wait behind design changes); no event comes before it. From there on, each design.changed line carries what document.revision would answer, sent when its document_id or revision differs from the last one this connection was told: an edit, undo or redo, a design opened or started, a tab switched.
• Lines are coalesced, not sent per frame: at most about ten a second, and changes made faster (a parameter dragged) are followed by one line with the latest. Once the design stops changing, the last line names it as it is.
• An event has event and params and no id; every reply still has its request’s id. Each event is a whole line of its own, between replies, never inside one. Ignore events you don’t know.
• Only connections that subscribed get events, until they close (or shut their sending side). A second control.subscribe on a subscribed connection is refused with already subscribed; ask document.revision for the design now. A control.subscribe that timed out or failed did not subscribe the connection: send it again.

Slow commands and the window (#1989)

With the preference Preferences > AI > Keep the window responsive while agents run commands on (ui.prefs {"agent_off_thread": true}; off by default), a design change in the desktop app that takes longer than about 150 ms (an engine.execute of a modelling command, an engine.batch of them) computes off the window thread, so the window keeps drawing and answering while it runs:

• The command is evaluated ahead on a copy of the design, which also makes the display meshes of the bodies it ends with. Then it runs for real on the window thread, reusing every feature the evaluation computed (kept for it, whatever the bounded evaluation cache dropped meanwhile), so the window waits only for the bookkeeping. Its reply, undo step, autosave and crash journal are the same as before. With the agent cursor shown, the evaluation runs while the pointer glides to the button, and the pointer waits there until it is done.
• Meanwhile ui.* requests, document.inspect and engine.commands are answered at once (inspection shows the design as it was), also while the agent cursor acts a command out. Later design changes, from any connection, wait their turn and run in the order they arrived.
• A person’s edit made meanwhile goes first. The agent’s command is then computed again for the design as it is and lands after that edit, never in the middle of it. If the design was replaced (another tab made active, a new file opened), the request fails with … the design was replaced … nothing was applied.
• A chip in the view names the command, with Stop. Stop answers {"ok": false, "stopped": true, "error": "stopped: …; nothing was applied"} and the requests waiting behind it go on. The computation finishes unseen in the background.
• file.export and file.save_mesh change nothing in the design. They run on a copy of the design as it was when they were asked for, and nothing waits behind them.
• Batches with timings or profile still run on the window thread, so the times they report measure the real work.

Timeouts and control.pending work as described above. A slow command is still answered when it is done, from a later frame. With the preference off, commands run on the window thread, and the window waits for each one.

Product images use render.preflight/start/status/cancel/export through engine.execute. Keep the returned session-scoped job ID for subsequent calls; status does not block or render. See render jobs for capture, cancellation and export semantics.

While an interactive native file picker is open, ui.inspect reports file_picker_busy: true. Engine commands, ui.file and ui.home requests wait for its answer; window resizing, inspection and screenshots remain available.

Every sketch.* command that changes a sketch adds created: {points, curves, constraints, dimensions} to its result (and wires for 3D curves): the ids of what it added, in creation order, next to whatever else the command returns (curves, sides, corners…). Sketch ids are stable and never reused, even after a delete (l1, l2, then l3 once l2 is gone; only undo rolls the numbering back with the design), so they can go straight into later commands:

{"id":7,"method":"engine.execute","params":{"command":"sketch.line","params":{"points":[[0,0],[40,0]]}}}
→ {"curves":["l1"],"created":{"points":["l1.start","l1.end"],"curves":["l1"],"constraints":["k1"],"dimensions":[]},…}
{"id":8,"method":"engine.execute","params":{"command":"sketch.dimension","params":{"entities":["l1"],"value":50}}}

A bare numeric value given to sketch.dimension (from the control channel, scripts or MCP) is read in the design’s units, exactly as if it were typed into the dimension box: in an inch design "value": 2 makes the line 2 in (50.8 mm) long. Point coordinates stay in millimetres. To pin a unit regardless of the design, pass an expression with one: "value": "50 mm" or "value": "0.5 in". Angles are degrees unless the expression says otherwise.

The viewport also shows an X/Y/Z-aligned dimension chain between the endpoints of the currently shown distance (centre, minimum or maximum), with each world-axis distance labelled separately as an absolute value (including zero). It uses the design’s units and length precision, independently of the view or sketch plane. Preferences → Graphics → Show X/Y/Z distances controls these extra lines and labels (default on, saved between runs). Set ui.prefs {"measure_axis_distances": false} to hide them while keeping the total distance and the dialog’s ΔX/ΔY/ΔZ values. These overlays remain visible until Measure closes. Overlay handles measure:label:x, measure:label:y and measure:label:z identify the extra labels; prefs:measure_axis_distances identifies the checkbox.

UI

ui.workspace {workspace?: "design" | "render"} reads or changes the active workspace. Entering Render requires finishing the current modelling operation; returning restores the Design camera. See the integrated Render workspace.

Continuous camera motion

Continuous camera motion is also available through engine.execute with command view.navigate: pass camera (from ui.inspect) and motion: "pan" | "orbit" | "zoom". Pan and orbit take delta: [dx,dy] in screen points (each within ±10000); pan also requires viewport: [width,height] (each 1..1000000). Orbit accepts a world-space pivot with the viewport size. Zoom takes factor (0.05..20, below 1 zooms in) and an optional world-space anchor. The returned camera is applied immediately by the UI, without animation, document edits, undo steps or a success-log entry per movement.

MCP

solidcraft-cli mcp --connect 127.0.0.1:PORT bridges an MCP client (an AI agent) to this channel; see mcp.md.

Example

{"id":1,"method":"engine.execute","params":{"command":"sketch.create","params":{"plane":"XY"}}}
{"id":2,"method":"engine.execute","params":{"command":"sketch.rectangle.two_point","params":{"p0":[0,0],"p1":[40,30]}}}
{"id":3,"method":"engine.execute","params":{"command":"solid.extrude","params":{"distance":20}}}
{"id":4,"method":"engine.execute","params":{"command":"solid.fillet","params":{"edges":[[0,0,10]],"radius":3}}}
{"id":5,"method":"ui.screenshot","params":{"path":"/tmp/part.png"}}

Preferences → Navigation → View navigator offers Signed axes (the original default) and Cube. This choice is saved independently of the mouse preset. The control channel selects it with ui.prefs {"navigator_style":"axes"} or ui.prefs {"navigator_style":"cube"}. Existing settings without this field keep signed axes. Signed-axis tips choose principal views; clicking an aligned tip again reverses the view.

Hold Shift during an orbit gesture to snap to the nearest standard or diagonal view. This applies to right-drag, the Orbit navigation tool, and dragging either view navigator. Under the default preset, Shift+middle also orbits with snapping; middle alone pans. Cube faces choose principal views, and corners choose isometric views. The middle of each cube edge belongs to its face. Face names follow the up-axis preference; the small X/Y/Z triad shows world axes. Clicking the same face keeps that view. The inward-pointing arrows orbit by 90 degrees; the curved arrows at the upper right roll the view by 90 degrees. The Home button at the upper left returns to isometric and the lower-right circle fits the model.

The cube is subdued while idle. Hovering its area brightens the cube and navigation bar and reveals the surrounding controls; the picked face or corner gets a pale blue fill and blue outline. Moving away restores the subdued state. Navigation-bar controls also brighten when hovered or when a navigation tool is active.

The cube has six face targets and eight corner targets, with no edge targets. Corner picking regions lie on the six flat faces, preserving sharp corners with no permanent subdivision lines. Hovering a corner highlights its parts on the adjacent visible faces together.

The cube widget occupies a compact 112-point square in the viewport corner. A straight-on cube face is approximately 55 points wide; painting and picking scale together. Face labels are stretched vertically. View clicks ease through intermediate orientations when Navigation animated view changes is enabled (the default), at the configured animation speed.

The cube runs view.navigate through the command engine. Programmatic callers pass camera and either direction: [x,y,z] in the camera’s up-axis frame or action (left, right, up, down, clockwise, counterclockwise, home, fit). The result contains camera and fit; UI callers apply the camera with their animation preference, without editing the design.

Shift-orbit snapping includes 45-degree edge views and isometric corner views, with a lightly damped spring transition and a small boundary margin to prevent flicker.

Command search

ui.palette {text?, open?} opens command search under the ribbon search field; open: false closes it. ui.start {command: "ui.palette"}, clicking ribbon:search, and S open the same popup. This is UI routing: engine.execute continues to run commands without opening dialogs. The query is limited to 4096 Unicode characters, with at most 80 visible results.

shortcut:search and palette:search identify the editor; ribbon:search_popup and palette:outer identify the popup. Command rows retain menu:<command id>; design rows use menu:search:design:<index>. Up/Down choose an enabled row, Enter runs it, Tab fills its id or name, and Esc closes. Typing command.id {"parameter": value} validates JSON live and runs through the same engine entry as engine.execute. Shift+Enter runs JSON and keeps the query open. Invalid JSON stays editable and reports the parser’s error. Feature results open their existing edit tools; parameter results open Change Parameters filtered to that name.

Reference tests

Generated by cargo xtask oracle. Each case in tests/oracle/ is a part described by our own recipe.json. SolidCraft replays the recipe through its command engine and compares the result with expected.json: body count, volume and area (relative tolerance 1e-3 unless the case states another), centre of mass and bounding box (within 1e-3 of the part’s size), face count where the geometry fixes it, and, where the case has a reference.stl, the sampled symmetric (Hausdorff) distance between the two surfaces and the principal second moments of both triangulations. Every rebuilt part is also exported as STEP, validated and read back.

Where the expected values come from (the Source column):

• analytic: closed-form geometry worked out by hand (prisms, cylinders, cones, spheres, tori and Pappus’ theorems, fillets on straight edges with a constant radius or one varying along the edge, sheet-metal bends as annular sectors). The scripts in tools/oracle-analytic/ compute them and give the formulas.
• freecad <version>: the same recipe built with FreeCAD’s public Python scripting API by tools/freecad-oracle/, an independent kernel run as an external program. FreeCAD is not a dependency of SolidCraft. Where the two kernels legitimately build a different shape (for example the corner patch where fillets meet), only volume and area are compared, within the tolerance the case states.

No expected value comes from a commercial CAD product.

83 / 83 cases pass; sources: 62 analytic, 21 freecad. 0 known failure(s) tracked in issues; 0 case(s) without expected values yet.