@snaptrude/plugin-core 0.9.14 → 0.9.16-networks-20261008.1

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

@@ -1,6 +1,8 @@
 import * as z from "zod"
 import { ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles"
 import { PluginOpeningBaseOptions } from "./opening-fields"
+import { PluginWallType } from "../types"
+import { PluginFamilyValues } from "../catalog"
 
 /**
  * Maximum items per bulk `design.create.*` call. A bounded request keeps
@@ -9,6 +11,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
 // ---------------------------------------------------------------------------
@@ -22,15 +90,19 @@ export const PLUGIN_CREATE_BATCH_LIMIT = 1000
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (Snaptrude units, > 0; default engine default) |
  * | `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) |
+ * | `wallType` | {@linkcode PluginWallType}? | Legacy name/id or exact native `{ id, version }` pin from `design.types.list("wall")` (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,
   height: z.number().optional(),
   thickness: z.number().optional(),
-  wallType: z.string().min(1).optional(),
+  wallType: PluginWallType.optional(),
   storey: z.number().int().optional(),
+  topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
+  /** Optional family overrides in mm/degrees. Host length/height stay geometry inputs. */
+  values: PluginFamilyValues.optional(),
 })
 export type PluginCreateWallRunItem = z.infer<typeof PluginCreateWallRunItem>
 

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

