@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.1

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

@@ -1,479 +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>
+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>