@metamesh/modeling 0.11.0 → 0.13.0

package/dist/api/text.d.ts

@@ -1,107 +1,119 @@
-/** Limits apply before parsing or shaping untrusted font data. */
-export declare const MAX_VECTOR_FONT_BYTES: number;
-
-/**
- * Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
- *
- * @example Prepare a label before building geometry
- * ```ts
- * async function prepareLabel(fontBytes: Uint8Array) {
- *   const font = await prepareVectorFont(fontBytes);
- *   return font.layout("MetaMesh", { fontSize: 8 });
- * }
- * ```
- */
-export declare function prepareVectorFont(bytes: Uint8Array, options?: VectorFontOptions): Promise<VectorFont>;
-
-/**
- * A prepared font owns its parsed bytes; keep handles local to their Worker or invocation.
- */
-export declare interface VectorFont {
-    /** Shape horizontal lines or one circular line; bounded to 512 UTF-16 units and supports blank text. */
-    readonly layout: (text: string, options: VectorTextLayoutOptions) => VectorTextLayout;
-    /** Measure the same cached vector layout; all returned lengths are in millimetres. */
-    readonly measure: (text: string, options: VectorTextLayoutOptions) => VectorTextMetrics;
-    /** Serialize visible horizontal or circular outlines as bounded path-only SVG in physical millimetres. */
-    readonly toSvg: (text: string, options: VectorTextLayoutOptions) => string;
-}
-
-/** Identifies the actual weight of a static face, without synthesizing a different weight. */
-export declare interface VectorFontOptions {
-    /** Actual weight of a static face, 1–1000; defaults to 400. */
-    readonly staticWeight?: number;
-}
-
-/** A circular baseline centered at the XY origin, with rigid shaped glyph groups. */
-export declare interface VectorTextArcBaseline {
-    /** Selects a circular baseline; glyph outlines rotate without bending or stretching. */
-    readonly kind: "arc";
-    /** Baseline radius in millimetres, greater than zero and at most 10000. */
-    readonly radius: number;
-    /** Alignment datum in degrees counterclockwise from +X; defaults to 90. */
-    readonly centerAngleDegrees?: number;
-    /** Reading direction around the circle; defaults to clockwise. */
-    readonly direction?: "clockwise" | "counterclockwise";
-}
-
-/** Exact curve bounds in millimetres; positive Y points upward. */
-export declare interface VectorTextBounds {
-    /** Minimum X and Y of visible outlines, including accents, descenders, and overhangs. */
-    readonly min: readonly [number, number];
-    /** Maximum X and Y of visible outlines. */
-    readonly max: readonly [number, number];
-}
-
-/**
- * Immutable vector layout with no browser, font parser, or kernel ownership.
- */
-export declare interface VectorTextLayout {
-    /** Nonzero-filled path data in millimetres, positive Y upward; empty for text with no ink. */
-    readonly paths: readonly string[];
-    /** Exact measurements of these paths and their logical text layout. */
-    readonly metrics: VectorTextMetrics;
-}
-
-/**
- * Text bounded to 512 UTF-16 units: horizontal lines or one circular line without wrapping.
- */
-export declare interface VectorTextLayoutOptions extends VectorTextOptions {
-    /** Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left. */
-    readonly align?: "left" | "center" | "right";
-    /** Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment. */
-    readonly baseline?: VectorTextArcBaseline;
-    /** Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics. */
-    readonly lineHeight?: number;
-    /** Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline. */
-    readonly verticalAlign?: "baseline" | "top" | "center" | "bottom";
-}
-
-/** Text measurements from the same immutable layout that supplies geometry and SVG outlines. */
-export declare interface VectorTextMetrics {
-    /** Visible curve bounds after alignment, or null when the text has no ink. */
-    readonly bounds: VectorTextBounds | null;
-    /** Unaligned logical advance and negative baseline displacement in mm; arcs retain [arc length, 0]. */
-    readonly advance: readonly [number, number];
-    /** Maximum logical line advance in millimetres, including spaces; arc length on circular baselines. */
-    readonly logicalWidth: number;
-    /** Selected font's ascender distance above a baseline in millimetres, independent of the text. */
-    readonly ascent: number;
-    /** Selected font's descender distance below a baseline in millimetres, a non-negative value. */
-    readonly descent: number;
-    /** Actual distance between baselines in millimetres. */
-    readonly lineHeight: number;
-    /** Number of lines, including empty and trailing lines; empty text occupies one line. */
-    readonly lineCount: number;
-}
-
-/** Shaping controls for a prepared exact font face; all lengths are in millimetres. */
-export declare interface VectorTextOptions {
-    /** Em size in millimetres, greater than zero and at most 10000; not the visible glyph height. */
-    readonly fontSize: number;
-    /** Actual static or variable weight, 1–1000; defaults to the prepared face's static weight. */
-    readonly fontWeight?: number;
-    /** Tracking between glyph clusters in millimetres, -100–100; defaults to zero. */
-    readonly letterSpacing?: number;
-}
-
-export { }
+/** Axis-aligned bounds in two-dimensional model space. */
+export declare interface Bounds2 {
+  /** Inclusive maximum X/Y coordinates. */
+  readonly max: Vector2;
+  /** Inclusive minimum X/Y coordinates. */
+  readonly min: Vector2;
+}
+
+/** Limits apply before parsing or shaping untrusted font data. */
+export declare const MAX_VECTOR_FONT_BYTES: number;
+
+/**
+ * Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
+ *
+ * @example Prepare a label before building geometry
+ * ```ts
+ * async function prepareLabel(fontBytes: Uint8Array) {
+ *   const font = await prepareVectorFont(fontBytes);
+ *   return font.layout("MetaMesh", { fontSize: 8 });
+ * }
+ * ```
+ */
+export declare function prepareVectorFont(
+  bytes: Uint8Array,
+  options?: VectorFontOptions,
+): Promise<VectorFont>;
+
+/** A two-dimensional Cartesian vector or point. */
+export declare type Vector2 = readonly [x: number, y: number];
+
+/**
+ * A prepared font owns its parsed bytes; keep handles local to their Worker or invocation.
+ */
+export declare interface VectorFont {
+  /** Shape horizontal lines or one circular line; bounded to 512 UTF-16 units and supports blank text. */
+  readonly layout: (
+    text: string,
+    options: VectorTextLayoutOptions,
+  ) => VectorTextLayout;
+  /** Measure the same cached vector layout; all returned lengths are in millimetres. */
+  readonly measure: (
+    text: string,
+    options: VectorTextLayoutOptions,
+  ) => VectorTextMetrics;
+  /** Serialize visible horizontal or circular outlines as bounded path-only SVG in physical millimetres. */
+  readonly toSvg: (text: string, options: VectorTextLayoutOptions) => string;
+}
+
+/** Identifies the actual weight of a static face, without synthesizing a different weight. */
+export declare interface VectorFontOptions {
+  /** Actual weight of a static face, 1–1000; defaults to 400. */
+  readonly staticWeight?: number;
+}
+
+/** A circular baseline centered at the XY origin, with rigid shaped glyph groups. */
+export declare interface VectorTextArcBaseline {
+  /** Selects a circular baseline; glyph outlines rotate without bending or stretching. */
+  readonly kind: "arc";
+  /** Baseline radius in millimetres, greater than zero and at most 10000. */
+  readonly radius: number;
+  /** Alignment datum in degrees counterclockwise from +X; defaults to 90. */
+  readonly centerAngleDegrees?: number;
+  /** Reading direction around the circle; defaults to clockwise. */
+  readonly direction?: "clockwise" | "counterclockwise";
+}
+
+/**
+ * Immutable vector layout with no browser, font parser, or kernel ownership.
+ */
+export declare interface VectorTextLayout {
+  /** Nonzero-filled path data in millimetres, positive Y upward; empty for text with no ink. */
+  readonly paths: readonly string[];
+  /** Exact measurements of these paths and their logical text layout. */
+  readonly metrics: VectorTextMetrics;
+}
+
+/**
+ * Text bounded to 512 UTF-16 units: horizontal lines or one circular line without wrapping.
+ */
+export declare interface VectorTextLayoutOptions extends VectorTextOptions {
+  /** Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left. */
+  readonly align?: "left" | "center" | "right";
+  /** Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment. */
+  readonly baseline?: VectorTextArcBaseline;
+  /** Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics. */
+  readonly lineHeight?: number;
+  /** Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline. */
+  readonly verticalAlign?: "baseline" | "top" | "center" | "bottom";
+}
+
+/** Text measurements from the same immutable layout that supplies geometry and SVG outlines. */
+export declare interface VectorTextMetrics {
+  /** Visible curve bounds after alignment, or null when the text has no ink. */
+  readonly bounds: Bounds2 | null;
+  /** Unaligned logical advance and negative baseline displacement in mm; arcs retain [arc length, 0]. */
+  readonly advance: readonly [number, number];
+  /** Maximum logical line advance in millimetres, including spaces; arc length on circular baselines. */
+  readonly logicalWidth: number;
+  /** Selected font's ascender distance above a baseline in millimetres, independent of the text. */
+  readonly ascent: number;
+  /** Selected font's descender distance below a baseline in millimetres, a non-negative value. */
+  readonly descent: number;
+  /** Actual distance between baselines in millimetres. */
+  readonly lineHeight: number;
+  /** Number of lines, including empty and trailing lines; empty text occupies one line. */
+  readonly lineCount: number;
+}
+
+/** Shaping controls for a prepared exact font face; all lengths are in millimetres. */
+export declare interface VectorTextOptions {
+  /** Em size in millimetres, greater than zero and at most 10000; not the visible glyph height. */
+  readonly fontSize: number;
+  /** Actual static or variable weight, 1–1000; defaults to the prepared face's static weight. */
+  readonly fontWeight?: number;
+  /** Tracking between glyph clusters in millimetres, -100–100; defaults to zero. */
+  readonly letterSpacing?: number;
+}
+
+export {};

