@metamesh/modeling 0.19.0 → 0.20.0

package/dist/api/text.d.ts

@@ -1,10 +1,9 @@
-/** Plain axis-aligned XY bounds for interchange; use bounds2 for immutable measurement methods. */
-export declare interface Bounds2Data {
-  /** Inclusive maximum X/Y coordinates. */
-  readonly max: Vector2Data;
-  /** Inclusive minimum X/Y coordinates. */
-  readonly min: Vector2Data;
-}
+import type {
+  Bounds2Data,
+  Vector2Data,
+  VectorTextLayout,
+  VectorTextMetrics,
+} from "@metamesh/modeling/geometry";
 
 /** Maximum input font size in bytes, checked before parsing or shaping untrusted font data. */
 export declare const MAX_VECTOR_FONT_BYTES: number;
@@ -13,6 +12,8 @@ export declare const MAX_VECTOR_FONT_BYTES: number;
  * Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
  * Argument and resource failures use GeometryError; parser and decoder exceptions propagate unchanged.
  *
+ * @param bytes - Non-empty font bytes, at most 16 MiB; copied before parsing.
+ *
  * @example Prepare a label before building geometry
  * ```ts
  * async function prepareLabel(fontBytes: Uint8Array) {
@@ -26,25 +27,34 @@ export declare function prepareVectorFont(
   options?: VectorFontOptions,
 ): Promise<VectorFont>;
 
-/** A two-dimensional Cartesian vector or point. */
-export declare type Vector2Data = readonly [x: number, y: number];
-
 /**
  * A prepared font owns its parsed bytes; keep handles local to their Worker or invocation.
  * Invalid arguments and bounded-work failures use GeometryError; unexpected dependency errors propagate.
  */
 export declare interface VectorFont {
-  /** Shape horizontal lines or one circular line; bounded to 512 UTF-16 units and supports blank text. */
+  /**
+   * Shape horizontal lines or one circular line, including blank text.
+   *
+   * @param text - Up to 512 UTF-16 code units, across at most 16 lines.
+   */
   readonly layout: (
     text: string,
     options: VectorTextLayoutOptions,
   ) => VectorTextLayout;
-  /** Measure the same cached vector layout; all returned lengths are in millimetres. */
+  /**
+   * Measure the same cached vector layout; all returned lengths are in millimetres.
+   *
+   * @param text - Same limits as {@link VectorFont.layout}.
+   */
   readonly measure: (
     text: string,
     options: VectorTextLayoutOptions,
   ) => VectorTextMetrics;
-  /** Serialize visible horizontal or circular outlines as bounded path-only SVG in physical millimetres. */
+  /**
+   * Serialize visible horizontal or circular outlines as path-only SVG in millimetres, bounded to 256 KiB.
+   *
+   * @param text - Same limits as {@link VectorFont.layout}; blank outlines are rejected.
+   */
   readonly toSvg: (text: string, options: VectorTextLayoutOptions) => string;
 }
 
@@ -66,19 +76,7 @@ export declare interface VectorTextArcBaseline {
   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.
- */
+/** 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";
@@ -90,24 +88,6 @@ export declare interface VectorTextLayoutOptions extends VectorTextOptions {
   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: Bounds2Data | 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. */

package/dist/docs/guides/concepts.md

@@ -1,44 +1,78 @@
-# Geometry API concepts
+# Choose imports and execution
 
-Choose geometry representations and modules, then find the conventions and host setup for your model.
+Find the right Modeling module and understand which operations need a host engine.
 
-Modeling separates the shape you describe from the host that evaluates it. Build immutable
-Sections and Solids for material, use pure geometry values for calculations, and let Studio or
-your standalone engine produce the finished result.
+Use the root Modeling module to build shapes, then reach for a focused geometry module when you
+need calculations, custom boundaries, or mesh buffers.
 
-## Choose the representation
 
-| You need                                               | Use                              |
-| ------------------------------------------------------ | -------------------------------- |
-| Filled material for Booleans, extrusion, or revolution | A `Section` or `Solid`           |
-| Sampled coordinates and traversal queries              | A `Path2`, `Path3`, or `Contour` |
-| Matching landmarks across cross sections               | An identified `Profile` family   |
-| Triangle buffers for a renderer or mesh algorithm      | A `TriangleMesh`                 |
 
-[Geometry values and representations](geometry-values.md) explains these choices,
-plain interchange data, and conversion between them. [Placement](transforms-and-placement.md)
-covers vectors, transforms, anchors, patterns, and bounds. [Resolution and inspection](resolution-and-inspection.md)
-explains sampling, preflight guarantees, and evaluated measurements.
+**Build a recipe, then choose its host**
 
-## Choose the module
+The same shapes work in Studio, the CLI, and your application. Modeling describes the material;
+  the host evaluates it and delivers the result.
 
-- [`@metamesh/modeling`](../reference/model.md): shapes, Booleans, construction, and generation programs.
-- [`@metamesh/modeling/geometry`](../reference/geometry.md): pure paths, profiles, transforms, and calculations.
-- [`@metamesh/modeling/geometry/mesh`](../reference/mesh.md): triangle mesh construction, processing, and inspection.
-- [`@metamesh/modeling/engine`](../reference/engine.md): standalone execution and finalization.
-- [`@metamesh/modeling/export`](../reference/export.md): renderer-independent STL, 3MF, and GLB export.
-- [`@metamesh/modeling/text`](../reference/text.md): exact font preparation and vector layouts.
 
-Constructing and combining ordinary recipes doesn't need an engine. Geometry observations run
-inside synchronous generation. The host owns evaluation, prepared services, and native resources;
-[inspect the result](resolution-and-inspection.md#lifecycle-and-inspection) before relying
-on its dimensions.
 
-## Choose where to run
+## Import by the work you are doing
 
-- **Studio:** follow the [code Project path](https://metamesh.studio/docs/develop#follow-the-studio-path). Studio supplies
-  controls, prepared services, preview, and export.
-- **Locally:** follow the [standalone path](https://metamesh.studio/docs/engine#follow-the-standalone-path). The CLI or
-  your application supplies the host.
+| Your task                                        | Import                                                                 | What it provides                                                        |
+| ------------------------------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Build a part                                     | [`@metamesh/modeling`](../reference/model.md)                          | Sections, Solids, construction, Booleans, and generation                |
+| Calculate geometry or placement                  | [`@metamesh/modeling/geometry`](../reference/geometry.md)              | Fluent vectors, bounds, transforms, frames, paths, profiles, and layout |
+| Work directly with coordinate tuples or matrices | [`@metamesh/modeling/geometry/math`](../reference/math.md)             | Numerical kernels for data processing and interoperability              |
+| Design a mechanical feature                      | [`@metamesh/modeling/geometry/mechanical`](../reference/mechanical.md) | Gear and thread calculations, fit, standards, and mechanical preflight  |
+| Construct or inspect triangle buffers            | [`@metamesh/modeling/geometry/mesh`](../reference/mesh.md)             | Pure mesh construction, processing, and analysis                        |
 
-When you're ready to shape a part, choose a [worked modeling technique](recipes.md).
+Start with shapes and fluent values for ordinary model authoring. Import tuple arithmetic only
+when your calculation needs it; there is no need to turn every coordinate into a fluent value.
+Mechanical helpers resolve dimensions and geometry; root factories such as `threadedRod` create
+Solid recipes from mechanical options.
+
+The [values guide](geometry-values.md) explains how these representations fit together.
+Each public function and type has one import home, shown on its API reference page. Shared
+options can belong to a different module from the operation that consumes them: `BoxOptions`
+comes from the root, `GridPatternOptions` from `/geometry`, and `ThreadedRodOptions` from
+`/geometry/mechanical`. Recipe constructors and pure helpers reuse those shared contracts.
+
+## Describing a shape does not evaluate it
+
+Factories such as `box` and `rectangle`, Boolean methods, and transforms create immutable recipes.
+You can declare them before an engine exists and reuse ordinary recipes across runs. Changing a
+recipe produces a new value; it leaves the original available for reuse.
+
+Pure geometry calculations also run without an engine. This includes vector arithmetic, path
+queries, profile matching, mechanical calculations, and functions in the mesh module.
+`mesh.extrude(...)` creates triangle buffers directly; `section.extrude(...)` describes a Solid
+that the host will evaluate.
+
+Operations that **observe a shape** need active synchronous generation:
+
+- `shape.inspect()` measures evaluated material.
+- `shape.anchor(name)` and `shape.components()` resolve evaluated placement or topology.
+- `solid.toMesh()` and `section.toRegionData()` extract evaluated geometry.
+
+The host owns native resources and cleanup. Don't initialize a kernel or delete individual shapes
+inside a model. Read [resolution and inspection](resolution-and-inspection.md) for
+measurement, session ownership, and preflight guarantees.
+
+## Choose the host once
+
+| You are building                         | Start here                                         | Who runs the model?                                                          |
+| ---------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------- |
+| A model with editable controls in Studio | [First code Project](https://metamesh.studio/docs/develop/code-projects)  | Studio supplies `@metamesh/project`, controls, services, preview, and export |
+| A local TypeScript model                 | [Standalone model](standalone-model.md) | The CLI checks, runs, and inspects your model                                |
+| An application that hosts models         | [Engine hosting](hosting.md)             | Your application initializes the engine and owns sessions and delivery       |
+
+The geometry operations stay the same across hosts. Setup and generation imports differ, so use
+the entry point shown by the workflow you chose. Projects in Studio do not install npm packages.
+
+Standalone hosts use [`@metamesh/modeling/engine`](../reference/engine.md) for execution,
+[`@metamesh/modeling/export`](../reference/export.md) for STL, 3MF, or GLB serialization, and
+optionally [`@metamesh/modeling/text`](../reference/text.md) to prepare exact fonts. The
+[hosting guide](hosting.md) owns installation and lifecycle setup.
+
+## Build a visible result
+
+Continue with [modeling fundamentals](fundamentals.md) to combine your first
+solids, or choose a [worked technique](recipes.md) for the part you want to make.

package/dist/docs/guides/exporting.md

@@ -0,0 +1,88 @@
+# Export completed parts
+
+Serialize one completed result as 3MF, STL, or GLB, preserving its placement and reporting format limitations.
+
+Use `@metamesh/modeling/export` when your application has completed part geometry to save or deliver.
+Start with [a working host](hosting.md#build-and-export-a-plate) if you have not generated
+a result yet. For Studio's download interface, use [Export a model](https://metamesh.studio/docs/use/export-3mf).
+
+
+
+**Export works from the completed result**
+
+No running engine or renderer is needed. Serialize `model.parts`, including after its session
+  closes, without evaluating the source again.
+
+
+
+## Serialize completed parts
+
+Import `export3mf`, `exportStl`, or `exportGlb` from `@metamesh/modeling/export`. Every exporter accepts completed parts with local
+`geometry`, an optional placement transform, and optional display color and material identity.
+
+This helper accepts a completed engine result and requests solid-mesh validation before writing 3MF:
+
+
+
+```ts
+import type { ModelResult } from "@metamesh/modeling/engine";
+import { export3mf, type ExportedFile } from "@metamesh/modeling/export";
+
+export function exportAssembly(model: ModelResult): Promise<ExportedFile> {
+  return export3mf(model.parts, { name: "Assembly", meshValidation: "solid" });
+}
+```
+
+
+
+Call `await exportAssembly(model)` and save or download its returned `bytes`. Review `diagnostics`
+for expected format losses; invalid inputs and failed delivery reject.
+
+The result contains `bytes: Uint8Array`, `mediaType`, `extension`, `byteLength`, and structured
+`diagnostics`. The host chooses the filename and saves or downloads the bytes. Resolve selected
+parts and appearance overrides before exporting so the file belongs to one captured revision.
+
+## Choose a format
+
+Inputs use millimetres and Z-up coordinates. Every writer preserves the supplied physical sampling.
+
+| Format  | Coordinates                     | What it preserves                                                                      |
+| ------- | ------------------------------- | -------------------------------------------------------------------------------------- |
+| **3MF** | Millimetres, Z-up               | Named manufacturing parts, placement, colors, and explicit material identities         |
+| **STL** | Placed triangles in millimetres | Triangle geometry; diagnostics report lost names, appearance, and material assignments |
+| **GLB** | Metres, Y-up                    | Named display parts, shared geometry, placement, colors, and crease-aware shading      |
+
+## Keep color and material identity separate
+
+Use explicit `materialId` values with `options.materials` when material identity matters. Two
+materials may share the same RGB value and remain distinct. Per-part display color overrides do
+not change the selected material identity. 3MF carries portable material names and standard
+Materials-extension color groups separately; assigned parts combine those properties with
+`multiproperties`. Slicer support for those properties varies. Full slicer projects and device-specific
+configuration require a separate application adapter.
+
+
+
+**Portable materials describe intent**
+
+A material ID and display color travel with supported output. Your downstream application still
+  chooses printer profiles, filament slots, and device settings.
+
+
+
+## Set validation and output limits
+
+Exports have their own input and output ceilings through `options.limits`; they do not inherit an
+engine's policy. `meshValidation: "solid"` requests the bounded geometric checks in addition to
+the format's structural requirements. Pass an `AbortSignal` to cancel bounded work.
+
+## Stream large output
+
+For large output, `write3mf(parts, sink, options)`, `writeStl`, and `writeGlb` await each sink write
+before continuing and return metadata and diagnostics without collecting the complete output.
+Browser applications own Worker execution; an async function alone does not move CPU work off
+the UI thread.
+
+Use the [Export API reference](../reference/export.md) for serialization options,
+the [Engine API reference](../reference/engine.md) for execution, and
+[Modeling guides](https://metamesh.studio/docs/modeling) to choose geometry operations.

package/dist/docs/guides/fonts.md

@@ -27,7 +27,8 @@ another weight.
 
 
 ```ts
