@snaptrude/plugin-core 0.9.17 → 0.9.18-voids-20261016.1

package/src/api/presentation/export.ts

@@ -1,14 +1,15 @@
 import * as z from "zod"
+import { PluginExportFileName } from "./drawingContract"
 
 /**
  * Presentation export — render the Present-mode layout sheets to a downloadable
- * file (PDF / PNG / JPG) and hand the plugin the bytes as base64.
+ * 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. Nothing is written to disk
- * host-side — the plugin receives the encoded bytes and decides what to do
- * with them (save, upload, preview).
+ * (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.
@@ -60,19 +61,27 @@ export type PluginPresentationExportResolution = z.infer<
  * | `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) |
+ * | `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: z.string().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.
  *
@@ -106,3 +115,20 @@ export const PluginPresentationExportResult = z.object({
 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/index.ts

@@ -5,6 +5,8 @@ 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"
@@ -13,9 +15,10 @@ import { PluginPresentationImportApi } from "./import"
 import { PluginPresentationWalkthroughsApi } from "./walkthroughs"
 import { PluginPresentationSectionsApi } from "./sections"
 import {
-  PluginPresentationExportResult,
+  type PluginPresentationExportResult,
+  type PluginPresentationExportDownloadResult,
   type PluginPresentationExportFormat,
-  type PluginPresentationExportResolution,
+  type PluginPresentationExportOptions,
 } from "./export"
 
 /**
@@ -30,7 +33,9 @@ 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.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
@@ -47,6 +52,10 @@ export abstract class PluginPresentationApi {
   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}. */
