@snaptrude/plugin-core 0.7.1 → 0.9.0

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

@@ -0,0 +1,233 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+// Type-only: src/handles.ts type-only-imports ArenaKind from this file, so the
+// cycle stays purely type-level and is erased at emit.
+import type { AnyArenaHandle } from "../../../handles"
+import { Handle } from "../../../handles"
+
+/**
+ * The 12 registry-arena handle kinds — the releasable families. Entity-style
+ * handles (component / material / underlay / terrain / importJob / comment) are
+ * raw engine ids with no arena entry and therefore no lifecycle: passing one to
+ * `release` is a silent no-op like any other unknown id.
+ */
+export const ArenaKind = z.enum([
+  "vec3",
+  "quat",
+  "line",
+  "arc",
+  "circle",
+  "profile",
+  "contour",
+  "brep",
+  "face",
+  "edge",
+  "halfedge",
+  "vertex",
+])
+export type ArenaKind = z.infer<typeof ArenaKind>
+
+/** Max handles accepted by a single `release` / `endScope(retain)` call. */
+export const RELEASE_BATCH_MAX = 10_000
+
+/**
+ * An opaque token identifying a handle scope opened by
+ * {@linkcode PluginCoreHandlesApi.beginScope}. It is NOT an arena handle —
+ * it pins no memory, and `release(token)` is a silent no-op; only
+ * {@linkcode PluginCoreHandlesApi.endScope} consumes it.
+ */
+export type ScopeToken = string
+
+/**
+ * Handle lifecycle — free host-side handle registry entries the plugin no
+ * longer needs, individually ({@linkcode release}), by kind
+ * ({@linkcode releaseAll}), or as a mint-recording region
+ * ({@linkcode beginScope} / {@linkcode endScope}).
+ *
+ * Releasing is a handle-lifecycle operation only: it frees the registry entry
+ * (host memory + quota room) and makes the handle unresolvable. It never
+ * deletes engine-side geometry or scene entities.
+ *
+ * Accessed via `snaptrude.core.handles`.
+ */
+export abstract class PluginCoreHandlesApi {
+  constructor() {}
+
+  /**
+   * Free arena handles in bulk. Unknown, foreign, or already-released ids are
+   * silent no-ops — there is no per-id result and no count, so responses can
+   * never be used as an existence oracle.
+   *
+   * @param handles The handles to release (max {@linkcode RELEASE_BATCH_MAX} per call)
+   * @returns Nothing
+   *
+   * # Example
+   * ```ts
+   * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   * // ... read what you need ...
+   * await snaptrude.core.handles.release(faces)
+   * ```
+   */
+  public abstract release(handles: ReadonlyArray<AnyArenaHandle>): PluginApiReturn<void>
+
+  /**
+   * Free every live arena handle of one kind, or ALL arena handles when the
+   * kind is omitted. Useful at batch boundaries — e.g. a poll loop that mints
+   * a fresh footprint contour per tick.
+   *
+   * @param kind Optional arena kind to restrict the sweep to
+   * @returns Nothing
+   *
+   * # Example
+   * ```ts
+   * const footprint = await snaptrude.design.query.spaces.getFootprint(space)
+   * // ... measure ...
+   * await snaptrude.core.handles.releaseAll("contour")
+   * ```
+   */
+  public abstract releaseAll(kind?: ArenaKind): PluginApiReturn<void>
+
+  /**
+   * Open a mint-recording scope: every arena handle MINTED after this call
+   * (fresh mints only — identity-deduped re-registrations of pre-existing
+   * objects are not captured) is freed when the matching
+   * {@linkcode endScope} runs. Scopes nest, up to 64 deep — always pair
+   * begin/end in try/finally.
+   *
+   * @returns The scope token to pass to {@linkcode endScope}
+   *
+   * # Example
+   * ```ts
+   * for (const space of spaces) {
+   *   const scope = await snaptrude.core.handles.beginScope()
+   *   try {
+   *     const footprint = await snaptrude.design.query.spaces.getFootprint(space)
+   *     const area = await snaptrude.core.geom.query.contour.getArea(footprint)
+   *   } finally {
+   *     await snaptrude.core.handles.endScope(scope) // footprint (and intermediates) freed
+   *   }
+   * }
+   * ```
+   */
+  public abstract beginScope(): PluginApiReturn<ScopeToken>
+
+  /**
+   * Close a scope by its token and free every handle it recorded, except those
+   * listed in `retain`. Retained handles are promoted to the enclosing scope
+   * (if any), so nesting composes like block scopes. Closing is
+   * token-addressed: an out-of-order close (interleaved async tasks) frees
+   * only that scope's mints and leaves other open scopes intact. Always pair
+   * begin/end in try/finally so a thrown body cannot leak the scope.
+   *
+   * @param scope The token returned by the matching {@linkcode beginScope}
+   * @param retain Handles minted inside the scope that must survive it
+   * @returns Nothing
+   *
+   * # Example
+   * ```ts
+   * const scope = await snaptrude.core.handles.beginScope()
+   * const outline = await snaptrude.design.query.spaces.getFootprint(space)
+   * const outer = await snaptrude.core.geom.query.contour.getOuterProfile(outline)
+   * await snaptrude.core.handles.endScope(scope, [outer]) // outline freed, outer survives
+   * ```
+   */
+  public abstract endScope(
+    scope: ScopeToken,
+    retain?: ReadonlyArray<AnyArenaHandle>
+  ): PluginApiReturn<void>
+
+  /**
+   * Live handle-registry statistics for the calling plugin, plus the host
+   * page's JS heap usage (when the browser exposes it). Diagnostic surface for
+   * verifying that releases actually shrink host memory.
+   *
+   * @returns Arena entry counts, open scope depth, and host heap bytes
+   *
+   * # Example
+   * ```ts
+   * const before = await snaptrude.core.handles.stats()
+   * await snaptrude.core.handles.releaseAll("vec3")
+   * const after = await snaptrude.core.handles.stats()
+   * console.log(`freed ${before.values - after.values} value entries`)
+   * ```
+   */
+  public abstract stats(): PluginApiReturn<PluginHandlesStatsResult>
+}
+
+/**
+ * Wire-normalize one handle argument: a raw id string passes through; a live
+ * `Handle` instance (direct host callers — console harness, host-internal) or a
+ * structured-clone-stripped `{id}` / tagged `{__h}` shape collapses to its id.
+ * Deliberately shape-lax beyond that (non-empty string) — a malformed id is
+ * just an id that resolves nowhere (anti-oracle).
+ */
+const handleIdWire = z.preprocess((v) => {
+  if (typeof v === "string") return v
+  if (v instanceof Handle) return v.id
+  if (v && typeof v === "object") {
+    const o = v as Record<string, unknown>
+    if (typeof o.__h === "string") return o.__h
+    if (typeof o.id === "string") return o.id
+  }
+  return v
+}, z.string().min(1))
+
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.release}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `handles` | `string[]` | Handles to release (≤ {@linkcode RELEASE_BATCH_MAX}) |
+ */
+export const PluginHandlesReleaseArgs = z.object({
+  handles: z.array(handleIdWire).max(RELEASE_BATCH_MAX),
+})
+export type PluginHandlesReleaseArgs = z.infer<typeof PluginHandlesReleaseArgs>
+
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.releaseAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode ArenaKind} (optional) | Restrict the sweep to one kind |
+ */
+export const PluginHandlesReleaseAllArgs = z.object({
+  kind: ArenaKind.optional(),
+})
+export type PluginHandlesReleaseAllArgs = z.infer<typeof PluginHandlesReleaseAllArgs>
+
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.endScope}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `scope` | {@linkcode ScopeToken} | Token from the matching `beginScope` |
+ * | `retain` | `string[]` (optional) | Scope-minted handles that must survive |
+ */
+export const PluginHandlesEndScopeArgs = z.object({
+  scope: z.string().regex(/^scope_[A-Za-z0-9_-]+$/, 'expected a "scope" token'),
+  retain: z.array(handleIdWire).max(RELEASE_BATCH_MAX).optional(),
+})
+export type PluginHandlesEndScopeArgs = z.infer<typeof PluginHandlesEndScopeArgs>
+
+/**
+ * Result of {@linkcode PluginCoreHandlesApi.stats}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `resources` | `number` | Live resource-arena entries (profile/contour) |
+ * | `values` | `number` | Live value-arena entries (vec3/quat/line/arc/circle) |
+ * | `topology` | `number` | Live topology-arena entries (brep/face/edge/halfedge/vertex) |
+ * | `scopes` | `number` | Currently open handle scopes |
+ * | `hostHeapUsedBytes` | `number \| null` | Host page `usedJSHeapSize` (null where unsupported) |
+ * | `hostHeapTotalBytes` | `number \| null` | Host page `totalJSHeapSize` (null where unsupported) |
+ */
+export const PluginHandlesStatsResult = z.object({
+  resources: z.number().int().nonnegative(),
+  values: z.number().int().nonnegative(),
+  topology: z.number().int().nonnegative(),
+  scopes: z.number().int().nonnegative(),
+  hostHeapUsedBytes: z.number().nullable(),
+  hostHeapTotalBytes: z.number().nullable(),
+})
+export type PluginHandlesStatsResult = z.infer<typeof PluginHandlesStatsResult>

