@snaptrude/plugin-core 0.10.0 → 1.0.0

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/graphics.ts

@@ -0,0 +1,324 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+
+/** A saved view id. Omit it to address the current Design/BIM view. */
+export const PluginGraphicsViewId = z.union([
+  z.string().min(1),
+  z.number().finite().int().nonnegative(),
+])
+export type PluginGraphicsViewId = z.infer<typeof PluginGraphicsViewId>
+
+/** A scale denominator: 50 means 1:50, not a world-coordinate multiplier. */
+export const PluginGraphicsScale = z.number().finite().int().min(1).max(24000)
+export const PluginGraphicsDetailLevel = z.enum(["coarse", "fine"])
+export type PluginGraphicsDetailLevel = z.infer<
+  typeof PluginGraphicsDetailLevel
+>
+export const PluginGraphicsViewKind = z.enum([
+  "plan",
+  "section",
+  "elevation",
+  "three-d",
+])
+export const PluginGraphicsPen = z.number().finite().int().min(1).max(16)
+
+/** Native Object Styles category keys; use these keys rather than the displayed plural labels. */
+export const PluginGraphicsModelCategory = z.enum([
+  "Buildable Envelope",
+  "Ceilings",
+  "Columns",
+  "Departments",
+  "Doors",
+  "Floors",
+  "Furniture",
+  "Families",
+  "Facade/Mass",
+  "Roofs",
+  "Slabs",
+  "Space",
+  "Staircase",
+  "Beams",
+  "Walls",
+  "Windows",
+])
+export const PluginGraphicsAnnotationCategory = z.enum([
+  "Dimension",
+  "Grids",
+  "Sections",
+])
+export const PluginGraphicsCategory = z.enum([
+  ...PluginGraphicsModelCategory.options,
+  ...PluginGraphicsAnnotationCategory.options,
+])
+export const PluginGraphicsOverrideCategory = z.enum([
+  ...PluginGraphicsCategory.options,
+  "Lines",
+])
+export type PluginGraphicsOverrideCategory = z.infer<
+  typeof PluginGraphicsOverrideCategory
+>
+
+/** Project line-style ids. These select a pen and pattern together. */
+export const PluginGraphicsLineStyleId = z.enum([
+  "thin",
+  "medium",
+  "wide",
+  "hidden",
+  "overhead",
+  "demolished",
+  "centerline",
+])
+export type PluginGraphicsLineStyleId = z.infer<
+  typeof PluginGraphicsLineStyleId
+>
+
+/** Paper dash patterns; their lengths are paper millimetres, not model units. */
+export const PluginGraphicsPatternId = z.enum([
+  "solid",
+  "dash",
+  "hidden",
+  "long-dash",
+  "loose-dash",
+  "dot",
+  "dash-dot",
+  "dash-dot-dot",
+  "center",
+  "overhead",
+  "demolished",
+  "double-dash",
+  "triple-dash",
+])
+export type PluginGraphicsPatternId = z.infer<typeof PluginGraphicsPatternId>
+
+/**
+ * Machine-readable reasons in PluginError.details.reason. Wire codes remain the
+ * published PRECONDITION_FAILED (feature disabled) or VALIDATION (file errors).
+ */
+export const PluginPaperPensErrorReason = z.enum([
+  "PAPER_PENS_DISABLED",
+  "NOT_ACTIVE_VIEW",
+  "NOT_A_STANDARD",
+  "NEWER_STANDARD",
+  "STANDARD_TOO_LARGE",
+])
+export type PluginPaperPensErrorReason = z.infer<
+  typeof PluginPaperPensErrorReason
+>
+
+/**
+ * Sparse category edit. Omitted fields stay unchanged; false clears a flag and
+ * null clears a pen override. Pens are numbers 1–16, never paper-mm widths.
+ * Lines supports flags only; annotation rows do not have a cut pen.
+ */
+export const PluginGraphicsOverride = z
+  .object({
+    hidden: z.boolean().optional(),
+    halftone: z.boolean().optional(),
+    projection: PluginGraphicsPen.nullable().optional(),
+    cut: PluginGraphicsPen.nullable().optional(),
+  })
+  .strict()
+export const PluginGraphicsOverrides = z
+  .partialRecord(PluginGraphicsOverrideCategory, PluginGraphicsOverride)
+  .superRefine((rows, ctx) => {
+    for (const [category, row] of Object.entries(rows)) {
+      if (!row) continue
+      if (
+        category === "Lines" &&
+        (row.projection !== undefined || row.cut !== undefined)
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: [category],
+          message: "Lines has visibility and halftone only",
+        })
+      } else if (
+        PluginGraphicsAnnotationCategory.options.some(
+          (value) => value === category,
+        ) &&
+        row.cut !== undefined
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: [category, "cut"],
+          message: "Annotation categories have no cut pen",
+        })
+      }
+    }
+  })
+export type PluginGraphicsOverrides = z.infer<typeof PluginGraphicsOverrides>
+
+/**
+ * One Design/BIM view's graphics. viewId:null means an unsaved current view.
+ * scale/scaleLabel:null means the camera has no applicable paper scale (free3D
+ * or a perspective section/elevation). Transient scale/detail edits are not saved.
+ */
+export const PluginViewGraphics = z.object({
+  viewId: z.string().nullable(),
+  kind: PluginGraphicsViewKind,
+  scale: PluginGraphicsScale.nullable(),
+  scaleLabel: z.string().nullable(),
+  isCustomScale: z.boolean(),
+  detailLevel: PluginGraphicsDetailLevel,
+  overrides: PluginGraphicsOverrides,
+})
+export type PluginViewGraphics = z.infer<typeof PluginViewGraphics>
+
+/** The same ordered scale choices as the chip, including the current exceptional scale. */
+export const PluginGraphicsScaleOption = z.object({
+  scale: PluginGraphicsScale,
+  label: z.string(),
+  isCustomScale: z.boolean(),
+})
+export type PluginGraphicsScaleOption = z.infer<
+  typeof PluginGraphicsScaleOption
+>
+
+export const PluginGraphicsViewOptions = z
+  .object({ viewId: PluginGraphicsViewId.optional() })
+  .strict()
+export type PluginGraphicsViewOptions = z.infer<
+  typeof PluginGraphicsViewOptions
+>
+export const PluginGraphicsGetArgs = PluginGraphicsViewOptions
+export const PluginGraphicsSetScaleArgs = z
+  .object({
+    scale: PluginGraphicsScale,
+    options: PluginGraphicsViewOptions.optional(),
+  })
+  .strict()
+export const PluginGraphicsSetDetailLevelArgs = z
+  .object({
+    level: PluginGraphicsDetailLevel,
+    options: PluginGraphicsViewOptions.optional(),
+  })
+  .strict()
+export const PluginGraphicsUpdateArgs = z
+  .object({
+    overrides: PluginGraphicsOverrides,
+    options: PluginGraphicsViewOptions.optional(),
+  })
+  .strict()
+export const PluginGraphicsResetOptions = PluginGraphicsViewOptions.extend({
+  category: PluginGraphicsOverrideCategory.optional(),
+}).strict()
+export type PluginGraphicsResetOptions = z.infer<
+  typeof PluginGraphicsResetOptions
+>
+export const PluginGraphicsResetArgs = z
+  .object({ options: PluginGraphicsResetOptions.optional() })
+  .strict()
+export const PluginGraphicsNoArgs = z.object({}).strict()
+
+/**
+ * Paper Pens on the Design/BIM canvas. Does not require Present mode.
+ *
+ * Scale/detail use the native UI setters: saved views persist, but these two
+ * settings are not model undo steps. Overrides are one saved, undoable step.
+ * Thin Lines is a local viewer preference, never a model save/undo or peer edit.
+ * All writes refuse PRECONDITION_FAILED with details.reason=PAPER_PENS_DISABLED
+ * while canvas-view-scale is off; reads still answer. There is no flag setter.
+ */
+export abstract class PluginPresentationGraphicsApi {
+  /**
+   * Whether Paper Pens is enabled on this viewer. Never changes the feature flag.
+   * @returns The current canvas-view-scale value.
+   */
+  public abstract isEnabled(): PluginApiReturn<boolean>
+
+  /**
+   * Read a view's scale denominator, detail and category overrides.
+   * @param viewId - Saved view id; omitted uses the current view.
+   * @returns Its graphics, or null for an unknown/inaccessible saved view.
+   * @examplePrompt What scale is this plan drawn at?
+   */
+  public abstract get(
+    viewId?: PluginGraphicsViewId,
+  ): PluginApiReturn<PluginViewGraphics | null>
+
+  /**
+   * List the chip's scale choices for the project units, in the same order.
+   * Custom denominators need not be listed: any integer 1–24000 is valid.
+   * @param viewId - View whose current custom/other-unit scale should be included.
+   * @returns Scale records; [] for an unknown/inaccessible saved view.
+   */
+  public abstract listScales(
+    viewId?: PluginGraphicsViewId,
+  ): PluginApiReturn<PluginGraphicsScaleOption[]>
+
+  /**
+   * Set a paper view's denominator through the same path as the scale chip.
+   * A saved view persists this change; it is not a model undo step. Without a
+   * saved current view, only viewer state changes. Does not switch the camera. An inactive target refuses NOT_ACTIVE_VIEW.
+   * @param scale - Integer 1–24000; 50 means 1:50.
+   * @param options - Optional id must identify the active view; open another view first.
+   * @returns Updated graphics.
+   * @throws VALIDATION for an invalid denominator; PRECONDITION_FAILED when
+   *   Paper Pens is off or the target has no applicable paper scale.
+   * @examplePrompt Set this plan to 1:50
+   * @example await snaptrude.presentation.graphics.setScale(50)
+   */
+  public abstract setScale(
+    scale: number,
+    options?: PluginGraphicsViewOptions,
+  ): PluginApiReturn<PluginViewGraphics>
+
+  /**
+   * Set the active plan's Coarse/Fine drawing detail through the native setter. Fine draws wall
+   * layers; this does not enable the project's Detailed View take-off setting.
+   * Saved for a saved view, not a model undo step; unsaved current views are transient.
+   * @param level - coarse or fine.
+   * @param options - Optional id must identify the active view; open another view first.
+   * @returns Updated graphics.
+   * @examplePrompt Show this plan in Fine detail
+   * @example await snaptrude.presentation.graphics.setDetailLevel("fine")
+   */
+  public abstract setDetailLevel(
+    level: PluginGraphicsDetailLevel,
+    options?: PluginGraphicsViewOptions,
+  ): PluginApiReturn<PluginViewGraphics>
+
+  /**
+   * Change only supplied category fields, as one saved and undoable step.
+   * Does not edit project standards. Requires a saved view.
+   * @param overrides - Known category keys and sparse fields; false/null clear overrides.
+   * @param options - Target saved view; omitted uses the current view. Inactive views are supported.
+   * @returns Updated graphics.
+   * @examplePrompt Halftone the furniture in this view
+   * @example await snaptrude.presentation.graphics.update({ Furniture: { halftone: true } })
+   */
+  public abstract update(
+    overrides: PluginGraphicsOverrides,
+    options?: PluginGraphicsViewOptions,
+  ): PluginApiReturn<PluginViewGraphics>
+
+  /**
+   * Clear one category or all category overrides, as one saved undoable step.
+   * The view's scale and detail level are preserved.
+   * @param options - Optional saved view and category; omit category to reset all rows.
+   * @returns Updated graphics.
+   */
+  public abstract reset(
+    options?: PluginGraphicsResetOptions,
+  ): PluginApiReturn<PluginViewGraphics>
+
+  /**
+   * Read the remembered Thin Lines preference. A disabled feature or capture
+   * suspension can make the renderer ignore a true preference temporarily.
+   * @returns The viewer preference, not the transient capture state.
+   */
+  public abstract isThinLinesEnabled(): PluginApiReturn<boolean>
+
+  /**
+   * Enable the viewer's Thin Lines preference. No model save, undo or peer change.
+   * capture_view and exported images deliberately suspend it and use real weights.
+   * @returns true.
+   */
+  public abstract enableThinLines(): PluginApiReturn<boolean>
+
+  /**
+   * Disable the viewer's Thin Lines preference. No model save, undo or peer change.
+   * @returns false.
+   */
+  public abstract disableThinLines(): PluginApiReturn<boolean>
+}

