Memory Model#

Two ownership models, chosen per subject. Knowing which you're holding prevents the two classic bugs: leaking arena memory, and calling free on something that isn't a handle.

Documents: GC-owned#

The default. Anything that is a JSON string or plain object is ordinary JS memory:

• Brep.* — solids in, solids out, all strings.
• NurbsCurve.*, Surface.*, Path2d.*, Nesting.* — same.
• TriangleMesh from Brep.tessellate — plain number[] channels.

Nothing to free, ever. Garbage collection handles it; the kernel parses on entry and keeps no reference.

Arena handles: you own them#

The Mesh namespace (half-edge polygon meshes) works in the wasm arena for speed on large in-place edits. A handle is just a number — an arena id:

import { Brep, Mesh } from '@huukhanhnguyen/geometry'

const mesh = Mesh.box(100, 100, 100) // you own this
try {
  Mesh.subdivide(mesh, JSON.stringify({ levels: 2 }))
} finally {
  Mesh.free(mesh) // your obligation
}

Own-and-free applies to everything returning number from Mesh: box, cone, load, clone, fromTriangleMesh, and the boolean results (union, subtract, intersect). Forgetting free leaks arena memory until the wasm instance is torn down — in a long-lived process, that is a real leak.

Mesh.free(id) returns boolean — false means the id was already free or never yours; treat it as a bug signal in tests.

The escape hatches between the two#

• Handle → document: Mesh.tessellateJson(handle), Mesh.dump(handle) — then free the handle.
• Document → handle: Mesh.load(json), Mesh.fromTriangleMesh(positions, indices, uvs) — now you own a handle.
• One-shot, no ownership: Mesh.tessellate(meshGeometry) loads, tessellates, and frees inside the call — the safe default when you just want triangles.

TriangleMesh.* namespace utilities (weld, loopSubdivide) are a third case: packed Float64Array soups, GC-owned, no handle.

Which model when#

• Display pipelines, booleans on solids, file interchange: documents — you never see a handle.
• Heavy polygon editing (subdivision modeling, bevel chains, mesh booleans at interactive rates): handles, with try/finally discipline.
• Unsure? Documents. Reach for Mesh handles when profiling says the document round-trip is the bottleneck.

Where next#

• Guide: Mesh and memory — the handle workflows in practice.
• Concepts: B-Rep documents.