@snaptrude/plugin-core 0.9.16 → 0.9.17

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @snaptrude/plugin-core
 
+## 0.9.17
+
+### Patch Changes
+
+- d63e597: Add a `presentation.sections` namespace for section lines: `list`, `get`, `create` (from two plan points), `update`, `delete`, open or close a section view with `getActive` / `setActive`, and `getCut`, which reports every element a section's cutting plane passes through, with the cut's area, outline length and extent on the plane. Unknown-id reads return `null`; unknown-id writes and `getCut` throw `HANDLE_INVALID`.
+
 ## 0.9.16
 
 ### Patch Changes

package/api-manifest.json

@@ -7823,6 +7823,99 @@
     "argsType": "string",
     "resultType": "PluginPlacedViewCategoryStyles"
   },
+  {
+    "path": "presentation.sections.create",
+    "namespace": "presentation.sections",
+    "summary": "Draw a section line from `start` to `end` on the plan. The section looks along the line's direction turned a quarter turn — a line drawn toward +x looks toward +z; flip it with `update(id, { isFlipped: true })`. Its slice defaults to the building's full height and its depth to the far side of the model. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Cut a section through the middle of the building, east to west",
+      "Add a section across the stair core",
+      "Draw a longitudinal section and open it\n\n# Example\n```ts\nconst section = await snaptrude.presentation.sections.create(\n{ x: -40, z: 10 },\n{ x: 40, z: 10 },\n{ name: \"Longitudinal\", isActive: true },\n)\n```"
+    ],
+    "argsType": "PluginSectionPoint",
+    "resultType": "PluginSection"
+  },
+  {
+    "path": "presentation.sections.delete",
+    "namespace": "presentation.sections",
+    "summary": "Delete a section. Closes its view first if it is open. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Delete Section B\n\n# Example\n```ts\nawait snaptrude.presentation.sections.delete(sectionId)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "presentation.sections.get",
+    "namespace": "presentation.sections",
+    "summary": "Get one section by id.",
+    "examplePrompts": [
+      "Where does Section A run?",
+      "How deep is this section?\n\n# Example\n```ts\nconst section = await snaptrude.presentation.sections.get(sectionId)\nconsole.log(section?.start, section?.end)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginSection | null"
+  },
+  {
+    "path": "presentation.sections.getActive",
+    "namespace": "presentation.sections",
+    "summary": "Get the section whose view is open.",
+    "examplePrompts": [
+      "Which section am I looking at?\n\n# Example\n```ts\nconst open = await snaptrude.presentation.sections.getActive()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginSection | null"
+  },
+  {
+    "path": "presentation.sections.getCut",
+    "namespace": "presentation.sections",
+    "summary": "What a section cuts: every element its cutting plane passes through within the section's extents, with the cut's area, outline length and extent on the plane, largest first. Computed from the model, not from the drawing, so it needs no open view and works however the section is shown; furniture is left out, as in the drawing. Areas are exact for closed solids. Repeated calls reuse the cuts of elements that have not changed. Read-only.",
+    "examplePrompts": [
+      "Which walls does Section A cut?",
+      "How thick is the slab where the section crosses it?",
+      "Does this section go through the stair?",
+      "What is the floor-to-floor height in this section?\n\n# Example\n```ts\nconst cut = await snaptrude.presentation.sections.getCut(sectionId)\nconst walls = cut.elements.filter((element) => element.type === \"wall\")\nconst thickest = walls[0]\nconsole.log(thickest.extent.uMax - thickest.extent.uMin)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginSectionCut"
+  },
+  {
+    "path": "presentation.sections.list",
+    "namespace": "presentation.sections",
+    "summary": "List the project's sections, in Views panel order.",
+    "examplePrompts": [
+      "Which sections are there?",
+      "List the section lines in this project",
+      "Is there a section through the stair?\n\n# Example\n```ts\nconst sections = await snaptrude.presentation.sections.list()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginSection[]"
+  },
+  {
+    "path": "presentation.sections.setActive",
+    "namespace": "presentation.sections",
+    "summary": "Open a section's view, or close the open one with `null`. Opening frames the section's saved camera, or a straight-on view when it has none. Not an edit: nothing is added to the undo history.",
+    "examplePrompts": [
+      "Open Section A",
+      "Show me the section through the atrium",
+      "Close the section view\n\n# Example\n```ts\nawait snaptrude.presentation.sections.setActive(section.sectionId)\nawait snaptrude.presentation.sections.setActive(null)\n```"
+    ],
+    "argsType": "string | null",
+    "resultType": "PluginSection | null"
+  },
+  {
+    "path": "presentation.sections.update",
+    "namespace": "presentation.sections",
+    "summary": "Change a section. Only the given fields change; the whole patch is one undo step. Write-gated.",
+    "examplePrompts": [
+      "Make Section A look the other way",
+      "Only show the ground floor in this section",
+      "Rename the section to \"Through atrium\"",
+      "Move the section line 5 m north\n\n# Example\n```ts\nawait snaptrude.presentation.sections.update(sectionId, {\nisFlipped: true,\ndepth: 60,\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginSection"
+  },
   {
     "path": "presentation.shapes.list",
     "namespace": "presentation.shapes",

package/dist/api/presentation/index.d.ts

@@ -11,6 +11,7 @@ import { PluginPresentationTablesApi } from "./tables";
 import { PluginPresentationSlideshowApi } from "./slideshow";
 import { PluginPresentationImportApi } from "./import";
 import { PluginPresentationWalkthroughsApi } from "./walkthroughs";
+import { PluginPresentationSectionsApi } from "./sections";
 import { PluginPresentationExportResult, type PluginPresentationExportFormat, type PluginPresentationExportResolution } from "./export";
 /**
  * Presentation APIs — prepare and assemble presentations.
@@ -32,6 +33,7 @@ import { PluginPresentationExportResult, type PluginPresentationExportFormat, ty
  * - {@linkcode PluginPresentationApi.import} — Import reference images/PDFs onto the canvas
  * - {@linkcode PluginPresentationApi.aiInspiration} — Present-mode AI image/video generation
  * - {@linkcode PluginPresentationApi.walkthroughs} — Camera paths through the model: create, play, capture, export as video
+ * - {@linkcode PluginPresentationApi.sections} — Section lines: create, edit, open their views, and read what each cuts
  *
  * Accessed via `snaptrude.presentation`.
  */
@@ -67,6 +69,12 @@ export declare abstract class PluginPresentationApi {
      * Present canvas. See {@linkcode PluginPresentationWalkthroughsApi}.
      */
     abstract walkthroughs: PluginPresentationWalkthroughsApi;
+    /**
+     * Sections — lines on the plan that cut the model: create, edit and delete
+     * them, open their views, and read what each one cuts (`getCut`). See
+     * {@linkcode PluginPresentationSectionsApi}.
+     */
+    abstract sections: PluginPresentationSectionsApi;
     /**
      * Export the presentation's layout sheets to a downloadable file (PDF / PNG /
      * JPG) and return the encoded bytes as base64. Wraps the Present-mode Export
@@ -112,5 +120,6 @@ export * from "./slideshow";
 export * from "./import";
 export * from "./aiInspiration";
 export * from "./walkthroughs";
+export * from "./sections";
 export * from "./export";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/presentation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AACpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,kCAAkC,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,gCAAgC,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,iCAAiC,EAAE,MAAM,gBAAgB,CAAA;AAClE,OAAO,EACL,8BAA8B,EAC9B,KAAK,8BAA8B,EACnC,KAAK,kCAAkC,EACxC,MAAM,UAAU,CAAA;AAEjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,qBAAqB;IACzC,qEAAqE;IACrE,SAAgB,KAAK,EAAE,0BAA0B,CAAA;IACjD,4JAA4J;IAC5J,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,mHAAmH;IACnH,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,4JAA4J;IAC5J,SAAgB,WAAW,EAAE,gCAAgC,CAAA;IAC7D,+GAA+G;IAC/G,SAAgB,QAAQ,EAAE,6BAA6B,CAAA;IACvD,wHAAwH;IACxH,SAAgB,QAAQ,EAAE,6BAA6B,CAAA;IACvD,2IAA2I;IAC3I,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,uHAAuH;IACvH,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,wGAAwG;IACxG,SAAgB,SAAS,EAAE,8BAA8B,CAAA;IACzD,yGAAyG;IACzG,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD;;;OAGG;IACH,SAAgB,aAAa,EAAE,kCAAkC,CAAA;IACjE;;;;OAIG;IACH,SAAgB,YAAY,EAAE,iCAAiC,CAAA;IAE/D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,MAAM,CACpB,MAAM,EAAE,8BAA8B,EACtC,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;QACnB,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,UAAU,CAAC,EAAE,kCAAkC,CAAA;QAC/C,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,GACA,eAAe,CAAC,8BAA8B,CAAC;;CAGnD;AAED,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AACpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,kCAAkC,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,gCAAgC,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,iCAAiC,EAAE,MAAM,gBAAgB,CAAA;AAClE,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EACL,8BAA8B,EAC9B,KAAK,8BAA8B,EACnC,KAAK,kCAAkC,EACxC,MAAM,UAAU,CAAA;AAEjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,qBAAqB;IACzC,qEAAqE;IACrE,SAAgB,KAAK,EAAE,0BAA0B,CAAA;IACjD,4JAA4J;IAC5J,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,mHAAmH;IACnH,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,4JAA4J;IAC5J,SAAgB,WAAW,EAAE,gCAAgC,CAAA;IAC7D,+GAA+G;IAC/G,SAAgB,QAAQ,EAAE,6BAA6B,CAAA;IACvD,wHAAwH;IACxH,SAAgB,QAAQ,EAAE,6BAA6B,CAAA;IACvD,2IAA2I;IAC3I,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,uHAAuH;IACvH,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,wGAAwG;IACxG,SAAgB,SAAS,EAAE,8BAA8B,CAAA;IACzD,yGAAyG;IACzG,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD;;;OAGG;IACH,SAAgB,aAAa,EAAE,kCAAkC,CAAA;IACjE;;;;OAIG;IACH,SAAgB,YAAY,EAAE,iCAAiC,CAAA;IAC/D;;;;OAIG;IACH,SAAgB,QAAQ,EAAE,6BAA6B,CAAA;IAEvD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,MAAM,CACpB,MAAM,EAAE,8BAA8B,EACtC,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;QACnB,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,UAAU,CAAC,EAAE,kCAAkC,CAAA;QAC/C,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,GACA,eAAe,CAAC,8BAA8B,CAAC;;CAGnD;AAED,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA"}

package/dist/api/presentation/sections.d.ts

@@ -0,0 +1,461 @@
+import * as z from "zod";
+import type { PluginApiReturn } from "../../types";
+/** A point on the plan: world `x` and `z` in babylon units. */
+export declare const PluginSectionPoint: z.ZodObject<{
+    x: z.ZodNumber;
+    z: z.ZodNumber;
+}, z.core.$strict>;
+export type PluginSectionPoint = z.infer<typeof PluginSectionPoint>;
+/**
+ * A section: a line drawn on the plan that cuts the model and looks one way
+ * along it.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sectionId` | `string` | The section's id |
+ * | `name` | `string` | Its name in the Views panel ("Section 1") |
+ * | `tagLabel` | `string` | What its heads are marked with on the plan ("A") |
+ * | `buildingId` | `string` | The building it belongs to |
+ * | `start` | {@linkcode PluginSectionPoint} | First head on the plan |
+ * | `end` | {@linkcode PluginSectionPoint} | Second head on the plan |
+ * | `isFlipped` | `boolean` | Looks the other way along the line |
+ * | `depth` | `number` | How far behind the line the view keeps, babylon units |
+ * | `base` | `number` | Bottom of the slice, world Y |
+ * | `top` | `number` | Top of the slice, world Y |
+ * | `isHidden` | `boolean` | The line is hidden on the plan |
+ * | `isLocked` | `boolean` | Geometry edits are refused |
+ * | `isActive` | `boolean` | It is the section view open now |
+ */
+export declare const PluginSection: z.ZodObject<{
+    sectionId: z.ZodString;
+    name: z.ZodString;
+    tagLabel: z.ZodString;
+    buildingId: z.ZodString;
+    start: z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>;
+    end: z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>;
+    isFlipped: z.ZodBoolean;
+    depth: z.ZodNumber;
+    base: z.ZodNumber;
+    top: z.ZodNumber;
+    isHidden: z.ZodBoolean;
+    isLocked: z.ZodBoolean;
+    isActive: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginSection = z.infer<typeof PluginSection>;
+export declare const PluginSectionIdArgs: z.ZodObject<{
+    sectionId: z.ZodString;
+}, z.core.$strict>;
+export type PluginSectionIdArgs = z.infer<typeof PluginSectionIdArgs>;
+/**
+ * Options for {@linkcode PluginPresentationSectionsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | Name in the Views panel (default: the next "Section N") |
+ * | `tagLabel` | `string \| undefined` | Head mark on the plan (default: the next free mark) |
+ * | `depth` | `number \| undefined` | How far behind the line the view keeps (default: to the far side of the model) |
+ * | `base` | `number \| undefined` | Bottom of the slice, world Y (default: the building's base) |
+ * | `top` | `number \| undefined` | Top of the slice, world Y (default: the building's top) |
+ * | `buildingId` | `string \| undefined` | Building it belongs to (default: the active one) |
+ * | `isActive` | `boolean \| undefined` | Open the section view once created (default `false`) |
+ */
+export declare const PluginSectionCreateOptions: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    tagLabel: z.ZodOptional<z.ZodString>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    base: z.ZodOptional<z.ZodNumber>;
+    top: z.ZodOptional<z.ZodNumber>;
+    buildingId: z.ZodOptional<z.ZodString>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type PluginSectionCreateOptions = z.infer<typeof PluginSectionCreateOptions>;
+export declare const PluginSectionCreateArgs: z.ZodObject<{
+    start: z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>;
+    end: z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>;
+    options: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        tagLabel: z.ZodOptional<z.ZodString>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        base: z.ZodOptional<z.ZodNumber>;
+        top: z.ZodOptional<z.ZodNumber>;
+        buildingId: z.ZodOptional<z.ZodString>;
+        isActive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PluginSectionCreateArgs = z.infer<typeof PluginSectionCreateArgs>;
+/**
+ * The fields to change in {@linkcode PluginPresentationSectionsApi.update};
+ * omitted fields keep their value.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | Name in the Views panel |
+ * | `tagLabel` | `string \| undefined` | Head mark on the plan |
+ * | `start` | {@linkcode PluginSectionPoint} `\| undefined` | First head |
+ * | `end` | {@linkcode PluginSectionPoint} `\| undefined` | Second head |
+ * | `isFlipped` | `boolean \| undefined` | Look the other way; without `depth`, the depth re-spans the model the new way |
+ * | `depth` | `number \| undefined` | View depth behind the line, > 0 |
+ * | `base` | `number \| undefined` | Bottom of the slice, world Y |
+ * | `top` | `number \| undefined` | Top of the slice, world Y; above `base` |
+ * | `isHidden` | `boolean \| undefined` | Hide the line on the plan |
+ */
+export declare const PluginSectionPatch: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    tagLabel: z.ZodOptional<z.ZodString>;
+    start: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>>;
+    end: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>>;
+    isFlipped: z.ZodOptional<z.ZodBoolean>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    base: z.ZodOptional<z.ZodNumber>;
+    top: z.ZodOptional<z.ZodNumber>;
+    isHidden: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type PluginSectionPatch = z.infer<typeof PluginSectionPatch>;
+export declare const PluginSectionUpdateArgs: z.ZodObject<{
+    sectionId: z.ZodString;
+    patch: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        tagLabel: z.ZodOptional<z.ZodString>;
+        start: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>>;
+        end: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>>;
+        isFlipped: z.ZodOptional<z.ZodBoolean>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        base: z.ZodOptional<z.ZodNumber>;
+        top: z.ZodOptional<z.ZodNumber>;
+        isHidden: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PluginSectionUpdateArgs = z.infer<typeof PluginSectionUpdateArgs>;
+/**
+ * Options for {@linkcode PluginPresentationSectionsApi.getCut}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `maxSegmentsPerElement` | `number \| undefined` | Outline segments to return per element, 0 to 2000 (default 0: none) |
+ */
+export declare const PluginSectionCutOptions: z.ZodObject<{
+    maxSegmentsPerElement: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type PluginSectionCutOptions = z.infer<typeof PluginSectionCutOptions>;
+export declare const PluginSectionCutArgs: z.ZodObject<{
+    sectionId: z.ZodString;
+    options: z.ZodOptional<z.ZodObject<{
+        maxSegmentsPerElement: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PluginSectionCutArgs = z.infer<typeof PluginSectionCutArgs>;
+/**
+ * A rect on the cutting plane. `u` runs along the line from the first head
+ * (0) to the second (the line's length); `v` is world Y.
+ */
+export declare const PluginSectionExtent: z.ZodObject<{
+    uMin: z.ZodNumber;
+    uMax: z.ZodNumber;
+    vMin: z.ZodNumber;
+    vMax: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginSectionExtent = z.infer<typeof PluginSectionExtent>;
+/**
+ * One element a section cuts.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `entityId` | `string` | The element's component id (a `ComponentHandle`) |
+ * | `type` | `string` | Its component type ("wall", "slab", "mass", …) |
+ * | `area` | `number` | Cut area inside the section's extents, square babylon units |
+ * | `perimeter` | `number` | Length of the cut outline inside the extents, babylon units |
+ * | `extent` | {@linkcode PluginSectionExtent} | Where the cut lies on the plane |
+ * | `isHatched` | `boolean` | `false` for masses and voids, which the drawing leaves unfilled |
+ * | `isOpening` | `boolean` | Doors and windows, which the drawing fills white |
+ * | `segments` | `[u0, v0, u1, v1][]` | Cut outline segments, when asked for |
+ * | `droppedSegmentCount` | `number` | Segments not returned because of `maxSegmentsPerElement` |
+ */
+export declare const PluginSectionCutElement: z.ZodObject<{
+    entityId: z.ZodString;
+    type: z.ZodString;
+    area: z.ZodNumber;
+    perimeter: z.ZodNumber;
+    extent: z.ZodObject<{
+        uMin: z.ZodNumber;
+        uMax: z.ZodNumber;
+        vMin: z.ZodNumber;
+        vMax: z.ZodNumber;
+    }, z.core.$strip>;
+    isHatched: z.ZodBoolean;
+    isOpening: z.ZodBoolean;
+    segments: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    droppedSegmentCount: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginSectionCutElement = z.infer<typeof PluginSectionCutElement>;
+/**
+ * What a section cuts, from {@linkcode PluginPresentationSectionsApi.getCut}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sectionId` | `string` | The section |
+ * | `origin` | `{ x, y, z }` | World point at `u = 0, v = 0`: the first head, at Y 0 |
+ * | `uAxis` | `{ x, y, z }` | Unit direction of `u`: from the first head to the second |
+ * | `normal` | `{ x, y, z }` | Unit direction the section looks |
+ * | `extent` | {@linkcode PluginSectionExtent} | The cut rect: `u` 0 to the line's length, `v` base to top |
+ * | `elements` | {@linkcode PluginSectionCutElement}`[]` | What it cuts, largest area first |
+ * | `candidateCount` | `number` | Meshes near the plane that were tested |
+ * | `durationInMs` | `number` | Time the query took |
+ */
+export declare const PluginSectionCut: z.ZodObject<{
+    sectionId: z.ZodString;
+    origin: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    uAxis: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    normal: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    extent: z.ZodObject<{
+        uMin: z.ZodNumber;
+        uMax: z.ZodNumber;
+        vMin: z.ZodNumber;
+        vMax: z.ZodNumber;
+    }, z.core.$strip>;
+    elements: z.ZodArray<z.ZodObject<{
+        entityId: z.ZodString;
+        type: z.ZodString;
+        area: z.ZodNumber;
+        perimeter: z.ZodNumber;
+        extent: z.ZodObject<{
+            uMin: z.ZodNumber;
+            uMax: z.ZodNumber;
+            vMin: z.ZodNumber;
+            vMax: z.ZodNumber;
+        }, z.core.$strip>;
+        isHatched: z.ZodBoolean;
+        isOpening: z.ZodBoolean;
+        segments: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        droppedSegmentCount: z.ZodNumber;
+    }, z.core.$strip>>;
+    candidateCount: z.ZodNumber;
+    durationInMs: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginSectionCut = z.infer<typeof PluginSectionCut>;
+/**
+ * Sections: lines on the plan that cut the model, each with its own section
+ * view.
+ *
+ * A section is a cutting plane through its line, vertical, looking one way
+ * along it; its view keeps `depth` behind the line, between `base` and `top`.
+ * Create, read, edit and delete sections (`create`, `list`, `get`, `update`,
+ * `delete`), open one's view (`setActive`, `getActive`), and ask what it cuts
+ * (`getCut`): which elements the plane passes through, with the area, outline
+ * and extent of each cut. `getCut` is computed from the model, needs no open
+ * view and changes nothing.
+ *
+ * Writes are write-gated and each call is one undo step. Geometry edits
+ * (`start`, `end`, `isFlipped`, `depth`, `base`, `top`) are refused on a locked
+ * section; names, marks and hiding are not, and repeating a locked section's
+ * geometry unchanged is not a geometry edit. View-only collaborators cannot
+ * write.
+ *
+ * Positions are world coordinates in internal `babylon` units (1 unit =
+ * 0.254 m, Y up); a section's heads are plan points `{ x, z }`. Accessed via
+ * `snaptrude.presentation.sections`.
+ */
+export declare abstract class PluginPresentationSectionsApi {
+    constructor();
+    /**
+     * List the project's sections, in Views panel order.
+     *
+     * @returns Every {@linkcode PluginSection} (`[]` when there are none).
+     *
+     * @examplePrompt Which sections are there?
+     * @examplePrompt List the section lines in this project
+     * @examplePrompt Is there a section through the stair?
+     *
+     * # Example
+     * ```ts
+     * const sections = await snaptrude.presentation.sections.list()
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginSection[]>;
+    /**
+     * Get one section by id.
+     *
+     * @param sectionId - The section's id
+     * @returns The {@linkcode PluginSection}, or `null` when there is none with that id.
+     *
+     * @examplePrompt Where does Section A run?
+     * @examplePrompt How deep is this section?
+     *
+     * # Example
+     * ```ts
+     * const section = await snaptrude.presentation.sections.get(sectionId)
+     * console.log(section?.start, section?.end)
+     * ```
+     */
+    abstract get(sectionId: string): PluginApiReturn<PluginSection | null>;
+    /**
+     * Get the section whose view is open.
+     *
+     * @returns The open {@linkcode PluginSection}, or `null` when no section view is open.
+     *
+     * @examplePrompt Which section am I looking at?
+     *
+     * # Example
+     * ```ts
+     * const open = await snaptrude.presentation.sections.getActive()
+     * ```
+     */
+    abstract getActive(): PluginApiReturn<PluginSection | null>;
+    /**
+     * Open a section's view, or close the open one with `null`. Opening frames
+     * the section's saved camera, or a straight-on view when it has none.
+     * Closing returns to 3D; with no section view open, `null` does nothing. Not
+     * an edit: nothing is added to the undo history.
+     *
+     * @param sectionId - The section to open, or `null` to close the section view
+     * @returns The open {@linkcode PluginSection}, or `null` after closing.
+     * @throws HANDLE_INVALID when there is no section with that id.
+     *
+     * @examplePrompt Open Section A
+     * @examplePrompt Show me the section through the atrium
+     * @examplePrompt Close the section view
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.presentation.sections.setActive(section.sectionId)
+     * await snaptrude.presentation.sections.setActive(null)
+     * ```
+     */
+    abstract setActive(sectionId: string | null): PluginApiReturn<PluginSection | null>;
+    /**
+     * Draw a section line from `start` to `end` on the plan. The section looks
+     * along the line's direction turned a quarter turn — a line drawn toward +x
+     * looks toward +z; flip it with `update(id, { isFlipped: true })`. Its slice
+     * defaults to the building's full height and its depth to the far side of
+     * the model. Write-gated; one undo step.
+     *
+     * @param start - First head, a plan point `{ x, z }`
+     * @param end - Second head; must differ from `start`
+     * @param options - Name, mark, depth, slice, building and whether to open it ({@linkcode PluginSectionCreateOptions})
+     * @returns The new {@linkcode PluginSection}.
+     * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. VALIDATION when
+     *   `start` and `end` coincide or `top` is not above `base`. PRECONDITION_FAILED
+     *   when the project is view-only or has no model to cut.
+     *
+     * @examplePrompt Cut a section through the middle of the building, east to west
+     * @examplePrompt Add a section across the stair core
+     * @examplePrompt Draw a longitudinal section and open it
+     *
+     * # Example
+     * ```ts
+     * const section = await snaptrude.presentation.sections.create(
+     *   { x: -40, z: 10 },
+     *   { x: 40, z: 10 },
+     *   { name: "Longitudinal", isActive: true },
+     * )
+     * ```
+     */
+    abstract create(start: PluginSectionPoint, end: PluginSectionPoint, options?: PluginSectionCreateOptions): PluginApiReturn<PluginSection>;
+    /**
+     * Change a section. Only the given fields change; the whole patch is one
+     * undo step. Flipping without a `depth` carries the depth to the far side of
+     * the model in the new direction, as `create` does. Write-gated.
+     *
+     * @param sectionId - The section's id
+     * @param patch - The fields to change ({@linkcode PluginSectionPatch})
+     * @returns The updated {@linkcode PluginSection}.
+     * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+     *   there is no section with that id. VALIDATION when the heads coincide or `top`
+     *   is not above `base`. PRECONDITION_FAILED when the project is view-only, or the
+     *   patch changes a locked section's geometry.
+     *
+     * @examplePrompt Make Section A look the other way
+     * @examplePrompt Only show the ground floor in this section
+     * @examplePrompt Rename the section to "Through atrium"
+     * @examplePrompt Move the section line 5 m north
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.presentation.sections.update(sectionId, {
+     *   isFlipped: true,
+     *   depth: 60,
+     * })
+     * ```
+     */
+    abstract update(sectionId: string, patch: PluginSectionPatch): PluginApiReturn<PluginSection>;
+    /**
+     * Delete a section. Closes its view first if it is open. Write-gated; one
+     * undo step.
+     *
+     * @param sectionId - The section's id
+     * @returns `true` once it has been deleted.
+     * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+     *   there is no section with that id. PRECONDITION_FAILED when the project is view-only.
+     *
+     * @examplePrompt Delete Section B
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.presentation.sections.delete(sectionId)
+     * ```
+     */
+    abstract delete(sectionId: string): PluginApiReturn<boolean>;
+    /**
+     * What a section cuts: every element its cutting plane passes through within
+     * the section's extents, with the cut's area, outline length and extent on
+     * the plane, largest first. Computed from the model, not from the drawing, so
+     * it needs no open view and works however the section is shown; furniture is
+     * left out, as in the drawing, and so is anything hidden in the model. Areas are exact for closed solids. Repeated
+     * calls reuse the cuts of elements that have not changed. Read-only.
+     *
+     * @param sectionId - The section's id
+     * @param options - Whether to return outline segments ({@linkcode PluginSectionCutOptions})
+     * @returns The {@linkcode PluginSectionCut}.
+     * @throws HANDLE_INVALID when there is no section with that id.
+     *
+     * @examplePrompt Which walls does Section A cut?
+     * @examplePrompt How thick is the slab where the section crosses it?
+     * @examplePrompt Does this section go through the stair?
+     * @examplePrompt What is the floor-to-floor height in this section?
+     *
+     * # Example
+     * ```ts
+     * const cut = await snaptrude.presentation.sections.getCut(sectionId)
+     * const walls = cut.elements.filter((element) => element.type === "wall")
+     * const thickest = walls[0]
+     * console.log(thickest.extent.uMax - thickest.extent.uMin)
+     * ```
+     */
+    abstract getCut(sectionId: string, options?: PluginSectionCutOptions): PluginApiReturn<PluginSectionCut>;
+}
+//# sourceMappingURL=sections.d.ts.map

package/dist/api/presentation/sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sections.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/sections.ts"],"names":[],"mappings":"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"}