@@ -4,6 +4,7 @@ import {
   BrepHandle,
   ComponentHandle,
   ContourHandle,
+  LineHandle,
   CurveHandle,
   ProfileHandle,
   Vec3Handle,
@@ -28,6 +29,15 @@ import type {
   PluginCreateWallRunItem,
   PluginCreateWindowItem,
 } from "./bulk-items"
+import { PluginWallTopProfile } from "./bulk-items"
+import { PluginWallType } from "../types"
+import {
+  PluginFamilyPlacement,
+  PluginFamilyFloorOptions,
+  PluginFamilySlabOptions,
+  PluginFamilyCeilingOptions,
+  PluginFamilyValues,
+} from "../catalog"
 
 /**
  * `design.create.*` — author new scene-committed BIM entities.
@@ -42,6 +52,12 @@ import type {
  * Footprint objects take a {@linkcode ContourHandle} (outer profile + holes);
  * build one with `snaptrude.core.geom.create.contourFromProfile(s)`.
  *
+ * Family overloads take `{ type, values? }` from `design.catalog`. The family supplies
+ * construction; the contour or axis supplies instance geometry. Geometry uses SU,
+ * while family length overrides use mm and angles use degrees. Omitted parameters
+ * retain family defaults; shared/type, formula and geometry-bound overrides are refused.
+ * Placement never publishes a definition. Unsupported references or geometry fail before mutation.
+ *
  * `door`/`window` place a catalog item into a host wall (the world point is
  * projected onto the wall face to locate the opening; the wall is re-cut in one
  * undo entry) and throw if the point projects outside the wall. `smartLayout` is
@@ -218,20 +234,29 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract slab(
-    contour: ContourHandle,
-    thickness: number,
-    direction?: "up" | "down",
-    slabType?: PluginSlabType,
+    ...args:
+      | [
+          contour: ContourHandle,
+          thickness: number,
+          direction?: "up" | "down",
+          slabType?: PluginSlabType,
+        ]
+      | [contour: ContourHandle, options: PluginFamilySlabOptions]
   ): PluginApiReturn<ComponentHandle>
 
   /**
    * Create a **floor** by extruding a footprint contour by `thickness`
    * (extruded upward).
    *
+   * The native family overload takes `{ type, values?, position? }`. Contour
+   * geometry uses SU; family values use mm. The family supplies layer thickness.
+   * PG2 can split or merge the footprint, so both overloads return an array.
+   * A merge into an existing floor can return no newly created handles.
+   *
    * @param contour - Footprint (outer + holes)
    * @param thickness - Floor thickness (> 0)
    * @param position - Offset from origin
-   * @returns the {@linkcode ComponentHandle} of the created floor
+   * @returns Newly created {@linkcode ComponentHandle}s; an empty array after a merge
    * @throws if the contour is invalid or the thickness is not positive
    *
    * @examplePrompt Create a floor from this room outline
@@ -246,15 +271,15 @@ export abstract class PluginDesignCreateApi {
    * const floor = await snaptrude.design.create.floor(contour, 0.1)
    * ```
    *
-   * @performance For MORE THAN ONE floor, call `design.create.floors(items[])` — one
-   *   host round-trip and ONE undo entry for the whole batch. Looping this single-floor
-   *   creator is N round-trips and N undo entries.
+   * @performance For dimensional floors, `design.create.floors(items[])` uses one
+   *   host round-trip and one undo entry. That bulk method does not accept native
+   *   family options; use this method for a family-backed floor.
    */
   public abstract floor(
-    contour: ContourHandle,
-    thickness: number,
-    position?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
+    ...args:
+      | [contour: ContourHandle, thickness: number, position?: Vec3Handle]
+      | [contour: ContourHandle, options: PluginFamilyFloorOptions]
+  ): PluginApiReturn<ComponentHandle[]>
 
   /**
    * Create **many floors** in one undoable operation (bulk plural of
@@ -319,7 +344,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract roof(
     contour: ContourHandle,
-    thickness: number,
+    thickness: number | PluginFamilyPlacement,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -345,9 +370,9 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract ceiling(
-    contour: ContourHandle,
-    thickness: number,
-    heightFromFloor?: number,
+    ...args:
+      | [contour: ContourHandle, thickness: number, heightFromFloor?: number]
+      | [contour: ContourHandle, options: PluginFamilyCeilingOptions]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -378,10 +403,14 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract column(
-    position: Vec3Handle,
-    crossSection: ContourHandle,
-    height: number,
-    directionUp?: Vec3Handle,
+    ...args:
+      | [
+          position: Vec3Handle,
+          crossSection: ContourHandle,
+          height: number,
+          directionUp?: Vec3Handle,
+        ]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -425,9 +454,9 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract beam(
-    section: ContourHandle,
-    length: number,
-    direction?: Vec3Handle,
+    ...args:
+      | [section: ContourHandle, length: number, direction?: Vec3Handle]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -438,21 +467,27 @@ export abstract class PluginDesignCreateApi {
    * @param height - Wall height (default engine default)
    * @param thickness - Wall thickness (default: the `wallType`'s total layer
    *   thickness when `wallType` is given, else the engine default)
-   * @param wallType - Wall type to build with — the same searchable list the
-   *   Draw tab's Wall Type dropdown offers. Pass a name from
-   *   `design.types.list("wall")` (the summary's `label`, or its `"wall:…"` id).
-   *   Drives the wall's construction layers and default material, and — when
-   *   `thickness` is omitted — its total layer thickness. Default: the engine's
-   *   generic wall.
+   * @param wallType - Legacy label/`wall:` id, or the exact `nativeFamily`
+   *   `{ id, version }` pin from `design.types.list("wall")`. Native pins are
+   *   authorized on every use; selecting a family in Draw is not registration.
+   *   Native pins support straight horizontal centerlines and flat tops only.
+   *   Omit thickness for native pins; a conflicting explicit thickness rejects.
+   *   Default: the engine's generic wall.
    * @param storey - Target storey (integer: `1` ground, `2` first floor, `-1`
    *   basement — same convention as `design.create.space`). The walls are
    *   assigned to it and lifted to its base elevation, all inside the same
    *   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 +496,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 +514,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
@@ -486,8 +531,10 @@ export abstract class PluginDesignCreateApi {
     profile: ProfileHandle,
     height?: number,
     thickness?: number,
-    wallType?: string,
+    wallType?: PluginWallType,
     storey?: number,
+    topProfiles?: (PluginWallTopProfile | null)[],
+    values?: PluginFamilyValues,
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
@@ -496,7 +543,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 +565,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 +586,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")
    * ```
@@ -1636,21 +1689,24 @@ export type PluginDesignCreateBeamArgs = z.infer<
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (default engine default) |
  * | `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) |
+ * | `wallType` | {@linkcode PluginWallType}? | Legacy name/id or exact native `{ id, version }` pin from `design.types.list("wall")` (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,
   height: z.number().optional(),
   thickness: z.number().optional(),
-  wallType: z.string().min(1).optional(),
+  wallType: PluginWallType.optional(),
   storey: z.number().int().optional(),
+  topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
+  values: PluginFamilyValues.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