@snaptrude/plugin-core 0.5.0 → 0.6.0

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

@@ -0,0 +1,214 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { TerrainHandle } from "../../../../handles"
+
+/**
+ * Terrain — inspect and manage the project's site terrain (the singleton created
+ * by `core.io.import.terrain`).
+ *
+ * There is at most one terrain per project. These methods read and edit it: the
+ * vertical **datum**, elevation/satellite layers, opacity, the cut/fill report,
+ * and removal. All edits are undoable.
+ *
+ * ## Datum
+ * The **datum** is the terrain's vertical position relative to where it was
+ * imported. {@link PluginCoreIoTerrainApi.setDatum} shifts the whole terrain
+ * vertically by a **relative** offset (each call moves it further — calls are
+ * cumulative, not absolute); {@link PluginCoreIoTerrainApi.getDatum} reads the
+ * current vertical offset from the imported position.
+ *
+ * Accessed via `snaptrude.core.io.terrain`.
+ */
+export abstract class PluginCoreIoTerrainApi {
+  constructor() {}
+
+  /**
+   * Whether the project has a site terrain.
+   *
+   * @examplePrompt Does this project have site terrain?
+   * @examplePrompt Is there a terrain imported?
+   * @examplePrompt Check if the site topography exists
+   * @examplePrompt Has a terrain been added yet?
+   *
+   * # Example
+   * ```ts
+   * if (!(await snaptrude.core.io.terrain.exists())) {
+   *   await snaptrude.core.io.import.terrain(40.7128, -74.006, 300, 300)
+   * }
+   * ```
+   */
+  public abstract exists(): PluginApiReturn<boolean>
+
+  /**
+   * Resolve the project's terrain handle, or `null` if there is none. The same
+   * handle {@link core.io.import.terrain} returns — use it to obtain the handle
+   * without re-importing.
+   *
+   * @examplePrompt Get the terrain handle
+   * @examplePrompt Give me the site terrain
+   * @examplePrompt Fetch the current terrain
+   * @examplePrompt Return the topography handle if it exists
+   */
+  public abstract get(): PluginApiReturn<TerrainHandle | null>
+
+  /**
+   * Read the terrain's current vertical position (world Y, internal units).
+   * `null` if there is no terrain. Import places the terrain so its highest
+   * point sits at `y = 0`, so a never-shifted terrain reads a negative
+   * baseline, not `0`; each {@link PluginCoreIoTerrainApi.setDatum} shift
+   * moves this value.
+   *
+   * @examplePrompt What's the terrain's datum?
+   * @examplePrompt Read the current site elevation reference
+   * @examplePrompt Get the terrain vertical offset
+   * @examplePrompt How far has the datum been shifted?
+   */
+  public abstract getDatum(): PluginApiReturn<number | null>
+
+  /**
+   * Shift the terrain's **datum** — move the whole terrain vertically DOWN by
+   * `offset` (internal units) from its current position; pass a negative value to
+   * raise it. Undoable.
+   *
+   * **Relative and cumulative**, not absolute: `setDatum(5)` called twice shifts
+   * the terrain down by 10 total, it does not settle at a fixed level. Read the
+   * terrain's resulting vertical position (world Y — not the accumulated
+   * shift) back with {@link PluginCoreIoTerrainApi.getDatum}.
+   *
+   * @param offset - How far to shift the terrain down, in internal units
+   *   (negative raises it).
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   *
+   * @examplePrompt Shift the terrain datum down by 12
+   * @examplePrompt Lower the site terrain by 10
+   * @examplePrompt Raise the terrain a little
+   * @examplePrompt Nudge the terrain datum down
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.io.terrain.setDatum(12)   // shift terrain down by 12 (relative)
+   * ```
+   */
+  public abstract setDatum(offset: number): PluginApiReturn<void>
+
+  /**
+   * Delete the site terrain. Undoable.
+   *
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   *
+   * @examplePrompt Delete the site terrain
+   * @examplePrompt Remove the topography
+   * @examplePrompt Clear the imported site
+   * @examplePrompt Get rid of the terrain
+   */
+  public abstract delete(): PluginApiReturn<void>
+
+  /**
+   * The terrain cut/fill earthwork report — cut, fill, and net volumes — or
+   * `null` if there is no terrain.
+   *
+   * @examplePrompt What are the cut and fill volumes for the site?
+   * @examplePrompt Get the terrain earthwork report
+   * @examplePrompt How much cut and fill does the grading need?
+   * @examplePrompt Show the net volume of the terrain edits
+   *
+   * # Example
+   * ```ts
+   * const r = await snaptrude.core.io.terrain.getReport()
+   * if (r) console.log(`cut ${r.cutVolume}, fill ${r.fillVolume}, net ${r.netVolume}`)
+   * ```
+   */
+  public abstract getReport(): PluginApiReturn<TerrainReport | null>
+
+  /** Whether terrain elevation (DEM height) is on. `null` if no terrain. */
+  public abstract isElevationEnabled(): PluginApiReturn<boolean | null>
+  /**
+   * Turn terrain elevation (DEM height) ON — a real 3D topography surface. Undoable.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Turn on terrain elevation
+   * @examplePrompt Enable the site heightmap
+   * @examplePrompt Make the terrain 3D
+   * @examplePrompt Show the topography relief
+   */
+  public abstract enableElevation(): PluginApiReturn<void>
+  /**
+   * Turn terrain elevation OFF — flatten to a plane. Undoable.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Flatten the terrain
+   * @examplePrompt Turn off site elevation
+   * @examplePrompt Disable the heightmap
+   * @examplePrompt Make the terrain flat
+   */
+  public abstract disableElevation(): PluginApiReturn<void>
+
+  /** Whether satellite imagery is draped on the terrain. `null` if no terrain. */
+  public abstract isSatelliteEnabled(): PluginApiReturn<boolean | null>
+  /**
+   * Turn satellite imagery ON. Undoable.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Show satellite imagery on the site
+   * @examplePrompt Enable the satellite texture
+   * @examplePrompt Turn on aerial imagery
+   * @examplePrompt Drape satellite over the terrain
+   */
+  public abstract enableSatellite(): PluginApiReturn<void>
+  /**
+   * Turn satellite imagery OFF. Undoable.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Hide the satellite imagery
+   * @examplePrompt Turn off the aerial texture
+   * @examplePrompt Disable satellite on the site
+   * @examplePrompt Remove the satellite drape
+   */
+  public abstract disableSatellite(): PluginApiReturn<void>
+
+  /** Read the terrain opacity, `0`..`1`, or `null` if no terrain. */
+  public abstract getOpacity(): PluginApiReturn<number | null>
+  /**
+   * Set the terrain opacity (`0` transparent .. `1` opaque). Undoable.
+   * @param opacity - Target opacity, `0`..`1`.
+   * @throws if writes are disabled, there is no terrain, or the terrain is
+   *   **locked** (unlock it in the app first).
+   * @examplePrompt Fade the terrain to 50%
+   * @examplePrompt Make the site semi-transparent
+   * @examplePrompt Set terrain opacity to 0.3
+   * @examplePrompt Dim the topography
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.io.terrain.setOpacity(0.5)
+   * ```
+   */
+  public abstract setOpacity(opacity: number): PluginApiReturn<void>
+}
+
+/**
+ * Terrain cut/fill earthwork report. Volumes are in the **project's display
+ * volume unit** (what the UI shows), not internal units.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `cutVolume` | `number` | Total excavated (cut) volume |
+ * | `fillVolume` | `number` | Total added (fill) volume |
+ * | `netVolume` | `number` | Net volume (`fill − cut`) |
+ */
+export const TerrainReport = z.object({
+  cutVolume: z.number(),
+  fillVolume: z.number(),
+  netVolume: z.number(),
+})
+export type TerrainReport = z.infer<typeof TerrainReport>
+
+/** Arguments for {@link PluginCoreIoTerrainApi.setDatum}. */
+export const PluginTerrainSetDatumArgs = z.object({ offset: z.number().finite() })
+export type PluginTerrainSetDatumArgs = z.infer<typeof PluginTerrainSetDatumArgs>
+
+/** Arguments for {@link PluginCoreIoTerrainApi.setOpacity}. */
+export const PluginTerrainSetOpacityArgs = z.object({ opacity: z.number().min(0).max(1) })
+export type PluginTerrainSetOpacityArgs = z.infer<typeof PluginTerrainSetOpacityArgs>

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

