@snaptrude/plugin-core 0.9.14 → 0.9.16

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

@@ -6,7 +6,8 @@ import { ComponentHandle } from "../../../handles"
  * Proposals — read and edit the project's design options ("proposals").
  *
  * A **proposal** is a design option: one of several variants of the same
- * project. Each proposal owns a set of buckets (a bucket == a drawing layer),
+ * project. Each proposal owns a set of buckets (a bucket is a layer in the
+ * Layers panel; read them with `core.layers.get` / {@linkcode PluginCoreLayersApi}),
  * and switching the active proposal shows/hides the buckets it owns. Proposals
  * are **infrastructure**, not design — they own the buckets/layers geometry
  * lives in — so they sit under `core`, not `design` (constitution §2A).
@@ -324,8 +325,8 @@ export abstract class PluginCoreProposalsApi {
  * | `id` | `string` | Stable public proposal id (e.g. `"prop_1"`) |
  * | `name` | `string` | Display name (≤ 24 chars) |
  * | `isActive` | `boolean` | Whether this is the active proposal |
- * | `defaultBucketId` | `string` | Id of the proposal's default bucket (cannot be unshared) |
- * | `bucketIds` | `string[]` | Ids of every bucket (layer) the proposal owns |
+ * | `defaultBucketId` | `string` | Id of the proposal's default layer (cannot be unshared); read it with `core.layers.get` ({@linkcode PluginCoreLayersApi}) |
+ * | `bucketIds` | `string[]` | Ids of every layer in the Layers panel the proposal owns; read them with `core.layers.get` ({@linkcode PluginCoreLayersApi}) |
  * | `createdAt` | `string` | ISO creation timestamp |
  * | `createdBy` | `string` | User id of the creator |
  */

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

@@ -11,6 +11,7 @@ import {
   PluginStoryDeleteResult,
   PluginStoryDuplicateResult,
 } from "../../entity/story"
+import { PluginCoreStoreysLayersApi } from "./layers"
 
 /**
  * Storey (floor) management.
@@ -24,11 +25,22 @@ import {
  * API calls** that return Promises and support undo/redo via Snaptrude's command
  * system (except {@linkcode PluginCoreStoreysApi.setActive}, a view change).
  *
+ * - {@linkcode PluginCoreStoreysApi.layers} — each storey's sketch surfaces
+ *   (Wall, Rough) and imported underlays (CAD, PDF, image, terrain): list, get,
+ *   active layer get/set, show/hide. Not the Layers panel; that is `core.layers`.
+ *
  * Accessed via `snaptrude.core.storeys`.
  */
 export abstract class PluginCoreStoreysApi {
   constructor() {}
 
+  /**
+   * Storey layers — each storey's sketch surfaces and imported underlays (ids
+   * like `ly_5`), formerly `core.layers`. Not the layers in the Layers panel;
+   * use `core.layers` for those. See {@linkcode PluginCoreStoreysLayersApi}.
+   */
+  public abstract layers: PluginCoreStoreysLayersApi
+
   /**
    * Get properties of a storey by its storey number.
    *
@@ -292,3 +304,5 @@ export const PluginCoreStoreysListResult = z.object({
 export type PluginCoreStoreysListResult = z.infer<
   typeof PluginCoreStoreysListResult
 >
+
+export * from "./layers"

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

@@ -0,0 +1,339 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Storey layers — read and toggle a storey's sketch surfaces and imported
+ * underlays.
+ *
+ * These are each storey's built-in sketch surfaces (Wall, Rough) and its
+ * imported underlays (CAD, PDF, images, terrain, neighbourhood buildings), with
+ * ids like `ly_5`. They are **NOT** the layers in the product's Layers panel in
+ * the left sidebar; use {@linkcode PluginCoreLayersApi} (`core.layers`) for
+ * those. They are also not wall/floor construction-assembly material layers.
+ *
+ * Reads return plain records and never throw for a missing layer (`get` and
+ * `getActive` return `null`, `list` returns `[]`).
+ *
+ * Storey layers are created only by storey creation and `core.io.import.*`;
+ * delete underlays with `core.io.underlay.delete` / `core.io.terrain.delete`.
+ *
+ * Sub-namespace members typed as optional (`?`) are **authored ahead of the
+ * host** — declared so plugins and codegen can see the shape, but kept out of the
+ * discovery manifest until the host lands them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.storeys.layers` (formerly `core.layers`).
+ *
+ * Formerly `core.layers`. Calls in that shape on `core.layers` (`list(storeyId)`,
+ * `getActive(storeyId)`, `get` / `setActive` / `update(layerId, hidden)` with a
+ * `ly_*` id) are still routed here, so plugins built before 0.9.15 keep working.
+ */
+export abstract class PluginCoreStoreysLayersApi {
+  constructor() {}
+
+  /**
+   * List the storey layers of a storey.
+   *
+   * Optionally filter to a single {@linkcode PluginCoreStoreyLayerType}.
+   *
+   * @param storeyId - The storey whose layers to read.
+   * @param layerType - Optional {@linkcode PluginCoreStoreyLayerType} filter.
+   * @returns A {@linkcode PluginCoreStoreysLayersListResult} with a `layers` array
+   *   (empty when the storey is missing or has no matching layers).
+   *
+   * @examplePrompt List the sketch surfaces and underlays on this storey
+   * @examplePrompt Show all the PDF underlays on storey st_2
+   * @examplePrompt What CAD layers are on the ground floor?
+   *
+   * # Example
+   * ```ts
+   * const { layers } = await snaptrude.core.storeys.layers.list("st_2")
+   * for (const l of layers) console.log(l.name, l.layerType, l.hidden)
+   * ```
+   */
+  public abstract list(
+    storeyId: string,
+    layerType?: PluginCoreStoreyLayerType,
+  ): PluginApiReturn<PluginCoreStoreysLayersListResult>
+
+  /**
+   * Get a single storey layer by id.
+   *
+   * @param layerId - The id of the layer to read.
+   * @returns The matching {@linkcode PluginCoreStoreyLayer}, or `null` if no layer has
+   *   that id.
+   *
+   * @examplePrompt Get the storey drawing layer with id ly_5
+   * @examplePrompt Is storey layer ly_5 hidden?
+   * @examplePrompt Look up a storey underlay layer by id
+   *
+   * # Example
+   * ```ts
+   * const layer = await snaptrude.core.storeys.layers.get("ly_5")
+   * if (layer) console.log(layer.name, layer.hidden, layer.locked)
+   * ```
+   */
+  public abstract get(
+    layerId: string,
+  ): PluginApiReturn<PluginCoreStoreysLayersGetResult>
+
+  /**
+   * Get the active storey layer of a storey.
+   *
+   * The active layer is the one new sketch geometry is drawn onto. Paired with
+   * {@linkcode PluginCoreStoreysLayersApi.setActive}.
+   *
+   * @param storeyId - The storey whose active layer to read.
+   * @returns The active {@linkcode PluginCoreStoreyLayer}, or `null` if the storey is
+   *   missing or has no active layer.
+   *
+   * @examplePrompt Which sketch surface (Wall/Rough) is active on this storey?
+   * @examplePrompt Get the active storey drawing layer on st_2
+   * @examplePrompt Which storey layer is new sketch geometry drawn onto?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.core.storeys.layers.getActive("st_2")
+   * if (active) console.log(active.name)
+   * ```
+   */
+  public abstract getActive(
+    storeyId: string,
+  ): PluginApiReturn<PluginCoreStoreysLayersGetActiveResult>
+
+  /**
+   * Make a storey layer the active layer of its storey.
+   *
+   * Paired with {@linkcode PluginCoreStoreysLayersApi.getActive}.
+   *
+   * @param layerId - The id of the layer to activate.
+   * @returns The id of the now-active layer.
+   * @throws If no layer has the given id.
+   *
+   * @examplePrompt Switch this storey's sketch surface to the Rough layer
+   * @examplePrompt Make storey layer ly_5 the active sketch surface
+   * @examplePrompt Switch the active storey layer to the CAD underlay
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.storeys.layers.setActive("ly_5")
+   * ```
+   */
+  public abstract setActive(
+    layerId: string,
+  ): PluginApiReturn<PluginCoreStoreysLayersSetActiveResult>
+
+  /**
+   * Update a storey layer's visibility.
+   *
+   * A **sparse** update: omit `hidden` to leave it unchanged. This edit is **not
+   * undoable**. Locking and renaming are not exposed — layer `locked` is a
+   * read-only status here (setting it at runtime does not lock the live meshes or
+   * show a padlock in the app until a reload), and a rename cascades to every member
+   * mesh's `layerName`, a corruption hazard.
+   *
+   * @param layerId - The id of the layer to update.
+   * @param hidden - New hidden state (unchanged if omitted).
+   * @returns The updated {@linkcode PluginCoreStoreyLayer}.
+   * @throws If no layer has the given id.
+   *
+   * @examplePrompt Hide the PDF underlay layer
+   * @examplePrompt Show the CAD underlay again
+   * @examplePrompt Hide storey layer ly_5
+   *
+   * # Example
+   * ```ts
+   * const layer = await snaptrude.core.storeys.layers.update("ly_5", true)
+   * ```
+   */
+  public abstract update(
+    layerId: string,
+    hidden?: boolean,
+  ): PluginApiReturn<PluginCoreStoreysLayersUpdateResult>
+}
+
+/**
+ * The kind of a storey layer.
+ *
+ * Author-drawable kinds (`floor`, `wall`, `ceiling`, `rough`, `default`) plus
+ * read-only imported underlays (`image`, `cad`, `pdf`, `terrain`, `buildings`).
+ */
+export const PluginCoreStoreyLayerType = z.enum([
+  "floor",
+  "wall",
+  "ceiling",
+  "rough",
+  "default",
+  "image",
+  "cad",
+  "pdf",
+  "terrain",
+  "buildings",
+])
+export type PluginCoreStoreyLayerType = z.infer<typeof PluginCoreStoreyLayerType>
+
+/**
+ * A storey layer on a storey.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public layer id (e.g. `"ly_5"`) |
+ * | `name` | `string` | Display name |
+ * | `layerType` | {@linkcode PluginCoreStoreyLayerType} | The layer's kind |
+ * | `storeyId` | `string` | The stable id of the storey this layer belongs to |
+ * | `buildingId` | `string` | The stable id of the building this layer belongs to |
+ * | `hidden` | `boolean` | Whether the layer is hidden |
+ * | `locked` | `boolean` | Whether the layer is locked against edits |
+ * | `contentSummary` | `object` | A summary of what the layer holds (see below) |
+ *
+ * `contentSummary`:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `hasFloorplan` | `boolean` | Whether the layer holds drawn floorplan geometry |
+ * | `pdfCount` | `number` | Number of PDF underlays on the layer |
+ * | `hasTerrain` | `boolean` | Whether the layer holds terrain |
+ */
+export const PluginCoreStoreyLayer = z.object({
+  id: z.string(),
+  name: z.string(),
+  layerType: PluginCoreStoreyLayerType,
+  storeyId: z.string(),
+  buildingId: z.string(),
+  hidden: z.boolean(),
+  locked: z.boolean(),
+  contentSummary: z.object({
+    hasFloorplan: z.boolean(),
+    pdfCount: z.number().int(),
+    hasTerrain: z.boolean(),
+  }),
+})
+export type PluginCoreStoreyLayer = z.infer<typeof PluginCoreStoreyLayer>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyId` | `string` | The storey whose layers to read |
+ * | `layerType` | {@linkcode PluginCoreStoreyLayerType}` \| undefined` | Optional layer-type filter |
+ */
+export const PluginCoreStoreysLayersListArgs = z.object({
+  storeyId: z.string(),
+  layerType: PluginCoreStoreyLayerType.optional(),
+})
+export type PluginCoreStoreysLayersListArgs = z.infer<
+  typeof PluginCoreStoreysLayersListArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreStoreysLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layers` | {@linkcode PluginCoreStoreyLayer}`[]` | The storey's storey layers (empty when missing or none match) |
+ */
+export const PluginCoreStoreysLayersListResult = z.object({
+  layers: z.array(PluginCoreStoreyLayer),
+})
+export type PluginCoreStoreysLayersListResult = z.infer<
+  typeof PluginCoreStoreysLayersListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to read |
+ */
+export const PluginCoreStoreysLayersGetArgs = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreStoreysLayersGetArgs = z.infer<
+  typeof PluginCoreStoreysLayersGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreStoreysLayersApi.get} — the layer, or `null`
+ * when no layer has the given id.
+ */
+export const PluginCoreStoreysLayersGetResult = PluginCoreStoreyLayer.nullable()
+export type PluginCoreStoreysLayersGetResult = z.infer<
+  typeof PluginCoreStoreysLayersGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.getActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyId` | `string` | The storey whose active layer to read |
+ */
+export const PluginCoreStoreysLayersGetActiveArgs = z.object({
+  storeyId: z.string(),
+})
+export type PluginCoreStoreysLayersGetActiveArgs = z.infer<
+  typeof PluginCoreStoreysLayersGetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreStoreysLayersApi.getActive} — the active layer,
+ * or `null` when the storey is missing or has no active layer.
+ */
+export const PluginCoreStoreysLayersGetActiveResult = PluginCoreStoreyLayer.nullable()
+export type PluginCoreStoreysLayersGetActiveResult = z.infer<
+  typeof PluginCoreStoreysLayersGetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to activate |
+ */
+export const PluginCoreStoreysLayersSetActiveArgs = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreStoreysLayersSetActiveArgs = z.infer<
+  typeof PluginCoreStoreysLayersSetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreStoreysLayersApi.setActive} — the now-active
+ * layer's id.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the now-active layer |
+ */
+export const PluginCoreStoreysLayersSetActiveResult = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreStoreysLayersSetActiveResult = z.infer<
+  typeof PluginCoreStoreysLayersSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to update |
+ * | `hidden` | `boolean \| undefined` | New hidden state (unchanged if omitted) |
+ */
+export const PluginCoreStoreysLayersUpdateArgs = z.object({
+  layerId: z.string(),
+  hidden: z.boolean().optional(),
+})
+export type PluginCoreStoreysLayersUpdateArgs = z.infer<
+  typeof PluginCoreStoreysLayersUpdateArgs
+>
+
+/** Result of {@linkcode PluginCoreStoreysLayersApi.update} — the updated layer. */
+export const PluginCoreStoreysLayersUpdateResult = PluginCoreStoreyLayer
+export type PluginCoreStoreysLayersUpdateResult = z.infer<
+  typeof PluginCoreStoreysLayersUpdateResult
+>

package/src/api/design/create/bulk-items.ts

@@ -9,6 +9,72 @@ import { PluginOpeningBaseOptions } from "./opening-fields"
  */
 export const PLUGIN_CREATE_BATCH_LIMIT = 1000
 
+// ---------------------------------------------------------------------------
+// wall top profile (raked / gabled walls)
+// ---------------------------------------------------------------------------
+
+/**
+ * One break point of a wall's top edge — see {@linkcode PluginWallTopProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `along` | `number` | Position along the wall centerline as a fraction: `0` = start of the curve, `1` = end |
+ * | `height` | `number` | Top height above the wall base at that point (Snaptrude units, > 0) |
+ */
+export const PluginWallTopProfilePoint = z.object({
+  along: z.number().min(0).max(1),
+  height: z.number().positive(),
+})
+export type PluginWallTopProfilePoint = z.infer<
+  typeof PluginWallTopProfilePoint
+>
+
+/**
+ * The top edge of ONE wall as a polyline over its centerline: at least two
+ * points, `along` strictly increasing from `0` (curve start) to `1` (curve end),
+ * straight segments between them. Two points give a single slope (a raked
+ * wall), three give a gable, more give any stepped or folded ridge. Heights are
+ * measured from the wall base, like `height`. Both long faces follow the same
+ * profile, so the top stays a set of flat faces and the wall keeps its thickness
+ * end to end.
+ *
+ * Only straight centerlines take a top profile (an arc curve with one is
+ * rejected). A wall built this way is a real Wall — doors and windows host on
+ * it, corners mitre, quantities and Revit export read its geometry — but it is
+ * **non-parametric**: the parametric wall graph does not rebuild it, so a later
+ * move of a neighbour does not re-mitre its corner, exactly like a wall whose
+ * top edge was dragged by hand. `design.update.wall({ height })` scales it
+ * proportionally.
+ */
+export const PluginWallTopProfile = z
+  .array(PluginWallTopProfilePoint)
+  .min(2)
+  .superRefine((points, ctx) => {
+    if (points[0].along !== 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: "topProfile must start at along = 0",
+      })
+    }
+    if (points[points.length - 1].along !== 1) {
+      ctx.addIssue({
+        code: "custom",
+        message: "topProfile must end at along = 1",
+      })
+    }
+    for (let i = 1; i < points.length; i++) {
+      if (points[i].along <= points[i - 1].along) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            "topProfile points must be in strictly increasing `along` order",
+        })
+        break
+      }
+    }
+  })
+export type PluginWallTopProfile = z.infer<typeof PluginWallTopProfile>
+
 // ---------------------------------------------------------------------------
 // wallRuns
 // ---------------------------------------------------------------------------
@@ -24,6 +90,7 @@ export const PLUGIN_CREATE_BATCH_LIMIT = 1000
  * | `thickness` | `number`? | Wall thickness (Snaptrude units, > 0; default: `wallType`'s total layer thickness when given, else engine default) |
  * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
  * | `storey` | `number`? (int) | Target storey (must exist) — the run's walls are assigned + lifted to its base in the same undo entry (default: geometry-derived) |
+ * | `topProfiles` | ({@linkcode PluginWallTopProfile} \| `null`)[]? | Top edge per curve of `profile`, same order; a `null` or missing entry keeps that wall flat at `height`. Raked / gabled walls (straight curves only) |
  */
 export const PluginCreateWallRunItem = z.object({
   profile: ProfileHandle,
@@ -31,6 +98,7 @@ export const PluginCreateWallRunItem = z.object({
   thickness: z.number().optional(),
   wallType: z.string().min(1).optional(),
   storey: z.number().int().optional(),
+  topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
 })
 export type PluginCreateWallRunItem = z.infer<typeof PluginCreateWallRunItem>
 

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

@@ -28,6 +28,7 @@ import type {
   PluginCreateWallRunItem,
   PluginCreateWindowItem,
 } from "./bulk-items"
+import { PluginWallTopProfile } from "./bulk-items"
 
 /**
  * `design.create.*` — author new scene-committed BIM entities.
@@ -450,9 +451,15 @@ export abstract class PluginDesignCreateApi {
    *   single undo entry. The storey must already exist
    *   (`core.storeys.create` first). Default: geometry-derived — a profile
    *   drawn at y = 0 lands on storey 1; the ACTIVE storey is NOT consulted.
+   * @param topProfiles - Optional top edge per curve of `profile` (same order):
+   *   a {@linkcode PluginWallTopProfile} makes that wall raked / gabled; `null`
+   *   or a missing entry keeps it flat at `height`. Straight curves only. Such
+   *   walls are non-parametric (see {@linkcode PluginWallTopProfile}).
    * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
    * @throws if the profile is empty, `wallType` names no wall type in the
-   *   project, `storey` does not exist, or wall creation fails
+   *   project, `storey` does not exist, `topProfiles` has more entries than the
+   *   profile has curves or names an arc curve, a top profile drops to the wall
+   *   base at a mitred corner, or wall creation fails
    *
    * @examplePrompt Draw walls along this centerline
    * @examplePrompt Create 3m high, 200mm thick walls from these points
@@ -461,6 +468,9 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Add walls with mitred corners along the path
    * @examplePrompt Draw brick walls with plaster along this outline
    * @examplePrompt Build the perimeter in exposed concrete walls
+   * @examplePrompt Create a raked wall that slopes from 3m to 5m
+   * @examplePrompt Build a gable end wall with the ridge in the middle
+   * @examplePrompt Draw a wall with a sloped top edge
    *
    * # Example
    * ```ts
@@ -476,6 +486,13 @@ export abstract class PluginDesignCreateApi {
    * const brickWalls = await snaptrude.design.create.walls(
    *   centerlines, 3, undefined, brick.label,
    * )
+   * // …a raked wall (3m at the start, 5m at the end) on a single centerline:
+   * const run = await snaptrude.core.geom.create.profileFromCurves([
+   *   await snaptrude.core.geom.create.line(await v.new(0, 0, 10), await v.new(8, 0, 10)),
+   * ])
+   * const [raked] = await snaptrude.design.create.walls(run, undefined, 0.2, undefined, undefined, [
+   *   [{ along: 0, height: 3 }, { along: 1, height: 5 }],
+   * ])
    * ```
    *
    * @performance For MORE THAN ONE run, call `design.create.wallRuns(items[])` — one
@@ -488,6 +505,7 @@ export abstract class PluginDesignCreateApi {
     thickness?: number,
     wallType?: string,
     storey?: number,
+    topProfiles?: (PluginWallTopProfile | null)[],
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
@@ -496,7 +514,9 @@ export abstract class PluginDesignCreateApi {
    * item's profile chain, mitred at shared endpoints. Junctions resolve within a
    * run, not between runs. Each item carries its own
    * dimensions, `wallType` and `storey`, so a single call can build a whole
-   * floor plate or several storeys at once. Validate-all-or-throw; one command.
+   * floor plate or several storeys at once. Per-curve `topProfiles` make raked
+   * or gabled walls (see {@linkcode PluginWallTopProfile}). Validate-all-or-throw;
+   * one command.
    *
    * @param items - One {@linkcode PluginCreateWallRunItem} per run to create
    *   (≥1, ≤1000)
@@ -516,6 +536,7 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Bulk create wall runs from these centerlines
    * @examplePrompt Create the walls for both storeys in a single undo step
    * @examplePrompt Turn these polylines into 200mm brick walls together
+   * @examplePrompt Import these raked walls with their top profiles in one go
    *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
    *   entry. Always prefer this over calling `design.create.walls` in a loop: build the
@@ -536,6 +557,9 @@ export abstract class PluginDesignCreateApi {
    * const [groundWalls, upperWalls] = await snaptrude.design.create.wallRuns([
    *   { profile: ground, height: 3, thickness: 0.2 },
    *   { profile: upper, height: 3, storey: 2 },
+   *   // one gable wall: 3m at both ends, 5m ridge in the middle
+   *   { profile: upper, thickness: 0.2, storey: 3,
+   *     topProfiles: [[{ along: 0, height: 3 }, { along: 0.5, height: 5 }, { along: 1, height: 3 }]] },
    * ])
    * console.log(groundWalls.length, "walls on the ground floor")
    * ```
@@ -1638,6 +1662,7 @@ export type PluginDesignCreateBeamArgs = z.infer<
  * | `thickness` | `number`? | Wall thickness (default: `wallType`'s total layer thickness when given, else engine default) |
  * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
  * | `storey` | `number`? | Target storey (integer, must exist) — walls assigned + lifted to its base in the same undo entry (default: geometry-derived) |
+ * | `topProfiles` | ({@linkcode PluginWallTopProfile} \| `null`)[]? | Top edge per curve (same order); `null`/missing = flat at `height`. Straight curves only |
  */
 export const PluginDesignCreateWallsArgs = z.object({
   profile: ProfileHandle,
@@ -1645,12 +1670,13 @@ export const PluginDesignCreateWallsArgs = z.object({
   thickness: z.number().optional(),
   wallType: z.string().min(1).optional(),
   storey: z.number().int().optional(),
+  topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
 })
 export type PluginDesignCreateWallsArgs = z.infer<
   typeof PluginDesignCreateWallsArgs
 >
-// TRANSPORT: positional signature shipped — storey is the trailing 5th arg:
-//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, storey?: number)
+// TRANSPORT: positional signature shipped — storey is the 5th arg, topProfiles the trailing 6th:
+//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, storey?: number, topProfiles?: (PluginWallTopProfile | null)[])
 
 // ---------------------------------------------------------------------------
 // staircase