@snaptrude/plugin-core 1.0.3 → 1.0.4

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

@@ -8,6 +8,7 @@ import {
   CurveHandle,
   ProfileHandle,
   Vec3Handle,
+  Vec3Input,
 } from "../../../handles"
 import { PluginGridStyleOptions } from "./grids"
 import { PluginGraphicsLineStyleId } from "../../presentation/graphics"
@@ -130,7 +131,7 @@ export abstract class PluginDesignCreateApi {
     contour: ContourHandle,
     height: number,
     label?: string,
-    position?: Vec3Handle,
+    position?: Vec3Input,
     spaceType?: PluginSpaceType,
     massType?: PluginMassType,
     departmentId?: PluginDepartmentId,
@@ -165,7 +166,7 @@ export abstract class PluginDesignCreateApi {
     contour: ContourHandle,
     height: number,
     label?: string,
-    position?: Vec3Handle,
+    position?: Vec3Input,
     massType?: PluginMassType,
   ): PluginApiReturn<ComponentHandle>
 
@@ -288,7 +289,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract floor(
     ...args:
-      | [contour: ContourHandle, thickness: number, position?: Vec3Handle]
+      | [contour: ContourHandle, thickness: number, position?: Vec3Input]
       | [contour: ContourHandle, options: PluginFamilyFloorOptions]
   ): PluginApiReturn<ComponentHandle[]>
 
@@ -422,10 +423,10 @@ export abstract class PluginDesignCreateApi {
   public abstract column(
     ...args:
       | [
-          position: Vec3Handle,
+          position: Vec3Input,
           crossSection: ContourHandle,
           height: number,
-          directionUp?: Vec3Handle,
+          directionUp?: Vec3Input,
         ]
       | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
@@ -472,7 +473,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract beam(
     ...args:
-      | [section: ContourHandle, length: number, direction?: Vec3Handle]
+      | [section: ContourHandle, length: number, direction?: Vec3Input]
       | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
@@ -496,10 +497,10 @@ export abstract class PluginDesignCreateApi {
    *   single undo entry. The storey must already exist
    *   (`core.storeys.create` first). Default: geometry-derived — a profile
    *   drawn at y = 0 lands on storey 1; the ACTIVE storey is NOT consulted.
-   * @param topProfiles - Optional top edge per curve of `profile` (same order):
-   *   a {@linkcode PluginWallTopProfile} makes that wall raked / gabled; `null`
-   *   or a missing entry keeps it flat at `height`. Straight curves only. Such
-   *   walls are non-parametric (see {@linkcode PluginWallTopProfile}).
+   * @param topProfiles - Top edge per curve of `profile` (same order). Current
+   *   hosts build walls with one height: any non-null entry is refused with
+   *   `PRECONDITION_FAILED` ("sloped or stepped tops are not supported") and
+   *   nothing is created. Pass `null` entries or omit it.
    * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
    * @throws if the profile is empty, `wallType` names no wall type in the
    *   project, `storey` does not exist, `topProfiles` has more entries than the
@@ -513,9 +514,6 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Add walls with mitred corners along the path
    * @examplePrompt Draw brick walls with plaster along this outline
    * @examplePrompt Build the perimeter in exposed concrete walls
-   * @examplePrompt Create a raked wall that slopes from 3m to 5m
-   * @examplePrompt Build a gable end wall with the ridge in the middle
-   * @examplePrompt Draw a wall with a sloped top edge
    *
    * # Example
    * ```ts
@@ -531,13 +529,6 @@ export abstract class PluginDesignCreateApi {
    * const brickWalls = await snaptrude.design.create.walls(
    *   centerlines, 3, undefined, brick.label,
    * )
-   * // …a raked wall (3m at the start, 5m at the end) on a single centerline:
-   * const run = await snaptrude.core.geom.create.profileFromCurves([
-   *   await snaptrude.core.geom.create.line(await v.new(0, 0, 10), await v.new(8, 0, 10)),
-   * ])
-   * const [raked] = await snaptrude.design.create.walls(run, undefined, 0.2, undefined, undefined, [
-   *   [{ along: 0, height: 3 }, { along: 1, height: 5 }],
-   * ])
    * ```
    *
    * @performance For MORE THAN ONE run, call `design.create.wallRuns(items[])` — one
@@ -560,8 +551,9 @@ export abstract class PluginDesignCreateApi {
    * item's profile chain, mitred at shared endpoints. Junctions resolve within a
    * run, not between runs. Each item carries its own
    * dimensions, `wallType` and `storey`, so a single call can build a whole
-   * floor plate or several storeys at once. Per-curve `topProfiles` make raked
-   * or gabled walls (see {@linkcode PluginWallTopProfile}). Validate-all-or-throw;
+   * floor plate or several storeys at once. Walls have one height: a non-null
+   * `topProfiles` entry is refused with `PRECONDITION_FAILED` (`details.itemIndex`
+   * names the item) and nothing is created. Validate-all-or-throw;
    * one command.
    *
    * @param items - One {@linkcode PluginCreateWallRunItem} per run to create
@@ -582,7 +574,6 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Bulk create wall runs from these centerlines
    * @examplePrompt Create the walls for both storeys in a single undo step
    * @examplePrompt Turn these polylines into 200mm brick walls together
-   * @examplePrompt Import these raked walls with their top profiles in one go
    *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
    *   entry. Always prefer this over calling `design.create.walls` in a loop: build the
@@ -603,9 +594,6 @@ export abstract class PluginDesignCreateApi {
    * const [groundWalls, upperWalls] = await snaptrude.design.create.wallRuns([
    *   { profile: ground, height: 3, thickness: 0.2 },
    *   { profile: upper, height: 3, storey: 2 },
-   *   // one gable wall: 3m at both ends, 5m ridge in the middle
-   *   { profile: upper, thickness: 0.2, storey: 3,
-   *     topProfiles: [[{ along: 0, height: 3 }, { along: 0.5, height: 5 }, { along: 1, height: 3 }]] },
    * ])
    * console.log(groundWalls.length, "walls on the ground floor")
    * ```
@@ -649,7 +637,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract staircase(
     preset: PluginStaircasePreset,
-    position: Vec3Handle,
+    position: Vec3Input,
     label?: string,
     structureId?: string,
     level?: string,
@@ -740,7 +728,7 @@ export abstract class PluginDesignCreateApi {
     spacingY: number,
     options?: {
       angle?: number
-      center?: Vec3Handle
+      center?: Vec3Input
     } & PluginGridStyleOptions,
   ): PluginApiReturn<ComponentHandle>
 
@@ -895,7 +883,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract furniture(
     catalogId: string,
-    position: Vec3Handle,
+    position: Vec3Input,
     options?: { label?: string; createNewSourceMesh?: boolean },
     angleInDegrees?: number,
   ): PluginApiReturn<ComponentHandle>
@@ -1008,14 +996,14 @@ export abstract class PluginDesignCreateApi {
   public abstract door(
     familyId: string,
     hostWall: ComponentHandle,
-    position: Vec3Handle,
+    position: Vec3Input,
     options?: {
       label?: string
-      hinge?: Vec3Handle
+      hinge?: Vec3Input
       version?: number
       values?: Record<string, number | string>
     },
-    facing?: Vec3Handle,
+    facing?: Vec3Input,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -1118,14 +1106,14 @@ export abstract class PluginDesignCreateApi {
   public abstract window(
     familyId: string,
     hostWall: ComponentHandle,
-    position: Vec3Handle,
+    position: Vec3Input,
     options?: {
       label?: string
-      hinge?: Vec3Handle
+      hinge?: Vec3Input
       version?: number
       values?: Record<string, number | string>
     },
-    facing?: Vec3Handle,
+    facing?: Vec3Input,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -1458,7 +1446,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract copy(
     components: ComponentHandle[],
-    displacement: Vec3Handle,
+    displacement: Vec3Input,
     options?: { count?: number; mode?: PluginCopyMode },
   ): PluginApiReturn<ComponentHandle[]>
 
@@ -1681,7 +1669,7 @@ export const PluginDesignCreateSpaceArgs = z.object({
   contour: ContourHandle,
   height: z.number(),
   label: z.string().optional(),
-  position: Vec3Handle.optional(),
+  position: Vec3Input.optional(),
   spaceType: PluginSpaceType.optional(),
   massType: PluginMassType.optional(),
   departmentId: PluginDepartmentId.optional(),
@@ -1712,7 +1700,7 @@ export const PluginDesignCreateMassArgs = z.object({
   contour: ContourHandle,
   height: z.number(),
   label: z.string().optional(),
-  position: Vec3Handle.optional(),
+  position: Vec3Input.optional(),
   massType: PluginMassType.optional(),
 })
 export type PluginDesignCreateMassArgs = z.infer<
@@ -1779,7 +1767,7 @@ export type PluginDesignCreateSlabArgs = z.infer<
 export const PluginDesignCreateFloorArgs = z.object({
   contour: ContourHandle,
   thickness: z.number(),
-  position: Vec3Handle.optional(),
+  position: Vec3Input.optional(),
 })
 export type PluginDesignCreateFloorArgs = z.infer<
   typeof PluginDesignCreateFloorArgs
@@ -1842,10 +1830,10 @@ export type PluginDesignCreateCeilingArgs = z.infer<
  * | `directionUp` | {@linkcode Vec3Handle}? | Up axis (default world up) |
  */
 export const PluginDesignCreateColumnArgs = z.object({
-  position: Vec3Handle,
+  position: Vec3Input,
   crossSection: ContourHandle,
   height: z.number(),
-  directionUp: Vec3Handle.optional(),
+  directionUp: Vec3Input.optional(),
 })
 export type PluginDesignCreateColumnArgs = z.infer<
   typeof PluginDesignCreateColumnArgs
@@ -1867,7 +1855,7 @@ export type PluginDesignCreateColumnArgs = z.infer<
 export const PluginDesignCreateBeamArgs = z.object({
   section: ContourHandle,
   length: z.number(),
-  direction: Vec3Handle.optional(),
+  direction: Vec3Input.optional(),
 })
 export type PluginDesignCreateBeamArgs = z.infer<
   typeof PluginDesignCreateBeamArgs
@@ -1922,7 +1910,7 @@ export type PluginDesignCreateWallsArgs = z.infer<
  */
 export const PluginDesignCreateStaircaseArgs = z.object({
   preset: PluginStaircasePreset,
-  position: Vec3Handle,
+  position: Vec3Input,
   label: z.string().optional(),
   structureId: z.string().optional(),
   level: z.string().optional(),
@@ -1949,7 +1937,7 @@ export type PluginDesignCreateStaircaseArgs = z.infer<
  */
 export const PluginDesignCreateFurnitureArgs = z.object({
   catalogId: z.string().min(1),
-  position: Vec3Handle,
+  position: Vec3Input,
   label: z.string().optional(),
   createNewSourceMesh: z.boolean().optional(),
   angleInDegrees: z.number().optional(),
@@ -2207,7 +2195,7 @@ export type PluginCopyMode = z.infer<typeof PluginCopyMode>
  */
 export const PluginDesignCreateCopyArgs = z.object({
   components: z.array(ComponentHandle).min(1),
-  displacement: Vec3Handle,
+  displacement: Vec3Input,
   count: z.number().int().positive().optional(),
   mode: PluginCopyMode.optional(),
 })
@@ -2240,7 +2228,7 @@ export const PluginCreateSpaceItem = z.object({
   contour: ContourHandle,
   height: z.number(),
   label: z.string().optional(),
-  position: Vec3Handle.optional(),
+  position: Vec3Input.optional(),
   spaceType: PluginSpaceType.optional(),
   massType: PluginMassType.optional(),
   departmentId: PluginDepartmentId.optional(),

package/src/api/design/create/opening-fields.ts

@@ -1,5 +1,5 @@
 import * as z from "zod"
-import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { ComponentHandle, Vec3Input } from "../../../handles"
 
 /**
  * The shared field bag every hosted opening (door / window) carries — used by
@@ -17,9 +17,9 @@ import { ComponentHandle, Vec3Handle } from "../../../handles"
  * | `version` | `number`? | Exact family version; newest known by default |
  * | `values` | `Record<string, number \| string>`? | Authored instance parameters; numeric lengths use Snaptrude units |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the opening |
- * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
- * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the opening swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires the recipe's hand parameter |
+ * | `position` | {@linkcode Vec3Input} | World point projected onto the wall (a vec3 handle or a plain `{ x, y, z }`) |
+ * | `facing` | {@linkcode Vec3Input}? | World point on the side of the wall the opening swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Input}? | World point near the hinged jamb; requires the recipe's hand parameter |
  * | `label` | `string`? | Instance name (optional) |
  * | `width` | `number`? | Sets the declared width parameter, not the opening's evaluated envelope |
  * | `height` | `number`? | Sets the declared height parameter |
@@ -31,9 +31,9 @@ export const PluginOpeningBaseOptions = {
     .record(z.string(), z.union([z.number().finite(), z.string()]))
     .optional(),
   hostWall: ComponentHandle,
-  position: Vec3Handle,
-  facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
+  position: Vec3Input,
+  facing: Vec3Input.optional(),
+  hinge: Vec3Input.optional(),
   label: z.string().optional(),
   width: z.number().finite().positive().optional(),
   height: z.number().finite().positive().optional(),

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

@@ -8,7 +8,7 @@ import { PluginDesignChangeResult } from "../lock"
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | Entities to delete. Unknown/forged handles reject the whole call (fail-fast). |
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to delete. Handles that no longer resolve are skipped and returned as `missing`; the call rejects only when none resolve. |
  *
  * `.min(1)` is deliberately stricter than the shipped `PluginDesignLockArgs`
  * (which allows an empty array) — an empty delete is a caller error, not a no-op.
@@ -43,12 +43,19 @@ export abstract class PluginDesignDeleteApi {
    * entry, exactly as the editor's Delete key does — see `design.dimensions`. They are
    * NOT listed in `affected`, which reports component handles only.
    *
-   * @param components - Entities to delete. Unknown/forged handles reject the whole call (fail-fast).
-   * @returns The entities that were deleted, as {@linkcode ComponentHandle}`[]`
-   *   (echoed host-side from the resolved+deleted set — the engine returns no ids).
-   *   Deleted handles are **stale** afterwards: re-resolving one throws `HANDLE_INVALID`.
-   * @throws If any supplied handle is unknown/forged (`HANDLE_INVALID`) — the whole
-   *   call rejects before anything is deleted (all-or-nothing resolution).
+   * @param components - Entities to delete. A handle that no longer resolves (already
+   *   removed by an earlier edit — a door deleted with its wall, a wall replaced by an
+   *   opening's re-cut) is skipped, not fatal.
+   * @returns `{ affected, cascaded?, missing?, rejected? }`: the entities you asked to delete
+   *   (echoed host-side — the engine returns no ids); `cascaded`, the derived walls/floors/slabs
+   *   the parametric graph removed with a deleted space; `missing`, handles that no longer
+   *   resolved and were skipped; `rejected`, handles the engine accepted but left standing
+   *   (delete them again, one at a time, or report them). Deleted handles are **stale**
+   *   afterwards: re-resolving one throws `HANDLE_STALE`.
+   * @throws `HANDLE_INVALID` when NONE of the supplied handles resolve (nothing is deleted);
+   *   hosts before Oct 2026 reject the whole call when any handle is gone. `OPERATION_FAILED`
+   *   when the parametric engine rejects the deletion — the batch is rolled back.
+   *   `HANDLE_STALE` for a handle the caller held that has since been retired.
    *
    * @examplePrompt Delete the selected objects
    * @examplePrompt Remove these walls from the model

package/src/api/design/dimensions.ts

@@ -5,6 +5,7 @@ import {
   DimensionHandle,
   Vec3Components,
   Vec3Handle,
+  Vec3Input,
 } from "../../handles"
 
 /**
@@ -94,8 +95,8 @@ export abstract class PluginDesignDimensionsApi {
    * ```
    */
   public abstract create(
-    from: Vec3Handle,
-    to: Vec3Handle,
+    from: Vec3Input,
+    to: Vec3Input,
     anchor: ComponentHandle,
     options?: { anchorTo?: ComponentHandle; offset?: number },
   ): PluginApiReturn<DimensionHandle>
@@ -362,8 +363,8 @@ export type PluginDimensionsChangeResult = z.infer<
  * TRANSPORT: positional args — validated host-side as this object.
  */
 export const PluginDesignDimensionsCreateArgs = z.object({
-  from: Vec3Handle,
-  to: Vec3Handle,
+  from: Vec3Input,
+  to: Vec3Input,
   anchor: ComponentHandle,
   anchorTo: ComponentHandle.optional(),
   offset: z.number().finite().optional(),

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { ComponentHandle, Vec3Input } from "../../../handles"
 import { OffsetSplitOutcome } from "../shared"
 
 /**
@@ -41,7 +41,7 @@ export abstract class PluginDesignEditApi {
   public abstract offsetSplit(
     component: ComponentHandle,
     offsetDistance: number,
-    options?: { profilePickPoint?: Vec3Handle },
+    options?: { profilePickPoint?: Vec3Input },
   ): PluginApiReturn<OffsetSplitOutcome>
 }
 
@@ -49,6 +49,6 @@ export abstract class PluginDesignEditApi {
 export const PluginDesignOffsetSplitArgs = z.object({
   component: ComponentHandle,
   offsetDistance: z.number(),
-  profilePickPoint: Vec3Handle.optional(),
+  profilePickPoint: Vec3Input.optional(),
 })
 export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>

package/src/api/design/family.ts

@@ -5,6 +5,7 @@ import {
   ComponentHandle,
   Vec3Components,
   Vec3Handle,
+  Vec3Input,
 } from "../../handles"
 import { NetworkFamilyContract } from "./networks"
 
@@ -1319,7 +1320,7 @@ export type PluginDesignFamilyDeleteArgs = z.infer<
 export const PluginDesignFamilyPlaceArgs = z.object({
   id: z.string().optional(),
   version: z.number().int().positive().optional(),
-  position: z.union([Vec3Handle, Vec3Components]).optional(),
+  position: z.union([Vec3Input, Vec3Components]).optional(),
   rotation: z.number().optional(),
   values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
   storey: z.number().int().optional(),

package/src/api/design/lock.ts

@@ -9,6 +9,12 @@ import { ComponentHandle } from "../../handles"
  */
 export const PluginDesignChangeResult = z.object({
   affected: z.array(ComponentHandle),
+  /** Derived BIM (walls/floors/slabs) the parametric engine removed with its host. Delete only. */
+  cascaded: z.array(ComponentHandle).optional(),
+  /** Handles that no longer resolved when the call ran and were skipped. Delete only. */
+  missing: z.array(ComponentHandle).optional(),
+  /** Handles the engine accepted but left standing; delete them again or report them. Delete only. */
+  rejected: z.array(ComponentHandle).optional(),
 })
 export type PluginDesignChangeResult = z.infer<typeof PluginDesignChangeResult>
 

package/src/api/design/transform/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 { PluginDesignChangeResult } from "../lock"
 
 /**
@@ -22,9 +22,17 @@ 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}
+   * @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 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
@@ -43,7 +51,7 @@ export abstract class PluginDesignTransformApi {
    */
   public abstract move(
     components: ComponentHandle[],
-    displacement: Vec3Handle,
+    displacement: Vec3Input,
     options?: { is2D?: boolean; trackParentChange?: boolean },
   ): PluginApiReturn<PluginDesignChangeResult>
 
@@ -81,7 +89,7 @@ export abstract class PluginDesignTransformApi {
   public abstract rotate(
     components: ComponentHandle[],
     angleInDegrees: number,
-    options?: { axis?: Vec3Handle; pivot?: Vec3Handle; is2D?: boolean },
+    options?: { axis?: Vec3Input; pivot?: Vec3Input; is2D?: boolean },
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -205,7 +213,7 @@ export type PluginAlignEdge = z.infer<typeof PluginAlignEdge>
  */
 export const PluginDesignMoveArgs = z.object({
   components: z.array(ComponentHandle).min(1),
-  displacement: Vec3Handle,
+  displacement: Vec3Input,
   is2D: z.boolean().optional(),
   trackParentChange: z.boolean().optional(),
 })
@@ -217,9 +225,9 @@ export type PluginDesignMoveArgs = z.infer<typeof PluginDesignMoveArgs>
 export const PluginDesignRotateArgs = z.object({
   components: z.array(ComponentHandle).min(1),
   angleInDegrees: z.number(),
-  axis: Vec3Handle.optional(),
+  axis: Vec3Input.optional(),
   is2D: z.boolean().optional(),
-  pivot: Vec3Handle.optional(),
+  pivot: Vec3Input.optional(),
 })
 export type PluginDesignRotateArgs = z.infer<typeof PluginDesignRotateArgs>
 

package/src/api/entity/space.ts

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

package/src/api/entity/story.ts

@@ -88,6 +88,10 @@ 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,8 +522,13 @@ export type PluginPresentationViewsCreateArgs = z.infer<
   typeof PluginPresentationViewsCreateArgs
 >
 
-/** Result of {@linkcode PluginPresentationViewsApi.create} — the saved view. */
-export const PluginPresentationViewsCreateResult = PluginPresentationView
+/**
+ * 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(),
+})
 export type PluginPresentationViewsCreateResult = z.infer<
   typeof PluginPresentationViewsCreateResult
 >

package/src/handles.ts

@@ -288,6 +288,17 @@ 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

@@ -0,0 +1,36 @@
+// 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')
+  }
+})