@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

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

@@ -0,0 +1,84 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { ProfileHandle, ContourHandle } from "../../../../handles"
+
+/**
+ * Geometry deletion — release transient geometry resource handles (all-handle model, §11).
+ *
+ * Methods here free a handle's backing registry entry and reclaim its share of the
+ * plugin's resource quota. This is purely a handle-lifecycle operation: it does NOT
+ * tear down or delete any engine-side geometry. Once released, the handle is no
+ * longer resolvable and must not be reused.
+ *
+ * Accessed via `snaptrude.core.geom.delete`.
+ */
+export abstract class PluginGeomDeleteApi {
+  constructor() {}
+
+  /**
+   * Free a transient profile resource handle — releases its registry entry and
+   * reclaims its share of the plugin's resource quota. This is a handle-lifecycle
+   * operation only and does NOT tear down any engine-side geometry.
+   *
+   * @deprecated Use `core.handles.release([profile])` — the universal, batched
+   * release API for every arena handle kind.
+   *
+   * @param profile The transient profile handle to release
+   * @returns Nothing
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const area = await snaptrude.core.geom.query.profile.getArea(rect)
+   * await snaptrude.core.geom.delete.profile(rect) // rect is no longer resolvable
+   * ```
+   */
+  public abstract profile(profile: ProfileHandle): PluginApiReturn<void>
+
+  /**
+   * Free a transient contour resource handle — releases its registry entry and
+   * reclaims its share of the plugin's resource quota. Handle-lifecycle only; does
+   * NOT tear down engine-side geometry, nor the contour's child profile handles.
+   *
+   * @deprecated Use `core.handles.release([contour])` — the universal, batched
+   * release API for every arena handle kind.
+   *
+   * @param contour The transient contour handle to release
+   * @returns Nothing
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const area = await snaptrude.core.geom.query.contour.getArea(contour)
+   * await snaptrude.core.geom.delete.contour(contour) // contour freed; rect still valid
+   * ```
+   */
+  public abstract contour(contour: ContourHandle): PluginApiReturn<void>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomDeleteApi.profile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | The transient profile handle to release |
+ */
+export const PluginGeomDeleteProfileArgs = z.object({
+  profile: ProfileHandle,
+})
+
+export type PluginGeomDeleteProfileArgs = z.infer<typeof PluginGeomDeleteProfileArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomDeleteApi.contour}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The transient contour handle to release |
+ */
+export const PluginGeomDeleteContourArgs = z.object({
+  contour: ContourHandle,
+})
+
+export type PluginGeomDeleteContourArgs = z.infer<typeof PluginGeomDeleteContourArgs>

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

@@ -0,0 +1,35 @@
+import { PluginGeomCreateApi } from "./create"
+import { PluginGeomQueryApi } from "./query"
+import { PluginGeomUpdateApi } from "./update"
+import { PluginGeomDeleteApi } from "./delete"
+
+/**
+ * Geometry kernel — domain-free construction, query, editing, and disposal of
+ * curves (lines / arcs) and profiles. No BIM/AEC knowledge lives here; build
+ * geometry bottom-up: points ({@linkcode Vec3Handle}) → curves → profiles → entities.
+ *
+ * - {@linkcode PluginGeomApi.create} — construct lines, arcs, and profiles
+ * - {@linkcode PluginGeomApi.query} — read curve / arc / profile geometry and relationships
+ * - {@linkcode PluginGeomApi.update} — derive new curves / profiles (immutable edits)
+ * - {@linkcode PluginGeomApi.delete} — free a transient profile resource handle
+ *
+ * Profiles can then be used with entity creation methods like
+ * {@linkcode PluginSpaceApi.createFromProfile}.
+ */
+export abstract class PluginGeomApi {
+  /** Curve and profile construction. See {@linkcode PluginGeomCreateApi}. */
+  public abstract create: PluginGeomCreateApi
+  /** Curve, arc, and profile queries. See {@linkcode PluginGeomQueryApi}. */
+  public abstract query: PluginGeomQueryApi
+  /** Curve and profile editing (derive-new). See {@linkcode PluginGeomUpdateApi}. */
+  public abstract update: PluginGeomUpdateApi
+  /** Resource-handle disposal (profile). See {@linkcode PluginGeomDeleteApi}. */
+  public abstract delete: PluginGeomDeleteApi
+
+  constructor() {}
+}
+
+export * from "./create"
+export * from "./query"
+export * from "./update"
+export * from "./delete"

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

