@snaptrude/plugin-core 0.5.0 → 0.6.0

package/src/api/index.ts

@@ -3,6 +3,7 @@ import { PluginDesignApi } from "./design"
 import { PluginEntityApi } from "./entity"
 import { PluginProgramApi } from "./program"
 import { PluginPresentationApi } from "./presentation"
+import { PluginAnalysisApi } from "./analysis"
 
 /**
  * Root API surface for Snaptrude plugins.
@@ -14,6 +15,7 @@ import { PluginPresentationApi } from "./presentation"
  * - {@linkcode PluginApi.entity} — CRUD operations on Snaptrude entities (spaces, stories)
  * - {@linkcode PluginApi.program} — Program-mode planning reads (departments, metrics)
  * - {@linkcode PluginApi.presentation} — Presentation preparation (views, AI Inspiration)
+ * - {@linkcode PluginApi.analysis} — Sustainability analysis (sunpath, shadows, sunlight/illuminance heatmaps)
  */
 export abstract class PluginApi {
   /** Core math, geometry, history, and units primitives. See {@linkcode PluginCoreApi}. */
@@ -26,6 +28,8 @@ export abstract class PluginApi {
   public abstract program: PluginProgramApi
   /** Presentation preparation reads — saved views. See {@linkcode PluginPresentationApi}. */
   public abstract presentation: PluginPresentationApi
+  /** Sustainability analysis — sun & daylight studies. See {@linkcode PluginAnalysisApi}. */
+  public abstract analysis: PluginAnalysisApi
 
   constructor() {}
 }
@@ -35,3 +39,4 @@ export * from "./design"
 export * from "./entity"
 export * from "./program"
 export * from "./presentation"
+export * from "./analysis"

package/src/api/program/site.ts

@@ -127,6 +127,63 @@ export abstract class PluginProgramSiteApi {
    * ```
    */
   public abstract getContext(): PluginApiReturn<PluginProgramSiteContextResult>
+
+  /**
+   * Get the project's geographic location.
+   *
+   * The latitude/longitude the site is geo-located at — the location the
+   * `analysis.*` sun and daylight studies compute against. Returns `null`
+   * when the project is not geo-located on terrain (there is no fallback
+   * location).
+   *
+   * Note the spelling: this result uses the full `{ latitude, longitude }`
+   * keys, while the older site reads
+   * ({@linkcode PluginProgramSiteApi.getContext},
+   * {@linkcode PluginProgramSiteApi.listGeoPolygons}) use the abbreviated
+   * `{ lat, lng }`.
+   *
+   * @returns A {@linkcode PluginProgramSiteLocationResult} —
+   *   `{ latitude, longitude }`, or `null` when the project has no
+   *   geo-located site.
+   *
+   * @examplePrompt What's the project's latitude and longitude?
+   * @examplePrompt Where is this site located?
+   * @examplePrompt Get the geographic coordinates of the project
+   *
+   * # Example
+   * ```ts
+   * const location = await snaptrude.program.site.getLocation()
+   * if (location) console.log(location.latitude, location.longitude)
+   * ```
+   */
+  public abstract getLocation(): PluginApiReturn<PluginProgramSiteLocationResult>
+
+  /**
+   * Get the site's true-north angle.
+   *
+   * The angle in degrees the model's north (the scene's +Z axis) is rotated
+   * from true north, derived from the terrain's rotation. `0` means the
+   * model is aligned to true north. Reported in `[0, 360)`,
+   * **clockwise-positive** viewed from above (Babylon's +Y rotation sign) —
+   * note this is the opposite sign convention to `design.transform.rotate`,
+   * where positive = CCW. Returns `null` when the project is not
+   * geo-located on terrain.
+   *
+   * @returns A {@linkcode PluginProgramSiteNorthAngleResult} — the angle in
+   *   degrees (`[0, 360)`, clockwise-positive), or `null` when the project
+   *   has no geo-located site.
+   *
+   * @examplePrompt What's the north angle of the site?
+   * @examplePrompt How far is the model rotated from true north?
+   * @examplePrompt Get the project's true north direction
+   *
+   * # Example
+   * ```ts
+   * const northAngle = await snaptrude.program.site.getNorthAngle()
+   * if (northAngle !== null) console.log(`${northAngle}° from true north`)
+   * ```
+   */
+  public abstract getNorthAngle(): PluginApiReturn<PluginProgramSiteNorthAngleResult>
 }
 
 /**
@@ -324,3 +381,39 @@ export const PluginProgramSiteContextResult =
 export type PluginProgramSiteContextResult = z.infer<
   typeof PluginProgramSiteContextResult
 >
+
+/**
+ * The project's geographic location (WGS84).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `latitude` | `number` | Latitude (degrees) |
+ * | `longitude` | `number` | Longitude (degrees) |
+ */
+export const PluginProgramSiteLocation = z.object({
+  latitude: z.number(),
+  longitude: z.number(),
+})
+export type PluginProgramSiteLocation = z.infer<
+  typeof PluginProgramSiteLocation
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getLocation} — the location, or
+ * `null` when the project is not geo-located.
+ */
+export const PluginProgramSiteLocationResult =
+  PluginProgramSiteLocation.nullable()
+export type PluginProgramSiteLocationResult = z.infer<
+  typeof PluginProgramSiteLocationResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getNorthAngle} — the true-north
+ * angle in degrees (`[0, 360)`, clockwise-positive), or `null` when the
+ * project is not geo-located.
+ */
+export const PluginProgramSiteNorthAngleResult = z.number().nullable()
+export type PluginProgramSiteNorthAngleResult = z.infer<
+  typeof PluginProgramSiteNorthAngleResult
+>

package/src/handles.ts

@@ -46,6 +46,34 @@ export type ComponentHandle = EntityId<"component">
  */
 export type MaterialHandle = EntityId<"material">
 
+/**
+ * A placed **scene underlay** — an imported reference plane the user traces over:
+ * an image `FloorPlan`, a `PDF` overlay, or a `CAD` sketch. Entity-style: the token
+ * IS the raw `Component.id` (`fp_…` / a pdf id / `cad_…`). Resolved live host-side
+ * via the import-order layer walk (`collectStoreyImportItems`) — NOT via
+ * `ComponentUtility.FindComponentById`, which does not index underlays. No arena, no
+ * quota, stable across undo/redo. Returned by `core.io.import.{image,pdf,cadJson}`
+ * and consumed by every `core.io.underlay.*` method.
+ */
+export type UnderlayHandle = EntityId<"underlay">
+
+/**
+ * The project's **site terrain** — a Mapbox-derived topography mesh. Entity-style
+ * and a project **singleton** (one terrain per project): the token is the terrain
+ * `Component.id` (`terrain-…`), resolved live via `TerrainOperations.getTerrain()`
+ * (absent from the level component collections, so NOT `FindComponentById`).
+ * Returned by `core.io.import.terrain`.
+ */
+export type TerrainHandle = EntityId<"terrain">
+
+/**
+ * A handle to an **asynchronous import job** (today: a DWG → Forge conversion, which
+ * can take minutes). Returned immediately by `core.io.import.dwg`; poll it via
+ * `core.io.job.*` (`getStatus` / `isComplete` / `getResult` / `getError`). The token
+ * is the engine's import request id; job state lives in a host-side registry.
+ */
+export type ImportJobHandle = EntityId<"importJob">
+
 // ── Value-kind handles (all-handle model, §11) ──────────────────────────────
 // Under the all-handle decision every structured type is a handle. The only
 // non-handles crossing the boundary are JS primitives (number/string/boolean)
@@ -123,6 +151,24 @@ export const MaterialHandle = z
   .min(1)
   .transform((s) => s as MaterialHandle)
 
+/**
+ * {@linkcode UnderlayHandle} / {@linkcode TerrainHandle} / {@linkcode ImportJobHandle}
+ * are entity-style handles — raw host ids, validated only as a non-empty string
+ * (no `"<kind>_"` prefix), resolved live host-side (existence enforced there).
+ */
+export const UnderlayHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as UnderlayHandle)
+export const TerrainHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as TerrainHandle)
+export const ImportJobHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as ImportJobHandle)
+
 // Value-kind handle schemas (all-handle model, §11).
 export const Vec3Handle = handleSchema("vec3")
 export const QuatHandle = handleSchema("quat")