@snaptrude/plugin-core 0.10.0 → 0.11.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.10.0",
+  "version": "0.11.0-rc.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,17 +16,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "check-types": "tsc --noEmit",
-    "build": "tsup --clean",
-    "dev": "tsup --watch",
-    "clean-dist": "rm -rf dist",
-    "test": "node --test test/*.test.mjs",
-    "generate:manifest": "node scripts/generate-manifest.mjs",
-    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
-    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
-    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
-  },
   "devDependencies": {
     "ts-morph": "^28.0.0",
     "tsup": "^8.5.1",
@@ -37,5 +26,16 @@
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "build": "tsup --clean",
+    "dev": "tsup --watch",
+    "clean-dist": "rm -rf dist",
+    "test": "node --test test/*.test.mjs",
+    "generate:manifest": "node scripts/generate-manifest.mjs",
+    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
+    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
+    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
   }
-}
+}

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

@@ -62,6 +62,23 @@ export abstract class PluginCameraApi {
     view: PluginStandardView,
   ): PluginApiReturn<boolean>
 
+  /**
+   * Get the current camera mode. Paired with {@linkcode PluginCameraApi.setMode}.
+   *
+   * @returns `"2d"` when the editor is in plan view, `"3d"` otherwise.
+   *
+   * @examplePrompt Am I in 2D or 3D?
+   * @examplePrompt What view mode is the editor in?
+   *
+   * # Example
+   * ```ts
+   * if ((await snaptrude.core.camera.getMode()) === "2d") {
+   *   await snaptrude.core.camera.setMode("3d")
+   * }
+   * ```
+   */
+  public abstract getMode(): PluginApiReturn<PluginCameraMode>
+
   /**
    * Toggle the modelling mode between `2d` (plan) and `3d`. Mirrors the canvas
    * 2D/3D toggle: `3d` enters the isometric perspective view, `2d` drops to the

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

@@ -1,15 +1,47 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
+import { PUnitType } from "../units"
 
 /**
  * Project-level settings and info.
  *
- * Accessed via `snaptrude.core.project`. Currently exposes
+ * Accessed via `snaptrude.core.project`. Exposes
+ * {@linkcode PluginProjectApi.getInfo} (project identity) and
  * {@linkcode PluginProjectApi.settings} (snap + grid controls).
  */
 export abstract class PluginProjectApi {
   constructor() {}
 
+  /**
+   * Read identity and headline facts about the currently open project — id,
+   * display name, unit type, storey count, active storey, and site location
+   * when the project is geo-located.
+   *
+   * `activeStorey` and `storeyCount` are both scoped to the ACTIVE BUILDING, so
+   * they always describe the same building. In a multi-building project
+   * `storeyCount` is therefore NOT the total across every building — use
+   * `core.storeys.list()`, which spans all buildings, for that.
+   *
+   * @returns A {@linkcode PluginProjectInfo}. `name` is `null` only when the
+   *   project genuinely has no title; `location` is `null` only when the project
+   *   is not geo-located. Neither is used to signal a failure.
+   * @throws PRECONDITION_FAILED when no project is open.
+   * @throws OPERATION_FAILED when the project lookup or the site-location read
+   *   fails. A failed read is never reported as `null`.
+   *
+   * @examplePrompt What is this project called?
+   * @examplePrompt Where is this project located?
+   * @examplePrompt Give me a summary of this project
+   * @examplePrompt How many storeys does this project have?
+   *
+   * # Example
+   * ```ts
+   * const info = await snaptrude.core.project.getInfo()
+   * console.log(info.name, info.units, info.storeyCount)
+   * ```
+   */
+  public abstract getInfo(): PluginApiReturn<PluginProjectInfo>
+
   /** Project settings — snaps and grid. See {@linkcode PluginProjectSettingsApi}. */
   public abstract settings: PluginProjectSettingsApi
 }
