okgeometry-api 1.19.0 → 1.20.0

package/src/SculptSession.ts

@@ -1,362 +1,377 @@
-import { ensureInit } from "./engine.js";
-import { Mesh } from "./Mesh.js";
-import * as wasm from "./wasm-bindings.js";
-
-/**
- * Sculpting brushes. Codes are a stable WASM ABI — never renumber.
- */
-export enum SculptBrush {
-  Draw = 0,
-  DrawSharp = 1,
-  Clay = 2,
-  Smooth = 3,
-  Inflate = 4,
-  Grab = 5,
-  SnakeHook = 6,
-  Flatten = 7,
-  Scrape = 8,
-  Fill = 9,
-  Pinch = 10,
-  Crease = 11,
-  Layer = 12,
-  Nudge = 13,
-  /** Paints the sculpt mask (protection) instead of moving geometry. */
-  Mask = 14,
-}
-
-/** Brush falloff profiles over normalized distance. Stable WASM ABI codes. */
-export enum SculptFalloff {
-  Smooth = 0,
-  Sphere = 1,
-  Linear = 2,
-  Sharp = 3,
-  Root = 4,
-  Constant = 5,
-}
-
-export interface SculptBrushSettings {
-  brush: SculptBrush;
-  /** Brush radius in mesh (local) units. */
-  radius: number;
-  /** Strength, typically 0..1. */
-  strength: number;
-  falloff?: SculptFalloff;
-  /** Invert the brush direction (carve instead of add, etc.). */
-  invert?: boolean;
-  /** Only affect vertices facing the viewer (default true). */
-  frontFacesOnly?: boolean;
-  /** Clay plane offset as a fraction of the radius (default 0.05). */
-  planeOffset?: number;
-  /** Mirror across local planes: combine SYMMETRY_X | SYMMETRY_Y | SYMMETRY_Z. */
-  symmetry?: number;
-}
-
-export const SYMMETRY_X = 1;
-export const SYMMETRY_Y = 2;
-export const SYMMETRY_Z = 4;
-
-export interface SculptRayHit {
-  point: [number, number, number];
-  normal: [number, number, number];
-  distance: number;
-  triangleIndex: number;
-}
-
-export interface SculptDabInput {
-  /** Brush center on the surface (usually the raycast hit point). */
-  center: [number, number, number];
-  /** Normalized view ray direction, used for front-face masking. */
-  viewDir: [number, number, number];
-  /**
-   * World-space drag vector. Grab: total drag since the stroke start.
-   * Snake hook / nudge: drag since the previous dab. Others: ignored.
-   */
-  drag?: [number, number, number];
-  /** Tablet pressure 0..1 (default 1). */
-  pressure?: number;
-}
-
-/**
- * Render patch after a dab/undo/redo/mask op: for each changed vertex,
- * 8 floats `[index, x, y, z, nx, ny, nz, mask]`.
- */
-export type SculptPatch = Float32Array;
-
-export interface SculptRenderData {
-  vertexCount: number;
-  triangleCount: number;
-  positions: Float32Array;
-  normals: Float32Array;
-  /** Per-vertex sculpt mask in [0, 1] (1 = protected). */
-  mask: Float32Array;
-  indices: Uint32Array;
-}
-
-/**
- * Interactive sculpting session over a triangle mesh.
- *
- * The mesh, its spatial index, adjacency and normals live WASM-side for the
- * lifetime of the session, so brush dabs are incremental: each dab returns
- * only the changed vertices as a compact patch. Call `dispose()` when done —
- * sessions hold WASM memory.
- *
- * ```ts
- * const session = SculptSession.fromMesh(mesh);
- * session.beginStroke({ brush: SculptBrush.Draw, radius: 0.5, strength: 0.8 });
- * const hit = session.raycast(origin, dir);
- * if (hit) session.dab({ center: hit.point, viewDir: dir });
- * session.endStroke();
- * const result = session.toMesh(); // commit
- * session.dispose();
- * ```
- */
-export class SculptSession {
-  private id: number;
-  private disposed = false;
-
-  private constructor(id: number) {
-    this.id = id;
-  }
-
-  /** Create a session from a Mesh. Throws on invalid/empty geometry. */
-  static fromMesh(mesh: Mesh): SculptSession {
-    ensureInit();
-    const buffer = mesh.rawBuffer;
-    const id = wasm.sculpt_session_create(mesh.vertexCount, buffer);
-    if (!id) {
-      throw new Error("SculptSession: invalid mesh (empty or malformed buffer)");
-    }
-    return new SculptSession(id);
-  }
-
-  /** Create a session from a raw mesh buffer `[vertexCount, xyz..., idx...]`. */
-  static fromBuffer(vertexCount: number, buffer: Float64Array): SculptSession {
-    ensureInit();
-    const id = wasm.sculpt_session_create(vertexCount, buffer);
-    if (!id) {
-      throw new Error("SculptSession: invalid mesh buffer");
-    }
-    return new SculptSession(id);
-  }
-
-  /** Free the WASM-side session. Safe to call more than once. */
-  dispose(): void {
-    if (!this.disposed) {
-      wasm.sculpt_session_release(this.id);
-      this.disposed = true;
-    }
-  }
-
-  get isDisposed(): boolean {
-    return this.disposed;
-  }
-
-  private ensureAlive(): void {
-    if (this.disposed) {
-      throw new Error("SculptSession: session already disposed");
-    }
-  }
-
-  get vertexCount(): number {
-    this.ensureAlive();
-    const info = wasm.sculpt_session_info(this.id);
-    return info.length ? info[0] : 0;
-  }
-
-  get triangleCount(): number {
-    this.ensureAlive();
-    const info = wasm.sculpt_session_info(this.id);
-    return info.length ? info[1] : 0;
-  }
-
-  /** Average edge length — a good baseline for default brush radius. */
-  get averageEdgeLength(): number {
-    this.ensureAlive();
-    const info = wasm.sculpt_session_info(this.id);
-    return info.length ? info[2] : 0;
-  }
-
-  get undoDepth(): number {
-    this.ensureAlive();
-    const info = wasm.sculpt_session_info(this.id);
-    return info.length ? info[3] : 0;
-  }
-
-  get redoDepth(): number {
-    this.ensureAlive();
-    const info = wasm.sculpt_session_info(this.id);
-    return info.length ? info[4] : 0;
-  }
-
-  /**
-   * Full render snapshot (f32 positions/normals + u32 indices) for building
-   * an indexed, smooth-shaded display mesh. Fetch once at session start and
-   * after `subdivide()`; use dab patches for incremental updates.
-   */
-  getRenderData(): SculptRenderData {
-    this.ensureAlive();
-    const raw = wasm.sculpt_session_render_data(this.id);
-    if (raw.length < 2) {
-      throw new Error("SculptSession: no render data (session lost)");
-    }
-    const vertexCount = raw[0];
-    const triangleCount = raw[1];
-    const pStart = 2;
-    const nStart = pStart + vertexCount * 3;
-    const mStart = nStart + vertexCount * 3;
-    const iStart = mStart + vertexCount;
-    const positions = raw.slice(pStart, nStart);
-    const normals = raw.slice(nStart, mStart);
-    const mask = raw.slice(mStart, iStart);
-    const indices = new Uint32Array(triangleCount * 3);
-    for (let i = 0; i < indices.length; i++) {
-      indices[i] = raw[iStart + i];
-    }
-    return { vertexCount, triangleCount, positions, normals, mask, indices };
-  }
-
-  /** Raycast the current (deforming) surface. */
-  raycast(
-    origin: [number, number, number],
-    direction: [number, number, number],
-  ): SculptRayHit | null {
-    this.ensureAlive();
-    const hit = wasm.sculpt_session_raycast(
-      this.id,
-      origin[0],
-      origin[1],
-      origin[2],
-      direction[0],
-      direction[1],
-      direction[2],
-    );
-    if (hit.length < 8) return null;
-    return {
-      point: [hit[0], hit[1], hit[2]],
-      normal: [hit[3], hit[4], hit[5]],
-      distance: hit[6],
-      triangleIndex: hit[7],
-    };
-  }
-
-  /** Begin a brush stroke. Ends any stroke still in flight. */
-  beginStroke(settings: SculptBrushSettings): void {
-    this.ensureAlive();
-    const flags =
-      (settings.invert ? 1 : 0) | ((settings.frontFacesOnly ?? true) ? 2 : 0);
-    const ok = wasm.sculpt_session_begin_stroke(
-      this.id,
-      settings.brush,
-      settings.radius,
-      settings.strength,
-      settings.falloff ?? SculptFalloff.Smooth,
-      flags,
-      settings.planeOffset ?? 0.05,
-      settings.symmetry ?? 0,
-    );
-    if (!ok) {
-      throw new Error("SculptSession: beginStroke failed (bad settings or session lost)");
-    }
-  }
-
-  /**
-   * Apply one brush dab. Returns the changed-vertex render patch
-   * (`[index, x,y,z, nx,ny,nz]` per vertex); empty when nothing changed.
-   */
-  dab(input: SculptDabInput): SculptPatch {
-    this.ensureAlive();
-    const drag = input.drag ?? [0, 0, 0];
-    return wasm.sculpt_session_dab(
-      this.id,
-      input.center[0],
-      input.center[1],
-      input.center[2],
-      input.viewDir[0],
-      input.viewDir[1],
-      input.viewDir[2],
-      drag[0],
-      drag[1],
-      drag[2],
-      input.pressure ?? 1,
-    );
-  }
-
-  /** Finish the active stroke; the stroke becomes one undo step. */
-  endStroke(): void {
-    this.ensureAlive();
-    wasm.sculpt_session_end_stroke(this.id);
-  }
-
-  /** Undo the last stroke. Returns the restoring patch (empty = nothing to undo). */
-  undo(): SculptPatch {
-    this.ensureAlive();
-    return wasm.sculpt_session_undo(this.id);
-  }
-
-  /** Redo the last undone stroke. */
-  redo(): SculptPatch {
-    this.ensureAlive();
-    return wasm.sculpt_session_redo(this.id);
-  }
-
-  /**
-   * Uniform 1:4 shape-preserving (linear midpoint) subdivision for more
-   * sculptable detail. Clears session undo history. Returns false when
-   * refused by the safety cap (~8M triangles). Refetch `getRenderData()`
-   * afterwards.
-   */
-  subdivide(): boolean {
-    this.ensureAlive();
-    return wasm.sculpt_session_subdivide(this.id) === 1;
-  }
-
-  /**
-   * Smooth face group around a seed triangle: edge-connected triangles whose
-   * dihedral angles stay below `maxAngleDeg` (whole planar face, whole
-   * cylinder wall — the same grouping used for face hovers on meshes).
-   * Empty when the seed is out of range.
-   */
-  faceGroup(seedTriangle: number, maxAngleDeg = 30): Uint32Array {
-    this.ensureAlive();
-    return wasm.sculpt_session_face_group(this.id, seedTriangle, maxAngleDeg);
-  }
-
-  /**
-   * Locally refine the given triangles 1:4 for finer sculpting control.
-   * Neighboring triangles get crack-free conforming splits (red-green
-   * refinement) so the mesh stays seamless/watertight. Shape preserving
-   * (linear midpoints); the mask interpolates. Clears session undo history.
-   * Returns false when refused (empty/out-of-range input or the ~8M
-   * triangle safety cap). Refetch `getRenderData()` afterwards.
-   */
-  subdivideFaces(triangles: Uint32Array | number[]): boolean {
-    this.ensureAlive();
-    const arr = triangles instanceof Uint32Array ? triangles : Uint32Array.from(triangles);
-    return wasm.sculpt_session_subdivide_faces(this.id, arr) === 1;
-  }
-
-  /**
-   * Fill the whole sculpt mask (0 clears, 1 protects everything).
-   * Undoable; returns the render patch of changed vertices.
-   */
-  maskFill(value: number): SculptPatch {
-    this.ensureAlive();
-    return wasm.sculpt_session_mask_fill(this.id, value);
-  }
-
-  /** Invert the sculpt mask. Undoable; returns the render patch. */
-  maskInvert(): SculptPatch {
-    this.ensureAlive();
-    return wasm.sculpt_session_mask_invert(this.id);
-  }
-
-  /** Current mesh as a new Mesh instance (for committing the sculpt). */
-  toMesh(): Mesh {
-    this.ensureAlive();
-    const buffer = wasm.sculpt_session_mesh_buffer(this.id);
-    if (!buffer.length) {
-      throw new Error("SculptSession: mesh buffer unavailable (session lost)");
-    }
-    return Mesh.fromBuffer(buffer);
-  }
-}
+import { ensureInit } from "./engine.js";
+import { Mesh } from "./Mesh.js";
+import * as wasm from "./wasm-bindings.js";
+
+/**
+ * Sculpting brushes. Codes are a stable WASM ABI — never renumber.
+ */
+export enum SculptBrush {
+  Draw = 0,
+  DrawSharp = 1,
+  Clay = 2,
+  Smooth = 3,
+  Inflate = 4,
+  Grab = 5,
+  SnakeHook = 6,
+  Flatten = 7,
+  Scrape = 8,
+  Fill = 9,
+  Pinch = 10,
+  Crease = 11,
+  Layer = 12,
+  Nudge = 13,
+  /** Paints the sculpt mask (protection) instead of moving geometry. */
+  Mask = 14,
+}
+
+/** Brush falloff profiles over normalized distance. Stable WASM ABI codes. */
+export enum SculptFalloff {
+  Smooth = 0,
+  Sphere = 1,
+  Linear = 2,
+  Sharp = 3,
+  Root = 4,
+  Constant = 5,
+}
+
+export interface SculptBrushSettings {
+  brush: SculptBrush;
+  /** Brush radius in mesh (local) units. */
+  radius: number;
+  /** Strength, typically 0..1. */
+  strength: number;
+  falloff?: SculptFalloff;
+  /** Invert the brush direction (carve instead of add, etc.). */
+  invert?: boolean;
+  /** Only affect vertices facing the viewer (default true). */
+  frontFacesOnly?: boolean;
+  /** Clay plane offset as a fraction of the radius (default 0.05). */
+  planeOffset?: number;
+  /** Mirror across local planes: combine SYMMETRY_X | SYMMETRY_Y | SYMMETRY_Z. */
+  symmetry?: number;
+}
+
+export const SYMMETRY_X = 1;
+export const SYMMETRY_Y = 2;
+export const SYMMETRY_Z = 4;
+
+export interface SculptRayHit {
+  point: [number, number, number];
+  normal: [number, number, number];
+  distance: number;
+  triangleIndex: number;
+}
+
+export interface SculptDabInput {
+  /** Brush center on the surface (usually the raycast hit point). */
+  center: [number, number, number];
+  /** Normalized view ray direction, used for front-face masking. */
+  viewDir: [number, number, number];
+  /**
+   * World-space drag vector. Grab: total drag since the stroke start.
+   * Snake hook / nudge: drag since the previous dab. Others: ignored.
+   */
+  drag?: [number, number, number];
+  /** Tablet pressure 0..1 (default 1). */
+  pressure?: number;
+}
+
+/**
+ * Render patch after a dab/undo/redo/mask op: for each changed vertex,
+ * 8 floats `[index, x, y, z, nx, ny, nz, mask]`.
+ */
+export type SculptPatch = Float32Array;
+
+export interface SculptRenderData {
+  vertexCount: number;
+  triangleCount: number;
+  positions: Float32Array;
+  normals: Float32Array;
+  /** Per-vertex sculpt mask in [0, 1] (1 = protected). */
+  mask: Float32Array;
+  indices: Uint32Array;
+}
+
+/**
+ * Interactive sculpting session over a triangle mesh.
+ *
+ * The mesh, its spatial index, adjacency and normals live WASM-side for the
+ * lifetime of the session, so brush dabs are incremental: each dab returns
+ * only the changed vertices as a compact patch. Call `dispose()` when done —
+ * sessions hold WASM memory.
+ *
+ * ```ts
+ * const session = SculptSession.fromMesh(mesh);
+ * session.beginStroke({ brush: SculptBrush.Draw, radius: 0.5, strength: 0.8 });
+ * const hit = session.raycast(origin, dir);
+ * if (hit) session.dab({ center: hit.point, viewDir: dir });
+ * session.endStroke();
+ * const result = session.toMesh(); // commit
+ * session.dispose();
+ * ```
+ */
+export class SculptSession {
+  private id: number;
+  private disposed = false;
+
+  private constructor(id: number) {
+    this.id = id;
+  }
+
+  /** Create a session from a Mesh. Throws on invalid/empty geometry. */
+  static fromMesh(mesh: Mesh): SculptSession {
+    ensureInit();
+    const buffer = mesh.rawBuffer;
+    const id = wasm.sculpt_session_create(mesh.vertexCount, buffer);
+    if (!id) {
+      throw new Error("SculptSession: invalid mesh (empty or malformed buffer)");
+    }
+    return new SculptSession(id);
+  }
+
+  /** Create a session from a raw mesh buffer `[vertexCount, xyz..., idx...]`. */
+  static fromBuffer(vertexCount: number, buffer: Float64Array): SculptSession {
+    ensureInit();
+    const id = wasm.sculpt_session_create(vertexCount, buffer);
+    if (!id) {
+      throw new Error("SculptSession: invalid mesh buffer");
+    }
+    return new SculptSession(id);
+  }
+
+  /** Free the WASM-side session. Safe to call more than once. */
+  dispose(): void {
+    if (!this.disposed) {
+      wasm.sculpt_session_release(this.id);
+      this.disposed = true;
+    }
+  }
+
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  private ensureAlive(): void {
+    if (this.disposed) {
+      throw new Error("SculptSession: session already disposed");
+    }
+  }
+
+  get vertexCount(): number {
+    this.ensureAlive();
+    const info = wasm.sculpt_session_info(this.id);
+    return info.length ? info[0] : 0;
+  }
+
+  get triangleCount(): number {
+    this.ensureAlive();
+    const info = wasm.sculpt_session_info(this.id);
+    return info.length ? info[1] : 0;
+  }
+
+  /** Average edge length — a good baseline for default brush radius. */
+  get averageEdgeLength(): number {
+    this.ensureAlive();
+    const info = wasm.sculpt_session_info(this.id);
+    return info.length ? info[2] : 0;
+  }
+
+  get undoDepth(): number {
+    this.ensureAlive();
+    const info = wasm.sculpt_session_info(this.id);
+    return info.length ? info[3] : 0;
+  }
+
+  get redoDepth(): number {
+    this.ensureAlive();
+    const info = wasm.sculpt_session_info(this.id);
+    return info.length ? info[4] : 0;
+  }
+
+  /**
+   * Full render snapshot (f32 positions/normals + u32 indices) for building
+   * an indexed, smooth-shaded display mesh. Fetch once at session start and
+   * after `subdivide()`; use dab patches for incremental updates.
+   */
+  getRenderData(): SculptRenderData {
+    this.ensureAlive();
+    const raw = wasm.sculpt_session_render_data(this.id);
+    if (raw.length < 2) {
+      throw new Error("SculptSession: no render data (session lost)");
+    }
+    const vertexCount = raw[0];
+    const triangleCount = raw[1];
+    const pStart = 2;
+    const nStart = pStart + vertexCount * 3;
+    const mStart = nStart + vertexCount * 3;
+    const iStart = mStart + vertexCount;
+    const positions = raw.slice(pStart, nStart);
+    const normals = raw.slice(nStart, mStart);
+    const mask = raw.slice(mStart, iStart);
+    const indices = new Uint32Array(triangleCount * 3);
+    for (let i = 0; i < indices.length; i++) {
+      indices[i] = raw[iStart + i];
+    }
+    return { vertexCount, triangleCount, positions, normals, mask, indices };
+  }
+
+  /** Raycast the current (deforming) surface. */
+  raycast(
+    origin: [number, number, number],
+    direction: [number, number, number],
+  ): SculptRayHit | null {
+    this.ensureAlive();
+    const hit = wasm.sculpt_session_raycast(
+      this.id,
+      origin[0],
+      origin[1],
+      origin[2],
+      direction[0],
+      direction[1],
+      direction[2],
+    );
+    if (hit.length < 8) return null;
+    return {
+      point: [hit[0], hit[1], hit[2]],
+      normal: [hit[3], hit[4], hit[5]],
+      distance: hit[6],
+      triangleIndex: hit[7],
+    };
+  }
+
+  /** Begin a brush stroke. Ends any stroke still in flight. */
+  beginStroke(settings: SculptBrushSettings): void {
+    this.ensureAlive();
+    const flags =
+      (settings.invert ? 1 : 0) | ((settings.frontFacesOnly ?? true) ? 2 : 0);
+    const ok = wasm.sculpt_session_begin_stroke(
+      this.id,
+      settings.brush,
+      settings.radius,
+      settings.strength,
+      settings.falloff ?? SculptFalloff.Smooth,
+      flags,
+      settings.planeOffset ?? 0.05,
+      settings.symmetry ?? 0,
+    );
+    if (!ok) {
+      throw new Error("SculptSession: beginStroke failed (bad settings or session lost)");
+    }
+  }
+
+  /**
+   * Apply one brush dab. Returns the changed-vertex render patch
+   * (`[index, x,y,z, nx,ny,nz]` per vertex); empty when nothing changed.
+   */
+  dab(input: SculptDabInput): SculptPatch {
+    this.ensureAlive();
+    const drag = input.drag ?? [0, 0, 0];
+    return wasm.sculpt_session_dab(
+      this.id,
+      input.center[0],
+      input.center[1],
+      input.center[2],
+      input.viewDir[0],
+      input.viewDir[1],
+      input.viewDir[2],
+      drag[0],
+      drag[1],
+      drag[2],
+      input.pressure ?? 1,
+    );
+  }
+
+  /** Finish the active stroke; the stroke becomes one undo step. */
+  endStroke(): void {
+    this.ensureAlive();
+    wasm.sculpt_session_end_stroke(this.id);
+  }
+
+  /** Undo the last stroke. Returns the restoring patch (empty = nothing to undo). */
+  undo(): SculptPatch {
+    this.ensureAlive();
+    return wasm.sculpt_session_undo(this.id);
+  }
+
+  /** Redo the last undone stroke. */
+  redo(): SculptPatch {
+    this.ensureAlive();
+    return wasm.sculpt_session_redo(this.id);
+  }
+
+  /**
+   * Uniform 1:4 shape-preserving (linear midpoint) subdivision for more
+   * sculptable detail. Clears session undo history. Returns false when
+   * refused by the safety cap (~8M triangles). Refetch `getRenderData()`
+   * afterwards.
+   */
+  subdivide(): boolean {
+    this.ensureAlive();
+    return wasm.sculpt_session_subdivide(this.id) === 1;
+  }
+
+  /**
+   * Smooth face group around a seed triangle: edge-connected triangles whose
+   * dihedral angles stay below `maxAngleDeg` (whole planar face, whole
+   * cylinder wall — the same grouping used for face hovers on meshes).
+   * Empty when the seed is out of range.
+   */
+  faceGroup(seedTriangle: number, maxAngleDeg = 30): Uint32Array {
+    this.ensureAlive();
+    return wasm.sculpt_session_face_group(this.id, seedTriangle, maxAngleDeg);
+  }
+
+  /**
+   * Locally refine the given triangles 1:4 for finer sculpting control.
+   * Neighboring triangles get crack-free conforming splits (red-green
+   * refinement) so the mesh stays seamless/watertight. Shape preserving
+   * (linear midpoints); the mask interpolates. Clears session undo history.
+   * Returns false when refused (empty/out-of-range input or the ~8M
+   * triangle safety cap). Refetch `getRenderData()` afterwards.
+   */
+  subdivideFaces(triangles: Uint32Array | number[]): boolean {
+    this.ensureAlive();
+    const arr = triangles instanceof Uint32Array ? triangles : Uint32Array.from(triangles);
+    return wasm.sculpt_session_subdivide_faces(this.id, arr) === 1;
+  }
+
+  /**
+   * Locally REDUCE point density in the given triangle group by collapsing
+   * interior edges (shortest first) until the group has at most
+   * `targetPoints` unique vertices or no safe collapse remains. Only
+   * vertices strictly interior to the group are removed — the group
+   * boundary and everything outside it are untouched, so a closed mesh
+   * stays watertight. Clears session undo history. Returns false when no
+   * collapse was possible. Refetch `getRenderData()` afterwards.
+   */
+  decimateFaces(triangles: Uint32Array | number[], targetPoints: number): boolean {
+    this.ensureAlive();
+    const arr = triangles instanceof Uint32Array ? triangles : Uint32Array.from(triangles);
+    return wasm.sculpt_session_decimate_faces(this.id, arr, Math.max(0, Math.floor(targetPoints))) === 1;
+  }
+
+  /**
+   * Fill the whole sculpt mask (0 clears, 1 protects everything).
+   * Undoable; returns the render patch of changed vertices.
+   */
+  maskFill(value: number): SculptPatch {
+    this.ensureAlive();
+    return wasm.sculpt_session_mask_fill(this.id, value);
+  }
+
+  /** Invert the sculpt mask. Undoable; returns the render patch. */
+  maskInvert(): SculptPatch {
+    this.ensureAlive();
+    return wasm.sculpt_session_mask_invert(this.id);
+  }
+
+  /** Current mesh as a new Mesh instance (for committing the sculpt). */
+  toMesh(): Mesh {
+    this.ensureAlive();
+    const buffer = wasm.sculpt_session_mesh_buffer(this.id);
+    if (!buffer.length) {
+      throw new Error("SculptSession: mesh buffer unavailable (session lost)");
+    }
+    return Mesh.fromBuffer(buffer);
+  }
+}