@snaptrude/plugin-core 0.0.0-dev-20260708130115

package/src/api/core/layers.ts

@@ -0,0 +1,333 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Layers — read and toggle the drawing/reference layers of a storey.
+ *
+ * These are the **drawing/reference** layers shown in the storey's Layers panel —
+ * the surfaces you sketch on and the imported underlays (CAD, PDF, images,
+ * terrain). They are **not** wall/floor construction-assembly material layers,
+ * which are a property of the built element, not this namespace.
+ *
+ * Reads return plain records and never throw for a missing layer (`get` and
+ * `getActive` return `null`, `list` returns `[]`).
+ *
+ * v1 exposes reads plus visibility edits and the active-layer switch.
+ * Creating and deleting layers are intentionally not part of this contract yet.
+ *
+ * Sub-namespace members typed as optional (`?`) are **authored ahead of the
+ * host** — declared so plugins and codegen can see the shape, but kept out of the
+ * discovery manifest until the host lands them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.layers`.
+ */
+export abstract class PluginCoreLayersApi {
+  constructor() {}
+
+  /**
+   * List the drawing layers of a storey.
+   *
+   * Optionally filter to a single {@linkcode PluginCoreLayerType}.
+   *
+   * @param storeyId - The storey whose layers to read.
+   * @param layerType - Optional {@linkcode PluginCoreLayerType} filter.
+   * @returns A {@linkcode PluginCoreLayersListResult} with a `layers` array
+   *   (empty when the storey is missing or has no matching layers).
+   *
+   * @examplePrompt List the drawing layers on this storey
+   * @examplePrompt Show all the PDF underlays on storey st_2
+   * @examplePrompt What CAD layers are on the ground floor?
+   *
+   * # Example
+   * ```ts
+   * const { layers } = await snaptrude.core.layers.list("st_2")
+   * for (const l of layers) console.log(l.name, l.layerType, l.hidden)
+   * ```
+   */
+  public abstract list(
+    storeyId: string,
+    layerType?: PluginCoreLayerType,
+  ): PluginApiReturn<PluginCoreLayersListResult>
+
+  /**
+   * Get a single drawing layer by id.
+   *
+   * @param layerId - The id of the layer to read.
+   * @returns The matching {@linkcode PluginCoreLayer}, or `null` if no layer has
+   *   that id.
+   *
+   * @examplePrompt Get the drawing layer with id ly_5
+   * @examplePrompt Is layer ly_5 hidden or locked?
+   * @examplePrompt Look up a single drawing layer by its id
+   *
+   * # Example
+   * ```ts
+   * const layer = await snaptrude.core.layers.get("ly_5")
+   * if (layer) console.log(layer.name, layer.hidden, layer.locked)
+   * ```
+   */
+  public abstract get(
+    layerId: string,
+  ): PluginApiReturn<PluginCoreLayersGetResult>
+
+  /**
+   * Get the active drawing layer of a storey.
+   *
+   * The active layer is the one new sketch geometry is drawn onto. Paired with
+   * {@linkcode PluginCoreLayersApi.setActive}.
+   *
+   * @param storeyId - The storey whose active layer to read.
+   * @returns The active {@linkcode PluginCoreLayer}, or `null` if the storey is
+   *   missing or has no active layer.
+   *
+   * @examplePrompt Which drawing layer is active on this storey?
+   * @examplePrompt Get the current layer on storey st_2
+   * @examplePrompt What layer am I drawing on?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.core.layers.getActive("st_2")
+   * if (active) console.log(active.name)
+   * ```
+   */
+  public abstract getActive(
+    storeyId: string,
+  ): PluginApiReturn<PluginCoreLayersGetActiveResult>
+
+  /**
+   * Make a drawing layer the active layer of its storey.
+   *
+   * Paired with {@linkcode PluginCoreLayersApi.getActive}.
+   *
+   * @param layerId - The id of the layer to activate.
+   * @returns The id of the now-active layer.
+   * @throws If no layer has the given id.
+   *
+   * @examplePrompt Draw on layer ly_5
+   * @examplePrompt Make this the active layer
+   * @examplePrompt Switch the active layer to the CAD underlay
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.layers.setActive("ly_5")
+   * ```
+   */
+  public abstract setActive(
+    layerId: string,
+  ): PluginApiReturn<PluginCoreLayersSetActiveResult>
+
+  /**
+   * Update a drawing layer's visibility.
+   *
+   * A **sparse** update: omit `hidden` to leave it unchanged. This edit is **not
+   * undoable**. Locking and renaming are not exposed — layer `locked` is a
+   * read-only status here (setting it at runtime does not lock the live meshes or
+   * flip the panel padlock until a reload), and a rename cascades to every member
+   * mesh's `layerName`, a corruption hazard.
+   *
+   * @param layerId - The id of the layer to update.
+   * @param hidden - New hidden state (unchanged if omitted).
+   * @returns The updated {@linkcode PluginCoreLayer}.
+   * @throws If no layer has the given id.
+   *
+   * @examplePrompt Hide the PDF underlay layer
+   * @examplePrompt Show the CAD layer again
+   * @examplePrompt Hide layer ly_5
+   *
+   * # Example
+   * ```ts
+   * const layer = await snaptrude.core.layers.update("ly_5", true)
+   * ```
+   */
+  public abstract update(
+    layerId: string,
+    hidden?: boolean,
+  ): PluginApiReturn<PluginCoreLayersUpdateResult>
+}
+
+/**
+ * The kind of a drawing layer.
+ *
+ * Author-drawable kinds (`floor`, `wall`, `ceiling`, `rough`, `default`) plus
+ * read-only imported underlays (`image`, `cad`, `pdf`, `terrain`, `buildings`).
+ */
+export const PluginCoreLayerType = z.enum([
+  "floor",
+  "wall",
+  "ceiling",
+  "rough",
+  "default",
+  "image",
+  "cad",
+  "pdf",
+  "terrain",
+  "buildings",
+])
+export type PluginCoreLayerType = z.infer<typeof PluginCoreLayerType>
+
+/**
+ * A drawing/reference layer on a storey.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public layer id (e.g. `"ly_5"`) |
+ * | `name` | `string` | Display name |
+ * | `layerType` | {@linkcode PluginCoreLayerType} | The layer's kind |
+ * | `storeyId` | `string` | The stable id of the storey this layer belongs to |
+ * | `buildingId` | `string` | The stable id of the building this layer belongs to |
+ * | `hidden` | `boolean` | Whether the layer is hidden |
+ * | `locked` | `boolean` | Whether the layer is locked against edits |
+ * | `contentSummary` | `object` | A summary of what the layer holds (see below) |
+ *
+ * `contentSummary`:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `hasFloorplan` | `boolean` | Whether the layer holds drawn floorplan geometry |
+ * | `pdfCount` | `number` | Number of PDF underlays on the layer |
+ * | `hasTerrain` | `boolean` | Whether the layer holds terrain |
+ */
+export const PluginCoreLayer = z.object({
+  id: z.string(),
+  name: z.string(),
+  layerType: PluginCoreLayerType,
+  storeyId: z.string(),
+  buildingId: z.string(),
+  hidden: z.boolean(),
+  locked: z.boolean(),
+  contentSummary: z.object({
+    hasFloorplan: z.boolean(),
+    pdfCount: z.number().int(),
+    hasTerrain: z.boolean(),
+  }),
+})
+export type PluginCoreLayer = z.infer<typeof PluginCoreLayer>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyId` | `string` | The storey whose layers to read |
+ * | `layerType` | {@linkcode PluginCoreLayerType}` \| undefined` | Optional layer-type filter |
+ */
+export const PluginCoreLayersListArgs = z.object({
+  storeyId: z.string(),
+  layerType: PluginCoreLayerType.optional(),
+})
+export type PluginCoreLayersListArgs = z.infer<
+  typeof PluginCoreLayersListArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layers` | {@linkcode PluginCoreLayer}`[]` | The storey's drawing layers (empty when missing or none match) |
+ */
+export const PluginCoreLayersListResult = z.object({
+  layers: z.array(PluginCoreLayer),
+})
+export type PluginCoreLayersListResult = z.infer<
+  typeof PluginCoreLayersListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to read |
+ */
+export const PluginCoreLayersGetArgs = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreLayersGetArgs = z.infer<
+  typeof PluginCoreLayersGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreLayersApi.get} — the layer, or `null`
+ * when no layer has the given id.
+ */
+export const PluginCoreLayersGetResult = PluginCoreLayer.nullable()
+export type PluginCoreLayersGetResult = z.infer<
+  typeof PluginCoreLayersGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.getActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyId` | `string` | The storey whose active layer to read |
+ */
+export const PluginCoreLayersGetActiveArgs = z.object({
+  storeyId: z.string(),
+})
+export type PluginCoreLayersGetActiveArgs = z.infer<
+  typeof PluginCoreLayersGetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreLayersApi.getActive} — the active layer,
+ * or `null` when the storey is missing or has no active layer.
+ */
+export const PluginCoreLayersGetActiveResult = PluginCoreLayer.nullable()
+export type PluginCoreLayersGetActiveResult = z.infer<
+  typeof PluginCoreLayersGetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to activate |
+ */
+export const PluginCoreLayersSetActiveArgs = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreLayersSetActiveArgs = z.infer<
+  typeof PluginCoreLayersSetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreLayersApi.setActive} — the now-active
+ * layer's id.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the now-active layer |
+ */
+export const PluginCoreLayersSetActiveResult = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreLayersSetActiveResult = z.infer<
+  typeof PluginCoreLayersSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to update |
+ * | `hidden` | `boolean \| undefined` | New hidden state (unchanged if omitted) |
+ */
+export const PluginCoreLayersUpdateArgs = z.object({
+  layerId: z.string(),
+  hidden: z.boolean().optional(),
+})
+export type PluginCoreLayersUpdateArgs = z.infer<
+  typeof PluginCoreLayersUpdateArgs
+>
+
+/** Result of {@linkcode PluginCoreLayersApi.update} — the updated layer. */
+export const PluginCoreLayersUpdateResult = PluginCoreLayer
+export type PluginCoreLayersUpdateResult = z.infer<
+  typeof PluginCoreLayersUpdateResult
+>

package/src/api/core/math/index.ts

@@ -0,0 +1,20 @@
+import { PluginVec3Api } from "./vec3"
+import { PluginQuatApi } from "./quat"
+
+/**
+ * Math primitives for 3D vector and quaternion operations.
+ *
+ * - {@linkcode PluginMathApi.vec3} — 3D vector creation and arithmetic
+ * - {@linkcode PluginMathApi.quat} — Quaternion creation and rotation operations
+ */
+export abstract class PluginMathApi {
+  /** 3D vector operations. See {@linkcode PluginVec3Api}. */
+  public abstract vec3: PluginVec3Api
+  /** Quaternion operations. See {@linkcode PluginQuatApi}. */
+  public abstract quat: PluginQuatApi
+
+  constructor() {}
+}
+
+export * from "./vec3"
+export * from "./quat"

package/src/api/core/math/quat.ts

@@ -0,0 +1,172 @@
+import { PluginApiReturn } from "../../../types"
+import { Vec3Handle, QuatHandle, QuatComponents } from "../../../handles"
+
+/**
+ * Quaternion operations (all-handle model, §11).
+ *
+ * Quaternions are opaque {@linkcode QuatHandle}s; every operation is a host call
+ * returning a new handle. Read primitive components back with
+ * {@linkcode PluginQuatApi.components}. Accessed via `snaptrude.core.math.quat`.
+ */
+export abstract class PluginQuatApi {
+  constructor() {}
+
+  /**
+   * Create a quaternion from primitive components.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.new(0, 0, 0, 1)
+   * const { x, y, z, w } = await snaptrude.core.math.quat.components(q)
+   * ```
+   */
+  abstract new(x: number, y: number, z: number, w: number): PluginApiReturn<QuatHandle>
+  /**
+   * Return the identity quaternion (no rotation).
+   *
+   * # Example
+   * ```ts
+   * const noRotation = await snaptrude.core.math.quat.identity()
+   * ```
+   */
+  abstract identity(): PluginApiReturn<QuatHandle>
+  /**
+   * Build a quaternion from a rotation axis and an angle in radians.
+   *
+   * # Example
+   * ```ts
+   * const axis = await snaptrude.core.math.vec3.new(0, 0, 1)
+   * const quarterTurn = await snaptrude.core.math.quat.fromAxisAngle(axis, Math.PI / 2)
+   * ```
+   */
+  abstract fromAxisAngle(axis: Vec3Handle, angle: number): PluginApiReturn<QuatHandle>
+  /**
+   * Build a quaternion from Euler angles in radians.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+   * ```
+   */
+  abstract fromEuler(x: number, y: number, z: number): PluginApiReturn<QuatHandle>
+  /**
+   * Compose two rotations with the Hamilton product `a * b` (apply `b` then `a`).
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+   * const b = await snaptrude.core.math.quat.fromEuler(Math.PI / 4, 0, 0)
+   * const combined = await snaptrude.core.math.quat.multiply(a, b) // b first, then a
+   * ```
+   */
+  abstract multiply(a: QuatHandle, b: QuatHandle): PluginApiReturn<QuatHandle>
+  /**
+   * Compute the conjugate of a quaternion (negated vector part).
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 4, 0)
+   * const conj = await snaptrude.core.math.quat.conjugate(q)
+   * ```
+   */
+  abstract conjugate(q: QuatHandle): PluginApiReturn<QuatHandle>
+  /**
+   * Compute the magnitude (norm) of a quaternion.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.new(0, 0, 0, 1)
+   * const len = await snaptrude.core.math.quat.length(q) // 1
+   * ```
+   */
+  abstract length(q: QuatHandle): PluginApiReturn<number>
+  /**
+   * Normalize a quaternion to unit length.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.new(0, 0, 1, 1)
+   * const unit = await snaptrude.core.math.quat.normalize(q)
+   * ```
+   */
+  abstract normalize(q: QuatHandle): PluginApiReturn<QuatHandle>
+  /**
+   * Compute the inverse quaternion — the rotation that undoes `q`.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+   * const undo = await snaptrude.core.math.quat.inverse(q)
+   * ```
+   */
+  abstract inverse(q: QuatHandle): PluginApiReturn<QuatHandle>
+  /**
+   * Decompose a quaternion into its rotation axis and angle (radians).
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 3, 0)
+   * const { axis, angle } = await snaptrude.core.math.quat.toAxisAngle(q)
+   * const { x, y, z } = await snaptrude.core.math.vec3.components(axis)
+   * ```
+   */
+  abstract toAxisAngle(q: QuatHandle): PluginApiReturn<{ axis: Vec3Handle; angle: number }>
+  /**
+   * Spherically interpolate (slerp) between two rotations by factor `t`.
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.quat.identity()
+   * const end = await snaptrude.core.math.quat.fromEuler(0, Math.PI, 0)
+   * const halfway = await snaptrude.core.math.quat.slerp(start, end, 0.5)
+   * ```
+   */
+  abstract slerp(a: QuatHandle, b: QuatHandle, t: number): PluginApiReturn<QuatHandle>
+  /**
+   * Compute the dot product of two quaternions.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.quat.identity()
+   * const b = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+   * const d = await snaptrude.core.math.quat.dot(a, b)
+   * ```
+   */
+  abstract dot(a: QuatHandle, b: QuatHandle): PluginApiReturn<number>
+  /**
+   * Test whether two quaternions have exactly equal components.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.quat.new(0, 0, 0, 1)
+   * const b = await snaptrude.core.math.quat.identity()
+   * const same = await snaptrude.core.math.quat.equals(a, b) // true
+   * ```
+   */
+  abstract equals(a: QuatHandle, b: QuatHandle): PluginApiReturn<boolean>
+  /**
+   * Test whether two quaternions are equal within a tolerance `epsilon` (default `1e-6`).
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+   * const b = await snaptrude.core.math.quat.fromEuler(0, 1.5711, 0)
+   * const close = await snaptrude.core.math.quat.equalsApprox(a, b, 1e-3) // true
+   * ```
+   */
+  abstract equalsApprox(
+    a: QuatHandle,
+    b: QuatHandle,
+    epsilon?: number,
+  ): PluginApiReturn<boolean>
+  /**
+   * Read the primitive `{ x, y, z, w }` components of a quaternion handle.
+   *
+   * # Example
+   * ```ts
+   * const q = await snaptrude.core.math.quat.fromEuler(0, Math.PI / 2, 0)
+   * const { x, y, z, w } = await snaptrude.core.math.quat.components(q)
+   * ```
+   */
+  abstract components(q: QuatHandle): PluginApiReturn<QuatComponents>
+}

