@snaptrude/plugin-core 0.9.5 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,17 +16,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "check-types": "tsc --noEmit",
-    "build": "tsup --clean",
-    "dev": "tsup --watch",
-    "clean-dist": "rm -rf dist",
-    "test": "node --test test/*.test.mjs",
-    "generate:manifest": "node scripts/generate-manifest.mjs",
-    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
-    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
-    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
-  },
   "devDependencies": {
     "ts-morph": "^28.0.0",
     "tsup": "^8.5.1",
@@ -37,5 +26,16 @@
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "build": "tsup --clean",
+    "dev": "tsup --watch",
+    "clean-dist": "rm -rf dist",
+    "test": "node --test test/*.test.mjs",
+    "generate:manifest": "node scripts/generate-manifest.mjs",
+    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
+    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
+    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
   }
-}
+}

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

@@ -62,6 +62,23 @@ export abstract class PluginCameraApi {
     view: PluginStandardView,
   ): PluginApiReturn<boolean>
 
+  /**
+   * Get the current camera mode. Paired with {@linkcode PluginCameraApi.setMode}.
+   *
+   * @returns `"2d"` when the editor is in plan view, `"3d"` otherwise.
+   *
+   * @examplePrompt Am I in 2D or 3D?
+   * @examplePrompt What view mode is the editor in?
+   *
+   * # Example
+   * ```ts
+   * if ((await snaptrude.core.camera.getMode()) === "2d") {
+   *   await snaptrude.core.camera.setMode("3d")
+   * }
+   * ```
+   */
+  public abstract getMode(): PluginApiReturn<PluginCameraMode>
+
   /**
    * Toggle the modelling mode between `2d` (plan) and `3d`. Mirrors the canvas
    * 2D/3D toggle: `3d` enters the isometric perspective view, `2d` drops to the

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>

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

@@ -160,6 +160,21 @@ export abstract class PluginCoreStoreysApi {
     options?: { name?: string },
   ): PluginApiReturn<PluginStoryUpdateResult>
 
+  /**
+   * Get the active storey's value. Paired with {@linkcode PluginCoreStoreysApi.setActive}.
+   *
+   * @returns The active storey value, in the same numbering `list` and `get` use.
+   *
+   * @examplePrompt Which storey am I on?
+   * @examplePrompt What is the current storey?
+   *
+   * # Example
+   * ```ts
+   * const storey = await snaptrude.core.storeys.getActive()
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<number>
+
   /**
    * Make a storey the active storey — the same as clicking it in the storey/layer
    * panel. Subsequent draws and creates target this storey, and in 2D the

package/src/api/design/furniture/index.ts

@@ -2,6 +2,7 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
+import { PluginObjectCatalogGroup } from "../doors"
 
 /**
  * `snaptrude.design.furniture` — the placeable furniture **catalog** (a library of
@@ -92,9 +93,42 @@ export abstract class PluginDesignFurnitureApi {
    * const items = await snaptrude.design.furniture.listCatalog(undefined, first)
    * console.log(first, "→", items.length, "items")
    * ```
+   *
+   * @deprecated Use `design.furniture.listCatalogGroups` — the same name
+   * `design.doors` and `design.windows` use. Still supported.
    */
   public abstract listCategories(): PluginApiReturn<string[]>
 
+  /**
+   * List the furniture catalog's groups. Matches
+   * {@linkcode PluginDesignDoorsApi.listCatalogGroups} and
+   * {@linkcode PluginDesignWindowsApi.listCatalogGroups}, so all three catalog
+   * surfaces are named alike.
+   *
+   * `source` is `"default"` for the built-in picker groups and `"team"` for the
+   * sub-types of THIS project's team library — exactly the split
+   * {@linkcode PluginDesignFurnitureApi.listCatalog}'s `source` filter uses, so
+   * every `"team"` group is guaranteed to match at least one team item here.
+   * For furniture the group token and its label are the same string (the
+   * category), so `dbType === label`; `design.doors`/`design.windows` have a
+   * distinct engine `dbType`.
+   *
+   * @returns The catalog groups as {@linkcode PluginObjectCatalogGroup}`[]`
+   *   (`[]` when empty). Pass a group's `dbType` (=== `label`) to
+   *   {@linkcode PluginDesignFurnitureApi.listCatalog}'s `category` filter to
+   *   list its items.
+   *
+   * @examplePrompt What furniture groups are available?
+   * @examplePrompt List the furniture categories in this project
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.furniture.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
   /**
    * List the placeable furniture catalog (team + general libraries),
    * optionally filtered by library `source` and/or `category`.

package/src/api/design/visibility.ts

@@ -39,6 +39,26 @@ export abstract class PluginDesignVisibilityApi {
     components: ComponentHandle[],
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /**
+   * Reveal specific hidden components — the inverse of
+   * {@linkcode PluginDesignVisibilityApi.hide}. Use
+   * {@linkcode PluginDesignVisibilityApi.showAll} to reveal everything.
+   *
+   * @param components - The components to reveal.
+   * @returns A {@linkcode PluginDesignChangeResult} echoing the components shown.
+   *
+   * @examplePrompt Show these walls again
+   * @examplePrompt Unhide the selected furniture
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.visibility.show([wall])
+   * ```
+   */
+  public abstract show(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
   /**
    * Isolate entities — hide everything else so only the given entities remain
    * visible (the "Isolate" / solo action). Undoable. Reverse it with
@@ -94,6 +114,20 @@ export const PluginDesignVisibilityHideArgs = z.object({
 })
 export type PluginDesignVisibilityHideArgs = z.infer<typeof PluginDesignVisibilityHideArgs>
 
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.show}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to reveal |
+ */
+export const PluginDesignVisibilityShowArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityShowArgs = z.infer<
+  typeof PluginDesignVisibilityShowArgs
+>
+
 /**
  * Arguments for {@linkcode PluginDesignVisibilityApi.isolate}.
  *