improve metadata handling

Author: timschmidt

PORTING_PLAN.md

@@ -70,8 +70,8 @@ It should not know about:
 
 `hyperlimit` should own robust predicate-facing geometry:
 
-- minimal `Point2<S>` and `Point3<S>` carrier types
-- `Plane3<S>` in implicit form
+- minimal `Point2<R>` and `Point3<R>` carrier types
+- `Plane3<R>` in implicit form
 - predicate case structs for batching, where useful
 - orientation and classification results
 
@@ -92,9 +92,9 @@ rich polygon, mesh, sketch, vertex, toolpath, or CSG types.
 
 `csgrs` should continue to own product-level geometry:
 
-- `Sketch<S>`
-- `Mesh<S>`
-- `Polygon<S>`
+- `Sketch<M>`
+- `Mesh<M>`
+- `Polygon<M>`
 - `Vertex`
 - BSP nodes and splitting logic
 - optional `BMesh` / manifold-backed representations
@@ -108,6 +108,28 @@ rich polygon, mesh, sketch, vertex, toolpath, or CSG types.
   or output file format
 - metadata propagation rules
 
+Metadata is moving immediately to a hard-break model: `Mesh<M>`, `Sketch<M>`,
+`Polygon<M>`, `BMesh<M>`, and `Nurbs<M>` store `metadata: M`, not
+`metadata: Option<M>`. Absence is represented by `M = ()`; optional user
+metadata is represented by `M = Option<T>`; required user metadata is represented
+by `M = T`. This avoids hidden double optionality, gives required metadata a
+compile-time guarantee, and makes boolean provenance rules explicit.
+
+Implementation decision:
+
+- primitive constructors for unannotated geometry should produce or accept
+  `M = ()` metadata, with `with_metadata` / `map_metadata` helpers used to move
+  into richer metadata types
+- APIs that import dynamic or optional metadata should choose
+  `M = Option<T>` explicitly
+- boolean operations preserve source-face metadata on polygons and use a
+  documented whole-object metadata policy for the returned shape
+- WASM bindings should not expose a generic metadata type; they should use
+  `Mesh<Option<String>>` / `Sketch<Option<String>>` or
+  `Mesh<serde_json::Value>` / `Sketch<serde_json::Value>` internally, with
+  null/undefined represented by `None` when using the `Option<String>` path
+- this is an immediate major-version break, not a compatibility shim target
+
 `csgrs` may re-export or alias lower-level point/vector/matrix types for user
 convenience, but it should avoid owning a new fundamental numeric geometry
 kernel once `hyperlattice` is available.
@@ -118,11 +140,11 @@ kernel once `hyperlattice` is available.
 
 Keep these as `csgrs` types because they encode CSG or product semantics:
 
-- `mesh::Mesh<S>`
-- `sketch::Sketch<S>`
-- `polygon::Polygon<S>`
+- `mesh::Mesh<M>`
+- `sketch::Sketch<M>`
+- `polygon::Polygon<M>`
 - `vertex::Vertex`
-- `bmesh::BMesh<S>`
+- `bmesh::BMesh<M>`
 - `voxels` module types
 - `toolpath` module types
 - IO module types
@@ -140,7 +162,7 @@ classification and splitting should delegate to `hyperlimit`.
 
 Recommended direction:
 
-- store face-plane data in whichever form is most useful for `Polygon<S>`
+- store face-plane data in whichever form is most useful for `Polygon<M>`
 - convert to `hyperlimit::Plane3` or oriented `hyperlimit::Point3` triples at
   predicate boundaries
 - use `hyperlimit` outcomes to classify vertices and polygons
@@ -1837,7 +1859,7 @@ This gives an early robustness win without forcing a broad public API rewrite.
 
 ## Non-goals
 
-- Do not move `Mesh<S>` or `Sketch<S>` into the lower stack.
+- Do not move `Mesh<M>` or `Sketch<M>` into the lower stack.
 - Do not make `hyperlimit` a mesh-processing crate.
 - Do not make `hyperlattice` aware of file formats or CSG operations.
 - Do not list WASM as a geometry file format; it is only a compilation target

examples/adjacency_demo.rs

