@snaptrude/plugin-core 0.9.4 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

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/io/underlay/index.ts

@@ -1,6 +1,10 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../../types"
-import { UnderlayHandle, BBoxComponents } from "../../../../handles"
+import {
+  UnderlayHandle,
+  BBoxComponents,
+  Vec3Components,
+} from "../../../../handles"
 
 /**
  * Underlays — inspect and edit the placed reference planes imported into the
@@ -65,7 +69,65 @@ export abstract class PluginCoreIoUnderlayApi {
    * if (bb) console.log(`width ${bb.max.x - bb.min.x}`)
    * ```
    */
-  public abstract getBounds(underlay: UnderlayHandle): PluginApiReturn<BBoxComponents | null>
+  public abstract getBounds(
+    underlay: UnderlayHandle,
+  ): PluginApiReturn<BBoxComponents | null>
+
+  /**
+   * List the distinct original AutoCAD layer names retained by a placed CAD
+   * underlay. Returns `[]` for non-CAD underlays, legacy imports created before
+   * source-layer retention, missing underlays, or CAD drawings without layer tags.
+   *
+   * @param underlay - The placed CAD underlay to inspect.
+   * @returns the retained AutoCAD layer names in first-appearance order.
+   *
+   * @examplePrompt List the original AutoCAD layers in this imported drawing
+   * @examplePrompt Which CAD layers are available in this underlay?
+   *
+   * # Example
+   * ```ts
+   * const layers = await snaptrude.core.io.underlay.listCadLayers(cad)
+   * console.log(layers)
+   * ```
+   */
+  public abstract listCadLayers(
+    underlay: UnderlayHandle,
+  ): PluginApiReturn<string[]>
+
+  /**
+   * Read one original AutoCAD layer's retained line and arc geometry in
+   * **Snaptrude world space** and Snaptrude internal units. Results are paged so
+   * large drawings can be inspected without returning the whole DWG at once.
+   *
+   * The world-space coordinates include the CAD underlay's current position,
+   * rotation, scale, and storey elevation. `null` means the underlay no longer
+   * resolves. An unknown layer returns a page with `total: 0`.
+   *
+   * @param underlay - The placed CAD underlay to inspect.
+   * @param layer - Exact, case-sensitive original AutoCAD layer name.
+   * @param options - Optional zero-based offset and page limit (default 500,
+   *   maximum 1000).
+   * @returns a page of retained CAD curves, or `null` if the underlay is gone.
+   * @throws if the handle resolves to an image/PDF rather than a CAD underlay.
+   *
+   * @examplePrompt Read the wall geometry from the A-WALL layer in this CAD underlay
+   * @examplePrompt Get the next 500 curves from the structural CAD layer
+   *
+   * # Example
+   * ```ts
+   * const page = await snaptrude.core.io.underlay.getCadLayerGeometry(
+   *   cad,
+   *   "A-WALL",
+   *   { offset: 0, limit: 500 },
+   * )
+   * if (page) console.log(`${page.curves.length} of ${page.total} curves`)
+   * ```
+   */
+  public abstract getCadLayerGeometry(
+    underlay: UnderlayHandle,
+    layer: string,
+    options?: PluginCadLayerGeometryOptions,
+  ): PluginApiReturn<PluginCadLayerGeometryPage | null>
 
   /**
    * Read an underlay's scale. Works for **image and PDF** underlays. Returns
@@ -158,7 +220,9 @@ export abstract class PluginCoreIoUnderlayApi {
    * await snaptrude.core.io.underlay.resetScale(plan)
    * ```
    */
-  public abstract resetScale(underlay: UnderlayHandle): PluginApiReturn<{ scaleFactor: number }>
+  public abstract resetScale(
+    underlay: UnderlayHandle,
+  ): PluginApiReturn<{ scaleFactor: number }>
 
   /**
    * Read an underlay's opacity (`0`..`1`), or `null` if it has no material.
@@ -175,7 +239,9 @@ export abstract class PluginCoreIoUnderlayApi {
    * const o = await snaptrude.core.io.underlay.getOpacity(plan)
    * ```
    */
-  public abstract getOpacity(underlay: UnderlayHandle): PluginApiReturn<number | null>
+  public abstract getOpacity(
+    underlay: UnderlayHandle,
+  ): PluginApiReturn<number | null>
 
   /**
    * Set an underlay's opacity (`0` = transparent .. `1` = opaque). Undoable.
@@ -197,7 +263,10 @@ export abstract class PluginCoreIoUnderlayApi {
    * await snaptrude.core.io.underlay.setOpacity(plan, 0.3)
    * ```
    */
