@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/src/api/entity/index.ts

@@ -1,30 +1,30 @@
-import { PluginBuildableEnvelopeApi } from "./buildableEnvelope"
-import { PluginReferenceLineApi } from "./referenceLine"
-import { PluginStoryApi } from "./story"
-
-/**
- * CRUD operations on Snaptrude building entities.
- *
- * - {@linkcode PluginEntityApi.story} — Create, query, and update stories (floors)
- * - {@linkcode PluginEntityApi.referenceLine} — Create, query, and delete reference lines
- * - {@linkcode PluginEntityApi.buildableEnvelope} — Create or update parametric buildable envelopes
- *
- * Space operations moved to `design.create.spaces` / `design.update.*` /
- * `design.query.*` / `design.delete.entities` (the `entity.space` API was removed);
- * `./space` still exports the shared space value types.
- */
-export abstract class PluginEntityApi {
-  /** Story (floor/storey) operations. See {@linkcode PluginStoryApi}. */
-  public abstract story: PluginStoryApi
-  /** Reference line operations. See {@linkcode PluginReferenceLineApi}. */
-  public abstract referenceLine: PluginReferenceLineApi
-  /** Buildable Envelope operations. See {@linkcode PluginBuildableEnvelopeApi}. */
-  public abstract buildableEnvelope: PluginBuildableEnvelopeApi
-
-  constructor() {}
-}
-
-export * from "./buildableEnvelope"
-export * from "./referenceLine"
-export * from "./space"
-export * from "./story"
+import { PluginBuildableEnvelopeApi } from "./buildableEnvelope"
+import { PluginReferenceLineApi } from "./referenceLine"
+import { PluginStoryApi } from "./story"
+
+/**
+ * CRUD operations on Snaptrude building entities.
+ *
+ * - {@linkcode PluginEntityApi.story} — Create, query, and update stories (floors)
+ * - {@linkcode PluginEntityApi.referenceLine} — Create, query, and delete reference lines
+ * - {@linkcode PluginEntityApi.buildableEnvelope} — Create or update parametric buildable envelopes
+ *
+ * Space operations moved to `design.create.spaces` / `design.update.*` /
+ * `design.query.*` / `design.delete.entities` (the `entity.space` API was removed);
+ * `./space` still exports the shared space value types.
+ */
+export abstract class PluginEntityApi {
+  /** Story (floor/storey) operations. See {@linkcode PluginStoryApi}. */
+  public abstract story: PluginStoryApi
+  /** Reference line operations. See {@linkcode PluginReferenceLineApi}. */
+  public abstract referenceLine: PluginReferenceLineApi
+  /** Buildable Envelope operations. See {@linkcode PluginBuildableEnvelopeApi}. */
+  public abstract buildableEnvelope: PluginBuildableEnvelopeApi
+
+  constructor() {}
+}
+
+export * from "./buildableEnvelope"
+export * from "./referenceLine"
+export * from "./space"
+export * from "./story"

package/src/api/entity/referenceLine.ts

