@snaptrude/plugin-core 0.3.0 → 0.6.0

package/src/api/core/geom/update/contour.ts

@@ -0,0 +1,315 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  ContourHandle,
+  ProfileHandle,
+  Vec3Handle,
+  Vec3Components,
+} from "../../../../handles"
+
+/**
+ * Contour editing — produce NEW contours from an existing one (all-handle model, §11).
+ *
+ * A contour is an outer {@linkcode ProfileHandle} plus zero or more inner profiles
+ * that punch holes in it. Every method here is an immutable derive-new operation:
+ * it takes an opaque {@linkcode ContourHandle} (plus any extra inputs) and returns a
+ * fresh {@linkcode ContourHandle} for the resulting contour. The input contour is
+ * never mutated — the original handle keeps referring to the unchanged contour. Read
+ * the resulting geometry back as plain values with the query namespace.
+ *
+ * Accessed via `snaptrude.core.geom.update.contour`.
+ */
+export abstract class PluginGeomUpdateContourApi {
+  constructor() {}
+
+  /**
+   * Offset a contour inward/outward by a signed distance. Immutable — returns a NEW
+   * contour and leaves the input unchanged.
+   *
+   * @param contour The contour to offset
+   * @param distance Signed offset distance (outward when positive, inward when negative)
+   * @returns The offset contour as a NEW {@linkcode ContourHandle}
+   *
+   * @examplePrompt Offset this boundary 500mm inward
+   * @examplePrompt Shrink this floor outline by half a metre all around
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(10, 8)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const inset = await snaptrude.core.geom.update.contour.offset(contour, -0.5)
+   * const area = await snaptrude.core.geom.query.contour.getArea(inset)
+   * ```
+   */
+  public abstract offset(
+    contour: ContourHandle,
+    distance: number,
+  ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Translate a contour by a vector. Immutable — returns a NEW contour and leaves
+   * the input unchanged.
+   *
+   * @param contour The contour to move
+   * @param translation Translation vector to move the contour by
+   * @returns The moved contour as a NEW {@linkcode ContourHandle}
+   *
+   * @examplePrompt Move this shape 2 metres to the right
+   * @examplePrompt Shift this outline over by 5 feet
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const shift = await snaptrude.core.math.vec3.new(2, 0, 0)
+   * const moved = await snaptrude.core.geom.update.contour.move(contour, shift)
+   * ```
+   */
+  public abstract move(
+    contour: ContourHandle,
+    translation: Vec3Handle,
+  ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Rotate a contour about an axis through an optional pivot. Immutable — returns a
+   * NEW contour and leaves the input unchanged.
+   *
+   * @param contour The contour to rotate
+   * @param axis Rotation axis direction
+   * @param angle Rotation angle in radians
+   * @param pivot Optional pivot point to rotate about (defaults to the origin)
+   * @returns The rotated contour as a NEW {@linkcode ContourHandle}
+   *
+   * @examplePrompt Rotate this shape 45 degrees
+   * @examplePrompt Turn this outline 90 degrees about its corner
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const axis = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const pivot = await snaptrude.core.math.vec3.new(3, 0, 2)
+   * const rotated = await snaptrude.core.geom.update.contour.rotate(contour, axis, Math.PI / 4, pivot)
+   * ```
+   */
+  public abstract rotate(
+    contour: ContourHandle,
+    axis: Vec3Handle,
+    angle: number,
+    pivot?: Vec3Handle,
+  ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Scale a contour uniformly or per-axis about an optional pivot. Immutable —
+   * returns a NEW contour and leaves the input unchanged.
+   *
+   * @param contour The contour to scale
+   * @param factor Uniform scale factor, or per-axis factors
+   * @param pivot Optional pivot point to scale about (defaults to the origin)
+   * @returns The scaled contour as a NEW {@linkcode ContourHandle}
+   *
+   * @examplePrompt Scale this shape up by a factor of 2
+   * @examplePrompt Make this outline half its current size
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const doubled = await snaptrude.core.geom.update.contour.scale(contour, 2)
+   * const stretched = await snaptrude.core.geom.update.contour.scale(contour, { x: 2, y: 1, z: 1 })
+   * ```
+   */
+  public abstract scale(
+    contour: ContourHandle,
+    factor: number | Vec3Components,
+    pivot?: Vec3Handle,
+  ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Mirror a contour across a plane. Immutable — returns a NEW contour and leaves
+   * the input unchanged.
+   *
+   * @param contour The contour to mirror
+   * @param plane Mirror plane defined by a point on it and its normal
+   * @returns The mirrored contour as a NEW {@linkcode ContourHandle}
+   *
+   * @examplePrompt Mirror this shape across the gridline
+   * @examplePrompt Flip this outline to its mirror image
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(6, 4)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const point = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const normal = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const mirrored = await snaptrude.core.geom.update.contour.mirror(contour, { point, normal })
+   * ```
+   */
+  public abstract mirror(
+    contour: ContourHandle,
+    plane: { point: Vec3Handle; normal: Vec3Handle },
+  ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Add a hole to a contour by appending an inner profile. Immutable — returns a NEW
+   * contour and leaves the input unchanged.
+   *
+   * @param contour The contour to add a hole to
+   * @param hole The inner profile to add as a hole
+   * @returns The contour with the added hole as a NEW {@linkcode ContourHandle}
+   *
+   * @examplePrompt Cut a hole in this shape
+   * @examplePrompt Punch an opening through this floor outline
+   *
+   * # Example
+   * ```ts
+   * const outer = await snaptrude.core.geom.create.profileRect(10, 8)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(outer)
+   * const hole = await snaptrude.core.geom.create.profileRect(2, 2)
+   * const withHole = await snaptrude.core.geom.update.contour.addHole(contour, hole)
+   * const count = await snaptrude.core.geom.query.contour.getHoleCount(withHole) // 1
+   * ```
+   */
+  public abstract addHole(
+    contour: ContourHandle,
+    hole: ProfileHandle,
+  ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Remove a hole from a contour by inner-profile index. Immutable — returns a NEW
+   * contour and leaves the input unchanged.
+   *
+   * @param contour The contour to remove a hole from
+   * @param index Zero-based index of the inner profile (hole) to remove
+   * @returns The contour with the hole removed as a NEW {@linkcode ContourHandle}
+   *
+   * @examplePrompt Remove the hole from this shape
+   * @examplePrompt Fill in the opening in this floor outline
+   *
+   * # Example
+   * ```ts
+   * const outer = await snaptrude.core.geom.create.profileRect(10, 8)
+   * const hole = await snaptrude.core.geom.create.profileRect(2, 2)
+   * const contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])
+   * const solid = await snaptrude.core.geom.update.contour.removeHole(contour, 0)
+   * ```
+   */
+  public abstract removeHole(
+    contour: ContourHandle,
+    index: number,
+  ): PluginApiReturn<ContourHandle>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateContourApi.offset}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to offset |
+ * | `distance` | `number` | Signed offset distance (outward when positive, inward when negative) |
+ */
+export const PluginGeomUpdateContourOffsetArgs = z.object({
+  contour: ContourHandle,
+  distance: z.number(),
+})
+
+export type PluginGeomUpdateContourOffsetArgs = z.infer<typeof PluginGeomUpdateContourOffsetArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateContourApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to move |
+ * | `translation` | {@linkcode Vec3Handle} | Translation vector to move the contour by |
+ */
+export const PluginGeomUpdateContourMoveArgs = z.object({
+  contour: ContourHandle,
+  translation: Vec3Handle,
+})
+
+export type PluginGeomUpdateContourMoveArgs = z.infer<typeof PluginGeomUpdateContourMoveArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateContourApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to rotate |
+ * | `axis` | {@linkcode Vec3Handle} | Rotation axis direction |
+ * | `angle` | `number` | Rotation angle in radians |
+ * | `pivot` | {@linkcode Vec3Handle} | Optional pivot point to rotate about (defaults to the origin) |
+ */
+export const PluginGeomUpdateContourRotateArgs = z.object({
+  contour: ContourHandle,
+  axis: Vec3Handle,
+  angle: z.number(),
+  pivot: Vec3Handle.optional(),
+})
+
+export type PluginGeomUpdateContourRotateArgs = z.infer<typeof PluginGeomUpdateContourRotateArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateContourApi.scale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to scale |
+ * | `factor` | `number` \| {@linkcode Vec3Components} | Uniform scale factor, or per-axis factors |
+ * | `pivot` | {@linkcode Vec3Handle} | Optional pivot point to scale about (defaults to the origin) |
+ */
+export const PluginGeomUpdateContourScaleArgs = z.object({
+  contour: ContourHandle,
+  factor: z.union([z.number(), Vec3Components]),
+  pivot: Vec3Handle.optional(),
+})
+
+export type PluginGeomUpdateContourScaleArgs = z.infer<typeof PluginGeomUpdateContourScaleArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateContourApi.mirror}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to mirror |
+ * | `plane` | `{ point: `{@linkcode Vec3Handle}`, normal: `{@linkcode Vec3Handle}` }` | Mirror plane defined by a point on it and its normal |
+ */
+export const PluginGeomUpdateContourMirrorArgs = z.object({
+  contour: ContourHandle,
+  plane: z.object({
+    point: Vec3Handle,
+    normal: Vec3Handle,
+  }),
+})
+
+export type PluginGeomUpdateContourMirrorArgs = z.infer<typeof PluginGeomUpdateContourMirrorArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateContourApi.addHole}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to add a hole to |
+ * | `hole` | {@linkcode ProfileHandle} | The inner profile to add as a hole |
+ */
+export const PluginGeomUpdateContourAddHoleArgs = z.object({
+  contour: ContourHandle,
+  hole: ProfileHandle,
+})
+
+export type PluginGeomUpdateContourAddHoleArgs = z.infer<typeof PluginGeomUpdateContourAddHoleArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateContourApi.removeHole}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The contour to remove a hole from |
+ * | `index` | `number` | Zero-based index of the inner profile (hole) to remove |
+ */
+export const PluginGeomUpdateContourRemoveHoleArgs = z.object({
+  contour: ContourHandle,
+  index: z.number(),
+})
+
+export type PluginGeomUpdateContourRemoveHoleArgs = z.infer<typeof PluginGeomUpdateContourRemoveHoleArgs>

package/src/api/core/geom/update/curve.ts

@@ -0,0 +1,209 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { Vec3Handle, CurveHandle } from "../../../../handles"
+
+/**
+ * Curve editing — produce NEW curves from an existing one (all-handle model, §11).
+ *
+ * Every method takes an opaque {@linkcode CurveHandle} and returns a fresh handle
+ * (or handles) for the resulting geometry; the input curve is never mutated. Read
+ * the resulting geometry back as plain values with the query namespace.
+ *
+ * Accessed via `snaptrude.core.geom.update.curve`.
+ */
+export abstract class PluginGeomUpdateCurveApi {
+  constructor() {}
+
+  /**
+   * Extend a curve by a distance from one of its ends. Host API call — returns a handle.
+   *
+   * @param curve - The curve to extend
+   * @param distance - Distance to extend the curve by
+   * @param fromStart - Extend from the start end when `true`, otherwise from the end
+   * @returns The extended curve as a {@linkcode CurveHandle}
+   *
+   * @examplePrompt Extend this line by 1 metre
+   * @examplePrompt Lengthen this edge from its start point
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const longer = await snaptrude.core.geom.update.curve.extend(line, 1, false)
+   * const length = await snaptrude.core.geom.query.curve.getLength(longer) // 6
+   * ```
+   */
+  public abstract extend(
+    curve: CurveHandle,
+    distance: number,
+    fromStart: boolean,
+  ): PluginApiReturn<CurveHandle>
+
+  /**
+   * Split a curve at a point into separate segments. Host API call — returns handles.
+   *
+   * @param curve - The curve to split
+   * @param point - Point on the curve to split at
+   * @returns The resulting segments as {@linkcode CurveHandle}`[]`
+   *
+   * @examplePrompt Split this line at its midpoint
+   * @examplePrompt Break this edge into two pieces where it meets the gridline
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(6, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const mid = await snaptrude.core.math.vec3.new(3, 0, 0)
+   * const [left, right] = await snaptrude.core.geom.update.curve.split(line, mid)
+   * ```
+   */
+  public abstract split(
+    curve: CurveHandle,
+    point: Vec3Handle,
+  ): PluginApiReturn<CurveHandle[]>
+
+  /**
+   * Trim a curve to the portion between two parameter values. Host API call — returns a handle.
+   *
+   * @param curve - The curve to trim
+   * @param startParam - Start parameter of the portion to keep
+   * @param endParam - End parameter of the portion to keep
+   * @returns The trimmed curve as a {@linkcode CurveHandle}
+   *
+   * @examplePrompt Trim this line back to a shorter segment
+   * @examplePrompt Keep only the middle portion of this curve
+   *
+   * # 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 line = await snaptrude.core.geom.create.line(a, b)
+   * const middle = await snaptrude.core.geom.update.curve.trim(line, 0.25, 0.75)
+   * ```
+   */
+  public abstract trim(
+    curve: CurveHandle,
+    startParam: number,
+    endParam: number,
+  ): PluginApiReturn<CurveHandle>
+
+  /**
+   * Offset a curve by a translation vector. Host API call — returns a handle.
+   *
+   * @param curve - The curve to offset
+   * @param vector - Translation vector to offset the curve by
+   * @returns The offset curve as a {@linkcode CurveHandle}
+   *
+   * @examplePrompt Offset this line 500mm to the side
+   * @examplePrompt Shift this edge over to make a parallel copy
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(8, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const sideways = await snaptrude.core.math.vec3.new(0, 0, 0.5)
+   * const parallel = await snaptrude.core.geom.update.curve.offset(line, sideways)
+   * ```
+   */
+  public abstract offset(
+    curve: CurveHandle,
+    vector: Vec3Handle,
+  ): PluginApiReturn<CurveHandle>
+
+  /**
+   * Reverse the direction of a curve. Host API call — returns a handle.
+   *
+   * @param curve - The curve to reverse
+   * @returns The reversed curve as a {@linkcode CurveHandle}
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(4, 0, 0)
+   * const line = await snaptrude.core.geom.create.line(a, b)
+   * const reversed = await snaptrude.core.geom.update.curve.reverse(line)
+   * const start = await snaptrude.core.geom.query.curve.getStartPoint(reversed) // { x: 4, y: 0, z: 0 }
+   * ```
+   */
+  public abstract reverse(curve: CurveHandle): PluginApiReturn<CurveHandle>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateCurveApi.extend}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to extend |
+ * | `distance` | `number` | Distance to extend the curve by |
+ * | `fromStart` | `boolean` | Extend from the start end when `true`, otherwise from the end |
+ */
+export const PluginGeomUpdateCurveExtendArgs = z.object({
+  curve: CurveHandle,
+  distance: z.number(),
+  fromStart: z.boolean(),
+})
+
+export type PluginGeomUpdateCurveExtendArgs = z.infer<typeof PluginGeomUpdateCurveExtendArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateCurveApi.split}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to split |
+ * | `point` | {@linkcode Vec3Handle} | Point on the curve to split at |
+ */
+export const PluginGeomUpdateCurveSplitArgs = z.object({
+  curve: CurveHandle,
+  point: Vec3Handle,
+})
+
+export type PluginGeomUpdateCurveSplitArgs = z.infer<typeof PluginGeomUpdateCurveSplitArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateCurveApi.trim}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to trim |
+ * | `startParam` | `number` | Start parameter of the portion to keep |
+ * | `endParam` | `number` | End parameter of the portion to keep |
+ */
+export const PluginGeomUpdateCurveTrimArgs = z.object({
+  curve: CurveHandle,
+  startParam: z.number(),
+  endParam: z.number(),
+})
+
+export type PluginGeomUpdateCurveTrimArgs = z.infer<typeof PluginGeomUpdateCurveTrimArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateCurveApi.offset}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to offset |
+ * | `vector` | {@linkcode Vec3Handle} | Translation vector to offset the curve by |
+ */
+export const PluginGeomUpdateCurveOffsetArgs = z.object({
+  curve: CurveHandle,
+  vector: Vec3Handle,
+})
+
+export type PluginGeomUpdateCurveOffsetArgs = z.infer<typeof PluginGeomUpdateCurveOffsetArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomUpdateCurveApi.reverse}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to reverse |
+ */
+export const PluginGeomUpdateCurveReverseArgs = z.object({
+  curve: CurveHandle,
+})
+
+export type PluginGeomUpdateCurveReverseArgs = z.infer<typeof PluginGeomUpdateCurveReverseArgs>

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