@@ -416,3 +448,32 @@ export const PluginToleranceArgs = z.object({
 })
 
 export type PluginToleranceArgs = z.infer<typeof PluginToleranceArgs>
+
+/**
+ * Identity and headline facts about the currently open project.
+ *
+ * `location` is a read-only projection of {@linkcode PluginProgramSiteApi.getLocation}
+ * — `program.site.*` remains the full site surface (context, weather, polygons).
+ * It is mirrored here because "what and where is this project" is one question.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The open project's id (floorkey) |
+ * | `name` | `string \| null` | Display name; `null` only when the project has no title (a failed lookup throws) |
+ * | `units` | {@linkcode PUnitType} | The project's unit type |
+ * | `activeStorey` | `number` | The active storey value, in the active building |
+ * | `storeyCount` | `number` | How many storeys the ACTIVE BUILDING has (not the project-wide total — `core.storeys.list()` spans all buildings) |
+ * | `location` | `{ latitude, longitude } \| null` | Site location; `null` only when not geo-located (a failed read throws) |
+ */
+export const PluginProjectInfo = z.object({
+  projectId: z.string(),
+  name: z.string().nullable(),
+  units: PUnitType,
+  activeStorey: z.number(),
+  storeyCount: z.number(),
+  location: z
+    .object({ latitude: z.number(), longitude: z.number() })
+    .nullable(),
+})
+
+export type PluginProjectInfo = z.infer<typeof PluginProjectInfo>

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

@@ -160,6 +160,21 @@ export abstract class PluginCoreStoreysApi {
     options?: { name?: string },
   ): PluginApiReturn<PluginStoryUpdateResult>
 
