@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/presentation/import.ts

@@ -0,0 +1,159 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation import — bring external reference assets onto the Present canvas.
+ *
+ * `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`.
+ *
+ * Accessed via `snaptrude.presentation.import`.
+ */
+export abstract class PluginPresentationImportApi {
+  constructor() {}
+
+  /**
+   * 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.
+   * @returns A {@linkcode PluginPresentationImportResult} with the created
+   *   `shapeIds`.
+   * @throws If Present mode is not open or the source cannot be loaded.
+   *
+   * @examplePrompt Import this reference image onto the present canvas
+   * @examplePrompt Add a JPG to my presentation board
+   * @examplePrompt Drop this site photo onto the current sheet
+   * @examplePrompt Bring an inspiration image into Present mode
+   *
+   * # Example
+   * ```ts
+   * const { shapeIds } = await snaptrude.presentation.import.image(
+   *   { url: "https://example.com/ref.png" },
+   *   { position: { x: 200, y: 150 } },
+   * )
+   * ```
+   */
+  public abstract image(
+    source: { url?: string; dataUrl?: string },
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginPresentationImportResult>
+
+  /**
+   * Import a PDF onto the current Present sheet (one shape per page).
+   *
+   * 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.
+   * @returns A {@linkcode PluginPresentationImportResult} with one `shapeId` per
+   *   page.
+   * @throws If Present mode is not open or the source cannot be loaded.
+   *
+   * @examplePrompt Import this PDF onto the present canvas
+   * @examplePrompt Add a multi-page PDF reference to my board
+   * @examplePrompt Bring a PDF floor plan into Present mode as vectors
+   * @examplePrompt Place each page of this PDF on the sheet
+   *
+   * # Example
+   * ```ts
+   * const { shapeIds } = await snaptrude.presentation.import.pdf({
+   *   url: "https://example.com/plans.pdf",
+   * })
+   * ```
+   */
+  public abstract pdf(
+    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} /
+ * {@linkcode PluginPresentationImportApi.svg}. Provide exactly one source.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `url` | `string \| undefined` | URL of the asset to import |
+ * | `dataUrl` | `string \| undefined` | Base64 data URL of the asset |
+ * | `position` | `{ x: number; y: number } \| undefined` | Where to place it on the sheet |
+ */
+export const PluginPresentationImportArgs = z
+  .object({
+    url: z.string().optional(),
+    dataUrl: z.string().optional(),
+    position: z.object({ x: z.number(), y: z.number() }).optional(),
+  })
+  .refine((a) => Boolean(a.url) || Boolean(a.dataUrl), {
+    message: "Provide a url or a dataUrl",
+  })
+export type PluginPresentationImportArgs = z.infer<
+  typeof PluginPresentationImportArgs
+>
+
+/**
+ * Result of an import.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeIds` | `string[]` | Ids of the created canvas shapes (one per page for PDFs) |
+ */
+export const PluginPresentationImportResult = z.object({
+  shapeIds: z.array(z.string()),
+})
+export type PluginPresentationImportResult = z.infer<
+  typeof PluginPresentationImportResult
+>

package/src/api/presentation/index.ts

@@ -0,0 +1,129 @@
+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 { 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 {
+  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.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
+ *
+ * Accessed via `snaptrude.presentation`.
+ */
+export abstract class PluginPresentationApi {
+  /** Saved 2D/3D views. See {@linkcode PluginPresentationViewsApi}. */
+  public abstract views: PluginPresentationViewsApi
+  /** Drawing deliverables independent of sheet composition; Present must be open. */
+  public abstract drawings: PluginPresentationDrawingsApi
+  /** Reusable kernel-plan styles stored in the Present document. */
+  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
+
+  /**
+   * 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.
+   *
+   * @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`, 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 "./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"
+export * from "./drawings"
+export * from "./viewPresets"