@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/presentation/drawings.ts

@@ -0,0 +1,529 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+import {
+  PluginPlacedView,
+  PluginPlacedViewCrop,
+  PluginPlacedViewStylePatch,
+  PluginViewLineStyle,
+  PluginPlacedViewLabel,
+} from "./placedViews"
+import { PluginSheetPosition } from "./sheets"
+import { PluginPresentationExportResolution } from "./export"
+
+/** Drawing ids are existing Present view-shape ids, stable across reload and undo. */
+export const PluginDrawingIdArgs = z
+  .object({ drawingId: z.string().min(1) })
+  .strict()
+export const PluginDrawingNameArgs = PluginDrawingIdArgs.extend({
+  name: z.string().trim().min(1),
+})
+export const PluginDrawingIdsArgs = z
+  .object({ drawingIds: z.array(z.string().min(1)).min(1).max(100) })
+  .strict()
+export const PluginDrawingCreateOptions = z
+  .object({
+    position: PluginSheetPosition.optional(),
+    scale: z.number().finite().positive().optional(),
+  })
+  .strict()
+export type PluginDrawingCreateOptions = z.infer<
+  typeof PluginDrawingCreateOptions
+>
+export const PluginDrawingCreateArgs = PluginDrawingCreateOptions.extend({
+  viewId: z.string().min(1),
+})
+export type PluginDrawingCreateArgs = z.infer<typeof PluginDrawingCreateArgs>
+export type PluginDrawingIdArgs = z.infer<typeof PluginDrawingIdArgs>
+export type PluginDrawingNameArgs = z.infer<typeof PluginDrawingNameArgs>
+export type PluginDrawingIdsArgs = z.infer<typeof PluginDrawingIdsArgs>
+export const PluginDrawingScaleArgs = PluginDrawingIdArgs.extend({
+  scale: z.number().finite().positive(),
+})
+export type PluginDrawingScaleArgs = z.infer<typeof PluginDrawingScaleArgs>
+export const PluginDrawingCropArgs = PluginDrawingIdArgs.extend({
+  crop: PluginPlacedViewCrop.nullable(),
+})
+export type PluginDrawingCropArgs = z.infer<typeof PluginDrawingCropArgs>
+export const PluginDrawingPresetArgs = PluginDrawingIdArgs.extend({
+  presetId: z.string().min(1),
+})
+export type PluginDrawingPresetArgs = z.infer<typeof PluginDrawingPresetArgs>
+
+/** Architectural scale is a denominator (100 means 1:100); positions are Present canvas units. */
+export const PluginDrawing = PluginPlacedView.extend({
+  id: z.string(),
+  presetId: z.string().nullable(),
+  kind: z.enum(["plan", "sitePlan", "threeD", "elevation"]),
+  direction: z.enum(["north", "east", "south", "west"]).nullable(),
+})
+export type PluginDrawing = z.infer<typeof PluginDrawing>
+
+const color = z.string().regex(/^#[0-9a-fA-F]{6}$/)
+const weight = z.number().finite().min(0).max(2.11)
+const opacity = z.number().finite().min(0).max(100)
+const pattern = z
+  .object({
+    id: z.string().min(1).optional(),
+    scale: z.number().finite().min(0.25).max(4).optional(),
+    color: color.optional(),
+    background: color.optional(),
+    weight: weight.optional(),
+  })
+  .strict()
+const face = z
+  .object({
+    fontStyle: z.enum(["400", "500", "700", "italic"]).optional(),
+    fontSize: z.enum(["12px", "16px", "24px", "2.5", "3.5", "5"]).optional(),
+    color: color.optional(),
+  })
+  .strict()
+const part = z
+  .object({
+    show: z.boolean().optional(),
+    lineStyle: PluginViewLineStyle.optional(),
+    weight: weight.optional(),
+  })
+  .strict()
+const title = z
+  .object({
+    show: z.boolean().optional(),
+    text: z.string().max(2000).optional(),
+  })
+  .strict()
+const material = z
+  .object({
+    show: z.boolean().optional(),
+    color: color.optional(),
+    pattern: pattern.optional(),
+  })
+  .strict()
+
+/**
+ * Vector-plan row patch. Only controls returned by getStyles are accepted for that row.
+ * Paper weights are mm; opacity is 0–100. Nested values merge, never replace the whole row.
+ * Presets apply to kernel plans only; other drawings use the legacy category patch.
+ */
+export const PluginDrawingVectorStylePatch = z
+  .object({
+    hide: z.boolean().optional(),
+    lineStyle: PluginViewLineStyle.optional(),
+    lineColor: color.optional(),
+    cutWidth: weight.optional(),
+    projectionWidth: weight.optional(),
+    weight: weight.optional(),
+    fillMode: z.string().optional(),
+    fillColor: color.optional(),
+    opacity: opacity.optional(),
+    pattern: pattern.optional(),
+    mask: z.boolean().optional(),
+    materials: z
+      .object({
+        brick: material.optional(),
+        glass: material.optional(),
+        concrete: material.optional(),
+        metalFrame: material.optional(),
+        woodFrame: material.optional(),
+        plaster: material.optional(),
+        paint: material.optional(),
+        insulation: material.optional(),
+      })
+      .strict()
+      .optional(),
+    components: z
+      .object({
+        frame: z.boolean().optional(),
+        leaf: z.boolean().optional(),
+        jambs: z.boolean().optional(),
+        glazing: z.boolean().optional(),
+        track: z.boolean().optional(),
+        operation: z.boolean().optional(),
+        operationStyle: PluginViewLineStyle.optional(),
+      })
+      .strict()
+      .optional(),
+    tag: z
+      .object({
+        show: z.boolean().optional(),
+        fontFamily: z.string().min(1).optional(),
+        fontStyle: z.enum(["400", "500", "700", "italic"]).optional(),
+        fontSize: z.enum(["12px", "16px", "24px"]).optional(),
+        frame: z.enum(["pill", "hexagon"]).optional(),
+        color: color.optional(),
+        opacity: opacity.optional(),
+        outline: weight.optional(),
+      })
+      .strict()
+      .optional(),
+    text: z
+      .object({
+        show: z.boolean().optional(),
+        labels: z.boolean().optional(),
+        areas: z.boolean().optional(),
+        department: z.boolean().optional(),
+        fontFamily: z.string().min(1).optional(),
+        color: color.optional(),
+        fontSize: z.enum(["12px", "16px", "24px"]).optional(),
+        label: face.optional(),
+        metrics: face.optional(),
+        title: face.optional(),
+        scale: face.optional(),
+      })
+      .strict()
+      .optional(),
+    detail: z
+      .object({ show: z.boolean().optional(), weight: weight.optional() })
+      .strict()
+      .optional(),
+    belowCut: part.optional(),
+    aboveCut: part.optional(),
+    underlay: part.optional(),
+    walkLine: part.optional(),
+    breakLine: part.optional(),
+    overlay: part.optional(),
+    title: title.optional(),
+    proposal: title.optional(),
+    building: title.optional(),
+    scale: z
+      .object({
+        show: z.boolean().optional(),
+        format: z.enum(["automatic", "ratio", "text"]).optional(),
+      })
+      .strict()
+      .optional(),
+    scaleBar: z
+      .object({
+        show: z.boolean().optional(),
+        format: z.enum(["divided", "simple"]).optional(),
+        length: z.enum(["1", "2", "5", "10"]).optional(),
+      })
+      .strict()
+      .optional(),
+    extension: z
+      .object({
+        show: z.boolean().optional(),
+        length: z.enum(["underTitle", "fullWidth"]).optional(),
+        weight: weight.optional(),
+        color: color.optional(),
+      })
+      .strict()
+      .optional(),
+    position: z.enum(["bottomLeft", "bottomCentre", "topLeft"]).optional(),
+  })
+  .strict()
+export const PluginDrawingStylePatch = z.union([
+  PluginDrawingVectorStylePatch,
+  PluginPlacedViewStylePatch,
+])
+export type PluginDrawingStylePatch = z.infer<typeof PluginDrawingStylePatch>
+export const PluginDrawingStylesArgs = PluginDrawingIdArgs.extend({
+  category: z.string().min(1),
+  patch: PluginDrawingStylePatch,
+})
+export type PluginDrawingStylesArgs = z.infer<typeof PluginDrawingStylesArgs>
+
+/** One selectable value exposed by a native drawing style control. */
+export const PluginDrawingStyleControlOption = z.object({
+  label: z.string(),
+  value: z.string(),
+})
+export type PluginDrawingStyleControlOption = z.infer<
+  typeof PluginDrawingStyleControlOption
+>
+
+/** Numeric bounds exposed by a native drawing style control. */
+export const PluginDrawingStyleControlRange = z.object({
+  min: z.number().finite(),
+  max: z.number().finite(),
+  step: z.number().finite().positive(),
+})
+export type PluginDrawingStyleControlRange = z.infer<
+  typeof PluginDrawingStyleControlRange
+>
+
+/** Description of one editable control returned by `drawings.getStyles`. */
+export const PluginDrawingStyleControl = z.object({
+  key: z.string(),
+  kind: z.string(),
+  options: z.array(PluginDrawingStyleControlOption).optional(),
+  range: PluginDrawingStyleControlRange.optional(),
+})
+export type PluginDrawingStyleControl = z.infer<
+  typeof PluginDrawingStyleControl
+>
+
+/**
+ * Read values differ from write patches: legacy renderers use -1 for an unset opacity and
+ * include the read-only `disable` flag. These values must not be echoed as an update patch.
+ */
+export const PluginDrawingStyleValues = z.union([
+  PluginDrawingVectorStylePatch,
+  z
+    .object({
+      ...PluginPlacedViewStylePatch.shape,
+      disable: z.boolean().optional(),
+      opacity: z.number().finite().min(-1).max(100).optional(),
+      mapOpacity: z.number().finite().min(-1).max(100).optional(),
+      buildingOpacity: z.number().finite().min(-1).max(100).optional(),
+    })
+    .strict(),
+])
+export type PluginDrawingStyleValues = z.infer<typeof PluginDrawingStyleValues>
+
+/** Read-only effective settings and editable controls for one drawing category. */
+export const PluginDrawingStyleCategory = z.object({
+  category: z.string(),
+  absent: z.boolean(),
+  settings: PluginDrawingStyleValues,
+  controls: z.array(PluginDrawingStyleControl),
+})
+export type PluginDrawingStyleCategory = z.infer<
+  typeof PluginDrawingStyleCategory
+>
+
+/** Effective style categories and their native editing capabilities. */
+export const PluginDrawingStyles = z.object({
+  categories: z.array(PluginDrawingStyleCategory),
+})
+export type PluginDrawingStyles = z.infer<typeof PluginDrawingStyles>
+export const PluginDrawingStatus = z.object({
+  drawingId: z.string(),
+  generation: z.enum(["ready", "updating", "missing"]),
+  assetSave: z.enum(["uploading", "retrying", "uploaded", "missing"]),
+  layout: z.enum(["pending", "ready", "unsupported"]),
+  exportReady: z.boolean(),
+  warnings: z.array(z.string()),
+})
+export type PluginDrawingStatus = z.infer<typeof PluginDrawingStatus>
+export const PluginDrawingStatusArgs = PluginDrawingIdArgs.extend({
+  waitMs: z.number().finite().int().min(0).max(30000).optional(),
+})
+export type PluginDrawingStatusArgs = z.infer<typeof PluginDrawingStatusArgs>
+export const PluginDrawingExportFormat = z.enum(["pdf", "svg", "png", "jpg"])
+export type PluginDrawingExportFormat = z.infer<
+  typeof PluginDrawingExportFormat
+>
+/** Renderer-specific operations and formats supported by a drawing. */
+export const PluginDrawingCapabilities = z.object({
+  renderer: z.enum(["vector", "hybrid", "raster", "unknown"]),
+  presets: z.boolean(),
+  labelLayout: z.boolean(),
+  architecturalScale: z.boolean(),
+  standardScales: z.array(
+    z.object({ label: z.string(), value: z.number().finite().positive() }),
+  ),
+  exportFormats: z.array(PluginDrawingExportFormat),
+})
+export type PluginDrawingCapabilities = z.infer<
+  typeof PluginDrawingCapabilities
+>
+export const PluginDrawingExportOptions = z
+  .object({
+    fileName: z.string().trim().min(1).max(200).optional(),
+    resolution: PluginPresentationExportResolution.optional(),
+    download: z.boolean().optional(),
+  })
+  .strict()
+export type PluginDrawingExportOptions = z.infer<
+  typeof PluginDrawingExportOptions
+>
+export const PluginDrawingExportArgs = PluginDrawingIdArgs.extend({
+  format: PluginDrawingExportFormat,
+  ...PluginDrawingExportOptions.shape,
+})
+export type PluginDrawingExportArgs = z.infer<typeof PluginDrawingExportArgs>
+export const PluginDrawingExportResult = z.object({
+  files: z.array(
+    z.object({
+      fileName: z.string(),
+      mimeType: z.string(),
+      byteLength: z.number(),
+      dataBase64: z.string().optional(),
+    }),
+  ),
+  downloadStarted: z.boolean(),
+  warnings: z.array(z.string()),
+})
+export type PluginDrawingExportResult = z.infer<
+  typeof PluginDrawingExportResult
+>
+
+export const PluginDrawingLabelArgs = z
+  .object({ labelId: z.string().min(1) })
+  .strict()
+export type PluginDrawingLabelArgs = z.infer<typeof PluginDrawingLabelArgs>
+export const PluginDrawingLabelMoveArgs = PluginDrawingLabelArgs.extend({
+  position: PluginSheetPosition,
+})
+export type PluginDrawingLabelMoveArgs = z.infer<
+  typeof PluginDrawingLabelMoveArgs
+>
+export const PluginDrawingLabelHiddenArgs = PluginDrawingLabelArgs.extend({
+  hidden: z.boolean(),
+})
+export type PluginDrawingLabelHiddenArgs = z.infer<
+  typeof PluginDrawingLabelHiddenArgs
+>
+export const PluginDrawingLabelResetArgs = PluginDrawingIdArgs.extend({
+  scope: z.enum(["scale", "all"]).optional(),
+})
+export type PluginDrawingLabelResetArgs = z.infer<
+  typeof PluginDrawingLabelResetArgs
+>
+
+/** Collision-layout diagnostics for drawing labels, including actionable scale suggestions. */
+export const PluginDrawingLabelLayout = z.object({
+  pending: z.boolean(),
+  pinned: z.number().int().nonnegative(),
+  unplaced: z.array(
+    z.object({
+      labelId: z.string(),
+      name: z.string(),
+      reason: z.string(),
+      suggestedScale: z.number().finite().positive().nullable(),
+    }),
+  ),
+  duplicatesMerged: z.number().int().nonnegative(),
+  rowsDropped: z.object({
+    department: z.number().int().nonnegative(),
+    area: z.number().int().nonnegative(),
+    wrapped: z.number().int().nonnegative(),
+  }),
+})
+export type PluginDrawingLabelLayout = z.infer<typeof PluginDrawingLabelLayout>
+
+/** Label ids are text-shape ids returned by list; positions are drawing-local canvas units. */
+export abstract class PluginDrawingLabelsApi {
+  /**
+   * List every text label on a drawing, including hidden labels.
+   * @examplePrompt List all labels in this drawing
+   */
+  public abstract list(
+    drawingId: string,
+  ): PluginApiReturn<PluginPlacedViewLabel[]>
+  /**
+   * Read collision diagnostics, suggested scales and pin counts without hiding failed labels.
+   * @examplePrompt Check this drawing for overlapping labels
+   */
+  public abstract getLayout(
+    drawingId: string,
+  ): PluginApiReturn<PluginDrawingLabelLayout>
+  /** Move a label; room labels retain the chosen position at the current architectural scale. */
+  public abstract move(
+    labelId: string,
+    position: z.infer<typeof PluginSheetPosition>,
+  ): PluginApiReturn<PluginPlacedViewLabel>
+  /** Set user visibility, independently of layout/crop visibility. */
+  public abstract setHidden(
+    labelId: string,
+    hidden: boolean,
+  ): PluginApiReturn<PluginPlacedViewLabel>
+  /** Pin an unclean room label at its best available position. May wait up to ten seconds for fitting. */
+  public abstract place(labelId: string): PluginApiReturn<boolean>
+  /** Clear pins at this scale (default) or every scale. Returns the number cleared. */
+  public abstract reset(
+    drawingId: string,
+    options?: { scope?: "scale" | "all" },
+  ): PluginApiReturn<number>
+}
+
+/**
+ * First-class drawing deliverables on the Present canvas. Present must be open for every method;
+ * no method changes tabs. Native shape history/sync are reused. Creating does not wait for upload:
+ * inspect getStatus; "uploaded" describes the asset, not a server acknowledgement of document sync.
+ * A drawing needs no sheet. Legacy placedViews/sheets.place continue to address the same shape ids.
+ */
+export abstract class PluginPresentationDrawingsApi {
+  public abstract labels: PluginDrawingLabelsApi
+  /**
+   * Generate a saved source view on the canvas. Options use page coordinates and a standard scale denominator.
+   * @examplePrompt Create a drawing from the ground floor view
+   */
+  public abstract create(
+    viewId: string,
+    options?: PluginDrawingCreateOptions,
+  ): PluginApiReturn<PluginDrawing>
+  /**
+   * List drawing deliverables on the current Present page.
+   * @examplePrompt List all drawings in this presentation
+   */
+  public abstract list(): PluginApiReturn<PluginDrawing[]>
+  /** Read a drawing by its stable id; null if it no longer exists. */
+  public abstract get(drawingId: string): PluginApiReturn<PluginDrawing | null>
+  /** Copy a drawing and its annotations with native duplication; returns the new drawing. */
+  public abstract copy(drawingId: string): PluginApiReturn<PluginDrawing>
+  /** Rename the drawing title without renaming its source saved view. */
+  public abstract rename(
+    drawingId: string,
+    name: string,
+  ): PluginApiReturn<PluginDrawing>
+  /** Delete a drawing and its children as one Present undo step. */
+  public abstract delete(drawingId: string): PluginApiReturn<void>
+  /** Regenerate specified drawings. Reports actual changed assets, not merely submitted ids. */
+  public abstract updateContent(
+    drawingIds: string[],
+  ): PluginApiReturn<{ drawingId: string; updated: boolean }[]>
+  /**
+   * Read actual renderer and supported operations; presets are kernel-plan-only.
+   * @examplePrompt What editing capabilities does this drawing support?
+   */
+  public abstract getCapabilities(
+    drawingId: string,
+  ): PluginApiReturn<PluginDrawingCapabilities>
+  /** Wait at most waitMs (0 by default) for export readiness and upload; returns current status on timeout. */
+  public abstract getStatus(
+    drawingId: string,
+    options?: { waitMs?: number },
+  ): PluginApiReturn<PluginDrawingStatus>
+  /** Set a standard architectural scale; perspective/isometric drawings reject this. */
+  public abstract setScale(
+    drawingId: string,
+    scale: number,
+  ): PluginApiReturn<PluginDrawing>
+  /** Set normalized crop corners (0–1), or null to remove the crop. */
+  public abstract setCrop(
+    drawingId: string,
+    crop: z.infer<typeof PluginPlacedViewCrop> | null,
+  ): PluginApiReturn<PluginDrawing>
+  /**
+   * Read effective categories/controls before editing; absent categories reject writes.
+   * @examplePrompt Show the editable styles for this drawing
+   */
+  public abstract getStyles(
+    drawingId: string,
+  ): PluginApiReturn<PluginDrawingStyles>
+  /** Merge a typed category patch as one undo step. Invalid/unsupported fields reject the whole call. */
+  public abstract updateStyles(
+    drawingId: string,
+    category: string,
+    patch: PluginDrawingStylePatch,
+  ): PluginApiReturn<PluginDrawingStyles>
+  /**
+   * Bind a kernel plan to a preset and clear declared overrides; local title text is retained.
+   * @examplePrompt Apply the presentation plan preset to this drawing
+   */
+  public abstract applyPreset(
+    drawingId: string,
+    presetId: string,
+  ): PluginApiReturn<PluginDrawing>
+  /** Reset declared overrides to the bound preset, preserving local title/proposal/building text. */
+  public abstract resetOverrides(
+    drawingId: string,
+  ): PluginApiReturn<PluginDrawing>
+  /** List pattern ids accepted by the native hatch catalog. */
+  public abstract listPatterns(): PluginApiReturn<
+    { id: string; label: string; group: string }[]
+  >
+  /** List available font families from the native catalog (including DEFAULT). */
+  public abstract listFonts(): PluginApiReturn<string[]>
+  /**
+   * Export the drawing including labels/annotations, no sheet required. PDF size follows its canvas bounds.
+   * download:true starts a browser download and returns metadata only (never send large base64 to an agent).
+   * Otherwise files contain dataBase64. downloadStarted means initiated, not proof of an OS-saved file.
+   * SVG/PDF preserve vector content; raster fallbacks remain raster. Layout warnings are returned.
+   */
+  public abstract export(
+    drawingId: string,
+    format: PluginDrawingExportFormat,
+    options?: PluginDrawingExportOptions,
+  ): PluginApiReturn<PluginDrawingExportResult>
+}

package/src/api/presentation/export.ts

@@ -0,0 +1,133 @@
+import * as z from "zod"
+
+/**
+ * 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 extension) |
+ * | `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: z.string().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
+>