@snaptrude/plugin-core 0.3.0 → 0.5.0

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

@@ -0,0 +1,164 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Unit-type queries and conversion.
+ *
+ * Snaptrude stores all geometry in an internal `babylon` unit. These methods
+ * read the available unit types, the internal (`babylon`) type, and the current
+ * project type; set the current project type; and convert values between any two
+ * unit types.
+ *
+ * Accessed via `snaptrude.core.units`.
+ */
+export abstract class PluginUnitsApi {
+  constructor() {}
+
+  /**
+   * List the selectable real-world unit types (excludes the internal `babylon`
+   * storage type, which is read via {@linkcode PluginUnitsApi.getBabylonType}).
+   *
+   * @examplePrompt What units can I use in this project?
+   * @examplePrompt List all the available measurement units
+   * @examplePrompt Which unit systems does Snaptrude support?
+   * @examplePrompt Show the unit options I could switch the model to
+   *
+   * # Example
+   * ```ts
+   * const types = await snaptrude.core.units.listTypes()
+   * console.log(types) // ["meters", "feet-inches", "inches", ...]
+   * ```
+   */
+  public abstract listTypes(): PluginApiReturn<PUnitType[]>
+
+  /**
+   * Get the internal storage unit type that all geometry is kept in — always
+   * `"babylon"` — for use as one side of a {@linkcode PluginUnitsApi.convert} call.
+   *
+   * @examplePrompt What unit does Snaptrude store geometry in internally?
+   * @examplePrompt Get the internal babylon unit type
+   * @examplePrompt Which unit are raw model coordinates saved in?
+   *
+   * # Example
+   * ```ts
+   * const babylon = await snaptrude.core.units.getBabylonType() // "babylon"
+   * const meters = await snaptrude.core.units.convert(10, babylon, "meters")
+   * ```
+   */
+  public abstract getBabylonType(): PluginApiReturn<PUnitType>
+
+  /**
+   * Get the current project's unit type — the unit lengths are displayed and
+   * entered in. Paired with {@linkcode PluginUnitsApi.setType}.
+   *
+   * @examplePrompt What units is this project using?
+   * @examplePrompt Are we working in metric or imperial?
+   * @examplePrompt Check the current measurement unit of the model
+   * @examplePrompt Is the file set to millimetres or feet and inches?
+   *
+   * # Example
+   * ```ts
+   * const type = await snaptrude.core.units.getType()
+   * console.log(type) // e.g. "millimeters"
+   * ```
+   */
+  public abstract getType(): PluginApiReturn<PUnitType>
+
+  /**
+   * Set the current project's unit type. Paired with {@linkcode PluginUnitsApi.getType}.
+   *
+   * @param type - The unit type to set as the project unit.
+   * @returns `true` if applied; `false` if `type` is not a settable project unit
+   *   (e.g. `kilometers`, `miles`, `babylon`).
+   *
+   * @examplePrompt Change the project units to millimeters
+   * @examplePrompt Switch this model to feet and inches
+   * @examplePrompt Set the working units to metric
+   * @examplePrompt Make the drawing use centimetres instead of meters
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.units.setType("meters")
+   * ```
+   */
+  public abstract setType(type: PUnitType): PluginApiReturn<boolean>
+
+  /**
+   * Convert a value between two unit types.
+   *
+   * @param value - The numeric value to convert.
+   * @param from - Source unit type.
+   * @param to - Target unit type.
+   * @param degree - (Optional) 1 = length, 2 = area, 3 = volume. Defaults to 1.
+   * @returns The converted numeric value.
+   *
+   * @examplePrompt Convert 5 meters to feet and inches
+   * @examplePrompt How many millimetres is 12 feet?
+   * @examplePrompt Change this area from internal units to square metres
+   * @examplePrompt Turn 2500 mm into meters
+   * @examplePrompt Convert a volume value from babylon units to cubic feet
+   *
+   * # Example
+   * ```ts
+   * // 5 meters → internal babylon units
+   * const b = await snaptrude.core.units.convert(5, "meters", "babylon")
+   * // an internal area → square metres
+   * const m2 = await snaptrude.core.units.convert(area, "babylon", "meters", 2)
+   * ```
+   */
+  public abstract convert(
+    value: number,
+    from: PUnitType,
+    to: PUnitType,
+    degree?: number,
+  ): PluginApiReturn<number>
+}
+
+/**
+ * Supported unit types. `babylon` is Snaptrude's internal storage unit; the rest
+ * are real-world units. Mirrors the engine `Converter.UNITS` vocabulary.
+ */
+export const PUnitType = z.enum([
+  "meters",
+  "feet-inches",
+  "inches",
+  "centimeters",
+  "millimeters",
+  "kilometers",
+  "miles",
+  "babylon",
+])
+
+export type PUnitType = z.infer<typeof PUnitType>
+
+/**
+ * Arguments for {@linkcode PluginUnitsApi.setType}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `type` | {@linkcode PUnitType} | The unit type to set as the project unit |
+ */
+export const PluginUnitsSetTypeArgs = z.object({
+  type: PUnitType,
+})
+
+export type PluginUnitsSetTypeArgs = z.infer<typeof PluginUnitsSetTypeArgs>
+
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The numeric value to convert |
+ * | `from` | {@linkcode PUnitType} | Source unit type |
+ * | `to` | {@linkcode PUnitType} | Target unit type |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) 1 = length, 2 = area, 3 = volume. Defaults to 1 |
+ */
+export const PluginUnitsConvertArgs = z.object({
+  value: z.number(),
+  from: PUnitType,
+  to: PUnitType,
+  degree: z.number().int().min(1).max(3).optional(),
+})
+
+export type PluginUnitsConvertArgs = z.infer<typeof PluginUnitsConvertArgs>

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

