@metamesh/modeling 0.18.0 → 0.19.0

package/dist/api/index.d.ts

@@ -73,8 +73,8 @@ export declare interface Bounds2 extends Bounds2Data {
  * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
  * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
  * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
- * Compiled Generator packages passing these values to host recipes or computed data require
- * runtime 10.0.0 or newer in major 10.
+ * Compiled Generator packages passing these values to host recipes or memo data require
+ * the current Modeling runtime.
  */
 export declare function bounds2(input: Bounds2Options | Bounds2): Bounds2;
 
@@ -130,8 +130,8 @@ export declare interface Bounds3 extends Bounds3Data {
  * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
  * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
  * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
- * Compiled Generator packages passing these values to host recipes or computed data require
- * runtime 10.0.0 or newer in major 10.
+ * Compiled Generator packages passing these values to host recipes or memo data require
+ * the current Modeling runtime.
  */
 export declare function bounds3(input: Bounds3Options | Bounds3): Bounds3;
 
@@ -299,19 +299,6 @@ export declare interface CircularPrimitiveOptions {
   readonly resolution?: GeometryResolution;
 }
 
-/** A lazy session-owned reader. Calling it tracks its output in the current computation. */
-export declare interface Computed<T> {
-  /** Compile-time ownership brand; readers are created by the engine's context helper. */
-  readonly [computedBrand]: "Computed";
-  /** Reads immutable data or a deferred recipe; evaluation is synchronous and cached. */
-  (): ImmutableValue<T>;
-}
-
-declare const computedBrand: unique symbol;
-
-/** A value supplied immediately or by a lazy computed reader. */
-export declare type ComputedValue<T> = T | Computed<T>;
-
 /**
  * A sampled closed two-dimensional boundary whose first point is not repeated at the end.
  *
@@ -482,7 +469,7 @@ export declare type EllipseOptions = EllipseContourOptions &
   PrimitiveAttachment;
 
 /**
- * Independent inward finishing on primitive or straight convex extrusion ends.
+ * Independent inward finishing on primitive or source-corresponding straight extrusion ends.
  * Zero amounts leave the end untreated, including when all ends are disabled.
  */
 export declare interface EndTreatments {
@@ -522,7 +509,7 @@ export declare interface ExtrudeMeshOptions extends ExtrusionSamplingOptions {
 
 /** Native +Z extrusion with optional inward end treatments. */
 export declare interface ExtrudeOptions extends ExtrudeMeshOptions {
-  /** Independent inward end treatments on straight convex single-contour extrusions. */
+  /** Independent inward treatments on every material rim of a straight, topology-preserving extrusion. */
   readonly ends?: EndTreatments;
 }
 
@@ -555,7 +542,7 @@ export declare interface Frame3 {
 /**
  * Defines a typed model without executing it. Parameters are an object map of capturable data;
  * runtime capture rejects arrays at the root, ordinary class instances, mutable buffers, and functions.
- * Supply live capabilities through services. Use `computed` only for work worth reusing.
+ * Supply live capabilities through services. Use `memo` only for work worth reusing.
  *
  * @example A simple model
  * ```ts
@@ -586,20 +573,12 @@ export declare interface GenerateContext<
   readonly params: ImmutableValue<P>;
   /** Host-prepared readonly synchronous capabilities, fixed for the session. */
   readonly services: Readonly<S>;
-  /**
-   * Registers a lazy pure calculation and automatically tracks parameter and computed-reader reads.
-   * Optional dependencies add changing outer captures; entries compare with Object.is. Objects and
-   * arrays must be deeply immutable. An empty list still tracks reads inside the callback.
-   */
-  readonly computed: <T>(
-    id: string,
-    callback: () => T,
-    dependencies?: readonly unknown[],
-  ) => Computed<T>;
+  /** Reuses a pure synchronous function; pass changing inputs as arguments and keep helpers stable. */
+  readonly memo: Memo;
   /** Declares a semantic part with identity placement, or explicit placement and appearance. */
   readonly part: (
     id: string,
-    input: ComputedValue<PartGeometry> | PartOptions,
+    input: PartGeometry | PartOptions,
   ) => PartDeclaration;
   /** Immediately aborts on false; geometry observations in the condition run first.
    * This diagnostic helper does not narrow TypeScript types; use an explicit conditional guard when needed.
@@ -624,7 +603,7 @@ export declare interface GenerationDiagnostic {
   readonly path?: readonly (string | number)[] | undefined;
 }
 
-/** A user-correctable assertion failure. Successful computation caches never retain failures. */
+/** A user-correctable assertion failure. Successful memo caches never retain failures. */
 export declare class GenerationError extends Error {
   /** Issues reached in normal JavaScript order, ending with the first failed assertion. */
   readonly diagnostics: readonly GenerationDiagnostic[];
@@ -1067,6 +1046,56 @@ export declare function intersect(sections: readonly Section[]): Section;
  */
 export declare function isGeometryError(value: unknown): value is GeometryError;
 
+/**
+ * Fuses two positioned solids with a dimensioned transition at the feature's source datum.
+ *
+ * Requires a local straight feature collar and a continuous support patch single-valued along
+ * that collar's axis. Angled and curved sampled supports are admitted when those proofs hold.
+ * Width is a parallel-edge offset; height is axial rise above local contact, both in millimetres.
+ * The default smooth profile matches tangents; kind "straight" gives a linear bevel profile.
+ * Neither operand moves, loses material, or changes sampling. The result has no inherited anchors.
+ * This operation promises neither a circular radius, a constant bevel angle, nor global curvature continuity.
+ *
+ * @example Join a mounting boss
+ * ```ts
+ * const base = box({ size: [50, 40, 6] });
+ * const feature = cylinder({ diameter: 12, height: 14, center: false }).translate([0, 0, 2]);
+ * base.join(feature, { source: "bottom", transition: { width: 2, height: 3 } });
+ * ```
+ */
+export declare function join(
+  base: Solid,
+  feature: Solid,
+  options: JoinOptions,
+): Solid;
+
+/** Options for joining two positioned solids through a validated local straight feature collar. */
+export declare interface JoinOptions {
+  /**
+   * Outward feature-root datum, pointing toward the base. Names resolve lazily on the feature;
+   * explicit anchors use the operands' shared modeling coordinates. The collar grows opposite
+   * this direction, with its roll fixed by the anchor's up vector. Every collar section cut
+   * by the source plane participates, including disconnected roots.
+   */
+  readonly source: string | Anchor3;
+  /** Both dimensions must be positive, or both zero to validate contact and fuse without a blend. */
+  readonly transition: JoinTransition;
+  /** Physical connection sampling. Input solids retain their own captured sampling. */
+  readonly resolution?: GeometryResolution;
+  /** Local allocation ceilings may only lower the evaluating host's limits. */
+  readonly limits?: Partial<ModelingLimits>;
+}
+
+/** Connection profile and setbacks, independent of feature construction. */
+export declare interface JoinTransition {
+  /** Tangent-matching cubic or linear profile. Defaults to "smooth"; neither specifies a radius. */
+  readonly kind?: "smooth" | "straight";
+  /** Nonnegative parallel-edge normal offset in millimetres perpendicular to the feature collar axis. */
+  readonly width: number;
+  /** Nonnegative axial rise in millimetres above the local support contact. */
+  readonly height: number;
+}
+
 /** Portable local geometry; consumers own plates, holes, part declarations, and final placement. */
 export declare interface KnuckleHinge {
   /** Alternating A intervals, including the integral shaft in print-in-place and lift-off modes. */
@@ -1341,6 +1370,20 @@ export declare interface MatchProfilesOptions {
   readonly limits?: Partial<GeometrySamplingLimits>;
 }
 
+/** Eagerly reuses pure synchronous functions by function identity and immutable arguments. */
+export declare interface Memo {
+  /**
+   * Invokes fn(...args) and returns captured immutable data. Stable helpers reuse work across runs.
+   * Arguments compare with Object.is and must be deeply immutable; the exact current params or
+   * generation context instead tracks parameter fields read by the function. Functions must be
+   * pure: supply changing inputs explicitly, and do not read changing globals or ambient state.
+   */
+  <Args extends readonly unknown[], Result>(
+    fn: (...args: Args) => Result,
+    ...args: Args
+  ): ImmutableValue<Result>;
+}
+
 /** Three-dimensional Minkowski sum. */
 export declare function minkowskiSum(a: Solid, b: Solid): Solid;
 
@@ -1378,12 +1421,12 @@ export declare type PartGeometry = Solid | TriangleMesh | ImmutableTriangleMesh;
 
 /** Appearance and rigid placement of a finished local manufacturing part. */
 export declare interface PartOptions {
-  /** Local geometry or a lazy reader; native objects never cross a revision. */
-  readonly geometry: ComputedValue<PartGeometry>;
+  /** Local manufacturing geometry; native objects never cross a revision. */
+  readonly geometry: PartGeometry;
   /** Rigid local-to-world transform; translation uses millimetres. Defaults to identity.
    * Accepts a fluent transform or row-major 4x4 matrix. Scale, shear, and reflection are invalid.
    */
-  readonly transform?: ComputedValue<Transform3Input>;
+  readonly transform?: Transform3Input;
   /** Optional six-digit hexadecimal semantic part color. */
   readonly color?: string;
 }
@@ -2207,6 +2250,13 @@ export declare interface Solid {
   toMesh(this: Solid): TriangleMesh;
   /** Robust union with one or more solids; an empty operand array preserves this solid. */
   union(this: Solid, operands: Solid | readonly Solid[]): Solid;
+  /**
+   * Fuses an already positioned feature with a smooth (default) or straight width/height transition.
+   * The source datum belongs to the feature; neither input moves or loses material.
+   * Requires a verified local straight collar and continuous sampled support patch.
+   * The result has no inherited anchors. This is not a rolling-ball fillet.
+   */
+  join(this: Solid, feature: Solid, options: JoinOptions): Solid;
   /** Robust intersection with every supplied solid; an empty operand array preserves this solid. */
   intersect(this: Solid, operands: Solid | readonly Solid[]): Solid;
   /**

package/dist/api/mesh.d.ts

@@ -225,12 +225,10 @@ export declare function heightfield(
  * ```ts
  * import { generate } from "@metamesh/modeling";
  * import * as mesh from "@metamesh/modeling/geometry/mesh";
- * const model = generate(({ computed, part }) => {
- *   const surface = computed("surface", () => mesh.immutable(mesh.heightfield({
- *     size: [10, 10], segments: [8, 8], height: () => 2,
- *   })));
- *   return [part("surface", surface)];
- * });
+ * const buildSurface = () => mesh.immutable(mesh.heightfield({
+ *   size: [10, 10], segments: [8, 8], height: () => 2,
+ * }));
+ * const model = generate(({ memo, part }) => part("surface", memo(buildSurface)));
  * ```
  */
 export declare function immutable(mesh: {
@@ -273,6 +271,12 @@ export declare function loft(
   options?: LoftOptions,
 ): TriangleMesh;
 
+/** Shading policy for a render copy; manufacturing positions and triangle order never change. */
+export declare interface MeshRenderOptions {
+  /** Maximum angle between averaged face normals, in degrees. Defaults to `20`; `0` is flat. */
+  readonly creaseAngle?: number;
+}
+
 /**
  * Improves pathological planar triangulation with bounded legal diagonal flips.
  *
@@ -319,6 +323,31 @@ export declare function preflightThreadSolid(
   options: ThreadSolidOptions,
 ): ThreadSolidPreflight;
 
+/**
+ * Builds crease-aware render buffers without moving or merging distinct positions.
+ * Face normals are averaged only at exactly coincident positions within the crease angle.
+ * Returns owned buffers; every triangle retains its coordinates, order and winding.
+ * Pathological vertex fans exceeding 50 million normal comparisons reject with a complexity error.
+ *
+ * @example
+ * ```ts
+ * import * as mesh from "@metamesh/modeling/geometry/mesh";
+ * const surface = mesh.heightfield({ size: [10, 10], segments: [2, 2], height: () => 0 });
+ * const rendered = mesh.render(surface);
+ * // rendered.positions and rendered.normals can be passed to a renderer or GLB writer.
+ * ```
+ */
+export declare function render(
+  input: TriangleMeshInput,
+  options?: MeshRenderOptions,
+): RenderMesh;
+
+/** Owned indexed render buffers with unit vertex normals and positions in millimetres. */
+export declare interface RenderMesh extends TriangleMesh {
+  /** XYZ unit normals, one for each render vertex. Vertices split at shading discontinuities. */
+  readonly normals: Float32Array;
+}
+
 /**
  * Returns a copy of a mesh with every triangle winding reversed.
  *