@snaptrude/plugin-core 1.0.2-plainpoint-20261102.2 → 1.0.3

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Handle, Vec3Input } from "../../../handles"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 
 /**
@@ -22,17 +22,9 @@ export abstract class PluginDesignTransformApi {
    * component's absolute position as the anchor). Undoable.
    *
    * @param components - Entities to move
-   * @param displacement - Relative translation as a {@linkcode Vec3Handle}. A displacement
-   *   shorter than 1e-6 is a no-op that succeeds (hosts before Oct 2026 throw
-   *   `OPERATION_FAILED` "No movement occurred" instead, so skip the call when nothing moves).
+   * @param displacement - Relative translation as a {@linkcode Vec3Handle}
    * @param options - `is2D`, `trackParentChange`
    * @returns {@linkcode PluginDesignChangeResult}
-   * @throws `OPERATION_FAILED` when the engine drops the whole move. A single connected
-   *   parametric wall moves only across its own line: the vertical part and the part along
-   *   the line are dropped. Move the whole connected run in one call to lift walls; to slide
-   *   or lengthen one wall, delete it and create it again on the new line. Graph-bound walls
-   *   made by Sketch-to-BIM refuse `move` outright (`TOPOLOGY_ERROR` / `ZERO_MOVEMENT`):
-   *   adjust the room boundary that owns the wall instead.
    *
    * @examplePrompt Move the selected room 5 metres to the right
    * @examplePrompt Shift these walls 3m along the x axis
@@ -51,7 +43,7 @@ export abstract class PluginDesignTransformApi {
    */
   public abstract move(
     components: ComponentHandle[],
-    displacement: Vec3Input,
+    displacement: Vec3Handle,
     options?: { is2D?: boolean; trackParentChange?: boolean },
   ): PluginApiReturn<PluginDesignChangeResult>
 
