@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

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

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

@@ -1,15 +1,47 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
+import { PUnitType } from "../units"
 
 /**
  * Project-level settings and info.
  *
- * Accessed via `snaptrude.core.project`. Currently exposes
+ * 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
 }
@@ -416,3 +448,32 @@ export const PluginToleranceArgs = z.object({
 })
 
 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>