@snaptrude/plugin-core 0.3.0 → 0.5.0

package/src/api/design/query/spaces.ts

@@ -0,0 +1,132 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, ContourHandle } from "../../../handles"
+import { PluginSpaceGetProperty, PluginSpaceGetResult } from "../../entity/space"
+
+/**
+ * `design.query.spaces.*` — space-specific reads (a space is a room mass).
+ *
+ * Only the space queries feasible against the engine today are exposed here.
+ * `getFloor` / `listBoundingWalls` (space↔wall topology) are deferred — they need
+ * engine work that does not exist yet. `listAdjacent` stays deferred because the
+ * shipped surfaces already answer it with value semantics: per-space via the
+ * `adjacency` field of `design.query.getProperties`, in bulk via
+ * `program.adjacency.getMatrix`.
+ *
+ * Accessed via `snaptrude.design.query.spaces`.
+ */
+export abstract class PluginDesignQuerySpacesApi {
+  constructor() {}
+
+  /**
+   * Get selected properties of a space — the selective multi-property read.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result. This is the canonical home of
+   * the read formerly at `entity.space.get` (now deprecated). Adjacency is not
+   * part of this read — it is an entity property: read it via the `adjacency`
+   * field of {@linkcode PluginDesignQueryApi.getProperties}.
+   *
+   * @param space - The space (room mass) to read
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginDesignQuerySpacesGetProperty} for available values.
+   * @returns A partial {@linkcode PluginDesignQuerySpacesGetResult} containing only
+   *   the requested properties
+   * @throws If the space does not exist or the component is not a space/mass
+   *
+   * @examplePrompt What is the area of this room?
+   * @examplePrompt Get the name, storey and height of the selected space
+   * @examplePrompt Which department does this room belong to?
+   * @examplePrompt Where is this space positioned on the plan?
+   * @examplePrompt Read the room type and dimensions of the selected room
+   *
+   * # Example
+   * ```ts
+   * const [space] = await snaptrude.design.query.listSpaces()
+   * const info = await snaptrude.design.query.spaces.get(space, ["name", "area", "position"])
+   * console.log(info.name, info.area, info.position)
+   * ```
+   */
+  public abstract get(
+    space: ComponentHandle,
+    properties: PluginDesignQuerySpacesGetArgs["properties"],
+  ): PluginApiReturn<PluginDesignQuerySpacesGetResult>
+
+  /**
+   * Get the **footprint** of a space — its bottom-face contour (outer profile +
+   * holes) as a reusable {@linkcode ContourHandle}. Equivalent to
+   * {@linkcode PluginDesignQueryGeometryApi.getBottomContour} narrowed to spaces.
+   *
+   * @param space - The space (room mass) to read
+   * @returns the footprint {@linkcode ContourHandle}, or `null` if the space has
+   *   no extractable footprint
+   *
+   * @examplePrompt Get the footprint of this room
+   * @examplePrompt Trace the floor outline of the selected space
+   * @examplePrompt What is the plan boundary of this room, including any holes?
+   * @examplePrompt Give me the base profile of the selected room mass
+   *
+   * # Example
+   * ```ts
+   * const [space] = await snaptrude.design.query.listSpaces()
+   * const footprint = await snaptrude.design.query.spaces.getFootprint(space)
+   * ```
+   */
+  public abstract getFootprint(
+    space: ComponentHandle,
+  ): PluginApiReturn<ContourHandle | null>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.getFootprint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ */
+export const PluginDesignQueryGetFootprintArgs = z.object({
+  space: ComponentHandle,
+})
+export type PluginDesignQueryGetFootprintArgs = z.infer<
+  typeof PluginDesignQueryGetFootprintArgs
+>
+
+/**
+ * Property names readable via {@linkcode PluginDesignQuerySpacesApi.get} — the
+ * legacy {@linkcode PluginSpaceGetProperty} set minus `"adjacency"` (adjacency is
+ * an entity property: see the `adjacency` field of
+ * {@linkcode PluginDesignQueryApi.getProperties}).
+ */
+export const PluginDesignQuerySpacesGetProperty =
+  PluginSpaceGetProperty.exclude(["adjacency"])
+export type PluginDesignQuerySpacesGetProperty = z.infer<
+  typeof PluginDesignQuerySpacesGetProperty
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ * | `properties` | {@linkcode PluginDesignQuerySpacesGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginDesignQuerySpacesGetArgs = z.object({
+  space: ComponentHandle,
+  properties: z.array(PluginDesignQuerySpacesGetProperty),
+})
+export type PluginDesignQuerySpacesGetArgs = z.infer<
+  typeof PluginDesignQuerySpacesGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginDesignQuerySpacesApi.get} — the legacy
+ * {@linkcode PluginSpaceGetResult} record minus `adjacency`. Partial: only the
+ * requested properties are present.
+ */
+export const PluginDesignQuerySpacesGetResult = PluginSpaceGetResult.omit({
+  adjacency: true,
+})
+export type PluginDesignQuerySpacesGetResult = z.infer<
+  typeof PluginDesignQuerySpacesGetResult
+>

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

@@ -0,0 +1,144 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * `snaptrude.design.selection` — read and mutate the current scene selection.
+ *
+ * Selection targets are {@linkcode ComponentHandle}s. `get` is the one sanctioned
+ * `get`-returns-array accessor (§4.1(3)). The mutators (`set`/`add`/`remove`/`clear`)
+ * change the live selection and return the resulting selection snapshot — they are
+ * **not undoable** (the engine fires a selection listener, no command), so the
+ * returned {@linkcode PluginDesignChangeResult} is a committed-state snapshot.
+ */
+export abstract class PluginDesignSelectionApi {
+  constructor() {}
+
+  /**
+   * Read the current scene selection — the entities the user (or a previous
+   * call) has selected, returned as handles you can pass straight into other
+   * API calls.
+   *
+   * @returns The selection as {@linkcode ComponentHandle}`[]` (`[]` when nothing is selected)
+   *
+   * @examplePrompt What do I have selected right now?
+   * @examplePrompt List the currently selected objects
+   * @examplePrompt Which rooms are selected in the scene?
+   * @examplePrompt Get the ids of everything I've selected
+   * @examplePrompt Is anything selected?
+   *
+   * # Example
+   * ```ts
+   * // Selection handles feed straight into other API calls
+   * const selection = await snaptrude.design.selection.get()
+   * if (selection.length > 0) {
+   *   const props = await snaptrude.design.query.getProperties(selection[0])
+   * }
+   * ```
+   */
+  public abstract get(): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Replace the selection with exactly the given entities — anything
+   * previously selected is deselected first, so afterwards only these
+   * entities are selected.
+   *
+   * @param components The entities to select
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Select these three walls
+   * @examplePrompt Select only the kitchen and deselect everything else
+   * @examplePrompt Change the selection to just these rooms
+   * @examplePrompt Highlight the spaces on the second storey
+   *
+   * # Example
+   * ```ts
+   * // Select only the ground-storey walls (replaces the previous selection)
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * const { affected } = await snaptrude.design.selection.set(walls)
+   * ```
+   */
+  public abstract set(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Add entities to the current selection without deselecting anything — the
+   * selection grows to include the given entities alongside whatever was
+   * already selected.
+   *
+   * @param components The entities to add to the selection
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Add the corridor to my current selection
+   * @examplePrompt Select these columns too, keeping what's already selected
+   * @examplePrompt Also select the roof
+   * @examplePrompt Extend the selection to include all the doors on this floor
+   *
+   * # Example
+   * ```ts
+   * // Grow the selection to include every roof, keeping what's already selected
+   * const roofs = await snaptrude.design.query.listRoofs()
+   * await snaptrude.design.selection.add(roofs)
+   * ```
+   */
+  public abstract add(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Remove entities from the current selection — the given entities are
+   * deselected while everything else stays selected.
+   *
+   * @param components The entities to remove from the selection
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Deselect the stair core but keep the rest selected
+   * @examplePrompt Remove these walls from my selection
+   * @examplePrompt Take the furniture out of the current selection
+   * @examplePrompt Unselect the two smaller rooms
+   *
+   * # Example
+   * ```ts
+   * // Deselect the furniture while keeping everything else selected
+   * const furniture = await snaptrude.design.query.listFurniture({ isSelected: true })
+   * await snaptrude.design.selection.remove(furniture)
+   * ```
+   */
+  public abstract remove(
+    components: ComponentHandle[]
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Clear the selection so nothing is selected (equivalent to `set([])`).
+   *
+   * @returns The resulting (empty) selection snapshot
+   *
+   * @examplePrompt Deselect everything
+   * @examplePrompt Clear my current selection
+   * @examplePrompt Unselect all objects in the scene
+   * @examplePrompt Make sure nothing is selected before we start
+   *
+   * # Example
+   * ```ts
+   * const { affected } = await snaptrude.design.selection.clear()
+   * // affected is the resulting selection — always [] here
+   * ```
+   */
+  public abstract clear(): PluginApiReturn<PluginDesignChangeResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignSelectionApi.set}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The entities to select |
+ */
+export const PluginDesignSelectionSetArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignSelectionSetArgs = z.infer<typeof PluginDesignSelectionSetArgs>
+
+export const PluginDesignSelectionAddArgs = PluginDesignSelectionSetArgs
+export type PluginDesignSelectionAddArgs = z.infer<typeof PluginDesignSelectionAddArgs>
+
+export const PluginDesignSelectionRemoveArgs = PluginDesignSelectionSetArgs
+export type PluginDesignSelectionRemoveArgs = z.infer<typeof PluginDesignSelectionRemoveArgs>

package/src/api/design/shared.ts

@@ -0,0 +1,40 @@
+import * as z from "zod"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Shared `design.*` operation return records (LLD Part A.3).
+ *
+ * `PluginDesignChangeResult` (`{ affected }`) is NOT here — it already lives in
+ * `./lock` and is reused verbatim by the transform/delete mutators.
+ *
+ * NOTE: `PluginMirrorAxis` currently lives in `./doors`; its relocation into this
+ * shared module is deferred to the transform wave (avoids a doors edit + a
+ * double-export while `design.transform` is unwired).
+ */
+
+/**
+ * Result of a CSG boolean op (`design.boolean.union/subtract/intersect`). Grounded
+ * in the engine `Boolean3dOperation.resultComponents { toCreate; toDelete }`:
+ * `created` are the result masses, `deleted` is every consumed input (for
+ * `subtract` this includes BOTH the target AND the tools). Errors throw (RPC
+ * rejects); no `Result<>` crosses the boundary.
+ */
+export const BooleanOutcome = z.object({
+  created: z.array(ComponentHandle),
+  deleted: z.array(ComponentHandle),
+})
+export type BooleanOutcome = z.infer<typeof BooleanOutcome>
+
+/**
+ * Result of `design.edit.offsetSplit` (migrated from `tools.offset`). `createdIds`
+ * are the components the offset produced; `deletedIds` are those a split-style
+ * offset removed. `offsetValue` is the engine's POST-clamp / post-sign applied
+ * distance — the only way a caller learns the actually-applied clamped distance
+ * (the shipped `tools.offset` result dropped it).
+ */
+export const OffsetSplitOutcome = z.object({
+  createdIds: z.array(ComponentHandle),
+  deletedIds: z.array(ComponentHandle),
+  offsetValue: z.number(),
+})
+export type OffsetSplitOutcome = z.infer<typeof OffsetSplitOutcome>

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

@@ -0,0 +1,93 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * `snaptrude.design.transform` — rigid transforms on scene entities.
+ *
+ * Migrated from the removed `tools.transform.*`. All ops are undoable and return
+ * {@linkcode PluginDesignChangeResult} `{ affected }`; failures throw (RPC rejects).
+ *
+ * `mirror` / `getPosition` / `setPosition` (and `scale`, an engine gap) are NOT in
+ * this surface yet — they are a later, non-migration pass.
+ */
+export abstract class PluginDesignTransformApi {
+  constructor() {}
+
+  /**
+   * Translate entities by a **relative** displacement vector (added to the first
+   * component's absolute position as the anchor). Undoable.
+   *
+   * @param components - Entities to move
+   * @param displacement - Relative translation as a {@linkcode Vec3Handle}
+   * @param options - `is2D`, `trackParentChange`
+   * @returns {@linkcode PluginDesignChangeResult}
+   *
+   * @examplePrompt Move the selected room 5 metres to the right
+   * @examplePrompt Shift these walls 3m along the x axis
+   * @examplePrompt Nudge this space 500mm north
+   * @examplePrompt Translate the furniture block by (10, 0, 5)
+   * @examplePrompt Move these masses up one storey
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   * await snaptrude.design.transform.move(["space-id"], vec3.new(10, 0, 0))
+   * ```
+   */
+  public abstract move(
+    components: ComponentHandle[],
+    displacement: Vec3Handle,
+    options?: { is2D?: boolean; trackParentChange?: boolean },
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Rotate entities by a **signed angle in DEGREES**, anchored at the combined
+   * bounding-box centre (positive = CCW about +Y). NOTE: unlike the removed
+   * `tools.transform.rotate` (radians + caller pivot), this canonical form takes
+   * DEGREES and has NO caller pivot — the pivot is always the bbox centre. Undoable.
+   *
+   * @param components - Entities to rotate
+   * @param angleInDegrees - Signed rotation angle in degrees
+   * @param options - `axis` (defaults to world +Y), `is2D`
+   * @returns {@linkcode PluginDesignChangeResult}
+   *
+   * @examplePrompt Rotate the selected building 90 degrees
+   * @examplePrompt Turn this room 45 degrees clockwise
+   * @examplePrompt Spin the furniture block 180 degrees about its centre
+   * @examplePrompt Rotate these masses 30 degrees around the vertical axis
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.transform.rotate(["space-id"], 90)
+   * ```
+   */
+  public abstract rotate(
+    components: ComponentHandle[],
+    angleInDegrees: number,
+    options?: { axis?: Vec3Handle; is2D?: boolean },
+  ): PluginApiReturn<PluginDesignChangeResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignTransformApi.move} (options flattened).
+ */
+export const PluginDesignMoveArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  displacement: Vec3Handle,
+  is2D: z.boolean().optional(),
+  trackParentChange: z.boolean().optional(),
+})
+export type PluginDesignMoveArgs = z.infer<typeof PluginDesignMoveArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignTransformApi.rotate} (options flattened).
+ */
+export const PluginDesignRotateArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  angleInDegrees: z.number(),
+  axis: Vec3Handle.optional(),
+  is2D: z.boolean().optional(),
+})
+export type PluginDesignRotateArgs = z.infer<typeof PluginDesignRotateArgs>

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

@@ -0,0 +1,117 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, ProfileHandle } from "../../../handles"
+import {
+  PluginSpaceType,
+  PluginMassType,
+  PluginDepartmentId,
+  PluginAreaClass,
+  PluginSpaceUpdateResult,
+} from "../../entity/space"
+
+/**
+ * Sparse property updates for a space. Only provided fields change.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `room_type` | `string`? | Room label |
+ * | `massType` | `PluginMassType`? | Mass type |
+ * | `spaceType` | `PluginSpaceType`? | Space type |
+ * | `areaClass` | `PluginAreaClass`? | Area class (NET/GROSS/EXCLUDED) |
+ * | `departmentId` | `PluginDepartmentId`? | Department |
+ */
+export const PluginSpacePropertyUpdates = z.object({
+  room_type: z.string().optional(),
+  massType: PluginMassType.optional(),
+  spaceType: PluginSpaceType.optional(),
+  areaClass: PluginAreaClass.optional(),
+  departmentId: PluginDepartmentId.optional(),
+})
+export type PluginSpacePropertyUpdates = z.infer<typeof PluginSpacePropertyUpdates>
+
+/** Geometry replacement for a space — re-extrude a profile. */
+export const PluginSpaceGeometryUpdate = z.object({
+  profile: ProfileHandle,
+  extrudeHeight: z.number(),
+})
+export type PluginSpaceGeometryUpdate = z.infer<typeof PluginSpaceGeometryUpdate>
+
+/** One space to update via {@linkcode PluginDesignUpdateApi.spaces}. */
+export const PluginUpdateSpaceItem = z.object({
+  space: ComponentHandle,
+  properties: PluginSpacePropertyUpdates.optional(),
+  geometry: PluginSpaceGeometryUpdate.optional(),
+})
+export type PluginUpdateSpaceItem = z.infer<typeof PluginUpdateSpaceItem>
+
+/**
+ * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
+ *
+ * Migrated from the removed `entity.space.{update, updateGeometryFromProfile, bulkUpdate}`.
+ * Only provided fields change; each call is undoable. Failures throw (RPC rejects).
+ */
+export abstract class PluginDesignUpdateApi {
+  constructor() {}
+
+  /**
+   * Update a single space (room) — change its properties (room label, space
+   * type, mass type, area class, department) and/or replace its geometry by
+   * re-extruding a profile to a new height. Sparse and undoable: only the
+   * fields you provide change.
+   *
+   * @param space - The space to update
+   * @param options - `properties` (sparse) and/or `geometry` ({ profile, extrudeHeight })
+   * @returns the updated space's echoed {@linkcode PluginSpaceUpdateResult}
+   *
+   * @examplePrompt Rename this room to Office
+   * @examplePrompt Change this space's room type to Meeting Room
+   * @examplePrompt Set the height of this room to 3 metres
+   * @examplePrompt Move this space into the Circulation department
+   * @examplePrompt Exclude this room from the area calculations
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.update.space("space-id", { properties: { room_type: "Office" } })
+   * ```
+   */
+  public abstract space(
+    space: ComponentHandle,
+    options: {
+      properties?: PluginSpacePropertyUpdates
+      geometry?: PluginSpaceGeometryUpdate
+    },
+  ): PluginApiReturn<PluginSpaceUpdateResult>
+
+  /**
+   * Update many spaces (rooms) in one undoable operation — the bulk form of
+   * {@linkcode space}. Each item pairs a space with the sparse property
+   * changes and/or geometry re-extrude to apply; every item is validated up
+   * front, then all changes are applied as a single command.
+   *
+   * Migrated from `entity.space.bulkUpdate`.
+   *
+   * @param items - One {@linkcode PluginUpdateSpaceItem} per space
+   * @returns one {@linkcode PluginSpaceUpdateResult} per item, in input order
+   *
+   * @examplePrompt Label all the selected rooms as Bedrooms
+   * @examplePrompt Change the room type of these five spaces at once
+   * @examplePrompt Set every room on this floor to a 3m height in one go
+   * @examplePrompt Bulk-assign these spaces to the Service department
+   * @examplePrompt Mark all of these rooms as excluded from area in one update
+   *
+   * # Example
+   * ```ts
+   * // Re-label every selected room and mark it NET area — one undoable bulk update
+   * const rooms = await snaptrude.design.query.listSpaces({ isSelected: true })
+   * const results = await snaptrude.design.update.spaces(
+   *   rooms.map((space) => ({
+   *     space,
+   *     properties: { room_type: "Bedroom", areaClass: "NET" },
+   *   })),
+   * )
+   * // One result per item, in input order
+   * console.log(results.map((r) => r.spaceId))
+   * ```
+   */
+  public abstract spaces(items: PluginUpdateSpaceItem[]): PluginApiReturn<PluginSpaceUpdateResult[]>
+}