@@ -0,0 +1,169 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { ArcHandle, Vec3Components } from "../../../../handles"
+
+/**
+ * Arc-specific geometry queries — read circular-arc properties as plain values.
+ *
+ * Every method takes an opaque {@linkcode ArcHandle} and returns plain values
+ * (numbers or {@linkcode Vec3Components}), never a handle. Use these to inspect
+ * the radius, centre, axis, sweep angle, and validity of an arc handle obtained
+ * from {@linkcode PluginGeomCreateApi.arc} or another query.
+ *
+ * Accessed via `snaptrude.core.geom.query.arc`.
+ */
+export abstract class PluginGeomQueryArcApi {
+  constructor() {}
+
+  /**
+   * Read the radius of an arc.
+   *
+   * @param arc The arc to query
+   * @returns The arc radius as a `number`
+   *
+   * @examplePrompt What is the radius of this curved wall segment?
+   * @examplePrompt Measure the radius of the selected arc
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const end = await snaptrude.core.math.vec3.new(0, 0, 5)
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const arc = await snaptrude.core.geom.create.arc(start, end, origin, up)
+   * const radius = await snaptrude.core.geom.query.arc.getRadius(arc)
+   * ```
+   */
+  public abstract getRadius(arc: ArcHandle): PluginApiReturn<number>
+
+  /**
+   * Read the centre point of an arc.
+   *
+   * @param arc The arc to query
+   * @returns The arc centre as {@linkcode Vec3Components}
+   *
+   * @examplePrompt Where is the centre of this arc?
+   * @examplePrompt Find the center point of the curved wall
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const end = await snaptrude.core.math.vec3.new(0, 0, 5)
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const arc = await snaptrude.core.geom.create.arc(start, end, origin, up)
+   * const centre = await snaptrude.core.geom.query.arc.getCentre(arc)
+   * console.log(centre.x, centre.y, centre.z)
+   * ```
+   */
+  public abstract getCentre(arc: ArcHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Read the rotation axis of an arc.
+   *
+   * @param arc The arc to query
+   * @returns The arc axis as {@linkcode Vec3Components}
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const end = await snaptrude.core.math.vec3.new(0, 0, 5)
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const arc = await snaptrude.core.geom.create.arc(start, end, origin, up)
+   * const axis = await snaptrude.core.geom.query.arc.getAxis(arc)
+   * console.log(axis.x, axis.y, axis.z)
+   * ```
+   */
+  public abstract getAxis(arc: ArcHandle): PluginApiReturn<Vec3Components>
+
+  /**
+   * Read the sweep angle of an arc (the angle subtended at its centre).
+   *
+   * @param arc The arc to query
+   * @returns The sweep angle in radians as a `number`
+   *
+   * @examplePrompt What angle does this arc sweep through?
+   * @examplePrompt How many degrees does this curved wall turn?
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const end = await snaptrude.core.math.vec3.new(0, 0, 5)
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const arc = await snaptrude.core.geom.create.arc(start, end, origin, up)
+   * const sweep = await snaptrude.core.geom.query.arc.getSweepAngle(arc)
+   * console.log("degrees:", (sweep * 180) / Math.PI)
+   * ```
+   */
+  public abstract getSweepAngle(arc: ArcHandle): PluginApiReturn<number>
+
+  /**
+   * Check whether an arc is geometrically valid.
+   *
+   * @param arc The arc to query
+   * @returns `true` if the arc is valid as a `boolean`
+   *
+   * # Example
+   * ```ts
+   * const start = await snaptrude.core.math.vec3.new(5, 0, 0)
+   * const end = await snaptrude.core.math.vec3.new(0, 0, 5)
+   * const origin = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const up = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const arc = await snaptrude.core.geom.create.arc(start, end, origin, up)
+   * const ok = await snaptrude.core.geom.query.arc.isValid(arc)
+   * ```
+   */
+  public abstract isValid(arc: ArcHandle): PluginApiReturn<boolean>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryArcApi.getRadius}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `arc` | {@linkcode ArcHandle} | The arc to query |
+ */
+export const PluginGeomQueryArcGetRadiusArgs = z.object({ arc: ArcHandle })
+export type PluginGeomQueryArcGetRadiusArgs = z.infer<typeof PluginGeomQueryArcGetRadiusArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryArcApi.getCentre}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `arc` | {@linkcode ArcHandle} | The arc to query |
+ */
+export const PluginGeomQueryArcGetCentreArgs = z.object({ arc: ArcHandle })
+export type PluginGeomQueryArcGetCentreArgs = z.infer<typeof PluginGeomQueryArcGetCentreArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryArcApi.getAxis}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `arc` | {@linkcode ArcHandle} | The arc to query |
+ */
+export const PluginGeomQueryArcGetAxisArgs = z.object({ arc: ArcHandle })
+export type PluginGeomQueryArcGetAxisArgs = z.infer<typeof PluginGeomQueryArcGetAxisArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryArcApi.getSweepAngle}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `arc` | {@linkcode ArcHandle} | The arc to query |
+ */
+export const PluginGeomQueryArcGetSweepAngleArgs = z.object({ arc: ArcHandle })
+export type PluginGeomQueryArcGetSweepAngleArgs = z.infer<typeof PluginGeomQueryArcGetSweepAngleArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryArcApi.isValid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `arc` | {@linkcode ArcHandle} | The arc to query |
+ */
+export const PluginGeomQueryArcIsValidArgs = z.object({ arc: ArcHandle })
+export type PluginGeomQueryArcIsValidArgs = z.infer<typeof PluginGeomQueryArcIsValidArgs>