@@ -0,0 +1,295 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import { UnderlayHandle, BBoxComponents } from "../../../../handles"
+
+/**
+ * Underlays — inspect and edit the placed reference planes imported into the
+ * scene (`core.io.import.image` / `pdf` / `dwg` / `cadJson`).
+ *
+ * An underlay is an image, PDF, or CAD sketch dropped on a storey to trace over.
+ * This namespace lists them, calibrates their scale, sets opacity, and removes
+ * them. Every underlay is an {@linkcode UnderlayHandle}.
+ *
+ * ## Set-scale
+ * {@link PluginCoreIoUnderlayApi.setScale} takes **either** a numeric factor **or**
+ * a `{ planSize }` — the real-world length of the plan's longest side. A numeric
+ * factor is **absolute**: it is the total scale relative to the underlay's
+ * import-time size, the same number {@link PluginCoreIoUnderlayApi.getScale}
+ * returns as `scaleFactor` (so `setScale(u, 2)` is idempotent, and
+ * `setScale(u, (await getScale(u)).scaleFactor)` is a no-op). Use `planSize` to
+ * calibrate programmatically ("this plan is 50 m across") without clicking
+ * points on the canvas. Scale is supported for **image and PDF** underlays;
+ * **CAD scaling is not supported** (`getScale` returns `null`, `setScale`/`resetScale`
+ * throw). Image scale is tracked on the plan (and is **not undoable**); PDF scale is
+ * baked into the mesh (X/Z) and **is undoable**.
+ *
+ * Accessed via `snaptrude.core.io.underlay`.
+ */
+export abstract class PluginCoreIoUnderlayApi {
+  constructor() {}
+
+  /**
+   * List the underlays in the scene, optionally limited to one storey.
+   *
+   * @param storey - When given, only underlays on this storey number.
+   * @returns an array of {@linkcode UnderlayHandle} (empty, never `null`).
+   *
+   * @examplePrompt List all the reference underlays in the model
+   * @examplePrompt What underlays are on the ground floor?
+   * @examplePrompt Show every imported floor plan and PDF
+   * @examplePrompt How many trace-over images are on storey 2?
+   *
+   * # Example
+   * ```ts
+   * const underlays = await snaptrude.core.io.underlay.list(1)
+   * console.log(`${underlays.length} underlays on storey 1`)
+   * ```
+   */
+  public abstract list(storey?: number): PluginApiReturn<UnderlayHandle[]>
+
+  /**
+   * Read an underlay's world-space bounding box (image, PDF, or CAD). `null` if
+   * the underlay no longer resolves or has no measurable mesh. Useful for fitting
+   * drawn geometry to a reference, or computing a plan size before scaling.
+   *
+   * @param underlay - The underlay to measure.
+   *
+   * @examplePrompt How big is this floor plan in the scene?
+   * @examplePrompt Get the bounding box of the underlay
+   * @examplePrompt What's the extent of the imported PDF?
+   * @examplePrompt Measure the CAD sketch's size
+   *
+   * # Example
+   * ```ts
+   * const bb = await snaptrude.core.io.underlay.getBounds(plan)
+   * if (bb) console.log(`width ${bb.max.x - bb.min.x}`)
+   * ```
+   */
+  public abstract getBounds(underlay: UnderlayHandle): PluginApiReturn<BBoxComponents | null>
+
+  /**
+   * Read an underlay's scale. Works for **image and PDF** underlays. Returns
+   * `null` for CAD (scaling not supported) or if the handle no longer resolves.
+   *
+   * - `scaleFactor` — the **cumulative user scale** relative to the underlay's
+   *   import-time size (`1` = as imported). This is the same number
+   *   {@link PluginCoreIoUnderlayApi.setScale} accepts.
+   * - `initialScaleFactor` — the engine's import-time fit factor (how the raw
+   *   image was sized to the canvas on import); informational only. For PDF it
+   *   is always `1`.
+   *
+   * @param underlay - The underlay to read.
+   *
+   * @examplePrompt What scale is this floor plan set to?
+   * @examplePrompt Get the current and original scale of the underlay
+   * @examplePrompt How much has this image been scaled since import?
+   * @examplePrompt Read the scale factor of the reference plan
+   *
+   * # Example
+   * ```ts
+   * const s = await snaptrude.core.io.underlay.getScale(plan)
+   * if (s) console.log(`scale ${s.scaleFactor} (was ${s.initialScaleFactor})`)
+   * ```
+   */
+  public abstract getScale(
+    underlay: UnderlayHandle,
+  ): PluginApiReturn<{ scaleFactor: number; initialScaleFactor: number } | null>
+
+  /**
+   * Set an underlay's scale — the **calibration** step after import. Works for
+   * **image and PDF** underlays (CAD scaling is not supported — throws).
+   *
+   * Pass the `scale` argument as **either**:
+   * - a **number** — the **absolute** scale factor relative to the underlay's
+   *   import-time size (e.g. `2` makes it twice its imported size, `0.5` half —
+   *   no matter what the current scale is). It is the same number
+   *   {@link PluginCoreIoUnderlayApi.getScale} returns as `scaleFactor`, so the
+   *   call is idempotent: repeating `setScale(u, 2)` leaves the underlay at 2×.
+   *   **Or**
+   * - a **`{ planSize }`** object — the real-world **length of the plan's longest
+   *   side**, in the project's length unit. The factor is computed precisely so the
+   *   underlay's longest side becomes exactly `planSize`. This is the way to
+   *   calibrate programmatically without clicking points on the canvas: if you
+   *   know the plan is 50&nbsp;m across, pass `{ planSize: 50 }`.
+   *
+   * Image scale is not undoable; PDF scale is undoable.
+   *
+   * @param underlay - The underlay to scale (image or PDF).
+   * @param scale - An absolute numeric factor, **or** `{ planSize }` (the real
+   *   length of the underlay's longest side, in project units).
+   * @returns the applied `{ scaleFactor }` (the new absolute factor).
+   * @throws if writes are disabled, the underlay is CAD / can't be resolved, the plan
+   *   has zero size, or the engine fails.
+   *
+   * @examplePrompt Scale this floor plan so it's 50 meters across
+   * @examplePrompt Set the plan size to 30m — it's imported too small
+   * @examplePrompt Make the reference image twice its imported size
+   * @examplePrompt Calibrate the PDF: the site is 120 meters long
+   *
+   * # Example
+   * ```ts
+   * // Absolute factor — set the underlay to 2× its imported size:
+   * await snaptrude.core.io.underlay.setScale(plan, 2)
+   *
+   * // Fit to a real-world size — make the plan's longest side 50 project-units:
+   * await snaptrude.core.io.underlay.setScale(plan, { planSize: 50 })
+   * ```
+   */
+  public abstract setScale(
+    underlay: UnderlayHandle,
+    scale: number | { planSize: number },
+  ): PluginApiReturn<{ scaleFactor: number }>
+
+  /**
+   * Reset an underlay's scale back to its import-time size (image or PDF; CAD
+   * scaling is not supported — throws). Equivalent to `setScale(underlay, 1)`.
+   *
+   * @param underlay - The underlay to reset (image or PDF).
+   * @returns the restored `{ scaleFactor }` (`1`).
+   * @throws if writes are disabled, the underlay is CAD / can't be resolved, or the engine fails.
+   *
+   * @examplePrompt Reset this floor plan's scale to how it was imported
+   * @examplePrompt Undo the scaling on the underlay
+   * @examplePrompt Put the reference image back to its original size
+   * @examplePrompt Restore the plan's default scale
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.io.underlay.resetScale(plan)
+   * ```
+   */
+  public abstract resetScale(underlay: UnderlayHandle): PluginApiReturn<{ scaleFactor: number }>
+
+  /**
+   * Read an underlay's opacity (`0`..`1`), or `null` if it has no material.
+   *
+   * @param underlay - The underlay to read.
+   *
+   * @examplePrompt How transparent is this underlay?
+   * @examplePrompt Get the opacity of the floor plan
+   * @examplePrompt What's the fade level on the reference image?
+   * @examplePrompt Read the underlay's opacity
+   *
+   * # Example
+   * ```ts
+   * const o = await snaptrude.core.io.underlay.getOpacity(plan)
+   * ```
+   */
+  public abstract getOpacity(underlay: UnderlayHandle): PluginApiReturn<number | null>
+
+  /**
+   * Set an underlay's opacity (`0` = transparent .. `1` = opaque). Undoable.
+   * The engine keeps underlays faintly visible: values below `0.01` clamp to
+   * `0.01`, so `setOpacity(u, 0)` reads back as `0.01`, not `0`.
+   *
+   * @param underlay - The underlay to change.
+   * @param opacity - Target opacity, `0`..`1` (engine floor `0.01`).
+   * @throws if writes are disabled, the underlay can't be resolved, or the
+   *   underlay is **locked** (unlock it in the app first).
+   *
+   * @examplePrompt Fade this floor plan to 30% so I can see through it
+   * @examplePrompt Make the underlay half transparent
+   * @examplePrompt Set the reference image opacity to 0.2
+   * @examplePrompt Dim the trace-over plan
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.io.underlay.setOpacity(plan, 0.3)
+   * ```
+   */
+  public abstract setOpacity(underlay: UnderlayHandle, opacity: number): PluginApiReturn<void>
+
+  /**
+   * Delete an underlay from the scene (and its backend record). Applies to image,
+   * PDF, and CAD underlays.
+   *
+   * @param underlay - The underlay to delete.
+   * @throws if writes are disabled or the underlay can't be resolved.
+   *
+   * @examplePrompt Delete this floor plan underlay
+   * @examplePrompt Remove the imported PDF from the scene
+   * @examplePrompt Get rid of the CAD sketch I traced over
+   * @examplePrompt Clear the reference image off storey 1
+   *
+   * # Example
+   * ```ts
+   * const [first] = await snaptrude.core.io.underlay.list(1)
+   * if (first) await snaptrude.core.io.underlay.delete(first)
+   * ```
+   */
+  public abstract delete(underlay: UnderlayHandle): PluginApiReturn<void>
+}
+
+/**
+ * Arguments for {@link PluginCoreIoUnderlayApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storey` | `number`? | Only underlays on this storey (default: all) |
+ */
+export const PluginUnderlayListArgs = z.object({
+  storey: z.number().int().optional(),
+})
+export type PluginUnderlayListArgs = z.infer<typeof PluginUnderlayListArgs>
+
+/**
+ * Fit-to-size calibration: the real-world **length of the plan's longest side**, in
+ * the project's length unit. Passed to {@link PluginCoreIoUnderlayApi.setScale}; the
+ * factor is computed as `planSize / currentLongestSide`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `planSize` | `number` | Real-world length of the underlay's longest side (project units) |
+ */
+export const PluginUnderlayPlanSize = z.object({
+  planSize: z.number().positive(),
+})
+export type PluginUnderlayPlanSize = z.infer<typeof PluginUnderlayPlanSize>
+
+/** The `scale` argument of {@link PluginCoreIoUnderlayApi.setScale}: a direct factor or a `{ planSize }`. */
+export const PluginUnderlaySetScaleValue = z.union([
+  z.number().positive(),
+  PluginUnderlayPlanSize,
+])
+export type PluginUnderlaySetScaleValue = z.infer<typeof PluginUnderlaySetScaleValue>
+
+/**
+ * Arguments for {@link PluginCoreIoUnderlayApi.setScale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `underlay` | {@link UnderlayHandle} | The image/PDF underlay to scale |
+ * | `scale` | `number \| {@link PluginUnderlayPlanSize}` | Direct factor, or `{ planSize }` |
+ */
+export const PluginUnderlaySetScaleArgs = z.object({
+  underlay: UnderlayHandle,
+  scale: PluginUnderlaySetScaleValue,
+})
+export type PluginUnderlaySetScaleArgs = z.infer<typeof PluginUnderlaySetScaleArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoUnderlayApi.setOpacity}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `underlay` | {@link UnderlayHandle} | The underlay to change |
+ * | `opacity` | `number` | Target opacity, `0`..`1` |
+ */
+export const PluginUnderlaySetOpacityArgs = z.object({
+  underlay: UnderlayHandle,
+  opacity: z.number().min(0).max(1),
+})
+export type PluginUnderlaySetOpacityArgs = z.infer<typeof PluginUnderlaySetOpacityArgs>
+
+/**
+ * Arguments for the single-underlay methods
+ * ({@link PluginCoreIoUnderlayApi.getScale} / `resetScale` / `getOpacity` / `delete`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `underlay` | {@link UnderlayHandle} | The target underlay |
+ */
+export const PluginUnderlayRefArgs = z.object({
+  underlay: UnderlayHandle,
+})
+export type PluginUnderlayRefArgs = z.infer<typeof PluginUnderlayRefArgs>

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

