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.