@snaptrude/plugin-core 0.9.11 → 0.9.12

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @snaptrude/plugin-core
 
+## 0.9.12
+
+### Patch Changes
+
+- 6e4a055: added param comps
+- 8e37e1f: `design.family`: `prepare` and `flex` warnings gain the `proportion` code — parts thinner than 0.5 mm, parts or a family larger than 50 m, a family smaller than 10 mm, each naming the parts — and `flex` now returns `warnings`.
+- 2a06dd9: `design.family`: `prepare`, `flex` and `getParameters` accept a `snapshot` option and return a `snapshot` block — an isolated offscreen picture of the family (iso, front, right, top tiles with a dimension line) as a PNG data URL, so an agent can look at what it built before reporting.
+
 ## 0.9.11
 
 ### Patch Changes

package/api-manifest.json

@@ -4413,12 +4413,13 @@
   {
     "path": "design.create.smartLayout",
     "namespace": "design.create",
-    "summary": "Place a **smart layout** — apply a saved smart-layout template from the team/user library (walls, floors, spaces, furniture, doors, windows) onto one or more target ROOM/DEPARTMENT spaces, adapting orientation and fit to each target.",
+    "summary": "Place a **smart layout** — clone an in-scene template cluster (walls, furniture, doors, windows, floors) into one or more target ROOM/DEPARTMENT spaces, adapting orientation and fit to each target.",
     "examplePrompts": [
-      "Apply this saved layout template to the selected rooms",
-      "Place the \"Meeting Room A\" template into these two spaces",
-      "Fill every office with my saved desk-cluster layout",
-      "Use a template from my library to lay out this room\n\n# Example\n```ts\nconst targets = await snaptrude.design.query.listSpaces({ isSelected: true })\nconst [template] = await snaptrude.design.smartLayouts.listCatalog()\nconst result = await snaptrude.design.create.smartLayout({\ntemplateId: template.id,\ntargets,\n})\nconsole.log(\"placed walls:\", result.created.walls.length, \"skipped:\", result.skippedWalls)\n```"
+      "Copy this room's layout into the selected rooms",
+      "Apply this furniture arrangement to the other offices",
+      "Replicate this template into these two spaces",
+      "Place this desk cluster into every meeting room",
+      "Use this room as a template for the rooms I selected but keep them visible\n\n# Example\n```ts\nconst [templateRoom, ...targets] = await snaptrude.design.query.listSpaces({ isSelected: true })\nconst result = await snaptrude.design.create.smartLayout({\ntemplateComponents: [templateRoom],\ntargets,\n})\nconsole.log(\"placed walls:\", result.created.walls.length, \"skipped:\", result.skippedWalls)\n\n// …or clone a saved group by its id (from core.groups.list)\nconst { groups } = await snaptrude.core.groups.list()\nawait snaptrude.design.create.smartLayout({ templateGroup: groups[0].id, targets })\n```"
     ],
     "argsType": "PluginSmartLayoutArgs",
     "resultType": "PluginSmartLayoutResult"
@@ -4738,6 +4739,103 @@
     "argsType": "PluginDesignListErasableEdgesArgs",
     "resultType": "ErasableEdgeRef[]"
   },
