@snaptrude/plugin-core 0.6.0 → 0.7.0

package/api-manifest.full.json

@@ -3038,6 +3038,114 @@
     "argsType": "number",
     "resultType": "boolean"
   },
+  {
+    "path": "core.proposals.create",
+    "namespace": "core.proposals",
+    "summary": "Create a new design option (proposal).",
+    "examplePrompts": [
+      "Create a design option called Scheme B",
+      "Add a new proposal named Option 2",
+      "Make a fresh design variant to explore\n\n# Example\n```ts\nconst { id } = await snaptrude.core.proposals.create(\"Scheme B\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsCreateResult"
+  },
+  {
+    "path": "core.proposals.delete",
+    "namespace": "core.proposals",
+    "summary": "Delete a proposal.",
+    "examplePrompts": [
+      "Delete proposal prop_2",
+      "Remove this design option and everything in it",
+      "Merge prop_2's layers into prop_1 and delete prop_2\n\n# Example\n```ts\nawait snaptrude.core.proposals.delete(\"prop_2\", { deleteObjects: true })\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsDeleteResult"
+  },
+  {
+    "path": "core.proposals.get",
+    "namespace": "core.proposals",
+    "summary": "Get a single proposal by id.",
+    "examplePrompts": [
+      "Get the proposal with id prop_1",
+      "Look up a single design option by its id",
+      "Which buckets belong to proposal prop_2?\n\n# Example\n```ts\nconst proposal = await snaptrude.core.proposals.get(\"prop_1\")\nif (proposal) console.log(proposal.name, proposal.bucketIds)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsGetResult"
+  },
+  {
+    "path": "core.proposals.getActive",
+    "namespace": "core.proposals",
+    "summary": "Get the active proposal.",
+    "examplePrompts": [
+      "Which design option is active?",
+      "Get the current proposal",
+      "What proposal am I working in?\n\n# Example\n```ts\nconst active = await snaptrude.core.proposals.getActive()\nif (active) console.log(active.id, active.name)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCoreProposalsGetActiveResult"
+  },
+  {
+    "path": "core.proposals.isActive",
+    "namespace": "core.proposals",
+    "summary": "Test whether a proposal is the active one.",
+    "examplePrompts": [
+      "Is proposal prop_2 the active one?",
+      "Check whether this design option is currently shown",
+      "Am I working in proposal prop_1?\n\n# Example\n```ts\nif (await snaptrude.core.proposals.isActive(\"prop_1\")) {\nconsole.log(\"prop_1 is active\")\n}\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "core.proposals.list",
+    "namespace": "core.proposals",
+    "summary": "List the design options (proposals) in the active project.",
+    "examplePrompts": [
+      "List all the design options in this project",
+      "How many proposals does this project have?",
+      "Show every design variant with its name\n\n# Example\n```ts\nconst { proposals } = await snaptrude.core.proposals.list()\nfor (const p of proposals) console.log(p.id, p.name, p.isActive)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCoreProposalsListResult"
+  },
+  {
+    "path": "core.proposals.listForComponent",
+    "namespace": "core.proposals",
+    "summary": "List the proposals a component belongs to.",
+    "examplePrompts": [
+      "Which design options is this component part of?",
+      "List the proposals that contain this wall",
+      "Is this element shared across multiple design variants?\n\n# Example\n```ts\nconst { proposals } = await snaptrude.core.proposals.listForComponent(wall)\nconsole.log(`shared across ${proposals.length} proposals`)\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginCoreProposalsListForComponentResult"
+  },
+  {
+    "path": "core.proposals.rename",
+    "namespace": "core.proposals",
+    "summary": "Rename a proposal.",
+    "examplePrompts": [
+      "Rename proposal prop_1 to Final Scheme",
+      "Change the name of this design option",
+      "Call proposal prop_2 \"Option A\"\n\n# Example\n```ts\nconst proposal = await snaptrude.core.proposals.rename(\"prop_1\", \"Final Scheme\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsRenameResult"
+  },
+  {
+    "path": "core.proposals.setActive",
+    "namespace": "core.proposals",
+    "summary": "Switch the active proposal.",
+    "examplePrompts": [
+      "Switch to proposal prop_2",
+      "Make Scheme B the active design option",
+      "Show me the other proposal\n\n# Example\n```ts\nawait snaptrude.core.proposals.setActive(\"prop_2\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsSetActiveResult"
+  },
   {
     "path": "core.tags.assign",
     "namespace": "core.tags",
@@ -3392,6 +3500,20 @@
     "argsType": "ComponentHandle[]",
     "resultType": "ComponentHandle[]"
   },
+  {
+    "path": "design.create.door",
+    "namespace": "design.create",
+    "summary": "Place a **door** from the catalog into a host wall.",
+    "examplePrompts": [
+      "Add a door to this wall here",
+      "Place a sliding door on the selected wall",
+      "Put a door from the catalog at this point on the wall",
+      "Insert the entrance door into this wall",
+      "Add a door to the wall and call it Entry-01\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ isSelected: true })\nconst [entry] = await snaptrude.design.doors.listCatalog()\nconst door = await snaptrude.design.create.door(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Entry-01\" },\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "ComponentHandle"
+  },
   {
     "path": "design.create.floor",
     "namespace": "design.create",
@@ -3473,6 +3595,20 @@
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
+  {
+    "path": "design.create.smartLayout",
+    "namespace": "design.create",
+    "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": [
+      "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```"
+    ],
+    "argsType": "PluginSmartLayoutArgs",
+    "resultType": "PluginSmartLayoutResult"
+  },
   {
     "path": "design.create.space",
     "namespace": "design.create",
@@ -3528,6 +3664,20 @@
     "argsType": "ProfileHandle",
     "resultType": "ComponentHandle[]"
   },
+  {
+    "path": "design.create.window",
+    "namespace": "design.create",
+    "summary": "Place a **window** from the catalog into a host wall.",
+    "examplePrompts": [
+      "Add a window to this wall here",
+      "Place a casement window on the selected wall",
+      "Put a window from the catalog at this point on the wall",
+      "Insert a window into the living room wall",
+      "Add a window to the wall and name it Win-01\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ isSelected: true })\nconst [entry] = await snaptrude.design.windows.listCatalog()\nconst window = await snaptrude.design.create.window(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Win-01\" },\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "ComponentHandle"
+  },
   {
     "path": "design.delete.entities",
     "namespace": "design.delete",
@@ -3542,6 +3692,32 @@
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.doors.exists",
+    "namespace": "design.doors",
+    "summary": "Test whether a door catalog item exists for the given library id.",
+    "examplePrompts": [
+      "Is this door still in the library?",
+      "Check whether a door catalog item with this id exists",
+      "Does my team library have this door?",
+      "Verify the door is available before placing it\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.doors.listCatalog()\nconst stillAvailable = await snaptrude.design.doors.exists(entry.id)\nconsole.log(stillAvailable ? \"safe to place\" : \"removed from library\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "design.doors.getCatalogItem",
+    "namespace": "design.doors",
+    "summary": "Get a single door catalog item by its library id.",
+    "examplePrompts": [
+      "Get the details of this door from the library",
+      "Look up the catalog entry for this door id",
+      "What is the cost of this door item?",
+      "Show me the family name of this door in the catalog\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.doors.listCatalog()\nconst item = await snaptrude.design.doors.getCatalogItem(entry.id)\nif (item) console.log(item.name, item.source, item.dbType)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginObjectCatalogItem | null"
+  },
   {
     "path": "design.doors.getFamily",
     "namespace": "design.doors",
@@ -3620,6 +3796,32 @@
     "argsType": "ComponentHandle",
     "resultType": "number | null"
   },
+  {
+    "path": "design.doors.listCatalog",
+    "namespace": "design.doors",
+    "summary": "List the placeable door catalog (team + general libraries), optionally restricted to one group by its `dbType` token.",
+    "examplePrompts": [
+      "What doors can I place in this project?",
+      "List every door in the library",
+      "Show me the sliding doors I can add",
+      "Browse the door catalog\n\n# Example\n```ts\nconst [group] = await snaptrude.design.doors.listCatalogGroups()\nconst items = await snaptrude.design.doors.listCatalog(group?.dbType)\nfor (const item of items) console.log(item.id, item.name, item.thumbnailUrl)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginObjectCatalogItem[]"
+  },
+  {
+    "path": "design.doors.listCatalogGroups",
+    "namespace": "design.doors",
+    "summary": "List the door catalog **groups** — the placement families (Swing, Sliding, Folding, Pivot, …), built-in groups merged with any team-custom types.",
+    "examplePrompts": [
+      "What kinds of doors can I place?",
+      "List the door groups in the catalog",
+      "Show me the door families available in this project",
+      "Which door types does this project support?\n\n# Example\n```ts\nconst groups = await snaptrude.design.doors.listCatalogGroups()\nfor (const g of groups) console.log(g.dbType, g.label, g.source)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginObjectCatalogGroup[]"
+  },
   {
     "path": "design.doors.mirror",
     "namespace": "design.doors",
@@ -3730,17 +3932,42 @@
   {
     "path": "design.furniture.listCatalog",
     "namespace": "design.furniture",
-    "summary": "List the placeable furniture catalog (team + general libraries).",
+    "summary": "List the placeable furniture catalog (team + general libraries), optionally filtered by library `source` and/or `category`.",
     "examplePrompts": [
       "What furniture can I place in this project?",
       "Show me all the furniture available in the library",
       "List the chairs and tables I can add to the model",
       "Which furniture items are in my team's library?",
-      "Browse the furniture catalog\n\n# Example\n```ts\nconst teamItems = await snaptrude.design.furniture.listCatalog(\"team\")\nfor (const item of teamItems) console.log(item.id, item.name, item.cost)\n```"
+      "Show me the bedroom furniture I can place\n\n# Example\n```ts\nconst bedroom = await snaptrude.design.furniture.listCatalog(\"team\", \"bedroom\")\nfor (const item of bedroom) console.log(item.id, item.name, item.thumbnailUrl)\n```"
     ],
     "argsType": "\"team\" | \"general\"",
     "resultType": "PluginFurnitureCatalogItem[]"
   },
+  {
+    "path": "design.furniture.listCategories",
+    "namespace": "design.furniture",
+    "summary": "List the categories (Living, Bedroom, Kitchen, …) that organize the furniture catalog — the picker taxonomy, merged from built-in categories, team types, and backend user types. Pass a value to {@linkcode PluginDesignFurnitureApi.listCatalog}'s `category` filter.",
+    "examplePrompts": [
+      "What furniture categories are available?",
+      "List the furniture categories",
+      "Show me the furniture groups like living and bedroom",
+      "Which furniture categories can I filter by?\n\n# Example\n```ts\nconst categories = await snaptrude.design.furniture.listCategories()\nconst [first] = categories\nconst items = await snaptrude.design.furniture.listCatalog(undefined, first)\nconsole.log(first, \"→\", items.length, \"items\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "string[]"
+  },
+  {
+    "path": "design.isAreaLocked",
+    "namespace": "design",
+    "summary": "Test whether a space's footprint area is locked. A read — never throws; returns `false` for non-space handles and when the `area_lock` feature is off.",
+    "examplePrompts": [
+      "Is the area of this room locked?",
+      "Check whether this department's footprint is pinned",
+      "Tell me if the selected space has its area locked\n\n# Example\n```ts\nconst [room] = await snaptrude.design.selection.get()\nconst locked = await snaptrude.design.isAreaLocked(room)\nconsole.log(locked ? \"area is locked\" : \"area is free\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
   {
     "path": "design.isLocked",
     "namespace": "design",
@@ -3754,6 +3981,18 @@
     "argsType": "ComponentHandle",
     "resultType": "boolean"
   },
+  {
+    "path": "design.listAreaLocked",
+    "namespace": "design",
+    "summary": "List the spaces whose footprint area is locked. A read — never throws; returns `[]` when the `area_lock` feature is off.",
+    "examplePrompts": [
+      "Which spaces have their area locked?",
+      "List every room with a locked footprint",
+      "Show me all the area-locked departments\n\n# Example\n```ts\nconst locked = await snaptrude.design.listAreaLocked()\nconsole.log(locked.length, \"area-locked spaces\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "ComponentHandle[]"
+  },
   {
     "path": "design.listLocked",
     "namespace": "design",
@@ -3780,6 +4019,19 @@
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.lockArea",
+    "namespace": "design",
+    "summary": "Lock the **footprint area** of one or more Room / Department mass spaces — geometry edits that would change the bottom-face area are then refused or auto-resized to preserve it. Distinct from {@linkcode PluginDesignApi.lock} (which freezes the whole object): this locks only the area. Cascades to the space's instances and its source mass. Undoable.",
+    "examplePrompts": [
+      "Lock the floor area of the selected rooms",
+      "Freeze the footprint area of this department so its size can't drift",
+      "Area-lock every room on this storey",
+      "Pin the area of this space while I edit its walls\n\n# Example\n```ts\nconst rooms = await snaptrude.design.selection.get()\nconst { affected } = await snaptrude.design.lockArea(rooms)\nconsole.log(\"area-locked\", affected.length, \"spaces\")\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
   {
     "path": "design.materials.apply",
     "namespace": "design.materials",
@@ -3794,6 +4046,19 @@
     "argsType": "ComponentHandle[]",
     "resultType": "PluginMaterialResult"
   },
+  {
+    "path": "design.materials.applyToFaces",
+    "namespace": "design.materials",
+    "summary": "Paint specific **BREP faces** of a component with a material — an existing project material by handle, or a new one described inline as a {@linkcode PluginMaterialSpec}. Faces are addressed by **durable BREP face index** (their 0-based position in the component's BREP face list). Undoable when `save` is true (the default).",
+    "examplePrompts": [
+      "Paint the top face of this slab red",
+      "Apply the brick material to faces 0 and 2 of this wall",
+      "Put a wood finish on just the front face of this column",
+      "Colour face 4 of the selected mass with #ff8800\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ storeys: [1] })\n// faces are addressed by durable 0-based BREP face index\nconst { count } = await snaptrude.design.materials.applyToFaces(wall, [0, 1], { name: \"Accent\", color: \"#b04a3a\" })\nconsole.log(\"painted\", count, \"faces\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginMaterialResult"
+  },
   {
     "path": "design.materials.create",
     "namespace": "design.materials",
@@ -3807,6 +4072,18 @@
     "argsType": "PluginMaterialSpec",
     "resultType": "MaterialHandle"
   },
+  {
+    "path": "design.materials.getByFace",
+    "namespace": "design.materials",
+    "summary": "Read the material applied to a single BREP face.",
+    "examplePrompts": [
+      "What material is on the top face of this slab?",
+      "Get the finish applied to face 2 of this wall",
+      "Which material is painted on the front face of this column?\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst material = await snaptrude.design.materials.getByFace(wall, 0)\nif (material) console.log(await snaptrude.design.materials.getInfo(material))\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "MaterialHandle | null"
+  },
   {
     "path": "design.materials.getDefault",
     "namespace": "design.materials",
@@ -3886,6 +4163,18 @@
     "argsType": "\"project\" | \"preset\"",
     "resultType": "MaterialHandle[]"
   },
+  {
+    "path": "design.materials.listByFace",
+    "namespace": "design.materials",
+    "summary": "List the per-face materials of a component — one entry per BREP face, in face index order. A face carrying no explicit per-face material reports `null`.",
+    "examplePrompts": [
+      "List the material on every face of this wall",
+      "Show me which faces of this slab are painted and with what",
+      "Break down the per-face finishes of the selected mass\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst faces = await snaptrude.design.materials.listByFace(wall)\nfor (const f of faces) console.log(f.faceIndex, f.material ?? \"(default)\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginFaceMaterial[]"
+  },
   {
     "path": "design.materials.reset",
     "namespace": "design.materials",
@@ -3899,6 +4188,18 @@
     "argsType": "ComponentHandle[]",
     "resultType": "PluginMaterialResult"
   },
+  {
+    "path": "design.materials.resetFaces",
+    "namespace": "design.materials",
+    "summary": "Reset specific BREP faces of a component back to the component/type default, removing any per-face finish. The inverse of {@linkcode PluginDesignMaterialsApi.applyToFaces}; undoable when `save` is true (the default). BREP-only (see `applyToFaces`).",
+    "examplePrompts": [
+      "Remove the paint from the top face of this slab",
+      "Reset faces 0 and 2 of this wall to their default material",
+      "Clear the custom finish on the front face of this column\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ storeys: [1] })\nconst { count } = await snaptrude.design.materials.resetFaces(wall, [0, 1])\nconsole.log(\"reset\", count, \"faces\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginMaterialResult"
+  },
   {
     "path": "design.query.exists",
     "namespace": "design.query",
@@ -4044,6 +4345,19 @@
     "argsType": "ComponentHandle",
     "resultType": "PluginEntityProperties"
   },
+  {
+    "path": "design.query.getStaircaseParams",
+    "namespace": "design.query",
+    "summary": "Read a staircase's parametric properties — its preset, dimensions, step count, base offset, and height-lock state — as a {@linkcode PluginStaircaseParams} record. The paired write is `design.update.staircase`.",
+    "examplePrompts": [
+      "What's the riser height of this staircase?",
+      "How many steps does the selected stair have?",
+      "Show me the tread and width of this staircase",
+      "Read all the parameters of the stairs on level 1\n\n# Example\n```ts\nconst [stair] = await snaptrude.design.query.listStaircases({ isSelected: true })\nconst params = stair ? await snaptrude.design.query.getStaircaseParams(stair) : null\nif (params) console.log(params.steps, params.riser, params.tread)\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginStaircaseParams | null"
+  },
   {
     "path": "design.query.listBeams",
     "namespace": "design.query",
@@ -4403,6 +4717,20 @@
     "argsType": "PluginSelectionFilter",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.transform.align",
+    "namespace": "design.transform",
+    "summary": "Align a set of components by snapping one bounding-box edge to a common value — the classic Left/Center/Right/Top/Middle/Bottom align. Purely **world-axis** (deterministic and headless — the UI's camera-relative remap is bypassed):",
+    "examplePrompts": [
+      "Align the selected rooms to the left",
+      "Line up these masses along their top edges",
+      "Center these columns horizontally",
+      "Align all the walls to the left edge of this reference wall",
+      "Snap the bottom edges of these spaces together\n\n# Example\n```ts\nconst rooms = await snaptrude.design.selection.get()\n// align every room's left (world -X) edge to a common minimum\nawait snaptrude.design.transform.align(rooms, \"left\")\n// …or align them to a fixed reference component's left edge\nconst [anchor] = await snaptrude.design.query.listWalls({ storeys: [1] })\nawait snaptrude.design.transform.align(rooms, \"left\", { reference: anchor })\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
   {
     "path": "design.transform.move",
     "namespace": "design.transform",
@@ -4443,6 +4771,32 @@
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.unlockArea",
+    "namespace": "design",
+    "summary": "Unlock the footprint area of previously area-locked spaces so their area can change again. Paired with {@linkcode PluginDesignApi.lockArea}; cascades to instances + source; undoable. Requires the `area_lock` feature (throws if off).",
+    "examplePrompts": [
+      "Unlock the area of the selected rooms",
+      "Remove the footprint-area lock from this department",
+      "Let me resize this space again by unlocking its area",
+      "Area-unlock everything I locked earlier\n\n# Example\n```ts\nconst locked = await snaptrude.design.listAreaLocked()\nconst { affected } = await snaptrude.design.unlockArea(locked)\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
+  {
+    "path": "design.update.setLabel",
+    "namespace": "design.update",
+    "summary": "Set a component's **Label** — the same editable Label field the properties panel shows (doors, windows, furniture, spaces, and every other labelled component). The paired read is `design.query.getLabel`. Undoable; the canvas label text updates immediately.",
+    "examplePrompts": [
+      "Rename this door to D-101",
+      "Number all doors on storey 2 with a D-2-XX tag",
+      "Set the selected window's label to W-04",
+      "Tag every door with its fire rating\n\n# Example\n```ts\n// Door tag numbering: label every door as D-<storey>-<n>, numbered per storey\nawait snaptrude.design.selection.setByFilter({ types: [\"door\"] })\nconst doors = await snaptrude.design.selection.get()\nconst counts = {}\nfor (const door of doors) {\nconst { storey = 0 } = await snaptrude.design.query.getProperties(door)\ncounts[storey] = (counts[storey] ?? 0) + 1\nawait snaptrude.design.update.setLabel(door, `D-${storey}-${String(counts[storey]).padStart(2, \"0\")}`)\n}\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
   {
     "path": "design.update.space",
     "namespace": "design.update",
@@ -4471,6 +4825,46 @@
     "argsType": "PluginUpdateSpaceItem[]",
     "resultType": "PluginSpaceUpdateResult[]"
   },
+  {
+    "path": "design.update.staircase",
+    "namespace": "design.update",
+    "summary": "Update the parameters of one or more staircases — riser, tread, width, depth, step count, total height, well size, landing depth, base offset, and the two height locks — in one undoable operation. Sparse: only the fields you provide change. The paired read is `design.query.getStaircaseParams`.",
+    "examplePrompts": [
+      "Set the riser of this staircase to 165mm",
+      "Change all the stairs to 14 steps",
+      "Make the selected staircase 1200 wide with a 280 tread",
+      "Widen every staircase on level 1 to 1 metre",
+      "Unlock the height and set this stair to 3200 tall\n\n# Example\n```ts\n// Give every ground-floor staircase a common riser + tread (engine units)\nconst stairs = await snaptrude.design.query.listStaircases({ storeys: [1] })\nconst { affected } = await snaptrude.design.update.staircase(stairs, {\nriser: 165,\ntread: 280,\n})\nconsole.log(\"updated\", affected.length, \"staircases\")\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
+  {
+    "path": "design.windows.exists",
+    "namespace": "design.windows",
+    "summary": "Test whether a window catalog item exists for the given library id.",
+    "examplePrompts": [
+      "Is this window still in the library?",
+      "Check whether a window catalog item with this id exists",
+      "Does my team library have this window?",
+      "Verify the window is available before placing it\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.windows.listCatalog()\nconst stillAvailable = await snaptrude.design.windows.exists(entry.id)\nconsole.log(stillAvailable ? \"safe to place\" : \"removed from library\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "design.windows.getCatalogItem",
+    "namespace": "design.windows",
+    "summary": "Get a single window catalog item by its library id.",
+    "examplePrompts": [
+      "Get the details of this window from the library",
+      "Look up the catalog entry for this window id",
+      "What is the cost of this window item?",
+      "Show me the family name of this window in the catalog\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.windows.listCatalog()\nconst item = await snaptrude.design.windows.getCatalogItem(entry.id)\nif (item) console.log(item.name, item.source, item.dbType)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginObjectCatalogItem | null"
+  },
   {
     "path": "design.windows.getDimensions",
     "namespace": "design.windows",
@@ -4524,6 +4918,32 @@
     "argsType": "ComponentHandle",
     "resultType": "number | null"
   },
+  {
+    "path": "design.windows.listCatalog",
+    "namespace": "design.windows",
+    "summary": "List the placeable window catalog (team + general libraries), optionally restricted to one group by its `dbType` token.",
+    "examplePrompts": [
+      "What windows can I place in this project?",
+      "List every window in the library",
+      "Show me the casement windows I can add",
+      "Browse the window catalog\n\n# Example\n```ts\nconst [group] = await snaptrude.design.windows.listCatalogGroups()\nconst items = await snaptrude.design.windows.listCatalog(group?.dbType)\nfor (const item of items) console.log(item.id, item.name, item.thumbnailUrl)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginObjectCatalogItem[]"
+  },
+  {
+    "path": "design.windows.listCatalogGroups",
+    "namespace": "design.windows",
+    "summary": "List the window catalog **groups** — the placement families (Fixed, Casement, Sliding, Folding, …), built-in groups merged with any team-custom types.",
+    "examplePrompts": [
+      "What kinds of windows can I place?",
+      "List the window groups in the catalog",
+      "Show me the window families available in this project",
+      "Which window types does this project support?\n\n# Example\n```ts\nconst groups = await snaptrude.design.windows.listCatalogGroups()\nfor (const g of groups) console.log(g.dbType, g.label, g.source)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginObjectCatalogGroup[]"
+  },
   {
     "path": "design.windows.setHeight",
     "namespace": "design.windows",
@@ -4645,6 +5065,19 @@
     "argsType": "number",
     "resultType": "PluginStoryCreateResult"
   },
+  {
+    "path": "entity.story.duplicate",
+    "namespace": "entity.story",
+    "summary": "Duplicate a story into the adjacent level, up or down.",
+    "examplePrompts": [
+      "Duplicate this floor to the storey above",
+      "Copy the ground floor down into a new basement",
+      "Repeat this level upwards with its own independent geometry",
+      "Duplicate just the selected walls onto the next floor up\n\n# Example\n```ts\n// Duplicate the whole active story one level up (instanced copies).\nconst { targetStories, created, skipped } =\nawait snaptrude.entity.story.duplicate(\"up\")\nconsole.log(`Copied ${created.length} elements onto story ${targetStories}`)\nif (skipped) console.log(`${skipped} elements were skipped`)\n```"
+    ],
+    "argsType": "\"up\" | \"down\"",
+    "resultType": "PluginStoryDuplicateResult"
+  },
   {
     "path": "entity.story.get",
     "namespace": "entity.story",
@@ -4675,12 +5108,12 @@
   {
     "path": "entity.story.update",
     "namespace": "entity.story",
-    "summary": "Update a story's height.",
+    "summary": "Update a story's floor-to-floor height, cascading the full geometry change.",
     "examplePrompts": [
       "Change the ground floor height to 3.5 metres",
       "Make the second storey taller",
       "Set the floor-to-floor height of level 1",
-      "Increase the height of the third floor\n\n# Example\n```ts\n// Set ground floor height to 5 Babylon units\nconst result = await snaptrude.entity.story.update(1, 5)\n```"
+      "Increase the height of the third floor\n\n# Example\n```ts\n// Set ground floor height to 5 Babylon units — walls stretch and the\n// floors above move up to match, all in a single undo step.\nconst result = await snaptrude.entity.story.update(1, 5)\n```"
     ],
     "argsType": "number",
     "resultType": "PluginStoryUpdateResult"
@@ -4773,6 +5206,19 @@
     "argsType": "{ url?: string; dataUrl?: string }",
     "resultType": "PluginPresentationImportResult"
   },
+  {
+    "path": "presentation.import.svg",
+    "namespace": "presentation.import",
+    "summary": "Import an SVG onto the current Present sheet as a true vector asset.",
+    "examplePrompts": [
+      "Import this SVG diagram onto the present canvas",
+      "Add a vector logo to my presentation board",
+      "Place this SVG floor plan on the current sheet as vectors",
+      "Bring a crisp vector graphic into Present mode\n\n# Example\n```ts\nconst { shapeIds } = await snaptrude.presentation.import.svg({\nurl: \"https://example.com/diagram.svg\",\n})\n```"
+    ],
+    "argsType": "{ url?: string; dataUrl?: string }",
+    "resultType": "PluginPresentationImportResult"
+  },
   {
     "path": "presentation.sheets.create",
     "namespace": "presentation.sheets",
@@ -4873,6 +5319,19 @@
     "argsType": null,
     "resultType": "PluginPresentationViewsGetResult"
   },
+  {
+    "path": "presentation.views.getSettings",
+    "namespace": "presentation.views",
+    "summary": "Read a saved view's display settings (background, color mode, axis, edges, labels).",
+    "examplePrompts": [
+      "What color mode is the Ground Floor view using?",
+      "Get the display settings for this view",
+      "Does the site plan view show axes and labels?",
+      "Read the background color of the active view\n\n# Example\n```ts\nconst settings = await snaptrude.presentation.views.getSettings(\"view_123\")\nif (settings) console.log(settings.colorMode, settings.backgroundColor)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationViewsGetSettingsResult"
+  },
   {
     "path": "presentation.views.list",
     "namespace": "presentation.views",
@@ -4900,6 +5359,20 @@
     "argsType": "string",
     "resultType": "PluginPresentationViewsSetActiveResult"
   },
+  {
+    "path": "presentation.views.updateSettings",
+    "namespace": "presentation.views",
+    "summary": "Update a saved view's display settings (partial patch — only the fields you pass change).",
+    "examplePrompts": [
+      "Switch this view to monochrome color mode",
+      "Turn off the axis in the Ground Floor view",
+      "Set the background of the active view to white",
+      "Show area labels on this view",
+      "Enable hidden-line mode for the section view\n\n# Example\n```ts\nawait snaptrude.presentation.views.updateSettings(\"view_123\", {\ncolorMode: \"monochrome\",\nshowAxis: false,\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationViewsUpdateSettingsResult"
+  },
   {
     "path": "program.adjacency.compute",
     "namespace": "program.adjacency",
@@ -4933,6 +5406,8 @@
     "examplePrompts": [
       "What's my FAR right now?",
       "Give me the program area summary",
+      "What is my net internal area vs gross external area?",
+      "How much net and gross area do I have?",
       "How much built-up area have I used against the site area?",
       "Am I within my FAR target?\n\n# Example\n```ts\nconst s = await snaptrude.program.areas.get()\nconsole.log(s.builtUp, s.siteArea, s.achievedFar, s.targetFar, s.areaUnit)\n```"
     ],
@@ -4945,6 +5420,7 @@
     "summary": "List the program area rollup grouped by a facet.",
     "examplePrompts": [
       "Break down the area by storey",
+      "Break down net vs gross area by storey",
       "Show the area rollup per department",
       "Group the built-up area by building\n\n# Example\n```ts\nconst { groups } = await snaptrude.program.areas.list(\"storeys\")\nfor (const g of groups) console.log(g.name, g.builtUp, g.count)\n```"
     ],
@@ -4957,6 +5433,7 @@
     "summary": "List the spaces that make up one area group.",
     "examplePrompts": [
       "List the spaces on this storey with their areas",
+      "Which spaces are net and which are gross on this storey?",
       "What rooms are in the Bedrooms department bucket?",
       "Break the storey area down into individual spaces\n\n# Example\n```ts\nconst { members } = await snaptrude.program.areas.listMembers(\"storeys\", \"st_2\")\nfor (const m of members) console.log(m.label, m.carpet)\n```"
     ],
@@ -5144,25 +5621,49 @@
   {
     "path": "program.layout.arrange",
     "namespace": "program.layout",
-    "summary": "Arrange the spaces inside the envelope using the computed adjacency data. _(Authored ahead — optional until the host lands.)_",
+    "summary": "Arrange the spaces inside the envelope using the computed adjacency data.",
     "examplePrompts": [
       "Arrange the rooms in the envelope",
       "Lay out the departments inside the building envelope",
-      "Auto-arrange the program spaces\n\n# Example\n```ts\nconst { success, error } = await snaptrude.program.layout.arrange()\nif (!success) console.log(\"Arrange failed:\", error)\n```"
+      "Auto-arrange the program spaces\n\n# Example\n```ts\nconst { success, error } = await snaptrude.program.layout.arrange()\nif (!success) throw new Error(error)\n// poll until the layout is applied\nlet job = await snaptrude.program.layout.getState()\nwhile (job?.status === \"running\") {\nawait new Promise((r) => setTimeout(r, 5000))\njob = await snaptrude.program.layout.getState()\n}\n```"
     ],
-    "argsType": null,
+    "argsType": "PluginProgramLayoutRunArgs",
     "resultType": "PluginProgramLayoutRunResult"
   },
+  {
+    "path": "program.layout.cancel",
+    "namespace": "program.layout",
+    "summary": "Cancel the in-flight layout run.",
+    "examplePrompts": [
+      "Cancel the arrange",
+      "Stop the running layout job",
+      "Abort the pack in envelope\n\n# Example\n```ts\nawait snaptrude.program.layout.cancel()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "program.layout.getState",
+    "namespace": "program.layout",
+    "summary": "Get the state of the layout run.",
+    "examplePrompts": [
+      "Is the arrange done?",
+      "Check the status of the layout run",
+      "Did the pack finish?\n\n# Example\n```ts\nconst job = await snaptrude.program.layout.getState()\nif (job?.status === \"active\") console.log(\"layout applied\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramLayoutStateResult"
+  },
   {
     "path": "program.layout.pack",
     "namespace": "program.layout",
-    "summary": "Pack the spaces into the envelope (a tighter fit than arrange). _(Authored ahead — optional until the host lands.)_",
+    "summary": "Pack the spaces into the envelope (a tighter fit than arrange).",
     "examplePrompts": [
       "Pack the rooms into the envelope",
       "Fit the program spaces tightly into the building",
-      "Run pack-in-envelope on this storey\n\n# Example\n```ts\nconst { success, error } = await snaptrude.program.layout.pack()\nif (!success) console.log(\"Pack failed:\", error)\n```"
+      "Run pack-in-envelope on this storey\n\n# Example\n```ts\nconst { success } = await snaptrude.program.layout.pack({ envelopeId: \"be_...\" })\nlet job = await snaptrude.program.layout.getState()\nwhile (job?.status === \"running\") {\nawait new Promise((r) => setTimeout(r, 5000))\njob = await snaptrude.program.layout.getState()\n}\n```"
     ],
-    "argsType": null,
+    "argsType": "PluginProgramLayoutRunArgs",
     "resultType": "PluginProgramLayoutRunResult"
   },
   {