@snaptrude/plugin-core 0.8.0 → 0.9.0

package/src/api/core/geom/create/index.ts

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../../types"
-import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle } from "../../../../handles"
+import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, Vec3Components } from "../../../../handles"
 
 /**
  * Curve creation — construct new geometric curves from point handles (all-handle
@@ -177,6 +177,260 @@ export abstract class PluginGeomCreateApi {
     outer: ProfileHandle,
     holes?: ProfileHandle[],
   ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Create a closed solid **B-rep** from explicit face loops. Host API call —
+   * returns a {@linkcode BrepHandle}. Faces are plain arrays of `{x, y, z}`
+   * point components, NOT point handles (bulk-data precedent:
+   * `design.query.geometry.getTriangulatedMeshes`), in raw Babylon units.
+   *
+   * Each face is one planar loop of at least 3 points; at least 4 faces are
+   * required. Loops may be authored in any consistent winding — the host
+   * validates edge coherence (every edge shared by exactly two faces, in
+   * opposite directions) and fixes the global orientation so faces point
+   * outward. Faces must be planar and the solid must be closed; holes in faces
+   * are not supported (v1).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param faces Face loops — each an ordered array of `{x, y, z}` points (≥3 points per face, ≥4 faces)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if a face is degenerate or non-planar, an edge is not shared by
+   *   exactly two faces (open shell, non-manifold, or inconsistent winding), or
+   *   the faces do not form a valid closed solid
+   *
+   * @examplePrompt Create a brep from faces
+   * @examplePrompt Build a custom solid from a set of faces
+   * @examplePrompt Make a pyramid from triangular faces
+   *
+   * # Example
+   * ```ts
+   * // A pyramid: square base + 4 triangular sides
+   * const apex = { x: 0, y: 4, z: 0 }
+   * const a = { x: -2, y: 0, z: -2 }
+   * const b = { x: 2, y: 0, z: -2 }
+   * const c = { x: 2, y: 0, z: 2 }
+   * const d = { x: -2, y: 0, z: 2 }
+   * const brep = await snaptrude.core.geom.create.brepFromFaces([
+   *   [a, d, c, b], // base
+   *   [a, b, apex],
+   *   [b, c, apex],
+   *   [c, d, apex],
+   *   [d, a, apex],
+   * ])
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 5
+   * ```
+   */
+  public abstract brepFromFaces(faces: Vec3Components[][]): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** by extruding a contour along a direction.
+   * Host API call — returns a {@linkcode BrepHandle}. The direction is
+   * normalised by the host, so `amount` is the extrusion distance in raw
+   * Babylon units (negative extrudes the opposite way). The contour is copied —
+   * the input handle is never mutated. Holes and arc/circle profiles extrude
+   * natively (a circle profile yields a cylinder).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param contour The cross-section to extrude (outer profile + optional holes)
+   * @param direction Extrusion direction as plain `{x, y, z}` components (non-zero, normalised by the host)
+   * @param amount Extrusion distance (non-zero; negative extrudes opposite to `direction`)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if the extrusion is degenerate (zero amount, zero direction, or a
+   *   direction lying in the contour plane) or the contour cannot be extruded
+   *   into a valid solid
+   *
+   * @examplePrompt Extrude this profile 3 metres up
+   * @examplePrompt Make a solid by extruding this outline
+   * @examplePrompt Create a cylinder from a circle profile
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6
+   * ```
+   */
+  public abstract brepFromExtrusion(
+    contour: ContourHandle,
+    direction: Vec3Components,
+    amount: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** by lofting between a bottom and a top
+   * contour. Host API call — returns a {@linkcode BrepHandle}. Both contours
+   * must have the same number of edges (and matching hole counts); side faces
+   * connect corresponding edges by authored index. Corresponding edges must
+   * stay coplanar — a twisted loft would produce non-planar side faces and is
+   * rejected. The contours are copied — the input handles are never mutated.
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param bottomContour The bottom cross-section
+   * @param topContour The top cross-section (same edge and hole counts as the bottom)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if the contours are coincident, their edge or hole counts differ,
+   *   a side face between corresponding edges would be non-planar, or the
+   *   contours cannot be lofted into a valid solid
+   *
+   * @examplePrompt Make a tapered tower from these two outlines
+   * @examplePrompt Loft between a large base and a smaller top
+   * @examplePrompt Create a frustum from two squares
+   *
+   * # Example
+   * ```ts
+   * // A square frustum: 4m base lofted to a 2m top, 3m up
+   * const base = await snaptrude.core.geom.create.profileRect(4, 4)
+   * const top = await snaptrude.core.geom.create.profileRect(2, 2, await snaptrude.core.math.vec3.new(0, 3, 0))
+   * const brep = await snaptrude.core.geom.create.brepFromLoft(
+   *   await snaptrude.core.geom.create.contourFromProfile(base),
+   *   await snaptrude.core.geom.create.contourFromProfile(top),
+   * )
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6
+   * ```
+   */
+  public abstract brepFromLoft(
+    bottomContour: ContourHandle,
+    topContour: ContourHandle,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** from indexed mesh data: a vertex position
+   * array plus face loops of indices into it. Host API call — returns a
+   * {@linkcode BrepHandle}. The indexed form of
+   * {@linkcode PluginGeomCreateApi.brepFromFaces} — same validation (planar
+   * faces, closed manifold solid, every edge shared by exactly two faces) after
+   * the indices are expanded to point loops.
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param positions Vertex positions as plain `{x, y, z}` components (≥4)
+   * @param faces Face loops — each an ordered array of indices into `positions` (≥3 indices per face, ≥4 faces)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if an index is not an integer within `positions` bounds, a face is
+   *   degenerate or non-planar, or the faces do not form a valid closed solid
+   *
+   * @examplePrompt Create a brep from mesh vertices and indices
+   * @examplePrompt Turn this indexed mesh into a solid
+   * @examplePrompt Build a solid from vertex positions and face indices
+   *
+   * # Example
+   * ```ts
+   * // A tetrahedron from 4 vertices and 4 triangular faces
+   * const positions = [
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 4, y: 0, z: 0 },
+   *   { x: 2, y: 0, z: 4 },
+   *   { x: 2, y: 3, z: 1.5 },
+   * ]
+   * const brep = await snaptrude.core.geom.create.brepFromMesh(positions, [
+   *   [0, 2, 1], // base
+   *   [0, 1, 3],
+   *   [1, 2, 3],
+   *   [2, 0, 3],
+   * ])
+   * const vertexCount = await snaptrude.core.geom.query.brep.getVertexCount(brep) // 4
+   * ```
+   */
+  public abstract brepFromMesh(
+    positions: Vec3Components[],
+    faces: number[][],
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **union** of two breps
+   * (`a ∪ b`). Host API call — returns a new {@linkcode BrepHandle}. Inputs are
+   * read-only and may be authored breps (any `core.geom.create` brep
+   * constructor) or scene-derived breps from `design.query.geometry.getBrep`;
+   * coordinates are combined as-is, so both inputs must share a frame. The
+   * result must be a single solid — disjoint inputs are rejected.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a First solid
+   * @param b Second solid
+   * @returns The union as a new {@linkcode BrepHandle}
+   * @throws if the inputs do not overlap or touch (the union would be disjoint
+   *   solids) or the result cannot be built as a valid single solid
+   *
+   * @examplePrompt Union these two solids
+   * @examplePrompt Merge these breps into one mass
+   * @examplePrompt Combine the tower and the podium into a single solid
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.geom.create.brepFromExtrusion(baseContour, { x: 0, y: 1, z: 0 }, 3)
+   * const b = await snaptrude.core.geom.create.brepFromExtrusion(overlappingContour, { x: 0, y: 1, z: 0 }, 5)
+   * const merged = await snaptrude.core.geom.create.brepFromUnion(a, b)
+   * ```
+   */
+  public abstract brepFromUnion(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **subtraction** of two
+   * breps: **`a` minus `b`** — `b` is cut away from `a`. Host API call —
+   * returns a new {@linkcode BrepHandle}. Argument order matters:
+   * `brepFromSubtraction(a, b)` removes `b`'s volume from `a`. Inputs are
+   * read-only and may be authored or scene-derived breps (see
+   * {@linkcode PluginGeomCreateApi.brepFromUnion}); coordinates are combined
+   * as-is.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a The solid to subtract from
+   * @param b The solid to remove from `a`
+   * @returns `a` minus `b` as a new {@linkcode BrepHandle}
+   * @throws if `b` consumes `a` entirely (empty result), the result splits into
+   *   disjoint solids, or it cannot be built as a valid single solid
+   *
+   * @examplePrompt Subtract the courtyard from the building mass
+   * @examplePrompt Cut this solid out of that one
+   * @examplePrompt Punch a hole through the slab with this box
+   *
+   * # Example
+   * ```ts
+   * // buildingBrep minus courtyardBrep — order matters
+   * const carved = await snaptrude.core.geom.create.brepFromSubtraction(buildingBrep, courtyardBrep)
+   * ```
+   */
+  public abstract brepFromSubtraction(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **intersection** of two
+   * breps (`a ∩ b` — the shared volume only). Host API call — returns a new
+   * {@linkcode BrepHandle}. Inputs are read-only and may be authored or
+   * scene-derived breps (see {@linkcode PluginGeomCreateApi.brepFromUnion});
+   * coordinates are combined as-is.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a First solid
+   * @param b Second solid
+   * @returns The shared volume as a new {@linkcode BrepHandle}
+   * @throws if the inputs do not overlap (empty intersection), the result
+   *   splits into disjoint solids, or it cannot be built as a valid single
+   *   solid
+   *
+   * @examplePrompt Keep only the overlap of these two solids
+   * @examplePrompt Intersect these two masses
+   * @examplePrompt Clip the tower to the zoning envelope
+   *
+   * # Example
+   * ```ts
+   * const overlap = await snaptrude.core.geom.create.brepFromIntersection(towerBrep, envelopeBrep)
+   * ```
+   */
+  public abstract brepFromIntersection(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
 }
 
 /**
@@ -291,3 +545,92 @@ export const PluginGeomCreateContourFromProfilesArgs = z.object({
 export type PluginGeomCreateContourFromProfilesArgs = z.infer<
   typeof PluginGeomCreateContourFromProfilesArgs
 >
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromFaces}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `faces` | {@linkcode Vec3Components}`[][]` | Face loops — each an ordered array of `{x, y, z}` points (≥3 points per face, ≥4 faces) |
+ */
+export const PluginGeomCreateBrepFromFacesArgs = z.object({
+  faces: z.array(z.array(Vec3Components).min(3)).min(4),
+})
+
+export type PluginGeomCreateBrepFromFacesArgs = z.infer<
+  typeof PluginGeomCreateBrepFromFacesArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromExtrusion}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The cross-section to extrude |
+ * | `direction` | {@linkcode Vec3Components} | Extrusion direction (non-zero, finite components) |
+ * | `amount` | `number` | Extrusion distance (finite, non-zero) |
+ */
+export const PluginGeomCreateBrepFromExtrusionArgs = z.object({
+  contour: ContourHandle,
+  direction: z.object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    z: z.number().finite(),
+  }),
+  amount: z
+    .number()
+    .finite()
+    .refine((value) => value !== 0, { message: "amount must be non-zero" }),
+})
+
+export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
+  typeof PluginGeomCreateBrepFromExtrusionArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromLoft}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `bottomContour` | {@linkcode ContourHandle} | The bottom cross-section |
+ * | `topContour` | {@linkcode ContourHandle} | The top cross-section |
+ */
+export const PluginGeomCreateBrepFromLoftArgs = z.object({
+  bottomContour: ContourHandle,
+  topContour: ContourHandle,
+})
+
+export type PluginGeomCreateBrepFromLoftArgs = z.infer<typeof PluginGeomCreateBrepFromLoftArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromMesh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `positions` | {@linkcode Vec3Components}`[]` | Vertex positions (≥4) |
+ * | `faces` | `number[][]` | Face loops of indices into `positions` (≥3 indices per face, ≥4 faces) |
+ */
+export const PluginGeomCreateBrepFromMeshArgs = z.object({
+  positions: z.array(Vec3Components).min(4),
+  faces: z.array(z.array(z.number()).min(3)).min(4),
+})
+
+export type PluginGeomCreateBrepFromMeshArgs = z.infer<typeof PluginGeomCreateBrepFromMeshArgs>
+
+/**
+ * Arguments for the brep boolean constructors —
+ * {@linkcode PluginGeomCreateApi.brepFromUnion},
+ * {@linkcode PluginGeomCreateApi.brepFromSubtraction} (`a` minus `b`), and
+ * {@linkcode PluginGeomCreateApi.brepFromIntersection}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `a` | {@linkcode BrepHandle} | First solid (the subtraction target) |
+ * | `b` | {@linkcode BrepHandle} | Second solid (the subtraction tool) |
+ */
+export const PluginGeomCreateBrepBooleanArgs = z.object({
+  a: BrepHandle,
+  b: BrepHandle,
+})
+
+export type PluginGeomCreateBrepBooleanArgs = z.infer<typeof PluginGeomCreateBrepBooleanArgs>

