@metamesh/modeling 0.19.0 → 0.20.0

package/dist/docs/guides/svg-and-text.md

@@ -19,8 +19,8 @@ painted bounds by default. `origin: "document"` retains the converted document v
 
 ## SVG parameter and extrusion
 
-Pass an SVG control's string value from `params` directly to `svgSection`. This example aliases
-`params` as `parameters`:
+Add an **SVG** control with ID `artwork` in **Model controls**, then pass its string value directly
+to `svgSection`:
 
 
 
@@ -28,19 +28,16 @@ Pass an SVG control's string value from `params` directly to `svgSection`. This
 import { svgSection } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
-export default generate(({ params: parameters, part }) => {
-  const profile = svgSection(parameters.profile6);
-  return [part("model", profile.extrude({ height: 3, center: true }))];
+export default generate(({ params, part }) => {
+  const profile = svgSection(params.artwork);
+  return part("model", profile.extrude({ height: 3, center: true }));
 });
 ```
 
 
 
-The property name matches the ID in **Model controls**: `profile6` in this example, or
-`parameters.logo` for a control with ID `logo`.
-
-`svgSection` also accepts literal SVG documents. Here two nested subpaths make a badge
-with a rectangular opening:
+`svgSection` also accepts a constant SVG document. This single path combines curved scallops
+and a star-shaped opening; the artwork stays outside `generate` because it does not depend on controls:
 
 
 
@@ -48,27 +45,33 @@ with a rectangular opening:
 import { svgSection } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
+// One path combines a curved outer edge with a star-shaped opening.
+const artwork = `
+  <svg xmlns="http://www.w3.org/2000/svg" width="48mm" height="32mm" viewBox="0 0 48 32">
+    <path
+      fill-rule="evenodd"
+      d="
+        M 24 0
+        C 28 0 29 4 33 4 C 37 2 41 4 41 8
+        C 45 8 48 12 48 16 C 48 20 45 24 41 24
+        C 41 28 37 30 33 28 C 29 28 28 32 24 32
+        C 20 32 19 28 15 28 C 11 30 7 28 7 24
+        C 3 24 0 20 0 16 C 0 12 3 8 7 8
+        C 7 4 11 2 15 4 C 19 4 20 0 24 0 Z
+        M 24 7 L 26.5 12.6 L 32.5 13.3 L 28 17.6 L 29.2 24
+        L 24 20.8 L 18.8 24 L 20 17.6 L 15.5 13.3 L 21.5 12.6 Z
+      "
+    />
+  </svg>
+`;
+
 export default generate(({ part }) => {
-  // Physical root units make the imported artwork exactly 48 × 32 mm.
-  // Even-odd filling turns the second closed subpath into an opening.
-  const badge = svgSection(`
-    <svg xmlns="http://www.w3.org/2000/svg" width="48mm" height="32mm" viewBox="0 0 48 32">
-      <path
-        fill-rule="evenodd"
-        d="M 0 0 H 48 V 32 H 0 Z M 14 8 H 34 V 24 H 14 Z"
-      />
-    </svg>
-  `);
-  // Check the imported topology before using it in the manufacturing solid.
-  const measurements = badge.inspect();
-  if (measurements.componentCount !== 1 || measurements.contourCount !== 2) {
-    throw new Error("Expected one badge with one rectangular opening.");
-  }
-  return [part("model", badge.extrude({ height: 4, center: true }))];
+  const badge = svgSection(artwork);
+  return part("badge", badge.extrude({ height: 4, center: true }));
 });
 ```
 
-The 48 × 32 mm SVG document retains its physical size and even-odd opening after extrusion.
+A 48 × 32 × 4 mm badge combines smooth cubic curves and a crisp star-shaped opening in one SVG path.
 
 
 
@@ -83,18 +86,27 @@ not reserve space. Adaptive curve tolerance and edge spacing apply at the final
 
 
 ```ts
-import { bounds2, svgSection } from "@metamesh/modeling";
+import { rectangle, svgSection } from "@metamesh/modeling";
+import { bounds2 } from "@metamesh/modeling/geometry";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
+  const target = bounds2({ size: [30, 18] });
   const artwork = svgSection('<svg><circle r="1"/></svg>', {
-    fit: bounds2({ size: [30, 18] }),
+    fit: target,
     resolution: { maxChordError: 0.05 },
   });
-  return part("artwork", artwork.extrude({ height: 0.8 }));
+  // The outline marks the available 30 × 18 mm rectangle, outside the artwork.
+  const outline = rectangle({ size: [31, 19] }).subtract(rectangle({ size: [30, 18] }));
+  return [
+    part("artwork", { geometry: artwork.extrude({ height: 0.8 }), color: "#f6ad55" }),
+    part("target-outline", { geometry: outline.extrude({ height: 0.35 }), color: "#60a5fa" }),
+  ];
 });
 ```
 
+Fit the painted outline in millimetres before sampling and extrusion, preserving its aspect ratio.
+
 
 
 To prepare SVG without an engine, `preflightSvgRegion` from `@metamesh/modeling/geometry` accepts
@@ -104,6 +116,10 @@ align layers imported with the same document coordinate system and origin.
 Exact circular segment counts retain precedence over adaptive sampling. Empty artwork cannot
 be fitted, and fitting rejects a requested resolution that exceeds the sampling limits.
 
+Round stroke caps are outward semicircles aligned with their end segments. Each cap uses
+`ceil(circularSegments / 2)` intervals, following the shared arc-sampling policy; odd counts are
+accepted. This also applies to pure `strokeRegionData` and authored `stroke` Sections.
+
 Visible fills and bounded strokes contribute geometry; editor metadata is ignored. Editor text is
 outlined to visible paths on Apply. Live `<text>`, images, `<use>`, external resources, class-based
 stylesheets, nested SVG viewports, clipping, masks, filters, scripts, animation, gradients, patterns,
@@ -143,7 +159,7 @@ export default generate(({ params, services, part }) => {
     letterSpacing: 0.15,
   });
   // textSection preserves counters, such as the enclosed hole in the letter a.
-  return [part("label", textSection(layout).extrude({ height: 1.2 }))];
+  return part("label", textSection(layout).extrude({ height: 1.2 }));
 });
 ```
 
@@ -167,24 +183,42 @@ and write parameter-specific error messages for your model.
 
 
 ```ts