package/dist/docs/guides/concepts.md

@@ -0,0 +1,197 @@
+# Geometry API concepts
+
+Choose the public Modeling modules, understand geometry and lifecycle conventions, and use them in Studio or a standalone Node or Worker host.
+
+Import modeling functions from the package root:
+
+
+
+```ts
+import { box, cylinder } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+```
+
+
+
+Studio supplies this API and its runtime to code Projects. Standalone applications use the same
+operations inside a generation program. The [Model API reference](../reference/model.md) provides
+exact signatures; this guide explains how the concepts fit together.
+
+## Choose the module for your host
+
+| Import                                                    | Use it for                                                          | Who owns execution                      |
+| --------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------- |
+| [`@metamesh/modeling`](../reference/model.md)             | Sections, Solids, transforms, Booleans, sweeps, lofts, and patterns | A synchronous generation program        |
+| [`@metamesh/modeling/geometry`](../reference/geometry.md) | Pure paths, profiles, calculations, and indexed meshes              | Your ordinary TypeScript code           |
+| [`@metamesh/modeling/engine`](../reference/engine.md)     | Standalone initialization, model finalization, and 3MF export       | Your Node application or browser Worker |
+| [`@metamesh/modeling/text`](../reference/text.md)         | Prepare exact font bytes and vector layouts outside Studio          | Your host acquires the font bytes       |
+
+Call root modeling operations inside synchronous generation. Add pure geometry helpers for custom
+calculations.
+
+## Use Modeling outside Studio
+
+Follow [Run Modeling in your application](hosting.md)
+to initialize the engine, build a model, load WASM, and export its completed snapshot.
+For lettering, [prepare exact font bytes](fonts.md) before building.
+
+## Geometry vocabulary
+
+The public API names values by modeling role:
+
+- A `Path3` is an ordered 3D trajectory.
+- A `Path2` is an ordered 2D trajectory.
+- A `Contour` is plain point data for a closed 2D boundary, without a repeated closing point.
+- A `Polygon` is explicit point data for one outer contour and its holes. A `Region` contains
+  disjoint polygons; neither is an engine-owned modeling handle.
+- A `Profile` specifies identified components, contours and spans for a related shape family.
+- A `CorrespondingProfile` contains the shared sampled landmarks produced by `matchProfiles`.
+- A `Section` is a filled 2D shape used for section Booleans, offsets, extrusion, revolution,
+  sweeps, and lofts.
+- A `Solid` is a valid three-dimensional result that can participate in solid Booleans and become
+  model output.
+- An `Anchor3` is an explicit local frame used to place one solid against another.
+- `Vector2` and `Vector3` are fixed numeric tuples for low-level coordinates.
+- `Bounds2` and `Bounds3` contain finite minimum and maximum tuples for measurements and placement.
+
+`Section` and `Solid` are opaque, evaluator-owned handles. Authored code chains their immutable
+methods and combines collections through imported functions. The engine owns native kernel values.
+
+Ordinary models use root Sections for shapes, Booleans, extrusion, sweeps, and lofts. The pure
+`/geometry` entry supplies point data through `circleContour`, `rectangleContour`, and other contour factories
+when custom calculations or mesh construction need it. `rectangle`, `rectangleContour`, and
+`rectangleProfile` share size, center, corner treatment, and sampling options; their result type
+reflects the operation's role.
+
+Use [`polygon(points)`](../reference/model/polygon.md) to fill one contour. The explicit
+`polygon({ outer, holes })` form validates exterior/hole topology and normalizes winding.
+`polygon({ contours, fillRule })` resolves compound paths with `"nonzero"` fill by default or
+explicit `"evenodd"` fill. These constructors return the same `Section` type as `circle` or
+`rectangle`; subsequent Booleans may produce holes or disconnected components.
+
+`rectangleProfile({ size: [width, height], treatment: { kind: "round", radius }, id })` describes
+identified spans for custom geometry. Prepare a complete explicit family with `matchProfiles`
+when loft stations or a sweep need authored holes, seams, or landmarks beyond ordinary primitives.
+
+Identified spans also accept cubic Béziers with the same endpoints and controls as
+[`CubicBezierCurve2`](../reference/geometry/CubicBezierCurve2.md). Paired spans share one parameter
+grid; physical sampling refines every member before choosing the family count. Collapsed spans
+retain repeated logical slots, while the completed loft removes degenerate faces.
+
+## Choose a modeling path
+
+| Starting intent                    | Typical operations                                                                                                                                                                                                                        |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A block, cylinder, sphere, or cone | Primitive solids, transforms, then [solid Booleans](fundamentals.md#choose-the-boolean-by-the-material-you-want)                                                                                                      |
+| A plate, gasket, logo, or profile  | Build a `Section`, use section Booleans or offsets, then [extrude](recipes.md#section-hole-offset-and-extrusion)                                                                                                      |
+| A rotational part                  | [Revolve a closed radial profile](recipes.md#revolve-a-radial-profile) around +Z                                                                                                                                      |
+| A tube or routed shape             | [Sweep one supported section](recipes.md#rotation-minimizing-path-sweep) along an open or closed path                                                                                                                 |
+| A transition between profiles      | [Loft corresponding boundaries](recipes.md#matched-section-loft) with holes                                                                                                                                           |
+| Repeated or mating parts           | [Patterns](recipes.md#primitive-booleans-and-repeated-placement), [explicit anchors](recipes.md#named-anchors-and-custom-frames), and [reusable thread settings](https://metamesh.studio/docs/develop/printable-threads) |
+
+Name meaningful intermediate values and choose a curve tolerance that preserves the required
+shape. Many high-resolution Boolean operands increase generation time.
+
+Primitive factories take one options object. For example, `rectangle({ size: [24, 16] })` creates a
+filled Section and `box({ size: [24, 16, 6] })` creates a Solid. `union` and `intersect`
+combine same-dimensional arrays. `shape.subtract(cutters)` accepts an array of same-dimensional
+cutters. `section.offset(distance, options)` stays in the filled XY plane.
+
+`section.extrude({ height, twistDegrees, scaleTop })` adds +Z depth, with its bottom at zero unless
+`center: true` is requested. `section.revolve({ revolveDegrees })` rotates radial/Z geometry around
++Z. `loft` pairs retained landmarks in compatible primitive Sections, including zero and fully
+rounded rectangle corners, and circle/ellipse stations transitioning to rectangles. This also works
+after invertible XY transforms with consistent handedness. It accepts explicit corresponding
+Profile stations for custom topology. Boolean Sections and point contours need a selected
+`correspondence` method (`"direct"`, `"reindex"`, `"fast-distance"`, or `"distance"`) or explicit
+profiles; Boolean contour order does not establish semantic correspondence.
+`section.sweep(path, options)` supports open or closed paths,
+degree twist, uniform/XY/per-station scales and an explicit compatible closed seam.
+
+## Coordinates, units, and resolution
+
+MetaMesh uses a right-handed coordinate system with **+Z up**. Authored dimensions and curve
+tolerances are millimetres; angular arguments such as `rotate` use degrees.
+
+`GeometryResolution` controls sampled curves in physical space. The default maximum chord error is
+`0.05 mm`, with 16–512 segments for a complete circle and no default maximum segment length. An
+operation-specific `segments` or `circularSegments` value takes priority, followed by its local
+`resolution`, and then host session defaults. A shape does not carry a sampling policy into later
+operations; pass the policy explicitly where needed.
+
+Use an exact segment count for intentionally faceted geometry or when two sampled contours must
+match point for point. Use physical chord and segment limits for ordinary printable curves. If a
+requested tolerance cannot fit within the safety cap, the operation fails instead of silently
+returning a coarser shape.
+
+`regularPolygon({ radius, sides, rotationDegrees, sizing })` makes a filled regular polygon.
+`sizing: "vertex"` uses the specified vertex radius; `"face"` compensates faceting so the faces
+meet the nominal radius. `circle` and `cylinder` support the same radial convention.
+
+Finishing shares `round` (radius), `chamfer` (setbacks), `smooth` (cubic setbacks), and exact
+`profile` points across applicable box edges, rectangle corners, and cylinder/extrusion ends.
+Boxes can select disjoint named edges or groups; rectangles can select individual corners.
+Cylinder/frustum and straight convex extrusion rims use independent `ends.bottom` and `ends.top`.
+Zero rounding radius, zero chamfer/smooth distance, or an all-zero distance pair leaves the
+selected feature untreated. Other setback pairs must have two positive values; negative and
+nonfinite amounts reject. Disabled extrusion end treatments retain ordinary extrusion support,
+including holes and twist.
+`placement` maps a named or explicit shape-local anchor to a world anchor after local
+construction, using alignment, millimetre gap and degree spin. Section placement must stay in XY.
+
+## SVG sections: fills and strokes are different inputs
+
+[`svgSection`](../reference/model/svgSection.md) converts a bounded complete SVG document into one
+painted `Section`. Supported visible **fills and bounded strokes both contribute geometry**. It
+handles supported shapes, paths, affine transforms, physical root units, `viewBox` scaling, and
+allowlisted inline fill and stroke presentation.
+
+[`svgPathSection`](../reference/model/svgPathSection.md) accepts SVG path-data text rather than a
+document. It is a **fill-only** path operation: stroke styling is not part of that contract. Path
+units default to millimetres and can be converted with its scale option.
+
+Both functions convert SVG's Y-down plane to MetaMesh's Y-up plane and center the final painted
+bounds by default. Use `origin: "document"` with `svgSection` when the converted document viewport
+origin must remain meaningful. Adaptive flattening happens after supported transforms and unit
+conversion, so tolerances apply in final millimetre space.
+
+Unsupported layout or external content fails rather than disappearing silently. The current public
+contract does not include nested SVG viewports, `<use>`, images, live text, external stylesheets,
+clipping, masks, filters, scripts, animation, gradients, patterns, uploaded project assets, or
+custom font files. Use the [SVG extrusion recipe](recipes.md#svg-parameter-and-extrusion)
+for a complete authored example.
+
+## Text and font variability
+
+`services.text.layout()` shapes text inside generation. Cache an expensive shared layout with
+`computed`, measure its `metrics`, and pass it to `textSection(layout())`. There is no
+ambient font provider or repeated shaping during export. Declare a Text control for the wording
+and a Font control for the face and weight.
+
+Font size is the em size in millimetres, not the height of a particular letter. Layout supports
+multiple lines, spacing, and alignment. Follow the
+[text recipe](recipes.md#text-from-a-font-parameter) for the control setup,
+layout conventions, and font availability limits.
+
+## Printable threads
+
+The public API provides coordinated external threads, internal cutters, and threaded nuts. Reuse
+one profile and fit policy across mating parts, then prove them with a short calibration print.
+
+Follow [Build printable threads](https://metamesh.studio/docs/develop/printable-threads) for the illustrated workflow,
+complete source, profile and fit choices, end treatments, and links into the exact API contracts.
+
+## Lifecycle and inspection
+
+Studio or your standalone engine owns geometry initialization, cleanup, and mesh finalization.
+The host owns Worker recovery, preview, and file delivery. Do not manually delete `Section` or `Solid`
+values. Use
+`inspectSection()` and `inspectSolid()` for supported bounds, topology counts, area, and volume
+measurements.
+
+An inspection result describes the generated geometry; it does not certify wall thickness,
+overhangs, fits, loads, or manufacturability. Keep those product decisions in parameters,
+validation, and your downstream manufacturing checks.
+
+- [Use geometry recipes](recipes.md)
+- [Browse exact signatures](../reference/model.md)

package/dist/docs/guides/fonts.md

@@ -0,0 +1,51 @@
+# Prepare fonts for modeling
+
+Prepare licensed font bytes and a reusable text layout before building a model outside Studio.
+
+Your host acquires exact licensed font bytes before synchronous generation.
+Studio authors use the [Font control recipe](recipes.md#text-from-a-font-parameter);
+standalone applications use the optional `@metamesh/modeling/text` entry point.
+
+## Install font support
+
+Install the optional `fontkit` peer. WOFF2 input also needs `woff2-encoder`:
+
+```bash
+pnpm add fontkit
+pnpm add woff2-encoder
+```
+
+TTF, OTF, and WOFF input use fontkit directly. WOFF2 decoding loads only when needed. The library
+does not fetch fonts; your application supplies their bytes.
+
+## Prepare one reusable layout
+
+
+
+```ts
+import { prepareVectorFont, type VectorTextLayout } from "@metamesh/modeling/text";
+
+export async function makeLabelLayout(fontBytes: Uint8Array): Promise<{
+  readonly layout: VectorTextLayout;
+  readonly svg: string;
+}> {
+  // Acquire licensed font bytes in your host before synchronous generation.
+  // Install fontkit; WOFF2 input also needs the optional woff2-encoder peer.
+  const font = await prepareVectorFont(fontBytes);
+  const layout = font.layout("MetaMesh", { fontSize: 8, letterSpacing: 0.15 });
+  const svg = font.toSvg("MetaMesh", { fontSize: 8, letterSpacing: 0.15 });
+  // Pass layout to textSection inside generation; its paths and metrics use Y-up millimetres.
+  return { layout, svg };
+}
+```
+
+
+
+Call `makeLabelLayout(fontBytes)` with the acquired bytes. It returns a `layout` and a separate
+`svg` string. The layout contains paths and metrics in Y-up millimetres. Pass the returned `layout` to
+[`textSection`](../reference/model/textSection.md) inside generation, then extrude its filled
+section with the ordinary modeling operations. A host can prepare layouts ahead of time or inject
+a deterministic text service and cache layouts with `computed`.
+
+Use the [Font preparation reference](../reference/text.md) for font and layout options, or
+[Run Modeling in your application](hosting.md) for the host lifecycle.

package/dist/docs/guides/fundamentals.md

@@ -0,0 +1,135 @@
+# Modeling fundamentals
+
+Understand watertight solids, coordinates, transforms, Boolean operations, and geometry ownership in Studio code Projects.
+
+[Manifold](https://manifoldcad.org/docs/jsapi/) is the solid-modeling kernel behind MetaMesh. Its
+core idea is a **manifold** mesh: an oriented, watertight boundary in which every edge belongs to a
+valid solid. That invariant makes Boolean operations and manufacturing output more dependable than
+working with an arbitrary triangle soup.
+
+Studio code Projects use Manifold through the curated `@metamesh/modeling` API. The public
+contract combines constructors and collection functions with fluent, opaque `Section` and `Solid`
+recipes. The engine owns the underlying kernel values.
+
+## Coordinates and units
+
+MetaMesh uses a right-handed coordinate system with **+Z up**. Model dimensions are millimetres.
+Place a part intentionally around the origin, then use transforms or anchors to relate it to other
+parts.
+
+Transform methods preserve the input and return immutable geometry recipes, so you can name
+meaningful stages and reuse a source shape without tracking hidden state.
+
+## Build solids compositionally
+
+Start with primitives, position them, and subtract a cutter that extends beyond both body faces:
+
+
+
+```ts
+import { box, cylinder } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const plate = box({ size: [80, 50, 4] });
+  // Primitives are centered by default, so both faces get 2 mm of overtravel.
+  // Overtravel is for robust subtraction; it does not enlarge the hole diameter.
+  const hole = cylinder({ height: 8, radius: 3 });
+  return [part("model", plate.subtract([hole]))];
+});
+```
+
+The cylinder clears both faces of the plate, leaving a through-hole without coincident cutter ends.
+
+
+
+The plate is centered about the origin. Its `4 mm` thickness occupies `Z = −2…2 mm`; the cutter
+occupies `Z = −4…4 mm`. That overtravel makes the subtraction deliberate while the hole radius
+stays `3 mm`. Derive cutter placement from the same datum as the body when changing dimensions.
+
+Prefer a small number of named intermediate solids. If many repeated cutters are independent, build
+or arrange them first and perform one meaningful subtraction where the API allows it. Excessive
+high-resolution Boolean steps cost time and obscure design intent.
+
+The `union` and `intersect` functions and `shape.subtract(cutters)` also combine filled Sections
+in XY. Choose one dimension for every operand in a call. Keep a Section native through its Boolean
+and offset steps, then chain `.extrude({ height })` or `.revolve(options)` to make a Solid.
+Transforms apply in written order about the origin: translating then rotating also rotates the
+translated position. Place finished parts through `part` options when their geometry can be reused.
+
+## Choose the Boolean by the material you want
+
+These three parts use the same overlapping block and cylindrical tool. Only the operation changes;
+the final translations separate the results for comparison.
+
+
+
+```ts
+import { box, cylinder, intersect, union } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const block = box({ size: [24, 24, 8] });
+  const tool = cylinder({ diameter: 20, height: 12 }).translate([10, 0, 0]);
+  // Reuse the same overlapping operands to compare the three operations.
+  // Place finished parts separately so display spacing can reuse their geometry.
+  return [
+    part("union", { geometry: union([block, tool]), color: "#60a5fa" }),
+    part("difference", {
+      geometry: block.subtract([tool]),
+      position: [42, 0, 0],
+      color: "#f59e0b",
+    }),
+    part("intersection", {
+      geometry: intersect([block, tool]),
+      position: [84, 0, 0],
+      color: "#34d399",
+    }),
+  ];
+});
+```
+
+Left: all material from union. Center: block material outside the tool. Right: material shared by both operands.
+
+
+
+| Operation                                                | Material retained                     | Common use                                               |
+| -------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------- |
+| [`union`](../reference/model/union.md)                   | Inside any operand                    | Join an overlapping boss or rib to a body                |
+| [`shape.subtract`](../reference/model/Solid.md#subtract) | Inside the base, outside every cutter | Cut holes, pockets, and clearance envelopes              |
+| [`intersect`](../reference/model/intersect.md)           | Inside every operand                  | Trim a feature to an envelope or isolate shared material |
+
+Use intentional overlap for joined features and overtravel for through-cutters. A face or point
+that only touches another feature is not a reliable connection for a manufacturing part. Inspect
+the result when thin walls, tangencies, or disconnected components are possible.
+
+## Valid solid does not mean manufacturable part
+
+The kernel can enforce solid topology, but it does not know your printer, material, load case,
+tolerance stack, minimum wall, overhang strategy, or fit target. Encode supported input limits and
+cross-field errors in the Project, then verify the exported file in its downstream tool.
+
+Likewise, an empty or zero-volume result is invalid model output, but a non-empty result is not an
+engineering certification.
+
+## Geometry ownership
+
+Geometry values allocate resources outside ordinary JavaScript objects. Studio's evaluator owns
+those resources for each run and cleans them up deterministically. Authored code should never
+initialize the kernel or manually delete a `Section` or `Solid`.
+
+Use `inspectSection()` or `inspectSolid()` when you need supported measurements such as bounds,
+area, volume, or part counts. Return an array of `part(...)` declarations to hand the final result
+back to Studio for preview and export.
+
+
+
+**Use the MetaMesh reference for authored code**
+
+The upstream Manifold documentation is useful background on the underlying mathematics. Exact
+  code-Project symbols and guarantees come from the [Geometry API reference](../reference/model.md).
+
+
+
+- [Try geometry recipes](recipes.md)
+- [Read the Project contract](generation.md)