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

package/src/api/presentation/export.ts

@@ -1,108 +1,134 @@
-import * as z from "zod"
-
-/**
- * Presentation export — render the Present-mode layout sheets to a downloadable
- * file (PDF / PNG / JPG) and hand the plugin the bytes as base64.
- *
- * This wraps the same pipeline the Present-mode **Export** dialog drives:
- * each sheet is serialized to an SVG, then either composed into a PDF
- * (svg2pdf/jspdf) or rasterized to a PNG/JPG. Nothing is written to disk
- * host-side — the plugin receives the encoded bytes and decides what to do
- * with them (save, upload, preview).
- *
- * Requires **Present mode to be open** (the documentation editor); the call
- * throws `PRECONDITION_FAILED` when it is not.
- *
- * The result is always a uniform `{ files }` array (see
- * {@linkcode PluginPresentationExportResult}):
- * - `pdf` with `combine` (the default) → a single multi-page file.
- * - `pdf` with `combine: false`, or any `png`/`jpg` → one file per sheet.
- *
- * Accessed via `snaptrude.presentation.export`.
- *
- * For a different export intent, see `core.io.export.model` (the 3D model as a
- * GLB/OBJ/FBX/3DS file) and `program.spreadsheet.export` (the area-program /
- * takeoff workbook as XLSX/PDF/CSV).
- *
- * The schemas and result types live here; the callable method is declared on
- * {@linkcode PluginPresentationApi.export}.
- */
-
-/** Output file format: a vector `pdf`, or a rasterized `png` / `jpg`. */
-export const PluginPresentationExportFormat = z.enum(["pdf", "png", "jpg"])
-export type PluginPresentationExportFormat = z.infer<
-  typeof PluginPresentationExportFormat
->
-
-/**
- * Target pixel dimensions for a rasterized (`png`/`jpg`) export. Ignored for
- * `pdf`, which stays vector and takes its size from the sheet.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `width` | `number` | Output width in pixels |
- * | `height` | `number` | Output height in pixels |
- */
-export const PluginPresentationExportResolution = z.object({
-  width: z.number().positive(),
-  height: z.number().positive(),
-})
-export type PluginPresentationExportResolution = z.infer<
-  typeof PluginPresentationExportResolution
->
-
-/**
- * Arguments for {@linkcode PluginPresentationApi.export}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `format` | `"pdf" \| "png" \| "jpg"` | Output format |
- * | `sheetIds` | `string[] \| undefined` | Sheets to export (all sheets when omitted) |
- * | `combine` | `boolean \| undefined` | PDF only: one multi-page file (default `true`) vs one file per sheet |
- * | `resolution` | {@linkcode PluginPresentationExportResolution}` \| undefined` | Raster target size (`png`/`jpg` only) |
- * | `fileName` | `string \| undefined` | Base file name (without extension) |
- */
-export const PluginPresentationExportArgs = z.object({
-  format: PluginPresentationExportFormat,
-  sheetIds: z.array(z.string()).optional(),
-  combine: z.boolean().optional(),
-  resolution: PluginPresentationExportResolution.optional(),
-  fileName: z.string().optional(),
-})
-export type PluginPresentationExportArgs = z.infer<
-  typeof PluginPresentationExportArgs
->
-
-/**
- * A single exported file.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `fileName` | `string` | File name including extension |
- * | `mimeType` | `string` | MIME type (`application/pdf`, `image/png`, `image/jpeg`) |
- * | `dataBase64` | `string` | The file bytes, base64-encoded (no data-URL prefix) |
- */
-export const PluginPresentationExportFile = z.object({
-  fileName: z.string(),
-  mimeType: z.string(),
-  dataBase64: z.string(),
-})
-export type PluginPresentationExportFile = z.infer<
-  typeof PluginPresentationExportFile
->
-
-/**
- * Result of {@linkcode PluginPresentationApi.export} — always a `files` array.
- * A combined PDF yields one entry; per-sheet exports yield one entry each, in
- * sheet order.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `files` | {@linkcode PluginPresentationExportFile}`[]` | The exported files |
- */
-export const PluginPresentationExportResult = z.object({
-  files: z.array(PluginPresentationExportFile),
-})
-export type PluginPresentationExportResult = z.infer<
-  typeof PluginPresentationExportResult
->
+import * as z from "zod"
+import { PluginExportFileName } from "./drawingContract"
+
+/**
+ * Presentation export — render the Present-mode layout sheets to a downloadable
+ * file (PDF / PNG / JPG), returning base64 by default or starting a browser download.
+ *
+ * This wraps the same pipeline the Present-mode **Export** dialog drives:
+ * each sheet is serialized to an SVG, then either composed into a PDF
+ * (svg2pdf/jspdf) or rasterized to a PNG/JPG. By default the plugin receives the
+ * encoded bytes to save, upload or preview. With `download: true`, the host
+ * initiates browser downloads and returns metadata only, keeping agent results small.
+ *
+ * Requires **Present mode to be open** (the documentation editor); the call
+ * throws `PRECONDITION_FAILED` when it is not.
+ *
+ * The result is always a uniform `{ files }` array (see
+ * {@linkcode PluginPresentationExportResult}):
+ * - `pdf` with `combine` (the default) → a single multi-page file.
+ * - `pdf` with `combine: false`, or any `png`/`jpg` → one file per sheet.
+ *
+ * Accessed via `snaptrude.presentation.export`.
+ *
+ * For a different export intent, see `core.io.export.model` (the 3D model as a
+ * GLB/OBJ/FBX/3DS file) and `program.spreadsheet.export` (the area-program /
+ * takeoff workbook as XLSX/PDF/CSV).
+ *
+ * The schemas and result types live here; the callable method is declared on
+ * {@linkcode PluginPresentationApi.export}.
+ */
+
+/** Output file format: a vector `pdf`, or a rasterized `png` / `jpg`. */
+export const PluginPresentationExportFormat = z.enum(["pdf", "png", "jpg"])
+export type PluginPresentationExportFormat = z.infer<
+  typeof PluginPresentationExportFormat
+>
+
+/**
+ * Target pixel dimensions for a rasterized (`png`/`jpg`) export. Ignored for
+ * `pdf`, which stays vector and takes its size from the sheet.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `width` | `number` | Output width in pixels |
+ * | `height` | `number` | Output height in pixels |
+ */
+export const PluginPresentationExportResolution = z.object({
+  width: z.number().positive(),
+  height: z.number().positive(),
+})
+export type PluginPresentationExportResolution = z.infer<
+  typeof PluginPresentationExportResolution
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationApi.export}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | `"pdf" \| "png" \| "jpg"` | Output format |
+ * | `sheetIds` | `string[] \| undefined` | Sheets to export (all sheets when omitted) |
+ * | `combine` | `boolean \| undefined` | PDF only: one multi-page file (default `true`) vs one file per sheet |
+ * | `resolution` | {@linkcode PluginPresentationExportResolution}` \| undefined` | Raster target size (`png`/`jpg` only) |
+ * | `fileName` | `string \| undefined` | Base file 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/.jpeg, a dot or a space is rejected |
+ * | `download` | `boolean \| undefined` | Start browser downloads and return metadata without base64 (default `false`) |
+ */
+export const PluginPresentationExportArgs = z.object({
+  format: PluginPresentationExportFormat,
+  sheetIds: z.array(z.string()).optional(),
+  combine: z.boolean().optional(),
+  resolution: PluginPresentationExportResolution.optional(),
+  fileName: PluginExportFileName.optional(),
+  download: z.boolean().optional(),
+})
+export type PluginPresentationExportArgs = z.infer<
+  typeof PluginPresentationExportArgs
+>
+
+/** Options after the positional export format. Omitted `download` preserves base64 results. */
+export type PluginPresentationExportOptions = Omit<
+  PluginPresentationExportArgs,
+  "format"
+>
+
+/**
+ * A single exported file.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `fileName` | `string` | File name including extension |
+ * | `mimeType` | `string` | MIME type (`application/pdf`, `image/png`, `image/jpeg`) |
+ * | `dataBase64` | `string` | The file bytes, base64-encoded (no data-URL prefix) |
+ */
+export const PluginPresentationExportFile = z.object({
+  fileName: z.string(),
+  mimeType: z.string(),
+  dataBase64: z.string(),
+})
+export type PluginPresentationExportFile = z.infer<
+  typeof PluginPresentationExportFile
+>
+
+/**
+ * Result of {@linkcode PluginPresentationApi.export} — always a `files` array.
+ * A combined PDF yields one entry; per-sheet exports yield one entry each, in
+ * sheet order.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `files` | {@linkcode PluginPresentationExportFile}`[]` | The exported files |
+ */
+export const PluginPresentationExportResult = z.object({
+  files: z.array(PluginPresentationExportFile),
+})
+export type PluginPresentationExportResult = z.infer<
+  typeof PluginPresentationExportResult
+>
+
+/**
+ * Metadata-only result for `download: true`. `downloadStarted` confirms initiation,
+ * not an OS-saved file: browsers may require multiple-download permission. No base64
+ * is returned. Default exports retain their existing result and TypeScript contract.
+ */
+export const PluginPresentationExportDownloadResult = z.object({
+  files: z.array(
+    PluginPresentationExportFile.omit({ dataBase64: true }).extend({
+      byteLength: z.number().int().nonnegative(),
+    }),
+  ),
+  downloadStarted: z.boolean(),
+})
+export type PluginPresentationExportDownloadResult = z.infer<
+  typeof PluginPresentationExportDownloadResult
+>

package/src/api/presentation/import.ts

@@ -1,159 +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
->
+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
+>