@@ -0,0 +1,47 @@
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Camera zoom controls.
+ *
+ * Frame the viewport camera onto scene geometry — mirrors the canvas zoom menu
+ * ("Zoom extents" / "Zoom to selection"). Accessed via `snaptrude.core.zoom`.
+ */
+export abstract class PluginZoomApi {
+  constructor() {}
+
+  /**
+   * Zoom (fit) the camera to all geometry in the scene — the "zoom extents" action.
+   *
+   * @returns `true` once the camera has been framed to the scene.
+   *
+   * @examplePrompt Zoom out so I can see the whole model
+   * @examplePrompt Fit everything in the view
+   * @examplePrompt Frame the entire building in the viewport
+   * @examplePrompt Do a zoom extents on the canvas
+   * @examplePrompt Show me the full scene
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.zoom.extents()
+   * ```
+   */
+  public abstract extents(): PluginApiReturn<boolean>
+
+  /**
+   * Zoom (fit) the camera to the current selection.
+   *
+   * @returns `true` if there was a selection to frame; `false` if nothing is
+   *   selected (no-op).
+   *
+   * @examplePrompt Zoom in on what I have selected
+   * @examplePrompt Frame the selected walls in the view
+   * @examplePrompt Focus the camera on my current selection
+   * @examplePrompt Fit the view to the selected room
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.zoom.selection()
+   * ```
+   */
+  public abstract selection(): PluginApiReturn<boolean>
+}

package/src/api/design/boolean/index.ts

