@snaptrude/plugin-core 1.0.0 → 1.0.1-shared-families-20261025.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "1.0.0",
+  "version": "1.0.1-shared-families-20261025.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

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

@@ -1406,20 +1406,24 @@ export abstract class PluginDesignCreateApi {
 
   /**
    * **Copy** existing entities, offsetting each copy by `displacement * i` (i = 1…count),
-   * source positions preserved. Migrated from the removed `tools.copy`. In `"instance"`
-   * mode copies stay in the source's instance family where possible; `"unique"` makes
-   * independent geometry. The created copies become the active selection. Undoable.
+   * source positions preserved. Migrated from the removed `tools.copy`.
+   * The created copies become the active selection. Undoable.
    *
-   * Runs on the engine's array-copy tool, so its semantics carry over: an
-   * `"instance"` copy of a source that is not yet an instance **replaces that
-   * source** with a fresh instance component — the handle you passed in stops
-   * resolving after the call. Re-query (e.g. `design.query.listSpaces`) to pick
-   * up the replacement before operating on that entity again; copying the stale
-   * handle throws. `"unique"` mode never replaces sources.
+   * Agents should omit `mode`. Never ask Instance/Unique for recipe family or
+   * parametric door/window copies. The field remains for legacy geometry-only
+   * compatibility: `"instance"` shares geometry where possible; `"unique"` does not.
+   * Recipe families (including recipe stairs) and parametric doors/windows keep
+   * their project family in BOTH modes. Use `design.family.duplicate` for an
+   * independent family variant; do not create a group to simulate family sharing.
+   * Door/window sill, hand/swing and host-bound dimensions remain placement-local.
+   *
+   * Uses the engine's array-copy tool. Recipe and graph-registered source handles
+   * stay live. Legacy catalog geometry can still replace its source when converting
+   * it to a Babylon instance; re-query if a legacy source handle becomes stale.
    *
    * @param components - Entities to copy (≥1)
    * @param displacement - Per-copy offset as a {@linkcode Vec3Handle} (copy `i` at `displacement * i`)
-   * @param options - `count` (copies per component, default 1), `mode` (`"instance"` | `"unique"`, default `"instance"`)
+   * @param options - `count` (copies per component, default 1). Omit `mode`; it is legacy geometry-only compatibility.
    * @returns the created copies as {@linkcode ComponentHandle}`[]`
    * @throws if a component handle is unknown or stale (replaced by an earlier
    *   `"instance"` copy), `count` is not a positive integer, or the engine fails
@@ -1428,7 +1432,6 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Duplicate the selected furniture along the X axis
    * @examplePrompt Make 5 copies of this column at 4 metre intervals
    * @examplePrompt Array these walls with a 3m offset
-   * @examplePrompt Clone the desk as a unique copy, not an instance
    *
    * @performance To place N repeats of the same geometry, bulk-create the seed(s) once then
    *   call this ONCE with `{ count: N - 1 }` — one host round-trip for all copies. Never
@@ -2167,12 +2170,15 @@ export type PluginDesignCreateReferenceLinesArgs = z.infer<
 // ---------------------------------------------------------------------------
 
 /**
- * Copy mode for {@linkcode PluginDesignCreateApi.copy}.
+ * Legacy geometry-only copy mode for {@linkcode PluginDesignCreateApi.copy}.
+ * Retained for runtime compatibility. Agents should omit it and never ask
+ * Instance/Unique for recipe families or parametric openings: both modes retain
+ * their project family. Use `design.family.duplicate` for independence.
  *
  * | Value | Description |
  * |---|---|
- * | `"instance"` | Keep copies in the source's instance family where possible |
- * | `"unique"` | Independent geometry copies |
+ * | `"instance"` | Share legacy geometry where possible |
+ * | `"unique"` | Independent legacy geometry copies |
  */
 export const PluginCopyMode = z.enum(["instance", "unique"])
 export type PluginCopyMode = z.infer<typeof PluginCopyMode>
@@ -2185,7 +2191,7 @@ export type PluginCopyMode = z.infer<typeof PluginCopyMode>
  * | `components` | {@linkcode ComponentHandle}`[]` | Entities to copy (≥1) |
  * | `displacement` | {@linkcode Vec3Handle} | Per-copy offset (copy `i` at `displacement * i`) |
  * | `count` | `number`? | Copies per component (default 1) |
- * | `mode` | {@linkcode PluginCopyMode}? | `"instance"` (default) or `"unique"` |
+ * | `mode` | {@linkcode PluginCopyMode}? | Legacy geometry-only compatibility; agents should omit |
  */
 export const PluginDesignCreateCopyArgs = z.object({
   components: z.array(ComponentHandle).min(1),

package/src/api/design/family.ts

@@ -335,8 +335,8 @@ export abstract class PluginDesignFamilyApi {
    * and returns immediately — no geometry yet. The USER clicks to drop it, so
    * tell them to. Prefer this when the location is a judgement call.
    *
-   * To COPY a placed component, place its family again at the new position with
-   * the same `values` — there is no separate copy call.
+   * To copy a placement, use `design.create.copy` to retain its project family.
+   * Placing a library definition again does not select an existing project variant.
    *
    * HOSTED families (doors, windows — anything with an `opening`, a `host`
    * block, or a void with `cuts: "host"`) take `host`: a wall or a placed
@@ -403,7 +403,12 @@ export abstract class PluginDesignFamilyApi {
   ): PluginApiReturn<PluginFamilyInstanceParameters | null>
 
   /**
-   * Change a placed component's parameters and rebuild its geometry in place.
+   * Change authored parameters across the selected component's project family.
+   * Use `duplicate({ component, name })` first for an independent project variant.
+   * This never publishes or modifies a library. Only changed authored values
+   * propagate; placement, hosting, links and relations remain local. A locked
+   * family member or host refuses a shared edit. Mixed requests containing links,
+   * relations and parameters are not one atomic transaction.
    *
    * Partial: pass only what changes. The component keeps its position,
    * rotation and identity — this is an edit, not a replace, and it is undoable.
@@ -469,6 +474,47 @@ export abstract class PluginDesignFamilyApi {
     args: PluginDesignFamilySetParametersArgs,
   ): PluginApiReturn<PluginFamilyInstanceParameters>
 
+  /**
+   * Assign one placed recipe family or parametric door/window to a new project
+   * family. Does not copy geometry, publish a library or alter native system families.
+   * Subsequent authored parameter edits no longer affect the original family.
+   * Undo restores the original family identity and name together.
+   * This is project-only. If the user requests both an independent project family
+   * and a library asset, call duplicate first, then saveToLibrary with the same
+   * component. If they request a library save later, call saveToLibrary alone;
+   * do not duplicate again.
+   * @param args The selected component and a nonblank project-family name.
+   * @returns The unchanged component handle, new project-family id and trimmed name.
+   * @example await snaptrude.design.family.duplicate({ component, name: "Wide door" })
+   */
+  public abstract duplicate(
+    args: PluginDesignFamilyDuplicateArgs,
+  ): PluginApiReturn<PluginFamilyDuplicateResult>
+
+  /**
+   * Save a placed recipe family or parametric door/window's current authored
+   * configuration as a separate library asset. Does not place geometry, reassign
+   * any model component, overwrite the original library asset or publish publicly.
+   *
+   * This is an explicit shared-library write: call only when the user requests
+   * a library save, never as a side effect of copying or project-only duplication.
+   * Choose the destination explicitly: teamId is a team id, or null for personal.
+   * Preserve libraryKey across retries of this save; a new UUID means a new save.
+   * For project independence plus a library asset, call duplicate first, then
+   * saveToLibrary on that component. To save later, call saveToLibrary alone.
+   *
+   * @param args Component, nonblank asset name, explicit library scope and retry key.
+   * @returns The saved asset's id, guid, version and name.
+   * @example
+   * const libraryKey = crypto.randomUUID() // Retain this key if the save needs retrying.
+   * const saved = await snaptrude.design.family.saveToLibrary({
+   *   component, name: "Wide door", teamId: null, libraryKey,
+   * })
+   */
+  public abstract saveToLibrary(
+    args: PluginDesignFamilySaveToLibraryArgs,
+  ): PluginApiReturn<PluginFamilySaveToLibraryResult>
+
   /**
    * Save the prepared bundle to the library: the open project's team library in a team
    * project, else the user's personal library. `teamId` picks another team, and `null` the
@@ -1301,6 +1347,45 @@ export type PluginDesignFamilyGetParametersArgs = z.infer<
   typeof PluginDesignFamilyGetParametersArgs
 >
 
+/** Input to project-only family duplication; names never determine membership. */
+export const PluginDesignFamilyDuplicateArgs = z.object({
+  component: ComponentHandle,
+  name: z.string().trim().min(1),
+})
+export type PluginDesignFamilyDuplicateArgs = z.infer<typeof PluginDesignFamilyDuplicateArgs>
+
+/** The selected placement now belongs to this project family, not a new library entry. */
+export const PluginFamilyDuplicateResult = z.object({
+  component: ComponentHandle,
+  projectFamilyId: z.string().min(1),
+  name: z.string().min(1),
+})
+export type PluginFamilyDuplicateResult = z.infer<typeof PluginFamilyDuplicateResult>
+
+/** Explicit library destination and stable retry identity for a separate asset save. */
+export const PluginDesignFamilySaveToLibraryArgs = z.object({
+  component: ComponentHandle,
+  name: z.string().trim().min(1),
+  /** Required: a team id, or null for the personal library. Never inferred from the project. */
+  teamId: z.string().nullable(),
+  /** Reuse for retries of this save; generate a new UUID only for a new save. */
+  libraryKey: z.string().uuid(),
+})
+export type PluginDesignFamilySaveToLibraryArgs = z.infer<
+  typeof PluginDesignFamilySaveToLibraryArgs
+>
+
+/** Saved library asset identity; no component was placed or reassigned. */
+export const PluginFamilySaveToLibraryResult = z.object({
+  id: z.string(),
+  guid: z.string(),
+  version: z.number().int().positive(),
+  name: z.string(),
+})
+export type PluginFamilySaveToLibraryResult = z.infer<
+  typeof PluginFamilySaveToLibraryResult
+>
+
 /**
  * Arguments for {@linkcode PluginDesignFamilyApi.setParameters}.
  *