@@ -439,10 +439,19 @@ export abstract class PluginDesignCreateApi {
    * mode copies stay in the source's instance family where possible; `"unique"` makes
    * independent geometry. The created copies become the active selection. Undoable.
    *
+   * Runs on the engine's array-copy tool, so its semantics carry over: an
+   * `"instance"` copy of a source that is not yet an instance **replaces that
+   * source** with a fresh instance component — the handle you passed in stops
+   * resolving after the call. Re-query (e.g. `design.query.listSpaces`) to pick
+   * up the replacement before operating on that entity again; copying the stale
+   * handle throws. `"unique"` mode never replaces sources.
+   *
    * @param components - Entities to copy (≥1)
    * @param displacement - Per-copy offset as a {@linkcode Vec3Handle} (copy `i` at `displacement * i`)
    * @param options - `count` (copies per component, default 1), `mode` (`"instance"` | `"unique"`, default `"instance"`)
    * @returns the created copies as {@linkcode ComponentHandle}`[]`
+   * @throws if a component handle is unknown or stale (replaced by an earlier
+   *   `"instance"` copy), `count` is not a positive integer, or the engine fails
    *
    * @examplePrompt Copy this room 3 times spaced 6m apart
    * @examplePrompt Duplicate the selected furniture along the X axis

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

@@ -35,7 +35,7 @@ export const ErasableEdgeRef = z.object({
   strategy: EraseStrategy,
   /** Bottom-graph edge weight: `1` = external boundary edge, `>=2` = internal edge shared between components. */
   edgeWeight: z.number(),
-  /** The components this edge is incident to — one for external (DirectDelete), two for internal (DirectUnion). */
+  /** The components this edge is incident to — one for external (DirectDelete); two or more for internal (DirectUnion; 3+ at T-junctions where several masses share the edge). */
   components: z.array(ComponentHandle),
   /** A representative point on the edge (its head endpoint). Diagnostic only. */
   snapPoint: Vec3Handle,

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

@@ -3,6 +3,91 @@ import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 
+/**
+ * The entity kinds {@linkcode PluginDesignSelectionApi.setByFilter} can select —
+ * the union of the editor's "Filter selection" menus (Design tab + BIM tab).
+ * Tokens mirror {@linkcode PluginEntityType} where a kind exists on the query
+ * surface; the rest are selection-only kinds the query surface cannot reach
+ * (layer-backed and annotation objects).
+ *
+ * | Value | Entity (menu label) |
+ * |---|---|
+ * | `"wall"` | Wall |
+ * | `"slab"` | Floor slab |
+ * | `"floor"` | Flooring |
+ * | `"door"` | Door |
+ * | `"window"` | Window |
+ * | `"beam"` | Beam |
+ * | `"column"` | Column |
+ * | `"ceiling"` | Ceiling |
+ * | `"roof"` | Roof |
+ * | `"staircase"` | Staircase |
+ * | `"furniture"` | Furniture |
+ * | `"pergola"` | Pergola |
+ * | `"sunshade"` | Sunshade |
+ * | `"referenceLine"` | Reference line |
+ * | `"space"` | Space (room mass) |
+ * | `"site"` | Site |
+ * | `"terrain"` | Terrain |
+ * | `"cad"` | CAD import |
+ * | `"pdf"` | PDF import |
+ * | `"image"` | Image import |
+ * | `"dimensionLine"` | Dimension line |
+ * | `"model3d"` | Imported 3D model |
+ * | `"neighborhoodBuilding"` | Neighborhood building |
+ * | `"programBlock"` | Program block (department mass) |
+ */
+export const PluginSelectionEntityType = z.enum([
+  "wall",
+  "slab",
+  "floor",
+  "door",
+  "window",
+  "beam",
+  "column",
+  "ceiling",
+  "roof",
+  "staircase",
+  "furniture",
+  "pergola",
+  "sunshade",
+  "referenceLine",
+  "space",
+  "site",
+  "terrain",
+  "cad",
+  "pdf",
+  "image",
+  "dimensionLine",
+  "model3d",
+  "neighborhoodBuilding",
+  "programBlock",
+])
+export type PluginSelectionEntityType = z.infer<typeof PluginSelectionEntityType>
+
+/**
+ * The filter for {@linkcode PluginDesignSelectionApi.setByFilter}. At least one
+ * field must be non-empty (to empty the selection use
+ * {@linkcode PluginDesignSelectionApi.clear}). Fields **AND**-combine; values
+ * within a field **OR**-combine — `{ storeys: [2], types: ["furniture"] }`
+ * selects only the furniture on storey 2.
+ *
+ * | Field | Type | Selects entities where |
+ * |---|---|---|
+ * | `storeys` | `number[]` | storey/floor level ∈ `storeys` (negative = basement) |
+ * | `types` | {@linkcode PluginSelectionEntityType}`[]` | entity kind ∈ `types` |
+ */
+export const PluginSelectionFilter = z
+  .object({
+    storeys: z.array(z.number()).optional(),
+    types: z.array(PluginSelectionEntityType).optional(),
+  })
+  .refine((f) => (f.storeys?.length ?? 0) + (f.types?.length ?? 0) > 0, {
+    message:
+      "PluginSelectionFilter requires at least one non-empty field (storeys or types); use design.selection.clear() to deselect everything",
+  })
+export type PluginSelectionFilter = z.infer<typeof PluginSelectionFilter>
+
 /**
  * `snaptrude.design.selection` — read and mutate the current scene selection.
  *
@@ -123,6 +208,50 @@ export abstract class PluginDesignSelectionApi {
    * ```
    */
   public abstract clear(): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Replace the selection with every visible entity of the active building that
+   * matches the filter — the programmatic equivalent of the editor's
+   * **Story selection** (`storeys`) and **Filter selection** (`types`) menus
+   * under the select tool, including their combination (fields AND, values
+   * within a field OR). Reaches selection-only kinds the query surface cannot
+   * (sites, terrain, CAD/PDF/image imports, dimension lines, 3D models,
+   * neighborhood buildings) and selects whole groups the way the editor does.
+   *
+   * This is a one-shot bulk select, not a persistent mode: the user's next
+   * canvas click resets the underlying filter state (the selection it made
+   * stays until changed). Results honor the ambient view — active building,
+   * hidden objects/buckets, and in 2D the active storey.
+   *
+   * @param filter Which entities to select — {@linkcode PluginSelectionFilter};
+   *   at least one field must be non-empty
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Select everything on storey 2
+   * @examplePrompt Select all the walls and doors
+   * @examplePrompt Story selection: select the ground floor and first floor
+   * @examplePrompt Filter selection: select all furniture in the model
+   * @examplePrompt Select only the furniture on the second storey
+   * @examplePrompt Select all the spaces so I can recolor them
+   *
+   * # Example
+   * ```ts
+   * // "Story selection": everything on storeys 1 and 2
+   * await snaptrude.design.selection.setByFilter({ storeys: [1, 2] })
+   *
+   * // "Filter selection": all walls and doors
+   * await snaptrude.design.selection.setByFilter({ types: ["wall", "door"] })
+   *
+   * // Combined: only the furniture on storey 2
+   * const { affected } = await snaptrude.design.selection.setByFilter({
+   *   storeys: [2],
+   *   types: ["furniture"],
+   * })
+   * ```
+   */
+  public abstract setByFilter(
+    filter: PluginSelectionFilter
+  ): PluginApiReturn<PluginDesignChangeResult>
 }
 
 /**