-  public abstract setOpacity(underlay: UnderlayHandle, opacity: number): PluginApiReturn<void>
+  public abstract setOpacity(
+    underlay: UnderlayHandle,
+    opacity: number,
+  ): PluginApiReturn<void>
 
   /**
    * Delete an underlay from the scene (and its backend record). Applies to image,
@@ -218,6 +287,106 @@ export abstract class PluginCoreIoUnderlayApi {
    * ```
    */
   public abstract delete(underlay: UnderlayHandle): PluginApiReturn<void>
+
+  /**
+   * Extract **continuous wall centrelines** from one retained AutoCAD layer's
+   * double-line wall faces — the deterministic tracing primitive behind
+   * CAD-to-BIM wall conversion. Instead of paging raw curves and re-deriving
+   * the geometry in worker code, this reads the whole layer and runs the vetted
+   * pipeline: cull fragments, dedupe, merge collinear runs into *faces*, pair
+   * parallel faces a wall-thickness apart into centrelines (midline = axis,
+   * separation = thickness), bridge collinear gaps up to
+   * `bridgeOpenings.maxWidth` into ONE continuous centreline while recording
+   * each bridged span as an opening, then snap near-touching endpoints at
+   * junctions.
+   *
+   * CAD drafters interrupt wall faces at every door/window, so raw wall layers
+   * always have gaps; Snaptrude doors/windows must host into a continuous wall.
+   * The returned centrelines are ready for `design.create.walls`, and each
+   * centreline's `openings` records where the CAD had a gap — feed those to the
+   * door/window placement step. `unpaired` faces (no parallel partner at wall
+   * thickness) are evidence, not noise: a run of unpaired perimeter faces
+   * usually means that stretch of facade is glazed, not solid.
+   *
+   * All lengths are in **Snaptrude internal units** (convert from project units
+   * with `core.units.convert`). Coordinates are world-space plan (x, z).
+   *
+   * Thin parallel pairs (glass lines, mullion faces) are the same algorithm at
+   * a smaller separation: pass e.g. `thicknessRange: [0.01, 0.25]` with
+   * `bridgeOpenings: null` to detect glazing runs on a glazing layer.
+   *
+   * @param underlay - The placed CAD underlay to read.
+   * @param layer - Exact, case-sensitive original AutoCAD layer name.
+   * @param options - Tolerances; see {@linkcode PluginCadCenterlineOptions}.
+   * @returns centrelines + unpaired faces + stats, or `null` if the underlay is gone.
+   * @throws if the handle resolves to an image/PDF rather than a CAD underlay.
+   *
+   * @examplePrompt Trace the walls from the a-wall CAD layer
+   * @examplePrompt Convert the AutoCAD wall linework into Snaptrude walls
+   * @examplePrompt Extract wall centrelines with thickness from the imported DWG
+   * @examplePrompt Find the glazing runs on the a-glazing layer
+   *
+   * # Example
+   * ```ts
+   * const [cad] = await snaptrude.core.io.underlay.list()
+   * const r = await snaptrude.core.io.underlay.extractCenterlines(cad, "a-wall")
+   * if (r) {
+   *   const items = r.centerlines.map((c) => ({
+   *     profile: [c.start, c.end],
+   *     thickness: c.thickness,
+   *   }))
+   *   console.log(`${items.length} walls, ${r.unpaired.length} unpaired faces`)
+   * }
+   * ```
+   */
+  public abstract extractCenterlines(
+    underlay: UnderlayHandle,
+    layer: string,
+    options?: PluginCadCenterlineOptions,
+  ): PluginApiReturn<PluginCadCenterlinesResult | null>
+
+  /**
+   * Classify one retained AutoCAD layer's **arcs as door swings** — the
+   * deterministic tracing primitive behind CAD-to-BIM door placement. A door
+   * swing is drawn as a ~90° arc whose radius IS the leaf width and whose
+   * centre IS the hinge point. This filters the layer's arcs by plausible
+   * radius and sweep (rejecting inch-scale fillets, full-circle symbols and
+   * long shallow curves), reads each survivor as a door candidate (hinge, leaf
+   * width, swing direction, hosting wall direction), merges mirrored pairs
+   * sharing a chord line into double doors, and returns a radius histogram —
+   * real drawings use a handful of standard door sizes, so the histogram's
+   * clusters are the drawing's door widths (sanity-check them against the
+   * catalog; distrust arcs in no cluster).
+   *
+   * All lengths are in **Snaptrude internal units**. `rejected` lists filtered
+   * arcs with reasons so nothing is silently dropped.
+   *
+   * @param underlay - The placed CAD underlay to read.
+   * @param layer - Exact, case-sensitive original AutoCAD layer name.
+   * @param options - Gates and binning; see {@linkcode PluginCadArcClassifyOptions}.
+   * @returns door candidates + rejected arcs + histogram, or `null` if the underlay is gone.
+   * @throws if the handle resolves to an image/PDF rather than a CAD underlay.
+   *
+   * @examplePrompt Find the doors on the a-door CAD layer
+   * @examplePrompt Classify the door swing arcs in the imported drawing
+   * @examplePrompt What door sizes does this DWG use?
+   * @examplePrompt Read hinge points and leaf widths from the CAD door layer
+   *
+   * # Example
+   * ```ts
+   * const [cad] = await snaptrude.core.io.underlay.list()
+   * const r = await snaptrude.core.io.underlay.classifyArcs(cad, "a-door")
+   * if (r) {
+   *   console.log(`${r.doors.length} doors; sizes:`,
+   *     r.radiusHistogram.filter((b) => b.count > 1))
+   * }
+   * ```
+   */
+  public abstract classifyArcs(
+    underlay: UnderlayHandle,
+    layer: string,
+    options?: PluginCadArcClassifyOptions,
+  ): PluginApiReturn<PluginCadArcClassifyResult | null>
 }
 
 /**
@@ -251,7 +420,9 @@ export const PluginUnderlaySetScaleValue = z.union([
   z.number().positive(),
   PluginUnderlayPlanSize,
 ])
-export type PluginUnderlaySetScaleValue = z.infer<typeof PluginUnderlaySetScaleValue>
+export type PluginUnderlaySetScaleValue = z.infer<
+  typeof PluginUnderlaySetScaleValue
+>
 
 /**
  * Arguments for {@link PluginCoreIoUnderlayApi.setScale}.
@@ -265,7 +436,9 @@ export const PluginUnderlaySetScaleArgs = z.object({
   underlay: UnderlayHandle,
   scale: PluginUnderlaySetScaleValue,
 })
-export type PluginUnderlaySetScaleArgs = z.infer<typeof PluginUnderlaySetScaleArgs>
+export type PluginUnderlaySetScaleArgs = z.infer<
+  typeof PluginUnderlaySetScaleArgs
+>
 
 /**
  * Arguments for {@link PluginCoreIoUnderlayApi.setOpacity}.
@@ -279,7 +452,9 @@ export const PluginUnderlaySetOpacityArgs = z.object({
   underlay: UnderlayHandle,
   opacity: z.number().min(0).max(1),
 })
-export type PluginUnderlaySetOpacityArgs = z.infer<typeof PluginUnderlaySetOpacityArgs>
+export type PluginUnderlaySetOpacityArgs = z.infer<
+  typeof PluginUnderlaySetOpacityArgs
+>
 
 /**
  * Arguments for the single-underlay methods
@@ -293,3 +468,238 @@ export const PluginUnderlayRefArgs = z.object({
   underlay: UnderlayHandle,
 })
 export type PluginUnderlayRefArgs = z.infer<typeof PluginUnderlayRefArgs>
+
+/** A retained AutoCAD line represented as a world-space read record. */
+export const PluginCadLineGeometry = z.object({
+  type: z.literal("line"),
+  start: Vec3Components,
+  end: Vec3Components,
+})
+export type PluginCadLineGeometry = z.infer<typeof PluginCadLineGeometry>
+
+/** A retained AutoCAD arc represented as a world-space read record. */
+export const PluginCadArcGeometry = z.object({
+  type: z.literal("arc"),
+  centre: Vec3Components,
+  axis: Vec3Components,
+  start: Vec3Components,
+  end: Vec3Components,
+})
+export type PluginCadArcGeometry = z.infer<typeof PluginCadArcGeometry>
+
+/** Line or arc geometry returned by `getCadLayerGeometry`. */
+export const PluginCadGeometry = z.discriminatedUnion("type", [
+  PluginCadLineGeometry,
+  PluginCadArcGeometry,
+])
+export type PluginCadGeometry = z.infer<typeof PluginCadGeometry>
+
+/** Pagination options for `getCadLayerGeometry`. */
+export const PluginCadLayerGeometryOptions = z.object({
+  offset: z.number().int().nonnegative().default(0),
+  limit: z.number().int().positive().max(1000).default(500),
+})
+export type PluginCadLayerGeometryOptions = z.input<
+  typeof PluginCadLayerGeometryOptions
+>
+
+/** Arguments for {@link PluginCoreIoUnderlayApi.getCadLayerGeometry}. */
+export const PluginCadLayerGeometryArgs = z.object({
+  underlay: UnderlayHandle,
+  layer: z.string(),
+  options: PluginCadLayerGeometryOptions.default({ offset: 0, limit: 500 }),
+})
+export type PluginCadLayerGeometryArgs = z.infer<
+  typeof PluginCadLayerGeometryArgs
+>
+
+/** A page of one original AutoCAD layer's geometry in Snaptrude world space. */
+export const PluginCadLayerGeometryPage = z.object({
+  layer: z.string(),
+  coordinateSpace: z.literal("snaptrude-world"),
+  units: z.literal("snaptrude-internal"),
+  total: z.number().int().nonnegative(),
+  offset: z.number().int().nonnegative(),
+  curves: z.array(PluginCadGeometry),
+})
+export type PluginCadLayerGeometryPage = z.infer<
+  typeof PluginCadLayerGeometryPage
+>
+
+
+/** A point in the world-space plan (x, z) projection, Snaptrude internal units. */
+export const PluginPlanPoint = z.object({ x: z.number(), z: z.number() })
+export type PluginPlanPoint = z.infer<typeof PluginPlanPoint>
+
+/**
+ * Options for {@link PluginCoreIoUnderlayApi.extractCenterlines}. All lengths in
+ * Snaptrude internal units.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `thicknessRange` | `[number, number]`? | Plausible wall thickness `[min, max]` (default `[0.3, 1.6]` ≈ 3–16 in) |
+ * | `mergeGap` | `number`? | Noise tolerance joining collinear segments that are really one face (default `0.05`) |
+ * | `minLength` | `number`? | Cull fragments shorter than this (default `0.1`) |
+ * | `parallelTolDeg` | `number`? | Max angle in degrees between faces still considered parallel (default `2`) |
+ * | `minOverlap` | `number`? | Fraction of the shorter face that must overlap its pair (default `0.6`) |
+ * | `bridgeOpenings` | `{ maxWidth }` \| `null`? | Close collinear centreline gaps up to `maxWidth`, recording each as an opening (default `{ maxWidth: 9.6 }` ≈ 8 ft); `null` disables bridging |
+ */
+export const PluginCadCenterlineOptions = z.object({
+  thicknessRange: z
+    .tuple([z.number().positive(), z.number().positive()])
+    .default([0.3, 1.6]),
+  mergeGap: z.number().nonnegative().default(0.05),
+  minLength: z.number().nonnegative().default(0.1),
+  parallelTolDeg: z.number().positive().max(15).default(2),
+  minOverlap: z.number().min(0).max(1).default(0.6),
+  bridgeOpenings: z
+    .object({ maxWidth: z.number().positive() })
+    .nullable()
+    .default({ maxWidth: 9.6 }),
+})
+export type PluginCadCenterlineOptions = z.input<
+  typeof PluginCadCenterlineOptions
+>
+
+/** Arguments for {@link PluginCoreIoUnderlayApi.extractCenterlines}. */
+export const PluginCadCenterlinesArgs = z.object({
+  underlay: UnderlayHandle,
+  layer: z.string(),
+  options: PluginCadCenterlineOptions.default({
+    thicknessRange: [0.3, 1.6],
+    mergeGap: 0.05,
+    minLength: 0.1,
+    parallelTolDeg: 2,
+    minOverlap: 0.6,
+    bridgeOpenings: { maxWidth: 9.6 },
+  }),
+})
+export type PluginCadCenterlinesArgs = z.infer<typeof PluginCadCenterlinesArgs>
+
+/** A span bridged over a CAD gap in a continuous centreline — a door/window opening candidate. */
+export const PluginCadOpening = z.object({
+  start: PluginPlanPoint,
+  end: PluginPlanPoint,
+  width: z.number(),
+})
+export type PluginCadOpening = z.infer<typeof PluginCadOpening>
+
+/**
+ * One continuous wall centreline extracted from CAD wall faces. `thickness` is
+ * the measured face separation; `openings` are the CAD gaps bridged into this
+ * centreline (feed the door/window step).
+ */
+export const PluginCadCenterline = z.object({
+  start: PluginPlanPoint,
+  end: PluginPlanPoint,
+  thickness: z.number(),
+  length: z.number(),
+  sourceFaceCount: z.number().int().nonnegative(),
+  openings: z.array(PluginCadOpening),
+})
+export type PluginCadCenterline = z.infer<typeof PluginCadCenterline>
+
+/** A merged face with no parallel partner at wall thickness — evidence (often glazing), not noise. */
+export const PluginCadUnpairedFace = z.object({
+  start: PluginPlanPoint,
+  end: PluginPlanPoint,
+  length: z.number(),
+})
+export type PluginCadUnpairedFace = z.infer<typeof PluginCadUnpairedFace>
+
+/** Result of {@link PluginCoreIoUnderlayApi.extractCenterlines}. */
+export const PluginCadCenterlinesResult = z.object({
+  layer: z.string(),
+  coordinateSpace: z.literal("snaptrude-world"),
+  units: z.literal("snaptrude-internal"),
+  centerlines: z.array(PluginCadCenterline),
+  unpaired: z.array(PluginCadUnpairedFace),
+  stats: z.object({
+    curvesRead: z.number().int().nonnegative(),
+    arcsSkipped: z.number().int().nonnegative(),
+    fragmentsCulled: z.number().int().nonnegative(),
+    duplicates: z.number().int().nonnegative(),
+    faces: z.number().int().nonnegative(),
+  }),
+})
+export type PluginCadCenterlinesResult = z.infer<
+  typeof PluginCadCenterlinesResult
+>
+
+/**
+ * Options for {@link PluginCoreIoUnderlayApi.classifyArcs}. Lengths in Snaptrude
+ * internal units, sweeps in degrees.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `radiusRange` | `[number, number]`? | Plausible door-leaf widths (default `[3, 5.4]` ≈ 2.5–4.5 ft) |
+ * | `sweepRangeDeg` | `[number, number]`? | Accepted arc sweep in degrees (default `[60, 120]`; a swing is ~90°) |
+ * | `clusterTol` | `number`? | Radius bin size for the histogram (default `0.1`) |
+ */
+export const PluginCadArcClassifyOptions = z.object({
+  radiusRange: z
+    .tuple([z.number().positive(), z.number().positive()])
+    .default([3, 5.4]),
+  sweepRangeDeg: z
+    .tuple([z.number().positive(), z.number().positive()])
+    .default([60, 120]),
+  clusterTol: z.number().positive().default(0.1),
+})
+export type PluginCadArcClassifyOptions = z.input<
+  typeof PluginCadArcClassifyOptions
+>
+
+/** Arguments for {@link PluginCoreIoUnderlayApi.classifyArcs}. */
+export const PluginCadArcClassifyArgs = z.object({
+  underlay: UnderlayHandle,
+  layer: z.string(),
+  options: PluginCadArcClassifyOptions.default({
+    radiusRange: [3, 5.4],
+    sweepRangeDeg: [60, 120],
+    clusterTol: 0.1,
+  }),
+})
+export type PluginCadArcClassifyArgs = z.infer<typeof PluginCadArcClassifyArgs>
+
+/**
+ * One door candidate read from a CAD swing arc. `hinge` is the arc centre,
+ * `leafWidth` the arc radius, `swingDir` the unit direction from hinge toward
+ * the open leaf, `wallDir` the unit direction of the hosting wall (hinge →
+ * closed-leaf chord end). `openingWidth` equals `leafWidth` for singles and
+ * `2 × leafWidth` for doubles.
+ */
+export const PluginCadDoorCandidate = z.object({
+  hinge: PluginPlanPoint,
+  leafWidth: z.number(),
+  swingDir: PluginPlanPoint,
+  wallDir: PluginPlanPoint,
+  openingWidth: z.number(),
+  double: z.boolean(),
+})
+export type PluginCadDoorCandidate = z.infer<typeof PluginCadDoorCandidate>
+
+/** Result of {@link PluginCoreIoUnderlayApi.classifyArcs}. */
+export const PluginCadArcClassifyResult = z.object({
+  layer: z.string(),
+  coordinateSpace: z.literal("snaptrude-world"),
+  units: z.literal("snaptrude-internal"),
+  doors: z.array(PluginCadDoorCandidate),
+  rejected: z.array(
+    z.object({
+      centre: PluginPlanPoint,
+      radius: z.number(),
+      sweepDeg: z.number(),
+      reason: z.string(),
+    }),
+  ),
+  radiusHistogram: z.array(
+    z.object({ radius: z.number(), count: z.number().int().positive() }),
+  ),
+  stats: z.object({
+    curvesRead: z.number().int().nonnegative(),
+    arcsConsidered: z.number().int().nonnegative(),
+  }),
+})
+export type PluginCadArcClassifyResult = z.infer<
+  typeof PluginCadArcClassifyResult
+>

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`.