@@ -89,7 +81,7 @@ export abstract class PluginDesignTransformApi {
   public abstract rotate(
     components: ComponentHandle[],
     angleInDegrees: number,
-    options?: { axis?: Vec3Input; pivot?: Vec3Input; is2D?: boolean },
+    options?: { axis?: Vec3Handle; pivot?: Vec3Handle; is2D?: boolean },
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -213,7 +205,7 @@ export type PluginAlignEdge = z.infer<typeof PluginAlignEdge>
  */
 export const PluginDesignMoveArgs = z.object({
   components: z.array(ComponentHandle).min(1),
-  displacement: Vec3Input,
+  displacement: Vec3Handle,
   is2D: z.boolean().optional(),
   trackParentChange: z.boolean().optional(),
 })
@@ -225,9 +217,9 @@ export type PluginDesignMoveArgs = z.infer<typeof PluginDesignMoveArgs>
 export const PluginDesignRotateArgs = z.object({
   components: z.array(ComponentHandle).min(1),
   angleInDegrees: z.number(),
-  axis: Vec3Input.optional(),
+  axis: Vec3Handle.optional(),
   is2D: z.boolean().optional(),
-  pivot: Vec3Input.optional(),
+  pivot: Vec3Handle.optional(),
 })
 export type PluginDesignRotateArgs = z.infer<typeof PluginDesignRotateArgs>
 

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

@@ -3,6 +3,10 @@ import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
+import type {
+  PluginOpeningPlacementArgs,
+  PluginOpeningPlacementResult,
+} from "../opening-placement"
 
 /**
  * `snaptrude.design.windows` — window-specific reads. Creation lives at
@@ -22,6 +26,31 @@ import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
 export abstract class PluginDesignWindowsApi {
   constructor() {}
 
+  /**
+   * Trial the native host fit and geometry rebuild, then restore the model without publishing commands.
+   * The first result uses the creation options; subsequent results use candidateWidths in input order.
+   * Widths are authored parameters, not physical envelopes or a guaranteed maximum width.
+   * No catalog save, history entry or model persistence occurs. Rerun after model edits.
+   * A failed fit leaves cut unverified. Family-host cuts are also unverified: their rebuild
+   * cannot supply a reversible, authoritative trial result. Material clearance checks evaluated
+   * parts against physical neighbours across hosts. The intended host uses native fit/cut checks.
+   * Creation repeats clearance immediately before placement; this report grants no later approval.
+   * Editing permission is required; locked hosts and an active opening tool reject.
+   * A requested width/height on a family sized by its Type (Custom Sizes off) picks the Type
+   * within 25 mm, else turns Custom Sizes on; each result's `sizing` says which. Creation
+   * (`design.create.window(s)`) applies the same rule, so the size you pass is the size built.
+   * @param options Window creation options and up to 12 alternative widths; numeric lengths use SU.
+   * @returns Separate fit/cut/clearance evidence, evaluated bounds and explicit limitations.
+   * @examplePrompt Check whether this window fits and its host can be cut
+   * @example
+   * const result = await snaptrude.design.windows.checkPlacement({
+   *   familyId, version, hostWall, position, width: 4, sillHeight: 3,
+   * })
+   */
+  public abstract checkPlacement(
+    options: PluginOpeningPlacementArgs,
+  ): PluginApiReturn<PluginOpeningPlacementResult>
+
   /**
    * Get the type name of a window — the label that identifies which kind of
    * window the instance is, as shown in its properties.

package/src/api/entity/space.ts

@@ -6,7 +6,6 @@ import * as z from "zod"
 import {
   ProfileHandle,
   Vec3Handle,
-  Vec3Input,
   Vec3Components,
   QuatComponents,
   CurveHandle,
@@ -22,7 +21,7 @@ import {
  * | `dimensions` | `{ width, height, depth }` | Box dimensions in Babylon units |
  */
 export const PluginSpaceCreateRectangularArgs = z.object({
-  position: Vec3Input,
+  position: Vec3Handle,
   dimensions: z.object({
     width: z.number(),
     height: z.number(),
@@ -63,7 +62,7 @@ export const PluginSpaceCreateFromProfileArgs = z.object({
   profile: ProfileHandle,
   innerProfiles: z.array(ProfileHandle).optional(),
   extrudeHeight: z.number(),
-  position: Vec3Input,
+  position: Vec3Handle,
 })
 
 export type PluginSpaceCreateFromProfileArgs = z.infer<
@@ -467,7 +466,7 @@ export type PluginSpaceUpdateResult = z.infer<typeof PluginSpaceUpdateResult>
 export const PluginSpaceBulkCreateItem = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("rectangular"),
-    position: Vec3Input,
+    position: Vec3Handle,
     dimensions: z.object({
       width: z.number(),
       height: z.number(),
@@ -483,7 +482,7 @@ export const PluginSpaceBulkCreateItem = z.discriminatedUnion("kind", [
     profile: ProfileHandle,
     innerProfiles: z.array(ProfileHandle).optional(),
     extrudeHeight: z.number(),
-    position: Vec3Input,
+    position: Vec3Handle,
     room_type: z.string().optional(),
     spaceType: PluginSpaceType.optional(),
     massType: PluginMassType.optional(),

package/src/api/entity/story.ts

@@ -88,10 +88,6 @@ export abstract class PluginStoryApi {
    * @returns A {@linkcode PluginStoryCreateResult} with `storyId` and `storyValue`
    * @throws If a story with the given value already exists or creation fails
    *
-   * Storeys are added at the ends of the stack only: a value above the top also creates
-   * every storey in between (returning only the requested one), and a value inside a gap
-   * is refused.
-   *
    * @examplePrompt Add a third floor to the building
    * @examplePrompt Create a new storey above the second floor
    * @examplePrompt Add a basement level to this project

package/src/api/presentation/views.ts

@@ -522,13 +522,8 @@ export type PluginPresentationViewsCreateArgs = z.infer<
   typeof PluginPresentationViewsCreateArgs
 >
 
-/**
- * Result of {@linkcode PluginPresentationViewsApi.create} — the saved view, plus `framed`:
- * whether the view was framed on the given elements or bounds (always `false` without `frame`).
- */
-export const PluginPresentationViewsCreateResult = PluginPresentationView.extend({
-  framed: z.boolean().optional(),
-})
+/** Result of {@linkcode PluginPresentationViewsApi.create} — the saved view. */
+export const PluginPresentationViewsCreateResult = PluginPresentationView
 export type PluginPresentationViewsCreateResult = z.infer<
   typeof PluginPresentationViewsCreateResult
 >

package/src/handles.ts

@@ -288,17 +288,6 @@ export const EdgeHandle = handleSchema("edge")
 export const HalfEdgeHandle = handleSchema("halfedge")
 export const VertexHandle = handleSchema("vertex")
 export const Vec3Components = z.object({ x: z.number(), y: z.number(), z: z.number() })
-/**
- * A vec3 ARGUMENT: a {@linkcode Vec3Handle} in any inbound form, or a plain finite
- * `{ x, y, z }` point. Geometry reads return plain points, and callers pass them straight
- * back where a vec3 is expected; the host resolves the point as a vector. Returns stay
- * {@linkcode Vec3Handle}. Explicitly typed to keep handles.d.ts inside its size budget.
- */
-export type Vec3Input = Handle<"vec3"> | Vec3Components
-export const Vec3Input: z.ZodUnion<readonly [typeof Vec3Handle, typeof Vec3Components]> = z.union(
-  [Vec3Handle, Vec3Components],
-  { error: 'expected a "vec3" handle or a plain { x, y, z } point' }
-)
 export const QuatComponents = z.object({
   x: z.number(),
   y: z.number(),

package/test/handles.test.mjs

@@ -1,36 +0,0 @@
-// Node built-in test runner suite for the handle schemas.
-// Imports the BUILT package (dist) — run `pnpm build` first.
-import test from "node:test"
-import assert from "node:assert/strict"
-import { Vec3Handle, Vec3Input, Handle, PluginDesignMoveArgs } from "../dist/index.js"
-
-test("a vec3 handle parses in every inbound form, and only as a handle", () => {
-  for (const v of ["vec3_abc", new Handle("vec3_abc"), { __h: "vec3_abc" }, { id: "vec3_abc" }]) {
-    const out = Vec3Handle.parse(v)
-    assert.ok(out instanceof Handle)
-    assert.equal(out.id, "vec3_abc")
-  }
-  assert.equal(Vec3Handle.safeParse({ x: 1, y: 2, z: 3 }).success, false)
-  const bad = Vec3Handle.safeParse("profile_1")
-  assert.equal(bad.success, false)
-  assert.match(bad.error.issues[0].message, /expected a "vec3" handle/)
-})
-
-test("Vec3Input takes a handle or a plain { x, y, z } point", () => {
-  // Geometry reads return plain points; agents pass them back where a vec3 belongs.
-  const point = { x: 1, y: 2.5, z: -3 }
-  assert.deepEqual(Vec3Input.parse(point), point)
-  assert.ok(Vec3Input.parse("vec3_abc") instanceof Handle)
-  const args = PluginDesignMoveArgs.parse({ components: ["wl_1"], displacement: { x: 0, y: 0, z: 10 } })
-  assert.deepEqual(args.displacement, { x: 0, y: 0, z: 10 })
-  const handled = PluginDesignMoveArgs.parse({ components: ["wl_1"], displacement: "vec3_d" })
-  assert.equal(handled.displacement.id, "vec3_d")
-})
-
-test("Vec3Input still rejects non-points and wrong handles, with one message", () => {
-  for (const v of [{ x: 1, y: 2 }, { x: 1, y: Number.NaN, z: 3 }, { x: "1", y: 2, z: 3 }, "profile_1", null, 42]) {
-    const r = Vec3Input.safeParse(v)
-    assert.equal(r.success, false, JSON.stringify(v))
-    assert.equal(r.error.issues[0].message, 'expected a "vec3" handle or a plain { x, y, z } point')
-  }
-})