@@ -83,15 +92,22 @@ export abstract class PluginPresentationApi {
 
   /**
    * 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.
+   * 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`), and `fileName`.
-   * @returns A {@linkcode PluginPresentationExportResult} — always a `files`
-   *   array (one entry for a combined PDF, one per sheet otherwise).
+   *   `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.
    *
@@ -104,17 +120,23 @@ export abstract class PluginPresentationApi {
    * # Example
    * ```ts
    * const { files } = await snaptrude.presentation.export("pdf")
+   * const download = await snaptrude.presentation.export("pdf", { download: true })
    * ```
    */
   public abstract export(
     format: PluginPresentationExportFormat,
-    options?: {
-      sheetIds?: string[]
-      combine?: boolean
-      resolution?: PluginPresentationExportResolution
-      fileName?: string
-    },
+    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() {}
 }
@@ -133,3 +155,6 @@ export * from "./aiInspiration"
 export * from "./walkthroughs"
 export * from "./sections"
 export * from "./export"
+export * from "./drawings"
+export * from "./drawingContract"
+export * from "./viewPresets"

package/src/api/presentation/placedViews.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { PluginSheetPosition } from "./sheets"
+import { PluginStandardDrawingScale } from "./drawingContract"
 
 /**
  * Placed views — the view shapes already laid out on the Present canvas.
@@ -141,14 +142,21 @@ export abstract class PluginPresentationPlacedViewsApi {
 
   /**
    * Set a placed view's architectural scale.
+   * `scale` must be a standard architectural scale denominator (100 means 1:100)
+   * in the project's unit system; any other value is rejected. Metric: 10, 20, 50,
+   * 100, 150, 200, 250, 500, 1000. Imperial detail: 12, 16, 24, 32, 48, 64, 96, 128,
+   * 192, 384, 768, 1536 (1" = 1' to 1/128" = 1'; 48 is 1/4" = 1', 96 is 1/8" = 1').
+   * Imperial site: 120, 240, 360, 480, 600, 1200, 2400, 3600, 4800 (1" = 10' to
+   * 1" = 400'). Pick the LARGEST standard scale (smallest denominator) at which the
+   * view still fits its frame or sheet and its room labels stay readable: for a
+   * building floor plan that is usually 1:50 to 1:200 (1/4" = 1' to 1/16" = 1').
+   * Never use a site-sized scale (1:500 and up, 1/64" = 1' (768) and smaller,
+   * 1" = 20' (240) and up) for a single building plan unless the user asked for it.
    *
    * Applies a standard architectural scale — the same write the placed view's
    * Scale dropdown performs. The view (and its labels) is resized about its
-   * top-left corner so it prints at the given scale. `scale` must be one of
-   * the standard values for the project's unit system (metric `10, 20, 50,
-   * 100, 150, 200, 250, 500, 1000`; imperial e.g. `48` for 1/4″ = 1′, `96`
-   * for 1/8″ = 1′, `120` for 1″ = 10′) — the same validation as
-   * `sheets.place`. 3D views have no architectural scale — calling this on
+   * top-left corner so it prints at the given scale (the same validation as
+   * `sheets.place`). 3D views have no architectural scale — calling this on
    * one throws. Requires Present mode to be open.
    *
    * @param shapeId - The placed view shape to set the scale of.
@@ -741,7 +749,7 @@ export type PluginPresentationPlacedViewsScaleArgs = z.infer<
  */
 export const PluginPresentationPlacedViewsSetScaleArgs = z.object({
   shapeId: z.string(),
-  scale: z.number().positive(),
+  scale: PluginStandardDrawingScale,
 })
 export type PluginPresentationPlacedViewsSetScaleArgs = z.infer<
   typeof PluginPresentationPlacedViewsSetScaleArgs
@@ -794,11 +802,28 @@ export const PluginViewSettingCategory = z.enum([
   "Envelope",
   "Facade/Mass",
   "Dimension",
+  "Grid",
+  "Walls",
+  "Columns",
+  "Beams",
+  "Doors",
+  "Windows",
+  "Floors",
+  "Slabs",
+  "Roofs",
+  "Ceilings",
+  "Staircase",
+  "Furniture",
+  "Families",
+  "Underlay",
+  "Overlay",
   "Reference Line",
   "Adjacency Line",
   "Landscape elements",
 ])
-export type PluginViewSettingCategory = z.infer<typeof PluginViewSettingCategory>
+export type PluginViewSettingCategory = z.infer<
+  typeof PluginViewSettingCategory
+>
 
 /** The 7 line dash styles (mirrors the host's LINE_STYLES). */
 export const PluginViewLineStyle = z.enum([
@@ -824,7 +849,7 @@ export type PluginViewLineStyle = z.infer<typeof PluginViewLineStyle>
  * | `lineStyle` | {@linkcode PluginViewLineStyle}? | Dash pattern |
  * | `lineColor` | `string`? | Line color, 6-digit hex (`#` optional) |
  * | `dashLength` | `number`? | Dash-length multiplier (> 0; `1` = default) |
- * | `lineWidth` | `number`? | Single line weight in mm (categories without cut/projection) |
+ * | `lineWidth` | `number`? | Single line weight in mm (Dimension: 0.05–0.7; otherwise non-negative) |
  * | `cutWidth` | `number`? | Cut-line weight in mm |
  * | `projectionWidth` | `number`? | Projection-line weight in mm |
  * | `treeLineWidth` | `number`? | Tree line weight in mm (Landscape) |
@@ -857,8 +882,13 @@ export const PluginPlacedViewStylePatch = z
     colorMode: z
       .string()
       .refine(
-        (v) => ["department", "texture", "monochrome"].includes(v) || v.startsWith("tag:"),
-        { message: "colorMode must be department, texture, monochrome, or tag:<tagCategoryId>" },
+        (v) =>
+          ["department", "texture", "monochrome"].includes(v) ||
+          v.startsWith("tag:"),
+        {
+          message:
+            "colorMode must be department, texture, monochrome, or tag:<tagCategoryId>",
+        },
       )
       .optional(),
     opacity: z.number().finite().min(0).max(100).optional(),
@@ -870,13 +900,42 @@ export const PluginPlacedViewStylePatch = z
     viewStyle: z.enum(["NONE", "FILLET", "BUBBLE"]).optional(),
     radius: z.number().finite().min(0).optional(),
     inset: z.number().finite().min(0).optional(),
+    // Dimension lengths are plotted paper millimetres, independent of drawing scale.
+    markerKind: z
+      .enum(["architecturalTick", "openArrow", "closedArrow"])
+      .optional(),
+    markerSize: z.number().finite().min(0.5).max(6).optional(),
+    extensionLineVisible: z.boolean().optional(),
+    extensionLineStyle: PluginViewLineStyle.optional(),
+    extensionGap: z.number().finite().min(0).max(10).optional(),
+    extensionOvershoot: z.number().finite().min(0).max(10).optional(),
+    textColor: z
+      .string()
+      .regex(/^(inherit|#[0-9a-fA-F]{6})$/)
+      .optional(),
+    textGap: z.number().finite().min(0).max(10).optional(),
+    textPlacement: z.literal("above").optional(),
+    textMask: z.boolean().optional(),
+    textMaskColor: z
+      .string()
+      .regex(/^#[0-9a-fA-F]{6}$/)
+      .optional(),
+    textMaskPadding: z.number().finite().min(0).max(5).optional(),
   })
   .strict()
-  .refine((p) => Object.keys(p).length > 0, { message: "patch must set at least one setting" })
-export type PluginPlacedViewStylePatch = z.infer<typeof PluginPlacedViewStylePatch>
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "patch must set at least one setting",
+  })
+export type PluginPlacedViewStylePatch = z.infer<
+  typeof PluginPlacedViewStylePatch
+>
 
 /** Label types that carry typography in a category's Text tab. */
-export const PluginViewLabelType = z.enum(["objectLabels", "department", "areas"])
+export const PluginViewLabelType = z.enum([
+  "objectLabels",
+  "department",
+  "areas",
+])
 export type PluginViewLabelType = z.infer<typeof PluginViewLabelType>
 
 /** Typography patch for one label type. `fontSize` is in px. */
@@ -885,7 +944,10 @@ const PluginViewFontVariantPatch = z
     fontFamily: z.string().min(1).optional(),
     fontWeight: z
       .string()
-      .regex(/^\d{3}$/, 'fontWeight must be a numeric string like "400" or "700"')
+      .regex(
+        /^\d{3}$/,
+        'fontWeight must be a numeric string like "400" or "700"',
+      )
       .optional(),
     fontStyle: z.enum(["normal", "italic"]).optional(),
     fontSize: z.number().finite().positive().max(200).optional(),
@@ -910,8 +972,12 @@ export const PluginPlacedViewFontStylesPatch = z
     areas: PluginViewFontVariantPatch.optional(),
   })
   .strict()
