@snaptrude/plugin-core 0.10.0 → 1.0.0

package/src/api/presentation/placedViews.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { PluginSheetPosition } from "./sheets"
+import { PluginStandardDrawingScale } from "./drawingContract"
 
 /**
  * Placed views — the view shapes already laid out on the Present canvas.
@@ -141,14 +142,21 @@ export abstract class PluginPresentationPlacedViewsApi {
 
   /**
    * Set a placed view's architectural scale.
+   * `scale` must be a standard architectural scale denominator (100 means 1:100)
+   * in the project's unit system; any other value is rejected. Metric: 10, 20, 50,
+   * 100, 150, 200, 250, 500, 1000. Imperial detail: 12, 16, 24, 32, 48, 64, 96, 128,
+   * 192, 384, 768, 1536 (1" = 1' to 1/128" = 1'; 48 is 1/4" = 1', 96 is 1/8" = 1').
+   * Imperial site: 120, 240, 360, 480, 600, 1200, 2400, 3600, 4800 (1" = 10' to
+   * 1" = 400'). Pick the LARGEST standard scale (smallest denominator) at which the
+   * view still fits its frame or sheet and its room labels stay readable: for a
+   * building floor plan that is usually 1:50 to 1:200 (1/4" = 1' to 1/16" = 1').
+   * Never use a site-sized scale (1:500 and up, 1/64" = 1' (768) and smaller,
+   * 1" = 20' (240) and up) for a single building plan unless the user asked for it.
    *
    * Applies a standard architectural scale — the same write the placed view's
    * Scale dropdown performs. The view (and its labels) is resized about its
-   * top-left corner so it prints at the given scale. `scale` must be one of
-   * the standard values for the project's unit system (metric `10, 20, 50,
-   * 100, 150, 200, 250, 500, 1000`; imperial e.g. `48` for 1/4″ = 1′, `96`
-   * for 1/8″ = 1′, `120` for 1″ = 10′) — the same validation as
-   * `sheets.place`. 3D views have no architectural scale — calling this on
+   * top-left corner so it prints at the given scale (the same validation as
+   * `sheets.place`). 3D views have no architectural scale — calling this on
    * one throws. Requires Present mode to be open.
    *
    * @param shapeId - The placed view shape to set the scale of.
@@ -741,7 +749,7 @@ export type PluginPresentationPlacedViewsScaleArgs = z.infer<
  */
 export const PluginPresentationPlacedViewsSetScaleArgs = z.object({
   shapeId: z.string(),
-  scale: z.number().positive(),
+  scale: PluginStandardDrawingScale,
 })
 export type PluginPresentationPlacedViewsSetScaleArgs = z.infer<
   typeof PluginPresentationPlacedViewsSetScaleArgs
@@ -794,11 +802,28 @@ export const PluginViewSettingCategory = z.enum([
   "Envelope",
   "Facade/Mass",
   "Dimension",
+  "Grid",
+  "Walls",
+  "Columns",
+  "Beams",
+  "Doors",
+  "Windows",
+  "Floors",
+  "Slabs",
+  "Roofs",
+  "Ceilings",
+  "Staircase",
+  "Furniture",
+  "Families",
+  "Underlay",
+  "Overlay",
   "Reference Line",
   "Adjacency Line",
   "Landscape elements",
 ])