+  /**
+   * Get the active storey's value. Paired with {@linkcode PluginCoreStoreysApi.setActive}.
+   *
+   * @returns The active storey value, in the same numbering `list` and `get` use.
+   *
+   * @examplePrompt Which storey am I on?
+   * @examplePrompt What is the current storey?
+   *
+   * # Example
+   * ```ts
+   * const storey = await snaptrude.core.storeys.getActive()
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<number>
+
   /**
    * Make a storey the active storey — the same as clicking it in the storey/layer
    * panel. Subsequent draws and creates target this storey, and in 2D the

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

@@ -217,11 +217,26 @@ export abstract class PluginDesignCreateApi {
    * Create a **floor** by extruding a footprint contour by `thickness`
    * (extruded upward).
    *
+   * The parametric engine owns floor topology and may resolve the request
+   * differently than asked: drawing against existing floors can **split** the
+   * footprint into several floors, or **merge** it into a pre-existing
+   * neighbour (that floor's region grows; nothing new is created). The call
+   * honors the engine's resolution and returns **every floor that covers the
+   * requested footprint after the operation** — the newly created floor(s),
+   * and/or the pre-existing floor that absorbed it. The array is never empty
+   * on success; a lone independently-created floor comes back as `[floor]`.
+   *
+   * **Breaking change in 0.11.0** — previously returned a single
+   * {@linkcode ComponentHandle}; callers must switch to the array (the first
+   * element preserves the old single-floor behavior for simple creates).
+   *
    * @param contour - Footprint (outer + holes)
    * @param thickness - Floor thickness (> 0)
    * @param position - Offset from origin
-   * @returns the {@linkcode ComponentHandle} of the created floor
-   * @throws if the contour is invalid or the thickness is not positive
+   * @returns the {@linkcode ComponentHandle}s of every floor covering the
+   *   requested footprint after parametric resolution (created and/or absorbing)
+   * @throws if the contour is invalid, the thickness is not positive, or the
+   *   engine rejected the operation (nothing covers the footprint)
    *
    * @examplePrompt Create a floor from this room outline
    * @examplePrompt Add a 100mm thick floor over the footprint
@@ -232,14 +247,14 @@ export abstract class PluginDesignCreateApi {
    * ```ts
    * const rect = await snaptrude.core.geom.create.profileRect(5, 4)
    * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const floor = await snaptrude.design.create.floor(contour, 0.1)
+   * const [floor, ...siblings] = await snaptrude.design.create.floor(contour, 0.1)
    * ```
    */
   public abstract floor(
     contour: ContourHandle,
     thickness: number,
     position?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
+  ): PluginApiReturn<ComponentHandle[]>
 
   /**
    * Create a **roof** by extruding a footprint contour by `thickness`. Created
@@ -395,7 +410,13 @@ 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.
-   * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
+   * @returns the actually-created wall {@linkcode ComponentHandle}s. The
+   *   parametric engine owns wall topology — curves touching existing walls
+   *   may merge into or split against them, so the returned count can differ
+   *   from the input curve count. Profile-ordered 1:1 matches come first,
+   *   then the remaining merged/split products in creation order. Re-query
+   *   (e.g. `design.query.spaces.listGeneratedBim`) rather than assuming a
+   *   wall per input curve.
    * @throws if the profile is empty, `wallType` names no wall type in the
    *   project, `storey` does not exist, or wall creation fails
    *
@@ -537,7 +558,9 @@ export abstract class PluginDesignCreateApi {
    *   the item's height yourself.
    * @param options - Optional placement options: `label` — instance name
    *   (default auto `${name}Ins${n}`); `createNewSourceMesh` — emit a
-   *   source-mesh creation command (default `true`)
+   *   source-mesh creation command (default `true`). `position.y` is always
+   *   grounded: the placed instance's bounding-box bottom rests at it (the
+   *   surface-flush grounding described above)
    * @param angleInDegrees - Optional signed rotation about the vertical axis, in
    *   degrees (same convention as {@linkcode PluginDesignTransformApi.rotate}).
    *   Applied at creation time so it is part of the placement's single undo entry.
@@ -571,7 +594,10 @@ export abstract class PluginDesignCreateApi {
   public abstract furniture(
     catalogId: string,
     position: Vec3Handle,
-    options?: { label?: string; createNewSourceMesh?: boolean },
+    options?: {
+      label?: string
+      createNewSourceMesh?: boolean
+    },
     angleInDegrees?: number,
   ): PluginApiReturn<ComponentHandle>
 
@@ -1219,7 +1245,7 @@ export const PluginDesignCreateWallsArgs = z.object({
 export type PluginDesignCreateWallsArgs = z.infer<
   typeof PluginDesignCreateWallsArgs
 >
-// TRANSPORT: positional signature shipped — storey is the trailing 5th arg:
+// TRANSPORT: positional signature shipped:
 //   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, storey?: number)
 
 // ---------------------------------------------------------------------------

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

@@ -20,6 +20,22 @@ export const PluginDesignDeleteEntitiesArgs = z.object({
 })
 export type PluginDesignDeleteEntitiesArgs = z.infer<typeof PluginDesignDeleteEntitiesArgs>
 
+/**
+ * Result of {@linkcode PluginDesignDeleteApi.entities} — the shared
+ * change-result shape plus the delete cascade. Deliberately a delete-specific
+ * extension of {@linkcode PluginDesignChangeResult} (which other change
+ * mutations keep unchanged).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `affected` | {@linkcode ComponentHandle}`[]` | The entities that were deleted (the resolved input set) |
+ * | `cascaded` | {@linkcode ComponentHandle}`[]`? | Components PG2 removed as a consequence — derived walls/floors/slabs of deleted spaces; returned so callers can invalidate cached handles |
+ */
+export const PluginDesignDeleteResult = PluginDesignChangeResult.extend({
+  cascaded: z.array(ComponentHandle).optional(),
+})
+export type PluginDesignDeleteResult = z.infer<typeof PluginDesignDeleteResult>
+
 /**
  * `snaptrude.design.delete.*` — **hard removal** of scene BIM entities.
  *
@@ -43,6 +59,9 @@ export abstract class PluginDesignDeleteApi {
    * @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`.
+   *   When the parametric engine removes further components as a consequence
+   *   (derived walls/floors/slabs of deleted spaces), those are reported in the
+   *   optional `cascaded` array — invalidate any cached handles to them too.
    * @throws If any supplied handle is unknown/forged (`HANDLE_INVALID`) — the whole
    *   call rejects before anything is deleted (all-or-nothing resolution).
    *
@@ -66,5 +85,5 @@ export abstract class PluginDesignDeleteApi {
    */
   public abstract entities(
     components: ComponentHandle[],
-  ): PluginApiReturn<PluginDesignChangeResult>
+  ): PluginApiReturn<PluginDesignDeleteResult>
 }

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

