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

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

@@ -1,205 +1,205 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import {
-  BrepHandle,
-  VertexHandle,
-  HalfEdgeHandle,
-  EdgeHandle,
-  FaceHandle,
-  Vec3Components,
-} from "../../../../handles"
-
-/**
- * Vertex queries — read a single BREP vertex's topology and position (all-handle
- * model, §11). A {@linkcode VertexHandle} is minted by walking from a brep/face/edge
- * handle; it is session-ephemeral and goes stale on undo/redo/re-topologize.
- *
- * Position lives on the parent brep (indexed by the vertex), so
- * {@linkcode PluginGeomQueryVertexApi.getPosition} takes both handles. No query
- * mutates its inputs.
- *
- * Accessed via `snaptrude.core.geom.query.vertex`.
- */
-export abstract class PluginGeomQueryVertexApi {
-  constructor() {}
-
-  /**
-   * Get the index of a vertex within its brep.
-   * @param vertex The vertex 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
-   *   const index = await snaptrude.core.geom.query.vertex.getIndex(vertex)
-   * }
-   * ```
-   */
-  public abstract getIndex(vertex: VertexHandle): PluginApiReturn<number>
-
-  /**
-   * Get a seed half-edge emanating from a vertex.
-   * @param vertex The vertex 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
-   *   const halfEdge = await snaptrude.core.geom.query.vertex.getHalfEdge(vertex)
-   *   if (halfEdge) {
-   *     const edge = await snaptrude.core.geom.query.halfedge.getEdge(halfEdge)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getHalfEdge(vertex: VertexHandle): PluginApiReturn<HalfEdgeHandle | null>
-
-  /**
-   * Get the position of a vertex (needs the parent brep for coordinates).
-   * @param brep The parent brep (source of coordinates)
-   * @param vertex The vertex whose position to read
-   * @returns The position as {@linkcode Vec3Components}
-   *
-   * @examplePrompt What are the coordinates of this corner point?
-   * @examplePrompt Get the exact x, y, z position of the selected vertex
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
-   *   const pos = await snaptrude.core.geom.query.vertex.getPosition(brep, vertex)
-   *   console.log(pos.x, pos.y, pos.z)
-   * }
-   * ```
-   */
-  public abstract getPosition(
-    brep: BrepHandle,
-    vertex: VertexHandle
-  ): PluginApiReturn<Vec3Components>
-
-  /**
-   * List the half-edges around a vertex.
-   * @param vertex The vertex 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
-   *   const halfEdges = await snaptrude.core.geom.query.vertex.listHalfEdges(vertex)
-   *   console.log("half-edges at this vertex:", halfEdges.length)
-   * }
-   * ```
-   */
-  public abstract listHalfEdges(vertex: VertexHandle): PluginApiReturn<HalfEdgeHandle[]>
-
-  /**
-   * List the edges around a vertex.
-   * @param vertex The vertex 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
-   *   const edges = await snaptrude.core.geom.query.vertex.listEdges(vertex)
-   *   console.log("edges meeting at this corner:", edges.length)
-   * }
-   * ```
-   */
-  public abstract listEdges(vertex: VertexHandle): PluginApiReturn<EdgeHandle[]>
-
-  /**
-   * List the faces around a vertex.
-   * @param vertex The vertex to query
-   * @returns The 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
-   *   const faces = await snaptrude.core.geom.query.vertex.listFaces(vertex)
-   *   console.log("faces sharing this corner:", faces.length)
-   * }
-   * ```
-   */
-  public abstract listFaces(vertex: VertexHandle): PluginApiReturn<FaceHandle[]>
-
-  /**
-   * List the neighbouring vertices of a vertex.
-   * @param vertex The vertex to query
-   * @returns The neighbours as {@linkcode VertexHandle}`[]`
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
-   * if (brep) {
-   *   const [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
-   *   const neighbors = await snaptrude.core.geom.query.vertex.listNeighbors(vertex)
-   *   for (const n of neighbors) {
-   *     const pos = await snaptrude.core.geom.query.vertex.getPosition(brep, n)
-   *   }
-   * }
-   * ```
-   */
-  public abstract listNeighbors(vertex: VertexHandle): PluginApiReturn<VertexHandle[]>
-}
-
-const vertexArg = z.object({ vertex: VertexHandle })
-
-/** Arguments for {@linkcode PluginGeomQueryVertexApi.getIndex}. `{ vertex: VertexHandle }` */
-export const PluginGeomQueryVertexGetIndexArgs = vertexArg
-export type PluginGeomQueryVertexGetIndexArgs = z.infer<typeof PluginGeomQueryVertexGetIndexArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryVertexApi.getHalfEdge}. `{ vertex: VertexHandle }` */
-export const PluginGeomQueryVertexGetHalfEdgeArgs = vertexArg
-export type PluginGeomQueryVertexGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryVertexGetHalfEdgeArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryVertexApi.getPosition}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `brep` | {@linkcode BrepHandle} | The parent brep (source of coordinates) |
- * | `vertex` | {@linkcode VertexHandle} | The vertex whose position to read |
- */
-export const PluginGeomQueryVertexGetPositionArgs = z.object({
-  brep: BrepHandle,
-  vertex: VertexHandle,
-})
-export type PluginGeomQueryVertexGetPositionArgs = z.infer<typeof PluginGeomQueryVertexGetPositionArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryVertexApi.listHalfEdges}. `{ vertex: VertexHandle }` */
-export const PluginGeomQueryVertexListHalfEdgesArgs = vertexArg
-export type PluginGeomQueryVertexListHalfEdgesArgs = z.infer<
-  typeof PluginGeomQueryVertexListHalfEdgesArgs
->
-
-/** Arguments for {@linkcode PluginGeomQueryVertexApi.listEdges}. `{ vertex: VertexHandle }` */
-export const PluginGeomQueryVertexListEdgesArgs = vertexArg
-export type PluginGeomQueryVertexListEdgesArgs = z.infer<typeof PluginGeomQueryVertexListEdgesArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryVertexApi.listFaces}. `{ vertex: VertexHandle }` */
-export const PluginGeomQueryVertexListFacesArgs = vertexArg
-export type PluginGeomQueryVertexListFacesArgs = z.infer<typeof PluginGeomQueryVertexListFacesArgs>
-
-/** Arguments for {@linkcode PluginGeomQueryVertexApi.listNeighbors}. `{ vertex: VertexHandle }` */
-export const PluginGeomQueryVertexListNeighborsArgs = vertexArg
-export type PluginGeomQueryVertexListNeighborsArgs = z.infer<
-  typeof PluginGeomQueryVertexListNeighborsArgs
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  BrepHandle,
+  VertexHandle,
+  HalfEdgeHandle,
+  EdgeHandle,
+  FaceHandle,
+  Vec3Components,
+} from "../../../../handles"
+
+/**
+ * Vertex queries — read a single BREP vertex's topology and position (all-handle
+ * model, §11). A {@linkcode VertexHandle} is minted by walking from a brep/face/edge
+ * handle; it is session-ephemeral and goes stale on undo/redo/re-topologize.
+ *
+ * Position lives on the parent brep (indexed by the vertex), so
+ * {@linkcode PluginGeomQueryVertexApi.getPosition} takes both handles. No query
+ * mutates its inputs.
+ *
+ * Accessed via `snaptrude.core.geom.query.vertex`.
+ */
+export abstract class PluginGeomQueryVertexApi {
+  constructor() {}
+
+  /**
+   * Get the index of a vertex within its brep.
+   * @param vertex The vertex 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const index = await snaptrude.core.geom.query.vertex.getIndex(vertex)
+   * }
+   * ```
+   */
+  public abstract getIndex(vertex: VertexHandle): PluginApiReturn<number>
+
+  /**
+   * Get a seed half-edge emanating from a vertex.
+   * @param vertex The vertex 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const halfEdge = await snaptrude.core.geom.query.vertex.getHalfEdge(vertex)
+   *   if (halfEdge) {
+   *     const edge = await snaptrude.core.geom.query.halfedge.getEdge(halfEdge)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getHalfEdge(vertex: VertexHandle): PluginApiReturn<HalfEdgeHandle | null>
+
+  /**
+   * Get the position of a vertex (needs the parent brep for coordinates).
+   * @param brep The parent brep (source of coordinates)
+   * @param vertex The vertex whose position to read
+   * @returns The position as {@linkcode Vec3Components}
+   *
+   * @examplePrompt What are the coordinates of this corner point?
+   * @examplePrompt Get the exact x, y, z position of the selected vertex
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const pos = await snaptrude.core.geom.query.vertex.getPosition(brep, vertex)
+   *   console.log(pos.x, pos.y, pos.z)
+   * }
+   * ```
+   */
+  public abstract getPosition(
+    brep: BrepHandle,
+    vertex: VertexHandle
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * List the half-edges around a vertex.
+   * @param vertex The vertex 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const halfEdges = await snaptrude.core.geom.query.vertex.listHalfEdges(vertex)
+   *   console.log("half-edges at this vertex:", halfEdges.length)
+   * }
+   * ```
+   */
+  public abstract listHalfEdges(vertex: VertexHandle): PluginApiReturn<HalfEdgeHandle[]>
+
+  /**
+   * List the edges around a vertex.
+   * @param vertex The vertex 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const edges = await snaptrude.core.geom.query.vertex.listEdges(vertex)
+   *   console.log("edges meeting at this corner:", edges.length)
+   * }
+   * ```
+   */
+  public abstract listEdges(vertex: VertexHandle): PluginApiReturn<EdgeHandle[]>
+
+  /**
+   * List the faces around a vertex.
+   * @param vertex The vertex to query
+   * @returns The 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 [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const faces = await snaptrude.core.geom.query.vertex.listFaces(vertex)
+   *   console.log("faces sharing this corner:", faces.length)
+   * }
+   * ```
+   */
+  public abstract listFaces(vertex: VertexHandle): PluginApiReturn<FaceHandle[]>
+
+  /**
+   * List the neighbouring vertices of a vertex.
+   * @param vertex The vertex to query
+   * @returns The neighbours as {@linkcode VertexHandle}`[]`
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const brep = await snaptrude.design.query.geometry.getBrep(wall)
+   * if (brep) {
+   *   const [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)
+   *   const neighbors = await snaptrude.core.geom.query.vertex.listNeighbors(vertex)
+   *   for (const n of neighbors) {
+   *     const pos = await snaptrude.core.geom.query.vertex.getPosition(brep, n)
+   *   }
+   * }
+   * ```
+   */
+  public abstract listNeighbors(vertex: VertexHandle): PluginApiReturn<VertexHandle[]>
+}
+
+const vertexArg = z.object({ vertex: VertexHandle })
+
+/** Arguments for {@linkcode PluginGeomQueryVertexApi.getIndex}. `{ vertex: VertexHandle }` */
+export const PluginGeomQueryVertexGetIndexArgs = vertexArg
+export type PluginGeomQueryVertexGetIndexArgs = z.infer<typeof PluginGeomQueryVertexGetIndexArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryVertexApi.getHalfEdge}. `{ vertex: VertexHandle }` */
+export const PluginGeomQueryVertexGetHalfEdgeArgs = vertexArg
+export type PluginGeomQueryVertexGetHalfEdgeArgs = z.infer<typeof PluginGeomQueryVertexGetHalfEdgeArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryVertexApi.getPosition}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The parent brep (source of coordinates) |
+ * | `vertex` | {@linkcode VertexHandle} | The vertex whose position to read |
+ */
+export const PluginGeomQueryVertexGetPositionArgs = z.object({
+  brep: BrepHandle,
+  vertex: VertexHandle,
+})
+export type PluginGeomQueryVertexGetPositionArgs = z.infer<typeof PluginGeomQueryVertexGetPositionArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryVertexApi.listHalfEdges}. `{ vertex: VertexHandle }` */
+export const PluginGeomQueryVertexListHalfEdgesArgs = vertexArg
+export type PluginGeomQueryVertexListHalfEdgesArgs = z.infer<
+  typeof PluginGeomQueryVertexListHalfEdgesArgs
+>
+
+/** Arguments for {@linkcode PluginGeomQueryVertexApi.listEdges}. `{ vertex: VertexHandle }` */
+export const PluginGeomQueryVertexListEdgesArgs = vertexArg
+export type PluginGeomQueryVertexListEdgesArgs = z.infer<typeof PluginGeomQueryVertexListEdgesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryVertexApi.listFaces}. `{ vertex: VertexHandle }` */
+export const PluginGeomQueryVertexListFacesArgs = vertexArg
+export type PluginGeomQueryVertexListFacesArgs = z.infer<typeof PluginGeomQueryVertexListFacesArgs>
+
+/** Arguments for {@linkcode PluginGeomQueryVertexApi.listNeighbors}. `{ vertex: VertexHandle }` */
+export const PluginGeomQueryVertexListNeighborsArgs = vertexArg
+export type PluginGeomQueryVertexListNeighborsArgs = z.infer<
+  typeof PluginGeomQueryVertexListNeighborsArgs
+>