package/src/api/presentation/index.ts

@@ -1,18 +1,26 @@
 import { PluginApiReturn } from "../../types"
 import { PluginPresentationViewsApi } from "./views"
+import { PluginPresentationCameraApi } from "./camera"
 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 { PluginPresentationWalkthroughsApi } from "./walkthroughs"
+import { PluginPresentationSectionsApi } from "./sections"
+import { PluginPresentationGraphicsApi } from "./graphics"
+import { PluginPresentationStandardsApi } from "./standards"
 import {
-  PluginPresentationExportResult,
+  type PluginPresentationExportResult,
+  type PluginPresentationExportDownloadResult,
   type PluginPresentationExportFormat,
-  type PluginPresentationExportResolution,
+  type PluginPresentationExportOptions,
 } from "./export"
 
 /**
@@ -26,19 +34,33 @@ import {
  * 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.camera} — The Present canvas camera (screenshot, pan/zoom, frame sheets)
+ * - {@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
  * - {@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
+ * - {@linkcode PluginPresentationApi.walkthroughs} — Camera paths through the model: create, play, capture, export as video
+ * - {@linkcode PluginPresentationApi.sections} — Section lines: create, edit, open their views, and read what each cuts
+ *
+ * - {@linkcode PluginPresentationApi.graphics} — Design/BIM view scale, detail, category overrides and viewer Thin Lines
+ * - {@linkcode PluginPresentationApi.standards} — Project graphic standards and standard-file interchange
  *
  * Accessed via `snaptrude.presentation`.
  */
 export abstract class PluginPresentationApi {
   /** Saved 2D/3D views. See {@linkcode PluginPresentationViewsApi}. */
   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}. */
