@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

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

@@ -0,0 +1,197 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { CurveHandle, BBoxComponents } from "../../../handles"
+import { PluginReferenceLineStyle } from "../create"
+
+// ---------------------------------------------------------------------------
+// Records
+// ---------------------------------------------------------------------------
+
+/**
+ * Visual properties of grid lines — the group's defaults and any per-line
+ * overrides share this shape (values mirror the engine's `GridLineProps`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `style` | {@linkcode PluginReferenceLineStyle} | Line style (`"SOLID"` \| `"DASHED"` \| `"DOT_DASH"`) |
+ * | `weight` | `number` | Line weight |
+ * | `color` | `string` | Line color as a `#rrggbb` hex string |
+ * | `showStart` | `boolean` | Whether the start-end tag bubble is shown |
+ * | `showEnd` | `boolean` | Whether the end-end tag bubble is shown |
+ */
+export const PluginGridLineProps = z.object({
+  style: PluginReferenceLineStyle,
+  weight: z.number(),
+  color: z.string(),
+  showStart: z.boolean(),
+  showEnd: z.boolean(),
+})
+export type PluginGridLineProps = z.infer<typeof PluginGridLineProps>
+
+/**
+ * One grid line within a wing.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The line's geometry in **world space** (a line or arc; read coordinates via `core.geom.curve`) |
+ * | `tag` | `string` | The line's grid tag (e.g. `"A"`, `"3"`) |
+ * | `visible` | `boolean` | Persisted per-line visibility |
+ * | `props` | {@linkcode PluginGridLineProps} | **Effective** visual properties (group defaults merged with this line's overrides) |
+ * | `overrides` | `Partial<`{@linkcode PluginGridLineProps}`>`? | This line's raw overrides, when any exist |
+ */
+export const PluginGridLineRecord = z.object({
+  curve: CurveHandle,
+  tag: z.string(),
+  visible: z.boolean(),
+  props: PluginGridLineProps,
+  overrides: PluginGridLineProps.partial().optional(),
+})
+export type PluginGridLineRecord = z.infer<typeof PluginGridLineRecord>
+
+/**
+ * One wing of a grid — a family of parallel lines sharing a local frame.
+ * `spacing` and `span` are measured along the wing's local axes in
+ * Snaptrude units; line addresses used by mutating APIs are
+ * `{ wing, line }` index pairs into these arrays.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spacing` | `number` | Nominal spacing between adjacent lines (Snaptrude units) |
+ * | `tagStart` | `string` | First tag of the wing's deterministic tag sequence |
+ * | `span` | `{ min: number; max: number }`? | Explicit family length along the wing's line axis, when baked |
+ * | `lines` | {@linkcode PluginGridLineRecord}`[]` | The wing's lines, in wing order (index = the `line` address) |
+ */
+export const PluginGridWingRecord = z.object({
+  spacing: z.number(),
+  tagStart: z.string(),
+  span: z.object({ min: z.number(), max: z.number() }).optional(),
+  lines: z.array(PluginGridLineRecord),
+})
+export type PluginGridWingRecord = z.infer<typeof PluginGridWingRecord>
+
+/**
+ * Per-storey 2D-plan visibility of a grid.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `activeStorey` | `number` | The storey the grid belongs to |
+ * | `disabledOnStoreys` | `number[]` | Storeys on whose 2D plan the grid is hidden |
+ */
+export const PluginGridStoreyVisibility = z.object({
+  activeStorey: z.number(),
+  disabledOnStoreys: z.array(z.number()),
+})
+export type PluginGridStoreyVisibility = z.infer<typeof PluginGridStoreyVisibility>
+
+// ---------------------------------------------------------------------------
+// get — args & result
+// ---------------------------------------------------------------------------
+
+/**
+ * Property names readable via {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"angle"` | World rotation about +Y, in **degrees** |
+ * | `"props"` | Group-level default line properties |
+ * | `"storeyVisibility"` | Active storey + storeys where the grid is hidden in 2D |
+ * | `"wings"` | Full wing/line structure with world-space curve handles |
+ * | `"bounds"` | World-space axis-aligned bounding box of the grid geometry |
+ */
+export const PluginGridGetProperty = z.enum([
+  "angle",
+  "props",
+  "storeyVisibility",
+  "wings",
+  "bounds",
+])
+export type PluginGridGetProperty = z.infer<typeof PluginGridGetProperty>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `gridId` | `string` | The grid group ID to query |
+ * | `properties` | {@linkcode PluginGridGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginGridGetArgs = z.object({
+  gridId: z.string(),
+  properties: z.array(PluginGridGetProperty),
+})
+export type PluginGridGetArgs = z.infer<typeof PluginGridGetArgs>
+
+/**
+ * Result of {@linkcode PluginDesignQueryGridsApi.get} — only the requested
+ * properties are present.
+ */
+export const PluginGridGetResult = z
+  .object({
+    angle: z.number(),
+    props: PluginGridLineProps,
+    storeyVisibility: PluginGridStoreyVisibility,
+    wings: z.array(PluginGridWingRecord),
+    bounds: BBoxComponents,
+  })
+  .partial()
+export type PluginGridGetResult = z.infer<typeof PluginGridGetResult>
+
+// ---------------------------------------------------------------------------
+// Abstract API
+// ---------------------------------------------------------------------------
+
+/**
+ * `design.query.grids.*` — structural-grid-specific reads.
+ *
+ * A **grid** (grid group) is a structural/documentation grid: one or more
+ * *wings* (families of parallel lines with a shared local frame), each holding
+ * tagged grid *lines* (straight lines, or a lone arc). Enumerate grids with
+ * `design.query.listGrids`; read an individual grid's structure here.
+ *
+ * Lines have no stable identity of their own — mutating APIs address them
+ * positionally as `{ wing, line }` index pairs into the `wings` arrays
+ * returned by {@linkcode get}. Structural edits (adding/removing lines,
+ * count changes) re-index lines; re-query after mutating.
+ *
+ * Accessed via `snaptrude.design.query.grids`.
+ */
+export abstract class PluginDesignQueryGridsApi {
+  constructor() {}
+
+  /**
+   * Get properties of a grid by its ID.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result. `wings` is the heavy
+   * read (it registers a world-space {@linkcode CurveHandle} per line);
+   * request it only when the geometry is needed.
+   *
+   * Units: `angle` is in **degrees** (positive = CCW about +Y); `spacing`,
+   * `span`, `bounds`, and curve coordinates are in **Snaptrude units**,
+   * world space.
+   *
+   * @param gridId - The unique grid group ID
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginGridGetProperty}.
+   * @returns A partial {@linkcode PluginGridGetResult} containing only the
+   *   requested properties
+   * @throws If the grid does not exist
+   *
+   * @examplePrompt What is the spacing of this grid?
+   * @examplePrompt Read the grid line tags on this structural grid
+   * @examplePrompt Get the geometry of every line in this grid
+   * @examplePrompt Which storeys is this grid hidden on?
+   *
+   * # Example
+   * ```ts
+   * const [grid] = await snaptrude.design.query.listGrids()
+   * const { wings } = await snaptrude.design.query.grids.get(grid, ["wings"])
+   * // wings[0].lines[0].curve is an opaque CurveHandle in world space;
+   * // read its coordinates via `snaptrude.core.geom.curve`.
+   * ```
+   */
+  public abstract get(
+    gridId: string,
+    properties: z.infer<typeof PluginGridGetProperty>[],
+  ): PluginApiReturn<PluginGridGetResult>
+}

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

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle, BBoxComponents } from "../../../handles"
+import type { MassParametersRecord } from "../../../massParameters"
 import {
   PluginSpaceType,
   PluginMassType,
@@ -11,6 +12,7 @@ import { PluginStaircasePreset } from "../create"
 import { PluginDesignQueryGeometryApi } from "./geometry"
 import { PluginDesignQuerySpacesApi } from "./spaces"
 import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
+import { PluginDesignQueryGridsApi } from "./grids"
 
 // ---------------------------------------------------------------------------
 // Entity type vocabulary
@@ -27,6 +29,7 @@ import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
  * | `"wall"` | Wall |
  * | `"space"` | Space (a room mass) |
  * | `"mass"` | Generic mass (non-room) |
+ * | `"void"` | A hosted cutting solid, separate from spaces and masses |
  * | `"door"` | Door |
  * | `"window"` | Window |
  * | `"floor"` | Floor |
@@ -41,11 +44,14 @@ import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
  * | `"curtainWall"` | Parametric curtain wall |
  * | `"mullion"` | Curtain-wall mullion |
  * | `"panel"` | Curtain-wall panel |
+ * | `"parametricComponent"` | A placed parametric family instance (native or Revit-imported). Its geometry is rebuilt from `design.family` parameters, so read and drive it through `design.family.getParameters` / `setParameters` rather than editing its meshes. |
+ * | `"grid"` | Structural grid group |
  */
 export const PluginEntityType = z.enum([
   "wall",
   "space",
   "mass",
+  "void",
   "door",
   "window",
   "floor",
@@ -60,6 +66,8 @@ export const PluginEntityType = z.enum([
   "curtainWall",
   "mullion",
   "panel",
+  "parametricComponent",
+  "grid",
 ])
 export type PluginEntityType = z.infer<typeof PluginEntityType>
 
@@ -173,7 +181,6 @@ export type PluginDesignQueryComponentsArgs = z.infer<
  * | `isLocked` | `boolean` | Lock flag |
  * | `isHidden` | `boolean` | User-hidden flag |
  * | `isSelected` | `boolean` | Current selection state |
- * | `isVisible` | `boolean` | Whether the entity currently has a visible representation on canvas (user hide flag AND LOD/mode gating both considered); read-only |
  * | `boundingBox` | {@linkcode BBoxComponents} | World-space AABB |
  * | `adjacency` | `{ spaceId: string; value: number }[]` | Adjacency relationships (spaces/masses only). `value`: `2` = Direct (required), `1` = Indirect or physical contact, `-1` = Restricted; `0` entries are filtered out. `[]` when adjacency has never been computed — see `program.adjacency.compute`. |
  */
@@ -193,7 +200,6 @@ export const PluginEntityProperties = z
     isLocked: z.boolean(),
     isHidden: z.boolean(),
     isSelected: z.boolean(),
-    isVisible: z.boolean(),
     boundingBox: BBoxComponents,
     adjacency: z.array(z.object({ spaceId: z.string(), value: z.number() })),
   })
@@ -306,6 +312,8 @@ export abstract class PluginDesignQueryApi {
   public abstract spaces: PluginDesignQuerySpacesApi
   /** Reference-line-specific reads. See {@linkcode PluginDesignQueryReferenceLinesApi}. */
   public abstract referenceLines: PluginDesignQueryReferenceLinesApi
+  /** Structural-grid-specific reads. See {@linkcode PluginDesignQueryGridsApi}. */
+  public abstract grids: PluginDesignQueryGridsApi
 
   constructor() {}
 
@@ -348,6 +356,9 @@ export abstract class PluginDesignQueryApi {
    * List all entities of one BIM object type — wall, door, slab, panel, and so
    * on — optionally narrowed by the shared filter.
    *
+   * `"void"` lists native Void components (made by `design.create.void`),
+   * as does `design.query.listVoids`. `"mass"` excludes voids.
+   *
    * @param type - the {@linkcode PluginEntityType} to list
    * @param filter - an optional {@linkcode PluginEntityFilter}
    * @returns matching entities as {@linkcode ComponentHandle}`[]`
@@ -439,6 +450,8 @@ export abstract class PluginDesignQueryApi {
    * List all the generic masses (non-room massing volumes) in the project,
    * optionally filtered by storey, building, label, mass type, or region.
    *
+   * Excludes Void components. Use `design.query.listVoids` for hosted cutters.
+   *
    * @param filter - an optional {@linkcode PluginEntityFilter}
    * @returns mass {@linkcode ComponentHandle}`[]`
    *
@@ -459,6 +472,19 @@ export abstract class PluginDesignQueryApi {
     filter?: PluginEntityFilter,
   ): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * List Void components, excluding masses and spaces. Voids cut their hosts.
+   * Use family queries for authored parametric families with a cut relationship.
+   *
+   * @param filter - Optional storey, building, selection, or region filter.
+   * @returns Void component handles, or an empty array when none match.
+   * @example
+   * const voids = await snaptrude.design.query.listVoids({ storeys: [1] })
+   */
+  public abstract listVoids(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
   /**
    * List all the doors in the project, optionally filtered by storey, building,
    * selection state, or region.
@@ -723,6 +749,27 @@ export abstract class PluginDesignQueryApi {
     filter?: PluginEntityFilter,
   ): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * List all the structural grids (grid groups) in the project, optionally
+   * filtered by storey, building, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns grid-group {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the structural grids in the model
+   * @examplePrompt How many grids are on the ground floor?
+   * @examplePrompt Show the grids on this storey
+   * @examplePrompt Which grids are currently selected?
+   *
+   * # Example
+   * ```ts
+   * const groundFloorGrids = await snaptrude.design.query.listGrids({ storeys: [1] })
+   * ```
+   */
+  public abstract listGrids(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
   // ── single-entity access & identity ─────────────────────────────────────────
 
   /**
@@ -854,7 +901,8 @@ export abstract class PluginDesignQueryApi {
 
   /**
    * List an entity's direct child entities — for example the doors and windows
-   * hosted in a wall.
+   * hosted in a wall, or the voids (holes, shafts, openings) cut in a slab,
+   * floor, roof or ceiling by `design.create.void`.
    * @param component - the entity's {@linkcode ComponentHandle}
    * @returns child {@linkcode ComponentHandle}`[]` (`[]` if none)
    *
@@ -862,6 +910,7 @@ export abstract class PluginDesignQueryApi {
    * @examplePrompt Show the child elements of the selected object
    * @examplePrompt Which openings belong to this wall?
    * @examplePrompt List everything nested under this mass
+   * @examplePrompt List all holes in this slab
    *
    * # Example
    * ```ts
@@ -881,7 +930,8 @@ export abstract class PluginDesignQueryApi {
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
-   * Get an entity's host/parent entity (e.g. the wall a door is cut into).
+   * Get an entity's host/parent entity (e.g. the wall a door is cut into, or
+   * the slab, floor, roof or ceiling a void is cut through).
    * @param component - the entity's {@linkcode ComponentHandle}
    * @returns the host {@linkcode ComponentHandle}, or `null` if top-level
    *
@@ -889,6 +939,7 @@ export abstract class PluginDesignQueryApi {
    * @examplePrompt Find the parent of the selected window
    * @examplePrompt What is this element attached to?
    * @examplePrompt Which wall hosts this window?
+   * @examplePrompt Which slab is this shaft in?
    *
    * # Example
    * ```ts
@@ -1014,6 +1065,55 @@ export abstract class PluginDesignQueryApi {
     staircase: ComponentHandle,
   ): PluginApiReturn<PluginStaircaseParams | null>
 
+  /**
+   * Read a mass's creation-parameter record — the recipe it was built from
+   * (`kind` plus the values that constructor was called with). Present on
+   * masses committed from a `core.geom.create` brep constructor that carries a
+   * recipe: {@linkcode MassParametersRecord} covers the four primitives
+   * (sphere, cylinder, cone, torus), extrusions, revolutions, lofts and sweeps.
+   *
+   * A fillet, chamfer, shell or offset of a recorded solid keeps the record
+   * too: `kind` stays the base constructor and the operation is appended to the
+   * record's `operations` list. Edit any of it with `design.update.parameters`.
+   *
+   * `null` for everything else — drawn masses, imported geometry, booleans,
+   * split parts, `brepFromFaces` / `brepFromMesh`, and results built on a
+   * source that carried no record — and for a mass whose record no longer
+   * matches what is on
+   * screen (a later free-form edit dropped the recipe, or the mass carries a
+   * baked scale). `null` too when the recipe was not recordable: the record
+   * schema has its own caps (a sweep path of at most 512 points, a loft of at
+   * most 32 sections, at most 8 chained `operations`, at most 256 curves in one
+   * profile loop and 64 holes in one contour), and a mass built past one of
+   * them — through a route that does not enforce the matching creator cap —
+   * commits as ordinary geometry carrying no record. The `operations` cap is
+   * the one an agent can walk into by accident: a 9th chained
+   * fillet/chamfer/shell/offset drops the record silently, so the result
+   * commits as ordinary geometry and reads back `null` here. A record is never
+   * reported unless it is still the truth.
+   *
+   * Points and axes come back in **world** coordinates. Pure read — nothing is
+   * created or modified.
+   *
+   * @param component - the mass's {@linkcode ComponentHandle}
+   * @returns the {@linkcode MassParametersRecord}, or `null`
+   *
+   * @examplePrompt What radius is this sphere?
+   * @examplePrompt Is this mass parametric?
+   * @examplePrompt Read back the dome's creation parameters
+   * @examplePrompt How tall was this cylinder made?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses({ isSelected: true })
+   * const params = await snaptrude.design.query.getParameters(mass)
+   * if (params?.kind === "sphere") console.log("radius:", params.values.radius)
+   * ```
+   */
+  public abstract getParameters(
+    component: ComponentHandle,
+  ): PluginApiReturn<MassParametersRecord | null>
+
   /**
    * Get the **union** axis-aligned bounding box enclosing a set of entities.
    *
@@ -1090,7 +1190,6 @@ export abstract class PluginDesignQueryApi {
   ): PluginApiReturn<PluginStoreyOutlineResult>
 }
 
-
 /** A point in the world-space plan (x, z) projection, Snaptrude internal units. */
 export const PluginOutlinePlanPoint = z.object({ x: z.number(), z: z.number() })
 export type PluginOutlinePlanPoint = z.infer<typeof PluginOutlinePlanPoint>
@@ -1147,3 +1246,4 @@ export type PluginStoreyOutlineResult = z.infer<
 export * from "./geometry"
 export * from "./spaces"
 export * from "./referenceLines"
+export * from "./grids"

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

@@ -124,41 +124,6 @@ export abstract class PluginDesignQuerySpacesApi {
   public abstract getEnclosure(
     space: ComponentHandle,
   ): PluginApiReturn<PluginSpaceEnclosure | null>
-
-  /**
-   * List the space's **engine-generated BIM components** — the walls, floors
-   * and slabs the parametric engine derived from this space, grouped by kind.
-   *
-   * Unlike {@linkcode getEnclosure} (a geometric best-effort match), this read
-   * reports the engine's own derivation records, so every returned handle is a
-   * component the engine created *for this space*.
-   *
-   * The derived set is NOT stable across writes: a merge/split/rebuild of the
-   * space graph retires members and creates successors — re-query after any
-   * write that touches the space. This is the churn-recovery anchor: when a
-   * cached derived handle goes stale, call this again to pick up the current
-   * set.
-   *
-   * @param space - The space (room mass) to read
-   * @returns the generated component handles, grouped by kind
-   *   ({@linkcode PluginSpaceGeneratedBim}); a group is `[]` when the engine
-   *   derived nothing of that kind
-   * @throws If the space does not exist or the component is not a space/mass
-   *
-   * @examplePrompt Which walls did this room generate?
-   * @examplePrompt List the BIM components derived from the selected space
-   * @examplePrompt Get the floors and slabs that belong to this room
-   *
-   * # Example
-   * ```ts
-   * const [space] = await snaptrude.design.query.listSpaces()
-   * const bim = await snaptrude.design.query.spaces.listGeneratedBim(space)
-   * console.log(`${bim.walls.length} walls, ${bim.floors.length} floors`)
-   * ```
-   */
-  public abstract listGeneratedBim(
-    space: ComponentHandle,
-  ): PluginApiReturn<PluginSpaceGeneratedBim>
 }
 
 /**
@@ -308,36 +273,3 @@ export const PluginSpaceEnclosure = z.object({
   adjacentSpaces: z.array(PluginAdjacentSpace),
 })
 export type PluginSpaceEnclosure = z.infer<typeof PluginSpaceEnclosure>
-
-/**
- * Arguments for {@linkcode PluginDesignQuerySpacesApi.listGeneratedBim}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
- */
-export const PluginDesignQuerySpacesListGeneratedBimArgs = z.object({
-  space: ComponentHandle,
-})
-export type PluginDesignQuerySpacesListGeneratedBimArgs = z.infer<
-  typeof PluginDesignQuerySpacesListGeneratedBimArgs
->
-
-/**
- * Result of {@linkcode PluginDesignQuerySpacesApi.listGeneratedBim} — the
- * space's engine-generated BIM component handles, grouped by kind. The set
- * changes whenever a write merges/splits/rebuilds the space graph — re-query
- * after writes rather than caching it.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `walls` | {@linkcode ComponentHandle}`[]` | Walls the engine derived from the space |
- * | `floors` | {@linkcode ComponentHandle}`[]` | Floors the engine derived from the space |
- * | `slabs` | {@linkcode ComponentHandle}`[]` | Slabs the engine derived from the space |
- */
-export const PluginSpaceGeneratedBim = z.object({
-  walls: z.array(ComponentHandle),
-  floors: z.array(ComponentHandle),
-  slabs: z.array(ComponentHandle),
-})
-export type PluginSpaceGeneratedBim = z.infer<typeof PluginSpaceGeneratedBim>

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

@@ -1,23 +1,25 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 
+/** An exact saved native wall family. Access is checked on every use; Draw selection is not registration. */
+export const PluginNativeWallType = z.object({
+  id: z.string().min(1),
+  version: z.number().int().positive(),
+})
+export type PluginNativeWallType = z.infer<typeof PluginNativeWallType>
+
+/** Legacy project type name/id, or an exact authorized native wall family pin. */
+export const PluginWallType = z.union([z.string().trim().min(1), PluginNativeWallType])
+export type PluginWallType = z.infer<typeof PluginWallType>
+
 /**
- * `snaptrude.design.types` — READ-ONLY reference over the project's building
- * **type / assembly** system (the Project Properties layer stacks: External /
- * Internal walls, slabs, floors, ceilings, roofs). A type bundles a labelled
- * layer stack — each layer's role, thickness (engine units) and material — plus a
- * summed total thickness. Both the built-in defaults and any team/user-added types
- * are surfaced.
- *
- * Types are plain value records ({@linkcode PluginBuildingType}) — NOT scene
- * entities/handles. A type's `id` is a stable `"<kind>:<name>"` token
- * (e.g. `"wall:brickWithPlasterAndPaint"`) returned by
- * {@linkcode PluginDesignTypesApi.list} and consumed by
- * {@linkcode PluginDesignTypesApi.get}. Reads never throw — an unknown id yields
- * `null`; a kind with no types yields `[]`.
- *
- * These are reads only: there is no engine seam to author a type from a plugin
- * (types are created through the construction/project-properties UI).
+ * Read-only project assemblies and authorized saved native wall families.
+ * Legacy ids use `"<kind>:<name>"`. Native wall records carry `nativeFamily`:
+ * pass that exact `{ id, version }` pin to get, create.walls, create.wallRuns,
+ * or update.wall. Labels and bare definition ids do not select native families.
+ * Native lengths use Snaptrude units (1 SU = 254 mm).
+ * Missing ids return null; catalog/network failures reject rather than return
+ * an incomplete catalog. Author native families with design.family.
  */
 export abstract class PluginDesignTypesApi {
   constructor() {}
@@ -46,10 +48,10 @@ export abstract class PluginDesignTypesApi {
   ): PluginApiReturn<PluginBuildingTypeSummary[]>
 
   /**
-   * Get one building type by its `"<kind>:<name>"` id — its labelled layer stack
+   * Get one building type by its legacy id or exact native wall pin — its labelled layer stack
    * (each layer's role, thickness and material) plus the summed total thickness.
    *
-   * @param typeId The type id from {@linkcode PluginDesignTypesApi.list} (e.g. `"wall:exposedConcrete"`)
+   * @param typeId The legacy id or nativeFamily pin from {@linkcode PluginDesignTypesApi.list}
    * @returns The full type, or `null` if no type matches
    *
    * @examplePrompt What layers make up this wall type?
@@ -60,11 +62,11 @@ export abstract class PluginDesignTypesApi {
    * # Example
    * ```ts
    * const [first] = await snaptrude.design.types.list("wall")
-   * const type = await snaptrude.design.types.get(first.id)
+   * const type = await snaptrude.design.types.get(first.nativeFamily ?? first.id)
    * if (type) for (const layer of type.layers) console.log(layer.name, layer.thickness)
    * ```
    */
-  public abstract get(typeId: string): PluginApiReturn<PluginBuildingType | null>
+  public abstract get(typeId: PluginWallType): PluginApiReturn<PluginBuildingType | null>
 }
 
 /** The building-type families exposed by {@linkcode PluginDesignTypesApi}. */
@@ -85,6 +87,8 @@ export const PluginTypeLayer = z.object({
   name: z.string(),
   role: z.string(),
   thickness: z.number(),
+  /** Native authored core membership. Never inferred from material or layer name. */
+  isCore: z.boolean().optional(),
   material: z
     .object({
       name: z.string(),
@@ -99,7 +103,7 @@ export type PluginTypeLayer = z.infer<typeof PluginTypeLayer>
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `id` | `string` | Stable `"<kind>:<name>"` token — pass to `design.types.get` |
+ * | `id` | `string` | Legacy `"<kind>:<name>"` token or native definition id; native lookups use `nativeFamily` |
  * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
  * | `label` | `string` | Human-readable label |
  * | `isDefault` | `boolean` | `true` for a built-in type, `false` for a team/user type |
@@ -111,6 +115,8 @@ export const PluginBuildingTypeSummary = z.object({
   label: z.string(),
   isDefault: z.boolean(),
   thickness: z.number(),
+  /** Present for native walls. Pass the whole pin to get/create/update, not its label or bare id. */
+  nativeFamily: PluginNativeWallType.optional(),
 })
 export type PluginBuildingTypeSummary = z.infer<typeof PluginBuildingTypeSummary>
 
@@ -119,7 +125,7 @@ export type PluginBuildingTypeSummary = z.infer<typeof PluginBuildingTypeSummary
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `id` | `string` | Stable `"<kind>:<name>"` token |
+ * | `id` | `string` | Legacy type token or native definition id |
  * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
  * | `label` | `string` | Human-readable label |
  * | `isDefault` | `boolean` | `true` for a built-in type |
@@ -148,9 +154,10 @@ export type PluginDesignTypesListArgs = z.infer<typeof PluginDesignTypesListArgs
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `typeId` | `string` | The `"<kind>:<name>"` id from `design.types.list` |
+ * | `typeId` | {@linkcode PluginWallType} | A legacy `"<kind>:<name>"` id or exact `nativeFamily` pin from `design.types.list` |
  */
 export const PluginDesignTypesGetArgs = z.object({
-  typeId: z.string(),
+  // Preserve legacy lookup behavior: malformed string ids return null in the host.
+  typeId: z.union([z.string(), PluginNativeWallType]),
 })
 export type PluginDesignTypesGetArgs = z.infer<typeof PluginDesignTypesGetArgs>