-export type PluginViewSettingCategory = z.infer<typeof PluginViewSettingCategory>
+export type PluginViewSettingCategory = z.infer<
+  typeof PluginViewSettingCategory
+>
 
 /** The 7 line dash styles (mirrors the host's LINE_STYLES). */
 export const PluginViewLineStyle = z.enum([
@@ -824,7 +849,7 @@ export type PluginViewLineStyle = z.infer<typeof PluginViewLineStyle>
  * | `lineStyle` | {@linkcode PluginViewLineStyle}? | Dash pattern |
  * | `lineColor` | `string`? | Line color, 6-digit hex (`#` optional) |
  * | `dashLength` | `number`? | Dash-length multiplier (> 0; `1` = default) |
- * | `lineWidth` | `number`? | Single line weight in mm (categories without cut/projection) |
+ * | `lineWidth` | `number`? | Single line weight in mm (Dimension: 0.05–0.7; otherwise non-negative) |
  * | `cutWidth` | `number`? | Cut-line weight in mm |
  * | `projectionWidth` | `number`? | Projection-line weight in mm |
  * | `treeLineWidth` | `number`? | Tree line weight in mm (Landscape) |
@@ -857,8 +882,13 @@ export const PluginPlacedViewStylePatch = z
     colorMode: z
       .string()
       .refine(
-        (v) => ["department", "texture", "monochrome"].includes(v) || v.startsWith("tag:"),
-        { message: "colorMode must be department, texture, monochrome, or tag:<tagCategoryId>" },
+        (v) =>
+          ["department", "texture", "monochrome"].includes(v) ||
+          v.startsWith("tag:"),
+        {
+          message:
+            "colorMode must be department, texture, monochrome, or tag:<tagCategoryId>",
+        },
       )
       .optional(),
     opacity: z.number().finite().min(0).max(100).optional(),
@@ -870,13 +900,42 @@ export const PluginPlacedViewStylePatch = z
     viewStyle: z.enum(["NONE", "FILLET", "BUBBLE"]).optional(),
     radius: z.number().finite().min(0).optional(),
     inset: z.number().finite().min(0).optional(),
+    // Dimension lengths are plotted paper millimetres, independent of drawing scale.
+    markerKind: z
+      .enum(["architecturalTick", "openArrow", "closedArrow"])
+      .optional(),
+    markerSize: z.number().finite().min(0.5).max(6).optional(),
+    extensionLineVisible: z.boolean().optional(),
+    extensionLineStyle: PluginViewLineStyle.optional(),
+    extensionGap: z.number().finite().min(0).max(10).optional(),
+    extensionOvershoot: z.number().finite().min(0).max(10).optional(),
+    textColor: z
+      .string()
+      .regex(/^(inherit|#[0-9a-fA-F]{6})$/)
+      .optional(),
+    textGap: z.number().finite().min(0).max(10).optional(),
+    textPlacement: z.literal("above").optional(),
+    textMask: z.boolean().optional(),
+    textMaskColor: z
+      .string()
+      .regex(/^#[0-9a-fA-F]{6}$/)
+      .optional(),
+    textMaskPadding: z.number().finite().min(0).max(5).optional(),
   })
   .strict()
-  .refine((p) => Object.keys(p).length > 0, { message: "patch must set at least one setting" })
-export type PluginPlacedViewStylePatch = z.infer<typeof PluginPlacedViewStylePatch>
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "patch must set at least one setting",
+  })
+export type PluginPlacedViewStylePatch = z.infer<
+  typeof PluginPlacedViewStylePatch
+>
 
 /** Label types that carry typography in a category's Text tab. */
-export const PluginViewLabelType = z.enum(["objectLabels", "department", "areas"])
+export const PluginViewLabelType = z.enum([
+  "objectLabels",
+  "department",
+  "areas",
+])
 export type PluginViewLabelType = z.infer<typeof PluginViewLabelType>
 
 /** Typography patch for one label type. `fontSize` is in px. */
@@ -885,7 +944,10 @@ const PluginViewFontVariantPatch = z
     fontFamily: z.string().min(1).optional(),
     fontWeight: z
       .string()
-      .regex(/^\d{3}$/, 'fontWeight must be a numeric string like "400" or "700"')
+      .regex(
+        /^\d{3}$/,
+        'fontWeight must be a numeric string like "400" or "700"',
+      )
       .optional(),
     fontStyle: z.enum(["normal", "italic"]).optional(),
     fontSize: z.number().finite().positive().max(200).optional(),
@@ -910,8 +972,12 @@ export const PluginPlacedViewFontStylesPatch = z
     areas: PluginViewFontVariantPatch.optional(),
   })
   .strict()