+import { rectangle, textSection } from "@metamesh/modeling";
 import {
   bounds2,
   fitTextLayout,
   type FittedTextLayout,
   type VectorTextLayout,
 } from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
 
-export function labelFits(layout: VectorTextLayout): boolean {
+function labelFits(layout: VectorTextLayout): boolean {
   const ink = layout.metrics.bounds;
   return ink !== null && bounds2({ size: [40, 12] }).containsBounds(ink);
 }
 
-export function fitLabel(layout: VectorTextLayout): FittedTextLayout {
+function fitLabel(layout: VectorTextLayout): FittedTextLayout {
   // Fit visible ink while preserving proportions and preventing enlargement.
   return fitTextLayout(layout, bounds2({ size: [40, 12] }), { maxScale: 1 });
 }
+
+export default generate(({ services, params, part }) => {
+  const layout = services.text.layout("MetaMesh", { font: params.font, fontSize: 20 });
+  const fitted = fitLabel(layout);
+  if (!labelFits(fitted)) throw new Error("Keep the lettering inside the label area.");
+  const backing = rectangle({ size: [44, 16], treatment: { kind: "round", radius: 2 } }).extrude({
+    height: 2,
+  });
+  const lettering = textSection(fitted).extrude({ height: 0.8 }).translate([0, 0, 2]);
+  return [
+    part("backing", { geometry: backing, color: "#60a5fa" }),
+    part("lettering", { geometry: lettering, color: "#f6ad55" }),
+  ];
+});
 ```
 
+Fit the visible letter outlines to the label area before turning them into material.
+
 
 
 | Setting         | Meaning                                                                        |
@@ -196,7 +230,7 @@ export function fitLabel(layout: VectorTextLayout): FittedTextLayout {
 | `verticalAlign` | First-line baseline by default, or top, center, or bottom using visible bounds |
 | `lineHeight`    | Baseline-spacing multiplier; omitted uses the font's natural line spacing      |
 
-For a circular label, add a [`baseline`](../reference/geometry/VectorTextArcBaseline.md) with
+For a circular label, add a [`baseline`](../reference/text/VectorTextArcBaseline.md) with
 `kind: "arc"` and a positive `radius` in millimetres to the layout options. The baseline is centered
 at the XY origin; `centerAngle` chooses its alignment datum and `direction` chooses the
 reading direction. Each shaped glyph group rotates without bending. Circular text requires one
@@ -208,8 +242,11 @@ Empty or whitespace-only text can be measured but cannot create a section. Retur
 for that expected input; a missing glyph also requires different wording or a font that supports it.
 See [`TextSectionOptions`](../reference/model/TextSectionOptions.md) for exact options.
 
-Studio loads declared fonts before generation. Export uses the captured visible mesh. Saving a Project
-preserves the exact selection, including its revision, without embedding font bytes. Fonts beyond
-the bundled starters can require internet; ordinary browser caching does not guarantee them offline.
-If loading fails, Studio preserves the selection and last valid model so you can retry or choose a
-replacement. Studio does not support custom font uploads.
+
+
+**Prepare for offline lettering**
+
+Saving a Project keeps the exact font selection, not its bytes. Fonts beyond the bundled starters
+  can need internet. Check the [font and offline
+  rules](https://metamesh.studio/docs/use/projects-and-offline#fonts-while-offline) before relying on a model away from a
+  connection.

package/dist/docs/guides/sweeps-and-lofts.md

@@ -32,12 +32,10 @@ export default generate(({ part }) => {
   ] as const;
   // The initial normal sets profile +X; transport carries it along the path.
   // The path is open, so the sweep closes both ends with caps.
-  return [
-    part(
-      "model",
-      section.sweep(path, { orientation: { kind: "transport", initialNormal: [0, 1, 0] } })
-    ),
-  ];
+  return part(
+    "model",
+    section.sweep(path, { orientation: { kind: "transport", initialNormal: [0, 1, 0] } })
+  );
 });
 ```
 
@@ -52,15 +50,54 @@ The asymmetric section makes its transported orientation visible as the path tur
   the sweep rejects a selected policy that becomes singular.
 - `twist` adds total rotation by physical path length. Set `twistBy: "stations"` to use the authored
   station schedule instead.
-- `scale` accepts a positive uniform size, an XY pair, or one XY pair per normalized station.
-- `closed: true` joins an implicitly closed path without repeated endpoints. Orientation, scales,
-  and `seamProfileOffset` must describe a compatible closing seam.
+- On an open path, `scale: 0.5` tapers from one to half size; `scale: [0.5, 1]` finishes at half
+  profile-local X size and unchanged Y size. Interpolation follows physical path length, independently
+  of `twistBy`. An array of XY pairs supplies exact scales at authored stations instead.
+- `closed: true` joins an implicitly closed path without repeated endpoints. Scalar/XY `scale` then
+  applies uniformly around the loop. The engine finds the cyclic vertex alignment and verifies
+  that every boundary coincides after the total twist. A hexagon can close after a 60° twist;
+  a rectangle cannot close after 45°. All sweep scales remain positive.
 
 Start with the open path above, inspect the first cap and the turns, then replace the rectangle
 with a [`circle`](../reference/model/circle.md) for a round rod. A sweep follows the supplied path
 stations; it does not infer a smooth curve between them. Sample a curve with the
 [path helpers](../reference/geometry/categories/curves-paths.md) when you need a curved trajectory.
 
+## Sweep through explicit placements
+
+Use `section.sweep([t0, t1, t2], options)` when your model already determines each station's
+placement and deformation. Each station accepts a plain `Frame3`, an immutable
+[`transform3`](../reference/geometry/transform3.md) value, or a row-major matrix. For example:
+
+
+
+```ts
+import { rectangle } from "@metamesh/modeling";
+import { transform3 } from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const profile = rectangle({ size: [12, 6] });
+  const stations = [
+    transform3(),
+    transform3().scale([0.8, 1, 1]).rotate([0, 0, 25]).translate([2, 0, 15]),
+    transform3().scale([0.5, 1, 1]).rotate([0, 0, 50]).translate([4, 0, 30]),
+  ];
+  // Each placement sets the section's full pose; no orientation is inferred.
+  return part("body", profile.sweep(stations));
+});
+```
+
+Each transform sets a complete station pose. The sweep connects their corresponding vertices without inventing intermediate rotations.
+
+
+
+Transforms already encode position, rotation, scale, and shear. This mode connects corresponding
+vertices at exactly the supplied stations; it does not infer rotations or add intermediate stations.
+Supply more placements to describe a curved or rotating route. Choose either a path or an array of transforms; mixed station lists reject.
+Explicit placements accept `closed` and `limits`, and reject orientation, twist, scale, and resolution controls.
+Set `closed: true` to connect the last station to the first without caps, preserving the supplied seams.
+
 ## Matched-section loft
 
 
@@ -77,21 +114,19 @@ export default generate(({ part }) => {
   // Transform the Section in its XY plane; loft supplies the station heights.
   // Keeping the original rectangle landmarks preserves corner correspondence.
   const top = base.scale([0.8, 1.2]).rotate(10).translate([3, 0]);
-  return [
-    part(
-      "model",
-      loft([
-        {
-          profile: base,
-          z: 0,
-        },
-        {
-          profile: top,
-          z: 18,
-        },
-      ])
-    ),
-  ];
+  return part(
+    "model",
+    loft([
+      {
+        profile: base,
+        z: 0,
+      },
+      {
+        profile: top,
+        z: 18,
+      },
+    ])
+  );
 });
 ```
 
@@ -99,11 +134,19 @@ The two rounded rectangles retain matching corner identities while their size an
 
 
 
-This [`loft`](../reference/model/loft.md) example places a rounded rectangle at two heights. Use
-`scale`, `rotate` and `translate` to pose the top profile in XY; `rotate` takes degrees. Each
-station uses `z` for an ordinary horizontal plane. To tilt a station, pass
-`frame: anchorFrame3(anchor3(position, direction, up))` instead; the direction chooses its
-normal and a nonparallel `up` vector chooses its roll.
+This [`loft`](../reference/model/loft.md) example places a rounded rectangle at two heights.
+Each station supplies its own profile and exactly one placement: `z` is a convenient height for
+a horizontal XY plane; `transform` accepts a non-singular affine transform for spatial placement
+and deformation. Rotations use degrees.
+
+The rendered example uses `z` for horizontal stations. For a spatial station, replace `z` with
+`transform: transform3().rotate([0, 0, 45]).translate([0, 0, 30])`. The profile keeps
+its local XY coordinates; the station transform places it in space.
+
+Loft `slices` counts positive integer intervals per adjacent station pair, defaulting to one. `slices: 20`
+inserts 19 profiles between each pair; an array assigns a separate interval count to each gap.
+Inserted profiles interpolate corresponding points in world space. To follow a rotating or curved
+trajectory, supply its stations explicitly rather than expecting extra slices to infer that route.
 
 The primitive retains its corner identities, so `loft` pairs corresponding landmarks without
 extra setup. The same approach works when corners become square or fully rounded. For a hollow
@@ -114,13 +157,14 @@ must retain consistent handedness across the stations.
 
 Custom hole topology or disconnected components can use an explicit
 [`Profile`](../reference/geometry/Profile.md) family with stable component, contour, and span IDs.
-Prepare [`matchProfiles`](../reference/geometry/matchProfiles.md) once and pass its
+Prepare [`matchProfiles`](../reference/geometry/matchProfiles.md) once, passing generation’s
+effective `resolution` and `limits` when it must agree with the host, then pass its
 [`CorrespondingProfile`](../reference/geometry/CorrespondingProfile.md) stations to the same `loft`
 function. Topology must remain constant across stations. Arbitrary Boolean Sections default to
 `correspondence: "direct"`; choose `"reindex"`, `"fast-distance"`, or `"distance"` to change the
 association strategy, or use explicit profiles for landmarks. Direct association preserves the supplied seams;
 reindex also chooses a cyclic phase, while distance methods optimize ordered connections. See
-[`LoftOptions`](../reference/geometry/LoftOptions.md) for sampling and work limits.
+[`LoftOptions`](../reference/model/LoftOptions.md) for sampling and work limits.
 
 ## Sample a heightfield
 
@@ -137,22 +181,22 @@ import { heightfield } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
-  return [
-    part(
-      "model",
-      heightfield({
-        coordinates: {
-          x: [-20, -18, -14, -8, 0, 8, 14, 18, 20],
-          y: [-12, -10, -6, 0, 6, 10, 12],
-        },
-        triangulation: "min-edge",
-        height: ([x, y]) => 3 + 0.8 * Math.cos(x / 6) * Math.cos(y / 5),
-      })
-    ),
-  ];
+  return part(
+    "model",
+    heightfield({
+      coordinates: {
+        x: [-20, -18, -14, -8, 0, 8, 14, 18, 20],
+        y: [-12, -10, -6, 0, 6, 10, 12],
+      },
+      triangulation: "min-edge",
+      height: ([x, y]) => 3 + 0.8 * Math.cos(x / 6) * Math.cos(y / 5),
+    })
+  );
 });
 ```
 
+An uneven XY grid samples absolute top heights. Walls and a flat underside close the tile.
+
 
 
 The uneven axes place more samples near the border. Coordinates are absolute millimetres, strictly