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

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

@@ -1,404 +1,404 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import { CircleHandle, Vec3Handle, Vec3Components } from "../../../../handles"
-
-/**
- * Circle-specific geometry queries — read closed-circle properties as plain values
- * (all-handle model, §11). A circle is a closed curve with its own namespace
- * (mirroring {@linkcode PluginGeomQueryArcApi}); it is NOT part of the shared
- * {@linkcode CurveHandle} line/arc surface.
- *
- * Every method takes an opaque {@linkcode CircleHandle} (plus a point handle where
- * relevant) and returns plain values — numbers, {@linkcode Vec3Components},
- * predicates as `boolean`. No query mutates its inputs.
- *
- * Accessed via `snaptrude.core.geom.query.circle`.
- */
-export abstract class PluginGeomQueryCircleApi {
-  constructor() {}
-
-  /**
-   * Read the radius of a circle.
-   * @param circle The circle to query
-   * @returns The radius as a `number`
-   *
-   * @examplePrompt What is the radius of this circle?
-   * @examplePrompt Measure the radius of the circular column grid
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const radius = await snaptrude.core.geom.query.circle.getRadius(circle)
-   * ```
-   */
-  public abstract getRadius(circle: CircleHandle): PluginApiReturn<number>
-
-  /**
-   * Read the centre point of a circle.
-   * @param circle The circle to query
-   * @returns The centre as {@linkcode Vec3Components}
-   *
-   * @examplePrompt Where is the centre of this circle?
-   * @examplePrompt Find the center point of the circular courtyard outline
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const centre = await snaptrude.core.geom.query.circle.getCentre(circle)
-   * console.log(centre.x, centre.y, centre.z)
-   * ```
-   */
-  public abstract getCentre(circle: CircleHandle): PluginApiReturn<Vec3Components>
-
-  /**
-   * Read the axis (plane normal) of a circle.
-   * @param circle The circle to query
-   * @returns The axis as {@linkcode Vec3Components}
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const axis = await snaptrude.core.geom.query.circle.getAxis(circle)
-   * console.log(axis.x, axis.y, axis.z)
-   * ```
-   */
-  public abstract getAxis(circle: CircleHandle): PluginApiReturn<Vec3Components>
-
-  /**
-   * Read the length (circumference, `2πr`) of a circle.
-   * @param circle The circle to query
-   * @returns The circumference as a `number`
-   *
-   * @examplePrompt What is the circumference of this circle?
-   * @examplePrompt How long is the circular path around the courtyard?
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const circumference = await snaptrude.core.geom.query.circle.getLength(circle)
-   * ```
-   */
-  public abstract getLength(circle: CircleHandle): PluginApiReturn<number>
-
-  /**
-   * Check whether a circle is geometrically valid (non-degenerate axis + positive radius).
-   * @param circle The circle to query
-   * @returns `true` if the circle is valid, otherwise `false`
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const ok = await snaptrude.core.geom.query.circle.isValid(circle)
-   * ```
-   */
-  public abstract isValid(circle: CircleHandle): PluginApiReturn<boolean>
-
-  /**
-   * Get the point on a circle nearest to an arbitrary point.
-   * @param circle The circle to query
-   * @param point The reference point
-   * @returns The nearest point as {@linkcode Vec3Components}
-   *
-   * @examplePrompt Find the point on the circle closest to this column
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const target = await snaptrude.core.math.vec3.new(8, 0, 2)
-   * const nearest = await snaptrude.core.geom.query.circle.getNearestPoint(circle, target)
-   * console.log(nearest.x, nearest.y, nearest.z)
-   * ```
-   */
-  public abstract getNearestPoint(
-    circle: CircleHandle,
-    point: Vec3Handle
-  ): PluginApiReturn<Vec3Components>
-
-  /**
-   * Test whether a point lies on a circle.
-   * @param circle The circle to query
-   * @param point The point to test
-   * @returns `true` if the point is on the circle, otherwise `false`
-   *
-   * @examplePrompt Check whether this point sits on the circle
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
-   * const onCircle = await snaptrude.core.geom.query.circle.hasPoint(circle, pt)
-   * ```
-   */
-  public abstract hasPoint(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<boolean>
-
-  /**
-   * Get the tangent direction of a circle at a point on it.
-   * @param circle The circle to query
-   * @param point A point on the circle
-   * @returns The tangent as {@linkcode Vec3Components}
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
-   * const tangent = await snaptrude.core.geom.query.circle.getTangent(circle, pt)
-   * console.log(tangent.x, tangent.y, tangent.z)
-   * ```
-   */
-  public abstract getTangent(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<Vec3Components>
-
-  /**
-   * Get the (in-plane, radial) normal direction of a circle at a point on it.
-   * @param circle The circle to query
-   * @param point A point on the circle
-   * @returns The radial normal as {@linkcode Vec3Components}
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
-   * const normal = await snaptrude.core.geom.query.circle.getNormal(circle, pt)
-   * console.log(normal.x, normal.y, normal.z)
-   * ```
-   */
-  public abstract getNormal(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<Vec3Components>
-
-  /**
-   * Get the point reached by travelling a signed arc-distance along the circle from
-   * a reference point that lies on it.
-   * @param circle The circle to query
-   * @param referencePoint A point on the circle to travel from
-   * @param distance Arc distance to travel
-   * @param forward Travel direction (optional; default forward)
-   * @returns The resulting point as {@linkcode Vec3Components}
-   *
-   * @examplePrompt Mark a point 2 metres along the circle from this point
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const ref = await snaptrude.core.math.vec3.new(5, 0, 0)
-   * const ahead = await snaptrude.core.geom.query.circle.getPointAtDistance(circle, ref, 2)
-   * const behind = await snaptrude.core.geom.query.circle.getPointAtDistance(circle, ref, 2, false)
-   * ```
-   */
-  public abstract getPointAtDistance(
-    circle: CircleHandle,
-    referencePoint: Vec3Handle,
-    distance: number,
-    forward?: boolean
-  ): PluginApiReturn<Vec3Components>
-
-  /**
-   * Test whether two circles are geometrically equal.
-   * @param circleA First circle
-   * @param circleB Second circle
-   * @returns `true` if the circles are equal, otherwise `false`
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const a = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const b = await snaptrude.core.geom.create.circle(origin, up, 3)
-   * const same = await snaptrude.core.geom.query.circle.isEqual(a, b)
-   * ```
-   */
-  public abstract isEqual(circleA: CircleHandle, circleB: CircleHandle): PluginApiReturn<boolean>
-
-  /**
-   * Sample a circle into an ordered list of points.
-   * @param circle The circle to query
-   * @param resolution Number of segments to sample (optional)
-   * @returns The sampled points as {@linkcode Vec3Components}`[]`
-   *
-   * @examplePrompt Divide this circle into 12 equal points
-   * @examplePrompt Get evenly spaced points around the circle to place columns
-   *
-   * # Example
-   * ```ts
-   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
-   * const points = await snaptrude.core.geom.query.circle.listPoints(circle, 12)
-   * for (const p of points) console.log(p.x, p.y, p.z)
-   * ```
-   */
-  public abstract listPoints(circle: CircleHandle, resolution?: number): PluginApiReturn<Vec3Components[]>
-}
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.getRadius}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- */
-export const PluginGeomQueryCircleGetRadiusArgs = z.object({ circle: CircleHandle })
-export type PluginGeomQueryCircleGetRadiusArgs = z.infer<typeof PluginGeomQueryCircleGetRadiusArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.getCentre}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- */
-export const PluginGeomQueryCircleGetCentreArgs = z.object({ circle: CircleHandle })
-export type PluginGeomQueryCircleGetCentreArgs = z.infer<typeof PluginGeomQueryCircleGetCentreArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.getAxis}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- */
-export const PluginGeomQueryCircleGetAxisArgs = z.object({ circle: CircleHandle })
-export type PluginGeomQueryCircleGetAxisArgs = z.infer<typeof PluginGeomQueryCircleGetAxisArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.getLength}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- */
-export const PluginGeomQueryCircleGetLengthArgs = z.object({ circle: CircleHandle })
-export type PluginGeomQueryCircleGetLengthArgs = z.infer<typeof PluginGeomQueryCircleGetLengthArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.isValid}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- */
-export const PluginGeomQueryCircleIsValidArgs = z.object({ circle: CircleHandle })
-export type PluginGeomQueryCircleIsValidArgs = z.infer<typeof PluginGeomQueryCircleIsValidArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.getNearestPoint}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- * | `point` | {@linkcode Vec3Handle} | The reference point |
- */
-export const PluginGeomQueryCircleGetNearestPointArgs = z.object({
-  circle: CircleHandle,
-  point: Vec3Handle,
-})
-export type PluginGeomQueryCircleGetNearestPointArgs = z.infer<
-  typeof PluginGeomQueryCircleGetNearestPointArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.hasPoint}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- * | `point` | {@linkcode Vec3Handle} | The point to test |
- */
-export const PluginGeomQueryCircleHasPointArgs = z.object({
-  circle: CircleHandle,
-  point: Vec3Handle,
-})
-export type PluginGeomQueryCircleHasPointArgs = z.infer<typeof PluginGeomQueryCircleHasPointArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.getTangent}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- * | `point` | {@linkcode Vec3Handle} | A point on the circle |
- */
-export const PluginGeomQueryCircleGetTangentArgs = z.object({
-  circle: CircleHandle,
-  point: Vec3Handle,
-})
-export type PluginGeomQueryCircleGetTangentArgs = z.infer<typeof PluginGeomQueryCircleGetTangentArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.getNormal}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- * | `point` | {@linkcode Vec3Handle} | A point on the circle |
- */
-export const PluginGeomQueryCircleGetNormalArgs = z.object({
-  circle: CircleHandle,
-  point: Vec3Handle,
-})
-export type PluginGeomQueryCircleGetNormalArgs = z.infer<typeof PluginGeomQueryCircleGetNormalArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.getPointAtDistance}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- * | `referencePoint` | {@linkcode Vec3Handle} | A point on the circle to travel from |
- * | `distance` | `number` | Arc distance to travel |
- * | `forward` | `boolean` | Travel direction (optional; default forward) |
- */
-export const PluginGeomQueryCircleGetPointAtDistanceArgs = z.object({
-  circle: CircleHandle,
-  referencePoint: Vec3Handle,
-  distance: z.number(),
-  forward: z.boolean().optional(),
-})
-export type PluginGeomQueryCircleGetPointAtDistanceArgs = z.infer<
-  typeof PluginGeomQueryCircleGetPointAtDistanceArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.isEqual}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circleA` | {@linkcode CircleHandle} | First circle |
- * | `circleB` | {@linkcode CircleHandle} | Second circle |
- */
-export const PluginGeomQueryCircleIsEqualArgs = z.object({
-  circleA: CircleHandle,
-  circleB: CircleHandle,
-})
-export type PluginGeomQueryCircleIsEqualArgs = z.infer<typeof PluginGeomQueryCircleIsEqualArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomQueryCircleApi.listPoints}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `circle` | {@linkcode CircleHandle} | The circle to query |
- * | `resolution` | `number` | Number of segments to sample (optional) |
- */
-export const PluginGeomQueryCircleListPointsArgs = z.object({
-  circle: CircleHandle,
-  resolution: z.number().optional(),
-})
-export type PluginGeomQueryCircleListPointsArgs = z.infer<typeof PluginGeomQueryCircleListPointsArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { CircleHandle, Vec3Handle, Vec3Components } from "../../../../handles"
+
+/**
+ * Circle-specific geometry queries — read closed-circle properties as plain values
+ * (all-handle model, §11). A circle is a closed curve with its own namespace
+ * (mirroring {@linkcode PluginGeomQueryArcApi}); it is NOT part of the shared
+ * {@linkcode CurveHandle} line/arc surface.
+ *
+ * Every method takes an opaque {@linkcode CircleHandle} (plus a point handle where
+ * relevant) and returns plain values — numbers, {@linkcode Vec3Components},
+ * predicates as `boolean`. No query mutates its inputs.
+ *
+ * Accessed via `snaptrude.core.geom.query.circle`.
+ */
+export abstract class PluginGeomQueryCircleApi {
+  constructor() {}
+
+  /**
+   * Read the radius of a circle.
+   * @param circle The circle to query
+   * @returns The radius as a `number`
+   *
+   * @examplePrompt What is the radius of this circle?
+   * @examplePrompt Measure the radius of the circular column grid
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const radius = await snaptrude.core.geom.query.circle.getRadius(circle)
+   * ```
+   */
+  public abstract getRadius(circle: CircleHandle): PluginApiReturn<number>
+
+  /**
+   * Read the centre point of a circle.
+   * @param circle The circle to query
+   * @returns The centre as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Where is the centre of this circle?
+   * @examplePrompt Find the center point of the circular courtyard outline
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const centre = await snaptrude.core.geom.query.circle.getCentre(circle)
+   * console.log(centre.x, centre.y, centre.z)
+   * ```
+   */
+  public abstract getCentre(circle: CircleHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Read the axis (plane normal) of a circle.
+   * @param circle The circle to query
+   * @returns The axis as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const axis = await snaptrude.core.geom.query.circle.getAxis(circle)
+   * console.log(axis.x, axis.y, axis.z)
+   * ```
+   */
+  public abstract getAxis(circle: CircleHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Read the length (circumference, `2πr`) of a circle.
+   * @param circle The circle to query
+   * @returns The circumference as a `number`
+   *
+   * @examplePrompt What is the circumference of this circle?
+   * @examplePrompt How long is the circular path around the courtyard?
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const circumference = await snaptrude.core.geom.query.circle.getLength(circle)
+   * ```
+   */
+  public abstract getLength(circle: CircleHandle): PluginApiReturn<number>
+
+  /**
+   * Check whether a circle is geometrically valid (non-degenerate axis + positive radius).
+   * @param circle The circle to query
+   * @returns `true` if the circle is valid, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const ok = await snaptrude.core.geom.query.circle.isValid(circle)
+   * ```
+   */
+  public abstract isValid(circle: CircleHandle): PluginApiReturn<boolean>
+
+  /**
+   * Get the point on a circle nearest to an arbitrary point.
+   * @param circle The circle to query
+   * @param point The reference point
+   * @returns The nearest point as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Find the point on the circle closest to this column
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const target = await snaptrude.core.math.vec3.new(8, 0, 2)
+   * const nearest = await snaptrude.core.geom.query.circle.getNearestPoint(circle, target)
+   * console.log(nearest.x, nearest.y, nearest.z)
+   * ```
+   */
+  public abstract getNearestPoint(
+    circle: CircleHandle,
+    point: Vec3Handle
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Test whether a point lies on a circle.
+   * @param circle The circle to query
+   * @param point The point to test
+   * @returns `true` if the point is on the circle, otherwise `false`
+   *
+   * @examplePrompt Check whether this point sits on the circle
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const onCircle = await snaptrude.core.geom.query.circle.hasPoint(circle, pt)
+   * ```
+   */
+  public abstract hasPoint(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<boolean>
+
+  /**
+   * Get the tangent direction of a circle at a point on it.
+   * @param circle The circle to query
+   * @param point A point on the circle
+   * @returns The tangent as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const tangent = await snaptrude.core.geom.query.circle.getTangent(circle, pt)
+   * console.log(tangent.x, tangent.y, tangent.z)
+   * ```
+   */
+  public abstract getTangent(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the (in-plane, radial) normal direction of a circle at a point on it.
+   * @param circle The circle to query
+   * @param point A point on the circle
+   * @returns The radial normal as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const pt = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const normal = await snaptrude.core.geom.query.circle.getNormal(circle, pt)
+   * console.log(normal.x, normal.y, normal.z)
+   * ```
+   */
+  public abstract getNormal(circle: CircleHandle, point: Vec3Handle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Get the point reached by travelling a signed arc-distance along the circle from
+   * a reference point that lies on it.
+   * @param circle The circle to query
+   * @param referencePoint A point on the circle to travel from
+   * @param distance Arc distance to travel
+   * @param forward Travel direction (optional; default forward)
+   * @returns The resulting point as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Mark a point 2 metres along the circle from this point
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const ref = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const ahead = await snaptrude.core.geom.query.circle.getPointAtDistance(circle, ref, 2)
+   * const behind = await snaptrude.core.geom.query.circle.getPointAtDistance(circle, ref, 2, false)
+   * ```
+   */
+  public abstract getPointAtDistance(
+    circle: CircleHandle,
+    referencePoint: Vec3Handle,
+    distance: number,
+    forward?: boolean
+  ): PluginApiReturn<Vec3Components>
+
+  /**
+   * Test whether two circles are geometrically equal.
+   * @param circleA First circle
+   * @param circleB Second circle
+   * @returns `true` if the circles are equal, otherwise `false`
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const a = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const b = await snaptrude.core.geom.create.circle(origin, up, 3)
+   * const same = await snaptrude.core.geom.query.circle.isEqual(a, b)
+   * ```
+   */
+  public abstract isEqual(circleA: CircleHandle, circleB: CircleHandle): PluginApiReturn<boolean>
+
+  /**
+   * Sample a circle into an ordered list of points.
+   * @param circle The circle to query
+   * @param resolution Number of segments to sample (optional)
+   * @returns The sampled points as {@linkcode Vec3Components}`[]`
+   *
+   * @examplePrompt Divide this circle into 12 equal points
+   * @examplePrompt Get evenly spaced points around the circle to place columns
+   *
+   * # Example
+   * ```ts
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const circle = await snaptrude.core.geom.create.circle(origin, up, 5)
+   * const points = await snaptrude.core.geom.query.circle.listPoints(circle, 12)
+   * for (const p of points) console.log(p.x, p.y, p.z)
+   * ```
+   */
+  public abstract listPoints(circle: CircleHandle, resolution?: number): PluginApiReturn<Vec3Components[]>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getRadius}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleGetRadiusArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleGetRadiusArgs = z.infer<typeof PluginGeomQueryCircleGetRadiusArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getCentre}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleGetCentreArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleGetCentreArgs = z.infer<typeof PluginGeomQueryCircleGetCentreArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getAxis}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleGetAxisArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleGetAxisArgs = z.infer<typeof PluginGeomQueryCircleGetAxisArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getLength}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleGetLengthArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleGetLengthArgs = z.infer<typeof PluginGeomQueryCircleGetLengthArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.isValid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ */
+export const PluginGeomQueryCircleIsValidArgs = z.object({ circle: CircleHandle })
+export type PluginGeomQueryCircleIsValidArgs = z.infer<typeof PluginGeomQueryCircleIsValidArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getNearestPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `point` | {@linkcode Vec3Handle} | The reference point |
+ */
+export const PluginGeomQueryCircleGetNearestPointArgs = z.object({
+  circle: CircleHandle,
+  point: Vec3Handle,
+})
+export type PluginGeomQueryCircleGetNearestPointArgs = z.infer<
+  typeof PluginGeomQueryCircleGetNearestPointArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.hasPoint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `point` | {@linkcode Vec3Handle} | The point to test |
+ */
+export const PluginGeomQueryCircleHasPointArgs = z.object({
+  circle: CircleHandle,
+  point: Vec3Handle,
+})
+export type PluginGeomQueryCircleHasPointArgs = z.infer<typeof PluginGeomQueryCircleHasPointArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getTangent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `point` | {@linkcode Vec3Handle} | A point on the circle |
+ */
+export const PluginGeomQueryCircleGetTangentArgs = z.object({
+  circle: CircleHandle,
+  point: Vec3Handle,
+})
+export type PluginGeomQueryCircleGetTangentArgs = z.infer<typeof PluginGeomQueryCircleGetTangentArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getNormal}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `point` | {@linkcode Vec3Handle} | A point on the circle |
+ */
+export const PluginGeomQueryCircleGetNormalArgs = z.object({
+  circle: CircleHandle,
+  point: Vec3Handle,
+})
+export type PluginGeomQueryCircleGetNormalArgs = z.infer<typeof PluginGeomQueryCircleGetNormalArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.getPointAtDistance}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `referencePoint` | {@linkcode Vec3Handle} | A point on the circle to travel from |
+ * | `distance` | `number` | Arc distance to travel |
+ * | `forward` | `boolean` | Travel direction (optional; default forward) |
+ */
+export const PluginGeomQueryCircleGetPointAtDistanceArgs = z.object({
+  circle: CircleHandle,
+  referencePoint: Vec3Handle,
+  distance: z.number(),
+  forward: z.boolean().optional(),
+})
+export type PluginGeomQueryCircleGetPointAtDistanceArgs = z.infer<
+  typeof PluginGeomQueryCircleGetPointAtDistanceArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.isEqual}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circleA` | {@linkcode CircleHandle} | First circle |
+ * | `circleB` | {@linkcode CircleHandle} | Second circle |
+ */
+export const PluginGeomQueryCircleIsEqualArgs = z.object({
+  circleA: CircleHandle,
+  circleB: CircleHandle,
+})
+export type PluginGeomQueryCircleIsEqualArgs = z.infer<typeof PluginGeomQueryCircleIsEqualArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryCircleApi.listPoints}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `circle` | {@linkcode CircleHandle} | The circle to query |
+ * | `resolution` | `number` | Number of segments to sample (optional) |
+ */
+export const PluginGeomQueryCircleListPointsArgs = z.object({
+  circle: CircleHandle,
+  resolution: z.number().optional(),
+})
+export type PluginGeomQueryCircleListPointsArgs = z.infer<typeof PluginGeomQueryCircleListPointsArgs>