package/src/api/core/index.ts

@@ -13,6 +13,8 @@ import { PluginCoreIoApi } from "./io"
 import { PluginCoreHandlesApi } from "./handles"
 import { PluginCoreProposalsApi } from "./proposals"
 import { PluginCameraApi } from "./camera"
+import { PluginCoreStoreysApi } from "./storeys"
+import { PluginCoreModeApi } from "./mode"
 import { PluginUserApi } from "./user"
 
 /**
@@ -29,6 +31,7 @@ import { PluginUserApi } from "./user"
  * - {@linkcode PluginCoreApi.comment} — Comments: create, edit, resolve, tag, list
  * - {@linkcode PluginCoreApi.groups} — Read & edit the group hierarchy
  * - {@linkcode PluginCoreApi.buildings} — Read & edit buildings and their storeys
+ * - {@linkcode PluginCoreApi.storeys} — Create, read & edit storeys (floors)
  * - {@linkcode PluginCoreApi.layers} — Read & toggle storey drawing/reference layers
  * - {@linkcode PluginCoreApi.tags} — Tag catalog + assignment
  * - {@linkcode PluginCoreApi.io} — Import files (image/pdf/cad/model/terrain), poll jobs, manage underlays
@@ -58,6 +61,10 @@ export abstract class PluginCoreApi {
   public abstract groups: PluginCoreGroupsApi
   /** Buildings — read & edit buildings and their storeys. See {@linkcode PluginCoreBuildingsApi}. */
   public abstract buildings: PluginCoreBuildingsApi