@@ -2,6 +2,7 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
+import { PluginObjectCatalogGroup } from "../doors"
 
 /**
  * `snaptrude.design.furniture` — the placeable furniture **catalog** (a library of
@@ -92,9 +93,42 @@ export abstract class PluginDesignFurnitureApi {
    * const items = await snaptrude.design.furniture.listCatalog(undefined, first)
    * console.log(first, "→", items.length, "items")
    * ```
+   *
+   * @deprecated Use `design.furniture.listCatalogGroups` — the same name
+   * `design.doors` and `design.windows` use. Still supported.
    */
   public abstract listCategories(): PluginApiReturn<string[]>
 
+  /**
+   * List the furniture catalog's groups. Matches
+   * {@linkcode PluginDesignDoorsApi.listCatalogGroups} and
+   * {@linkcode PluginDesignWindowsApi.listCatalogGroups}, so all three catalog
+   * surfaces are named alike.
+   *
+   * `source` is `"default"` for the built-in picker groups and `"team"` for the
+   * sub-types of THIS project's team library — exactly the split
+   * {@linkcode PluginDesignFurnitureApi.listCatalog}'s `source` filter uses, so
+   * every `"team"` group is guaranteed to match at least one team item here.
+   * For furniture the group token and its label are the same string (the
+   * category), so `dbType === label`; `design.doors`/`design.windows` have a
+   * distinct engine `dbType`.
+   *
+   * @returns The catalog groups as {@linkcode PluginObjectCatalogGroup}`[]`
+   *   (`[]` when empty). Pass a group's `dbType` (=== `label`) to
+   *   {@linkcode PluginDesignFurnitureApi.listCatalog}'s `category` filter to
+   *   list its items.
+   *
+   * @examplePrompt What furniture groups are available?
+   * @examplePrompt List the furniture categories in this project
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.furniture.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
   /**
    * List the placeable furniture catalog (team + general libraries),
    * optionally filtered by library `source` and/or `category`.

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

@@ -173,6 +173,7 @@ export type PluginDesignQueryComponentsArgs = z.infer<
  * | `isLocked` | `boolean` | Lock flag |
  * | `isHidden` | `boolean` | User-hidden flag |
  * | `isSelected` | `boolean` | Current selection state |
+ * | `isVisible` | `boolean` | Whether the entity currently has a visible representation on canvas (user hide flag AND LOD/mode gating both considered); read-only |
  * | `boundingBox` | {@linkcode BBoxComponents} | World-space AABB |
  * | `adjacency` | `{ spaceId: string; value: number }[]` | Adjacency relationships (spaces/masses only). `value`: `2` = Direct (required), `1` = Indirect or physical contact, `-1` = Restricted; `0` entries are filtered out. `[]` when adjacency has never been computed — see `program.adjacency.compute`. |
  */
@@ -192,6 +193,7 @@ export const PluginEntityProperties = z
     isLocked: z.boolean(),
     isHidden: z.boolean(),
     isSelected: z.boolean(),
+    isVisible: z.boolean(),
     boundingBox: BBoxComponents,
     adjacency: z.array(z.object({ spaceId: z.string(), value: z.number() })),
   })

package/src/api/design/query/spaces.ts

