Files
materialcraft/docs/architecture.md
chasse20 8737d45b64 Use shared Liberation fallback for clean-room SBS assets
Preserve available user fonts and use craft-fonts Liberation Mono only when font data is missing. Keep original identifiers and retain repairable references if the fallback is unavailable.

Attribute the bundled clean-room SBS library, remove the bundled font binary, and share documentation and license staging across Windows MSI and portable packages.
2026-11-13 17:00:24 -05:00

398 lines
31 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Architecture
> **Last reviewed:** 2026-11-05 · **Last updated:** 2026-11-05 · **Change:** evaluator and editor organization · **Target:** the professional node-based material workflow
MaterialCraft is a Cargo workspace of small crates in strict layers (`cargo xtask layers` enforces
them). Everything below the UI is plain Rust with no UI toolkit and builds for
`wasm32-unknown-unknown`.
```text
L0 core document model: Package → Graph → Node / Connection / Frame / Comment / Pin / ExposedParameter;
Value (float, vectors, int, bool, color, enum, text, curve, gradient, function graph)
L0 image Image: grayscale or RGBA f32 planes behind an Arc (copy-on-write, free to share);
wrap/clamp sampling, bilinear, box/bilinear resampling, sRGB, 8-bit display
L0 geom meshes, primitives (rounded cube, sphere, cylinder, plane, torus, material ball), BVH, camera
L1 nodes 30 main-graph entries (NodeDefinition), 85 function operations, four pattern node kinds;
shared image operations and iterative function/pattern execution
L2 eval cooking: topological order, output sizes (relative to input / parent, absolute, preview
cap), parameter resolution (defaults, overrides, bindings to exposed inputs), the
content-addressed LRU cache, graph instances (sub-graphs, recursion-guarded)
L2 formats native .sbs packages, .mcraft ZIP packages, .mcmat portable materials, bitmap/SVG decode,
texture encode (PNG/JPEG/TGA/BMP/WEBP/EXR/HDR), atomic writes
L3 engine Session (open packages, active graph, selection, 2D/3D view state, snapshot undo, cache),
the command registry, inspect, sample materials and graph templates
L3 render the 3D view: BVH ray casts, the height output displacing a subdivided mesh, GGX PBR with
prefiltered IBL + SH diffuse, alpha transparency (layered ray compositing) and an
alpha channel view, ACES tone mapping; procedural environments
L4 automation MCP server (rmcp), JSON-lines RPC (stdio/TCP with token), bridge client, workspace sandbox
L5 ui-egui the egui shell: docking (craft-ui), graph editor, library, properties, 2D/3D views,
dialogs, menus, control channel with synthetic input
apps materialcraft (desktop), materialcraft-cli, materialcraft-web
```
## Cooking
A node's cook is a pure function `fn(&CookContext) -> Result<Vec<Image>, String>`: `CookContext` carries the output
size, the seed, tiling, the inputs (by port order, `None` when unconnected), the resolved parameters,
a resource decoder and the graph's exposed values. `eval::cook` walks the graph in dependency order.
For each node it hashes the definition id, resolved parameters, size, seed, tiling, the keys of its
input images, resource bytes and (for instances) the sub-graph: equal keys hit the cache, so an edit
re-cooks only the nodes downstream of it, and undo finds earlier results again. A failing node shows
a magenta image and its error; nodes after it still cook.
The editor's output cache retains at most 256 MiB and 8192 entries; decoded resource images
retain at most 128 MiB and 128 entries. Both evict least-recently-used data. An image larger than
its cache budget serves the current cook without being retained in that cache. These are cache
limits, not a limit on total process memory: open documents, undo, loaded library graphs, active
cook results and GPU textures have their own lifetimes.
Each cook builds a borrowed `core::GraphIndex` for node and connection lookups. `PreparedGraph`
resolves the needed nodes' ports once; `graph_execution` schedules them and `node_execution` handles
a single node. Parameter resolution, graph instances, value execution, output collection and cache
keys have separate modules. The index lives only for the cook, so it needs no invalidation protocol.
Function execution shares one interpreter. Pixel Processor borrows the caller's variables and keeps
only assignments in its per-pixel state; ordinary function evaluation retains the full environment
for callers such as FX-Map that read the resulting variables.
Sizes: generators take the graph ("parent") size; filters take their main input's size; both can be
offset by powers of two or set absolutely. While editing, outputs are capped at the preview size
(512 px by default), with pixel-based parameters scaled by `w / 256` so previews and full-size
exports look the same. Exports cook at full size through the same cache.
The 2D toolbar and the 3D view's Display menu expose the shared preview limit (256, 512, 1024,
2048 or 4096 px, or Full size). This is a cap, so a 4K preview requires a graph/node configured
for 4096 px or larger. Both controls run `view.previewSize` and persist the choice in preferences;
control-channel calls to the same command also retain their size across UI frames. The 3D view
uses those cooked maps, while its rendered frame follows the panel's physical pixel dimensions.
If the device supports smaller textures than the cooked image, the 2D view reduces only the
uploaded texture to that limit; source pixels, readout and screenshots retain the cooked size.
The desktop UI cooks on a worker thread (`ui-egui/src/cook.rs`) from a snapshot of the package and
keeps drawing the last results; the browser cooks on the UI thread.
## Commands and automation
`Session` exposes the active package and keeps inactive editing state in `OpenDocument`. Switching
packages retains their undo histories, selections and previews and invalidates pending cook results.
Linked main and Function graph instances store a source path, graph name and cached connector interface.
`linked_packages` publishes source snapshots and refreshes dependent packages; `linked_files`
resolves saved references on native open. Source snapshots share a flat registry of `Arc<Package>`
values whose own registries are empty, so cross-file references cannot create ownership cycles.
The registry is runtime state; SBS serializes the file references and connectors instead.
Function instances resolve to bounded runtime call bodies before cooking. Each compiled call owns
its program and reuses separate evaluation storage, so source lookup and compilation never happen
per pixel. Calls share the execution-step budget and are capped at eight levels, 4096 nodes per
graph and 8192 nodes across expanded calls.
SBS Function nodes store the source URI in their instance data; a `materialcraftInterface` cache
preserves unconnected input pins when a source file is unavailable.
Package folders are part of each graph's SBS identity. Exact paths take priority over leaf names;
a leaf name is accepted only when it is unambiguous. Unconnected function-instance inputs use
the source's declared defaults. Unknown function operations retain their connector names, data
and output designation so an unavailable implementation does not erase the containing graph.
Missing external resources retain their paths for repair on a later load.
Empty folders also persist as native SBS groups. Explorer renders these groups as a collapsible
tree, including resources in their original folders. Folder creation, rename, removal, copying
and moving use engine commands with snapshot undo. Renames and moves update local instance paths;
copies retarget references between copied graphs. The Explorer clipboard survives document changes.
Single clicks select Explorer rows; double clicks open their graph or input/output preview.
The Explorer New submenu creates items immediately with numbered default names, advancing past
name conflicts in the destination folder. Rename remains an explicit context-menu action.
`sbs://` resolves beneath `assets/sbs/`. Native installations can place that directory beside the
executable or set `MATERIALCRAFT_SBS_DIR`; packaged and browser builds also embed the standard
library. Alias paths cannot escape that root; saves outside the library retain the alias. The Function
Library lists these source graphs and inserts references into Function and processor canvases.
Library aliases are read-only save destinations; an edited library can be saved to a local path.
Resource paths resolve beside their owning package: `resources/tile.png` in
`sbs://functions.sbs` reads `assets/sbs/resources/tile.png`, also addressable as
`sbs://resources/tile.png`. Nested library packages can use `../resources/` paths within
the library root. Filesystem resolution checks the canonical target to prevent escaping that root.
Native saves inside the library retain loaded resource links and write ordinary relative paths;
ordinary project saves copy resource bytes alongside the package, and byte-only saves embed them.
Unavailable resources retain their reference and missing state. Font resources first load their
embedded data or their file relative to the SBS package, including user-supplied `cour.ttf`.
Only a missing font uses `sbs://resources/LiberationMono-Regular.ttf`. The same precedence applies
to direct Text font references and unresolved package font references; a blank reference keeps the
built-in stroke font. Empty embedded data and empty files do not hide later font sources. If the
fallback is also unavailable, the original SBS font name and reference remain available for repair.
Resource loading and round trips preserve these fonts; the Text cook does not yet rasterize external fonts.
The formats build reads Liberation Mono Regular and its OFL notice from the optional
`CRAFT_FONTS_DIR/fonts/latin-manifest.txt` catalog, verifies its checksum, and embeds only that
face for native and web builds. Font binaries stay in craft-fonts. Set `CRAFT_FONTS_REQUIRED=1`
for releases to fail on an unavailable fallback. Without the optional input, builds still work;
a missing font produces a repairable resource and a load warning. A checkout with the Latin
catalog is required (for example craft-fonts revision `c1db6d1a8ed772191241c3d185e2104be84d8691`).
All bundled `.sbs` packages, including nested materials, are original clean-room recreations
covered together in [ATTRIBUTION.md](../ATTRIBUTION.md); their other resources retain separate credits.
Bitmap/SVG references into another package import only the requested resource declarations,
resolving asset paths beside that owner. These become local resource snapshots with distinct
names on collisions; saving retains shared asset links inside the library or carries their bytes
in portable saves. The owning package's graphs are not recursively imported for resource lookup.
Every session loads the whole library folder once per process (`engine::node_library`, cached
until `library.reload`). Each package joins every session's dependencies, so its graphs can be
instanced, and the Library lists them: function graphs under Functions, sorted into its
sub-categories by their folder (`Functions/Math/Pi` → Constant), other graphs under the category
their attributes name: the category picks the top level (`Generator` → Texture generators, `Filter`
→ Filters, `Mesh Adaptive` → Mesh-based generators…) and the first matching tag the sub-category
(`Noise` → Noises, `Blur` → Blurs). Graphs marked `hideInLibrary`, and uncategorized functions
beside material graphs, are helpers and stay out of the Library. A package whose titled frames name Library categories ("Filters - Blurs") can also lay
the tree out (`formats::sbs::read_layout`): each node inside a frame becomes an entry there, listed
as missing until a package in the folder provides it. Installed and browser builds embed all SBS
packages and shared resources, compressed at build time. Library packages share a flat dependency
registry; only sources reachable from open packages refresh their instance interfaces on edits.
Library thumbnails cook one visible native node or graph at a time, with 32 MiB of output caching and 16 MiB
of decoded-image caching. Only output dependencies are evaluated. Editing takes priority, and
leaving a tile or reloading the library cancels its cook between nodes. The next job waits for
that worker to finish; hidden tiles cannot accumulate queued work or workers. At most 256
finished previews retain GPU textures (about 5 MiB of pixels).
Native Library previews also persist as PNGs in the platform cache folder selected by
the existing `craft_update::Paths::per_user("materialcraft").cache`, under `previews/`: `%LOCALAPPDATA%` on
Windows, `$XDG_CACHE_HOME` or `~/.cache` on Linux/BSD, and `~/Library/Caches` on macOS.
This follows the [Craft storage policy](https://github.com/storytold/craft-libs/blob/main/docs/settings-storage.md).
The cache covers native nodes and SBS graphs. Edit → Preferences → Library preview cache stores
the disk limit (default 64 MiB, 0 disables persistence) and maximum stored previews (default 4096).
The supported ranges are 0–65536 MiB and 1–65536 previews. Settings apply immediately to running
workers, with background eviction when lowering either limit, including when all previews are warm.
Older files are evicted first (access times refresh at most hourly). These disposable thumbnails are
independent of projects, autosaves and temporary render storage.
**Clear cache** removes stored previews and loaded library textures, cancels the active preview,
and discards its result. Previews rebuild passively, one visible tile at a time; hidden native
nodes and graphs do not cook. A job from before Clear cannot write its old result back. One
maintenance worker handles trimming and clearing without blocking the UI. Cleanup failures
report an error and bypass disk persistence for the session so stale previews cannot reappear.
The same actions are available through `library.cache.configure` and `library.cache.clear`;
`session.inspect` exposes `libraryCachePreferences`. These commands never edit package contents.
Background workers do all reads, encoding, atomic writes (`craft-atomic`) and eviction; none run
on the UI thread. Keys include the preview size, an executable content digest (including local
rebuilds with an unchanged release version), and, for SBS graphs, the source packages and all
resource bytes in their dependency closure. Changes become visible after `library.reload` or
the next launch, just like the in-memory library. Corrupt, oversized or unavailable cache files
are misses; failed or cancelled renders are never persisted. Concurrent writers use a
nonblocking file lock to share the disk budget. The browser keeps previews in memory only.
`MATERIALCRAFT_CACHE_DIR` overrides the app cache folder (`previews/` is appended); an empty
value disables persistence. Scripted `MATERIALCRAFT_NO_PREFS` runs leave the user's cache
untouched unless that explicit override is provided. Headless UI harnesses keep persistence off.
The local `sbs_library_build` example converts native XML without a model round trip, checking that
computational fields survive presentation edits and reference rewriting. It generates independent
resource substitutes without reading source resource files. It retains supplied graph implementations;
these edits do not establish redistribution rights. Native dependency closure and XML preservation do
not establish runtime compatibility. The `sbs_library_audit` engine example separately reports import
warnings and standalone function compilation failures; it does not validate every graph's output.
Importing a user-supplied function package preserves its graph bodies, connections and positions;
it does not replace them with the bundled library. Redundant legacy instance connectors are retained
on save and evaluated only through the declared inputs. Conflicting obsolete connections remain
visible errors. A shared typed system-variable catalog drives Get-node suggestions and execution.
Ordinary functions expose size, log2 size, pixel ratio, tiling, physical size, UV tile, time and
normal-format variables. Pixel Processor adds `$pos`; FX-Map adds `$pos`, `$depth`, `$depthpow2`
and `$number`. Reusable function instances inherit their caller's scope. Out-of-scope variables
remain undefined even if a user input has the same name, and Set cannot overwrite system variables.
Get properties offer a type-filtered dropdown and accept typed custom names.
Node tiling and pixel ratio resolve from absolute values, the first connected image input or the
parent graph. SBS preserves these inheritance modes and the graph's `physicalSize` attribute.
The host supplies time, UV tile and a raw normal-format integer through `EvaluationEnvironment`;
the static authoring defaults are zero. These values propagate through nested graph instances
without becoming constants in saved functions. Relevant variable changes invalidate cached cooks.
The normal-format integer is passed through without assigning a convention label to an unverified code.
Numeric, Boolean, color, enum and text value parameters can own a Function graph, including
inputs on material graph instances. The six base parameters store their functions separately from
node-specific parameters so native identifiers cannot collide. Size and seed functions establish
the evaluation context before other parameters run; downstream nodes inherit evaluated nominal
sizes rather than capped previews. SBS writes these functions as native dynamic values, including
incomplete graphs. Exposing a parameter creates a typed Get-node function. Properties offers the
same function creation, editing and reset actions for base parameters and instance inputs.
Only Specific Parameters offer exposure: a modal drafts the identifier, label, group, description,
editor, default, limits, clamp and step before one undoable command creates the input and function.
Inheritance buttons show distinct icons for input, parent and absolute modes.
The local `assets/sbs/functions.sbs` is converted from a user-supplied package with
`cargo run -p materialcraft-formats --release --example standard_function_library -- <source.sbs> assets/sbs/functions.sbs`.
The converter preserves all 171 function bodies (2,334 nodes), folder paths, identifiers, inputs,
defaults and internal references. It writes new interface-based descriptions, generates node
positions and omits source parameter descriptions, annotations and icons. It rejects import warnings and functions that
cannot compile instead of substituting empty graphs. The source graph bodies are retained;
rewritten metadata does not establish redistribution rights.
Local tests compare every converted body and evaluate all 171 functions against the supplied
package with valid inputs and caller context. External runtime import and numerical compatibility
still require validation. The first SBS save writes the workspace's Cargo version to both
`formatVersion` and `updaterVersion`. The package model retains the baseline `formatVersion`
when reopening a document; later saves refresh only `updaterVersion`.
Every user-visible action is a `CommandSpec` (`engine/src/*_cmds.rs`): id, label, menu, shortcut,
params doc, `enabled`, `run`. The UI calls them through `MaterialCraftApp::run`; the CLI, the JSON
control channel and MCP dispatch the same ids. `Session::edit` snapshots the package before running
an edit and restores it on error; `edit_merged` folds repeated edits with the same key (a slider
drag) into one undo step. See [control-protocol.md](control-protocol.md).
## The UI
`MaterialCraftApp` owns the session and `UiState` (serde, persisted by eframe, readable and writable
through `ui.inspect` / `ui.set`). The dock (craft-ui) hosts eight panels around the protected graph
panel. The graph editor lays nodes out in graph space, draws cards with thumbnails from the cook
results (uploaded once per cache key), wires as cubic beziers between typed ports (hit-tested
against the curve, so wires can be selected, deleted, swapped or split with a reroute dot), and turns
gestures into commands only when they complete. See [wires-and-alpha.md](wires-and-alpha.md). The 3D view renders with `materialcraft-render`
on the CPU: half resolution while the camera moves, 2×2 supersampled when it rests.
The 3D material has its own `MaterialPreview` assignment state. Automatic graph output usages and
explicit `MaterialSource` overrides resolve to channels from `core::MaterialChannel`, shared with the
renderer and menus. A source records its graph, node and named port; selection and 2D preview do not
change it. `PreviewCook` publishes the editor cook and any other assigned graphs together through
the existing worker/cache, so opening a Function Graph preserves the material. Render invalidation
includes both source assignments and cooked content. Snapshot undo and graph deletion retain or
adjust source ownership; package replacement clears old assignments.
`core::ComponentUsage` defines output metadata once for node properties, SBS and exports. Its
indices stay stable as choices are added; renderable channels remain a separate capability.
Explorer and canvas node labels share display formatting without rewriting identifiers. Explorer
lists every graph input/output, and graph drops dispatch the existing material assignment command.
`crates/ui-egui/tests/snapshot.rs` renders the real UI offscreen with egui_kittest + wgpu for visual
checks and README screenshots.
The regular and function canvases separate drawing, geometry, navigation and input handling.
Shared modules own node cards, selection and annotation gestures. The regular canvas borrows the
document while drawing, then dispatches edits. Graph Properties follows the same pattern; its
`property/` modules separate panel routing, node and graph settings, parameter controls, curves
and gradients. Function and pattern Properties dispatch value edits without cloning graphs in the UI.
Explorer inspection uses a document-and-graph target independent of the canvas. Shared graph
attribute controls retain text drafts until focus changes, then dispatch targeted engine commands.
Inactive packages record those edits in their own snapshot history. Both graph kinds share the SBS
attribute codec; display labels are resolved separately from reference identifiers.
The properties panel builds every parameter editor from the node catalog; the Levels node adds a
histogram editor with range handles on top of its sliders ([levels-editor.md](levels-editor.md)).
### Shared graph editing
The graph panel renders one toolbar before dispatching to the material, Function Graph or FX-Map
canvas. Framing, alignment, distribution and snapping occupy the same positions. Image inserts,
parent texture size, annotations and parent-graph navigation appear only where the graph supports
them. Alignment uses the same engine command for all three models, with explicit embedded node IDs
and an explicit Function target or FX-Map owner ID, so overlapping IDs cannot move the parent material nodes.
Pixel Processor, Value Processor and parameter functions use that same main panel and function node
catalog, with one target-aware availability rule shared by node creation, Library and Add node.
Both processor types accept Sample gray and Sample color to read their image inputs.
A breadcrumb and parent action return from nested functions, FX-Maps and local graph instances
while retaining the parent view and material preview.
`ui-egui/graph/graph_camera.rs` owns framing, pointer-centered scroll/pinch zoom and navigation
shortcuts. `node_selection.rs` owns click and box selection; `port_hit.rs` owns nearest-port picking;
`wire_geometry.rs` owns curve construction. Node movement uses the engine's `graph_grid::translate`
for both previews and commits.
`engine/graph_edit/` owns Function/FX-Map selection commands, clipboard remapping, deletion and
connected-node traversal. Its small model adapters supply node fields, link direction, ID allocation
and result/root handling. Material clipboard commands retain their named-port connections and
cross-graph clipboard rules. Rendering and connection validation remain specific to each model;
all document changes still pass through engine commands and snapshot undo. `selection_commands.rs`
routes the existing selection and clipboard command IDs to these adapters, including headless calls.
Read-only selection actions borrow the graph. Document, selection and clipboard updates are published
only after validation succeeds; clipboard provenance prevents external links crossing graph targets.
`graph_validation.rs` supplies the same checks to creation, legacy setters and targeted edits.
`graph/editor_target.rs` resolves command ownership for the material canvas, standalone Function
Graphs, FX-Map canvases and embedded Function Graphs. Menus, keyboard shortcuts and
`ui.menu.invoke`, Library and Properties use that resolver; `ui.inspect` reports the same editor and
its canvas coordinates. Embedded editors record their owning graph and close when undo or another
command makes that owner unavailable.
Common context-menu entries live in `graph/edit_menu.rs`. Pointer gestures finish only when their
initiating button is released; Escape or focus loss cancels pending canvas movement.
Function and FX-Map rendering borrow the document, prepare screen geometry, and dispatch edits
after painting. Function wires reuse one node-layout index instead of scanning the graph for each
endpoint. The engine's `graph.function.edit` and `graph.pattern.edit` commands own creation,
movement, connections, values and result/root changes. Function targets identify standalone,
parameter, dynamic-parameter or nested FX-Map functions explicitly. Value updates may request
`merge: true`; `edit.finish` closes that undo group. The UI closes groups at gesture boundaries,
while discrete edits always receive their own undo entry.
## Files
SBS XML is the document representation. A native `.sbs` saves assets in an adjacent `resources/`
directory and references them with relative paths. A `.mcraft` is a ZIP containing the fixed root
entry `package.sbs` and `resources/`, with no manifest or private graph payload. Both formats open,
save, reload and save copies independently. The same clean-room SBS codec writes native filters,
ports, parameters, function graphs, pattern graphs and resources. Unsupported imports produce
warnings; unknown nodes remain placeholders.
Dynamic Gradient maps native `coordinate` and `uvselector` fields to position and orientation,
including parameter functions. Earlier `position`/`orientation` spellings remain readable.
FX-Map maps the native `hurst` parameter to Roughness, including parameter functions and SBS
round trips. Rendering uses Hurst octave attenuation `2^(-roughness * quadrant_depth)` on each
pattern's opacity, including alpha blending, while retaining the background. Switch, Iterate and
Dot nodes do not increase that depth. Omitted roughness stays neutral for existing documents.
This is an independent depth-weighting model; exact external-runtime pixel parity is unverified.
The traversal budget permits full 512-by-512 quadtrees while retaining a 1,048,576-visit ceiling
and the separate raster sample budget. Levels channel controls and FX-Map background functions
can return either a scalar or Float4; scalar backgrounds keep opaque alpha. Other vector
parameters retain exact output-type checks. Library conversion qualifies known bare standard
function calls through an existing declared dependency, preserving local definitions and explicit
references. It never chooses an unknown function target.
`formats::project::ProjectFiles` builds either representation without changing the live package.
Imports retain original bytes in snapshot history, including before the first save. Content-based
asset filenames avoid overwriting resources shared by another SBS and allow the XML to be replaced
last. Missing assets cause saving to fail. Existing unreferenced files are left in place. Archives
are read in memory and validate paths, duplicate entries, symlinks and malformed data. Project I/O
and resource imports impose no fixed file-size, resource-count or linked-package-count ceilings.
Referenced packages are included under `resources/packages/`;
unresolved installed-library aliases retain their `sbs://` references. Autosaves use `.mcraft`.
Explorer shows its reserved Resources folder once it contains assets or subfolders. Its Import
submenu accepts bitmaps or SVG vector graphics into the selected asset folder. Subfolders can be
created, renamed and removed; graph creation and graph-folder moves into this tree are rejected.
The root Resources name is reserved regardless of capitalization and cannot be renamed, copied, moved or
removed. Import creates an asset; dragging it onto the canvas or choosing Add to graph creates the
appropriate bitmap or SVG node. Drops from another open package copy the asset into the destination
in one undo step. Imported native SBS groups retain their original resource placement for round-trip
fidelity. Folder Properties exposes Identifier and Description; descriptions persist in native SBS
group `desc` elements, including inside MCRAFT. The reserved root identifier is read-only.
Bitmap imports support DDS, WebP, GIF, HDR, EXR, JPEG, PGM, PNG, TIFF, Targa and BMP. DDS uses the
MIT OR Apache-2.0 `dds` decoder; GIF and ASCII/binary PGM use `image`. GIF loads its first frame;
DDS loads its first surface at the largest mip level. Each bitmap format has its own picker filter,
and vector import offers SVG only. Both pickers include All formats, restricted to their supported
extensions, and descriptive names with extension patterns. Open offers SBS XML Package and
MaterialCraft Project plus All formats; Save As offers those two formats separately.
The browser downloads `.mcraft` directly. SBS downloads use a transport ZIP containing the named
SBS and its adjacent resources; extract it to work with the native files. Both forms can be opened
in the browser. A bare SBS can load embedded assets, but browser file pickers cannot automatically
read adjacent files; use the SBS transport ZIP to include those assets.
The SBS `read` and `write` modules expose codec entry points. `SbsReader` and `SbsWriter` own
serialization state; focused helpers handle values, functions, patterns and canvas annotations.
Native value type codes come from `core::ValueType` rather than a second scalar type table.
See [atomic-workflow.md](atomic-workflow.md) for the tested scope and remaining limitations.
## Other apps
A `.mcmat` portable material (`formats/src/material/`, `engine/src/material_cmds.rs`) holds a
graph's cooked maps, its portable exposed inputs, presets and input nodes, and the source package.
TextureCraft paints with it and re-cooks it by running `materialcraft-cli run <package>
file.exportMaterial {path, size, values, inputs}`: the apps share the file format and the command
line, never code. Graphs keep preview images for their input nodes (`Graph::input_images`, mesh
maps from TextureCraft); `eval::cook` feeds them to the top-level graph, and a caller's images win.
Preview cooks publish the editor graph and assigned material graphs together. A synchronous cook
invalidates older worker results. Displacement uses the assigned Height source even while another
graph or an embedded function is open. Native image loading checks dimensions before decoding;
bitmap resources and graph input previews can request linear data-map reads.