@snaptrude/plugin-core 0.2.9 → 0.5.0

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

@@ -0,0 +1,207 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * `snaptrude.design.windows` — window-specific reads. Creation lives at
+ * `design.create.window`; generic reads (`listWindows`/`getHost`/`getProperties`) live
+ * at `design.query.*`. Window targets are {@linkcode ComponentHandle}s.
+ *
+ * `listTypes` (UI-const catalog), `getSillHeight` (bounds-derived), and the
+ * command-wired `mirror` land in a later pass.
+ */
+export abstract class PluginDesignWindowsApi {
+  constructor() {}
+
+  /**
+   * Get the type name of a window — the label that identifies which kind of
+   * window the instance is, as shown in its properties.
+   *
+   * @param window The window to query
+   * @returns The type as a `string`, or `null`
+   *
+   * @examplePrompt What type of window is this?
+   * @examplePrompt Is the selected window a casement or a slider?
+   * @examplePrompt Tell me the window type used on this wall
+   * @examplePrompt Check what kind of window the living room has
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
+   * const type = await snaptrude.design.windows.getType(win)
+   * if (type) console.log("window type:", type)
+   * ```
+   */
+  public abstract getType(window: ComponentHandle): PluginApiReturn<string | null>
+
+  /**
+   * Get the width of a window — how wide its opening is along the host wall.
+   *
+   * @param window The window to query
+   * @returns The width as a `number`, or `null`
+   *
+   * @examplePrompt How wide is this window?
+   * @examplePrompt What's the width of the selected window?
+   * @examplePrompt Measure the width of the kitchen window
+   * @examplePrompt Check whether this window is 1200mm wide
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows()
+   * const width = await snaptrude.design.windows.getWidth(win)
+   * if (width !== null) console.log("window width:", width)
+   * ```
+   */
+  public abstract getWidth(window: ComponentHandle): PluginApiReturn<number | null>
+
+  /**
+   * Get the height of a window — how tall its opening is on the host wall.
+   *
+   * @param window The window to query
+   * @returns The height as a `number`, or `null`
+   *
+   * @examplePrompt How tall is this window?
+   * @examplePrompt What's the height of the selected window?
+   * @examplePrompt Check the window height on this wall
+   * @examplePrompt Is the bedroom window 1.5m high?
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows()
+   * const height = await snaptrude.design.windows.getHeight(win)
+   * if (height !== null) console.log("window height:", height)
+   * ```
+   */
+  public abstract getHeight(window: ComponentHandle): PluginApiReturn<number | null>
+
+  /**
+   * Get a window's full dimensions in one call — width along the wall, vertical
+   * height, and thickness through the wall — measured in the window's local
+   * oriented space.
+   *
+   * @param window The window to query
+   * @returns The dimensions, or `null`
+   *
+   * @examplePrompt What are the dimensions of this window?
+   * @examplePrompt How big is the selected window?
+   * @examplePrompt Give me the width, height and depth of this window
+   * @examplePrompt Measure the living room window
+   * @examplePrompt Get the window size including its thickness through the wall
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
+   * const dims = await snaptrude.design.windows.getDimensions(win)
+   * if (dims) console.log(dims.width, dims.height, dims.thickness)
+   * ```
+   */
+  public abstract getDimensions(
+    window: ComponentHandle
+  ): PluginApiReturn<PluginWindowDimensions | null>
+
+  /**
+   * Set the width of a window, resizing its opening and re-cutting the host
+   * wall. Width is in engine units; the change is undoable.
+   *
+   * @param window The window to resize
+   * @param width New width (engine units)
+   * @returns The affected window
+   *
+   * @examplePrompt Make this window 1200mm wide
+   * @examplePrompt Widen the selected window to 4 feet
+   * @examplePrompt Change the window width to 1.5m
+   * @examplePrompt Resize the kitchen window to 900 wide
+   *
+   * # Example
+   * ```ts
+   * // Takes a single window (unlike design.doors.setWidth, which takes an array)
+   * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
+   * const { affected } = await snaptrude.design.windows.setWidth(win, 1200)
+   * ```
+   */
+  public abstract setWidth(
+    window: ComponentHandle,
+    width: number
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Set the height of a window, resizing its opening and re-cutting the host
+   * wall. Height is in engine units; the change is undoable.
+   *
+   * @param window The window to resize
+   * @param height New height (engine units)
+   * @returns The affected window
+   *
+   * @examplePrompt Make this window 1.5m tall
+   * @examplePrompt Change the window height to 4 feet
+   * @examplePrompt Shorten the selected window to 900mm high
+   * @examplePrompt Set the bedroom window height to 1200
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
+   * await snaptrude.design.windows.setHeight(win, 1500)
+   * ```
+   */
+  public abstract setHeight(
+    window: ComponentHandle,
+    height: number
+  ): PluginApiReturn<PluginDesignChangeResult>
+}
+
+/**
+ * Arguments for the single-window read methods.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `window` | {@linkcode ComponentHandle} | The window to query |
+ */
+export const PluginDesignWindowArgs = z.object({
+  window: ComponentHandle,
+})
+export type PluginDesignWindowArgs = z.infer<typeof PluginDesignWindowArgs>
+
+/**
+ * A window's dimensions.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `width` | `number` | Along the wall |
+ * | `height` | `number` | Vertical |
+ * | `thickness` | `number` | Through the wall (engine `length` axis) |
+ */
+export const PluginWindowDimensions = z.object({
+  width: z.number(),
+  height: z.number(),
+  thickness: z.number(),
+})
+export type PluginWindowDimensions = z.infer<typeof PluginWindowDimensions>
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.setWidth}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `window` | {@linkcode ComponentHandle} | The window to resize |
+ * | `width` | `number` | New width (engine units) |
+ */
+export const PluginDesignWindowSetWidthArgs = z.object({
+  window: ComponentHandle,
+  width: z.number(),
+})
+export type PluginDesignWindowSetWidthArgs = z.infer<typeof PluginDesignWindowSetWidthArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.setHeight}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `window` | {@linkcode ComponentHandle} | The window to resize |
+ * | `height` | `number` | New height (engine units) |
+ */
+export const PluginDesignWindowSetHeightArgs = z.object({
+  window: ComponentHandle,
+  height: z.number(),
+})
+export type PluginDesignWindowSetHeightArgs = z.infer<typeof PluginDesignWindowSetHeightArgs>

package/src/api/entity/buildableEnvelope.ts

@@ -15,66 +15,107 @@ export abstract class PluginBuildableEnvelopeApi {
   constructor() {}
 
   /**
-   * Create a new parametric buildable envelope.
+   * Create a new parametric buildable envelope — the zoning-regulated volume a
+   * building may occupy — generated from a site polygon, tiered setbacks, a
+   * height or floor-count cap, and optional FAR and lot-coverage limits.
    *
-   * @param args - A {@linkcode PluginBuildableEnvelopeCreateArgs} object.
+   * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
+   * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
+   * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
+   * @param verticalCap - Maximum height or floor count.
+   * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
+   * @param farRatio - Optional FAR value, positive when provided.
+   * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
    * @returns A {@linkcode PluginBuildableEnvelopeCreateResult} with the
    *   `buildableEnvelopeId` of the created envelope.
    * @throws If validation fails or generation produces no renderable geometry.
    *
+   * @examplePrompt Create a buildable envelope for my site
+   * @examplePrompt Generate the zoning envelope with 10ft front setbacks
+   * @examplePrompt Show the maximum buildable volume with a 150ft height limit
+   * @examplePrompt Model the allowable massing from the setback rules
+   * @examplePrompt Create a zoning envelope capped at 12 floors with FAR 3
+   *
    * # Example
    * ```ts
-   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.create({
-   *   sitePolygon: [
+   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.create(
+   *   [
    *     { x: 0, z: 0 },
    *     { x: 100, z: 0 },
    *     { x: 100, z: 80 },
    *     { x: 0, z: 80 },
    *   ],
-   *   lengthUnit: "ft",
-   *   setbacks: [
+   *   "ft",
+   *   [
    *     { aboveHeight: 0, front: 10, side: 5, rear: 10 },
    *     { aboveHeight: 100, front: 20, side: 10, rear: 20 },
    *   ],
-   *   verticalCap: { kind: "max_height", maxHeight: 150 },
-   *   floorToFloor: 12,
-   * })
+   *   { kind: "max_height", maxHeight: 150 },
+   *   12,
+   * )
    * ```
    */
   public abstract create(
-    args: PluginBuildableEnvelopeCreateArgs
+    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
+    lengthUnit: "ft" | "m",
+    setbacks: PluginBuildableEnvelopeSetbackTier[],
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: number,
+    farRatio?: number,
+    lotCoverageMaxPct?: number
   ): PluginApiReturn<PluginBuildableEnvelopeCreateResult>
 
   /**
-   * Update an existing parametric buildable envelope.
+   * Update an existing parametric buildable envelope — regenerate the zoning
+   * volume from a revised site polygon, setbacks, vertical cap, or FAR and
+   * lot-coverage limits, keeping the same envelope id.
    *
-   * @param args - A {@linkcode PluginBuildableEnvelopeUpdateArgs} object.
-   *   `buildableEnvelopeId` is required and must match an existing envelope on
-   *   the canvas.
+   * @param buildableEnvelopeId - Existing envelope ID to update; non-empty and
+   *   must match an existing envelope on the canvas.
+   * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
+   * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
+   * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
+   * @param verticalCap - Maximum height or floor count.
+   * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
+   * @param farRatio - Optional FAR value, positive when provided.
+   * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
    * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
    *   `buildableEnvelopeId` of the updated envelope.
    * @throws If validation fails, the envelope does not exist, or generation
    *   produces no renderable geometry.
    *
+   * @examplePrompt Change the envelope's height limit to 175 feet
+   * @examplePrompt Update the setbacks on the buildable envelope
+   * @examplePrompt Regenerate the zoning envelope with a new site boundary
+   * @examplePrompt Increase the FAR on the buildable volume
+   * @examplePrompt Modify the envelope to allow 15 storeys instead
+   *
    * # Example
    * ```ts
-   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.update({
-   *   buildableEnvelopeId: existingId,
-   *   sitePolygon: [
+   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.update(
+   *   existingId,
+   *   [
    *     { x: 0, z: 0 },
    *     { x: 100, z: 0 },
    *     { x: 100, z: 80 },
    *     { x: 0, z: 80 },
    *   ],
-   *   lengthUnit: "ft",
-   *   setbacks: [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
-   *   verticalCap: { kind: "max_height", maxHeight: 175 },
-   *   floorToFloor: 12,
-   * })
+   *   "ft",
+   *   [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
+   *   { kind: "max_height", maxHeight: 175 },
+   *   12,
+   * )
    * ```
    */
   public abstract update(
-    args: PluginBuildableEnvelopeUpdateArgs
+    buildableEnvelopeId: string,
+    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
+    lengthUnit: "ft" | "m",
+    setbacks: PluginBuildableEnvelopeSetbackTier[],
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: number,
+    farRatio?: number,
+    lotCoverageMaxPct?: number
   ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
 }
 

package/src/api/entity/department.ts

@@ -1,113 +0,0 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Department management — create and query departments.
- *
- * A **department** is a named, colored grouping applied to spaces.
- * Departments are used to categorize spaces by function (e.g. "FOH",
- * "Emergency", "Residential") and control their visual appearance.
- *
- * Accessed via `snaptrude.entity.department`.
- */
-export abstract class PluginDepartmentApi {
-  constructor() {}
-
-  /**
-   * Create a new department.
-   *
-   * @param args - An object containing:
-   *   - {@linkcode PluginDepartmentCreateArgs.name args.name} — Display name
-   *   - {@linkcode PluginDepartmentCreateArgs.color args.color} — CSS hex color string (e.g. `"#b5e1dc"`)
-   * @returns A {@linkcode PluginDepartmentCreateResult} with the `departmentId`
-   *   of the created department
-   * @throws If department creation fails
-   *
-   * # Example
-   * ```ts
-   * const { departmentId } = await snaptrude.entity.department.create({
-   *   name: "Emergency",
-   *   color: "#f5e68b",
-   * })
-   * ```
-   */
-  public abstract create(
-    args: PluginDepartmentCreateArgs
-  ): PluginApiReturn<PluginDepartmentCreateResult>
-
-  /**
-   * Get all departments in the current project.
-   *
-   * Returns every department including well-known ones (Default, Site, etc.)
-   * and user-created departments.
-   *
-   * @returns A {@linkcode PluginDepartmentGetAllResult} with a `departments` array
-   *
-   * # Example
-   * ```ts
-   * const { departments } = await snaptrude.entity.department.getAll()
-   * for (const dept of departments) {
-   *   console.log(dept.id, dept.name, dept.color)
-   * }
-   * ```
-   */
-  public abstract getAll(): PluginApiReturn<PluginDepartmentGetAllResult>
-}
-
-/**
- * Arguments for {@linkcode PluginDepartmentApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `name` | `string` | Display name of the department |
- * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
- */
-export const PluginDepartmentCreateArgs = z.object({
-  name: z.string(),
-  color: z.string(),
-})
-
-export type PluginDepartmentCreateArgs = z.infer<
-  typeof PluginDepartmentCreateArgs
->
-
-/**
- * Result of {@linkcode PluginDepartmentApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departmentId` | `string` | Unique ID of the created department |
- */
-export const PluginDepartmentCreateResult = z.object({
-  departmentId: z.string(),
-})
-
-export type PluginDepartmentCreateResult = z.infer<
-  typeof PluginDepartmentCreateResult
->
-
-/**
- * A single department entry returned by {@linkcode PluginDepartmentApi.getAll}.
- */
-export const PluginDepartmentEntry = z.object({
-  id: z.string(),
-  name: z.string(),
-  color: z.string(),
-})
-
-export type PluginDepartmentEntry = z.infer<typeof PluginDepartmentEntry>
-
-/**
- * Result of {@linkcode PluginDepartmentApi.getAll}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `departments` | {@linkcode PluginDepartmentEntry}`[]` | All departments in the project |
- */
-export const PluginDepartmentGetAllResult = z.object({
-  departments: z.array(PluginDepartmentEntry),
-})
-
-export type PluginDepartmentGetAllResult = z.infer<
-  typeof PluginDepartmentGetAllResult
->

package/src/api/entity/index.ts

@@ -1,27 +1,23 @@
 import { PluginBuildableEnvelopeApi } from "./buildableEnvelope"
-import { PluginDepartmentApi } from "./department"
 import { PluginReferenceLineApi } from "./referenceLine"
-import { PluginSpaceApi } from "./space"
 import { PluginStoryApi } from "./story"
 
 /**
  * CRUD operations on Snaptrude building entities.
  *
- * - {@linkcode PluginEntityApi.space} — Create, query, and delete spaces (rooms/masses)
  * - {@linkcode PluginEntityApi.story} — Create, query, and update stories (floors)
  * - {@linkcode PluginEntityApi.referenceLine} — Create, query, and delete reference lines
- * - {@linkcode PluginEntityApi.department} — Create and query departments
  * - {@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 {
-  /** Space (room/mass) operations. See {@linkcode PluginSpaceApi}. */
-  public abstract space: PluginSpaceApi
   /** Story (floor/storey) operations. See {@linkcode PluginStoryApi}. */
   public abstract story: PluginStoryApi
   /** Reference line operations. See {@linkcode PluginReferenceLineApi}. */
   public abstract referenceLine: PluginReferenceLineApi
-  /** Department operations. See {@linkcode PluginDepartmentApi}. */
-  public abstract department: PluginDepartmentApi
   /** Buildable Envelope operations. See {@linkcode PluginBuildableEnvelopeApi}. */
   public abstract buildableEnvelope: PluginBuildableEnvelopeApi
 
@@ -29,7 +25,6 @@ export abstract class PluginEntityApi {
 }
 
 export * from "./buildableEnvelope"
-export * from "./department"
 export * from "./referenceLine"
 export * from "./space"
 export * from "./story"

package/src/api/entity/referenceLine.ts

@@ -1,7 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
-import { PProfile } from "../core/geom/profile"
-import { PCurve } from "../core/geom/curve"
+import { ProfileHandle, CurveHandle } from "../../handles"
 
 /**
  * Reference line management — create, query, and delete reference lines.
@@ -21,61 +20,68 @@ export abstract class PluginReferenceLineApi {
   /**
    * Create multiple reference lines from a profile.
    *
-   * Each {@linkcode PCurve} in the given {@linkcode PProfile} becomes
+   * Each curve in the given {@linkcode ProfileHandle} becomes
    * a separate reference line. Uses `ReferenceLineConstructor.createFromProfile`
    * internally.
    *
-   * @param args - An object containing:
-   *   - {@linkcode PluginReferenceLineCreateMultiArgs.profile args.profile} — A
-   *     {@linkcode PProfile} whose curves define the reference lines to create
+   * @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 l1 = snaptrude.core.geom.line.new(vec3.new(0, 0, 0), vec3.new(10, 0, 0))
-   * const l2 = snaptrude.core.geom.line.new(vec3.new(10, 0, 0), vec3.new(10, 0, 10))
-   * const profile = snaptrude.core.geom.profile.new([l1, l2])
+   * 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,
-   * })
+   * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti(profile)
    * ```
    */
   public abstract createMulti(
-    args: PluginReferenceLineCreateMultiArgs
+    profile: ProfileHandle
   ): PluginApiReturn<PluginReferenceLineCreateMultiResult>
 
   /**
    * Get properties of a reference line by its ID.
    *
-   * Only the properties listed in {@linkcode PluginReferenceLineGetArgs.properties
-   * args.properties} are returned — unlisted properties will be `undefined`
-   * in the result.
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result.
    *
-   * @param args - An object containing:
-   *   - {@linkcode PluginReferenceLineGetArgs.referenceLineId args.referenceLineId} —
-   *     The unique reference line ID
-   *   - {@linkcode PluginReferenceLineGetArgs.properties args.properties} — Array of
-   *     property names to retrieve. See {@linkcode PluginReferenceLineGetProperty}.
+   * @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({
-   *   referenceLineId: "some-ref-line-id",
-   *   properties: ["curve"],
-   * })
-   * console.log(result.curve) // PCurve
+   * 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`.
    * ```
    */
   public abstract get(
-    args: PluginReferenceLineGetArgs
+    referenceLineId: string,
+    properties: z.infer<typeof PluginReferenceLineGetProperty>[]
   ): PluginApiReturn<PluginReferenceLineGetResult>
 
   /**
@@ -88,6 +94,11 @@ export abstract class PluginReferenceLineApi {
    * @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()
@@ -102,20 +113,21 @@ export abstract class PluginReferenceLineApi {
    * Permanently removes the reference line and its associated mesh from
    * the scene. This operation is undoable via Snaptrude's command system.
    *
-   * @param args - An object containing:
-   *   - {@linkcode PluginReferenceLineDeleteArgs.referenceLineId args.referenceLineId} —
-   *     The unique reference line ID to delete
+   * @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({
-   *   referenceLineId: "some-ref-line-id",
-   * })
+   * await snaptrude.entity.referenceLine.delete("some-ref-line-id")
    * ```
    */
   public abstract delete(
-    args: PluginReferenceLineDeleteArgs
+    referenceLineId: string
   ): PluginApiReturn<PluginReferenceLineDeleteResult>
 }
 
@@ -124,10 +136,10 @@ export abstract class PluginReferenceLineApi {
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `profile` | {@linkcode PProfile} | Profile whose curves define reference lines |
+ * | `profile` | {@linkcode ProfileHandle} | Profile handle whose curves define reference lines |
  */
 export const PluginReferenceLineCreateMultiArgs = z.object({
-  profile: PProfile,
+  profile: ProfileHandle,
 })
 
 export type PluginReferenceLineCreateMultiArgs = z.infer<typeof PluginReferenceLineCreateMultiArgs>
@@ -150,7 +162,7 @@ export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenc
  *
  * | Value | Return Type | Description |
  * |---|---|---|
- * | `"curve"` | {@linkcode PCurve} | The curve geometry of the reference line |
+ * | `"curve"` | {@linkcode CurveHandle} | The curve geometry of the reference line, as an opaque handle |
  */
 export const PluginReferenceLineGetProperty = z.enum([
   "curve",
@@ -179,7 +191,7 @@ export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetAr
  */
 export const PluginReferenceLineGetResult = z
   .object({
-    curve: PCurve,
+    curve: CurveHandle,
   })
   .partial()