@snaptrude/plugin-core 1.1.0-pbr-20261102.2 → 1.1.0

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

@@ -4,6 +4,10 @@ import { ComponentHandle, MaterialHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
 import { PluginMaterialSpec } from "../materials"
+import type {
+  PluginOpeningPlacementArgs,
+  PluginOpeningPlacementResult,
+} from "../opening-placement"
 
 /**
  * `snaptrude.design.windows` — window-specific reads. Creation lives at
@@ -50,6 +54,31 @@ export abstract class PluginDesignWindowsApi {
     material: MaterialHandle | PluginMaterialSpec,
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /**
+   * 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,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/lighting.ts

@@ -22,7 +22,8 @@ import { BBoxComponents, Vec3Components, Vec3Handle } from "../../handles"
  *
  * Realistic rendering is rolling out behind a feature flag and can be suspended
  * in a browser whose GPU it lost. `get().realisticAvailable` says whether
- * {@linkcode PluginPresentationLightingApi.enableRealistic} can succeed. The sky,
+ * {@linkcode PluginPresentationLightingApi.enableRealistic} can succeed, and
+ * `get().realisticUnavailableReason` says why not. The sky,
  * the cloud shapes and the PBR light are seen only while realistic rendering
  * draws: in 3D, with it on.
  *
@@ -62,6 +63,7 @@ export abstract class PluginPresentationLightingApi {
    *
    * @examplePrompt Is realistic rendering on?
    * @examplePrompt Can I turn on the realistic view?
+   * @examplePrompt Why can't realistic mode be turned on?
    * @examplePrompt Which lighting preset is active?
    * @examplePrompt Are clouds showing in the sky?
    *
@@ -176,10 +178,13 @@ export abstract class PluginPresentationLightingApi {
    *
    * # Example
    * ```ts
-   * const { realisticAvailable } = await snaptrude.presentation.lighting.get()
-   * if (realisticAvailable) {
+   * const { realisticUnavailableReason } =
+   *   await snaptrude.presentation.lighting.get()
+   * if (realisticUnavailableReason === null) {
    *   await snaptrude.presentation.lighting.enableRealistic()
    *   await snaptrude.presentation.lighting.applyPreset("golden")
+   * } else if (realisticUnavailableReason === "REALISTIC_SUSPENDED") {
+   *   // Ask the user to turn Realistic on in View settings; do not retry.
    * }
    * ```
    */
@@ -392,14 +397,31 @@ export type PluginPresentationLightingApplyPresetOptions = z.infer<
   typeof PluginPresentationLightingApplyPresetOptions
 >
 
+/**
+ * Why realistic rendering cannot be turned on: the `details.reason` of the
+ * `PRECONDITION_FAILED` {@linkcode PluginPresentationLightingApi.enableRealistic}
+ * throws. `"REALISTIC_ROLLOUT_OFF"`: not enabled for this user, or the rollout
+ * has not been evaluated yet (wait or keep the Design look).
+ * `"REALISTIC_SUSPENDED"`: suspended in this browser after the GPU was lost or
+ * ran over its frame budget; only the user can lift it, from View settings.
+ */
+export const PluginPresentationLightingRealisticUnavailableReason = z.enum([
+  "REALISTIC_ROLLOUT_OFF",
+  "REALISTIC_SUSPENDED"
+])
+export type PluginPresentationLightingRealisticUnavailableReason = z.infer<
+  typeof PluginPresentationLightingRealisticUnavailableReason
+>
+
 /**
  * The lighting, returned by every {@linkcode PluginPresentationLightingApi}
  * method but `listPresets`.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `realistic` | `boolean` | The session asks for realistic rendering (drawn in 3D only) |
- * | `realisticAvailable` | `boolean` | `enableRealistic` can succeed: the rollout is on for this user and realistic rendering is not suspended in this browser |
+ * | `realistic` | `boolean` | Realistic rendering is on (drawn in 3D only); `false` while it is suspended in this browser |
+ * | `realisticAvailable` | `boolean` | `enableRealistic` can succeed: `realisticUnavailableReason` is `null` |
+ * | `realisticUnavailableReason` | {@linkcode PluginPresentationLightingRealisticUnavailableReason}` \| null` | Why `enableRealistic` would throw: the `details.reason` it throws with; `null` when it can succeed |
  * | `preset` | {@linkcode PluginPresentationLightingPresetId} | The active preset |
  * | `sunSource` | `"preset" \| "analysis"` | Who aims the sun |
  * | `sunDirection` | `{ x, y, z }` | From the sun toward the scene, world space (+Y up) |
@@ -412,6 +434,8 @@ export type PluginPresentationLightingApplyPresetOptions = z.infer<
 export const PluginPresentationLightingState = z.object({
   realistic: z.boolean(),
   realisticAvailable: z.boolean(),
+  realisticUnavailableReason:
+    PluginPresentationLightingRealisticUnavailableReason.nullable(),
   preset: PluginPresentationLightingPresetId,
   sunSource: z.enum(["preset", "analysis"]),
   sunDirection: Vec3Components,

package/src/api/presentation/views.ts

@@ -90,17 +90,23 @@ export abstract class PluginPresentationViewsApi {
    * @param options - All optional: `viewId` (capture this saved view; omit for the
    *   current viewport), `format` (default `"png"`), `resolution` (e.g. `"1280x720"`).
    * @returns A {@linkcode PluginPresentationViewsCaptureResult} with the base64
-   *   `image` data URL.
+   *   `image` data URL, and `realisticPending: true` when realistic rendering is
+   *   on but was still compiling its shaders after the capture's 20 s wait, so
+   *   the image shows the Design look instead (capture again once it is ready).
    * @throws If a given `viewId` does not exist.
    *
    * @examplePrompt Take a screenshot of the current view
    * @examplePrompt Capture this view as a PNG
    * @examplePrompt Render the Site Plan view to an image
    * @examplePrompt Export a high-res image of what I'm looking at
+   * @examplePrompt Did the realistic render finish before the screenshot?
    *
    * # Example
    * ```ts
-   * const { image } = await snaptrude.presentation.views.capture({ format: "png" })
+   * const shot = await snaptrude.presentation.views.capture({ format: "png" })
+   * if (shot.realisticPending) {
+   *   // Drawn with the Design look: realistic rendering was still compiling.
+   * }
    * ```
    */
   public abstract capture(options?: {
@@ -474,9 +480,11 @@ export type PluginPresentationViewsCaptureArgs = z.infer<
  * | Property | Type | Description |
  * |---|---|---|
  * | `image` | `string` | The captured image as a base64 data URL |
+ * | `realisticPending` | `boolean \| undefined` | `true` when realistic rendering was on but still compiling after the capture's wait, so the image was drawn with the Design look; `false` or absent otherwise (absent from hosts before 1.1) |
  */
 export const PluginPresentationViewsCaptureResult = z.object({
   image: z.string(),
+  realisticPending: z.boolean().optional(),
 })
 export type PluginPresentationViewsCaptureResult = z.infer<
   typeof PluginPresentationViewsCaptureResult
@@ -522,8 +530,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')
+  }
+})