@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

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

@@ -1,179 +1,181 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Handle } from "../../../handles"
-import { BooleanOutcome } from "../shared"
-
-/**
- * `snaptrude.design.boolean` — OpenCascade CSG on scene masses/spaces.
- *
- * Every method **commits** the operation as one undoable step (engine `run()`
- * queues create/delete/group/dimension commands, `execute()` runs them through
- * `CommandManager`) and returns the committed {@linkcode BooleanOutcome}. Failures
- * **throw** (RPC rejects) — no `Result<>` monad crosses the boundary.
- *
- * Eligibility (all inputs): a `Mass` that is a room OR a DEPARTMENT, has a brep, is
- * unlocked (mesh + bucket), visible, and NOT in a parametric-copy group; the whole
- * set must be all-planar OR all-non-planar; **≥2** components; all inputs share one
- * group or are ungrouped; inputs must be adjacent/overlapping.
- *
- * `design.boolean.subtract` is a **CSG geometry delete** — distinct from
- * `design.delete.entities` (hard entity removal) and `design.erase.edge`
- * (adjacency-edge topology op).
- *
- * TRANSPORT: positional args per method.
- */
-export abstract class PluginDesignBooleanApi {
-  constructor() {}
-
-  /**
-   * Fuse two or more masses into a single combined mass (`A ∪ B ∪ …`) — a boolean
-   * (CSG) union that merges the adjacent or overlapping inputs into one solid,
-   * committed as a single undoable step. Order-independent.
-   * @param components - The ≥2 entities to fuse (order-independent)
-   * @param options - Optional output offset — {@linkcode BooleanOptions}
-   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
-   * @throws if inputs are ineligible, disjoint, non-manifold when joined, span
-   *   different groups, or the CSG yields no / invalid geometry.
-   *
-   * @examplePrompt Merge these two masses into one
-   * @examplePrompt Union the selected volumes into a single mass
-   * @examplePrompt Combine the overlapping rooms into one shape
-   * @examplePrompt Join the tower and podium blocks together
-   * @examplePrompt Fuse all the selected massing blocks into a single solid
-   *
-   * # Example
-   * ```ts
-   * // Fuse the overlapping massing blocks on the ground storey into one solid
-   * const masses = await snaptrude.design.query.listMasses({ storeys: [1] })
-   * const { created, deleted } = await snaptrude.design.boolean.union(masses)
-   * console.log("created", created.length, "mass; consumed", deleted.length)
-   * ```
-   */
-  public abstract union(
-    components: ComponentHandle[],
-    options?: BooleanOptions,
-  ): PluginApiReturn<BooleanOutcome>
-
-  /**
-   * Cut one or more tool masses out of a target mass (`target − ⋃tools`) — a
-   * boolean (CSG) subtraction that carves the tools' volume out of the target and
-   * commits the remainder as a single undoable step.
-   *
-   * ORDER-SENSITIVE: the host seeds `[target, ...tools]`; index 0 is the arg brep,
-   * the rest are tool breps. `deleted` includes the target AND every tool;
-   * `created` is the remainder mass(es).
-   * @param target - The entity subtracted FROM (arg brep)
-   * @param tools - The ≥1 entities subtracted (tool breps)
-   * @param options - Optional output offset — {@linkcode BooleanOptions}
-   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
-   * @throws as {@linkcode union}; a `NoResult` here carries the "select the target
-   *   object first" hint from the engine.
-   *
-   * @examplePrompt Cut this shape out of the bigger mass
-   * @examplePrompt Subtract the cylinder from the building volume
-   * @examplePrompt Punch an opening through this block using the small box
-   * @examplePrompt Carve the courtyard volume out of the main massing
-   * @examplePrompt Remove the overlapping part of mass B from mass A
-   *
-   * # Example
-   * ```ts
-   * // Order matters: the first arg is the target, the array holds the tools
-   * const [building, courtyard] = await snaptrude.design.selection.get()
-   * const { created, deleted } = await snaptrude.design.boolean.subtract(building, [courtyard])
-   * // deleted includes the target AND every tool; created is the remainder
-   * ```
-   */
-  public abstract subtract(
-    target: ComponentHandle,
-    tools: ComponentHandle[],
-    options?: BooleanOptions,
-  ): PluginApiReturn<BooleanOutcome>
-
-  /**
-   * Keep only the overlapping volume of exactly two masses (`A ∩ B`) — a boolean
-   * (CSG) intersection that discards everything outside the shared region and
-   * commits the overlap as a single undoable step. Order-independent.
-   *
-   * HARD constraint: **EXACTLY 2** components (schema `.length(2)`; the engine
-   * also throws `MoreThan2ComponentsForIntersect` on >2).
-   * @param components - **EXACTLY 2** entities to intersect (order-independent)
-   * @param options - Optional output offset — {@linkcode BooleanOptions}
-   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
-   * @throws as {@linkcode union}, plus `MoreThan2ComponentsForIntersect` on >2.
-   *
-   * @examplePrompt Keep only the part where these two masses overlap
-   * @examplePrompt Intersect the two selected volumes
-   * @examplePrompt Give me the common volume between the tower and the zoning envelope
-   * @examplePrompt Trim this mass down to just its overlap with the other one
-   *
-   * # Example
-   * ```ts
-   * // Keep only the overlap of the tower and the zoning envelope (EXACTLY 2 inputs),
-   * // shifting the result mass 10 units in x via the optional offset
-   * const [tower, envelope] = await snaptrude.design.query.listMasses()
-   * const offset = await snaptrude.core.math.vec3.new(10, 0, 0)
-   * const { created } = await snaptrude.design.boolean.intersect([tower, envelope], { offset })
-   * ```
-   */
-  public abstract intersect(
-    components: ComponentHandle[],
-    options?: BooleanOptions,
-  ): PluginApiReturn<BooleanOutcome>
-}
-
-/**
- * Optional knobs shared by all boolean ops. The only safe one is a world-space
- * translation applied to the output mass(es) — maps to `Boolean3dOperation.offset`.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `offset` | {@linkcode Vec3Handle} | Translation added to the created result mass(es) (default: none) |
- */
-export const BooleanOptions = z.object({
-  offset: Vec3Handle.optional(),
-})
-export type BooleanOptions = z.infer<typeof BooleanOptions>
-
-/**
- * Arguments for {@linkcode PluginDesignBooleanApi.union}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | The ≥2 entities to fuse (order-independent) |
- * | `options` | {@linkcode BooleanOptions} | Optional output offset |
- */
-export const PluginDesignBooleanUnionArgs = z.object({
-  components: z.array(ComponentHandle).min(2),
-  options: BooleanOptions.optional(),
-})
-export type PluginDesignBooleanUnionArgs = z.infer<typeof PluginDesignBooleanUnionArgs>
-
-/**
- * Arguments for {@linkcode PluginDesignBooleanApi.subtract}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `target` | {@linkcode ComponentHandle} | The entity subtracted FROM (arg brep) |
- * | `tools` | {@linkcode ComponentHandle}`[]` | The ≥1 entities subtracted (tool breps) |
- * | `options` | {@linkcode BooleanOptions} | Optional output offset |
- */
-export const PluginDesignBooleanSubtractArgs = z.object({
-  target: ComponentHandle,
-  tools: z.array(ComponentHandle).min(1),
-  options: BooleanOptions.optional(),
-})
-export type PluginDesignBooleanSubtractArgs = z.infer<typeof PluginDesignBooleanSubtractArgs>
-
-/**
- * Arguments for {@linkcode PluginDesignBooleanApi.intersect}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | **EXACTLY 2** entities to intersect (order-independent) |
- * | `options` | {@linkcode BooleanOptions} | Optional output offset |
- */
-export const PluginDesignBooleanIntersectArgs = z.object({
-  components: z.array(ComponentHandle).length(2),
-  options: BooleanOptions.optional(),
-})
-export type PluginDesignBooleanIntersectArgs = z.infer<typeof PluginDesignBooleanIntersectArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { BooleanOutcome } from "../shared"
+
+/**
+ * `snaptrude.design.boolean` — OpenCascade CSG on scene masses/spaces.
+ *
+ * Every method **commits** the operation as one undoable step (engine `run()`
+ * queues create/delete/group/dimension commands, `execute()` runs them through
+ * `CommandManager`) and returns the committed {@linkcode BooleanOutcome}. Failures
+ * **throw** (RPC rejects) — no `Result<>` monad crosses the boundary.
+ *
+ * Eligibility (all inputs): a `Mass` that is a room OR a DEPARTMENT, has a brep, is
+ * unlocked (mesh + bucket), visible, and NOT in a parametric-copy group; the whole
+ * set must be all-planar OR all-non-planar; **≥2** components; all inputs share one
+ * group or are ungrouped; inputs must be adjacent/overlapping.
+ *
+ * `design.boolean.subtract` is a **CSG geometry delete** — distinct from
+ * `design.delete.entities` (hard entity removal) and `design.erase.edge`
+ * (adjacency-edge topology op).
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignBooleanApi {
+  constructor() {}
+
+  /**
+   * Fuse two or more masses into a single combined mass (`A ∪ B ∪ …`) — a boolean
+   * (CSG) union that merges the adjacent or overlapping inputs into one solid,
+   * committed as a single undoable step. Order-independent.
+   * @param components - The ≥2 entities to fuse (order-independent)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws if inputs are ineligible, disjoint, non-manifold when joined, span
+   *   different groups, or the CSG yields no / invalid geometry.
+   *
+   * @examplePrompt Merge these two masses into one
+   * @examplePrompt Union the selected volumes into a single mass
+   * @examplePrompt Combine the overlapping rooms into one shape
+   * @examplePrompt Join the tower and podium blocks together
+   * @examplePrompt Fuse all the selected massing blocks into a single solid
+   *
+   * # Example
+   * ```ts
+   * // Fuse the overlapping massing blocks on the ground storey into one solid
+   * const masses = await snaptrude.design.query.listMasses({ storeys: [1] })
+   * const { created, deleted } = await snaptrude.design.boolean.union(masses)
+   * console.log("created", created.length, "mass; consumed", deleted.length)
+   * ```
+   */
+  public abstract union(
+    components: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+
+  /**
+   * Cut one or more tool masses out of a target mass (`target − ⋃tools`) — a
+   * boolean (CSG) subtraction that carves the tools' volume out of the target and
+   * commits the remainder as a single undoable step.
+   *
+   * Masses only. Slabs, floors and roofs take holes through `design.create.void`.
+   *
+   * ORDER-SENSITIVE: the host seeds `[target, ...tools]`; index 0 is the arg brep,
+   * the rest are tool breps. `deleted` includes the target AND every tool;
+   * `created` is the remainder mass(es).
+   * @param target - The entity subtracted FROM (arg brep)
+   * @param tools - The ≥1 entities subtracted (tool breps)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws as {@linkcode union}; a `NoResult` here carries the "select the target
+   *   object first" hint from the engine.
+   *
+   * @examplePrompt Cut this shape out of the bigger mass
+   * @examplePrompt Subtract the cylinder from the building volume
+   * @examplePrompt Punch an opening through this block using the small box
+   * @examplePrompt Carve the courtyard volume out of the main massing
+   * @examplePrompt Remove the overlapping part of mass B from mass A
+   *
+   * # Example
+   * ```ts
+   * // Order matters: the first arg is the target, the array holds the tools
+   * const [building, courtyard] = await snaptrude.design.selection.get()
+   * const { created, deleted } = await snaptrude.design.boolean.subtract(building, [courtyard])
+   * // deleted includes the target AND every tool; created is the remainder
+   * ```
+   */
+  public abstract subtract(
+    target: ComponentHandle,
+    tools: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+
+  /**
+   * Keep only the overlapping volume of exactly two masses (`A ∩ B`) — a boolean
+   * (CSG) intersection that discards everything outside the shared region and
+   * commits the overlap as a single undoable step. Order-independent.
+   *
+   * HARD constraint: **EXACTLY 2** components (schema `.length(2)`; the engine
+   * also throws `MoreThan2ComponentsForIntersect` on >2).
+   * @param components - **EXACTLY 2** entities to intersect (order-independent)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws as {@linkcode union}, plus `MoreThan2ComponentsForIntersect` on >2.
+   *
+   * @examplePrompt Keep only the part where these two masses overlap
+   * @examplePrompt Intersect the two selected volumes
+   * @examplePrompt Give me the common volume between the tower and the zoning envelope
+   * @examplePrompt Trim this mass down to just its overlap with the other one
+   *
+   * # Example
+   * ```ts
+   * // Keep only the overlap of the tower and the zoning envelope (EXACTLY 2 inputs),
+   * // shifting the result mass 10 units in x via the optional offset
+   * const [tower, envelope] = await snaptrude.design.query.listMasses()
+   * const offset = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const { created } = await snaptrude.design.boolean.intersect([tower, envelope], { offset })
+   * ```
+   */
+  public abstract intersect(
+    components: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+}
+
+/**
+ * Optional knobs shared by all boolean ops. The only safe one is a world-space
+ * translation applied to the output mass(es) — maps to `Boolean3dOperation.offset`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `offset` | {@linkcode Vec3Handle} | Translation added to the created result mass(es) (default: none) |
+ */
+export const BooleanOptions = z.object({
+  offset: Vec3Handle.optional(),
+})
+export type BooleanOptions = z.infer<typeof BooleanOptions>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.union}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The ≥2 entities to fuse (order-independent) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanUnionArgs = z.object({
+  components: z.array(ComponentHandle).min(2),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanUnionArgs = z.infer<typeof PluginDesignBooleanUnionArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.subtract}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `target` | {@linkcode ComponentHandle} | The entity subtracted FROM (arg brep) |
+ * | `tools` | {@linkcode ComponentHandle}`[]` | The ≥1 entities subtracted (tool breps) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanSubtractArgs = z.object({
+  target: ComponentHandle,
+  tools: z.array(ComponentHandle).min(1),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanSubtractArgs = z.infer<typeof PluginDesignBooleanSubtractArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.intersect}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | **EXACTLY 2** entities to intersect (order-independent) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanIntersectArgs = z.object({
+  components: z.array(ComponentHandle).length(2),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanIntersectArgs = z.infer<typeof PluginDesignBooleanIntersectArgs>

package/src/api/design/catalog.ts

@@ -0,0 +1,203 @@
+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,
+})
+
+/** Search metadata is extensible. A slash separates category path segments. */
+export const PluginCatalogSearchArgs = z
+  .object({
+    query: z.string().trim().max(200).optional(),
+    category: z.string().trim().max(1000).optional(),
+    limit: z.number().int().min(1).max(50).optional(),
+    cursor: z.string().min(1).max(16384).optional(),
+  })
+  .strict()
+export type PluginCatalogSearchArgs = z.infer<typeof PluginCatalogSearchArgs>
+
+/** Browse one hierarchy level without enumerating families or fetching recipe bodies. */
+export const PluginCatalogListCategoriesArgs = z
+  .object({
+    parent: z.string().trim().max(1000).optional(),
+    after: z.string().max(1000).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+  })
+  .strict()
+export type PluginCatalogListCategoriesArgs = z.infer<
+  typeof PluginCatalogListCategoriesArgs
+>
+
+/** Metadata only: the category does not establish placement capabilities or recipe validity. */
+export const PluginCatalogCategory = z.object({
+  categoryPath: z.array(z.string()).min(1),
+  hasChildren: z.boolean(),
+})
+export type PluginCatalogCategory = z.infer<typeof PluginCatalogCategory>
+
+/** Metadata only. Read get(reference) to validate a selected family and inspect placement methods. */
+export const PluginCatalogSummary = z.object({
+  reference: PluginCatalogReference,
+  label: z.string(),
+  categoryPath: z.array(z.string()),
+  description: z.string(),
+  source: PluginCatalogEntry.shape.source,
+})
+export type PluginCatalogSummary = z.infer<typeof PluginCatalogSummary>
+export const PluginCatalogSearchResult = z.object({
+  items: z.array(PluginCatalogSummary),
+  nextCursor: z.string().nullable(),
+})
+export type PluginCatalogSearchResult = z.infer<
+  typeof PluginCatalogSearchResult
+>
+
+/** Shared read surface over existing libraries. Does not publish, register, or place definitions. */
+export abstract class PluginDesignCatalogApi {
+  /**
+   * Discover categories from accessible saved families and current project constructions.
+   * Omit parent for roots; pass a slash-separated returned path for its direct children.
+   * This metadata read does not fetch recipes, include unsaved drafts or legacy mesh inventories,
+   * or establish capabilities. Use search then get before placement. Names retain their case.
+   * @param args Parent path, exclusive after-name, and page limit (default 50, maximum 100).
+   * For another page at the same parent, pass the last item's final categoryPath segment as after.
+   * @returns Categories in Unicode code-point order, with descendant flags. Stop when a page has
+   * fewer than limit items. Live pagination is not a snapshot. Metadata-service failures reject.
+   */
+  abstract listCategories(
+    args?: PluginCatalogListCategoriesArgs,
+  ): PluginApiReturn<PluginCatalogCategory[]>
+  /**
+   * Search accessible saved-family and project-construction metadata without downloading recipes.
+   * Categories are data, not an SDK enum. Legacy mesh inventories and unsaved drafts are excluded.
+   * Inspect selected references with get before placement; a search match does not prove validity
+   * or supported behavior. Pagination reads live data, not a snapshot. Failures reject.
+   * @param args Text/category filters, page limit (default 20, maximum 50), and opaque cursor.
+   * @returns Compact metadata and continuation. Continue until nextCursor is null or a suitable
+   * family is found. Concurrent changes can leave an empty page with continuation.
+   */
+  abstract search(
+    args?: PluginCatalogSearchArgs,
+  ): PluginApiReturn<PluginCatalogSearchResult>
+  /** @param kind Optional element filter. @returns Accessible entries and their supported API paths. */
+  abstract list(kind?: PluginCatalogKind): PluginApiReturn<PluginCatalogEntry[]>
+  /** @param reference Exact reference from search or list. @returns The current entry, or null when unavailable. */
+  abstract get(
+    reference: PluginCatalogReference,
+  ): PluginApiReturn<PluginCatalogEntry | null>
+}