@@ -0,0 +1,179 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { BooleanOutcome } from "../shared"
+
+/**
+ * `snaptrude.design.boolean` — OpenCascade CSG on scene masses/spaces.
+ *
+ * Every method **commits** the operation as one undoable step (engine `run()`
+ * queues create/delete/group/dimension commands, `execute()` runs them through
+ * `CommandManager`) and returns the committed {@linkcode BooleanOutcome}. Failures
+ * **throw** (RPC rejects) — no `Result<>` monad crosses the boundary.
+ *
+ * Eligibility (all inputs): a `Mass` that is a room OR a DEPARTMENT, has a brep, is
+ * unlocked (mesh + bucket), visible, and NOT in a parametric-copy group; the whole
+ * set must be all-planar OR all-non-planar; **≥2** components; all inputs share one
+ * group or are ungrouped; inputs must be adjacent/overlapping.
+ *
+ * `design.boolean.subtract` is a **CSG geometry delete** — distinct from
+ * `design.delete.entities` (hard entity removal) and `design.erase.edge`
+ * (adjacency-edge topology op).
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignBooleanApi {
+  constructor() {}
+
+  /**
+   * Fuse two or more masses into a single combined mass (`A ∪ B ∪ …`) — a boolean
+   * (CSG) union that merges the adjacent or overlapping inputs into one solid,
+   * committed as a single undoable step. Order-independent.
+   * @param components - The ≥2 entities to fuse (order-independent)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws if inputs are ineligible, disjoint, non-manifold when joined, span
+   *   different groups, or the CSG yields no / invalid geometry.
+   *
+   * @examplePrompt Merge these two masses into one
+   * @examplePrompt Union the selected volumes into a single mass
+   * @examplePrompt Combine the overlapping rooms into one shape
+   * @examplePrompt Join the tower and podium blocks together
+   * @examplePrompt Fuse all the selected massing blocks into a single solid
+   *
+   * # Example
+   * ```ts
+   * // Fuse the overlapping massing blocks on the ground storey into one solid
+   * const masses = await snaptrude.design.query.listMasses({ storeys: [1] })
+   * const { created, deleted } = await snaptrude.design.boolean.union(masses)
+   * console.log("created", created.length, "mass; consumed", deleted.length)
+   * ```
+   */
+  public abstract union(
+    components: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+
+  /**
+   * Cut one or more tool masses out of a target mass (`target − ⋃tools`) — a
+   * boolean (CSG) subtraction that carves the tools' volume out of the target and
+   * commits the remainder as a single undoable step.
+   *
+   * ORDER-SENSITIVE: the host seeds `[target, ...tools]`; index 0 is the arg brep,
+   * the rest are tool breps. `deleted` includes the target AND every tool;
+   * `created` is the remainder mass(es).
+   * @param target - The entity subtracted FROM (arg brep)
+   * @param tools - The ≥1 entities subtracted (tool breps)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws as {@linkcode union}; a `NoResult` here carries the "select the target
+   *   object first" hint from the engine.
+   *
+   * @examplePrompt Cut this shape out of the bigger mass
+   * @examplePrompt Subtract the cylinder from the building volume
+   * @examplePrompt Punch an opening through this block using the small box
+   * @examplePrompt Carve the courtyard volume out of the main massing
+   * @examplePrompt Remove the overlapping part of mass B from mass A
+   *
+   * # Example
+   * ```ts
+   * // Order matters: the first arg is the target, the array holds the tools
+   * const [building, courtyard] = await snaptrude.design.selection.get()
+   * const { created, deleted } = await snaptrude.design.boolean.subtract(building, [courtyard])
+   * // deleted includes the target AND every tool; created is the remainder
+   * ```
+   */
+  public abstract subtract(
+    target: ComponentHandle,
+    tools: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+
+  /**
+   * Keep only the overlapping volume of exactly two masses (`A ∩ B`) — a boolean
+   * (CSG) intersection that discards everything outside the shared region and
+   * commits the overlap as a single undoable step. Order-independent.
+   *
+   * HARD constraint: **EXACTLY 2** components (schema `.length(2)`; the engine
+   * also throws `MoreThan2ComponentsForIntersect` on >2).
+   * @param components - **EXACTLY 2** entities to intersect (order-independent)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws as {@linkcode union}, plus `MoreThan2ComponentsForIntersect` on >2.
+   *
+   * @examplePrompt Keep only the part where these two masses overlap
+   * @examplePrompt Intersect the two selected volumes
+   * @examplePrompt Give me the common volume between the tower and the zoning envelope
+   * @examplePrompt Trim this mass down to just its overlap with the other one
+   *
+   * # Example
+   * ```ts
+   * // Keep only the overlap of the tower and the zoning envelope (EXACTLY 2 inputs),
+   * // shifting the result mass 10 units in x via the optional offset
+   * const [tower, envelope] = await snaptrude.design.query.listMasses()
+   * const offset = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const { created } = await snaptrude.design.boolean.intersect([tower, envelope], { offset })
+   * ```
+   */
+  public abstract intersect(
+    components: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+}
+
+/**
+ * Optional knobs shared by all boolean ops. The only safe one is a world-space
+ * translation applied to the output mass(es) — maps to `Boolean3dOperation.offset`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `offset` | {@linkcode Vec3Handle} | Translation added to the created result mass(es) (default: none) |
+ */
+export const BooleanOptions = z.object({
+  offset: Vec3Handle.optional(),
+})
+export type BooleanOptions = z.infer<typeof BooleanOptions>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.union}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The ≥2 entities to fuse (order-independent) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanUnionArgs = z.object({
+  components: z.array(ComponentHandle).min(2),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanUnionArgs = z.infer<typeof PluginDesignBooleanUnionArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.subtract}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `target` | {@linkcode ComponentHandle} | The entity subtracted FROM (arg brep) |
+ * | `tools` | {@linkcode ComponentHandle}`[]` | The ≥1 entities subtracted (tool breps) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanSubtractArgs = z.object({
+  target: ComponentHandle,
+  tools: z.array(ComponentHandle).min(1),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanSubtractArgs = z.infer<typeof PluginDesignBooleanSubtractArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.intersect}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | **EXACTLY 2** entities to intersect (order-independent) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanIntersectArgs = z.object({
+  components: z.array(ComponentHandle).length(2),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanIntersectArgs = z.infer<typeof PluginDesignBooleanIntersectArgs>