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

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

@@ -1,130 +1,130 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import { EdgeHandle, VertexHandle, HalfEdgeHandle, FaceHandle, CurveHandle } from "../../../../handles"
-
-/**
- * Edge queries — read a single BREP edge's topology and geometry (all-handle model,
- * §11). An {@linkcode EdgeHandle} is minted by walking from a brep/face/vertex handle;
- * it is session-ephemeral and goes stale on undo/redo/re-topologize.
- *
- * Accessed via `snaptrude.core.geom.query.edge`.
- */
-export abstract class PluginGeomQueryEdgeApi {
-  constructor() {}
-
-  /**
-   * Get the index of an edge within its brep.
-   * @param edge The edge 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 [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
-   *   const index = await snaptrude.core.geom.query.edge.getIndex(edge)
-   * }
-   * ```
-   */
-  public abstract getIndex(edge: EdgeHandle): PluginApiReturn<number>
-
-  /**
-   * Get the primary half-edge of an edge.
-   * @param edge The edge to query
-   * @returns The half-edge as a {@linkcode HalfEdgeHandle}, or `null` if uninitialized
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
-   *   const halfEdge = await snaptrude.core.geom.query.edge.getHalfEdge(edge)
-   *   if (halfEdge) {
-   *     const face = await snaptrude.core.geom.query.halfedge.getFace(halfEdge)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getHalfEdge(edge: EdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
-
-  /**
-   * List the two endpoint vertices of an edge.
-   * @param edge The edge to query
-   * @returns The endpoints as {@linkcode VertexHandle}`[]`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
-   *   const [a, b] = await snaptrude.core.geom.query.edge.listVertices(edge)
-   *   const start = await snaptrude.core.geom.query.vertex.getPosition(brep, a)
-   *   const end = await snaptrude.core.geom.query.vertex.getPosition(brep, b)
-   * }
-   * ```
-   */
-  public abstract listVertices(edge: EdgeHandle): PluginApiReturn<VertexHandle[]>
-
-  /**
-   * Get the underlying curve geometry of an edge (a line, arc or spline).
-   * @param edge The edge to query
-   * @returns The curve as a {@linkcode CurveHandle} (`line_`, `arc_` or `spline_`), or `null` if it is a circle or unset
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
-   *   const curve = await snaptrude.core.geom.query.edge.getCurve(edge)
-   *   if (curve) {
-   *     const length = await snaptrude.core.geom.query.curve.getLength(curve)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getCurve(edge: EdgeHandle): PluginApiReturn<CurveHandle | null>
-
-  /**
-   * List the faces bordering an edge (one or two).
-   * @param edge The edge to query
-   * @returns The bordering faces as {@linkcode FaceHandle}`[]`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
-   *   const faces = await snaptrude.core.geom.query.edge.listFaces(edge)
-   *   console.log(faces.length === 1 ? "boundary edge" : "interior edge")
-   * }
-   * ```
-   */
-  public abstract listFaces(edge: EdgeHandle): PluginApiReturn<FaceHandle[]>
-}
-
-const edgeArg = z.object({ edge: EdgeHandle })
-
-/** Arguments for {@linkcode PluginGeomQueryEdgeApi.getIndex}. `{ edge: EdgeHandle }` */
-export const PluginGeomQueryEdgeGetIndexArgs = edgeArg
-export type PluginGeomQueryEdgeGetIndexArgs = z.infer<typeof PluginGeomQueryEdgeGetIndexArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryEdgeApi.getHalfEdge}. `{ edge: EdgeHandle }` */
-export const PluginGeomQueryEdgeGetHalfEdgeArgs = edgeArg
-export type PluginGeomQueryEdgeGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryEdgeGetHalfEdgeArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryEdgeApi.listVertices}. `{ edge: EdgeHandle }` */
-export const PluginGeomQueryEdgeListVerticesArgs = edgeArg
-export type PluginGeomQueryEdgeListVerticesArgs = z.infer<typeof PluginGeomQueryEdgeListVerticesArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryEdgeApi.getCurve}. `{ edge: EdgeHandle }` */
-export const PluginGeomQueryEdgeGetCurveArgs = edgeArg
-export type PluginGeomQueryEdgeGetCurveArgs = z.infer<typeof PluginGeomQueryEdgeGetCurveArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryEdgeApi.listFaces}. `{ edge: EdgeHandle }` */
-export const PluginGeomQueryEdgeListFacesArgs = edgeArg
-export type PluginGeomQueryEdgeListFacesArgs = z.infer<typeof PluginGeomQueryEdgeListFacesArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { EdgeHandle, VertexHandle, HalfEdgeHandle, FaceHandle, CurveHandle } from "../../../../handles"
+
+/**
+ * Edge queries — read a single BREP edge's topology and geometry (all-handle model,
+ * §11). An {@linkcode EdgeHandle} is minted by walking from a brep/face/vertex handle;
+ * it is session-ephemeral and goes stale on undo/redo/re-topologize.
+ *
+ * Accessed via `snaptrude.core.geom.query.edge`.
+ */
+export abstract class PluginGeomQueryEdgeApi {
+  constructor() {}
+
+  /**
+   * Get the index of an edge within its brep.
+   * @param edge The edge 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 [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
+   *   const index = await snaptrude.core.geom.query.edge.getIndex(edge)
+   * }
+   * ```
+   */
+  public abstract getIndex(edge: EdgeHandle): PluginApiReturn<number>
+
+  /**
+   * Get the primary half-edge of an edge.
+   * @param edge The edge to query
+   * @returns The half-edge as a {@linkcode HalfEdgeHandle}, or `null` if uninitialized
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
+   *   const halfEdge = await snaptrude.core.geom.query.edge.getHalfEdge(edge)
+   *   if (halfEdge) {
+   *     const face = await snaptrude.core.geom.query.halfedge.getFace(halfEdge)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getHalfEdge(edge: EdgeHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * List the two endpoint vertices of an edge.
+   * @param edge The edge to query
+   * @returns The endpoints as {@linkcode VertexHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
+   *   const [a, b] = await snaptrude.core.geom.query.edge.listVertices(edge)
+   *   const start = await snaptrude.core.geom.query.vertex.getPosition(brep, a)
+   *   const end = await snaptrude.core.geom.query.vertex.getPosition(brep, b)
+   * }
+   * ```
+   */
+  public abstract listVertices(edge: EdgeHandle): PluginApiReturn<VertexHandle[]>
+
+  /**
+   * Get the underlying curve geometry of an edge (a line, arc or spline).
+   * @param edge The edge to query
+   * @returns The curve as a {@linkcode CurveHandle} (`line_`, `arc_` or `spline_`), or `null` if it is a circle or unset
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
+   *   const curve = await snaptrude.core.geom.query.edge.getCurve(edge)
+   *   if (curve) {
+   *     const length = await snaptrude.core.geom.query.curve.getLength(curve)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getCurve(edge: EdgeHandle): PluginApiReturn<CurveHandle | null>
+
+  /**
+   * List the faces bordering an edge (one or two).
+   * @param edge The edge to query
+   * @returns The bordering faces as {@linkcode FaceHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [edge] = await snaptrude.core.geom.query.brep.listEdges(brep)
+   *   const faces = await snaptrude.core.geom.query.edge.listFaces(edge)
+   *   console.log(faces.length === 1 ? "boundary edge" : "interior edge")
+   * }
+   * ```
+   */
+  public abstract listFaces(edge: EdgeHandle): PluginApiReturn<FaceHandle[]>
+}
+
+const edgeArg = z.object({ edge: EdgeHandle })
+
+/** Arguments for {@linkcode PluginGeomQueryEdgeApi.getIndex}. `{ edge: EdgeHandle }` */
+export const PluginGeomQueryEdgeGetIndexArgs = edgeArg
+export type PluginGeomQueryEdgeGetIndexArgs = z.infer<typeof PluginGeomQueryEdgeGetIndexArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryEdgeApi.getHalfEdge}. `{ edge: EdgeHandle }` */
+export const PluginGeomQueryEdgeGetHalfEdgeArgs = edgeArg
+export type PluginGeomQueryEdgeGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryEdgeGetHalfEdgeArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryEdgeApi.listVertices}. `{ edge: EdgeHandle }` */
+export const PluginGeomQueryEdgeListVerticesArgs = edgeArg
+export type PluginGeomQueryEdgeListVerticesArgs = z.infer<typeof PluginGeomQueryEdgeListVerticesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryEdgeApi.getCurve}. `{ edge: EdgeHandle }` */
+export const PluginGeomQueryEdgeGetCurveArgs = edgeArg
+export type PluginGeomQueryEdgeGetCurveArgs = z.infer<typeof PluginGeomQueryEdgeGetCurveArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryEdgeApi.listFaces}. `{ edge: EdgeHandle }` */
+export const PluginGeomQueryEdgeListFacesArgs = edgeArg
+export type PluginGeomQueryEdgeListFacesArgs = z.infer<typeof PluginGeomQueryEdgeListFacesArgs>