-  .refine((p) => Object.keys(p).length > 0, { message: "patch must set at least one field" })
-export type PluginPlacedViewFontStylesPatch = z.infer<typeof PluginPlacedViewFontStylesPatch>
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "patch must set at least one field",
+  })
+export type PluginPlacedViewFontStylesPatch = z.infer<
+  typeof PluginPlacedViewFontStylesPatch
+>
 
 /** Resolved font styles for one label type (fontSize in px). */
 export type PluginViewFontVariant = {
@@ -961,12 +1027,25 @@ export type PluginPlacedViewStylesResult = {
 }
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.updateStyles}. */
-export const PluginPlacedViewsUpdateStylesArgs = z.object({
-  shapeId: z.string().min(1),
-  category: PluginViewSettingCategory,
-  patch: PluginPlacedViewStylePatch,
-})
-export type PluginPlacedViewsUpdateStylesArgs = z.infer<typeof PluginPlacedViewsUpdateStylesArgs>
+export const PluginPlacedViewsUpdateStylesArgs = z
+  .object({
+    shapeId: z.string().min(1),
+    category: PluginViewSettingCategory,
+    patch: PluginPlacedViewStylePatch,
+  })
+  .refine(
+    ({ category, patch }) =>
+      category !== "Dimension" ||
+      patch.lineWidth === undefined ||
+      (patch.lineWidth >= 0.05 && patch.lineWidth <= 0.7),
+    {
+      message: "Dimension lineWidth must be between 0.05 and 0.7 paper mm",
+      path: ["patch", "lineWidth"],
+    },
+  )
+export type PluginPlacedViewsUpdateStylesArgs = z.infer<
+  typeof PluginPlacedViewsUpdateStylesArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.updateFontStyles}. */
 export const PluginPlacedViewsUpdateFontStylesArgs = z.object({
@@ -1011,7 +1090,9 @@ export const PluginPlacedViewsMoveLabelArgs = z.object({
   labelId: z.string().min(1),
   position: PluginSheetPosition,
 })
-export type PluginPlacedViewsMoveLabelArgs = z.infer<typeof PluginPlacedViewsMoveLabelArgs>
+export type PluginPlacedViewsMoveLabelArgs = z.infer<
+  typeof PluginPlacedViewsMoveLabelArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setLabelHidden}. */
 export const PluginPlacedViewsSetLabelHiddenArgs = z.object({
@@ -1081,14 +1162,18 @@ export const PluginPlacedViewsMoveShapeArgs = z.object({
   position: PluginSheetPosition,
   sheetId: z.string().optional(),
 })
-export type PluginPlacedViewsMoveShapeArgs = z.infer<typeof PluginPlacedViewsMoveShapeArgs>
+export type PluginPlacedViewsMoveShapeArgs = z.infer<
+  typeof PluginPlacedViewsMoveShapeArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.resizeShape}. */
 export const PluginPlacedViewsResizeShapeArgs = z.object({
   shapeId: z.string().min(1),
   factor: z.number().finite().min(0.01).max(100),
 })
-export type PluginPlacedViewsResizeShapeArgs = z.infer<typeof PluginPlacedViewsResizeShapeArgs>
+export type PluginPlacedViewsResizeShapeArgs = z.infer<
+  typeof PluginPlacedViewsResizeShapeArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.rotateShape}. */
 export const PluginPresentationPlacedViewsRotateShapeArgs = z.object({
@@ -1103,18 +1188,24 @@ export type PluginPresentationPlacedViewsRotateShapeArgs = z.infer<
 export const PluginPlacedViewsDeleteShapesArgs = z.object({
   shapeIds: z.array(z.string().min(1)).min(1).max(500),
 })
-export type PluginPlacedViewsDeleteShapesArgs = z.infer<typeof PluginPlacedViewsDeleteShapesArgs>
+export type PluginPlacedViewsDeleteShapesArgs = z.infer<
+  typeof PluginPlacedViewsDeleteShapesArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setOpacity}. */
 export const PluginPlacedViewsSetOpacityArgs = z.object({
   shapeId: z.string().min(1),
   opacity: z.number().finite().min(0).max(1),
 })
-export type PluginPlacedViewsSetOpacityArgs = z.infer<typeof PluginPlacedViewsSetOpacityArgs>
+export type PluginPlacedViewsSetOpacityArgs = z.infer<
+  typeof PluginPlacedViewsSetOpacityArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setMask}. */
 export const PluginPlacedViewsSetMaskArgs = z.object({
   shapeId: z.string().min(1),
   enabled: z.boolean(),
 })
-export type PluginPlacedViewsSetMaskArgs = z.infer<typeof PluginPlacedViewsSetMaskArgs>
+export type PluginPlacedViewsSetMaskArgs = z.infer<
+  typeof PluginPlacedViewsSetMaskArgs
+>

package/src/api/presentation/sections.ts

@@ -0,0 +1,420 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+import { Vec3Components } from "../../handles"
+
+/** A point on the plan: world `x` and `z` in babylon units. */
+export const PluginSectionPoint = z
+  .object({ x: z.number().finite(), z: z.number().finite() })
+  .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 const PluginSection = z.object({
+  sectionId: z.string(),
+  name: z.string(),
+  tagLabel: z.string(),
+  buildingId: z.string(),
+  start: PluginSectionPoint,
+  end: PluginSectionPoint,
+  isFlipped: z.boolean(),
+  depth: z.number(),
+  base: z.number(),
+  top: z.number(),
+  isHidden: z.boolean(),
+  isLocked: z.boolean(),
+  isActive: z.boolean(),
+})
+export type PluginSection = z.infer<typeof PluginSection>
+
+export const PluginSectionIdArgs = z
+  .object({ sectionId: z.string().min(1) })
+  .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 const PluginSectionCreateOptions = z
+  .object({
+    name: z.string().trim().min(1).optional(),
+    tagLabel: z.string().trim().min(1).optional(),
+    depth: z.number().finite().positive().optional(),
+    base: z.number().finite().optional(),
+    top: z.number().finite().optional(),
+    buildingId: z.string().min(1).optional(),
+    isActive: z.boolean().optional(),
+  })
+  .strict()
+export type PluginSectionCreateOptions = z.infer<
+  typeof PluginSectionCreateOptions
+>
+
+export const PluginSectionCreateArgs = z
+  .object({
+    start: PluginSectionPoint,
+    end: PluginSectionPoint,
+    options: PluginSectionCreateOptions.optional(),
+  })
+  .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 const PluginSectionPatch = z
+  .object({
+    name: z.string().trim().min(1).optional(),
+    tagLabel: z.string().trim().min(1).optional(),
+    start: PluginSectionPoint.optional(),
+    end: PluginSectionPoint.optional(),
+    isFlipped: z.boolean().optional(),
+    depth: z.number().finite().positive().optional(),
+    base: z.number().finite().optional(),
+    top: z.number().finite().optional(),
+    isHidden: z.boolean().optional(),
+  })
+  .strict()
+export type PluginSectionPatch = z.infer<typeof PluginSectionPatch>
+
+export const PluginSectionUpdateArgs = PluginSectionIdArgs.extend({
+  patch: PluginSectionPatch,
+})
+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 const PluginSectionCutOptions = z
+  .object({
+    maxSegmentsPerElement: z.number().int().min(0).max(2000).optional(),
+  })
+  .strict()
+export type PluginSectionCutOptions = z.infer<typeof PluginSectionCutOptions>
+
+export const PluginSectionCutArgs = PluginSectionIdArgs.extend({
+  options: PluginSectionCutOptions.optional(),
+})
+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 const PluginSectionExtent = z.object({
+  uMin: z.number(),
+  uMax: z.number(),
+  vMin: z.number(),
+  vMax: z.number(),
+})
+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 const PluginSectionCutElement = z.object({
+  entityId: z.string(),
+  type: z.string(),
+  area: z.number(),
+  perimeter: z.number(),
+  extent: PluginSectionExtent,
+  isHatched: z.boolean(),
+  isOpening: z.boolean(),
+  segments: z.array(z.tuple([z.number(), z.number(), z.number(), z.number()])),
+  droppedSegmentCount: z.number().int(),
+})
+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 const PluginSectionCut = z.object({
+  sectionId: z.string(),
+  origin: Vec3Components,
+  uAxis: Vec3Components,
+  normal: Vec3Components,
+  extent: PluginSectionExtent,
+  elements: z.array(PluginSectionCutElement),
+  candidateCount: z.number().int(),
+  durationInMs: z.number(),
+})
+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 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()
+   * ```
+   */
+  public 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)
+   * ```
+   */
+  public 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()
+   * ```
+   */
+  public 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)
+   * ```
+   */
+  public 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 },
+   * )
+   * ```
+   */
+  public 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,
+   * })
+   * ```
+   */
+  public 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)
+   * ```
+   */
+  public 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)
+   * ```
+   */
+  public abstract getCut(
+    sectionId: string,
+    options?: PluginSectionCutOptions,
+  ): PluginApiReturn<PluginSectionCut>
+}