@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/presentation/index.ts

@@ -1,126 +1,160 @@
-import { PluginApiReturn } from "../../types"
-import { PluginPresentationViewsApi } from "./views"
-import { PluginPresentationCameraApi } from "./camera"
-import { PluginPresentationAIInspirationApi } from "./aiInspiration"
-import { PluginPresentationSheetsApi } from "./sheets"
-import { PluginPresentationPlacedViewsApi } from "./placedViews"
-import { PluginPresentationDiagramsApi } from "./diagrams"
-import { PluginPresentationAnnotateApi } from "./annotate"
-import { PluginPresentationShapesApi } from "./shapes"
-import { PluginPresentationTablesApi } from "./tables"
-import { PluginPresentationSlideshowApi } from "./slideshow"
-import { PluginPresentationImportApi } from "./import"
-import { PluginPresentationWalkthroughsApi } from "./walkthroughs"
-import {
-  PluginPresentationExportResult,
-  type PluginPresentationExportFormat,
-  type PluginPresentationExportResolution,
-} from "./export"
-
-/**
- * Presentation APIs — prepare and assemble presentations.
- *
- * Reads describe the artifacts a presentation is built from (saved views, layout
- * sheets); writes assemble them (place views/diagrams on sheets, import
- * references, capture/save views). Present-mode AI Inspiration also lives here.
- *
- * Several members require **Present mode to be open** (the documentation editor):
- * sheets, diagram placement, and import.
- *
- * - {@linkcode PluginPresentationApi.views} — Saved 2D/3D views (list, get, capture, activate, create)
- * - {@linkcode PluginPresentationApi.camera} — The Present canvas camera (screenshot, pan/zoom, frame sheets)
- * - {@linkcode PluginPresentationApi.sheets} — Layout sheets (list, get, create, place views)
- * - {@linkcode PluginPresentationApi.placedViews} — Views already placed on the canvas (move, scale, crop)
- * - {@linkcode PluginPresentationApi.diagrams} — Generate program/site diagram sheets, place diagram images
- * - {@linkcode PluginPresentationApi.tables} — Place data tables on sheets
- * - {@linkcode PluginPresentationApi.slideshow} — Run the Present-mode slideshow
- * - {@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
- *
- * Accessed via `snaptrude.presentation`.
- */
-export abstract class PluginPresentationApi {
-  /** Saved 2D/3D views. See {@linkcode PluginPresentationViewsApi}. */
-  public abstract views: PluginPresentationViewsApi
-  /** The Present canvas camera — screenshot what is on screen, read/pan/zoom it, frame sheets (Present mode). See {@linkcode PluginPresentationCameraApi}. */
-  public abstract camera: PluginPresentationCameraApi
-  /** Layout sheets — list/get/create and place views (Present mode). See {@linkcode PluginPresentationSheetsApi}. */
-  public abstract sheets: PluginPresentationSheetsApi
-  /** Placed views — layout of the view shapes on the canvas: move/scale/setScale/setCrop (Present mode). See {@linkcode PluginPresentationPlacedViewsApi}. */
-  public abstract placedViews: PluginPresentationPlacedViewsApi
-  /** Program/adjacency/site diagrams — place images on sheets. See {@linkcode PluginPresentationDiagramsApi}. */
-  public abstract diagrams: PluginPresentationDiagramsApi
-  /** Annotations on Present-mode sheets — text/arrows/notes/geo shapes. See {@linkcode PluginPresentationAnnotateApi}. */
-  public abstract annotate: PluginPresentationAnnotateApi
-  /** Plugin-owned keyed shapes — upsert/remove/list so reruns update instead of duplicating. See {@linkcode PluginPresentationShapesApi}. */
-  public abstract shapes: PluginPresentationShapesApi
-  /** Data tables on Present sheets — place string rows as a table shape. See {@linkcode PluginPresentationTablesApi}. */
-  public abstract tables: PluginPresentationTablesApi
-  /** The Present-mode slideshow — start/stop/getState. See {@linkcode PluginPresentationSlideshowApi}. */
-  public abstract slideshow: PluginPresentationSlideshowApi
-  /** Import reference images/PDFs onto the Present canvas. See {@linkcode PluginPresentationImportApi}. */
-  public abstract import: PluginPresentationImportApi
-  /**
-   * Present-mode AI Inspiration image/video generation. See
-   * {@linkcode PluginPresentationAIInspirationApi}.
-   */
-  public abstract aiInspiration: PluginPresentationAIInspirationApi
-  /**
-   * Walkthroughs — camera paths through the model: create (keyframes, floor
-   * points, camera-move presets), play, capture and export as video onto the
-   * Present canvas. See {@linkcode PluginPresentationWalkthroughsApi}.
-   */
-  public abstract walkthroughs: PluginPresentationWalkthroughsApi
-
-  /**
-   * 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
-   * dialog pipeline headlessly. Requires Present mode to be open.
-   *
-   * @param format - Output format: `"pdf"`, `"png"`, or `"jpg"`.
-   * @param options - Optional `sheetIds` (all sheets when omitted), `combine`
-   *   (PDF only — one multi-page file vs one per sheet, default `true`),
-   *   `resolution` (raster target size for `png`/`jpg`), and `fileName`.
-   * @returns A {@linkcode PluginPresentationExportResult} — always a `files`
-   *   array (one entry for a combined PDF, one per sheet otherwise).
-   * @throws If Present mode is not open, a `sheetId` is unknown, or a sheet
-   *   fails to serialize/encode.
-   *
-   * @examplePrompt Export the presentation as a PDF
-   * @examplePrompt Download all sheets as a single PDF
-   * @examplePrompt Export sheet 1 as a PNG
-   * @examplePrompt Save the presentation sheets as JPG images
-   * @examplePrompt Export these sheets to PDF at high resolution
-   *
-   * # Example
-   * ```ts
-   * const { files } = await snaptrude.presentation.export("pdf")
-   * ```
-   */
-  public abstract export(
-    format: PluginPresentationExportFormat,
-    options?: {
-      sheetIds?: string[]
-      combine?: boolean
-      resolution?: PluginPresentationExportResolution
-      fileName?: string
-    },
-  ): PluginApiReturn<PluginPresentationExportResult>
-
-  constructor() {}
-}
-
-export * from "./views"
-export * from "./camera"
-export * from "./sheets"
-export * from "./placedViews"
-export * from "./diagrams"
-export * from "./annotate"
-export * from "./shapes"
-export * from "./tables"
-export * from "./slideshow"
-export * from "./import"
-export * from "./aiInspiration"
-export * from "./walkthroughs"
-export * from "./export"
+import { PluginApiReturn } from "../../types"
+import { PluginPresentationViewsApi } from "./views"
+import { PluginPresentationCameraApi } from "./camera"
+import { PluginPresentationAIInspirationApi } from "./aiInspiration"
+import { PluginPresentationSheetsApi } from "./sheets"
+import { PluginPresentationPlacedViewsApi } from "./placedViews"
+import { PluginPresentationDiagramsApi } from "./diagrams"
+import { PluginPresentationDrawingsApi } from "./drawings"
+import { PluginPresentationViewPresetsApi } from "./viewPresets"
+import { PluginPresentationAnnotateApi } from "./annotate"
+import { PluginPresentationShapesApi } from "./shapes"
+import { PluginPresentationTablesApi } from "./tables"
+import { PluginPresentationSlideshowApi } from "./slideshow"
+import { PluginPresentationImportApi } from "./import"
+import { PluginPresentationWalkthroughsApi } from "./walkthroughs"
+import { PluginPresentationSectionsApi } from "./sections"
+import {
+  type PluginPresentationExportResult,
+  type PluginPresentationExportDownloadResult,
+  type PluginPresentationExportFormat,
+  type PluginPresentationExportOptions,
+} from "./export"
+
+/**
+ * Presentation APIs — prepare and assemble presentations.
+ *
+ * Reads describe the artifacts a presentation is built from (saved views, layout
+ * sheets); writes assemble them (place views/diagrams on sheets, import
+ * references, capture/save views). Present-mode AI Inspiration also lives here.
+ *
+ * Several members require **Present mode to be open** (the documentation editor):
+ * sheets, diagram placement, and import.
+ *
+ * - {@linkcode PluginPresentationApi.views} — Saved 2D/3D views (list, get, capture, activate, create)
+ * - {@linkcode PluginPresentationApi.camera} — The Present canvas camera (screenshot, pan/zoom, frame sheets)
+ * - {@linkcode PluginPresentationApi.drawings} — Drawings made from saved views (create, rescale, crop, restyle, labels, export)
+ * - {@linkcode PluginPresentationApi.viewPresets} — Reusable drawing styles (list, get, create, update, copy, rename, delete)
+ * - {@linkcode PluginPresentationApi.sheets} — Layout sheets (list, get, create, place views and drawings)
+ * - {@linkcode PluginPresentationApi.placedViews} — Views already placed on the canvas (move, scale, crop)
+ * - {@linkcode PluginPresentationApi.diagrams} — Generate program/site diagram sheets, place diagram images
+ * - {@linkcode PluginPresentationApi.tables} — Place data tables on sheets
+ * - {@linkcode PluginPresentationApi.slideshow} — Run the Present-mode slideshow
+ * - {@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`.
+ */
+export abstract class PluginPresentationApi {
+  /** Saved 2D/3D views. See {@linkcode PluginPresentationViewsApi}. */
+  public abstract views: PluginPresentationViewsApi
+  /** The Present canvas camera — screenshot what is on screen, read/pan/zoom it, frame sheets (Present mode). See {@linkcode PluginPresentationCameraApi}. */
+  public abstract camera: PluginPresentationCameraApi
+  /** Drawing deliverables made from saved views, independent of sheet composition (Present mode). See {@linkcode PluginPresentationDrawingsApi}. */
+  public abstract drawings: PluginPresentationDrawingsApi
+  /** Reusable kernel-plan styles stored in the Present document. See {@linkcode PluginPresentationViewPresetsApi}. */
+  public abstract viewPresets: PluginPresentationViewPresetsApi
+  /** Layout sheets — list/get/create and place views (Present mode). See {@linkcode PluginPresentationSheetsApi}. */
+  public abstract sheets: PluginPresentationSheetsApi
+  /** Placed views — layout of the view shapes on the canvas: move/scale/setScale/setCrop (Present mode). See {@linkcode PluginPresentationPlacedViewsApi}. */
+  public abstract placedViews: PluginPresentationPlacedViewsApi
+  /** Program/adjacency/site diagrams — place images on sheets. See {@linkcode PluginPresentationDiagramsApi}. */
+  public abstract diagrams: PluginPresentationDiagramsApi
+  /** Annotations on Present-mode sheets — text/arrows/notes/geo shapes. See {@linkcode PluginPresentationAnnotateApi}. */
+  public abstract annotate: PluginPresentationAnnotateApi
+  /** Plugin-owned keyed shapes — upsert/remove/list so reruns update instead of duplicating. See {@linkcode PluginPresentationShapesApi}. */
+  public abstract shapes: PluginPresentationShapesApi
+  /** Data tables on Present sheets — place string rows as a table shape. See {@linkcode PluginPresentationTablesApi}. */
+  public abstract tables: PluginPresentationTablesApi
+  /** The Present-mode slideshow — start/stop/getState. See {@linkcode PluginPresentationSlideshowApi}. */
+  public abstract slideshow: PluginPresentationSlideshowApi
+  /** Import reference images/PDFs onto the Present canvas. See {@linkcode PluginPresentationImportApi}. */
+  public abstract import: PluginPresentationImportApi
+  /**
+   * Present-mode AI Inspiration image/video generation. See
+   * {@linkcode PluginPresentationAIInspirationApi}.
+   */
+  public abstract aiInspiration: PluginPresentationAIInspirationApi
+  /**
+   * Walkthroughs — camera paths through the model: create (keyframes, floor
+   * points, camera-move presets), play, capture and export as video onto the
+   * Present canvas. See {@linkcode PluginPresentationWalkthroughsApi}.
+   */
+  public 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}.
+   */
+  public abstract sections: PluginPresentationSectionsApi
+
+  /**
+   * Export the presentation's layout sheets to a downloadable file (PDF / PNG /
+   * JPG). Return base64 by default; `download: true` initiates browser downloads
+   * and returns metadata without base64. Requires Present mode to be open.
+   * `fileName` is a base name WITHOUT an extension ("Floor Pattern View", never
+   * "Floor Pattern View.pdf"): the host appends the extension for the format, and
+   * a name ending in .pdf, .svg, .png, .jpg or .jpeg, a dot or a space is rejected.
+   *
+   * @param format - Output format: `"pdf"`, `"png"`, or `"jpg"`.
+   * @param options - Optional `sheetIds` (all sheets when omitted), `combine`
+   *   (PDF only — one multi-page file vs one per sheet, default `true`),
+   *   `resolution` (raster target size for `png`/`jpg`), `fileName` (a base name
+   *   WITHOUT an extension, e.g. "Floor Pattern View"; the host appends the
+   *   extension and rejects a name ending in .pdf/.svg/.png/.jpg/.jpeg), and `download`.
+   * @returns A `files` array (one entry for a combined PDF, one per sheet otherwise).
+   *   Downloads return {@linkcode PluginPresentationExportDownloadResult}; otherwise
+   *   {@linkcode PluginPresentationExportResult}. Download initiation does not prove
+   *   the browser saved the file; multiple downloads may require user permission.
+   * @throws If Present mode is not open, a `sheetId` is unknown, or a sheet
+   *   fails to serialize/encode.
+   *
+   * @examplePrompt Export the presentation as a PDF
+   * @examplePrompt Download all sheets as a single PDF
+   * @examplePrompt Export sheet 1 as a PNG
+   * @examplePrompt Save the presentation sheets as JPG images
+   * @examplePrompt Export these sheets to PDF at high resolution
+   *
+   * # Example
+   * ```ts
+   * const { files } = await snaptrude.presentation.export("pdf")
+   * const download = await snaptrude.presentation.export("pdf", { download: true })
+   * ```
+   */
+  public abstract export(
+    format: PluginPresentationExportFormat,
+    options?: PluginPresentationExportOptions & { download?: false },
+  ): PluginApiReturn<PluginPresentationExportResult>
+  public abstract export(
+    format: PluginPresentationExportFormat,
+    options: PluginPresentationExportOptions & { download: true },
+  ): PluginApiReturn<PluginPresentationExportDownloadResult>
+  public abstract export(
+    format: PluginPresentationExportFormat,
+    options?: PluginPresentationExportOptions,
+  ): PluginApiReturn<
+    PluginPresentationExportResult | PluginPresentationExportDownloadResult
+  >
+
+  constructor() {}
+}
+
+export * from "./views"
+export * from "./camera"
+export * from "./sheets"
+export * from "./placedViews"
+export * from "./diagrams"
+export * from "./annotate"
+export * from "./shapes"
+export * from "./tables"
+export * from "./slideshow"
+export * from "./import"
+export * from "./aiInspiration"
+export * from "./walkthroughs"
+export * from "./sections"
+export * from "./export"
+export * from "./drawings"
+export * from "./drawingContract"
+export * from "./viewPresets"