+  /** Storeys — create, read & edit storeys (floors). See {@linkcode PluginCoreStoreysApi}. */
+  public abstract storeys: PluginCoreStoreysApi
+  /** Application mode — read & switch the editor's top-bar mode. See {@linkcode PluginCoreModeApi}. */
+  public abstract mode: PluginCoreModeApi
   /** Layers — read & toggle storey drawing/reference layers. See {@linkcode PluginCoreLayersApi}. */
   public abstract layers: PluginCoreLayersApi
   /** Tags — tag catalog + assignment. See {@linkcode PluginCoreTagsApi}. */
@@ -83,6 +90,8 @@ export * from "./project"
 export * from "./comment"
 export * from "./groups"
 export * from "./buildings"
+export * from "./storeys"
+export * from "./mode"
 export * from "./layers"
 export * from "./tags"
 export * from "./io"

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

@@ -39,7 +39,9 @@ export type ExportedFile = z.infer<typeof ExportedFile>
  *
  * `core.io.export.model` hands you the file bytes as base64 — no download
  * dialog opens; the plugin decides what to do with the result (save it, POST
- * it, diff it). Four formats:
+ * it, diff it). For a different export intent, see `presentation.export`
+ * (Present-mode layout sheets to PDF/PNG/JPG) and `program.spreadsheet.export`
+ * (the area-program / takeoff workbook). Four formats:
  *
  * - `"glb"` — binary glTF (`model/gltf-binary`); geometry + materials,
  *   serialized in the browser (nothing is uploaded).

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