@@ -1,235 +1,235 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-import { ProfileHandle, CurveHandle } from "../../handles"
-
-/**
- * Reference line management — create, query, and delete reference lines.
- *
- * A **reference line** is a 2D guide line (or arc) in the Snaptrude scene,
- * typically used for grid lines and alignment guides. Reference lines
- * carry properties such as grid tags, labels, and line styles.
- *
- * All methods are **host API calls** that return Promises and support
- * undo/redo via Snaptrude's command system.
- *
- * Accessed via `snaptrude.entity.referenceLine`.
- */
-export abstract class PluginReferenceLineApi {
-  constructor() {}
-
-  /**
-   * Create multiple reference lines from a profile.
-   *
-   * Each curve in the given {@linkcode ProfileHandle} becomes
-   * a separate reference line. Uses `ReferenceLineConstructor.createFromProfile`
-   * internally.
-   *
-   * @param profile - A {@linkcode ProfileHandle} whose curves define the
-   *   reference lines to create
-   * @returns A {@linkcode PluginReferenceLineCreateMultiResult} with the
-   *   `referenceLineIds` of the created reference lines
-   * @throws If reference line creation fails
-   *
-   * @examplePrompt Draw grid lines across the site
-   * @examplePrompt Create reference lines from these curves
-   * @examplePrompt Add alignment guides along the building edge
-   * @examplePrompt Set up a structural grid using guide lines
-   * @examplePrompt Turn this profile into reference lines
-   *
-   * # Example
-   * ```ts
-   * const { vec3 } = snaptrude.core.math
-   *
-   * const start = await vec3.new(0, 0, 0)
-   * const mid = await vec3.new(10, 0, 0)
-   * const end = await vec3.new(10, 0, 10)
-   * const l1 = await snaptrude.core.geom.create.line(start, mid)
-   * const l2 = await snaptrude.core.geom.create.line(mid, end)
-   * const profile = await snaptrude.core.geom.create.profileFromCurves([l1, l2])
-   *
-   * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti(profile)
-   * ```
-   *
-   * @deprecated Use `design.create.referenceLines`
-   */
-  public abstract createMulti(
-    profile: ProfileHandle
-  ): PluginApiReturn<PluginReferenceLineCreateMultiResult>
-
-  /**
-   * Get properties of a reference line by its ID.
-   *
-   * Only the properties listed in `properties` are returned — unlisted
-   * properties will be `undefined` in the result.
-   *
-   * @param referenceLineId - The unique reference line ID
-   * @param properties - Array of property names to retrieve. See
-   *   {@linkcode PluginReferenceLineGetProperty}.
-   * @returns A partial {@linkcode PluginReferenceLineGetResult} containing only the
-   *   requested properties
-   * @throws If the reference line does not exist
-   *
-   * @examplePrompt Get the curve geometry of this reference line
-   * @examplePrompt Where does this grid line run?
-   * @examplePrompt Read the geometry of a guide line by its id
-   * @examplePrompt Look up the curve of the selected reference line
-   *
-   * # Example
-   * ```ts
-   * const result = await snaptrude.entity.referenceLine.get("some-ref-line-id", ["curve"])
-   * // result.curve is an opaque CurveHandle; a dedicated curve read API for its
-   * // coordinates is exposed separately via `snaptrude.core.geom.curve`.
-   * ```
-   *
-   * @deprecated Use `design.query.referenceLines.get`
-   */
-  public abstract get(
-    referenceLineId: string,
-    properties: z.infer<typeof PluginReferenceLineGetProperty>[]
-  ): PluginApiReturn<PluginReferenceLineGetResult>
-
-  /**
-   * Get the IDs of all reference lines in the current project.
-   *
-   * Returns every reference line across all stories.
-   * Use the returned IDs with {@linkcode PluginReferenceLineApi.get} to query
-   * individual reference line properties.
-   *
-   * @returns A {@linkcode PluginReferenceLineGetAllResult} with a
-   *   `referenceLineIds` array
-   *
-   * @examplePrompt How many grid lines are in the project?
-   * @examplePrompt List all the reference lines in my model
-   * @examplePrompt Show every guide line in the file
-   * @examplePrompt Do I have any reference lines in this project?
-   *
-   * # Example
-   * ```ts
-   * const { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()
-   * console.log(`Project has ${referenceLineIds.length} reference lines`)
-   * ```
-   *
-   * @deprecated Use `design.query.listReferenceLines`
-   */
-  public abstract getAll(): PluginApiReturn<PluginReferenceLineGetAllResult>
-
-  /**
-   * Delete a reference line by its ID.
-   *
-   * Permanently removes the reference line and its associated mesh from
-   * the scene. This operation is undoable via Snaptrude's command system.
-   *
-   * @param referenceLineId - The unique reference line ID to delete
-   * @throws If the reference line does not exist
-   *
-   * @examplePrompt Delete this reference line
-   * @examplePrompt Remove the grid line I just drew
-   * @examplePrompt Get rid of the alignment guide on the left
-   * @examplePrompt Erase a reference line by its id
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.entity.referenceLine.delete("some-ref-line-id")
-   * ```
-   *
-   * @deprecated Use `design.delete.entities`
-   */
-  public abstract delete(
-    referenceLineId: string
-  ): PluginApiReturn<PluginReferenceLineDeleteResult>
-}
-
-/**
- * Arguments for {@linkcode PluginReferenceLineApi.createMulti}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `profile` | {@linkcode ProfileHandle} | Profile handle whose curves define reference lines |
- */
-export const PluginReferenceLineCreateMultiArgs = z.object({
-  profile: ProfileHandle,
-})
-
-export type PluginReferenceLineCreateMultiArgs = z.infer<typeof PluginReferenceLineCreateMultiArgs>
-
-/**
- * Result of {@linkcode PluginReferenceLineApi.createMulti}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `referenceLineIds` | `string[]` | IDs of the created reference lines |
- */
-export const PluginReferenceLineCreateMultiResult = z.object({
-  referenceLineIds: z.array(z.string()),
-})
-
-export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenceLineCreateMultiResult>
-
-/**
- * Available properties that can be queried on a reference line.
- *
- * | Value | Return Type | Description |
- * |---|---|---|
- * | `"curve"` | {@linkcode CurveHandle} | The curve geometry of the reference line, as an opaque handle |
- */
-export const PluginReferenceLineGetProperty = z.enum([
-  "curve",
-])
-
-/**
- * Arguments for {@linkcode PluginReferenceLineApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `referenceLineId` | `string` | The reference line ID to query |
- * | `properties` | {@linkcode PluginReferenceLineGetProperty}`[]` | Properties to retrieve |
- */
-export const PluginReferenceLineGetArgs = z.object({
-  referenceLineId: z.string(),
-  properties: z.array(PluginReferenceLineGetProperty),
-})
-
-export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetArgs>
-
-/**
- * Result of {@linkcode PluginReferenceLineApi.get}.
- *
- * A partial object — only the properties that were requested in
- * {@linkcode PluginReferenceLineGetArgs.properties} will be present.
- */
-export const PluginReferenceLineGetResult = z
-  .object({
-    curve: CurveHandle,
-  })
-  .partial()
-
-export type PluginReferenceLineGetResult = z.infer<typeof PluginReferenceLineGetResult>
-
-/**
- * Result of {@linkcode PluginReferenceLineApi.getAll}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `referenceLineIds` | `string[]` | IDs of all reference lines in the project |
- */
-export const PluginReferenceLineGetAllResult = z.object({
-  referenceLineIds: z.array(z.string()),
-})
-
-export type PluginReferenceLineGetAllResult = z.infer<typeof PluginReferenceLineGetAllResult>
-
-/**
- * Arguments for {@linkcode PluginReferenceLineApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `referenceLineId` | `string` | The reference line ID to delete |
- */
-export const PluginReferenceLineDeleteArgs = z.object({
-  referenceLineId: z.string(),
-})
-
-export type PluginReferenceLineDeleteArgs = z.infer<typeof PluginReferenceLineDeleteArgs>
-
-/** Result type for {@linkcode PluginReferenceLineApi.delete} — returns nothing on success. */
-export type PluginReferenceLineDeleteResult = void
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ProfileHandle, CurveHandle } from "../../handles"
+
+/**
+ * Reference line management — create, query, and delete reference lines.
+ *
+ * A **reference line** is a 2D guide line (or arc) in the Snaptrude scene,
+ * typically used for grid lines and alignment guides. Reference lines
+ * carry properties such as grid tags, labels, and line styles.
+ *
+ * All methods are **host API calls** that return Promises and support
+ * undo/redo via Snaptrude's command system.
+ *
+ * Accessed via `snaptrude.entity.referenceLine`.
+ */
+export abstract class PluginReferenceLineApi {
+  constructor() {}
+
+  /**
+   * Create multiple reference lines from a profile.
+   *
+   * Each curve in the given {@linkcode ProfileHandle} becomes
+   * a separate reference line. Uses `ReferenceLineConstructor.createFromProfile`
+   * internally.
+   *
+   * @param profile - A {@linkcode ProfileHandle} whose curves define the
+   *   reference lines to create
+   * @returns A {@linkcode PluginReferenceLineCreateMultiResult} with the
+   *   `referenceLineIds` of the created reference lines
+   * @throws If reference line creation fails
+   *
+   * @examplePrompt Draw grid lines across the site
+   * @examplePrompt Create reference lines from these curves
+   * @examplePrompt Add alignment guides along the building edge
+   * @examplePrompt Set up a structural grid using guide lines
+   * @examplePrompt Turn this profile into reference lines
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * const start = await vec3.new(0, 0, 0)
+   * const mid = await vec3.new(10, 0, 0)
+   * const end = await vec3.new(10, 0, 10)
+   * const l1 = await snaptrude.core.geom.create.line(start, mid)
+   * const l2 = await snaptrude.core.geom.create.line(mid, end)
+   * const profile = await snaptrude.core.geom.create.profileFromCurves([l1, l2])
+   *
+   * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti(profile)
+   * ```
+   *
+   * @deprecated Use `design.create.referenceLines`
+   */
+  public abstract createMulti(
+    profile: ProfileHandle
+  ): PluginApiReturn<PluginReferenceLineCreateMultiResult>
+
+  /**
+   * Get properties of a reference line by its ID.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result.
+   *
+   * @param referenceLineId - The unique reference line ID
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginReferenceLineGetProperty}.
+   * @returns A partial {@linkcode PluginReferenceLineGetResult} containing only the
+   *   requested properties
+   * @throws If the reference line does not exist
+   *
+   * @examplePrompt Get the curve geometry of this reference line
+   * @examplePrompt Where does this grid line run?
+   * @examplePrompt Read the geometry of a guide line by its id
+   * @examplePrompt Look up the curve of the selected reference line
+   *
+   * # Example
+   * ```ts
+   * const result = await snaptrude.entity.referenceLine.get("some-ref-line-id", ["curve"])
+   * // result.curve is an opaque CurveHandle; a dedicated curve read API for its
+   * // coordinates is exposed separately via `snaptrude.core.geom.curve`.
+   * ```
+   *
+   * @deprecated Use `design.query.referenceLines.get`
+   */
+  public abstract get(
+    referenceLineId: string,
+    properties: z.infer<typeof PluginReferenceLineGetProperty>[]
+  ): PluginApiReturn<PluginReferenceLineGetResult>
+
+  /**
+   * Get the IDs of all reference lines in the current project.
+   *
+   * Returns every reference line across all stories.
+   * Use the returned IDs with {@linkcode PluginReferenceLineApi.get} to query
+   * individual reference line properties.
+   *
+   * @returns A {@linkcode PluginReferenceLineGetAllResult} with a
+   *   `referenceLineIds` array
+   *
+   * @examplePrompt How many grid lines are in the project?
+   * @examplePrompt List all the reference lines in my model
+   * @examplePrompt Show every guide line in the file
+   * @examplePrompt Do I have any reference lines in this project?
+   *
+   * # Example
+   * ```ts
+   * const { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()
+   * console.log(`Project has ${referenceLineIds.length} reference lines`)
+   * ```
+   *
+   * @deprecated Use `design.query.listReferenceLines`
+   */
+  public abstract getAll(): PluginApiReturn<PluginReferenceLineGetAllResult>
+
+  /**
+   * Delete a reference line by its ID.
+   *
+   * Permanently removes the reference line and its associated mesh from
+   * the scene. This operation is undoable via Snaptrude's command system.
+   *
+   * @param referenceLineId - The unique reference line ID to delete
+   * @throws If the reference line does not exist
+   *
+   * @examplePrompt Delete this reference line
+   * @examplePrompt Remove the grid line I just drew
+   * @examplePrompt Get rid of the alignment guide on the left
+   * @examplePrompt Erase a reference line by its id
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.entity.referenceLine.delete("some-ref-line-id")
+   * ```
+   *
+   * @deprecated Use `design.delete.entities`
+   */
+  public abstract delete(
+    referenceLineId: string
+  ): PluginApiReturn<PluginReferenceLineDeleteResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.createMulti}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | Profile handle whose curves define reference lines |
+ */
+export const PluginReferenceLineCreateMultiArgs = z.object({
+  profile: ProfileHandle,
+})
+
+export type PluginReferenceLineCreateMultiArgs = z.infer<typeof PluginReferenceLineCreateMultiArgs>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.createMulti}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineIds` | `string[]` | IDs of the created reference lines |
+ */
+export const PluginReferenceLineCreateMultiResult = z.object({
+  referenceLineIds: z.array(z.string()),
+})
+
+export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenceLineCreateMultiResult>
+
+/**
+ * Available properties that can be queried on a reference line.
+ *
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"curve"` | {@linkcode CurveHandle} | The curve geometry of the reference line, as an opaque handle |
+ */
+export const PluginReferenceLineGetProperty = z.enum([
+  "curve",
+])
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineId` | `string` | The reference line ID to query |
+ * | `properties` | {@linkcode PluginReferenceLineGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginReferenceLineGetArgs = z.object({
+  referenceLineId: z.string(),
+  properties: z.array(PluginReferenceLineGetProperty),
+})
+
+export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetArgs>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.get}.
+ *
+ * A partial object — only the properties that were requested in
+ * {@linkcode PluginReferenceLineGetArgs.properties} will be present.
+ */
+export const PluginReferenceLineGetResult = z
+  .object({
+    curve: CurveHandle,
+  })
+  .partial()
+
+export type PluginReferenceLineGetResult = z.infer<typeof PluginReferenceLineGetResult>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.getAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineIds` | `string[]` | IDs of all reference lines in the project |
+ */
+export const PluginReferenceLineGetAllResult = z.object({
+  referenceLineIds: z.array(z.string()),
+})
+
+export type PluginReferenceLineGetAllResult = z.infer<typeof PluginReferenceLineGetAllResult>
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineId` | `string` | The reference line ID to delete |
+ */
+export const PluginReferenceLineDeleteArgs = z.object({
+  referenceLineId: z.string(),
+})
+
+export type PluginReferenceLineDeleteArgs = z.infer<typeof PluginReferenceLineDeleteArgs>
+
+/** Result type for {@linkcode PluginReferenceLineApi.delete} — returns nothing on success. */
+export type PluginReferenceLineDeleteResult = void