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

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/bim.ts

@@ -0,0 +1,121 @@
+import * as z from "zod"
+import { ComponentHandle } from "../../handles"
+import type { PluginApiReturn } from "../../types"
+import { PluginConstructionType, PluginFamilyValues } from "./catalog"
+import { PluginFamilyBundleSchema } from "./family"
+
+const id = z.string().min(1).max(300)
+const spaces = z.array(ComponentHandle).min(1).max(1000)
+
+/** Read scope. Omit spaces to inspect the active proposal's sketch spaces. */
+export const PluginBimContextArgs = z.object({ spaces: spaces.optional() }).strict()
+export type PluginBimContextArgs = z.infer<typeof PluginBimContextArgs>
+
+/** Directed graph edge. Side A lies along world-up × curve-direction; side B is opposite.
+ * Region IDs are snapshot identifiers, not component handles. Null means no adjacent region.
+ */
+export const PluginBimEdge = z.object({
+  id,
+  startMm: z.tuple([z.number(), z.number(), z.number()]),
+  endMm: z.tuple([z.number(), z.number(), z.number()]),
+  lengthMm: z.number(),
+  heightMm: z.number(),
+  sideA: id.nullable(),
+  sideB: id.nullable(),
+  wall: ComponentHandle.nullable(),
+  supported: z.boolean(),
+})
+export type PluginBimEdge = z.infer<typeof PluginBimEdge>
+
+/** Construction context is detached. Revision covers geometry, room metadata and construction state. */
+export const PluginBimContext = z.object({
+  revision: id,
+  proposalId: id,
+  units: z.literal("mm"),
+  spaces: z.array(z.object({
+    component: ComponentHandle,
+    label: z.string(),
+    storey: z.number(),
+    eligible: z.boolean(),
+    reason: z.string().optional(),
+  })),
+  regions: z.array(z.object({ id, spaces: z.array(ComponentHandle) })),
+  edges: z.array(PluginBimEdge),
+})
+export type PluginBimContext = z.infer<typeof PluginBimContext>
+
+/** Plan-local key selects either an existing construction or a new project-only native recipe.
+ * Bundles use the native DSL's SU/unit-expression rules; values overrides use mm/degrees.
+ */
+export const PluginBimConstruction = z.union([
+  z.object({ key: id, reference: PluginConstructionType }).strict(),
+  z.object({ key: id, bundle: PluginFamilyBundleSchema }).strict(),
+])
+export type PluginBimConstruction = z.infer<typeof PluginBimConstruction>
+
+/** Every unwalled edge in the selected scope needs exactly one assignment.
+ * The first authored layer faces sideA unless reversed. Alignment sets the initial core-centre offset.
+ * Later parameter edits preserve the offset and reject invalid core alignment.
+ */
+export const PluginBimWallAssignment = z.object({
+  edgeId: id,
+  construction: id,
+  values: PluginFamilyValues.optional(),
+  reversed: z.boolean(),
+  alignment: z.literal("coreCentre"),
+}).strict()
+export type PluginBimWallAssignment = z.infer<typeof PluginBimWallAssignment>
+
+export const PluginBimPrepareArgs = z.object({
+  revision: id,
+  spaces,
+  constructions: z.array(PluginBimConstruction).max(1000),
+  walls: z.array(PluginBimWallAssignment).max(10000),
+}).strict()
+export type PluginBimPrepareArgs = z.infer<typeof PluginBimPrepareArgs>
+
+/** Expected recipe/plan failures are diagnostics. No scene or library change occurs during prepare. */
+export const PluginBimPreparation = z.object({
+  ok: z.boolean(),
+  preparationId: id.optional(),
+  diagnostics: z.array(z.object({ path: z.string(), message: z.string() })),
+})
+export type PluginBimPreparation = z.infer<typeof PluginBimPreparation>
+export const PluginBimCreateArgs = z.object({ preparationId: id }).strict()
+
+/** Source IDs identify removed sketch spaces, not live handles. Successful storeys share one undo step.
+ * Failed storeys remain spaces. Cancellation rolls back the whole conversion. Persistence is queued
+ * through normal model commands; this result is not a durable server-save acknowledgement.
+ */
+export const PluginBimResult = z.object({
+  status: z.enum(["created", "partial", "cancelled", "unchanged"]),
+  convertedSpaceIds: z.array(z.string()),
+  created: z.array(ComponentHandle),
+  kept: z.array(z.object({ space: ComponentHandle, reason: z.string() })),
+})
+export type PluginBimResult = z.infer<typeof PluginBimResult>
+
+/** Agent-driven Sketch-to-BIM. Uses PG2 topology; never redraws routes or publishes library families. */
+export abstract class PluginDesignBimApi {
+  /** Read room adjacency and native conversion eligibility in the active proposal.
+   * @param options Optional explicit spaces; filters edges but keeps adjacent room metadata.
+   * @returns Rooms, directed boundaries in mm, eligibility and revision.
+   * @examplePrompt Inspect the rooms on each side of these sketch wall boundaries
+   */
+  abstract getContext(options?: PluginBimContextArgs): PluginApiReturn<PluginBimContext>
+
+  /** Stage a complete wall-construction assignment. A new prepare replaces this plugin's prior plan.
+   * @param plan Exact context revision, selected spaces, constructions and edge assignments.
+   * @returns Diagnostics or an opaque preparation ID, scoped to the caller and current project.
+   * @examplePrompt Validate wall layer assignments before converting sketch rooms to BIM
+   */
+  abstract prepare(plan: PluginBimPrepareArgs): PluginApiReturn<PluginBimPreparation>
+
+  /** Execute native Sketch-to-BIM. Revalidates scope, catalogue access and construction before mutation.
+   * Uses native progress/cancel controls and worker cancellation. Floors/roofs retain project defaults.
+   * @param preparationId ID returned by prepare. Consumed once; stale or foreign IDs throw PRECONDITION_FAILED.
+   * @returns Created component handles and explicit converted/kept outcomes, including partial success.
+   * @examplePrompt Convert these sketch rooms to BIM with wall layers chosen for each room boundary
+   */
+  abstract create(preparationId: string): PluginApiReturn<PluginBimResult>
+}