@@ -55,6 +55,9 @@ export abstract class PluginCoreIoImportApi {
    * Supported formats: PNG, JPG/JPEG, BMP. The image is placed on the target
    * storey's "Image" layer at ~50% opacity by default.
    *
+   * To place the image on a **Present-mode sheet** instead of the scene, use
+   * `presentation.import.image`.
+   *
    * The plane is placed at the storey origin (the engine's import placement);
    * there is no placement parameter — calibrate size with
    * {@link PluginCoreIoUnderlayApi.setScale} after import.
@@ -308,6 +311,40 @@ export abstract class PluginCoreIoImportApi {
     neighborhood?: boolean,
     parcels?: boolean,
   ): PluginApiReturn<TerrainHandle>
+
+  /**
+   * Import an **EPW weather file** into the project's weather catalog.
+   *
+   * Uploads an EnergyPlus Weather (`.epw`) file and registers it as the
+   * project's site weather, returning its catalog `weatherFileId` — the same id
+   * {@link PluginAnalysisWeatherApi.getSeries}, `program.site.getWeather`, and a
+   * daylight run's provenance report. Uploading a user file makes the site's
+   * `selectionMethod` `"user-upload"`, overriding nearest-station resolution.
+   *
+   * **Mutating**: this writes project state and is subject to the plugin
+   * write-gate — it throws when plugin writes are disabled. Unlike the file
+   * underlay/model importers it returns no scene handle (a weather file is not
+   * a scene object), only the catalog `{ weatherFileId, label }`.
+   *
+   * @param source - The `.epw` file to import: an `https://` URL or a `data:` URL.
+   * @returns A {@linkcode PluginImportEpwResult} — the catalog `weatherFileId`
+   *   and a human-readable `label` (the station/file name).
+   * @throws if writes are disabled, the source can't be loaded, or the file is
+   *   not a valid EPW.
+   *
+   * @examplePrompt Import this EPW weather file for the site
+   * @examplePrompt Upload a custom weather file for the daylight analysis
+   * @examplePrompt Use this .epw as the project's weather source
+   *
+   * # Example
+   * ```ts
+   * const { weatherFileId, label } = await snaptrude.core.io.import.epw(
+   *   "https://example.com/Chicago-OHare.epw",
+   * )
+   * console.log(`Weather set to ${label} (${weatherFileId})`)
+   * ```
+   */
+  public abstract epw(source: string): PluginApiReturn<PluginImportEpwResult>
 }
 
 /**
@@ -430,3 +467,30 @@ export const PluginImportTerrainArgs = z.object({
   parcels: z.boolean().optional(),
 })
 export type PluginImportTerrainArgs = z.infer<typeof PluginImportTerrainArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.epw}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | EPW `https://` URL or `data:` URL |
+ */
+export const PluginImportEpwArgs = z.object({
+  source: ImportSource,
+})
+export type PluginImportEpwArgs = z.infer<typeof PluginImportEpwArgs>
+
+/**
+ * Result of {@link PluginCoreIoImportApi.epw} — the imported weather file's
+ * catalog entry.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `analysis.weather`'s `weatherFileId`) |
+ * | `label` | `string` | Human-readable name (station / file name) |
+ */
+export const PluginImportEpwResult = z.object({
+  weatherFileId: z.string(),
+  label: z.string(),
+})
+export type PluginImportEpwResult = z.infer<typeof PluginImportEpwResult>

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

@@ -0,0 +1,96 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * The editor's top-bar application modes — the tabs a user switches between
+ * while working on a project.
+ */
+export const PluginAppMode = z.enum(["design", "bim", "present", "program"])
+export type PluginAppMode = z.infer<typeof PluginAppMode>
+
+export const PluginCoreModeSetArgs = z.object({
+  mode: PluginAppMode,
+})
+export type PluginCoreModeSetArgs = z.infer<typeof PluginCoreModeSetArgs>
+
+export interface PluginCoreModeListResult {
+  modes: PluginAppMode[]
+}
+
+export interface PluginCoreModeSetResult {
+  mode: PluginAppMode
+}
+
+/**
+ * Application-mode control — read and switch the editor's top-bar mode
+ * (Design, BIM, Present, Program), the same tabs a user clicks in the
+ * top menu bar. Accessed via `snaptrude.core.mode`.
+ *
+ * Not to be confused with the viewport's 2D/3D camera mode
+ * (`core.camera.setMode`) or saved presentation views (`presentation.views`).
+ *
+ * `set` covers `design`, `bim`, and `present` — in-page switches.
+ * `program` opens in its own browser tab in the product, which a plugin worker
+ * cannot do, so `set("program")` fails with `PRECONDITION_FAILED`; `get()`
+ * still reports `"program"` for code running in the Program tab.
+ */
+export abstract class PluginCoreModeApi {
+  constructor() {}
+
+  /**
+   * List every application mode the editor has.
+   *
+   * @returns The full set of mode tokens accepted by {@linkcode get} / {@linkcode set}.
+   *
+   * @examplePrompt What modes does Snaptrude have?
+   * @examplePrompt List the editor modes I can switch to
+   *
+   * # Example
+   * ```ts
+   * const { modes } = await snaptrude.core.mode.list()
+   * // ["design", "bim", "present", "program"]
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginCoreModeListResult>
+
+  /**
+   * Get the currently active application mode.
+   *
+   * @returns The active mode token (e.g. `"design"`).
+   *
+   * @examplePrompt Which mode am I in right now?
+   * @examplePrompt Am I in present mode?
+   * @examplePrompt Check whether the editor is in BIM mode
+   *
+   * # Example
+   * ```ts
+   * const mode = await snaptrude.core.mode.get()
+   * if (mode !== "present") await snaptrude.core.mode.set("present")
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginAppMode>
+
+  /**
+   * Switch the editor to another application mode — the same action as
+   * clicking that tab in the top menu bar.
+   *
+   * Supported: `"design"`, `"bim"`, `"present"`. Switching to
+   * `"program"` is rejected with `PRECONDITION_FAILED` (the Program surface
+   * opens in its own browser tab in the product; a plugin cannot open one).
+   *
+   * @param mode - Target mode token from {@linkcode PluginAppMode}
+   * @returns The committed `{ mode }` after the switch.
+   *
+   * @examplePrompt Switch to present mode
+   * @examplePrompt Open BIM mode
+   * @examplePrompt Go back to design mode
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.mode.set("present")
+   * // ... presentation work ...
+   * await snaptrude.core.mode.set("design")
+   * ```
+   */
+  public abstract set(mode: PluginAppMode): PluginApiReturn<PluginCoreModeSetResult>
+}