@metamesh/modeling 0.11.0 → 0.13.0

package/dist/docs/reference/text/VectorFont.md

@@ -0,0 +1,186 @@
+# VectorFont
+
+A prepared font owns its parsed bytes; keep handles local to their Worker or invocation.
+
+## Properties
+
+### layout
+
+
+
+`readonly` **layout**: (`text`: `string`, `options`: [`VectorTextLayoutOptions`](VectorTextLayoutOptions.md)) => [`VectorTextLayout`](VectorTextLayout.md)
+
+
+
+Shape horizontal lines or one circular line; bounded to 512 UTF-16 units and supports blank text.
+
+#### Parameters
+
+<a id="text"></a>
+
+**`text`** · `string` · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`VectorTextLayoutOptions`](VectorTextLayoutOptions.md) · Required
+
+- [`fontSize`](VectorTextLayoutOptions.md#fontsize) · `number` · Required
+
+  Em size in millimetres, greater than zero and at most 10000; not the visible glyph height.
+
+- [`align`](VectorTextLayoutOptions.md#align) · `"left"` \| `"right"` \| `"center"` · Optional
+
+  Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left.
+
+- [`baseline`](VectorTextLayoutOptions.md#baseline) · [`VectorTextArcBaseline`](VectorTextArcBaseline.md) · Optional
+
+  Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment.
+
+- [`lineHeight`](VectorTextLayoutOptions.md#lineheight) · `number` · Optional
+
+  Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics.
+
+- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"top"` \| `"bottom"` \| `"center"` \| `"baseline"` · Optional
+
+  Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline.
+
+- [`fontWeight`](VectorTextLayoutOptions.md#fontweight) · `number` · Optional
+
+  Actual static or variable weight, 1–1000; defaults to the prepared face's static weight.
+
+- [`letterSpacing`](VectorTextLayoutOptions.md#letterspacing) · `number` · Optional
+
+  Tracking between glyph clusters in millimetres, -100–100; defaults to zero.
+
+
+
+#### Returns
+
+[`VectorTextLayout`](VectorTextLayout.md)
+
+***
+
+### measure
+
+
+
+`readonly` **measure**: (`text`: `string`, `options`: [`VectorTextLayoutOptions`](VectorTextLayoutOptions.md)) => [`VectorTextMetrics`](VectorTextMetrics.md)
+
+
+
+Measure the same cached vector layout; all returned lengths are in millimetres.
+
+#### Parameters
+
+<a id="text-1"></a>
+
+**`text`** · `string` · Required
+
+
+
+<a id="options-1"></a>
+
+**`options`** · [`VectorTextLayoutOptions`](VectorTextLayoutOptions.md) · Required
+
+- [`fontSize`](VectorTextLayoutOptions.md#fontsize) · `number` · Required
+
+  Em size in millimetres, greater than zero and at most 10000; not the visible glyph height.
+
+- [`align`](VectorTextLayoutOptions.md#align) · `"left"` \| `"right"` \| `"center"` · Optional
+
+  Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left.
+
+- [`baseline`](VectorTextLayoutOptions.md#baseline) · [`VectorTextArcBaseline`](VectorTextArcBaseline.md) · Optional
+
+  Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment.
+
+- [`lineHeight`](VectorTextLayoutOptions.md#lineheight) · `number` · Optional
+
+  Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics.
+
+- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"top"` \| `"bottom"` \| `"center"` \| `"baseline"` · Optional
+
+  Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline.
+
+- [`fontWeight`](VectorTextLayoutOptions.md#fontweight) · `number` · Optional
+
+  Actual static or variable weight, 1–1000; defaults to the prepared face's static weight.
+
+- [`letterSpacing`](VectorTextLayoutOptions.md#letterspacing) · `number` · Optional
+
+  Tracking between glyph clusters in millimetres, -100–100; defaults to zero.
+
+
+
+#### Returns
+
+[`VectorTextMetrics`](VectorTextMetrics.md)
+
+***
+
+### toSvg
+
+
+
+`readonly` **toSvg**: (`text`: `string`, `options`: [`VectorTextLayoutOptions`](VectorTextLayoutOptions.md)) => `string`
+
+
+
+Serialize visible horizontal or circular outlines as bounded path-only SVG in physical millimetres.
+
+#### Parameters
+
+<a id="text-2"></a>
+
+**`text`** · `string` · Required
+
+
+
+<a id="options-2"></a>
+
+**`options`** · [`VectorTextLayoutOptions`](VectorTextLayoutOptions.md) · Required
+
+- [`fontSize`](VectorTextLayoutOptions.md#fontsize) · `number` · Required
+
+  Em size in millimetres, greater than zero and at most 10000; not the visible glyph height.
+
+- [`align`](VectorTextLayoutOptions.md#align) · `"left"` \| `"right"` \| `"center"` · Optional
+
+  Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left.
+
+- [`baseline`](VectorTextLayoutOptions.md#baseline) · [`VectorTextArcBaseline`](VectorTextArcBaseline.md) · Optional
+
+  Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment.
+
+- [`lineHeight`](VectorTextLayoutOptions.md#lineheight) · `number` · Optional
+
+  Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics.
+
+- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"top"` \| `"bottom"` \| `"center"` \| `"baseline"` · Optional
+
+  Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline.
+
+- [`fontWeight`](VectorTextLayoutOptions.md#fontweight) · `number` · Optional
+
+  Actual static or variable weight, 1–1000; defaults to the prepared face's static weight.
+
+- [`letterSpacing`](VectorTextLayoutOptions.md#letterspacing) · `number` · Optional
+
+  Tracking between glyph clusters in millimetres, -100–100; defaults to zero.
+
+
+
+#### Returns
+
+`string`
+
+
+## Related APIs
+
+- [VectorTextLayout](VectorTextLayout.md)
+- [VectorTextLayoutOptions](VectorTextLayoutOptions.md)
+- [VectorTextMetrics](VectorTextMetrics.md)
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/VectorFontOptions.md

@@ -0,0 +1,17 @@
+# VectorFontOptions
+
+Identifies the actual weight of a static face, without synthesizing a different weight.
+
+## Properties
+
+### staticWeight?
+
+
+
+`readonly` `optional` **staticWeight?**: `number`
+
+
+
+Actual weight of a static face, 1–1000; defaults to 400.
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/VectorTextArcBaseline.md

@@ -0,0 +1,53 @@
+# VectorTextArcBaseline
+
+A circular baseline centered at the XY origin, with rigid shaped glyph groups.
+
+## Properties
+
+### kind
+
+
+
+`readonly` **kind**: `"arc"`
+
+
+
+Selects a circular baseline; glyph outlines rotate without bending or stretching.
+
+***
+
+### radius
+
+
+
+`readonly` **radius**: `number`
+
+
+
+Baseline radius in millimetres, greater than zero and at most 10000.
+
+***
+
+### centerAngleDegrees?
+
+
+
+`readonly` `optional` **centerAngleDegrees?**: `number`
+
+
+
+Alignment datum in degrees counterclockwise from +X; defaults to 90.
+
+***
+
+### direction?
+
+
+
+`readonly` `optional` **direction?**: `"clockwise"` \| `"counterclockwise"`
+
+
+
+Reading direction around the circle; defaults to clockwise.
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/VectorTextLayout.md

@@ -0,0 +1,34 @@
+# VectorTextLayout
+
+Immutable vector layout with no browser, font parser, or kernel ownership.
+
+## Properties
+
+### paths
+
+
+
+`readonly` **paths**: readonly `string`[]
+
+
+
+Nonzero-filled path data in millimetres, positive Y upward; empty for text with no ink.
+
+***
+
+### metrics
+
+
+
+`readonly` **metrics**: [`VectorTextMetrics`](VectorTextMetrics.md)
+
+
+
+Exact measurements of these paths and their logical text layout.
+
+
+## Related APIs
+
+- [VectorTextMetrics](VectorTextMetrics.md)
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/VectorTextLayoutOptions.md

@@ -0,0 +1,111 @@
+# VectorTextLayoutOptions
+
+Text bounded to 512 UTF-16 units: horizontal lines or one circular line without wrapping.
+
+## Extends
+
+- [`VectorTextOptions`](VectorTextOptions.md)
+
+## Properties
+
+### align?
+
+
+
+`readonly` `optional` **align?**: `"left"` \| `"right"` \| `"center"`
+
+
+
+Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left.
+
+***
+
+### baseline?
+
+
+
+`readonly` `optional` **baseline?**: [`VectorTextArcBaseline`](VectorTextArcBaseline.md)
+
+
+
+Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment.
+
+***
+
+### lineHeight?
+
+
+
+`readonly` `optional` **lineHeight?**: `number`
+
+
+
+Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics.
+
+***
+
+### verticalAlign?
+
+
+
+`readonly` `optional` **verticalAlign?**: `"top"` \| `"bottom"` \| `"center"` \| `"baseline"`
+
+
+
+Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline.
+
+***
+
+### fontSize
+
+
+
+`readonly` **fontSize**: `number`
+
+
+
+Em size in millimetres, greater than zero and at most 10000; not the visible glyph height.
+
+#### Inherited from
+
+[`VectorTextOptions`](VectorTextOptions.md).[`fontSize`](VectorTextOptions.md#fontsize)
+
+***
+
+### fontWeight?
+
+
+
+`readonly` `optional` **fontWeight?**: `number`
+
+
+
+Actual static or variable weight, 1–1000; defaults to the prepared face's static weight.
+
+#### Inherited from
+
+[`VectorTextOptions`](VectorTextOptions.md).[`fontWeight`](VectorTextOptions.md#fontweight)
+
+***
+
+### letterSpacing?
+
+
+
+`readonly` `optional` **letterSpacing?**: `number`
+
+
+
+Tracking between glyph clusters in millimetres, -100–100; defaults to zero.
+
+#### Inherited from
+
+[`VectorTextOptions`](VectorTextOptions.md).[`letterSpacing`](VectorTextOptions.md#letterspacing)
+
+
+## Related APIs
+
+- [VectorTextArcBaseline](VectorTextArcBaseline.md)
+- [VectorTextOptions](VectorTextOptions.md)
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/VectorTextMetrics.md

@@ -0,0 +1,94 @@
+# VectorTextMetrics
+
+Text measurements from the same immutable layout that supplies geometry and SVG outlines.
+
+## Properties
+
+### bounds
+
+
+
+`readonly` **bounds**: [`Bounds2`](Bounds2.md) \| `null`
+
+
+
+Visible curve bounds after alignment, or null when the text has no ink.
+
+***
+
+### advance
+
+
+
+`readonly` **advance**: readonly \[`number`, `number`\]
+
+
+
+Unaligned logical advance and negative baseline displacement in mm; arcs retain [arc length, 0].
+
+***
+
+### logicalWidth
+
+
+
+`readonly` **logicalWidth**: `number`
+
+
+
+Maximum logical line advance in millimetres, including spaces; arc length on circular baselines.
+
+***
+
+### ascent
+
+
+
+`readonly` **ascent**: `number`
+
+
+
+Selected font's ascender distance above a baseline in millimetres, independent of the text.
+
+***
+
+### descent
+
+
+
+`readonly` **descent**: `number`
+
+
+
+Selected font's descender distance below a baseline in millimetres, a non-negative value.
+
+***
+
+### lineHeight
+
+
+
+`readonly` **lineHeight**: `number`
+
+
+
+Actual distance between baselines in millimetres.
+
+***
+
+### lineCount
+
+
+
+`readonly` **lineCount**: `number`
+
+
+
+Number of lines, including empty and trailing lines; empty text occupies one line.
+
+
+## Related APIs
+
+- [Bounds2](Bounds2.md)
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/VectorTextOptions.md

@@ -0,0 +1,50 @@
+# VectorTextOptions
+
+Shaping controls for a prepared exact font face; all lengths are in millimetres.
+
+## Extended by
+
+- [`VectorTextLayoutOptions`](VectorTextLayoutOptions.md)
+
+## Properties
+
+### fontSize
+
+
+
+`readonly` **fontSize**: `number`
+
+
+
+Em size in millimetres, greater than zero and at most 10000; not the visible glyph height.
+
+***
+
+### fontWeight?
+
+
+
+`readonly` `optional` **fontWeight?**: `number`
+
+
+
+Actual static or variable weight, 1–1000; defaults to the prepared face's static weight.
+
+***
+
+### letterSpacing?
+
+
+
+`readonly` `optional` **letterSpacing?**: `number`
+
+
+
+Tracking between glyph clusters in millimetres, -100–100; defaults to zero.
+
+
+## Related APIs
+
+- [VectorTextLayoutOptions](VectorTextLayoutOptions.md)
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/categories/font-preparation.md

@@ -0,0 +1,38 @@
+# Font preparation
+
+Prepare bounded exact font bytes and reusable vector layouts.
+
+Prepare fonts before modeling. TTF, OTF, and WOFF are parsed directly; WOFF2 decoding loads lazily. No fetching occurs in this library. Font layout returns immutable paths and metrics in Y-up millimetres. Pass that prepared layout to textSection inside a build; do not shape it again.
+
+## Functions
+
+| API | Summary |
+| --- | --- |
+| [prepareVectorFont](../prepareVectorFont.md) | Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here. |
+
+## Interfaces
+
+| API | Summary |
+| --- | --- |
+| [VectorFont](../VectorFont.md) | A prepared font owns its parsed bytes; keep handles local to their Worker or invocation. |
+| [VectorFontOptions](../VectorFontOptions.md) | Identifies the actual weight of a static face, without synthesizing a different weight. |
+| [VectorTextArcBaseline](../VectorTextArcBaseline.md) | A circular baseline centered at the XY origin, with rigid shaped glyph groups. |
+| [VectorTextLayout](../VectorTextLayout.md) | Immutable vector layout with no browser, font parser, or kernel ownership. |
+| [VectorTextLayoutOptions](../VectorTextLayoutOptions.md) | Text bounded to 512 UTF-16 units: horizontal lines or one circular line without wrapping. |
+| [VectorTextMetrics](../VectorTextMetrics.md) | Text measurements from the same immutable layout that supplies geometry and SVG outlines. |
+| [VectorTextOptions](../VectorTextOptions.md) | Shaping controls for a prepared exact font face; all lengths are in millimetres. |
+| [Bounds2](../Bounds2.md) | Axis-aligned bounds in two-dimensional model space. |
+
+## Type aliases
+
+| API | Summary |
+| --- | --- |
+| [Vector2](../Vector2.md) | A two-dimensional Cartesian vector or point. |
+
+## Values
+
+| API | Summary |
+| --- | --- |
+| [MAX_VECTOR_FONT_BYTES](../MAX_VECTOR_FONT_BYTES.md) | Limits apply before parsing or shaping untrusted font data. |
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/prepareVectorFont.md

@@ -0,0 +1,46 @@
+# prepareVectorFont
+
+Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
+
+**prepareVectorFont**(`bytes`: `Uint8Array`, `options?`: [`VectorFontOptions`](VectorFontOptions.md)): `Promise`\<[`VectorFont`](VectorFont.md)\>
+
+
+
+## Example: Prepare a label before building geometry
+
+```ts
+async function prepareLabel(fontBytes: Uint8Array) {
+  const font = await prepareVectorFont(fontBytes);
+  return font.layout("MetaMesh", { fontSize: 8 });
+}
+```
+
+## Parameters
+
+<a id="bytes"></a>
+
+**`bytes`** · `Uint8Array` · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`VectorFontOptions`](VectorFontOptions.md) · Optional
+
+- [`staticWeight`](VectorFontOptions.md#staticweight) · `number` · Optional
+
+  Actual weight of a static face, 1–1000; defaults to 400.
+
+
+
+## Returns
+
+`Promise`\<[`VectorFont`](VectorFont.md)\>
+
+
+## Related APIs
+
+- [VectorFont](VectorFont.md)
+- [VectorFontOptions](VectorFontOptions.md)
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text.md

@@ -0,0 +1,21 @@
+# Text preparation
+
+Prepare exact font bytes and shape reusable vector layouts before entering synchronous modeling.
+
+Install `fontkit` for font preparation and `woff2-encoder` for WOFF2 decoding. Import optional exact-font preparation from `@metamesh/modeling/text`. Supply already acquired font bytes; this entrypoint never fetches a font. Shape once during preparation and pass the immutable layout to modeling.
+
+```ts
+import { prepareVectorFont } from "@metamesh/modeling/text";
+export async function prepareLabel(bytes: Uint8Array) {
+  const font = await prepareVectorFont(bytes);
+  return font.layout("MetaMesh", { fontSize: 8 });
+}
+```
+
+Paths and metrics use Y-up millimetres and a baseline origin. Empty layouts can be measured but cannot create a manufacturing section. Font parsing and WOFF2 decoding stay outside synchronous native builds.
+
+## Categories
+
+- [Font preparation](text/categories/font-preparation.md) — Prepare bounded exact font bytes and reusable vector layouts.
+
+Package: `@metamesh/modeling@0.13.0`.

package/dist/engine/construction-operations.js

@@ -1,3 +1,4 @@
+import { edgeTreatmentSetbacks } from "../geometry/edge-finishing.js";
 import { GeometryError } from "../geometry/errors.js";
 import { resolveExtrusionContourDivisions, resolveExtrusionControls, } from "../geometry/extrusion.js";
 import { heightfieldMesh } from "../geometry/heightfield.js";
@@ -28,7 +29,7 @@ export function createConstructionOperations(environment, sections) {
         const normal = [scaled[0] / length, scaled[1] / length, scaled[2] / length];
         return { normal, offset: validateFiniteNumber(value.offset ?? 0, operation) };
     };
-    const fromContours = sections.sectionFromContours;
+    const fromContours = (contours) => sections.polygon({ contours });
     const corresponding = (value) => typeof value === "object" && value !== null && "components" in value;
     const shapeSection = (shape) => corresponding(shape)
         ? nativeSection(fromContours(shape.components.flatMap((component) => [component.outer, ...component.holes].map((contour) => contour.points))))
@@ -38,8 +39,14 @@ export function createConstructionOperations(environment, sections) {
         assertPrimitiveOptions(value, "extrude");
         const native = shapeSection(handle), resolved = withResolutionDefaults(value);
         if (value.ends !== undefined) {
-            const profile = corresponding(handle) ? handle : environment.sectionProfileFor(handle);
-            return solidFromMesh(buildFinishedExtrusion(module, profile, resolved));
+            assertPrimitiveOptions(value.ends, "extrude");
+            const setbacks = [value.ends.bottom, value.ends.top].map((treatment) => treatment === undefined
+                ? [0, 0]
+                : edgeTreatmentSetbacks(treatment, "extrude", Math.PI / 2, resolved.limits));
+            if (setbacks.some((pair) => pair.some((distance) => distance > 0))) {
+                const profile = corresponding(handle) ? handle : environment.sectionProfileFor(handle);
+                return solidFromMesh(buildFinishedExtrusion(module, profile, resolved));
+            }
         }
         assertSamplingCount(native.numVert(), "extrude", resolved.limits.maxProfilePoints);
         const controls = resolveExtrusionControls(value.height, resolved, "extrude");