@metamesh/modeling 0.12.0 → 0.14.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: Vector2Tuple;
+  /** Inclusive minimum X/Y coordinates. */
+  readonly min: Vector2Tuple;
+}
+
+/** 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 Vector2Tuple = 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,300 @@
+# 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
+values in 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       |
+
+Construct immutable shapes, vectors, and transforms in ordinary TypeScript and reuse them in
+synchronous generation. A host evaluates geometry and owns observations and export. 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.
+- `PolygonData` contains one outer contour and its holes. `RegionData` is the plain serialized
+  representation of filled 2D geometry, including disconnected polygons.
+- 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 immutable arithmetic values created by `vector2` and `vector3`.
+- `Vector2Tuple` and `Vector3Tuple` are fixed numeric tuples for coordinate interchange and kernels.
+- `Bounds2` and `Bounds3` contain finite minimum and maximum tuples for measurements and placement.
+
+`Section` and `Solid` are opaque immutable recipes. Construction and composition need no engine;
+ordinary recipes can be reused across sessions regardless of where they were constructed.
+Explicitly supplied resolution settings are captured; unspecified settings inherit the evaluating
+host's defaults. The host owns evaluation caches and native kernel values. `components()` is an
+observation: its selected shapes, and recipes using them, can only be evaluated in the originating
+session because component identity depends on evaluated topology.
+
+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. Use `polygon({ polygons: data })` for existing `RegionData`.
+Every form returns the same `Section` type as `circle` or `rectangle`; subsequent Booleans may
+produce holes or disconnected components. `section.toRegionData()` observes the evaluated shape
+inside synchronous generation. Keep serialized point data for interchange or pure preparation.
+
+`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.
+Pure [`rotate2`](../reference/geometry/rotate2.md) and transform-chain rotations also take degrees.
+The low-level [`rotationTransform3`](../reference/geometry/rotationTransform3.md) constructor
+requires an explicit `{ degrees }` or `{ radians }` angle.
+
+`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.
+
+## Reuse a transform across shapes and coordinates
+
+Use [`transform2`](../reference/geometry/transform2.md) and
+[`transform3`](../reference/geometry/transform3.md) chains for reusable placements. They are immutable
+and pure; no engine initialization is needed. Calls apply in written order. A rotation followed
+by a translation rotates around the origin, then moves the result:
+
+
+
+```ts
+import { transform3, vector3 } from "@metamesh/modeling";
+
+// Calls apply in written order: rotate, then translate.
+const placement = transform3().rotate([0, 0, 90]).translate([20, 0, 5]);
+export const placedPoint = placement.applyPoint([10, 0, 0]); // approximately [20, 10, 5]
+export const placedDirection = placement.applyDirection([10, 0, 0]); // approximately [0, 10, 0]
+```
+
+
+
+Pass a transform directly to `solid.transform(placement)`, `section.transform(placement)` and
+matching path helpers. `toMatrix()` supplies a canonical matrix when another system needs it.
+Construct the placement once and reuse it across point collections.
+
+`current.andThen(next)` applies `current` first and `next` second, accepting another chain or a
+same-dimensional matrix. `inverse()` returns the reverse placement. Transform-building operations
+return new chains, so shared placements can branch safely.
+
+Use `rotate(degrees, { pivot })` or `scale(factors, { pivot })` to work around a world-space pivot after
+the preceding operations. In 3D, `rotate` takes XYZ Euler degrees, applied about global X, Y, then
+Z; `rotateAxis(axis, degrees, { pivot })` normalizes its nonzero axis. Omitted pivots use the
+coordinate origin. Uniform and per-axis scales
+must be finite and nonzero; negative factors reflect. Nonfinite inputs, invalid axes, and singular
+matrices throw `GeometryError`.
+
+`applyPoint` includes translation. `applyDirection` excludes translation and preserves scale;
+its result is not normalized. `applyNormal` applies the inverse transpose and returns a unit normal,
+including under nonuniform scaling; it rejects zero normals. All three return fluent vectors.
+
+`Transform2` works directly with Sections and pure XY helpers; its `Transform2Matrix` is the same
+canonical 3x3 representation throughout. Use `to3D()` when that XY placement
+also needs to position a Solid or 3D path. The reverse `to2D()` conversion rejects transforms
+that move the XY plane or collapse its dimensions; it does not project 3D points.
+See the [2D placement recipe](recipes.md#reuse-a-2d-placement).
+
+For low-level matrix interoperability, the factories accept existing canonical matrices. Use
+`transform3(frameTransform3(frame))` for an orthonormal frame. The raw constructors and
+`composeTransform3(after, before)` remain available; composition applies `before` first.
+
+## Calculate with vectors
+
+Use [`vector2`](../reference/geometry/vector2.md) and [`vector3`](../reference/geometry/vector3.md)
+for readable arithmetic chains. Operands accept tuples or vectors; `dot`, `length` and `distance`
+return numbers. `cross` returns a signed scalar in 2D and a right-handed vector in 3D.
+
+
+
+```ts
+export const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+export const alignment = direction.dot([0, 0, 1]); // number
+```
+
+
+
+Values snapshot their input and operations return new values. `toArray()` returns the value's
+frozen coordinate tuple without allocating another copy. Normalization rejects zero-length vectors;
+nonfinite coordinates, scalar parameters and overflowing results throw `GeometryError`.
+
+For rotations and nonuniform scaling, use a reusable transform's `applyDirection`. Use
+`applyNormal` for surface normals:
+
+
+
+```ts
+const stretched = transform3().scale([2, 1, 1]);
+export const normal = stretched.applyNormal([1, 1, 0]);
+export const tangent = stretched.applyDirection([1, -1, 0]);
+export const perpendicular = normal.dot(tangent); // approximately 0
+```
+
+
+
+The tuple arithmetic kernels remain available for dense numerical loops. Fluent values add
+validation and immutable object allocation; they are an authoring convenience, not a speedup.
+Fluent math, shape transforms and part placement accept vector values directly; geometry
+specifications and point collections use canonical tuples.
+Keep simple coordinate expressions and equations intrinsic to the model beside the model.
+
+## 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
+horizontal lines, spacing, and alignment, or a single circular baseline through
+[`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). 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.
+
+Observations, including `section.toRegionData()`, require the host's active synchronous generation.
+Constructing or composing a recipe outside generation does not evaluate it.
+
+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,59 @@
+# 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.
+
+For a static face whose actual weight is not 400, pass that weight through `staticWeight` when
+preparing it. This identifies the supplied face; it does not synthesize another weight.
+
+## 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`.
+
+The same layout options support horizontal lines or one circular line through
+[`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). The
+[text recipe](recipes.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 the host lifecycle.