@@ -124,6 +124,41 @@ export abstract class PluginDesignQuerySpacesApi {
   public abstract getEnclosure(
     space: ComponentHandle,
   ): PluginApiReturn<PluginSpaceEnclosure | null>
+
+  /**
+   * List the space's **engine-generated BIM components** — the walls, floors
+   * and slabs the parametric engine derived from this space, grouped by kind.
+   *
+   * Unlike {@linkcode getEnclosure} (a geometric best-effort match), this read
+   * reports the engine's own derivation records, so every returned handle is a
+   * component the engine created *for this space*.
+   *
+   * The derived set is NOT stable across writes: a merge/split/rebuild of the
+   * space graph retires members and creates successors — re-query after any
+   * write that touches the space. This is the churn-recovery anchor: when a
+   * cached derived handle goes stale, call this again to pick up the current
+   * set.
+   *
+   * @param space - The space (room mass) to read
+   * @returns the generated component handles, grouped by kind
+   *   ({@linkcode PluginSpaceGeneratedBim}); a group is `[]` when the engine
+   *   derived nothing of that kind
+   * @throws If the space does not exist or the component is not a space/mass
+   *
+   * @examplePrompt Which walls did this room generate?
+   * @examplePrompt List the BIM components derived from the selected space
+   * @examplePrompt Get the floors and slabs that belong to this room
+   *
+   * # Example
+   * ```ts
+   * const [space] = await snaptrude.design.query.listSpaces()
+   * const bim = await snaptrude.design.query.spaces.listGeneratedBim(space)
+   * console.log(`${bim.walls.length} walls, ${bim.floors.length} floors`)
+   * ```
+   */
+  public abstract listGeneratedBim(
+    space: ComponentHandle,
+  ): PluginApiReturn<PluginSpaceGeneratedBim>
 }
 
 /**
@@ -273,3 +308,36 @@ export const PluginSpaceEnclosure = z.object({
   adjacentSpaces: z.array(PluginAdjacentSpace),
 })
 export type PluginSpaceEnclosure = z.infer<typeof PluginSpaceEnclosure>
+
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.listGeneratedBim}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ */
+export const PluginDesignQuerySpacesListGeneratedBimArgs = z.object({
+  space: ComponentHandle,
+})
+export type PluginDesignQuerySpacesListGeneratedBimArgs = z.infer<
+  typeof PluginDesignQuerySpacesListGeneratedBimArgs
+>
+
+/**
+ * Result of {@linkcode PluginDesignQuerySpacesApi.listGeneratedBim} — the
+ * space's engine-generated BIM component handles, grouped by kind. The set
+ * changes whenever a write merges/splits/rebuilds the space graph — re-query
+ * after writes rather than caching it.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `walls` | {@linkcode ComponentHandle}`[]` | Walls the engine derived from the space |
+ * | `floors` | {@linkcode ComponentHandle}`[]` | Floors the engine derived from the space |
+ * | `slabs` | {@linkcode ComponentHandle}`[]` | Slabs the engine derived from the space |
+ */
+export const PluginSpaceGeneratedBim = z.object({
+  walls: z.array(ComponentHandle),
+  floors: z.array(ComponentHandle),
+  slabs: z.array(ComponentHandle),
+})
+export type PluginSpaceGeneratedBim = z.infer<typeof PluginSpaceGeneratedBim>

package/src/api/design/visibility.ts

