forma-dsl-mcp 0.1.4

package/src/reference/reference/refinement.md

@@ -0,0 +1,284 @@
+# Refinement
+
+Six operations that change how geometry is built rather than where it is. Most are about
+mesh quality or a single cheap cut.
+
+| Block | Takes | Description |
+| --- | --- | --- |
+| [`offset`](#offset) | 2D | Grows or shrinks an outline |
+| [`hull`](#hull) | 2D or 3D | The convex hull of everything inside |
+| [`refine`](#refine) | 3D | Subdivides edges longer than a limit |
+| [`simplify`](#simplify) | 2D or 3D | Removes vertices within a tolerance |
+| [`smooth`](#smooth) | 3D | Rounds edges below a sharpness threshold |
+| [`trim`](#trim) | 3D | Cuts a solid with a half-space |
+
+---
+
+## `offset`
+
+Grows or shrinks a 2D outline, keeping true arcs at convex corners.
+
+```hcl
+offset { amount = 2  project { bracket { } } }
+offset { amount = -1.5  join = "Miter"  rect { size = [40, 20] } }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `amount` | number | **required** | Positive grows, negative shrinks |
+| `join` | `"Square"` `"Round"` `"Miter"` | `"Round"` | How convex corners are treated |
+| `miter_limit` | number | `2` | How far a mitred corner may extend before it is squared off |
+| `segments` | integer | `0` | Segments per rounded corner |
+
+#### Caveats
+
+- **2D only.** `"offset" takes 2D geometry, got 3D`. There is no 3D shell operation; build
+  one as a `difference` of two profiles, or offset the profile before extruding.
+- A negative amount larger than the shape's half-width erases it, leaving empty geometry.
+- This is the operation [`rounded_rect`](shapes-2d.md#rounded_rect) is built from — a
+  shrunken rectangle offset back out is what makes its corners true arcs.
+
+---
+
+## `hull`
+
+The convex hull of everything inside — the shape a rubber sheet would take around it.
+
+```hcl
+hull {
+  translate { offset = [0, 0, 0]   sphere { radius = 4 } }
+  translate { offset = [40, 0, 0]  sphere { radius = 4 } }
+  translate { offset = [20, 30, 0] sphere { radius = 8 } }
+}
+```
+
+#### Attributes
+
+None.
+
+#### Caveats
+
+- Works in 2D and 3D, passing the dimensionality through.
+- Children are unioned first, so the hull is of everything together — which is the point.
+- Any concavity is filled in. A hull of a C-shape is a solid blob.
+
+---
+
+## `refine`
+
+Subdivides every edge longer than a limit, producing more, smaller triangles.
+
+```hcl
+refine { edge_length = 1  sphere { radius = 20 } }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `edge_length` | number | **required** | No edge longer than this survives |
+
+#### Caveats
+
+- 3D only.
+- Triangle count grows quadratically as the limit falls. `edge_length = 0.1` on anything
+  large will cost seconds and hundreds of megabytes.
+- Refining does not change the shape — it only adds vertices, usually so that
+  [`smooth`](#smooth) or a downstream deformation has something to work with.
+
+---
+
+## `simplify`
+
+Removes vertices that lie within a tolerance of the surface they are on.
+
+```hcl
+simplify { tolerance = 0.01  imported_thing { } }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tolerance` | number | `1e-6` | How far a vertex may move |
+
+#### Caveats
+
+- Works in 2D and 3D.
+- The default is small enough to be a no-op on most geometry; it is there so the block can be
+  written without arguments while a value is chosen.
+- A tolerance near the size of a feature will delete that feature.
+
+---
+
+## `smooth`
+
+Rounds edges whose dihedral angle is below a threshold.
+
+```hcl
+smooth { min_sharp_angle = 40  refine { edge_length = 1  blocky_thing { } } }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `min_sharp_angle` | number | `60` | Degrees. Edges sharper than this stay sharp |
+| `min_smoothness` | number | `0` | How strongly to smooth, from `0` to `1` |
+
+#### Caveats
+
+- 3D only.
+- **Smoothing needs vertices to work with.** On a cube there is nothing between the corners
+  to move, so the result is barely different. Pair it with [`refine`](#refine).
+- This is a mesh operation, not a fillet. For a controlled radius, model the fillet — round
+  the profile, or union in a [`torus`](shapes-3d.md#torus).
+
+---
+
+## `trim`
+
+Cuts a solid with a half-space, keeping what is behind the plane.
+
+```hcl
+trim { normal = [0, 0, 1]  offset = 20  tall_thing { } }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `normal` | 3-vector | **required** | The plane's normal. Everything on the normal's side is removed |
+| `offset` | number | `0` | How far the plane sits along the normal from the origin |
+
+#### Caveats
+
+- 3D only.
+- Much cheaper than an `intersection` with a big box, because it is a plane clip rather than
+  a boolean between two solids. Use it for flat cuts.
+- The cut face is capped, so the result stays a closed solid.
+
+---
+
+## Usage
+
+### Growing a footprint
+
+`offset` after `project` is the standard way to derive a base, a gasket or a clearance
+outline from a finished part:
+
+```hcl
+extrude {
+  height = 3
+  offset { amount = 2  project { bracket { } } }
+}
+```
+
+### Shelling a profile
+
+There is no 3D shell, but offsetting the profile inwards gives the same result for anything
+prismatic:
+
+```hcl
+difference {
+  extrude { height = 20  rounded_rect { size = [40, 30]  radius = 4  center = true } }
+  translate {
+    offset = [0, 0, 2]
+    extrude {
+      height = 20
+      offset { amount = -2  rounded_rect { size = [40, 30]  radius = 4  center = true } }
+    }
+  }
+}
+```
+
+### Organic shapes from a hull
+
+A hull of a few spheres is the quickest route to a smooth, blobby form — a handle, a fillet
+between two bosses, a rounded enclosure:
+
+```hcl
+component "rounded_enclosure" {
+  param size   = [60, 40, 20]
+  param radius = 6
+
+  hull {
+    for x in [radius, size.x - radius] {
+      for y in [radius, size.y - radius] {
+        for z in [radius, size.z - radius] {
+          translate { offset = [x, y, z]  sphere { radius = radius  segments = 32 } }
+        }
+      }
+    }
+  }
+}
+```
+
+Eight spheres, but one sphere node — content identity means the kernel builds the sphere
+once and the hull sees eight transforms of it.
+
+### Flat cuts
+
+`trim` is the cheap way to lop something off:
+
+```hcl
+trim { normal = [0, 0, 1]  offset = 15  bottle { } }    // keep everything below z = 15
+trim { normal = [-1, 0, 0]  bracket { } }               // keep everything with x ≥ 0
+```
+
+For a half-model view, that is one operation instead of an intersection with a box.
+
+### Refine, then smooth
+
+The two go together — smoothing has nothing to move until the mesh is dense enough:
+
+```hcl
+smooth {
+  min_sharp_angle = 35
+  refine { edge_length = 0.8  blocky_thing { } }
+}
+```
+
+Watch the triangle count; this is the most expensive pair of operations in the language.
+
+---
+
+## Troubleshooting
+
+### `"offset" takes 2D geometry, got 3D`
+
+`offset` works on outlines. To grow a solid, project it, offset the outline and re-extrude —
+or offset the profile before it was extruded in the first place.
+
+### `offset: "amount" must be a finite number`
+
+`amount` is required and has no default. A shrink is a negative number, not a missing one.
+
+### My `smooth` did nothing
+
+The mesh has no vertices to move. Refine first, and check that `min_sharp_angle` is above the
+angle of the edges you want rounded — the default of `60` leaves every edge on a cube alone.
+
+### `refine` hung the browser
+
+`edge_length` is an absolute length, and triangle count grows quadratically as it falls.
+Start an order of magnitude coarser than you think you need.
+
+### My negative offset erased the shape
+
+A negative `amount` larger than half the narrowest part of the outline consumes it entirely.
+The result is empty geometry, not an error.
+
+### `hull` swallowed the hole in my part
+
+Hulls are convex; every concavity and every hole is filled. Hull the pieces that need it, and
+subtract the holes afterwards:
+
+```hcl
+difference {
+  hull { ... }
+  the_holes { }
+}
+```

package/src/reference/reference/shapes-2d.md

@@ -0,0 +1,309 @@
+# 2D shapes
+
+Seven leaf blocks producing cross-sections. They take attributes and never contain other
+blocks.
+
+**2D shapes cannot be rendered on their own.** Give them thickness with
+[`extrude`](conversions.md#extrude) or [`revolve`](conversions.md#revolve) first, or a part
+holding one fails with `part "body" is 2D — extrude or revolve it before rendering`.
+
+| Block | Sized by | Centred by default |
+| --- | --- | --- |
+| [`rect`](#rect) | `size` | no |
+| [`rounded_rect`](#rounded_rect) | `size`, `radius` | no |
+| [`circle`](#circle) | `radius` or `diameter` | always |
+| [`ellipse`](#ellipse) | `radii` | always |
+| [`regular_polygon`](#regular_polygon) | across flats, across corners, or radius | always |
+| [`stadium`](#stadium) | `size` | no |
+| [`polygon`](#polygon) | `points` | as drawn |
+
+### A note on `segments`
+
+Several shapes take `segments`, the number of straight edges used to approximate a curve.
+`0` — the default — means *let the kernel decide* from its global quality settings, which
+[`setQuality`](../api/kernel.md#setquality) controls. Set it explicitly when a specific facet
+count matters: a hole that must clear a printed bolt, or a preview that must stay cheap.
+
+---
+
+## `rect`
+
+An axis-aligned rectangle.
+
+```hcl
+rect { size = [40, 20] }
+rect { size = [40, 20]  center = true }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | 2-vector | **required** | Width and height |
+| `center` | bool | `false` | `true` centres it on the origin; otherwise its lower-left corner sits there |
+
+---
+
+## `rounded_rect`
+
+A rectangle with true arcs at the corners.
+
+```hcl
+rounded_rect { size = [62, 13]  radius = 6.5  center = true }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | 2-vector | **required** | Width and height, over the rounded corners |
+| `radius` | number | `1` | Corner radius. Clamped to half the shorter side, so it cannot invert the shape |
+| `segments` | integer | `0` | Segments per corner arc; `0` lets the kernel choose |
+| `center` | bool | `false` | As for [`rect`](#rect) |
+
+#### Caveats
+
+- Built by shrinking the rectangle and offsetting it back out, which is what makes each
+  corner a true arc rather than a chamfer. A `radius` of `0` or less degenerates to a plain
+  `rect`.
+- `size` is the outer size. `rounded_rect { size = [10, 10] radius = 5 }` is a circle of
+  diameter 10.
+
+---
+
+## `circle`
+
+```hcl
+circle { radius = 12 }
+circle { diameter = 24  segments = 64 }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `radius` | number | `1` | |
+| `diameter` | number | — | An alternative spelling of the same thing |
+| `segments` | integer | `0` | Segments around the circle; `0` lets the kernel choose |
+
+#### Caveats
+
+- Give `radius` **or** `diameter`, never both: `circle: give either "radius" or "diameter",
+  not both`. Both spellings exist because a drilled hole is specified by diameter and a
+  fillet by radius, and converting at the call site is where mistakes happen.
+- Always centred on the origin. There is no `center` attribute.
+
+---
+
+## `ellipse`
+
+A circle scaled to two exact radii.
+
+```hcl
+ellipse { radii = [30, 18] }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `radii` | 2-vector | **required** | Semi-axes along X and Y |
+| `segments` | integer | `0` | Segments around the unit circle before scaling |
+
+#### Caveats
+
+- Implemented as a scaled unit circle, so both radii stay exact rather than being
+  approximated by a polygon fitted to an ellipse.
+- Always centred. There is no `center` attribute — passing one is
+  `ellipse: unknown attribute "center"`.
+
+---
+
+## `regular_polygon`
+
+An *n*-sided polygon, sized the way the part it represents is actually specified.
+
+```hcl
+regular_polygon { sides = 6  width_across_flats = 5.5 }   // an M3 nut
+regular_polygon { sides = 8  radius = 20  rotation = 22.5 }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sides` | integer | **required** | At least 3 |
+| `width_across_flats` | number | — | Distance between opposite flats — how a hex key or a nut is specified |
+| `width_across_corners` | number | — | Distance between opposite corners |
+| `radius` | number | `1` | Centre to corner. Same as half the across-corners width |
+| `diameter` | number | — | Twice the radius |
+| `rotation` | angle | `0` | Where the first corner sits, in degrees |
+
+#### Caveats
+
+- Give **one** sizing attribute. They are tried in the order above, so
+  `width_across_flats` wins if several are present — do not rely on that; pass one.
+- `radius` and `diameter` together are an error, as on [`circle`](#circle).
+- Fewer than 3 sides is an error: `regular_polygon: "sides" must be at least 3`.
+- Always centred on the origin.
+- With `rotation = 0` the first corner is on +X. For a hexagon with **flats** on the X axis,
+  use `rotation = 30`.
+
+---
+
+## `stadium`
+
+A rectangle fully rounded on its short axis — the shape of a slot.
+
+```hcl
+stadium { size = [40, 8]  center = true }
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | 2-vector | **required** | Width and height, over the rounded ends |
+| `segments` | integer | `0` | Segments per end arc |
+| `center` | bool | `false` | As for [`rect`](#rect) |
+
+#### Caveats
+
+- The corner radius is always half the **shorter** side. That is what makes it a stadium
+  rather than a [`rounded_rect`](#rounded_rect) that happens to look like one, and it means
+  the ends are always semicircular however long it is.
+
+---
+
+## `polygon`
+
+An explicit outline, or several contours.
+
+```hcl
+polygon {
+  points = [
+    [0, 0], [26, 0], [24, 6], [16, 26],
+    [14, 48], [18, 66], [22, 74], [0, 74],
+  ]
+}
+```
+
+#### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `points` | list | **required** | A list of `[x, y]` points, or a list of such lists for several contours |
+| `fill_rule` | `"EvenOdd"` `"NonZero"` `"Positive"` `"Negative"` | `"NonZero"` | How overlapping contours are resolved |
+
+#### Caveats
+
+- At least three points: `polygon: "points" must be an array of at least 3 points`.
+- **A nested list is read as several contours.** `[[0,0],[1,0],[1,1]]` is one triangle;
+  `[[[0,0],…],[[2,2],…]]` is two contours, which is how a shape with a hole is written
+  without a separate `difference`.
+- The outline should not self-intersect. The fill rule decides what happens when it does,
+  rather than the shape being rejected.
+- Points are not closed for you — the last point connects back to the first automatically, so
+  do not repeat it.
+
+---
+
+## Usage
+
+### Profiles for revolving
+
+`polygon` is the workhorse for anything turned on a lathe. The profile is written in the XY
+plane with X as the radius and Y as the height, then revolved:
+
+```hcl
+local profile = [
+  [0, 0], [26, 0], [24, 6], [16, 26],
+  [14, 48], [18, 66], [22, 74], [0, 74],
+]
+
+model "vase" {
+  revolve { segments = 96  polygon { points = profile } }
+}
+```
+
+Every X must be ≥ 0 — a profile that crosses the axis revolves through itself.
+
+### Slots and keyways
+
+`stadium` extruded is a slot; subtracted, it is a keyway:
+
+```hcl
+difference {
+  extrude { height = 6  rect { size = [60, 20]  center = true } }
+  translate {
+    offset = [0, 0, -1]
+    extrude { height = 8  stadium { size = [40, 6]  center = true } }
+  }
+}
+```
+
+### Hex sockets sized from the tool
+
+`width_across_flats` is the number printed on the key, so the model says what it means:
+
+```hcl
+for i, size in [1.5, 2, 2.5, 3, 4, 5, 6] {
+  translate {
+    offset = [i * 8, 0, 0]
+    extrude { height = 20  regular_polygon { sides = 6  width_across_flats = size + 0.3 } }
+  }
+}
+```
+
+The `+ 0.3` is print clearance — the language has no opinion about fits, so the model states
+them.
+
+### Holes without a boolean
+
+A second contour inside the first is a hole, which keeps a two-part profile as one shape:
+
+```hcl
+polygon {
+  fill_rule = "EvenOdd"
+  points = [
+    [[0, 0], [40, 0], [40, 30], [0, 30]],    // outline
+    [[10, 10], [30, 10], [30, 20], [10, 20]], // hole
+  ]
+}
+```
+
+---
+
+## Troubleshooting
+
+### `part "body" is 2D — extrude or revolve it before rendering`
+
+A 2D shape reached the renderer. Wrap it:
+
+```hcl
+extrude { height = 4  circle { radius = 10 } }
+```
+
+### `"circle" is a shape and cannot contain other blocks`
+
+A shape is a leaf. Something was nested inside its braces — usually a missing `}` on the
+line before, so the next block was swallowed.
+
+### `circle: give either "radius" or "diameter", not both`
+
+Pass one. They mean the same thing and accepting both would let a model disagree with itself.
+
+### `circle: unknown attribute "segements"`
+
+A typo. Every block rejects attributes it did not read, precisely so a misspelling fails
+loudly instead of silently rendering the default.
+
+### My rounded rectangle came out as a plain rectangle
+
+`radius` defaults to `1`, which is invisible at most sizes, and it is clamped to half the
+shorter side. Check that it is set and that the shape is big enough to show it.
+
+### My hexagon is rotated 30° from what I wanted
+
+`rotation = 0` puts a **corner** on +X. For a flat on +X, use `rotation = 30` — or in general
+`180 / sides`.