Design properties: project, author and licence in the design, its exports and inspect_design (#1015) (#1189)

A design carries metadata (format 21): project, part number, revision, author, organization, description and license, plus other tools' data under reverse-DNS keys, kept as written. Edited in the Design Properties window (Document Settings), set by document.metadata.set, reported by inspect_design, and written into STEP, IGES and 3MF where the format has a place for them. Translated, with tests.

docs/book/src/guide/files.md

@@ -73,7 +73,7 @@ is available. Missing or incompatible pictures use the usual thumbnail generatio
 The default `cache: false` omits the portable thumbnail too.
 The repository's `docs/design-container.md` describes limits and encoding details.
 
-Current designs use format 20, including thin extrudes, sheet metal perforation fields, associative editable sketch patterns, editable associative offset-distance dimensions, the style of sketch text (bold, italic, alignment, spacing and the curve it follows), face anchors on a piece of a face by its own name, sheet metal rims and bend ends, bend edges for Convert to Sheet Metal, the tear corner relief of sheet metal rules, the names of projected edges, physical materials defined in the design, the font of sketch text, sheet metal corner relief shapes, sketch face anchors on cylinder caps, sketch axis
+Current designs use format 21, including design properties, named render setups, thin extrudes, sheet metal perforation fields, associative editable sketch patterns, editable associative offset-distance dimensions, the style of sketch text (bold, italic, alignment, spacing and the curve it follows), face anchors on a piece of a face by its own name, sheet metal rims and bend ends, bend edges for Convert to Sheet Metal, the tear corner relief of sheet metal rules, the names of projected edges, physical materials defined in the design, the font of sketch text, sheet metal corner relief shapes, sketch face anchors on cylinder caps, sketch axis
 links, persistent
 names from exact face history, exact planar shell-face anchors, persistent analytic offset boundary roles and
 association profile references, durable sketch face anchors, periodic fit splines and versioned
@@ -86,6 +86,61 @@ retain world coordinates. A lost cross-component association refreshed by an old
 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:
+
+| Format | Written |
+|---|---|
+| STEP | `author` and `organization` in `FILE_NAME`, `description` in `FILE_DESCRIPTION` (on one line) |
+| IGES | `author` and `organization` in the global section |
+| 3MF | `project` as `Title`, `author` as `Designer`, `description` as `Description`, `license` as `LicenseTerms` |
+
+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:
+
+```json
+"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.
+
 ## Saving in the web app
 
 In the web app, **Save** and **Save As** keep designs in this browser's private storage;

docs/features.md

@@ -1,6 +1,6 @@
 # Features
 
-SolidCraft's commands by area, generated by `cargo xtask features` from the command registry (`solidcraft-cli commands`). **353 commands.** Planned (registered, not built yet): 6. Every command runs the same way from the toolbar, a script, `solidcraft-cli exec <id> '<json>'`, the control channel and MCP; parameters are in the [command reference](book/src/reference/commands.md) (`cargo xtask book`). Status and plans: [ROADMAP](../ROADMAP.md).
+SolidCraft's commands by area, generated by `cargo xtask features` from the command registry (`solidcraft-cli commands`). **354 commands.** Planned (registered, not built yet): 6. Every command runs the same way from the toolbar, a script, `solidcraft-cli exec <id> '<json>'`, the control channel and MCP; parameters are in the [command reference](book/src/reference/commands.md) (`cargo xtask book`). Status and plans: [ROADMAP](../ROADMAP.md).
 
 ## Sketch (99)
 
@@ -401,11 +401,14 @@ SolidCraft's commands by area, generated by `cargo xtask features` from the comm
 | Delete Crash Reports | `diagnostics.crash_reports.clear` | – |
 | Crash Test | `diagnostics.crash_test` | – |
 
-## `document.*` (2)
+## `document.*` (5)
 
 | Command | Id | Toolbar |
 |---|---|---|
 | Change Design Units | `document.units` | – |
+| Design Properties | `document.metadata` | – |
+| Change Design Properties | `document.metadata.set` | – |
+| Remove Design Property | `document.metadata.remove` | – |
 | Inspect Design | `document.inspect` | – |
 
 ## `engine.*` (1)

docs/mcp.md

@@ -124,7 +124,7 @@ They cover the workflow, the command shapes, how to verify with `measure`, and t
 | `list_commands` | `filter?` | The command catalog: id, label, tab/panel, shortcut, parameter docs, enabled now. `filter` matches id, label, tab and panel. |
 | `execute` | `command`, `params?`, `verbose?` (default true) | Run any command with JSON parameters (`list_commands` shows them). Failures leave the design unchanged. A feature command replies with the feature (`feature`, `name`), every body (`bodies`) and the bodies it created, changed and removed (`created_bodies`, `changed_bodies`, `removed_bodies`). `verbose: false` uses the same compact reply as `batch`. |
 | `batch` | `commands: [{command, params}]`, `rollback?` (default true), `verbose?` (default true) | Run steps in order, stop at the first error and undo the completed steps. The reply names the failing step (`failed.index`, `failed.command`, `failed.error`) and every result before it. `verbose: false` keeps the reply small in large designs: feature steps leave out the full body list (`created_bodies`, `changed_bodies`, `removed_bodies` stay) and sketch steps the ids they repeat outside `created`. Bridged to an app that has `engine.batch`, the whole batch is one control request (one frame of the app). Older apps, and apps showing the agent cursor, get the steps one by one. |
-| `inspect_design` | `measure?` (default true), `sketches?` (default true) | Parameters, timeline (type, suppressed, rolled back, error, warning, timing), bodies (volume, area, centre of mass, bbox, face/edge/vertex counts, visible), sketches (curves, points, constraints, profiles, DOF, solve status, visible), selection, undo depth. Hide helper sketches, bodies or construction planes with `execute` `browser.visibility` (`{items, visible}` or `{folder, visible}`), and joint glyphs with `{joints: [id or name], visible}` or `{folder: "joints", visible}` (a hidden joint still constrains and drives; `joint.list` reports each joint's `visible`). |
+| `inspect_design` | `measure?` (default true), `sketches?` (default true) | Design properties (`metadata`: project, author… and other tools' keys; set them with `execute` `document.metadata.set`), parameters, timeline (type, suppressed, rolled back, error, warning, timing), bodies (volume, area, centre of mass, bbox, face/edge/vertex counts, visible), sketches (curves, points, constraints, profiles, DOF, solve status, visible), selection, undo depth. Hide helper sketches, bodies or construction planes with `execute` `browser.visibility` (`{items, visible}` or `{folder, visible}`), and joint glyphs with `{joints: [id or name], visible}` or `{folder: "joints", visible}` (a hidden joint still constrains and drives; `joint.list` reports each joint's `visible`). |
 | `measure` | `body?` | Volume (mm³), area (mm²), centre of mass, bbox and topology counts per body, with totals. |
 | `body_topology` | `body` | Edges (index, midpoint, length, ends) and faces (index, area, centroid, normal). An edge midpoint is the `[x,y,z]` that picks that edge for fillet and chamfer. |
 | `set_parameter` | `name`, `value` (number or expression), `unit?`, `comment?` | Create or change a user parameter and recompute; reports `recomputed` (features rebuilt), `restored` (features whose earlier result for the same inputs was reused, e.g. a value set back) and features that now fail. |