-import { prepareVectorFont, type VectorTextLayout } from "@metamesh/modeling/text";
+import { type VectorTextLayout } from "@metamesh/modeling/geometry";
+import { prepareVectorFont } from "@metamesh/modeling/text";
 
 export async function makeLabelLayout(fontBytes: Uint8Array): Promise<{
   readonly layout: VectorTextLayout;
@@ -53,9 +54,10 @@ extrude the filled section. Prepare layouts ahead of time, or supply a determini
 and cache layouts with `memo`.
 
 The same layout options support horizontal lines or one circular line through
-[`VectorTextArcBaseline`](../reference/geometry/VectorTextArcBaseline.md). The
+[`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). The
 [text recipe](svg-and-text.md#text-from-a-font-parameter) explains units, alignment,
 metrics, and circular-text constraints.
 
 Use the [Font preparation reference](../reference/text.md) for font and layout options, or
-[Run Modeling in your application](hosting.md) for engine setup, export, and cleanup.
+[Run Modeling in your application](hosting.md) for execution and cleanup, and
+[Export completed parts](exporting.md) for file delivery.

package/dist/docs/guides/fundamentals.md

@@ -33,7 +33,7 @@ export default generate(({ part }) => {
   // 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))];
+  return part("model", plate.subtract(hole));
 });
 ```
 
@@ -65,7 +65,8 @@ the final translations separate the results for comparison.
 
 
 ```ts
-import { box, cylinder, transform3 } from "@metamesh/modeling";
+import { box, cylinder } from "@metamesh/modeling";
+import { transform3 } from "@metamesh/modeling/geometry";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
@@ -103,35 +104,22 @@ Use intentional overlap for joined features and overtravel for through-cutters.
 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 doesn't 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.
-
-Empty or zero-volume output is invalid; non-empty output still needs engineering checks.
-
-## Geometry ownership
-
-Studio creates and cleans up the native resources needed to evaluate your `Section` and `Solid`
-recipes. Don't initialize the kernel or manually delete shapes in `model.ts`.
-
-Use `shape.inspect()` for measurements such as bounds, area, volume, and
-`componentCount`. `shape.components()` returns disconnected material pieces, preserving holes and
-enclosed cavities. A sealed hollow box is one component; adding a loose ball inside its cavity
-makes two. Recombining the pieces preserves the original material.
 
-Snapshot `stats.partCount` counts named `part(...)` declarations; one part may contain several
-material components. Return one declaration or an array for Studio to preview and export.
 
+**A valid solid still needs engineering checks**
 
+Closed geometry does not establish fit, wall thickness, strength, or printability. Validate your
+  supported dimensions and check the result with your intended material and manufacturing process.
 
-**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 [Model API reference](../reference/model.md).
 
+## Let the host manage geometry
 
+Studio and standalone hosts evaluate the recipes and clean up native resources. Keep kernel
+initialization and manual deletion out of your model. Use
+[inspection](resolution-and-inspection.md#lifecycle-and-inspection) to check evaluated
+dimensions and components; use the [Model API reference](../reference/model.md) for exact symbols.
+The upstream Manifold documentation provides background on the underlying mathematics.
 
 - [Try geometry recipes](recipes.md)
 - [Read the Project contract](generation.md)

package/dist/docs/guides/generation.md

@@ -7,10 +7,13 @@ Studio compiles it, prepares services, runs the modeling engine, saves the Proje
 
 ## Source boundary
 
-Keep helpers in the single editable `model.ts` file. Import modeling operations from
-`@metamesh/modeling`, pure utilities from `@metamesh/modeling/geometry`, mesh operations from
-`@metamesh/modeling/geometry/mesh`, and the typed
-`generate` helper from `@metamesh/project`. These approved modules and declarations work offline.
+Keep helpers in the single editable `model.ts` file. Import shapes from `@metamesh/modeling` and
+the typed `generate` helper from `@metamesh/project`. The Geometry, Math, Mechanical, and Mesh
+modules in the [import map](concepts.md#import-by-the-work-you-are-doing) are
+also available.
+
+For font-selection metadata, import `isFontSelection` and `type FontSelection` from
+`@metamesh/generator-sdk/fonts`. These approved modules and declarations work offline.
 Source can't install packages, fetch modules, or initialize another kernel.
 
 ## Start with generate
@@ -23,8 +26,8 @@ Default-export one synchronous program:
 import { box } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
-export default generate(({ params: parameters, part }) => {
-  return part("model", box({ size: [parameters.width, parameters.depth, parameters.height] }));
+export default generate(({ params, part }) => {
+  return part("model", box({ size: [params.width, params.depth, params.height] }));
 });
 ```
 
@@ -68,7 +71,7 @@ evaluates. Pass the full generation context to a helper that needs `assert` or f
 
 
 
-**Caching is optional**
+**Start without caching**
 
 Start with ordinary generation code. If parameter edits become slow, add `memo` around expensive
   work that can stay unchanged across edits. Cheap arithmetic and part placement usually do not need
@@ -153,9 +156,14 @@ Raw typed arrays in memo results or arguments reject with guidance to use these
 
 ## Text services
 
-Studio prepares the exact selected font bytes before passing `services` to the callback.
-Call `services.text.layout()` synchronously, check its metrics, then pass the layout to
-`textSection(layout)`. Generation itself does no networking:
+
+
+**Studio prepares the selected font for you**
+
+The exact font bytes are ready before `generate` runs. Lay out text synchronously through
+  `services.text.layout()`, check its metrics, and pass the layout to `textSection`.
+
+
 
 
 
@@ -171,7 +179,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 }));
 });
 ```
 
@@ -186,14 +194,14 @@ Geometry and placement accept values. Give each part a stable ID:
 
 
 ```ts
-export default generate(({ params: parameters, part }) => {
-  const base = box({ size: [parameters.width, parameters.depth, parameters.height] });
-  const lid = box({ size: [parameters.width, parameters.depth, 2] });
+export default generate(({ params, part }) => {
+  const base = box({ size: [params.width, params.depth, params.height] });
+  const lid = box({ size: [params.width, params.depth, 2] });
   return [
     part("base", { geometry: base, color: "#3b82f6" }),
     part("lid", {
       geometry: lid,
-      transform: transform3().translate([0, parameters.depth + 4, 0]),
+      transform: transform3().translate([0, params.depth + 4, 0]),
       color: "#f59e0b",
     }),
   ];
@@ -202,7 +210,7 @@ export default generate(({ params: parameters, part }) => {
 
 
 
-Use a `transform3()` value or a row-major 16-number matrix for translation and rotation;
+Use a plain `Frame3`, `transform3()` value, or row-major 16-number matrix for translation and rotation;
 omitting it means identity placement. Scale, shear, reflection and perspective are rejected.
 Pattern and attachment transforms pass directly to this option.
 Lengths use millimetres and fluent rotations use degrees. Coordinates are right-handed with **+Z up**.