@snaptrude/plugin-core 1.0.2 → 1.0.4

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

@@ -3,6 +3,7 @@ import { PluginApiReturn } from "../../../../types"
 import {
   ProfileHandle,
   Vec3Handle,
+  Vec3Input,
   CurveHandle,
   Vec3Components,
   BBoxComponents,
@@ -136,7 +137,7 @@ export abstract class PluginGeomQueryProfileApi {
    */
   public abstract getNearestPoint(
     profile: ProfileHandle,
-    point: Vec3Handle,
+    point: Vec3Input,
   ): PluginApiReturn<Vec3Components>
 
   /**
@@ -157,7 +158,7 @@ export abstract class PluginGeomQueryProfileApi {
    */
   public abstract hasPoint(
     profile: ProfileHandle,
-    point: Vec3Handle,
+    point: Vec3Input,
   ): PluginApiReturn<boolean>
 
   /**
@@ -175,7 +176,7 @@ export abstract class PluginGeomQueryProfileApi {
    */
   public abstract isOnBoundary(
     profile: ProfileHandle,
-    point: Vec3Handle,
+    point: Vec3Input,
   ): PluginApiReturn<boolean>
 
   /**
@@ -357,7 +358,7 @@ export type PluginGeomQueryProfileGetNormalArgs = z.infer<typeof PluginGeomQuery
  */
 export const PluginGeomQueryProfileGetNearestPointArgs = z.object({
   profile: ProfileHandle,
-  point: Vec3Handle,
+  point: Vec3Input,
 })
 
 export type PluginGeomQueryProfileGetNearestPointArgs = z.infer<typeof PluginGeomQueryProfileGetNearestPointArgs>
@@ -372,7 +373,7 @@ export type PluginGeomQueryProfileGetNearestPointArgs = z.infer<typeof PluginGeo
  */
 export const PluginGeomQueryProfileHasPointArgs = z.object({
   profile: ProfileHandle,
-  point: Vec3Handle,
+  point: Vec3Input,
 })
 
 export type PluginGeomQueryProfileHasPointArgs = z.infer<typeof PluginGeomQueryProfileHasPointArgs>
@@ -387,7 +388,7 @@ export type PluginGeomQueryProfileHasPointArgs = z.infer<typeof PluginGeomQueryP
  */
 export const PluginGeomQueryProfileIsOnBoundaryArgs = z.object({
   profile: ProfileHandle,
-  point: Vec3Handle,
+  point: Vec3Input,
 })
 
 export type PluginGeomQueryProfileIsOnBoundaryArgs = z.infer<typeof PluginGeomQueryProfileIsOnBoundaryArgs>

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

@@ -4,6 +4,7 @@ import {
   ContourHandle,
   ProfileHandle,
   Vec3Handle,
+  Vec3Input,
   Vec3Components,
 } from "../../../../handles"
 
@@ -69,7 +70,7 @@ export abstract class PluginGeomUpdateContourApi {
    */
   public abstract move(
     contour: ContourHandle,
-    translation: Vec3Handle,
+    translation: Vec3Input,
   ): PluginApiReturn<ContourHandle>
 
   /**
@@ -96,9 +97,9 @@ export abstract class PluginGeomUpdateContourApi {
    */
   public abstract rotate(
     contour: ContourHandle,
-    axis: Vec3Handle,
+    axis: Vec3Input,
     angle: number,
-    pivot?: Vec3Handle,
+    pivot?: Vec3Input,
   ): PluginApiReturn<ContourHandle>
 
   /**
@@ -124,7 +125,7 @@ export abstract class PluginGeomUpdateContourApi {
   public abstract scale(
     contour: ContourHandle,
     factor: number | Vec3Components,
-    pivot?: Vec3Handle,
+    pivot?: Vec3Input,
   ): PluginApiReturn<ContourHandle>
 
   /**
@@ -149,7 +150,7 @@ export abstract class PluginGeomUpdateContourApi {
    */
   public abstract mirror(
     contour: ContourHandle,
-    plane: { point: Vec3Handle; normal: Vec3Handle },
+    plane: { point: Vec3Input; normal: Vec3Input },
   ): PluginApiReturn<ContourHandle>
 
   /**
@@ -233,7 +234,7 @@ export type PluginGeomUpdateContourOffsetArgs = z.infer<typeof PluginGeomUpdateC
  */
 export const PluginGeomUpdateContourMoveArgs = z.object({
   contour: ContourHandle,
-  translation: Vec3Handle,
+  translation: Vec3Input,
 })
 
 export type PluginGeomUpdateContourMoveArgs = z.infer<typeof PluginGeomUpdateContourMoveArgs>
@@ -250,9 +251,9 @@ export type PluginGeomUpdateContourMoveArgs = z.infer<typeof PluginGeomUpdateCon
  */
 export const PluginGeomUpdateContourRotateArgs = z.object({
   contour: ContourHandle,
-  axis: Vec3Handle,
+  axis: Vec3Input,
   angle: z.number(),
-  pivot: Vec3Handle.optional(),
+  pivot: Vec3Input.optional(),
 })
 
 export type PluginGeomUpdateContourRotateArgs = z.infer<typeof PluginGeomUpdateContourRotateArgs>
@@ -269,7 +270,7 @@ export type PluginGeomUpdateContourRotateArgs = z.infer<typeof PluginGeomUpdateC
 export const PluginGeomUpdateContourScaleArgs = z.object({
   contour: ContourHandle,
   factor: z.union([z.number(), Vec3Components]),
-  pivot: Vec3Handle.optional(),
+  pivot: Vec3Input.optional(),
 })
 
 export type PluginGeomUpdateContourScaleArgs = z.infer<typeof PluginGeomUpdateContourScaleArgs>
@@ -285,8 +286,8 @@ export type PluginGeomUpdateContourScaleArgs = z.infer<typeof PluginGeomUpdateCo
 export const PluginGeomUpdateContourMirrorArgs = z.object({
   contour: ContourHandle,
   plane: z.object({
-    point: Vec3Handle,
-    normal: Vec3Handle,
+    point: Vec3Input,
+    normal: Vec3Input,
   }),
 })
 

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../../types"
-import { Vec3Handle, CurveHandle } from "../../../../handles"
+import { Vec3Handle, Vec3Input, CurveHandle } from "../../../../handles"
 
 /**
  * Curve editing — produce NEW curves from an existing one (all-handle model, §11).
@@ -61,7 +61,7 @@ export abstract class PluginGeomUpdateCurveApi {
    */
   public abstract split(
     curve: CurveHandle,
-    point: Vec3Handle,
+    point: Vec3Input,
   ): PluginApiReturn<CurveHandle[]>
 
   /**
@@ -110,7 +110,7 @@ export abstract class PluginGeomUpdateCurveApi {
    */
   public abstract offset(
     curve: CurveHandle,
-    vector: Vec3Handle,
+    vector: Vec3Input,
   ): PluginApiReturn<CurveHandle>
 
   /**
@@ -158,7 +158,7 @@ export type PluginGeomUpdateCurveExtendArgs = z.infer<typeof PluginGeomUpdateCur
  */
 export const PluginGeomUpdateCurveSplitArgs = z.object({
   curve: CurveHandle,
-  point: Vec3Handle,
+  point: Vec3Input,
 })
 
 export type PluginGeomUpdateCurveSplitArgs = z.infer<typeof PluginGeomUpdateCurveSplitArgs>
@@ -190,7 +190,7 @@ export type PluginGeomUpdateCurveTrimArgs = z.infer<typeof PluginGeomUpdateCurve
  */
 export const PluginGeomUpdateCurveOffsetArgs = z.object({
   curve: CurveHandle,
-  vector: Vec3Handle,
+  vector: Vec3Input,
 })
 
 export type PluginGeomUpdateCurveOffsetArgs = z.infer<typeof PluginGeomUpdateCurveOffsetArgs>

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

@@ -3,6 +3,7 @@ import { PluginApiReturn } from "../../../../types"
 import {
   ProfileHandle,
   Vec3Handle,
+  Vec3Input,
   CurveHandle,
   Vec3Components,
 } from "../../../../handles"
@@ -66,7 +67,7 @@ export abstract class PluginGeomUpdateProfileApi {
    */
   public abstract move(
     profile: ProfileHandle,
-    translation: Vec3Handle,
+    translation: Vec3Input,
   ): PluginApiReturn<ProfileHandle>
 
   /**
@@ -91,9 +92,9 @@ export abstract class PluginGeomUpdateProfileApi {
    */
   public abstract rotate(
     profile: ProfileHandle,
-    axis: Vec3Handle,
+    axis: Vec3Input,
     angle: number,
-    pivot?: Vec3Handle,
+    pivot?: Vec3Input,
   ): PluginApiReturn<ProfileHandle>
 
   /**
@@ -118,7 +119,7 @@ export abstract class PluginGeomUpdateProfileApi {
   public abstract scale(
     profile: ProfileHandle,
     factor: number | Vec3Components,
-    pivot?: Vec3Handle,
+    pivot?: Vec3Input,
   ): PluginApiReturn<ProfileHandle>
 
   /**
@@ -142,7 +143,7 @@ export abstract class PluginGeomUpdateProfileApi {
    */
   public abstract mirror(
     profile: ProfileHandle,
-    plane: { point: Vec3Handle; normal: Vec3Handle },
+    plane: { point: Vec3Input; normal: Vec3Input },
   ): PluginApiReturn<ProfileHandle>
 
   /**
@@ -261,7 +262,7 @@ export type PluginGeomUpdateProfileOffsetArgs = z.infer<typeof PluginGeomUpdateP
  */
 export const PluginGeomUpdateProfileMoveArgs = z.object({
   profile: ProfileHandle,
-  translation: Vec3Handle,
+  translation: Vec3Input,
 })
 
 export type PluginGeomUpdateProfileMoveArgs = z.infer<typeof PluginGeomUpdateProfileMoveArgs>
@@ -278,9 +279,9 @@ export type PluginGeomUpdateProfileMoveArgs = z.infer<typeof PluginGeomUpdatePro
  */
 export const PluginGeomUpdateProfileRotateArgs = z.object({
   profile: ProfileHandle,
-  axis: Vec3Handle,
+  axis: Vec3Input,
   angle: z.number(),
-  pivot: Vec3Handle.optional(),
+  pivot: Vec3Input.optional(),
 })
 
 export type PluginGeomUpdateProfileRotateArgs = z.infer<typeof PluginGeomUpdateProfileRotateArgs>
@@ -297,7 +298,7 @@ export type PluginGeomUpdateProfileRotateArgs = z.infer<typeof PluginGeomUpdateP
 export const PluginGeomUpdateProfileScaleArgs = z.object({
   profile: ProfileHandle,
   factor: z.union([z.number(), Vec3Components]),
-  pivot: Vec3Handle.optional(),
+  pivot: Vec3Input.optional(),
 })
 
 export type PluginGeomUpdateProfileScaleArgs = z.infer<typeof PluginGeomUpdateProfileScaleArgs>
@@ -313,8 +314,8 @@ export type PluginGeomUpdateProfileScaleArgs = z.infer<typeof PluginGeomUpdatePr
 export const PluginGeomUpdateProfileMirrorArgs = z.object({
   profile: ProfileHandle,
   plane: z.object({
-    point: Vec3Handle,
-    normal: Vec3Handle,
+    point: Vec3Input,
+    normal: Vec3Input,
   }),
 })
 

package/src/api/core/io/import/index.ts

@@ -2,6 +2,7 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../../../types"
 import {
   Vec3Handle,
+  Vec3Input,
   UnderlayHandle,
   TerrainHandle,
   ImportJobHandle,
@@ -266,7 +267,7 @@ export abstract class PluginCoreIoImportApi {
     source: string,
     storey?: number,
     format?: ModelFormat,
-    position?: Vec3Handle,
+    position?: Vec3Input,
     label?: string,
   ): PluginApiReturn<ComponentHandle>
 
@@ -445,7 +446,7 @@ export const PluginImportModelArgs = z.object({
   source: ImportSource,
   storey: z.number().int().optional(),
   format: ModelFormat.optional(),
-  position: Vec3Handle.optional(),
+  position: Vec3Input.optional(),
   label: z.string().optional(),
 })
 export type PluginImportModelArgs = z.infer<typeof PluginImportModelArgs>

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

@@ -1,5 +1,5 @@
 import { PluginApiReturn } from "../../../types"
-import { Vec3Handle, QuatHandle, QuatComponents } from "../../../handles"
+import { Vec3Handle, Vec3Input, QuatHandle, QuatComponents } from "../../../handles"
 
 /**
  * Quaternion operations (all-handle model, §11).
@@ -39,7 +39,7 @@ export abstract class PluginQuatApi {
    * const quarterTurn = await snaptrude.core.math.quat.fromAxisAngle(axis, Math.PI / 2)
    * ```
    */
-  abstract fromAxisAngle(axis: Vec3Handle, angle: number): PluginApiReturn<QuatHandle>
+  abstract fromAxisAngle(axis: Vec3Input, angle: number): PluginApiReturn<QuatHandle>
   /**
    * Build a quaternion from Euler angles in radians.
    *

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

@@ -1,5 +1,5 @@
 import { PluginApiReturn } from "../../../types"
-import { Vec3Handle, Vec3Components } from "../../../handles"
+import { Vec3Handle, Vec3Input, Vec3Components } from "../../../handles"
 
 /**
  * 3D vector operations (all-handle model, §11).
@@ -31,7 +31,7 @@ export abstract class PluginVec3Api {
    * const sum = await snaptrude.core.math.vec3.add(a, b)
    * ```
    */
-  abstract add(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  abstract add(a: Vec3Input, b: Vec3Input): PluginApiReturn<Vec3Handle>
   /**
    * Subtract vector `b` from `a` component-wise (`a - b`).
    *
@@ -42,7 +42,7 @@ export abstract class PluginVec3Api {
    * const diff = await snaptrude.core.math.vec3.subtract(a, b)
    * ```
    */
-  abstract subtract(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  abstract subtract(a: Vec3Input, b: Vec3Input): PluginApiReturn<Vec3Handle>
   /**
    * Scale `v` by a scalar.
    *
@@ -52,7 +52,7 @@ export abstract class PluginVec3Api {
    * const doubled = await snaptrude.core.math.vec3.scale(v, 2)
    * ```
    */
-  abstract scale(v: Vec3Handle, scalar: number): PluginApiReturn<Vec3Handle>
+  abstract scale(v: Vec3Input, scalar: number): PluginApiReturn<Vec3Handle>
   /**
    * Compute the dot product of two vectors.
    *
@@ -63,7 +63,7 @@ export abstract class PluginVec3Api {
    * const d = await snaptrude.core.math.vec3.dot(a, b) // 0.5
    * ```
    */
-  abstract dot(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
+  abstract dot(a: Vec3Input, b: Vec3Input): PluginApiReturn<number>
   /**
    * Compute the cross product `a × b` — the vector perpendicular to both.
    *
@@ -74,7 +74,7 @@ export abstract class PluginVec3Api {
    * const perpendicular = await snaptrude.core.math.vec3.cross(a, b)
    * ```
    */
-  abstract cross(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  abstract cross(a: Vec3Input, b: Vec3Input): PluginApiReturn<Vec3Handle>
   /**
    * Compute the Euclidean length (magnitude) of a vector.
    *
@@ -84,7 +84,7 @@ export abstract class PluginVec3Api {
    * const len = await snaptrude.core.math.vec3.length(v) // 5
    * ```
    */
-  abstract length(v: Vec3Handle): PluginApiReturn<number>
+  abstract length(v: Vec3Input): PluginApiReturn<number>
   /**
    * Compute the squared Euclidean length of a vector (avoids the sqrt).
    *
@@ -94,7 +94,7 @@ export abstract class PluginVec3Api {
    * const sq = await snaptrude.core.math.vec3.lengthSquared(v) // 25
    * ```
    */
-  abstract lengthSquared(v: Vec3Handle): PluginApiReturn<number>
+  abstract lengthSquared(v: Vec3Input): PluginApiReturn<number>
   /**
    * Return the unit vector in the same direction (the zero vector if length is 0).
    *
@@ -104,7 +104,7 @@ export abstract class PluginVec3Api {
    * const unit = await snaptrude.core.math.vec3.normalize(v) // (0, 0, 1)
    * ```
    */
-  abstract normalize(v: Vec3Handle): PluginApiReturn<Vec3Handle>
+  abstract normalize(v: Vec3Input): PluginApiReturn<Vec3Handle>
   /**
    * Measure the straight-line (Euclidean) distance between two points.
    *
@@ -118,7 +118,7 @@ export abstract class PluginVec3Api {
    * const dist = await snaptrude.core.math.vec3.distance(a, b) // 5
    * ```
    */
-  abstract distance(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
+  abstract distance(a: Vec3Input, b: Vec3Input): PluginApiReturn<number>
   /**
    * Linearly interpolate between two vectors: `a + (b - a) * t`.
    *
@@ -129,7 +129,7 @@ export abstract class PluginVec3Api {
    * const midpoint = await snaptrude.core.math.vec3.lerp(a, b, 0.5)
    * ```
    */
-  abstract lerp(a: Vec3Handle, b: Vec3Handle, t: number): PluginApiReturn<Vec3Handle>
+  abstract lerp(a: Vec3Input, b: Vec3Input, t: number): PluginApiReturn<Vec3Handle>
   /**
    * Negate a vector, reversing its direction.
    *
@@ -139,7 +139,7 @@ export abstract class PluginVec3Api {
    * const reversed = await snaptrude.core.math.vec3.negate(v) // (-1, 2, -3)
    * ```
    */
-  abstract negate(v: Vec3Handle): PluginApiReturn<Vec3Handle>
+  abstract negate(v: Vec3Input): PluginApiReturn<Vec3Handle>
   /**
    * Test whether two vectors have exactly equal components.
    *
@@ -150,7 +150,7 @@ export abstract class PluginVec3Api {
    * const same = await snaptrude.core.math.vec3.equals(a, b) // true
    * ```
    */
-  abstract equals(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<boolean>
+  abstract equals(a: Vec3Input, b: Vec3Input): PluginApiReturn<boolean>
   /**
    * Test whether two vectors are equal within a tolerance `epsilon` (default `1e-6`).
    *
@@ -162,8 +162,8 @@ export abstract class PluginVec3Api {
    * ```
    */
   abstract equalsApprox(
-    a: Vec3Handle,
-    b: Vec3Handle,
+    a: Vec3Input,
+    b: Vec3Input,
     epsilon?: number,
   ): PluginApiReturn<boolean>
   /**
@@ -175,5 +175,5 @@ export abstract class PluginVec3Api {
    * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
    * ```
    */
-  abstract components(v: Vec3Handle): PluginApiReturn<Vec3Components>
+  abstract components(v: Vec3Input): PluginApiReturn<Vec3Components>
 }

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

@@ -101,6 +101,11 @@ export abstract class PluginCoreStoreysApi {
    * The new storey is inserted at the position specified by `storyValue`. This
    * operation is undoable.
    *
+   * Storeys are added at the ends of the stack only. A value above the top (or below the
+   * bottom) also creates every storey in between at the default height — `create(5)` on a
+   * stack of 1–2 adds 3, 4 and 5 and returns only 5 — and a value inside a gap of the
+   * stack is refused (PRECONDITION_FAILED). Read the stack back with `list` afterwards.
+   *
    * @param storyValue - Integer storey number
    *   to create (e.g. `3` to add a third floor)
    * @param height - Optional height in Babylon

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { ComponentHandle, Vec3Handle, Vec3Input } from "../../../handles"
 import { BooleanOutcome } from "../shared"
 
 /**
@@ -132,7 +132,7 @@ export abstract class PluginDesignBooleanApi {
  * | `offset` | {@linkcode Vec3Handle} | Translation added to the created result mass(es) (default: none) |
  */
 export const BooleanOptions = z.object({
-  offset: Vec3Handle.optional(),
+  offset: Vec3Input.optional(),
 })
 export type BooleanOptions = z.infer<typeof BooleanOptions>
 

package/src/api/design/create/bulk-items.ts

@@ -4,6 +4,7 @@ import {
   ContourHandle,
   ProfileHandle,
   Vec3Handle,
+  Vec3Input,
 } from "../../../handles"
 import { PluginOpeningBaseOptions } from "./opening-fields"
 import { PluginWallType } from "../types"
@@ -37,6 +38,10 @@ export type PluginWallTopProfilePoint = z.infer<
 >
 
 /**
+ * Current hosts refuse a non-null top profile (`PRECONDITION_FAILED`, "Walls have one
+ * height: sloped or stepped tops are not supported") and create nothing; the shape is
+ * kept for compatibility. The description below is the original contract.
+ *
  * The top edge of ONE wall as a polyline over its centerline: at least two
  * points, `along` strictly increasing from `0` (curve start) to `1` (curve end),
  * straight segments between them. Two points give a single slope (a raked
@@ -135,7 +140,7 @@ export type PluginCreateWallRunItems = z.infer<typeof PluginCreateWallRunItems>
 export const PluginCreateFloorItem = z.object({
   contour: ContourHandle,
   thickness: z.number(),
-  position: Vec3Handle.optional(),
+  position: Vec3Input.optional(),
 })
 export type PluginCreateFloorItem = z.infer<typeof PluginCreateFloorItem>
 
@@ -156,6 +161,9 @@ export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
  * Values are evaluated before cutting. Numeric lengths use SU; unit strings
  * are accepted in values. `facing` selects local +Z; `hinge` sets the declared
  * hand enum (left = local -X, right = +X). Both are world points.
+ * A door between a room and a corridor, lobby or hall swings into the room:
+ * pass `facing` inside the room it serves, never in the corridor. Toilets,
+ * cupboards, shafts and exits on an escape route open outward instead.
  *
  * | Property | Type | Description |
  * |---|---|---|
@@ -164,7 +172,7 @@ export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
  * | `values` | `Record<string, number \| string>`? | Authored parameter overrides |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
- * | `facing` | {@linkcode Vec3Handle}? | World point on the side the door swings open to (default engine-chosen) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side the door swings open to: inside the room it serves (default engine-chosen) |
  * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  * | `label` | `string`? | Instance name (optional) |
  * | `width` | `number`? | Declared width parameter (SU, > 0), not evaluated hole width |
@@ -245,7 +253,7 @@ export type PluginCreateWindowItems = z.infer<typeof PluginCreateWindowItems>
  */
 export const PluginCreateFurnitureItem = z.object({
   catalogId: z.string().min(1),
-  position: Vec3Handle,
+  position: Vec3Input,
   label: z.string().optional(),
   angleInDegrees: z.number().optional(),
 })