-  .refine((p) => Object.keys(p).length > 0, { message: "patch must set at least one field" })
-export type PluginPlacedViewFontStylesPatch = z.infer<typeof PluginPlacedViewFontStylesPatch>
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "patch must set at least one field",
+  })
+export type PluginPlacedViewFontStylesPatch = z.infer<
+  typeof PluginPlacedViewFontStylesPatch
+>
 
 /** Resolved font styles for one label type (fontSize in px). */
 export type PluginViewFontVariant = {
@@ -961,12 +1027,25 @@ export type PluginPlacedViewStylesResult = {
 }
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.updateStyles}. */
-export const PluginPlacedViewsUpdateStylesArgs = z.object({
-  shapeId: z.string().min(1),
-  category: PluginViewSettingCategory,
-  patch: PluginPlacedViewStylePatch,
-})
-export type PluginPlacedViewsUpdateStylesArgs = z.infer<typeof PluginPlacedViewsUpdateStylesArgs>
+export const PluginPlacedViewsUpdateStylesArgs = z
+  .object({
+    shapeId: z.string().min(1),
+    category: PluginViewSettingCategory,
+    patch: PluginPlacedViewStylePatch,
+  })
+  .refine(
+    ({ category, patch }) =>
+      category !== "Dimension" ||
+      patch.lineWidth === undefined ||
+      (patch.lineWidth >= 0.05 && patch.lineWidth <= 0.7),
+    {
+      message: "Dimension lineWidth must be between 0.05 and 0.7 paper mm",
+      path: ["patch", "lineWidth"],
+    },
+  )
+export type PluginPlacedViewsUpdateStylesArgs = z.infer<
+  typeof PluginPlacedViewsUpdateStylesArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.updateFontStyles}. */
 export const PluginPlacedViewsUpdateFontStylesArgs = z.object({
@@ -1011,7 +1090,9 @@ export const PluginPlacedViewsMoveLabelArgs = z.object({
   labelId: z.string().min(1),
   position: PluginSheetPosition,
 })
-export type PluginPlacedViewsMoveLabelArgs = z.infer<typeof PluginPlacedViewsMoveLabelArgs>
+export type PluginPlacedViewsMoveLabelArgs = z.infer<
+  typeof PluginPlacedViewsMoveLabelArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setLabelHidden}. */
 export const PluginPlacedViewsSetLabelHiddenArgs = z.object({
@@ -1081,14 +1162,18 @@ export const PluginPlacedViewsMoveShapeArgs = z.object({
   position: PluginSheetPosition,
   sheetId: z.string().optional(),
 })
-export type PluginPlacedViewsMoveShapeArgs = z.infer<typeof PluginPlacedViewsMoveShapeArgs>
+export type PluginPlacedViewsMoveShapeArgs = z.infer<
+  typeof PluginPlacedViewsMoveShapeArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.resizeShape}. */
 export const PluginPlacedViewsResizeShapeArgs = z.object({
   shapeId: z.string().min(1),
   factor: z.number().finite().min(0.01).max(100),
 })
-export type PluginPlacedViewsResizeShapeArgs = z.infer<typeof PluginPlacedViewsResizeShapeArgs>
+export type PluginPlacedViewsResizeShapeArgs = z.infer<
+  typeof PluginPlacedViewsResizeShapeArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.rotateShape}. */
 export const PluginPresentationPlacedViewsRotateShapeArgs = z.object({
@@ -1103,18 +1188,24 @@ export type PluginPresentationPlacedViewsRotateShapeArgs = z.infer<
 export const PluginPlacedViewsDeleteShapesArgs = z.object({
   shapeIds: z.array(z.string().min(1)).min(1).max(500),
 })
-export type PluginPlacedViewsDeleteShapesArgs = z.infer<typeof PluginPlacedViewsDeleteShapesArgs>
+export type PluginPlacedViewsDeleteShapesArgs = z.infer<
+  typeof PluginPlacedViewsDeleteShapesArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setOpacity}. */
 export const PluginPlacedViewsSetOpacityArgs = z.object({
   shapeId: z.string().min(1),
   opacity: z.number().finite().min(0).max(1),
 })
-export type PluginPlacedViewsSetOpacityArgs = z.infer<typeof PluginPlacedViewsSetOpacityArgs>
+export type PluginPlacedViewsSetOpacityArgs = z.infer<
+  typeof PluginPlacedViewsSetOpacityArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setMask}. */
 export const PluginPlacedViewsSetMaskArgs = z.object({
   shapeId: z.string().min(1),
   enabled: z.boolean(),
 })
-export type PluginPlacedViewsSetMaskArgs = z.infer<typeof PluginPlacedViewsSetMaskArgs>
+export type PluginPlacedViewsSetMaskArgs = z.infer<
+  typeof PluginPlacedViewsSetMaskArgs
+>