@@ -39,6 +39,26 @@ export abstract class PluginDesignVisibilityApi {
     components: ComponentHandle[],
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /**
+   * Reveal specific hidden components — the inverse of
+   * {@linkcode PluginDesignVisibilityApi.hide}. Use
+   * {@linkcode PluginDesignVisibilityApi.showAll} to reveal everything.
+   *
+   * @param components - The components to reveal.
+   * @returns A {@linkcode PluginDesignChangeResult} echoing the components shown.
+   *
+   * @examplePrompt Show these walls again
+   * @examplePrompt Unhide the selected furniture
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.visibility.show([wall])
+   * ```
+   */
+  public abstract show(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
   /**
    * Isolate entities — hide everything else so only the given entities remain
    * visible (the "Isolate" / solo action). Undoable. Reverse it with
@@ -94,6 +114,20 @@ export const PluginDesignVisibilityHideArgs = z.object({
 })
 export type PluginDesignVisibilityHideArgs = z.infer<typeof PluginDesignVisibilityHideArgs>
 
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.show}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to reveal |
+ */
+export const PluginDesignVisibilityShowArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityShowArgs = z.infer<
+  typeof PluginDesignVisibilityShowArgs
+>
+
 /**
  * Arguments for {@linkcode PluginDesignVisibilityApi.isolate}.
  *

package/src/api/entity/space.ts

@@ -434,6 +434,7 @@ export type PluginSpaceUpdateArgs = z.infer<typeof PluginSpaceUpdateArgs>
  * | `massType` | `string?` | Updated mass type (if changed) |
  * | `spaceType` | `string?` | Updated space type (if changed) |
  * | `departmentId` | `string \| null?` | Updated department ID (if changed) |
+ * | `rebuilt` | `boolean?` | `true` when a geometry update rebuilt the space's derived BIM — hosted children were re-created and the previous derived handles are retired (re-query them) |
  */
 export const PluginSpaceUpdateResult = z.object({
   spaceId: z.string(),
@@ -442,6 +443,7 @@ export const PluginSpaceUpdateResult = z.object({
   spaceType: z.string().optional(),
   areaClass: PluginAreaClass.optional(),
   departmentId: z.string().nullable().optional(),
+  rebuilt: z.boolean().optional(),
 })
 
 export type PluginSpaceUpdateResult = z.infer<typeof PluginSpaceUpdateResult>

package/src/api/presentation/placedViews.ts

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
-import { PluginSheetPosition } from "./sheets"
+import { PluginSheetPosition, PluginViewLod } from "./sheets"
 
 /**
  * Placed views — the view shapes already laid out on the Present canvas.
@@ -613,6 +613,23 @@ export abstract class PluginPresentationPlacedViewsApi {
     shapeId: string,
     enabled: boolean,
   ): PluginApiReturn<void>
+
+  /**
+   * Set the level of detail a placed view renders at — `"design"` (the
+   * Design-mode massing representation) or `"bim"` (the detailed BIM
+   * representation). Views only. Undoable. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape.
+   * @param lod - Target level of detail.
+   * @throws If Present mode is not open or `shapeId` is not a placed view.
+   *
+   * @examplePrompt Switch this placed view to the BIM level of detail
+   * @examplePrompt Show the massing version of the placed plan
+   */
+  public abstract setLod(
+    shapeId: string,
+    lod: PluginViewLod,
+  ): PluginApiReturn<void>
 }
 
 /** A point in crop space — fractions (0–1) of the uncropped view. */
@@ -657,6 +674,8 @@ export type PluginPlacedViewCrop = z.infer<typeof PluginPlacedViewCrop>
  * | `rotation` | `number` | Rotation in radians, `[0, 2π)` (nonzero only for 3D views — 2D views cannot rotate; set with `setRotation`) |
  * | `crop` | {@linkcode PluginPlacedViewCrop}` \| null` | Crop window (`null` when uncropped) |
  * | `isUnlinked` | `boolean` | Whether the source proposal was removed (an unlinked view no longer refreshes) |
+ * | `lod` | {@linkcode PluginViewLod}? | Level of detail the view renders at (`"design"` massing / `"bim"` detail); absent on views that predate LOD variants (set with `setLod`) |
+ * | `inactiveBuildingMask` | `boolean`? | Whether inactive proposal buildings are masked (the `setMask` toggle); absent when never set (masked by default) |
  */
 export const PluginPlacedView = z.object({
   shapeId: z.string(),
@@ -670,6 +689,8 @@ export const PluginPlacedView = z.object({
   rotation: z.number(),
   crop: PluginPlacedViewCrop.nullable(),
   isUnlinked: z.boolean(),
+  lod: PluginViewLod.optional(),
+  inactiveBuildingMask: z.boolean().optional(),
 })
 export type PluginPlacedView = z.infer<typeof PluginPlacedView>
 
@@ -1118,3 +1139,10 @@ export const PluginPlacedViewsSetMaskArgs = z.object({
   enabled: z.boolean(),
 })
 export type PluginPlacedViewsSetMaskArgs = z.infer<typeof PluginPlacedViewsSetMaskArgs>
+
+/** Arguments for {@link PluginPresentationPlacedViewsApi.setLod}. */
+export const PluginPlacedViewsSetLodArgs = z.object({
+  shapeId: z.string().min(1),
+  lod: PluginViewLod,
+})
+export type PluginPlacedViewsSetLodArgs = z.infer<typeof PluginPlacedViewsSetLodArgs>

package/src/api/presentation/sheets.ts

@@ -172,9 +172,10 @@ export abstract class PluginPresentationSheetsApi {
    * @param sheetId - The id of the sheet to place onto.
    * @param viewId - The id of the saved view to place.
    * @param options - Optional `position` ({@linkcode PluginSheetPosition}) —
-   *   where to place it (sheet centre when omitted) — and `scale` — a standard
+   *   where to place it (sheet centre when omitted) — `scale` — a standard
    *   scale value for the project's unit system (2D/site-plan views only;
-   *   auto-fit when omitted).
+   *   auto-fit when omitted) — and `lod` ({@linkcode PluginViewLod}) — the LOD
+   *   of the placed view (default: the product's Design default).
    * @returns A {@linkcode PluginPresentationSheetsPlaceResult} with the created
    *   `shapeId`.
    * @throws If Present mode is not open, the sheet/view id is invalid, `scale`
@@ -197,7 +198,11 @@ export abstract class PluginPresentationSheetsApi {
   public abstract place(
     sheetId: string,
     viewId: string,
-    options?: { position?: PluginSheetPosition; scale?: number },
+    options?: {
+      position?: PluginSheetPosition
+      scale?: number
+      lod?: PluginViewLod
+    },
   ): PluginApiReturn<PluginPresentationSheetsPlaceResult>
 
   /**
@@ -408,6 +413,15 @@ export const PluginSheetPosition = z.object({
 })
 export type PluginSheetPosition = z.infer<typeof PluginSheetPosition>
 
+/**
+ * The level of detail a placed view renders at: `"design"` (the Design-mode
+ * massing representation) or `"bim"` (the detailed BIM representation).
+ * Shared by `sheets.place` and `placedViews.*` (defined here because
+ * `placedViews` already imports from this module).
+ */
+export const PluginViewLod = z.enum(["design", "bim"])
+export type PluginViewLod = z.infer<typeof PluginViewLod>
+
 /** Result of {@linkcode PluginPresentationSheetsApi.list}. */
 export const PluginPresentationSheetsListResult = z.object({
   sheets: z.array(PluginPresentationSheet),
@@ -469,12 +483,14 @@ export type PluginPresentationSheetsSetMarginArgs = z.infer<
  * | `viewId` | `string` | The saved view to place |
  * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (sheet centre when omitted) |
  * | `scale` | `number \| undefined` | Standard scale value for the project's unit system (2D/site-plan views only; auto-fit to the closest standard scale when omitted) |
+ * | `lod` | {@linkcode PluginViewLod}` \| undefined` | LOD of the placed view (default: the product's Design default) |
  */
 export const PluginPresentationSheetsPlaceArgs = z.object({
   sheetId: z.string(),
   viewId: z.string(),
   position: PluginSheetPosition.optional(),
   scale: z.number().positive().optional(),
+  lod: PluginViewLod.optional(),
 })
 export type PluginPresentationSheetsPlaceArgs = z.infer<
   typeof PluginPresentationSheetsPlaceArgs