+  {
+    "path": "design.family.create",
+    "namespace": "design.family",
+    "summary": "Commit the prepared bundle to the project's parametric-definition library, so it survives the session and appears in the Families panel.",
+    "examplePrompts": [
+      "Save this as a family called Vertical Louvre",
+      "Add it to my library\n\n# Example\n```ts\nconst { definitionId } = await snaptrude.design.family.create({ name: \"Louvre Screen\" })\n```"
+    ],
+    "argsType": "PluginDesignFamilyCreateArgs",
+    "resultType": "PluginFamilyCreateResult"
+  },
+  {
+    "path": "design.family.flex",
+    "namespace": "design.family",
+    "summary": "Re-run the prepared family's recipe at new parameter values.",
+    "examplePrompts": [
+      "Change it to 6 bays",
+      "Show me what happens with 20 blades\n\n# Example\n```ts\nconst { changed } = await snaptrude.design.family.flex({ values: { bays: 6 } })\nconsole.log(`removed ${changed.removed}, rebuilt ${changed.rebuilt}`)\n```"
+    ],
+    "argsType": "PluginDesignFamilyFlexArgs",
+    "resultType": "PluginFamilyFlexResult"
+  },
+  {
+    "path": "design.family.get",
+    "namespace": "design.family",
+    "summary": "The prepared family's spec bundle, or `null` when nothing is prepared.",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "PluginFamilyBundle | null"
+  },
+  {
+    "path": "design.family.getParameters",
+    "namespace": "design.family",
+    "summary": "Read a placed component's current parameter values and its sheet.",
+    "examplePrompts": [
+      "What size is that table?",
+      "Show me the parameters on this partition\n\n# Example\n```ts\nconst { values, parameters } = await snaptrude.design.family.getParameters({ component })\n```"
+    ],
+    "argsType": "PluginDesignFamilyGetParametersArgs",
+    "resultType": "PluginFamilyInstanceParameters | null"
+  },
+  {
+    "path": "design.family.getReference",
+    "namespace": "design.family",
+    "summary": "Read the family-spec DSL reference: grammar, the op table, the expression whitelist, the coordinate convention, the repair contract, and a worked example taken from a registered family.",
+    "examplePrompts": [
+      "How do I write a parametric family spec?",
+      "Show me the family DSL\n\n# Example\n```ts\nconst { reference } = await snaptrude.design.family.getReference()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginFamilyReference"
+  },
+  {
+    "path": "design.family.list",
+    "namespace": "design.family",
+    "summary": "Every parametric family registered in this session — native and imported.",
+    "examplePrompts": [
+      "What families are available?\n\n# Example\n```ts\nconst families = await snaptrude.design.family.list()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginFamilySummary[]"
+  },
+  {
+    "path": "design.family.place",
+    "namespace": "design.family",
+    "summary": "Put a family into the model — either the prepared draft or any family from {@linkcode PluginDesignFamilyApi.list}.",
+    "examplePrompts": [
+      "Place it in the model",
+      "Put a louvre screen at the origin",
+      "Copy that table two metres to the right\n\n# Example\n```ts\n// positioned — geometry exists when this resolves\nconst { component } = await snaptrude.design.family.place({\nid: \"revit:gypsum-stud-partition~90ad72\",\nposition: { x: 0, y: 0, z: 0 },\nrotation: 90,\n})\nawait snaptrude.design.transform.move([component], { x: 2, y: 0, z: 0 })\n\n// interactive — the user clicks\nawait snaptrude.design.family.place()\n```"
+    ],
+    "argsType": "PluginDesignFamilyPlaceArgs",
+    "resultType": "PluginFamilyPlaceResult"
+  },
+  {
+    "path": "design.family.prepare",
+    "namespace": "design.family",
+    "summary": "Validate, compile and preview a family spec. Nothing is committed to the model or the library — call {@linkcode PluginDesignFamilyApi.place} or {@linkcode PluginDesignFamilyApi.create} for that.",
+    "examplePrompts": [
+      "Make a louvre screen with adjustable blade count and tilt",
+      "Design a curtain wall panel family with 8 bays",
+      "Create a railing family I can adjust\n\n# Example\n```ts\nconst r = await snaptrude.design.family.prepare({ bundle })\nif (!r.ok) console.error(r.errors[0].path, r.errors[0].message)\n```"
+    ],
+    "argsType": "PluginDesignFamilyPrepareArgs",
+    "resultType": "PluginFamilyPrepareResult"
+  },
+  {
+    "path": "design.family.setParameters",
+    "namespace": "design.family",
+    "summary": "Change a placed component's parameters and rebuild its geometry in place.",
+    "examplePrompts": [
+      "Make that table seat 8",
+      "Change the stud spacing to 400\n\n# Example\n```ts\nawait snaptrude.design.family.setParameters({ component, values: { seats: 8 } })\n```"
+    ],
+    "argsType": "PluginDesignFamilySetParametersArgs",
+    "resultType": "PluginFamilyInstanceParameters"
+  },
   {
     "path": "design.furniture.exists",
     "namespace": "design.furniture",
@@ -5671,67 +5769,6 @@
     "argsType": "PluginSelectionFilter",
     "resultType": "PluginDesignChangeResult"
   },
-  {
-    "path": "design.smartLayouts.create",
-    "namespace": "design.smartLayouts",
-    "summary": "**Create** a smart-layout template in the library from an in-scene component cluster (walls, floors, furniture, doors, windows) — the save side of `design.create.smartLayout`.",
-    "examplePrompts": [
-      "Save this room's layout as a template",
-      "Add the selected furniture cluster to my template library",
-      "Save this arrangement as \"Meeting Room A\" under Offices\n\n# Example\n```ts\nconst selected = await snaptrude.design.selection.list()\nconst item = await snaptrude.design.smartLayouts.create({\ncomponents: selected,\nname: \"Meeting Room A\",\n})\nconsole.log(\"saved:\", item.id, item.name)\n```"
-    ],
-    "argsType": "PluginSmartLayoutCreateArgs",
-    "resultType": "PluginSmartLayoutCatalogItem"
-  },
-  {
-    "path": "design.smartLayouts.exists",
-    "namespace": "design.smartLayouts",
-    "summary": "Test whether a saved smart-layout template exists for the given catalog id.",
-    "examplePrompts": [
-      "Is this layout template still in the library?",
-      "Check whether this template id exists",
-      "Verify the template is available before placing it\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.smartLayouts.listCatalog()\nconst stillAvailable = await snaptrude.design.smartLayouts.exists(entry.id)\nconsole.log(stillAvailable ? \"safe to place\" : \"removed from library\")\n```"
-    ],
-    "argsType": "string",
-    "resultType": "boolean"
-  },
-  {
-    "path": "design.smartLayouts.getCatalogItem",
-    "namespace": "design.smartLayouts",
-    "summary": "Get a single saved smart-layout template by its catalog id.",
-    "examplePrompts": [
-      "Get the details of this saved layout template",
-      "Look up the template with this id",
-      "What's the floor area of this saved template?\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.smartLayouts.listCatalog()\nconst item = await snaptrude.design.smartLayouts.getCatalogItem(entry.id)\nif (item) console.log(item.name, item.categoryId)\n```"
-    ],
-    "argsType": "string",
-    "resultType": "PluginSmartLayoutCatalogItem | null"
-  },
-  {
-    "path": "design.smartLayouts.listCatalog",
-    "namespace": "design.smartLayouts",
-    "summary": "List the saved smart-layout templates of the ambient library scope, optionally restricted to one category.",
-    "examplePrompts": [
-      "What layout templates can I place?",
-      "List every saved smart layout in my library",
-      "Show the templates in the \"Meeting Rooms\" category",
-      "Browse the smart layout catalog\n\n# Example\n```ts\nconst items = await snaptrude.design.smartLayouts.listCatalog()\nfor (const item of items) console.log(item.id, item.name, item.area)\n```"
-    ],
-    "argsType": "string",
-    "resultType": "PluginSmartLayoutCatalogItem[]"
-  },
-  {
-    "path": "design.smartLayouts.listCatalogGroups",
-    "namespace": "design.smartLayouts",
-    "summary": "List the smart-layout template categories of the ambient library scope. The implicit `Default` bucket is always present and listed first; the rest follow alphabetically.",
-    "examplePrompts": [
-      "What smart layout categories does my library have?",
-      "List the template categories",
-      "Which buckets can I save a layout template into?\n\n# Example\n```ts\nconst groups = await snaptrude.design.smartLayouts.listCatalogGroups()\nfor (const g of groups) console.log(g.id, g.label)\n```"
-    ],
-    "argsType": null,
-    "resultType": "PluginSmartLayoutCatalogGroup[]"
-  },
   {
     "path": "design.transform.align",
     "namespace": "design.transform",