package/src/api/core/index.ts

@@ -10,7 +10,12 @@ import { PluginCoreBuildingsApi } from "./buildings"
 import { PluginCoreLayersApi } from "./layers"
 import { PluginCoreTagsApi } from "./tags"
 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"
 
 /**
  * Core primitives and infrastructure used across the plugin API.
@@ -20,13 +25,17 @@ import { PluginCoreProposalsApi } from "./proposals"
  * - {@linkcode PluginCoreApi.history} — Undo / redo of committed history entries
  * - {@linkcode PluginCoreApi.units} — Unit-type queries and conversion
  * - {@linkcode PluginCoreApi.zoom} — Camera zoom controls (extents / selection)
+ * - {@linkcode PluginCoreApi.camera} — Camera controls — position, standard views, 2D/3D mode
+ * - {@linkcode PluginCoreApi.user} — User locale — timezone & language
  * - {@linkcode PluginCoreApi.project} — Project-level settings and info
  * - {@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
+ * - {@linkcode PluginCoreApi.handles} — Handle lifecycle: release, releaseAll, scopes
  * - {@linkcode PluginCoreApi.proposals} — Design options: read, create, rename, switch, delete
  */
 export abstract class PluginCoreApi {
@@ -40,6 +49,10 @@ export abstract class PluginCoreApi {
   public abstract units: PluginUnitsApi
   /** Camera zoom controls. See {@linkcode PluginZoomApi}. */
   public abstract zoom: PluginZoomApi
+  /** Camera controls — position, standard views, 2D/3D mode. See {@linkcode PluginCameraApi}. */
+  public abstract camera: PluginCameraApi
+  /** User locale — timezone & language. See {@linkcode PluginUserApi}. */
+  public abstract user: PluginUserApi
   /** Project-level settings and info. See {@linkcode PluginProjectApi}. */
   public abstract project: PluginProjectApi
   /** Comments — create, edit, resolve, tag, list. See {@linkcode PluginCommentApi}. */
@@ -48,12 +61,18 @@ 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}. */
   public abstract tags: PluginCoreTagsApi
   /** I/O — file import, import jobs, and underlay management. See {@linkcode PluginCoreIoApi}. */
   public abstract io: PluginCoreIoApi
+  /** Handle lifecycle — release, releaseAll, and mint-recording scopes. See {@linkcode PluginCoreHandlesApi}. */
+  public abstract handles: PluginCoreHandlesApi
   /** Proposals — design options: read, create, rename, switch, delete. See {@linkcode PluginCoreProposalsApi}. */
   public abstract proposals: PluginCoreProposalsApi
 
@@ -65,11 +84,16 @@ export * from "./geom"
 export * from "./history"
 export * from "./units"
 export * from "./zoom"
+export * from "./camera"
+export * from "./user"
 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"
+export * from "./handles"
 export * from "./proposals"

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

@@ -0,0 +1,126 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+
+/**
+ * Serialization format for {@link PluginCoreIoExportApi.model}.
+ *
+ * `glb` / `obj` serialize in the browser; `fbx` / `3ds` run the same server
+ * conversion the app's Export dialog uses and return a **zip** containing the
+ * converted file.
+ */
+export const ExportModelFormat = z.enum(["glb", "obj", "fbx", "3ds"])
+export type ExportModelFormat = z.infer<typeof ExportModelFormat>
+
+/**
+ * What to export: the whole model (`"scene"`, default) or only the current
+ * selection (`"selection"`).
+ */
+export const ExportScope = z.enum(["scene", "selection"])
+export type ExportScope = z.infer<typeof ExportScope>
+
+/**
+ * A serialized model file returned by {@link PluginCoreIoExportApi.model}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `fileName` | `string` | Suggested file name incl. extension (e.g. `"model.glb"`) |
+ * | `mimeType` | `string` | MIME type (`"model/gltf-binary"` for glb, `"text/plain"` for obj) |
+ * | `dataBase64` | `string` | The file's bytes, base64-encoded (decode to save/download) |
+ */
+export const ExportedFile = z.object({
+  fileName: z.string(),
+  mimeType: z.string(),
+  dataBase64: z.string(),
+})
+export type ExportedFile = z.infer<typeof ExportedFile>
+
+/**
+ * Model export — serialize the scene (or selection) to a downloadable 3D file.
+ *
+ * `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). 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).
+ * - `"obj"` — Wavefront OBJ text (`text/plain`); geometry only, serialized in
+ *   the browser.
+ * - `"fbx"` / `"3ds"` — Autodesk FBX / 3D Studio; the scene is uploaded to the
+ *   same `/exportmodel/` conversion service the app's Export dialog uses, and
+ *   the call resolves once the converted artifact is fetched back — a **zip**
+ *   (`application/zip`) containing the `.fbx`/`.3ds` file. Whole-scene only
+ *   (`scope: "selection"` is rejected). Conversion runs on the server and is
+ *   bounded by the per-call plugin timeout (60 s) — very large models may
+ *   exceed it and reject with `TIMEOUT`.
+ *
+ * For the browser formats, only real model geometry is exported (walls, slabs,
+ * roofs, floors, doors, windows, furniture, staircases, masses, ceilings,
+ * mullions, beams, columns, terrain); UI helpers, hidden objects, and
+ * hidden-bucket objects are excluded — matching the app's GLB export. The
+ * server formats convert the full serialized scene (hidden-bucket objects
+ * excluded), exactly like the Export dialog. This is a **read**: it never
+ * mutates the model.
+ *
+ * > Server-backed BIM exports (RVT / IFC / DWG) are **not** exposed here — those
+ * > run as fire-and-forget Forge jobs that stream a browser download and return
+ * > no retrievable bytes. Use the app's Export menu for those.
+ *
+ * Accessed via `snaptrude.core.io.export`.
+ */
+export abstract class PluginCoreIoExportApi {
+  constructor() {}
+
+  /**
+   * Export the model to a 3D file and return its bytes as base64.
+   *
+   * @param format - `"glb"` (binary glTF, geometry + materials), `"obj"`
+   *   (Wavefront OBJ text, geometry only) — both serialized in the browser —
+   *   or `"fbx"` / `"3ds"`, converted by the app's export service and returned
+   *   as a zip containing the converted file.
+   * @param scope - `"scene"` (default) for the whole model, or `"selection"` for
+   *   only the currently selected objects (browser formats only — `"fbx"`/`"3ds"`
+   *   reject it). An empty selection yields an empty file.
+   * @returns an {@linkcode ExportedFile} — `{ fileName, mimeType, dataBase64 }`.
+   * @throws if the format is unsupported, `scope: "selection"` is combined with a
+   *   server format, or the serialization/conversion fails.
+   *
+   * @examplePrompt Export the model as a GLB
+   * @examplePrompt Give me the whole scene as an OBJ file
+   * @examplePrompt Export just my selection to GLB
+   * @examplePrompt Download the model as an FBX file
+   * @examplePrompt Export the scene to 3DS for 3ds Max
+   *
+   * # Example
+   * ```ts
+   * const file = await snaptrude.core.io.export.model("glb")
+   * // decode base64 → bytes and save/download in the plugin UI
+   * const bytes = Uint8Array.from(atob(file.dataBase64), (c) => c.charCodeAt(0))
+   * const blob = new Blob([bytes], { type: file.mimeType })
+   * // ...offer blob for download as file.fileName
+   *
+   * // Only the current selection, as OBJ text:
+   * const obj = await snaptrude.core.io.export.model("obj", "selection")
+   * const text = atob(obj.dataBase64)
+   * ```
+   */
+  public abstract model(
+    format: ExportModelFormat,
+    scope?: ExportScope,
+  ): PluginApiReturn<ExportedFile>
+}
+
+/**
+ * Arguments for {@link PluginCoreIoExportApi.model}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | {@link ExportModelFormat} | `"glb"`, `"obj"`, `"fbx"`, or `"3ds"` |
+ * | `scope` | {@link ExportScope} | `"scene"` (default) or `"selection"` (browser formats only) |
+ */
+export const PluginExportModelArgs = z.object({
+  format: ExportModelFormat,
+  scope: ExportScope.optional(),
+})
+export type PluginExportModelArgs = z.infer<typeof PluginExportModelArgs>

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/io/index.ts

@@ -3,6 +3,7 @@ import { PluginCoreIoJobApi } from "./job"
 import { PluginCoreIoUnderlayApi } from "./underlay"
 import { PluginCoreIoTerrainApi } from "./terrain"
 import { PluginCoreIoQueryApi } from "./query"
+import { PluginCoreIoExportApi } from "./export"
 
 /**
  * I/O — bring external files into the project and manage what was imported.
@@ -12,6 +13,7 @@ import { PluginCoreIoQueryApi } from "./query"
  * - {@linkcode PluginCoreIoApi.job} — poll long-running async imports (e.g. DWG)
  * - {@linkcode PluginCoreIoApi.underlay} — inspect/scale/opacity/delete placed underlays
  * - {@linkcode PluginCoreIoApi.terrain} — inspect/edit the site terrain (datum, layers, delete)
+ * - {@linkcode PluginCoreIoApi.export} — serialize the model to glb/obj (base64 bytes)
  *
  * Accessed via `snaptrude.core.io`.
  */
@@ -26,6 +28,8 @@ export abstract class PluginCoreIoApi {
   public abstract underlay: PluginCoreIoUnderlayApi
   /** Inspect and manage the site terrain. See {@linkcode PluginCoreIoTerrainApi}. */
   public abstract terrain: PluginCoreIoTerrainApi
+  /** Serialize the model to a downloadable 3D file. See {@linkcode PluginCoreIoExportApi}. */
+  public abstract export: PluginCoreIoExportApi
 
   constructor() {}
 }
@@ -35,3 +39,4 @@ export * from "./job"
 export * from "./underlay"
 export * from "./terrain"
 export * from "./query"
+export * from "./export"

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>
+}