@@ -0,0 +1,29 @@
+import { PluginGeomUpdateCurveApi } from "./curve"
+import { PluginGeomUpdateProfileApi } from "./profile"
+import { PluginGeomUpdateContourApi } from "./contour"
+
+/**
+ * Curve/profile/contour update namespace — derive NEW geometry by editing existing
+ * handles (all-handle model, §11). Inputs are never mutated; every method returns a
+ * fresh handle.
+ *
+ * - {@linkcode PluginGeomUpdateApi.curve} — extend, split, trim, offset, reverse
+ * - {@linkcode PluginGeomUpdateApi.profile} — offset, affine, add/remove/reverse/simplify
+ * - {@linkcode PluginGeomUpdateApi.contour} — offset, affine, addHole/removeHole
+ *
+ * Accessed via `snaptrude.core.geom.update`.
+ */
+export abstract class PluginGeomUpdateApi {
+  /** Curve editing operations. See {@linkcode PluginGeomUpdateCurveApi}. */
+  public abstract curve: PluginGeomUpdateCurveApi
+  /** Profile editing operations. See {@linkcode PluginGeomUpdateProfileApi}. */
+  public abstract profile: PluginGeomUpdateProfileApi
+  /** Contour editing operations. See {@linkcode PluginGeomUpdateContourApi}. */
+  public abstract contour: PluginGeomUpdateContourApi
+
+  constructor() {}
+}
+
+export * from "./curve"
+export * from "./profile"
+export * from "./contour"