@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

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

@@ -0,0 +1,108 @@
+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 — and
+ * `program`, which opens the Program tab (a paired browser window) through the
+ * same path as the top bar's Program button. Because the open happens outside a
+ * user gesture the browser may block the pop-up; the editor then shows its
+ * "Allow pop-up to continue" modal and the tab opens when the user confirms.
+ * `get()` reports `"program"` only for code running in the Program tab itself.
+ * Prefer {@linkcode PluginWorkspaceApi.openProgramMode} when you need to know
+ * the tab is ready before calling `program.spreadsheet.*`.
+ */
+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.
+   *
+   * `"design"`, `"bim"` and `"present"` switch in place. `"program"` opens
+   * the Program tab (a paired browser window) exactly as the top bar's Program
+   * button does, and resolves once that tab has connected to the editor (up to
+   * ~90s — the browser may block the pop-up, in which case the editor shows an
+   * "Allow pop-up to continue" modal and waits for the user to confirm).
+   * Idempotent when the Program tab is already open. Note `get()` in the model
+   * tab keeps reporting the model tab's own mode afterwards; the Program tab is
+   * a separate window.
+   *
+   * @param mode - Target mode token from {@linkcode PluginAppMode}
+   * @returns The committed `{ mode }` after the switch.
+   * @throws `PRECONDITION_FAILED` for `"program"` when the user dismisses the
+   *   pop-up modal or the tab does not connect within the timeout.
+   *
+   * @examplePrompt Switch to present mode
+   * @examplePrompt Open BIM mode
+   * @examplePrompt Go back to design mode
+   * @examplePrompt Open program mode
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.mode.set("present")
+   * // ... presentation work ...
+   * await snaptrude.core.mode.set("design")
+   * ```
+   */
+  public abstract set(mode: PluginAppMode): PluginApiReturn<PluginCoreModeSetResult>
+}

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

@@ -0,0 +1,479 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { PUnitType } from "../units"
+
+/**
+ * Project-level settings and info.
+ *
+ * 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
+}
+
+/**
+ * Project settings — tolerance, snaps, and grid.
+ *
+ * Accessed via `snaptrude.core.project.settings`.
+ */
+export abstract class PluginProjectSettingsApi {
+  constructor() {}
+
+  /**
+   * Get the project tolerance as a numeric magnitude.
+   *
+   * The engine stores tolerance as a discrete per-unit precision option; this
+   * returns its magnitude (decimal precision `"0.00"` → `0.01`; fraction `"1/4"`
+   * → `0.25`).
+   *
+   * @examplePrompt What is the tolerance setting in this project?
+   * @examplePrompt Check the current dimension precision of the model
+   * @examplePrompt How precise are the measurements in this project?
+   * @examplePrompt Show me the project's tolerance value
+   *
+   * # Example
+   * ```ts
+   * const tolerance = await snaptrude.core.project.settings.getTolerance()
+   * console.log(tolerance) // e.g. 0.01
+   * ```
+   */
+  public abstract getTolerance(): PluginApiReturn<number>
+
+  /**
+   * Set the project tolerance. The value snaps to the **nearest allowed**
+   * per-unit precision option (tolerance is a discrete dropdown, not arbitrary).
+   *
+   * @param value - Target tolerance magnitude; snaps to the nearest allowed option.
+   * @returns `true` once applied; `false` if no tolerance options are available.
+   *
+   * @examplePrompt Set the project tolerance to 0.01
+   * @examplePrompt Change the dimension precision to two decimal places
+   * @examplePrompt Round dimensions to the nearest quarter inch
+   * @examplePrompt Make the measurements in this project more precise
+   *
+   * # Example
+   * ```ts
+   * // snaps to the nearest allowed precision option
+   * const applied = await snaptrude.core.project.settings.setTolerance(0.01)
+   * if (!applied) console.log("no tolerance options available")
+   * ```
+   */
+  public abstract setTolerance(value: number): PluginApiReturn<boolean>
+
+  /** Snap controls (dimension / angle / parallel / normal / magnetic). See {@linkcode PluginSnapsApi}. */
+  public abstract snaps: PluginSnapsApi
+  /** Grid controls. See {@linkcode PluginGridApi}. */
+  public abstract grid: PluginGridApi
+}
+
+/**
+ * Snap controls. Dimension and angle snaps each have a numeric threshold plus an
+ * on/off toggle; parallel, normal, and magnetic snaps are on/off only.
+ * (`normal` is the perpendicular snap.)
+ *
+ * Accessed via `snaptrude.core.project.settings.snaps`.
+ */
+export abstract class PluginSnapsApi {
+  constructor() {}
+
+  /**
+   * Set the dimension-snap threshold — the length increment that drawing and
+   * editing snap to when dimension snapping is on.
+   *
+   * @param value - The snap threshold distance.
+   *
+   * @examplePrompt Set the dimension snap to 100mm
+   * @examplePrompt Change the snap distance to half a metre
+   * @examplePrompt Make the cursor snap every 6 inches when drawing
+   * @examplePrompt Adjust the snapping increment for lengths
+   *
+   * # Example
+   * ```ts
+   * // the threshold only applies while dimension snapping is on
+   * await snaptrude.core.project.settings.snaps.setDimension(100)
+   * await snaptrude.core.project.settings.snaps.enableDimension()
+   * ```
+   */
+  public abstract setDimension(value: number): PluginApiReturn<boolean>
+  /**
+   * Get the current dimension-snap threshold — the length increment that
+   * drawing and editing snap to when dimension snapping is on.
+   *
+   * @examplePrompt What is the dimension snap distance?
+   * @examplePrompt Check the current snap increment for drawing
+   * @examplePrompt How far apart are the length snaps set?
+   * @examplePrompt Show me the snap spacing value
+   *
+   * # Example
+   * ```ts
+   * const increment = await snaptrude.core.project.settings.snaps.getDimension()
+   * console.log(increment)
+   * ```
+   */
+  public abstract getDimension(): PluginApiReturn<number>
+  /**
+   * Turn dimension snapping on, so drawing and editing snap to the configured
+   * length increment.
+   *
+   * @examplePrompt Turn on dimension snapping
+   * @examplePrompt Enable snapping to set lengths while I draw
+   * @examplePrompt Make my walls snap to round dimensions
+   * @examplePrompt Switch length snapping back on
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableDimension()
+   * ```
+   */
+  public abstract enableDimension(): PluginApiReturn<boolean>
+  /**
+   * Turn dimension snapping off, so lengths no longer snap to the configured
+   * increment while drawing.
+   *
+   * @examplePrompt Turn off dimension snapping
+   * @examplePrompt Stop snapping to fixed lengths when I draw
+   * @examplePrompt Disable the length snap so I can draw freely
+   * @examplePrompt I don't want dimensions to snap anymore
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableDimension()
+   * ```
+   */
+  public abstract disableDimension(): PluginApiReturn<boolean>
+
+  /**
+   * Set the angle-snap threshold in degrees — the angular increment that
+   * drawing snaps to when angle snapping is on.
+   *
+   * @param value - The snap threshold in degrees.
+   *
+   * @examplePrompt Set the angle snap to 15 degrees
+   * @examplePrompt Change angle snapping to every 45 degrees
+   * @examplePrompt Make drawing snap at 30 degree increments
+   * @examplePrompt Adjust the rotation snap angle
+   *
+   * # Example
+   * ```ts
+   * // snap drawing to 15-degree increments (applies while angle snapping is on)
+   * await snaptrude.core.project.settings.snaps.setAngle(15)
+   * await snaptrude.core.project.settings.snaps.enableAngle()
+   * ```
+   */
+  public abstract setAngle(value: number): PluginApiReturn<boolean>
+  /**
+   * Get the current angle-snap threshold in degrees — the angular increment
+   * that drawing snaps to when angle snapping is on.
+   *
+   * @examplePrompt What angle does drawing snap to?
+   * @examplePrompt Check the current angle snap in degrees
+   * @examplePrompt Show me the angle snapping increment
+   * @examplePrompt How many degrees is the angle snap set to?
+   *
+   * # Example
+   * ```ts
+   * const degrees = await snaptrude.core.project.settings.snaps.getAngle()
+   * console.log(degrees)
+   * ```
+   */
+  public abstract getAngle(): PluginApiReturn<number>
+  /**
+   * Turn angle snapping on, so drawn lines snap to the configured angle
+   * increment.
+   *
+   * @examplePrompt Turn on angle snapping
+   * @examplePrompt Enable snapping to angles while drawing
+   * @examplePrompt Make my lines snap to set angles
+   * @examplePrompt Switch angle snap back on
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableAngle()
+   * ```
+   */
+  public abstract enableAngle(): PluginApiReturn<boolean>
+  /**
+   * Turn angle snapping off, so lines can be drawn at any angle without
+   * snapping to fixed increments.
+   *
+   * @examplePrompt Turn off angle snapping
+   * @examplePrompt Stop lines snapping to fixed angles
+   * @examplePrompt Disable the angle snap so I can draw at any angle
+   * @examplePrompt Remove angle snapping while sketching
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableAngle()
+   * ```
+   */
+  public abstract disableAngle(): PluginApiReturn<boolean>
+
+  /**
+   * Turn parallel snapping on, so drawing snaps when the cursor lines up
+   * parallel to existing edges.
+   *
+   * @examplePrompt Turn on parallel snapping
+   * @examplePrompt Enable snapping to parallel lines
+   * @examplePrompt Help me draw walls parallel to existing ones
+   * @examplePrompt Snap to parallel edges when drawing
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableParallel()
+   * ```
+   */
+  public abstract enableParallel(): PluginApiReturn<boolean>
+  /**
+   * Turn parallel snapping off, so drawing no longer snaps to directions
+   * parallel to existing edges.
+   *
+   * @examplePrompt Turn off parallel snapping
+   * @examplePrompt Stop snapping to parallel edges
+   * @examplePrompt Disable the parallel snap guide
+   * @examplePrompt I don't want my lines snapping parallel anymore
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableParallel()
+   * ```
+   */
+  public abstract disableParallel(): PluginApiReturn<boolean>
+
+  /**
+   * Turn normal (perpendicular) snapping on, so drawing snaps when the cursor
+   * is at a right angle to existing edges.
+   *
+   * @examplePrompt Turn on perpendicular snapping
+   * @examplePrompt Enable the normal snap so lines snap at right angles
+   * @examplePrompt Snap to perpendicular when I draw walls
+   * @examplePrompt Help me draw at 90 degrees to existing edges
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableNormal()
+   * ```
+   */
+  public abstract enableNormal(): PluginApiReturn<boolean>
+  /**
+   * Turn normal (perpendicular) snapping off, so drawing no longer snaps at
+   * right angles to existing edges.
+   *
+   * @examplePrompt Turn off perpendicular snapping
+   * @examplePrompt Disable the normal snap
+   * @examplePrompt Stop snapping at right angles to edges
+   * @examplePrompt Remove the 90 degree snap guide
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableNormal()
+   * ```
+   */
+  public abstract disableNormal(): PluginApiReturn<boolean>
+
+  /**
+   * Turn magnetic snapping on, so the cursor is pulled to nearby geometry
+   * while drawing.
+   *
+   * @examplePrompt Turn on magnetic snapping
+   * @examplePrompt Enable the magnet snap
+   * @examplePrompt Make the cursor stick to nearby geometry when drawing
+   * @examplePrompt Switch magnetic snap back on
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableMagnetic()
+   * ```
+   */
+  public abstract enableMagnetic(): PluginApiReturn<boolean>
+  /**
+   * Turn magnetic snapping off, so the cursor is no longer pulled to nearby
+   * geometry while drawing.
+   *
+   * @examplePrompt Turn off magnetic snapping
+   * @examplePrompt Disable the magnet snap
+   * @examplePrompt Stop the cursor sticking to nearby objects
+   * @examplePrompt The magnetic snap is annoying, switch it off
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableMagnetic()
+   * ```
+   */
+  public abstract disableMagnetic(): PluginApiReturn<boolean>
+}
+
+/**
+ * Grid controls — the visual snap-to grid.
+ *
+ * Accessed via `snaptrude.core.project.settings.grid`.
+ */
+export abstract class PluginGridApi {
+  constructor() {}
+
+  /**
+   * Turn the grid on, showing the visual snap-to grid in the canvas.
+   *
+   * @examplePrompt Turn on the grid
+   * @examplePrompt Show the grid in my project
+   * @examplePrompt Enable the drawing grid
+   * @examplePrompt Switch the snap grid back on
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.grid.enable()
+   * ```
+   */
+  public abstract enable(): PluginApiReturn<boolean>
+  /**
+   * Turn the grid off, hiding the visual snap-to grid in the canvas.
+   *
+   * @examplePrompt Turn off the grid
+   * @examplePrompt Hide the grid
+   * @examplePrompt Disable the background grid in the canvas
+   * @examplePrompt Remove the drawing grid from view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.grid.disable()
+   * ```
+   */
+  public abstract disable(): PluginApiReturn<boolean>
+  /**
+   * Set the grid cell value — the size of each cell in the visual snap-to
+   * grid.
+   *
+   * @param value - The grid cell value.
+   *
+   * @examplePrompt Set the grid spacing to 1 metre
+   * @examplePrompt Change the grid cell size to 500mm
+   * @examplePrompt Make the grid squares 2 feet wide
+   * @examplePrompt Adjust the grid size in this project
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.grid.setValue(1)
+   * await snaptrude.core.project.settings.grid.enable()
+   * ```
+   */
+  public abstract setValue(value: number): PluginApiReturn<boolean>
+  /**
+   * Get the current grid cell value — the size of each cell in the visual
+   * snap-to grid.
+   *
+   * @examplePrompt What is the grid spacing?
+   * @examplePrompt Check the current grid cell size
+   * @examplePrompt How big are the grid squares?
+   * @examplePrompt Show me the grid size setting
+   *
+   * # Example
+   * ```ts
+   * const cellSize = await snaptrude.core.project.settings.grid.getValue()
+   * console.log(cellSize)
+   * ```
+   */
+  public abstract getValue(): PluginApiReturn<number>
+}
+
+/**
+ * Arguments for the snap-threshold setters
+ * ({@linkcode PluginSnapsApi.setDimension} / {@linkcode PluginSnapsApi.setAngle}).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The snap threshold (distance, or degrees for angle) |
+ */
+export const PluginSnapValueArgs = z.object({
+  value: z.number(),
+})
+
+export type PluginSnapValueArgs = z.infer<typeof PluginSnapValueArgs>
+
+/**
+ * Arguments for {@linkcode PluginGridApi.setValue}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The grid cell value |
+ */
+export const PluginGridValueArgs = z.object({
+  value: z.number(),
+})
+
+export type PluginGridValueArgs = z.infer<typeof PluginGridValueArgs>
+
+/**
+ * Arguments for {@linkcode PluginProjectSettingsApi.setTolerance}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | Target tolerance magnitude; snaps to the nearest allowed option |
+ */
+export const PluginToleranceArgs = z.object({
+  value: z.number(),
+})
+
+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>