@@ -60,18 +82,41 @@ export abstract class PluginPresentationApi {
    * {@linkcode PluginPresentationAIInspirationApi}.
    */
   public abstract aiInspiration: PluginPresentationAIInspirationApi
+  /**
+   * Walkthroughs — camera paths through the model: create (keyframes, floor
+   * points, camera-move presets), play, capture and export as video onto the
+   * Present canvas. See {@linkcode PluginPresentationWalkthroughsApi}.
+   */
+  public abstract walkthroughs: PluginPresentationWalkthroughsApi
+  /**
+   * Sections — lines on the plan that cut the model: create, edit and delete
+   * them, open their views, and read what each one cuts (`getCut`). See
+   * {@linkcode PluginPresentationSectionsApi}.
+   */
+  public abstract sections: PluginPresentationSectionsApi
+  /** Paper Pens scale, detail, overrides and Thin Lines on the Design/BIM canvas. */
+  public abstract graphics: PluginPresentationGraphicsApi
+  /** Project graphic standards in paper mm, including native file import/export. */
+  public abstract standards: PluginPresentationStandardsApi
 
   /**
    * 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.
    *
@@ -84,22 +129,29 @@ 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() {}
 }
 
 export * from "./views"
+export * from "./camera"
 export * from "./sheets"
 export * from "./placedViews"
 export * from "./diagrams"
@@ -109,4 +161,11 @@ export * from "./tables"
 export * from "./slideshow"
 export * from "./import"
 export * from "./aiInspiration"
+export * from "./walkthroughs"
+export * from "./sections"
+export * from "./graphics"
+export * from "./standards"
 export * from "./export"
+export * from "./drawings"
+export * from "./drawingContract"
+export * from "./viewPresets"