@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

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

@@ -1,210 +1,210 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import { HalfEdgeHandle, VertexHandle, EdgeHandle, FaceHandle } from "../../../../handles"
-
-/**
- * Half-edge queries — walk and read a single BREP half-edge (all-handle model, §11).
- * A {@linkcode HalfEdgeHandle} is minted by walking from a brep/face/edge/vertex
- * handle; it is session-ephemeral and goes stale on undo/redo/re-topologize.
- *
- * The kind token is all-lowercase `"halfedge"` (§6.1 — no camelCase namespaces).
- * Traversals (`getNext`/`getPrev`/`getFlip`) return `null` on a boundary or a
- * malformed chain rather than throwing (§6, reads never throw).
- *
- * Accessed via `snaptrude.core.geom.query.halfedge`.
- */
-export abstract class PluginGeomQueryHalfEdgeApi {
-  constructor() {}
-
-  /**
-   * Get the next half-edge around the face loop.
-   * @param halfEdge The half-edge to walk from
-   * @returns The next half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a malformed chain
-   *
-   * # 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.listHalfEdges(face)
-   *   const next = await snaptrude.core.geom.query.halfedge.getNext(he)
-   *   if (next) {
-   *     const vertex = await snaptrude.core.geom.query.halfedge.getVertex(next)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getNext(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
-
-  /**
-   * Get the previous half-edge around the face loop.
-   * @param halfEdge The half-edge to walk from
-   * @returns The previous half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a malformed chain
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
-   *   const prev = await snaptrude.core.geom.query.halfedge.getPrev(he)
-   *   if (prev) {
-   *     const edge = await snaptrude.core.geom.query.halfedge.getEdge(prev)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getPrev(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
-
-  /**
-   * Get the flip (opposite) half-edge of the shared edge.
-   * @param halfEdge The half-edge to flip
-   * @returns The flip half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a boundary
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
-   *   const flip = await snaptrude.core.geom.query.halfedge.getFlip(he)
-   *   if (flip) {
-   *     // cross the shared edge into the neighbouring face
-   *     const neighbourFace = await snaptrude.core.geom.query.halfedge.getFace(flip)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getFlip(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
-
-  /**
-   * Get the tail vertex of a half-edge.
-   * @param halfEdge The half-edge to read
-   * @returns The vertex as a {@linkcode VertexHandle}
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
-   *   const vertex = await snaptrude.core.geom.query.halfedge.getVertex(he)
-   *   const pos = await snaptrude.core.geom.query.vertex.getPosition(brep, vertex)
-   * }
-   * ```
-   */
-  public abstract getVertex(halfEdge: HalfEdgeHandle): PluginApiReturn<VertexHandle>
-
-  /**
-   * Get the edge of a half-edge.
-   * @param halfEdge The half-edge to read
-   * @returns The edge as an {@linkcode EdgeHandle}
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
-   *   const edge = await snaptrude.core.geom.query.halfedge.getEdge(he)
-   *   const faces = await snaptrude.core.geom.query.edge.listFaces(edge)
-   * }
-   * ```
-   */
-  public abstract getEdge(halfEdge: HalfEdgeHandle): PluginApiReturn<EdgeHandle>
-
-  /**
-   * Get the face of a half-edge.
-   * @param halfEdge The half-edge to read
-   * @returns The face as a {@linkcode FaceHandle}
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
-   *   const face = await snaptrude.core.geom.query.halfedge.getFace(he)
-   *   const index = await snaptrude.core.geom.query.face.getIndex(face)
-   * }
-   * ```
-   */
-  public abstract getFace(halfEdge: HalfEdgeHandle): PluginApiReturn<FaceHandle>
-
-  /**
-   * Test whether a half-edge lies on the brep boundary (has no flip).
-   * @param halfEdge The half-edge to test
-   * @returns `true` if on the boundary, otherwise `false`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const halfEdges = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
-   *   let boundary = 0
-   *   for (const he of halfEdges) {
-   *     if (await snaptrude.core.geom.query.halfedge.isOnBoundary(he)) boundary++
-   *   }
-   *   console.log("boundary half-edges:", boundary)
-   * }
-   * ```
-   */
-  public abstract isOnBoundary(halfEdge: HalfEdgeHandle): PluginApiReturn<boolean>
-
-  /**
-   * Test whether a half-edge is the forward (primary) half-edge of its edge —
-   * i.e. `edge.getHalfEdge() === thisHalfEdge`.
-   * @param halfEdge The half-edge to test
-   * @returns `true` if forward, otherwise `false`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
-   *   const forward = await snaptrude.core.geom.query.halfedge.isForward(he)
-   *   console.log(forward ? "primary half-edge" : "flip half-edge")
-   * }
-   * ```
-   */
-  public abstract isForward(halfEdge: HalfEdgeHandle): PluginApiReturn<boolean>
-}
-
-const heArg = z.object({ halfEdge: HalfEdgeHandle })
-
-/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getNext}. `{ halfEdge: HalfEdgeHandle }` */
-export const PluginGeomQueryHalfEdgeGetNextArgs = heArg
-export type PluginGeomQueryHalfEdgeGetNextArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetNextArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getPrev}. `{ halfEdge: HalfEdgeHandle }` */
-export const PluginGeomQueryHalfEdgeGetPrevArgs = heArg
-export type PluginGeomQueryHalfEdgeGetPrevArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetPrevArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getFlip}. `{ halfEdge: HalfEdgeHandle }` */
-export const PluginGeomQueryHalfEdgeGetFlipArgs = heArg
-export type PluginGeomQueryHalfEdgeGetFlipArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetFlipArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getVertex}. `{ halfEdge: HalfEdgeHandle }` */
-export const PluginGeomQueryHalfEdgeGetVertexArgs = heArg
-export type PluginGeomQueryHalfEdgeGetVertexArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetVertexArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getEdge}. `{ halfEdge: HalfEdgeHandle }` */
-export const PluginGeomQueryHalfEdgeGetEdgeArgs = heArg
-export type PluginGeomQueryHalfEdgeGetEdgeArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetEdgeArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getFace}. `{ halfEdge: HalfEdgeHandle }` */
-export const PluginGeomQueryHalfEdgeGetFaceArgs = heArg
-export type PluginGeomQueryHalfEdgeGetFaceArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetFaceArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.isOnBoundary}. `{ halfEdge: HalfEdgeHandle }` */
-export const PluginGeomQueryHalfEdgeIsOnBoundaryArgs = heArg
-export type PluginGeomQueryHalfEdgeIsOnBoundaryArgs = z.infer<
-  typeof PluginGeomQueryHalfEdgeIsOnBoundaryArgs
->
-
-/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.isForward}. `{ halfEdge: HalfEdgeHandle }` */
-export const PluginGeomQueryHalfEdgeIsForwardArgs = heArg
-export type PluginGeomQueryHalfEdgeIsForwardArgs = z.infer<typeof PluginGeomQueryHalfEdgeIsForwardArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { HalfEdgeHandle, VertexHandle, EdgeHandle, FaceHandle } from "../../../../handles"
+
+/**
+ * Half-edge queries — walk and read a single BREP half-edge (all-handle model, §11).
+ * A {@linkcode HalfEdgeHandle} is minted by walking from a brep/face/edge/vertex
+ * handle; it is session-ephemeral and goes stale on undo/redo/re-topologize.
+ *
+ * The kind token is all-lowercase `"halfedge"` (§6.1 — no camelCase namespaces).
+ * Traversals (`getNext`/`getPrev`/`getFlip`) return `null` on a boundary or a
+ * malformed chain rather than throwing (§6, reads never throw).
+ *
+ * Accessed via `snaptrude.core.geom.query.halfedge`.
+ */
+export abstract class PluginGeomQueryHalfEdgeApi {
+  constructor() {}
+
+  /**
+   * Get the next half-edge around the face loop.
+   * @param halfEdge The half-edge to walk from
+   * @returns The next half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a malformed chain
+   *
+   * # 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.listHalfEdges(face)
+   *   const next = await snaptrude.core.geom.query.halfedge.getNext(he)
+   *   if (next) {
+   *     const vertex = await snaptrude.core.geom.query.halfedge.getVertex(next)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getNext(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * Get the previous half-edge around the face loop.
+   * @param halfEdge The half-edge to walk from
+   * @returns The previous half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a malformed chain
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const prev = await snaptrude.core.geom.query.halfedge.getPrev(he)
+   *   if (prev) {
+   *     const edge = await snaptrude.core.geom.query.halfedge.getEdge(prev)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getPrev(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * Get the flip (opposite) half-edge of the shared edge.
+   * @param halfEdge The half-edge to flip
+   * @returns The flip half-edge as a {@linkcode HalfEdgeHandle}, or `null` on a boundary
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const flip = await snaptrude.core.geom.query.halfedge.getFlip(he)
+   *   if (flip) {
+   *     // cross the shared edge into the neighbouring face
+   *     const neighbourFace = await snaptrude.core.geom.query.halfedge.getFace(flip)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getFlip(halfEdge: HalfEdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * Get the tail vertex of a half-edge.
+   * @param halfEdge The half-edge to read
+   * @returns The vertex as a {@linkcode VertexHandle}
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const vertex = await snaptrude.core.geom.query.halfedge.getVertex(he)
+   *   const pos = await snaptrude.core.geom.query.vertex.getPosition(brep, vertex)
+   * }
+   * ```
+   */
+  public abstract getVertex(halfEdge: HalfEdgeHandle): PluginApiReturn<VertexHandle>
+
+  /**
+   * Get the edge of a half-edge.
+   * @param halfEdge The half-edge to read
+   * @returns The edge as an {@linkcode EdgeHandle}
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const edge = await snaptrude.core.geom.query.halfedge.getEdge(he)
+   *   const faces = await snaptrude.core.geom.query.edge.listFaces(edge)
+   * }
+   * ```
+   */
+  public abstract getEdge(halfEdge: HalfEdgeHandle): PluginApiReturn<EdgeHandle>
+
+  /**
+   * Get the face of a half-edge.
+   * @param halfEdge The half-edge to read
+   * @returns The face as a {@linkcode FaceHandle}
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const face = await snaptrude.core.geom.query.halfedge.getFace(he)
+   *   const index = await snaptrude.core.geom.query.face.getIndex(face)
+   * }
+   * ```
+   */
+  public abstract getFace(halfEdge: HalfEdgeHandle): PluginApiReturn<FaceHandle>
+
+  /**
+   * Test whether a half-edge lies on the brep boundary (has no flip).
+   * @param halfEdge The half-edge to test
+   * @returns `true` if on the boundary, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const halfEdges = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   let boundary = 0
+   *   for (const he of halfEdges) {
+   *     if (await snaptrude.core.geom.query.halfedge.isOnBoundary(he)) boundary++
+   *   }
+   *   console.log("boundary half-edges:", boundary)
+   * }
+   * ```
+   */
+  public abstract isOnBoundary(halfEdge: HalfEdgeHandle): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a half-edge is the forward (primary) half-edge of its edge —
+   * i.e. `edge.getHalfEdge() === thisHalfEdge`.
+   * @param halfEdge The half-edge to test
+   * @returns `true` if forward, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [he] = await snaptrude.core.geom.query.brep.listHalfEdges(brep)
+   *   const forward = await snaptrude.core.geom.query.halfedge.isForward(he)
+   *   console.log(forward ? "primary half-edge" : "flip half-edge")
+   * }
+   * ```
+   */
+  public abstract isForward(halfEdge: HalfEdgeHandle): PluginApiReturn<boolean>
+}
+
+const heArg = z.object({ halfEdge: HalfEdgeHandle })
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getNext}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetNextArgs = heArg
+export type PluginGeomQueryHalfEdgeGetNextArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetNextArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getPrev}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetPrevArgs = heArg
+export type PluginGeomQueryHalfEdgeGetPrevArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetPrevArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getFlip}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetFlipArgs = heArg
+export type PluginGeomQueryHalfEdgeGetFlipArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetFlipArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getVertex}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetVertexArgs = heArg
+export type PluginGeomQueryHalfEdgeGetVertexArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetVertexArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getEdge}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetEdgeArgs = heArg
+export type PluginGeomQueryHalfEdgeGetEdgeArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetEdgeArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.getFace}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeGetFaceArgs = heArg
+export type PluginGeomQueryHalfEdgeGetFaceArgs = z.infer<typeof PluginGeomQueryHalfEdgeGetFaceArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.isOnBoundary}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeIsOnBoundaryArgs = heArg
+export type PluginGeomQueryHalfEdgeIsOnBoundaryArgs = z.infer<
+  typeof PluginGeomQueryHalfEdgeIsOnBoundaryArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryHalfEdgeApi.isForward}. `{ halfEdge: HalfEdgeHandle }` */
+export const PluginGeomQueryHalfEdgeIsForwardArgs = heArg
+export type PluginGeomQueryHalfEdgeIsForwardArgs = z.infer<typeof PluginGeomQueryHalfEdgeIsForwardArgs>

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

@@ -1,63 +1,63 @@
-import { PluginGeomQueryCurveApi } from "./curve"
-import { PluginGeomQueryArcApi } from "./arc"
-import { PluginGeomQueryCircleApi } from "./circle"
-import { PluginGeomQueryProfileApi } from "./profile"
-import { PluginGeomQueryContourApi } from "./contour"
-import { PluginGeomQueryBrepApi } from "./brep"
-import { PluginGeomQueryFaceApi } from "./face"
-import { PluginGeomQueryEdgeApi } from "./edge"
-import { PluginGeomQueryHalfEdgeApi } from "./halfedge"
-import { PluginGeomQueryVertexApi } from "./vertex"
-
-/**
- * Geometry-kernel query namespace — read geometry, topology, and relationships as
- * plain values / child handles (all-handle model, §11). No query mutates its inputs.
- *
- * - {@linkcode PluginGeomQueryApi.curve} — shared line/arc queries + two-curve relationships
- * - {@linkcode PluginGeomQueryApi.arc} — arc-specific reads
- * - {@linkcode PluginGeomQueryApi.circle} — circle-specific reads
- * - {@linkcode PluginGeomQueryApi.profile} — profile reads
- * - {@linkcode PluginGeomQueryApi.contour} — contour reads (outer profile + holes)
- * - {@linkcode PluginGeomQueryApi.brep} — BREP mesh topology + geometry
- * - {@linkcode PluginGeomQueryApi.face} — BREP face reads
- * - {@linkcode PluginGeomQueryApi.edge} — BREP edge reads
- * - {@linkcode PluginGeomQueryApi.halfedge} — BREP half-edge walks
- * - {@linkcode PluginGeomQueryApi.vertex} — BREP vertex reads
- *
- * Accessed via `snaptrude.core.geom.query`.
- */
-export abstract class PluginGeomQueryApi {
-  /** Shared curve queries (line or arc) and relationships. See {@linkcode PluginGeomQueryCurveApi}. */
-  public abstract curve: PluginGeomQueryCurveApi
-  /** Arc-specific queries. See {@linkcode PluginGeomQueryArcApi}. */
-  public abstract arc: PluginGeomQueryArcApi
-  /** Circle-specific queries. See {@linkcode PluginGeomQueryCircleApi}. */
-  public abstract circle: PluginGeomQueryCircleApi
-  /** Profile queries. See {@linkcode PluginGeomQueryProfileApi}. */
-  public abstract profile: PluginGeomQueryProfileApi
-  /** Contour queries. See {@linkcode PluginGeomQueryContourApi}. */
-  public abstract contour: PluginGeomQueryContourApi
-  /** BREP mesh topology + geometry queries. See {@linkcode PluginGeomQueryBrepApi}. */
-  public abstract brep: PluginGeomQueryBrepApi
-  /** BREP face queries. See {@linkcode PluginGeomQueryFaceApi}. */
-  public abstract face: PluginGeomQueryFaceApi
-  /** BREP edge queries. See {@linkcode PluginGeomQueryEdgeApi}. */
-  public abstract edge: PluginGeomQueryEdgeApi
-  /** BREP half-edge walks. See {@linkcode PluginGeomQueryHalfEdgeApi}. */
-  public abstract halfedge: PluginGeomQueryHalfEdgeApi
-  /** BREP vertex queries. See {@linkcode PluginGeomQueryVertexApi}. */
-  public abstract vertex: PluginGeomQueryVertexApi
-
-  constructor() {}
-}
-
-export * from "./curve"
-export * from "./arc"
-export * from "./circle"
-export * from "./profile"
-export * from "./contour"
-export * from "./brep"
-export * from "./face"
-export * from "./edge"
-export * from "./halfedge"
-export * from "./vertex"
+import { PluginGeomQueryCurveApi } from "./curve"
+import { PluginGeomQueryArcApi } from "./arc"
+import { PluginGeomQueryCircleApi } from "./circle"
+import { PluginGeomQueryProfileApi } from "./profile"
+import { PluginGeomQueryContourApi } from "./contour"
+import { PluginGeomQueryBrepApi } from "./brep"
+import { PluginGeomQueryFaceApi } from "./face"
+import { PluginGeomQueryEdgeApi } from "./edge"
+import { PluginGeomQueryHalfEdgeApi } from "./halfedge"
+import { PluginGeomQueryVertexApi } from "./vertex"
+
+/**
+ * Geometry-kernel query namespace — read geometry, topology, and relationships as
+ * plain values / child handles (all-handle model, §11). No query mutates its inputs.
+ *
+ * - {@linkcode PluginGeomQueryApi.curve} — shared line/arc queries + two-curve relationships
+ * - {@linkcode PluginGeomQueryApi.arc} — arc-specific reads
+ * - {@linkcode PluginGeomQueryApi.circle} — circle-specific reads
+ * - {@linkcode PluginGeomQueryApi.profile} — profile reads
+ * - {@linkcode PluginGeomQueryApi.contour} — contour reads (outer profile + holes)
+ * - {@linkcode PluginGeomQueryApi.brep} — BREP mesh topology + geometry
+ * - {@linkcode PluginGeomQueryApi.face} — BREP face reads
+ * - {@linkcode PluginGeomQueryApi.edge} — BREP edge reads
+ * - {@linkcode PluginGeomQueryApi.halfedge} — BREP half-edge walks
+ * - {@linkcode PluginGeomQueryApi.vertex} — BREP vertex reads
+ *
+ * Accessed via `snaptrude.core.geom.query`.
+ */
+export abstract class PluginGeomQueryApi {
+  /** Shared curve queries (line or arc) and relationships. See {@linkcode PluginGeomQueryCurveApi}. */
+  public abstract curve: PluginGeomQueryCurveApi
+  /** Arc-specific queries. See {@linkcode PluginGeomQueryArcApi}. */
+  public abstract arc: PluginGeomQueryArcApi
+  /** Circle-specific queries. See {@linkcode PluginGeomQueryCircleApi}. */
+  public abstract circle: PluginGeomQueryCircleApi
+  /** Profile queries. See {@linkcode PluginGeomQueryProfileApi}. */
+  public abstract profile: PluginGeomQueryProfileApi
+  /** Contour queries. See {@linkcode PluginGeomQueryContourApi}. */
+  public abstract contour: PluginGeomQueryContourApi
+  /** BREP mesh topology + geometry queries. See {@linkcode PluginGeomQueryBrepApi}. */
+  public abstract brep: PluginGeomQueryBrepApi
+  /** BREP face queries. See {@linkcode PluginGeomQueryFaceApi}. */
+  public abstract face: PluginGeomQueryFaceApi
+  /** BREP edge queries. See {@linkcode PluginGeomQueryEdgeApi}. */
+  public abstract edge: PluginGeomQueryEdgeApi
+  /** BREP half-edge walks. See {@linkcode PluginGeomQueryHalfEdgeApi}. */
+  public abstract halfedge: PluginGeomQueryHalfEdgeApi
+  /** BREP vertex queries. See {@linkcode PluginGeomQueryVertexApi}. */
+  public abstract vertex: PluginGeomQueryVertexApi
+
+  constructor() {}
+}
+
+export * from "./curve"
+export * from "./arc"
+export * from "./circle"
+export * from "./profile"
+export * from "./contour"
+export * from "./brep"
+export * from "./face"
+export * from "./edge"
+export * from "./halfedge"
+export * from "./vertex"