@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/dist/api/core/project/index.d.ts

@@ -0,0 +1,466 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+/**
+ * Project-level settings and info.
+ *
+ * Accessed via `snaptrude.core.project`. Exposes
+ * {@linkcode PluginProjectApi.getInfo} (project identity) and
+ * {@linkcode PluginProjectApi.settings} (snap + grid controls).
+ */
+export declare 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)
+     * ```
+     */
+    abstract getInfo(): PluginApiReturn<PluginProjectInfo>;
+    /** Project settings — snaps and grid. See {@linkcode PluginProjectSettingsApi}. */
+    abstract settings: PluginProjectSettingsApi;
+}
+/**
+ * Project settings — tolerance, snaps, and grid.
+ *
+ * Accessed via `snaptrude.core.project.settings`.
+ */
+export declare 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
+     * ```
+     */
+    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")
+     * ```
+     */
+    abstract setTolerance(value: number): PluginApiReturn<boolean>;
+    /** Snap controls (dimension / angle / parallel / normal / magnetic). See {@linkcode PluginSnapsApi}. */
+    abstract snaps: PluginSnapsApi;
+    /** Grid controls. See {@linkcode PluginGridApi}. */
+    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 declare 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()
+     * ```
+     */
+    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)
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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)
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    abstract disableMagnetic(): PluginApiReturn<boolean>;
+}
+/**
+ * Grid controls — the visual snap-to grid.
+ *
+ * Accessed via `snaptrude.core.project.settings.grid`.
+ */
+export declare 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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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)
+     * ```
+     */
+    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 declare const PluginSnapValueArgs: z.ZodObject<{
+    value: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginSnapValueArgs = z.infer<typeof PluginSnapValueArgs>;
+/**
+ * Arguments for {@linkcode PluginGridApi.setValue}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The grid cell value |
+ */
+export declare const PluginGridValueArgs: z.ZodObject<{
+    value: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginToleranceArgs: z.ZodObject<{
+    value: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginProjectInfo: z.ZodObject<{
+    projectId: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    units: z.ZodEnum<{
+        meters: "meters";
+        "feet-inches": "feet-inches";
+        inches: "inches";
+        centimeters: "centimeters";
+        millimeters: "millimeters";
+        kilometers: "kilometers";
+        miles: "miles";
+        babylon: "babylon";
+    }>;
+    activeStorey: z.ZodNumber;
+    storeyCount: z.ZodNumber;
+    location: z.ZodNullable<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProjectInfo = z.infer<typeof PluginProjectInfo>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/project/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/project/index.ts"],"names":[],"mappings":"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"}