package/src/api/design/catalog.ts

@@ -0,0 +1,128 @@
+import * as z from "zod"
+import { ContourHandle, LineHandle, Vec3Handle } from "../../handles"
+import type { PluginApiReturn } from "../../types"
+import { PluginFamilyDefinitionParameter, PluginFamilyBundleSchema } from "./family"
+import { NetworkFamilyContract } from "./networks"
+
+/** Exact saved family identity. A label or a selected Draw type is not an identity. */
+export const PluginSavedFamilyReference = z
+  .object({
+    id: z.string().min(1),
+    version: z.number().int().positive(),
+  })
+  .strict()
+export type PluginSavedFamilyReference = z.infer<
+  typeof PluginSavedFamilyReference
+>
+
+/** Public overrides: physical lengths use mm, angles use degrees. Omitted values retain defaults. */
+export const PluginFamilyValues = z.record(
+  z.string(),
+  z.union([z.number().finite(), z.string(), z.boolean()]),
+)
+export type PluginFamilyValues = z.infer<typeof PluginFamilyValues>
+
+/** Native construction uses a saved family or a project assembly token from the catalogue. */
+export const PluginConstructionType = z.union([
+  PluginSavedFamilyReference,
+  z.string().min(1),
+])
+export type PluginConstructionType = z.infer<typeof PluginConstructionType>
+
+/** Family owns its layers/section. Geometry owns the footprint/axis; it is never a values override. */
+export const PluginFamilyPlacement = z
+  .object({
+    type: PluginConstructionType,
+    values: PluginFamilyValues.optional(),
+  })
+  .strict()
+export type PluginFamilyPlacement = z.infer<typeof PluginFamilyPlacement>
+
+/** Sparse native family edit. Omitted type keeps the component's exact saved reference. */
+export const PluginFamilyUpdates = PluginFamilyPlacement.partial().refine(
+  (updates) => updates.type !== undefined || updates.values !== undefined,
+  { message: "Supply a type or parameter values" },
+)
+export type PluginFamilyUpdates = z.infer<typeof PluginFamilyUpdates>
+
+export const PluginFamilyFloorOptions = PluginFamilyPlacement.extend({
+  position: Vec3Handle.optional(),
+})
+export type PluginFamilyFloorOptions = z.infer<typeof PluginFamilyFloorOptions>
+export const PluginFamilySlabOptions = PluginFamilyPlacement.extend({
+  direction: z.enum(["up", "down"]).optional(),
+})
+export type PluginFamilySlabOptions = z.infer<typeof PluginFamilySlabOptions>
+export const PluginFamilyCeilingOptions = PluginFamilyPlacement.extend({
+  heightFromFloor: z.number().finite().optional(),
+})
+export type PluginFamilyCeilingOptions = z.infer<
+  typeof PluginFamilyCeilingOptions
+>
+export const PluginFamilyContourArgs = z.object({
+  contour: ContourHandle,
+  options: PluginFamilyPlacement,
+})
+export const PluginFamilyAxisArgs = z.object({
+  axis: LineHandle,
+  options: PluginFamilyPlacement,
+})
+
+/** Inventory includes architectural recipes, ordinary PCs, and the existing placement libraries. */
+export const PluginCatalogKind = z.enum([
+  "wall",
+  "floor",
+  "slab",
+  "roof",
+  "ceiling",
+  "beam",
+  "column",
+  "component",
+  "door",
+  "window",
+  "furniture",
+])
+export type PluginCatalogKind = z.infer<typeof PluginCatalogKind>
+export const PluginCatalogReference = z.union([
+  PluginSavedFamilyReference,
+  // Project assemblies retain kind:name; asset tokens retain the underlying library identity.
+  z.string().min(1),
+])
+export type PluginCatalogReference = z.infer<typeof PluginCatalogReference>
+
+/** Read-only capability record. Availability is checked again on every mutation. */
+export const PluginCatalogEntry = z.object({
+  reference: PluginCatalogReference,
+  label: z.string(),
+  kind: PluginCatalogKind,
+  source: z.enum(["native", "revit", "project", "asset"]),
+  createMethods: z.array(z.string()),
+  updateMethods: z.array(z.string()),
+  requirements: z.array(z.string()),
+  unsupportedReason: z.string().optional(),
+  parameters: z.array(PluginFamilyDefinitionParameter).optional(),
+  /** Parameter keys owned by native placement geometry, never accepted as values overrides. */
+  geometryParameters: z.array(z.string()),
+  network: NetworkFamilyContract.optional(),
+  /** get() includes the native wall recipe without opening a Family Studio draft.
+   * Bare recipe lengths use SU; parameter metadata and public values overrides use mm.
+   */
+  construction: PluginFamilyBundleSchema.optional(),
+})
+export type PluginCatalogEntry = z.infer<typeof PluginCatalogEntry>
+export const PluginCatalogListArgs = z.object({
+  kind: PluginCatalogKind.optional(),
+})
+export const PluginCatalogGetArgs = z.object({
+  reference: PluginCatalogReference,
+})
+
+/** Shared read surface over existing libraries. Does not publish, register, or place definitions. */
+export abstract class PluginDesignCatalogApi {
+  /** @param kind Optional element filter. @returns Accessible entries and their supported API paths. */
+  abstract list(kind?: PluginCatalogKind): PluginApiReturn<PluginCatalogEntry[]>
+  /** @param reference Exact reference from list. @returns The current entry, or null when unavailable. */
+  abstract get(
+    reference: PluginCatalogReference,
+  ): PluginApiReturn<PluginCatalogEntry | null>
+}