@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/src/api/presentation/import.ts

@@ -4,9 +4,10 @@ import { PluginApiReturn } from "../../types"
 /**
  * Presentation import — bring external reference assets onto the Present canvas.
  *
- * `import.image` places a reference image and `import.pdf` places a PDF (each
- * page vectorized to SVG) onto the current Present sheet, returning the created
- * canvas shape ids. Requires Present mode to be open.
+ * `import.image` places a reference image, `import.pdf` places a PDF (each
+ * page vectorized to SVG), and `import.svg` places a validated SVG onto
+ * the current Present sheet, returning the created canvas shape ids. Requires
+ * Present mode to be open.
  *
  * The host engine takes a browser `File`, which a plugin worker cannot supply,
  * so these accept a `url`/`dataUrl` that the host adapts into a `File`.
@@ -19,6 +20,9 @@ export abstract class PluginPresentationImportApi {
   /**
    * Import a reference image onto the current Present sheet.
    *
+   * To place the image as a **scene** underlay to trace over — on a storey,
+   * not the Present canvas — use `core.io.import.image` instead.
+   *
    * @param source - The asset to import: exactly one of `url` or `dataUrl`.
    * @param options - Optional `position` — where to place the image on the
    *   sheet.
@@ -49,6 +53,9 @@ export abstract class PluginPresentationImportApi {
    *
    * Each page is converted to vector SVG and placed as a canvas shape.
    *
+   * To bring the PDF into the **scene** as a traceable underlay — on a storey,
+   * not the Present canvas — use `core.io.import.pdf` instead.
+   *
    * @param source - The asset to import: exactly one of `url` or `dataUrl`.
    * @param options - Optional `position` — where to place the pages on the
    *   sheet.
@@ -72,11 +79,51 @@ export abstract class PluginPresentationImportApi {
     source: { url?: string; dataUrl?: string },
     options?: { position?: { x: number; y: number } },
   ): PluginApiReturn<PluginPresentationImportResult>
+
+  /**
+   * Import an SVG onto the current Present sheet as a vector asset.
+   *
+   * An SVG-validating variant of {@linkcode PluginPresentationImportApi.image}:
+   * `import.image` already passes SVG sources through, but this method first
+   * validates that the source really is an SVG and forces the vector mime
+   * type. Throws if the source is not an SVG.
+   *
+   * **Rendering is vector up to a complexity cap.** Simple SVGs (up to ~1500
+   * SVG element nodes and ~2 MB) render true-vector and stay crisp at every
+   * zoom. Beyond that cap the shared canvas renderer **intentionally falls
+   * back to a 1920px raster** to protect canvas performance, so very complex
+   * SVGs can look rasterized when zoomed in. The stored asset is the original
+   * SVG either way; only the on-canvas rendering falls back.
+   *
+   * @param source - The SVG to import: exactly one of `url` or `dataUrl`.
+   * @param options - Optional `position` — where to place the SVG on the sheet.
+   * @returns A {@linkcode PluginPresentationImportResult} with the created
+   *   `shapeIds`.
+   * @throws If Present mode is not open, the source is not an SVG, or it cannot
+   *   be loaded.
+   *
+   * @examplePrompt Import this SVG diagram onto the present canvas
+   * @examplePrompt Add a vector logo to my presentation board
+   * @examplePrompt Place this SVG floor plan on the current sheet as vectors
+   * @examplePrompt Bring a crisp vector graphic into Present mode
+   *
+   * # Example
+   * ```ts
+   * const { shapeIds } = await snaptrude.presentation.import.svg({
+   *   url: "https://example.com/diagram.svg",
+   * })
+   * ```
+   */
+  public abstract svg(
+    source: { url?: string; dataUrl?: string },
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginPresentationImportResult>
 }
 
 /**
  * Arguments for {@linkcode PluginPresentationImportApi.image} /
- * {@linkcode PluginPresentationImportApi.pdf}. Provide exactly one source.
+ * {@linkcode PluginPresentationImportApi.pdf} /
+ * {@linkcode PluginPresentationImportApi.svg}. Provide exactly one source.
  *
  * | Property | Type | Description |
  * |---|---|---|

package/src/api/presentation/index.ts

@@ -1,8 +1,19 @@
+import { PluginApiReturn } from "../../types"
 import { PluginPresentationViewsApi } from "./views"
 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 {
+  PluginPresentationExportResult,
+  type PluginPresentationExportFormat,
+  type PluginPresentationExportResolution,
+} from "./export"
 
 /**
  * Presentation APIs — prepare and assemble presentations.
@@ -16,7 +27,10 @@ import { PluginPresentationImportApi } from "./import"
  *
  * - {@linkcode PluginPresentationApi.views} — Saved 2D/3D views (list, get, capture, activate, create)
  * - {@linkcode PluginPresentationApi.sheets} — Layout sheets (list, get, create, place views)
- * - {@linkcode PluginPresentationApi.diagrams} — Place program/adjacency/site diagram images on sheets
+ * - {@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
  *
@@ -27,8 +41,18 @@ export abstract class PluginPresentationApi {
   public abstract views: PluginPresentationViewsApi
   /** 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
   /**
@@ -37,11 +61,52 @@ export abstract class PluginPresentationApi {
    */
   public abstract aiInspiration: PluginPresentationAIInspirationApi
 
+  /**
+   * 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 "./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 "./export"