@@ -19,7 +19,7 @@ fn main() {
 
     // Create a test mesh - sphere for interesting connectivity
     println!("1. Creating test mesh (sphere with 16 segments, 8 rings)...");
-    let sphere: Mesh<()> = Mesh::sphere(1.0, 16, 8, None);
+    let sphere: Mesh<()> = Mesh::sphere(1.0, 16, 8, ());
     println!("   Original polygons: {}", sphere.polygons.len());
 
     // Build mesh connectivity - this is where adjacency map is created and used

examples/basic2d_shapes_and_offsetting.rs

@@ -8,10 +8,10 @@ const PATH: &str = "stl/examples/basic2d_shapes";
 fn main() {
     fs::create_dir_all(PATH).unwrap();
 
-    let square = Sketch::<()>::square(2.0, None);
-    let circle = Sketch::<()>::circle(1.0, 64, None);
-    let ring = Sketch::<()>::ring(2.0, 0.25, 64, None);
-    let keyhole = Sketch::<()>::keyhole(1.0, 0.4, 1.5, 32, None);
+    let square = Sketch::<()>::square(2.0, ());
+    let circle = Sketch::<()>::circle(1.0, 64, ());
+    let ring = Sketch::<()>::ring(2.0, 0.25, 64, ());
+    let keyhole = Sketch::<()>::keyhole(1.0, 0.4, 1.5, 32, ());
 
     write_sketch(&square, "square");
     write_sketch(&circle, "circle");

examples/basic_shapes.rs

@@ -8,14 +8,11 @@ const PATH: &str = "stl/examples/basic_shapes";
 fn main() {
     fs::create_dir_all(PATH).unwrap();
 
-    write_mesh(&Mesh::<()>::cube(2.0, None), "cube");
-    write_mesh(&Mesh::<()>::sphere(1.0, 32, 16, None), "sphere");
-    write_mesh(&Mesh::<()>::cylinder(1.0, 2.0, 32, None), "cylinder");
-    write_mesh(
-        &Mesh::<()>::ellipsoid(2.0, 1.0, 3.0, 32, 16, None),
-        "ellipsoid",
-    );
-    write_mesh(&Mesh::<()>::torus(2.0, 0.35, 48, 16, None), "torus");
+    write_mesh(&Mesh::<()>::cube(2.0, ()), "cube");
+    write_mesh(&Mesh::<()>::sphere(1.0, 32, 16, ()), "sphere");
+    write_mesh(&Mesh::<()>::cylinder(1.0, 2.0, 32, ()), "cylinder");
+    write_mesh(&Mesh::<()>::ellipsoid(2.0, 1.0, 3.0, 32, 16, ()), "ellipsoid");
+    write_mesh(&Mesh::<()>::torus(2.0, 0.35, 48, 16, ()), "torus");
 }
 
 fn write_mesh(mesh: &Mesh<()>, name: &str) {

examples/boolean_operations.rs

@@ -8,8 +8,8 @@ const PATH: &str = "stl/examples/boolean_operations";
 fn main() {
     fs::create_dir_all(PATH).unwrap();
 
-    let cube = Mesh::<()>::cube(2.0, None);
-    let sphere = Mesh::<()>::sphere(1.35, 32, 16, None).translate(0.55, 0.25, 0.2);
+    let cube = Mesh::<()>::cube(2.0, ());
+    let sphere = Mesh::<()>::sphere(1.35, 32, 16, ()).translate(0.55, 0.25, 0.2);
 
     write_mesh(&cube.union(&sphere), "union");
     write_mesh(&cube.difference(&sphere), "difference");

examples/convex_hull.rs

@@ -8,10 +8,10 @@ const PATH: &str = "stl/examples/convex_hull";
 fn main() {
     fs::create_dir_all(PATH).unwrap();
 
-    let cube = Mesh::<()>::cube(2.0, None)
+    let cube = Mesh::<()>::cube(2.0, ())
         .translate(0.8, 0.0, 0.0)
         .rotate(0.0, 35.0, 0.0);
-    let sphere = Mesh::<()>::sphere(1.1, 32, 16, None).translate(-0.5, 0.0, 0.0);
+    let sphere = Mesh::<()>::sphere(1.1, 32, 16, ()).translate(-0.5, 0.0, 0.0);
     let union = cube.union(&sphere);
 
     write_mesh(&union, "union");

examples/extrude.rs

@@ -9,9 +9,9 @@ const PATH: &str = "stl/examples/extrude";
 fn main() {
     fs::create_dir_all(PATH).unwrap();
 
-    let square = Sketch::<()>::square(1.5, None);
-    let circle = Sketch::<()>::circle(0.5, 32, None).translate(1.5, 0.0, 0.0);
-    let star = Sketch::<()>::star(5, 1.2, 0.45, None);
+    let square = Sketch::<()>::square(1.5, ());
+    let circle = Sketch::<()>::circle(0.5, 32, ()).translate(1.5, 0.0, 0.0);
+    let star = Sketch::<()>::star(5, 1.2, 0.45, ());
 
     write_mesh(&square.extrude(1.0), "square_extrude");
     write_mesh(
@@ -26,7 +26,7 @@ fn main() {
             Point3::new(t.cos() * 0.6, t.sin() * 0.6, i as f64 * 0.04)
         })
         .collect::<Vec<_>>();
-    write_mesh(&Sketch::<()>::circle(0.08, 12, None).sweep(&path), "sweep");
+    write_mesh(&Sketch::<()>::circle(0.08, 12, ()).sweep(&path), "sweep");
 
     let bottom = Polygon::new(
         vec![
@@ -35,7 +35,7 @@ fn main() {
             Vertex::new(Point3::new(0.5, 0.5, 0.0), Vector3::z()),
             Vertex::new(Point3::new(-0.5, 0.5, 0.0), Vector3::z()),
         ],
-        None,
+        (),
     );
     let top = Polygon::new(
         vec![
@@ -44,7 +44,7 @@ fn main() {
             Vertex::new(Point3::new(0.25, 0.25, 1.0), Vector3::z()),
             Vertex::new(Point3::new(-0.25, 0.25, 1.0), Vector3::z()),
         ],
-        None,
+        (),
     );
     write_mesh(&Sketch::<()>::loft(&bottom, &top, true).unwrap(), "loft");
 }

examples/minkowski_sum.rs

@@ -8,8 +8,8 @@ const PATH: &str = "stl/examples/minkowski_sum";
 fn main() {
     fs::create_dir_all(PATH).unwrap();
 
-    let cube = Mesh::<()>::cube(1.5, None);
-    let sphere = Mesh::<()>::sphere(0.4, 16, 8, None);
+    let cube = Mesh::<()>::cube(1.5, ());
+    let sphere = Mesh::<()>::sphere(0.4, 16, 8, ());
     write_mesh(&cube.minkowski_sum(&sphere), "rounded_cube");
 }
 

examples/multi_format_export.rs

@@ -14,20 +14,20 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Create various Mesh objects to demonstrate OBJ export
 
     // 1. Simple cube
-    let cube: Mesh<()> = Mesh::cube(20.0, None).center();
+    let cube: Mesh<()> = Mesh::cube(20.0, ()).center();
     export_to_obj(&cube, "cube", "Simple 20x20x20mm cube")?;
 
     // 2. Sphere
-    let sphere: Mesh<()> = Mesh::sphere(15.0, 32, 16, None);
+    let sphere: Mesh<()> = Mesh::sphere(15.0, 32, 16, ());
     export_to_obj(&sphere, "sphere", "Sphere with 15mm radius")?;
 
     // 3. Cylinder
-    let cylinder: Mesh<()> = Mesh::cylinder(8.0, 25.0, 24, None);
+    let cylinder: Mesh<()> = Mesh::cylinder(8.0, 25.0, 24, ());
     export_to_obj(&cylinder, "cylinder", "Cylinder: 8mm radius, 25mm height")?;
 
     // 4. Complex boolean operation: cube with spherical cavity
-    let cube_large: Mesh<()> = Mesh::cube(30.0, None).center();
-    let sphere_cavity: Mesh<()> = Mesh::sphere(12.0, 24, 12, None).translate(5.0, 5.0, 0.0);
+    let cube_large: Mesh<()> = Mesh::cube(30.0, ()).center();
+    let sphere_cavity: Mesh<()> = Mesh::sphere(12.0, 24, 12, ()).translate(5.0, 5.0, 0.0);
     let cube_with_cavity = cube_large.difference(&sphere_cavity);
     export_to_obj(
         &cube_with_cavity,
@@ -36,8 +36,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     )?;
 
     // 5. Union operation: cube + sphere
-    let cube_small: Mesh<()> = Mesh::cube(16.0, None).center();
-    let sphere_union: Mesh<()> = Mesh::sphere(10.0, 20, 10, None).translate(8.0, 8.0, 8.0);
+    let cube_small: Mesh<()> = Mesh::cube(16.0, ()).center();
+    let sphere_union: Mesh<()> = Mesh::sphere(10.0, 20, 10, ()).translate(8.0, 8.0, 8.0);
     let union_object = cube_small.union(&sphere_union);
     export_to_obj(
         &union_object,
@@ -46,8 +46,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     )?;
 
     // 6. Intersection operation
-    let cube_intersect: Mesh<()> = Mesh::cube(25.0, None).center();
-    let sphere_intersect: Mesh<()> = Mesh::sphere(15.0, 24, 12, None).translate(5.0, 5.0, 0.0);
+    let cube_intersect: Mesh<()> = Mesh::cube(25.0, ()).center();
+    let sphere_intersect: Mesh<()> = Mesh::sphere(15.0, 24, 12, ()).translate(5.0, 5.0, 0.0);
     let intersection_object = cube_intersect.intersection(&sphere_intersect);
     export_to_obj(
         &intersection_object,
@@ -56,8 +56,8 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     )?;
 
     // 7. More complex shape: cube with cylindrical hole
-    let cube_base: Mesh<()> = Mesh::cube(40.0, None).center();
-    let hole_cylinder: Mesh<()> = Mesh::cylinder(6.0, 50.0, 16, None)
+    let cube_base: Mesh<()> = Mesh::cube(40.0, ()).center();
+    let hole_cylinder: Mesh<()> = Mesh::cylinder(6.0, 50.0, 16, ())
         .rotate(90.0, 0.0, 0.0) // Rotate to align with X-axis
         .translate(0.0, 0.0, 0.0);
     let cube_with_hole = cube_base.difference(&hole_cylinder);
@@ -238,7 +238,7 @@ mod tests {
     #[test]
     fn test_obj_export() {
         // Test basic OBJ export functionality
-        let cube: Mesh<()> = Mesh::cube(10.0, None);
+        let cube: Mesh<()> = Mesh::cube(10.0, ());
 
         #[cfg(feature = "obj-io")]
         {
@@ -258,7 +258,7 @@ mod tests {
 
     #[test]
     fn test_obj_content_format() {
-        let sphere: Mesh<()> = Mesh::sphere(5.0, 8, 4, None); // Low res for testing
+        let sphere: Mesh<()> = Mesh::sphere(5.0, 8, 4, ()); // Low res for testing
 
         #[cfg(feature = "obj-io")]
         {
@@ -314,8 +314,8 @@ mod tests {
     #[test]
     fn test_boolean_operations_obj_export() {
         // Test that boolean operations export correctly
-        let cube: Mesh<()> = Mesh::cube(10.0, None);
-        let sphere: Mesh<()> = Mesh::sphere(6.0, 8, 4, None);
+        let cube: Mesh<()> = Mesh::cube(10.0, ());
+        let sphere: Mesh<()> = Mesh::sphere(6.0, 8, 4, ());
 
         #[cfg(feature = "obj-io")]
         {
@@ -345,7 +345,7 @@ mod tests {
     #[test]
     fn test_ply_export() {
         // Test basic PLY export functionality
-        let cube: Mesh<()> = Mesh::cube(10.0, None);
+        let cube: Mesh<()> = Mesh::cube(10.0, ());
 
         #[cfg(feature = "ply-io")]
         {
@@ -388,7 +388,7 @@ mod tests {
 
     #[test]
     fn test_ply_format_structure() {
-        let sphere: Mesh<()> = Mesh::sphere(5.0, 8, 4, None); // Low res for testing
+        let sphere: Mesh<()> = Mesh::sphere(5.0, 8, 4, ()); // Low res for testing
 
         #[cfg(feature = "ply-io")]
         {
@@ -452,7 +452,7 @@ mod tests {
     #[test]
     fn test_amf_export() {
         // Test basic AMF export functionality
-        let cube: Mesh<()> = Mesh::cube(10.0, None);
+        let cube: Mesh<()> = Mesh::cube(10.0, ());
 
         #[cfg(feature = "amf-io")]
         {
@@ -488,7 +488,7 @@ mod tests {
 
     #[test]
     fn test_amf_with_color() {
-        let sphere: Mesh<()> = Mesh::sphere(5.0, 8, 4, None); // Low res for testing
+        let sphere: Mesh<()> = Mesh::sphere(5.0, 8, 4, ()); // Low res for testing
 
         #[cfg(feature = "amf-io")]
         {
@@ -516,7 +516,7 @@ mod tests {
 
     #[test]
     fn test_amf_xml_structure() {
-        let cube: Mesh<()> = Mesh::cube(8.0, None);
+        let cube: Mesh<()> = Mesh::cube(8.0, ());
 
         #[cfg(feature = "amf-io")]
         {