@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.1

package/src/api/core/geom/query/face.ts

@@ -1,508 +1,508 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import {
-  BrepHandle,
-  FaceHandle,
-  EdgeHandle,
-  VertexHandle,
-  HalfEdgeHandle,
-  Vec3Components,
-} from "../../../../handles"
-
-/**
- * Face queries — read the topology and boundary geometry of a single BREP face
- * (all-handle model, §11). A {@linkcode FaceHandle} is minted by walking from a
- * {@linkcode BrepHandle}; it is session-ephemeral and goes stale on
- * undo/redo/re-topologize.
- *
- * Traversals mint fresh child topology handles; position reads return
- * {@linkcode Vec3Components}. Holes are modelled per-loop: {@linkcode PluginGeomQueryFaceApi.listHoles}
- * returns one seed half-edge per hole, and {@linkcode PluginGeomQueryFaceApi.listHoleHalfEdges}
- * returns the full (flat) half-edge loop of one hole by index. No query mutates its inputs.
- *
- * Accessed via `snaptrude.core.geom.query.face`.
- */
-export abstract class PluginGeomQueryFaceApi {
-  constructor() {}
-
-  /**
-   * Get the index of a face within its brep.
-   * @param face The face to query
-   * @returns The index as a `number` (`-1` if unindexed)
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const index = await snaptrude.core.geom.query.face.getIndex(face)
-   * }
-   * ```
-   */
-  public abstract getIndex(face: FaceHandle): PluginApiReturn<number>
-
-  /**
-   * Get the raw (unmapped) material index of a face.
-   * @param face The face to query
-   * @returns The material index as a `number`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const materialIndex = await snaptrude.core.geom.query.face.getMaterialIndex(face)
-   * }
-   * ```
-   */
-  public abstract getMaterialIndex(face: FaceHandle): PluginApiReturn<number>
-
-  /**
-   * Read what KIND of surface a face lies on. This is the one read that tells a
-   * genuinely curved face from a faceted approximation of one: every face of a
-   * 200-triangle "dome" answers `"plane"`, while a real dome has faces
-   * answering `"sphere"`. Use it to confirm a curved solid actually came out
-   * curved.
-   *
-   * | Value | Surface |
-   * |---|---|
-   * | `"plane"` | Flat face |
-   * | `"cylinder"` | Cylindrical face — constant radius about an axis |
-   * | `"cone"` | Conical face — a tapered ring (a cone or frustum side) |
-   * | `"sphere"` | Spherical face |
-   * | `"torus"` | Toroidal face — the ring surface of a donut |
-   * | `"spline"` | Free-form NURBS face |
-   *
-   * Pure read: no geometry kernel is loaded.
-   *
-   * @param face The face to query
-   * @returns The surface kind (see the table), or `null` when the face carries
-   *   no surface classification
-   *
-   * @examplePrompt Is this face flat or curved?
-   * @examplePrompt Check that this dome is a real sphere, not a faceted approximation
-   * @examplePrompt What kind of surface is this face?
-   * @examplePrompt How many curved faces does this mass have?
-   *
-   * # Example
-   * ```ts
-   * const [mass] = await snaptrude.design.query.listMasses()
-   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
-   * if (brep) {
-   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const kinds = []
-   *   for (const face of faces) kinds.push(await snaptrude.core.geom.query.face.getSurfaceKind(face))
-   *   console.log("spherical faces:", kinds.filter((k) => k === "sphere").length)
-   * }
-   * ```
-   */
-  public abstract getSurfaceKind(
-    face: FaceHandle,
-  ): PluginApiReturn<"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null>
-
-  /**
-   * Get a seed half-edge of a face's outer loop.
-   * @param face The face to query
-   * @returns The half-edge as a {@linkcode HalfEdgeHandle}, or `null` for a degenerate face
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const seed = await snaptrude.core.geom.query.face.getHalfEdge(face)
-   *   if (seed) {
-   *     const next = await snaptrude.core.geom.query.halfedge.getNext(seed)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getHalfEdge(face: FaceHandle): PluginApiReturn<HalfEdgeHandle | null>
-
-  /**
-   * List the edges of a face's outer loop.
-   * @param face The face to query
-   * @returns The edges as {@linkcode EdgeHandle}`[]`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const edges = await snaptrude.core.geom.query.face.listEdges(face)
-   * }
-   * ```
-   */
-  public abstract listEdges(face: FaceHandle): PluginApiReturn<EdgeHandle[]>
-
-  /**
-   * List the half-edges of a face's outer loop.
-   * @param face The face to query
-   * @returns The half-edges as {@linkcode HalfEdgeHandle}`[]`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const halfEdges = await snaptrude.core.geom.query.face.listHalfEdges(face)
-   * }
-   * ```
-   */
-  public abstract listHalfEdges(face: FaceHandle): PluginApiReturn<HalfEdgeHandle[]>
-
-  /**
-   * List the vertices of a face's outer loop.
-   * @param face The face to query
-   * @returns The vertices as {@linkcode VertexHandle}`[]`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const vertices = await snaptrude.core.geom.query.face.listVertices(face)
-   * }
-   * ```
-   */
-  public abstract listVertices(face: FaceHandle): PluginApiReturn<VertexHandle[]>
-
-  /**
-   * List a face's holes as one seed half-edge per hole loop.
-   * @param face The face to query
-   * @returns The hole seeds as {@linkcode HalfEdgeHandle}`[]`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const holeSeeds = await snaptrude.core.geom.query.face.listHoles(face)
-   *   console.log("holes in this face:", holeSeeds.length)
-   * }
-   * ```
-   */
-  public abstract listHoles(face: FaceHandle): PluginApiReturn<HalfEdgeHandle[]>
-
-  /**
-   * Get the number of holes in a face.
-   * @param face The face to query
-   * @returns The hole count as a `number`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const holeCount = await snaptrude.core.geom.query.face.getHoleCount(face)
-   * }
-   * ```
-   */
-  public abstract getHoleCount(face: FaceHandle): PluginApiReturn<number>
-
-  /**
-   * List the half-edge loop of one hole of a face (by hole index).
-   * @param face The face to query
-   * @param holeIndex Index of the hole (`0..getHoleCount-1`)
-   * @returns The hole's half-edges as {@linkcode HalfEdgeHandle}`[]` (`[]` if the index is out of range)
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const holeCount = await snaptrude.core.geom.query.face.getHoleCount(face)
-   *   if (holeCount > 0) {
-   *     const loop = await snaptrude.core.geom.query.face.listHoleHalfEdges(face, 0)
-   *   }
-   * }
-   * ```
-   */
-  public abstract listHoleHalfEdges(
-    face: FaceHandle,
-    holeIndex: number,
-  ): PluginApiReturn<HalfEdgeHandle[]>
-
-  /**
-   * Test whether a face has any holes.
-   * @param face The face to query
-   * @returns `true` if the face has at least one hole, otherwise `false`
-   *
-   * @examplePrompt Does this face have any holes cut into it?
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const pierced = await snaptrude.core.geom.query.face.hasHoles(face)
-   * }
-   * ```
-   */
-  public abstract hasHoles(face: FaceHandle): PluginApiReturn<boolean>
-
-  /**
-   * Get the seed half-edge of the hole loop containing a given half-edge.
-   * @param face The face to query
-   * @param halfEdge The half-edge to locate
-   * @returns The hole seed as a {@linkcode HalfEdgeHandle}, or `null` if not in any hole
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const [he] = await snaptrude.core.geom.query.face.listHoleHalfEdges(face, 0)
-   *   if (he) {
-   *     const seed = await snaptrude.core.geom.query.face.getHoleContainingHalfEdge(face, he)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getHoleContainingHalfEdge(
-    face: FaceHandle,
-    halfEdge: HalfEdgeHandle,
-  ): PluginApiReturn<HalfEdgeHandle | null>
-
-  /**
-   * List the positions of a face's outer-loop vertices (needs the parent brep for coordinates).
-   * @param face The face to query
-   * @param brep The parent brep (source of vertex coordinates)
-   * @returns The positions as {@linkcode Vec3Components}`[]`
-   *
-   * @examplePrompt What are the corner coordinates of this face?
-   * @examplePrompt Get the boundary points of the selected face
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const corners = await snaptrude.core.geom.query.face.listVertexPositions(face, brep)
-   *   for (const p of corners) console.log(p.x, p.y, p.z)
-   * }
-   * ```
-   */
-  public abstract listVertexPositions(
-    face: FaceHandle,
-    brep: BrepHandle,
-  ): PluginApiReturn<Vec3Components[]>
-
-  /**
-   * Exact surface area of one face of `brep`, in internal length units SQUARED —
-   * integrated off the face's own surface, not its facets, so a curved patch
-   * reads exactly rather than as its triangles. Needs the parent brep: a face
-   * handle cannot name its own solid.
-   * @param face The face to measure
-   * @param brep The parent brep (owner last, as in
-   *   {@linkcode PluginGeomQueryFaceApi.listVertexPositions})
-   * @returns The area as a `number`
-   * @throws VALIDATION if `face` is not a face of `brep`
-   * @throws OPERATION_FAILED if the kernel could not measure the face
-   *
-   * @examplePrompt How big is this roof patch?
-   * @examplePrompt Which face of this mass has the largest area?
-   *
-   * # Example
-   * ```ts
-   * const [mass] = await snaptrude.design.query.listMasses()
-   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
-   * if (brep) {
-   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const areas = await Promise.all(
-   *     faces.map((f) => snaptrude.core.geom.query.face.getArea(f, brep)),
-   *   )
-   * }
-   * ```
-   */
-  public abstract getArea(face: FaceHandle, brep: BrepHandle): PluginApiReturn<number>
-
-  /**
-   * Centre of area of one face of `brep`, as a point in that brep's frame
-   * (internal length units). On a solid whose every face reads `"spline"` this
-   * is the read that tells two patches apart — the top of a thickened patch from
-   * its bottom, one quarter of a closed surface from the next.
-   * @param face The face to measure
-   * @param brep The parent brep (owner last)
-   * @returns The centroid as {@linkcode Vec3Components}
-   * @throws VALIDATION if `face` is not a face of `brep`
-   * @throws OPERATION_FAILED if the kernel could not measure the face
-   *
-   * @examplePrompt Where is the middle of this face?
-   * @examplePrompt Pick the topmost face of this curved mass
-   *
-   * # Example
-   * ```ts
-   * const centre = await snaptrude.core.geom.query.face.getCentroid(face, brep)
-   * ```
-   */
-  public abstract getCentroid(face: FaceHandle, brep: BrepHandle): PluginApiReturn<Vec3Components>
-
-  /**
-   * List the tessellated boundary points of a face's outer loop (arcs sampled,
-   * sense-corrected). Not cardinality-equal to {@linkcode PluginGeomQueryFaceApi.listVertexPositions}.
-   * @param face The face to query
-   * @returns The boundary points as {@linkcode Vec3Components}`[]`
-   *
-   * @examplePrompt Trace the outline of this face including its curved edges
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const outline = await snaptrude.core.geom.query.face.listVertexPositionsWithCurves(face)
-   * }
-   * ```
-   */
-  public abstract listVertexPositionsWithCurves(
-    face: FaceHandle,
-  ): PluginApiReturn<Vec3Components[]>
-
-  /**
-   * List the faces adjacent to a face (sharing an edge). Boundary edges are skipped.
-   * @param face The face to query
-   * @returns The adjacent faces as {@linkcode FaceHandle}`[]`
-   *
-   * @examplePrompt Which faces are next to this one?
-   * @examplePrompt Find the faces that share an edge with the selected face
-   *
-   * # Example
-   * ```ts
-   * const [mass] = await snaptrude.design.query.listMasses()
-   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
-   * if (brep) {
-   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
-   *   const neighbours = await snaptrude.core.geom.query.face.listAdjacentFaces(face)
-   * }
-   * ```
-   */
-  public abstract listAdjacentFaces(face: FaceHandle): PluginApiReturn<FaceHandle[]>
-}
-
-const faceArg = z.object({ face: FaceHandle })
-const faceWithBrepArg = z.object({ face: FaceHandle, brep: BrepHandle })
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.getIndex}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceGetIndexArgs = faceArg
-export type PluginGeomQueryFaceGetIndexArgs = z.infer<typeof PluginGeomQueryFaceGetIndexArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.getMaterialIndex}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceGetMaterialIndexArgs = faceArg
-export type PluginGeomQueryFaceGetMaterialIndexArgs = z.infer<
-  typeof PluginGeomQueryFaceGetMaterialIndexArgs
->
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.getSurfaceKind}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceGetSurfaceKindArgs = faceArg
-export type PluginGeomQueryFaceGetSurfaceKindArgs = z.infer<
-  typeof PluginGeomQueryFaceGetSurfaceKindArgs
->
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.getHalfEdge}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceGetHalfEdgeArgs = faceArg
-export type PluginGeomQueryFaceGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryFaceGetHalfEdgeArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.listEdges}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceListEdgesArgs = faceArg
-export type PluginGeomQueryFaceListEdgesArgs = z.infer<typeof PluginGeomQueryFaceListEdgesArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.listHalfEdges}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceListHalfEdgesArgs = faceArg
-export type PluginGeomQueryFaceListHalfEdgesArgs = z.infer<
-  typeof PluginGeomQueryFaceListHalfEdgesArgs
->
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.listVertices}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceListVerticesArgs = faceArg
-export type PluginGeomQueryFaceListVerticesArgs = z.infer<typeof PluginGeomQueryFaceListVerticesArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.listHoles}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceListHolesArgs = faceArg
-export type PluginGeomQueryFaceListHolesArgs = z.infer<typeof PluginGeomQueryFaceListHolesArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.getHoleCount}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceGetHoleCountArgs = faceArg
-export type PluginGeomQueryFaceGetHoleCountArgs = z.infer<typeof PluginGeomQueryFaceGetHoleCountArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryFaceApi.listHoleHalfEdges}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `face` | {@linkcode FaceHandle} | The face to query |
- * | `holeIndex` | `number` | Index of the hole (`0..getHoleCount-1`) |
- */
-export const PluginGeomQueryFaceListHoleHalfEdgesArgs = z.object({
-  face: FaceHandle,
-  holeIndex: z.number(),
-})
-export type PluginGeomQueryFaceListHoleHalfEdgesArgs = z.infer<
-  typeof PluginGeomQueryFaceListHoleHalfEdgesArgs
->
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.hasHoles}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceHasHolesArgs = faceArg
-export type PluginGeomQueryFaceHasHolesArgs = z.infer<typeof PluginGeomQueryFaceHasHolesArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryFaceApi.getHoleContainingHalfEdge}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `face` | {@linkcode FaceHandle} | The face to query |
- * | `halfEdge` | {@linkcode HalfEdgeHandle} | The half-edge to locate |
- */
-export const PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs = z.object({
-  face: FaceHandle,
-  halfEdge: HalfEdgeHandle,
-})
-export type PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs = z.infer<
-  typeof PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomQueryFaceApi.listVertexPositions}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `face` | {@linkcode FaceHandle} | The face to query |
- * | `brep` | {@linkcode BrepHandle} | The parent brep (source of vertex coordinates) |
- */
-export const PluginGeomQueryFaceListVertexPositionsArgs = faceWithBrepArg
-export type PluginGeomQueryFaceListVertexPositionsArgs = z.infer<
-  typeof PluginGeomQueryFaceListVertexPositionsArgs
->
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.getArea}. `{ face: FaceHandle, brep: BrepHandle }` */
-export const PluginGeomQueryFaceGetAreaArgs = faceWithBrepArg
-export type PluginGeomQueryFaceGetAreaArgs = z.infer<typeof PluginGeomQueryFaceGetAreaArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.getCentroid}. `{ face: FaceHandle, brep: BrepHandle }` */
-export const PluginGeomQueryFaceGetCentroidArgs = faceWithBrepArg
-export type PluginGeomQueryFaceGetCentroidArgs = z.infer<typeof PluginGeomQueryFaceGetCentroidArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.listVertexPositionsWithCurves}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = faceArg
-export type PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = z.infer<
-  typeof PluginGeomQueryFaceListVertexPositionsWithCurvesArgs
->
-
-/** Arguments for {@linkcode PluginGeomQueryFaceApi.listAdjacentFaces}. `{ face: FaceHandle }` */
-export const PluginGeomQueryFaceListAdjacentFacesArgs = faceArg
-export type PluginGeomQueryFaceListAdjacentFacesArgs = z.infer<
-  typeof PluginGeomQueryFaceListAdjacentFacesArgs
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  BrepHandle,
+  FaceHandle,
+  EdgeHandle,
+  VertexHandle,
+  HalfEdgeHandle,
+  Vec3Components,
+} from "../../../../handles"
+
+/**
+ * Face queries — read the topology and boundary geometry of a single BREP face
+ * (all-handle model, §11). A {@linkcode FaceHandle} is minted by walking from a
+ * {@linkcode BrepHandle}; it is session-ephemeral and goes stale on
+ * undo/redo/re-topologize.
+ *
+ * Traversals mint fresh child topology handles; position reads return
+ * {@linkcode Vec3Components}. Holes are modelled per-loop: {@linkcode PluginGeomQueryFaceApi.listHoles}
+ * returns one seed half-edge per hole, and {@linkcode PluginGeomQueryFaceApi.listHoleHalfEdges}
+ * returns the full (flat) half-edge loop of one hole by index. No query mutates its inputs.
+ *
+ * Accessed via `snaptrude.core.geom.query.face`.
+ */
+export abstract class PluginGeomQueryFaceApi {
+  constructor() {}
+
+  /**
+   * Get the index of a face within its brep.
+   * @param face The face to query
+   * @returns The index as a `number` (`-1` if unindexed)
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const index = await snaptrude.core.geom.query.face.getIndex(face)
+   * }
+   * ```
+   */
+  public abstract getIndex(face: FaceHandle): PluginApiReturn<number>
+
+  /**
+   * Get the raw (unmapped) material index of a face.
+   * @param face The face to query
+   * @returns The material index as a `number`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const materialIndex = await snaptrude.core.geom.query.face.getMaterialIndex(face)
+   * }
+   * ```
+   */
+  public abstract getMaterialIndex(face: FaceHandle): PluginApiReturn<number>
+
+  /**
+   * Read what KIND of surface a face lies on. This is the one read that tells a
+   * genuinely curved face from a faceted approximation of one: every face of a
+   * 200-triangle "dome" answers `"plane"`, while a real dome has faces
+   * answering `"sphere"`. Use it to confirm a curved solid actually came out
+   * curved.
+   *
+   * | Value | Surface |
+   * |---|---|
+   * | `"plane"` | Flat face |
+   * | `"cylinder"` | Cylindrical face — constant radius about an axis |
+   * | `"cone"` | Conical face — a tapered ring (a cone or frustum side) |
+   * | `"sphere"` | Spherical face |
+   * | `"torus"` | Toroidal face — the ring surface of a donut |
+   * | `"spline"` | Free-form NURBS face |
+   *
+   * Pure read: no geometry kernel is loaded.
+   *
+   * @param face The face to query
+   * @returns The surface kind (see the table), or `null` when the face carries
+   *   no surface classification
+   *
+   * @examplePrompt Is this face flat or curved?
+   * @examplePrompt Check that this dome is a real sphere, not a faceted approximation
+   * @examplePrompt What kind of surface is this face?
+   * @examplePrompt How many curved faces does this mass have?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const kinds = []
+   *   for (const face of faces) kinds.push(await snaptrude.core.geom.query.face.getSurfaceKind(face))
+   *   console.log("spherical faces:", kinds.filter((k) => k === "sphere").length)
+   * }
+   * ```
+   */
+  public abstract getSurfaceKind(
+    face: FaceHandle,
+  ): PluginApiReturn<"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null>
+
+  /**
+   * Get a seed half-edge of a face's outer loop.
+   * @param face The face to query
+   * @returns The half-edge as a {@linkcode HalfEdgeHandle}, or `null` for a degenerate face
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const seed = await snaptrude.core.geom.query.face.getHalfEdge(face)
+   *   if (seed) {
+   *     const next = await snaptrude.core.geom.query.halfedge.getNext(seed)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getHalfEdge(face: FaceHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * List the edges of a face's outer loop.
+   * @param face The face to query
+   * @returns The edges as {@linkcode EdgeHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const edges = await snaptrude.core.geom.query.face.listEdges(face)
+   * }
+   * ```
+   */
+  public abstract listEdges(face: FaceHandle): PluginApiReturn<EdgeHandle[]>
+
+  /**
+   * List the half-edges of a face's outer loop.
+   * @param face The face to query
+   * @returns The half-edges as {@linkcode HalfEdgeHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const halfEdges = await snaptrude.core.geom.query.face.listHalfEdges(face)
+   * }
+   * ```
+   */
+  public abstract listHalfEdges(face: FaceHandle): PluginApiReturn<HalfEdgeHandle[]>
+
+  /**
+   * List the vertices of a face's outer loop.
+   * @param face The face to query
+   * @returns The vertices as {@linkcode VertexHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const vertices = await snaptrude.core.geom.query.face.listVertices(face)
+   * }
+   * ```
+   */
+  public abstract listVertices(face: FaceHandle): PluginApiReturn<VertexHandle[]>
+
+  /**
+   * List a face's holes as one seed half-edge per hole loop.
+   * @param face The face to query
+   * @returns The hole seeds as {@linkcode HalfEdgeHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const holeSeeds = await snaptrude.core.geom.query.face.listHoles(face)
+   *   console.log("holes in this face:", holeSeeds.length)
+   * }
+   * ```
+   */
+  public abstract listHoles(face: FaceHandle): PluginApiReturn<HalfEdgeHandle[]>
+
+  /**
+   * Get the number of holes in a face.
+   * @param face The face to query
+   * @returns The hole count as a `number`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const holeCount = await snaptrude.core.geom.query.face.getHoleCount(face)
+   * }
+   * ```
+   */
+  public abstract getHoleCount(face: FaceHandle): PluginApiReturn<number>
+
+  /**
+   * List the half-edge loop of one hole of a face (by hole index).
+   * @param face The face to query
+   * @param holeIndex Index of the hole (`0..getHoleCount-1`)
+   * @returns The hole's half-edges as {@linkcode HalfEdgeHandle}`[]` (`[]` if the index is out of range)
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const holeCount = await snaptrude.core.geom.query.face.getHoleCount(face)
+   *   if (holeCount > 0) {
+   *     const loop = await snaptrude.core.geom.query.face.listHoleHalfEdges(face, 0)
+   *   }
+   * }
+   * ```
+   */
+  public abstract listHoleHalfEdges(
+    face: FaceHandle,
+    holeIndex: number,
+  ): PluginApiReturn<HalfEdgeHandle[]>
+
+  /**
+   * Test whether a face has any holes.
+   * @param face The face to query
+   * @returns `true` if the face has at least one hole, otherwise `false`
+   *
+   * @examplePrompt Does this face have any holes cut into it?
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const pierced = await snaptrude.core.geom.query.face.hasHoles(face)
+   * }
+   * ```
+   */
+  public abstract hasHoles(face: FaceHandle): PluginApiReturn<boolean>
+
+  /**
+   * Get the seed half-edge of the hole loop containing a given half-edge.
+   * @param face The face to query
+   * @param halfEdge The half-edge to locate
+   * @returns The hole seed as a {@linkcode HalfEdgeHandle}, or `null` if not in any hole
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const [he] = await snaptrude.core.geom.query.face.listHoleHalfEdges(face, 0)
+   *   if (he) {
+   *     const seed = await snaptrude.core.geom.query.face.getHoleContainingHalfEdge(face, he)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getHoleContainingHalfEdge(
+    face: FaceHandle,
+    halfEdge: HalfEdgeHandle,
+  ): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * List the positions of a face's outer-loop vertices (needs the parent brep for coordinates).
+   * @param face The face to query
+   * @param brep The parent brep (source of vertex coordinates)
+   * @returns The positions as {@linkcode Vec3Components}`[]`
+   *
+   * @examplePrompt What are the corner coordinates of this face?
+   * @examplePrompt Get the boundary points of the selected face
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const corners = await snaptrude.core.geom.query.face.listVertexPositions(face, brep)
+   *   for (const p of corners) console.log(p.x, p.y, p.z)
+   * }
+   * ```
+   */
+  public abstract listVertexPositions(
+    face: FaceHandle,
+    brep: BrepHandle,
+  ): PluginApiReturn<Vec3Components[]>
+
+  /**
+   * Exact surface area of one face of `brep`, in internal length units SQUARED —
+   * integrated off the face's own surface, not its facets, so a curved patch
+   * reads exactly rather than as its triangles. Needs the parent brep: a face
+   * handle cannot name its own solid.
+   * @param face The face to measure
+   * @param brep The parent brep (owner last, as in
+   *   {@linkcode PluginGeomQueryFaceApi.listVertexPositions})
+   * @returns The area as a `number`
+   * @throws VALIDATION if `face` is not a face of `brep`
+   * @throws OPERATION_FAILED if the kernel could not measure the face
+   *
+   * @examplePrompt How big is this roof patch?
+   * @examplePrompt Which face of this mass has the largest area?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const areas = await Promise.all(
+   *     faces.map((f) => snaptrude.core.geom.query.face.getArea(f, brep)),
+   *   )
+   * }
+   * ```
+   */
+  public abstract getArea(face: FaceHandle, brep: BrepHandle): PluginApiReturn<number>
+
+  /**
+   * Centre of area of one face of `brep`, as a point in that brep's frame
+   * (internal length units). On a solid whose every face reads `"spline"` this
+   * is the read that tells two patches apart — the top of a thickened patch from
+   * its bottom, one quarter of a closed surface from the next.
+   * @param face The face to measure
+   * @param brep The parent brep (owner last)
+   * @returns The centroid as {@linkcode Vec3Components}
+   * @throws VALIDATION if `face` is not a face of `brep`
+   * @throws OPERATION_FAILED if the kernel could not measure the face
+   *
+   * @examplePrompt Where is the middle of this face?
+   * @examplePrompt Pick the topmost face of this curved mass
+   *
+   * # Example
+   * ```ts
+   * const centre = await snaptrude.core.geom.query.face.getCentroid(face, brep)
+   * ```
+   */
+  public abstract getCentroid(face: FaceHandle, brep: BrepHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * List the tessellated boundary points of a face's outer loop (arcs sampled,
+   * sense-corrected). Not cardinality-equal to {@linkcode PluginGeomQueryFaceApi.listVertexPositions}.
+   * @param face The face to query
+   * @returns The boundary points as {@linkcode Vec3Components}`[]`
+   *
+   * @examplePrompt Trace the outline of this face including its curved edges
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const outline = await snaptrude.core.geom.query.face.listVertexPositionsWithCurves(face)
+   * }
+   * ```
+   */
+  public abstract listVertexPositionsWithCurves(
+    face: FaceHandle,
+  ): PluginApiReturn<Vec3Components[]>
+
+  /**
+   * List the faces adjacent to a face (sharing an edge). Boundary edges are skipped.
+   * @param face The face to query
+   * @returns The adjacent faces as {@linkcode FaceHandle}`[]`
+   *
+   * @examplePrompt Which faces are next to this one?
+   * @examplePrompt Find the faces that share an edge with the selected face
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const [face] = await snaptrude.core.geom.query.brep.listFaces(brep)
+   *   const neighbours = await snaptrude.core.geom.query.face.listAdjacentFaces(face)
+   * }
+   * ```
+   */
+  public abstract listAdjacentFaces(face: FaceHandle): PluginApiReturn<FaceHandle[]>
+}
+
+const faceArg = z.object({ face: FaceHandle })
+const faceWithBrepArg = z.object({ face: FaceHandle, brep: BrepHandle })
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getIndex}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceGetIndexArgs = faceArg
+export type PluginGeomQueryFaceGetIndexArgs = z.infer<typeof PluginGeomQueryFaceGetIndexArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getMaterialIndex}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceGetMaterialIndexArgs = faceArg
+export type PluginGeomQueryFaceGetMaterialIndexArgs = z.infer<
+  typeof PluginGeomQueryFaceGetMaterialIndexArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getSurfaceKind}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceGetSurfaceKindArgs = faceArg
+export type PluginGeomQueryFaceGetSurfaceKindArgs = z.infer<
+  typeof PluginGeomQueryFaceGetSurfaceKindArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getHalfEdge}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceGetHalfEdgeArgs = faceArg
+export type PluginGeomQueryFaceGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryFaceGetHalfEdgeArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.listEdges}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceListEdgesArgs = faceArg
+export type PluginGeomQueryFaceListEdgesArgs = z.infer<typeof PluginGeomQueryFaceListEdgesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.listHalfEdges}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceListHalfEdgesArgs = faceArg
+export type PluginGeomQueryFaceListHalfEdgesArgs = z.infer<
+  typeof PluginGeomQueryFaceListHalfEdgesArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.listVertices}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceListVerticesArgs = faceArg
+export type PluginGeomQueryFaceListVerticesArgs = z.infer<typeof PluginGeomQueryFaceListVerticesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.listHoles}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceListHolesArgs = faceArg
+export type PluginGeomQueryFaceListHolesArgs = z.infer<typeof PluginGeomQueryFaceListHolesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getHoleCount}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceGetHoleCountArgs = faceArg
+export type PluginGeomQueryFaceGetHoleCountArgs = z.infer<typeof PluginGeomQueryFaceGetHoleCountArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryFaceApi.listHoleHalfEdges}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `face` | {@linkcode FaceHandle} | The face to query |
+ * | `holeIndex` | `number` | Index of the hole (`0..getHoleCount-1`) |
+ */
+export const PluginGeomQueryFaceListHoleHalfEdgesArgs = z.object({
+  face: FaceHandle,
+  holeIndex: z.number(),
+})
+export type PluginGeomQueryFaceListHoleHalfEdgesArgs = z.infer<
+  typeof PluginGeomQueryFaceListHoleHalfEdgesArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.hasHoles}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceHasHolesArgs = faceArg
+export type PluginGeomQueryFaceHasHolesArgs = z.infer<typeof PluginGeomQueryFaceHasHolesArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryFaceApi.getHoleContainingHalfEdge}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `face` | {@linkcode FaceHandle} | The face to query |
+ * | `halfEdge` | {@linkcode HalfEdgeHandle} | The half-edge to locate |
+ */
+export const PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs = z.object({
+  face: FaceHandle,
+  halfEdge: HalfEdgeHandle,
+})
+export type PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs = z.infer<
+  typeof PluginGeomQueryFaceGetHoleContainingHalfEdgeArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryFaceApi.listVertexPositions}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `face` | {@linkcode FaceHandle} | The face to query |
+ * | `brep` | {@linkcode BrepHandle} | The parent brep (source of vertex coordinates) |
+ */
+export const PluginGeomQueryFaceListVertexPositionsArgs = faceWithBrepArg
+export type PluginGeomQueryFaceListVertexPositionsArgs = z.infer<
+  typeof PluginGeomQueryFaceListVertexPositionsArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getArea}. `{ face: FaceHandle, brep: BrepHandle }` */
+export const PluginGeomQueryFaceGetAreaArgs = faceWithBrepArg
+export type PluginGeomQueryFaceGetAreaArgs = z.infer<typeof PluginGeomQueryFaceGetAreaArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.getCentroid}. `{ face: FaceHandle, brep: BrepHandle }` */
+export const PluginGeomQueryFaceGetCentroidArgs = faceWithBrepArg
+export type PluginGeomQueryFaceGetCentroidArgs = z.infer<typeof PluginGeomQueryFaceGetCentroidArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.listVertexPositionsWithCurves}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = faceArg
+export type PluginGeomQueryFaceListVertexPositionsWithCurvesArgs = z.infer<
+  typeof PluginGeomQueryFaceListVertexPositionsWithCurvesArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryFaceApi.listAdjacentFaces}. `{ face: FaceHandle }` */
+export const PluginGeomQueryFaceListAdjacentFacesArgs = faceArg
+export type PluginGeomQueryFaceListAdjacentFacesArgs = z.infer<
+  typeof PluginGeomQueryFaceListAdjacentFacesArgs
+>