package/src/api/core/math/vec3.ts

@@ -0,0 +1,179 @@
+import { PluginApiReturn } from "../../../types"
+import { Vec3Handle, Vec3Components } from "../../../handles"
+
+/**
+ * 3D vector operations (all-handle model, §11).
+ *
+ * Vectors are opaque {@linkcode Vec3Handle}s; every operation is a host call
+ * returning a new handle (vectors are immutable). Read primitive components back
+ * with {@linkcode PluginVec3Api.components}. Accessed via `snaptrude.core.math.vec3`.
+ */
+export abstract class PluginVec3Api {
+  constructor() {}
+
+  /**
+   * Create a vector from primitive components.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(10, 0, 5)
+   * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
+   * ```
+   */
+  abstract new(x: number, y: number, z: number): PluginApiReturn<Vec3Handle>
+  /**
+   * Add two vectors component-wise (`a + b`).
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const sum = await snaptrude.core.math.vec3.add(a, b)
+   * ```
+   */
+  abstract add(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Subtract vector `b` from `a` component-wise (`a - b`).
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(3, 2, 1)
+   * const b = await snaptrude.core.math.vec3.new(1, 1, 1)
+   * const diff = await snaptrude.core.math.vec3.subtract(a, b)
+   * ```
+   */
+  abstract subtract(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Scale `v` by a scalar.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const doubled = await snaptrude.core.math.vec3.scale(v, 2)
+   * ```
+   */
+  abstract scale(v: Vec3Handle, scalar: number): PluginApiReturn<Vec3Handle>
+  /**
+   * Compute the dot product of two vectors.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(0.5, 0.5, 0)
+   * const d = await snaptrude.core.math.vec3.dot(a, b) // 0.5
+   * ```
+   */
+  abstract dot(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
+  /**
+   * Compute the cross product `a × b` — the vector perpendicular to both.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const perpendicular = await snaptrude.core.math.vec3.cross(a, b)
+   * ```
+   */
+  abstract cross(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Compute the Euclidean length (magnitude) of a vector.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(3, 4, 0)
+   * const len = await snaptrude.core.math.vec3.length(v) // 5
+   * ```
+   */
+  abstract length(v: Vec3Handle): PluginApiReturn<number>
+  /**
+   * Compute the squared Euclidean length of a vector (avoids the sqrt).
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(3, 4, 0)
+   * const sq = await snaptrude.core.math.vec3.lengthSquared(v) // 25
+   * ```
+   */
+  abstract lengthSquared(v: Vec3Handle): PluginApiReturn<number>
+  /**
+   * Return the unit vector in the same direction (the zero vector if length is 0).
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(0, 0, 10)
+   * const unit = await snaptrude.core.math.vec3.normalize(v) // (0, 0, 1)
+   * ```
+   */
+  abstract normalize(v: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Measure the straight-line (Euclidean) distance between two points.
+   *
+   * @examplePrompt What is the distance between these two points?
+   * @examplePrompt Measure how far apart these two points are
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(3, 4, 0)
+   * const dist = await snaptrude.core.math.vec3.distance(a, b) // 5
+   * ```
+   */
+  abstract distance(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
+  /**
+   * Linearly interpolate between two vectors: `a + (b - a) * t`.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const midpoint = await snaptrude.core.math.vec3.lerp(a, b, 0.5)
+   * ```
+   */
+  abstract lerp(a: Vec3Handle, b: Vec3Handle, t: number): PluginApiReturn<Vec3Handle>
+  /**
+   * Negate a vector, reversing its direction.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(1, -2, 3)
+   * const reversed = await snaptrude.core.math.vec3.negate(v) // (-1, 2, -3)
+   * ```
+   */
+  abstract negate(v: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Test whether two vectors have exactly equal components.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const b = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const same = await snaptrude.core.math.vec3.equals(a, b) // true
+   * ```
+   */
+  abstract equals(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<boolean>
+  /**
+   * Test whether two vectors are equal within a tolerance `epsilon` (default `1e-6`).
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const b = await snaptrude.core.math.vec3.new(1.0004, 2, 3)
+   * const close = await snaptrude.core.math.vec3.equalsApprox(a, b, 1e-3) // true
+   * ```
+   */
+  abstract equalsApprox(
+    a: Vec3Handle,
+    b: Vec3Handle,
+    epsilon?: number,
+  ): PluginApiReturn<boolean>
+  /**
+   * Read the primitive `{ x, y, z }` components of a vector handle.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
+   * ```
+   */
+  abstract components(v: Vec3Handle): PluginApiReturn<Vec3Components>
+}