@snaptrude/plugin-core 0.8.0 → 0.9.0

package/src/api/presentation/export.ts

@@ -20,6 +20,10 @@ import * as z from "zod"
  *
  * 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}.
  */

package/src/api/presentation/import.ts

@@ -20,6 +20,9 @@ export abstract class PluginPresentationImportApi {
   /**
    * 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.
@@ -50,6 +53,9 @@ export abstract class PluginPresentationImportApi {
    *
    * 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.

package/src/api/presentation/index.ts

@@ -2,8 +2,10 @@ import { PluginApiReturn } from "../../types"
 import { PluginPresentationViewsApi } from "./views"
 import { PluginPresentationAIInspirationApi } from "./aiInspiration"
 import { PluginPresentationSheetsApi } from "./sheets"
+import { PluginPresentationPlacedViewsApi } from "./placedViews"
 import { PluginPresentationDiagramsApi } from "./diagrams"
 import { PluginPresentationAnnotateApi } from "./annotate"
+import { PluginPresentationShapesApi } from "./shapes"
 import { PluginPresentationImportApi } from "./import"
 import {
   PluginPresentationExportResult,
@@ -23,6 +25,7 @@ import {
  *
  * - {@linkcode PluginPresentationApi.views} — Saved 2D/3D views (list, get, capture, activate, create)
  * - {@linkcode PluginPresentationApi.sheets} — Layout sheets (list, get, create, place views)
+ * - {@linkcode PluginPresentationApi.placedViews} — Views already placed on the canvas (move, scale, crop)
  * - {@linkcode PluginPresentationApi.diagrams} — Place program/adjacency/site diagram images on sheets
  * - {@linkcode PluginPresentationApi.import} — Import reference images/PDFs onto the canvas
  * - {@linkcode PluginPresentationApi.aiInspiration} — Present-mode AI image/video generation
@@ -34,10 +37,14 @@ export abstract class PluginPresentationApi {
   public abstract views: PluginPresentationViewsApi
   /** Layout sheets — list/get/create and place views (Present mode). See {@linkcode PluginPresentationSheetsApi}. */
   public abstract sheets: PluginPresentationSheetsApi
+  /** Placed views — layout of the view shapes on the canvas: move/scale/setScale/setCrop (Present mode). See {@linkcode PluginPresentationPlacedViewsApi}. */
+  public abstract placedViews: PluginPresentationPlacedViewsApi
   /** Program/adjacency/site diagrams — place images on sheets. See {@linkcode PluginPresentationDiagramsApi}. */
   public abstract diagrams: PluginPresentationDiagramsApi
   /** Annotations on Present-mode sheets — text/arrows/notes/geo shapes. See {@linkcode PluginPresentationAnnotateApi}. */
   public abstract annotate: PluginPresentationAnnotateApi
+  /** Plugin-owned keyed shapes — upsert/remove/list so reruns update instead of duplicating. See {@linkcode PluginPresentationShapesApi}. */
+  public abstract shapes: PluginPresentationShapesApi
   /** Import reference images/PDFs onto the Present canvas. See {@linkcode PluginPresentationImportApi}. */
   public abstract import: PluginPresentationImportApi
   /**
@@ -86,8 +93,10 @@ export abstract class PluginPresentationApi {
 
 export * from "./views"
 export * from "./sheets"
+export * from "./placedViews"
 export * from "./diagrams"
 export * from "./annotate"
+export * from "./shapes"
 export * from "./import"
 export * from "./aiInspiration"
 export * from "./export"

package/src/api/presentation/placedViews.ts

@@ -0,0 +1,363 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginSheetPosition } from "./sheets"
+
+/**
+ * Placed views — the view shapes already laid out on the Present canvas.
+ *
+ * A **placed view** is a saved view that has been dropped onto a layout sheet
+ * (or the open canvas) — the live linked view shape
+ * {@linkcode PluginPresentationSheetsApi.place} and the Present views panel's
+ * drag-drop create. These methods read and edit the **layout** of those
+ * shapes: where they sit, how big they are, their architectural scale, and
+ * their crop. To refresh a placed view's **content** from the current model,
+ * use `sheets.updatePlacedView` — content refresh lives on `sheets`,
+ * layout lives here.
+ *
+ * Reads (`list`) return `[]` when Present mode is closed; `get` and every
+ * write require Present mode to be open.
+ *
+ * Accessed via `snaptrude.presentation.placedViews`.
+ */
+export abstract class PluginPresentationPlacedViewsApi {
+  constructor() {}
+
+  /**
+   * List the placed views in the presentation.
+   *
+   * Returns every placed view shape on the Present canvas — those nested on a
+   * layout sheet (with that sheet's id) and those sitting loose on the canvas
+   * (`sheetId: null`). Pass `sheetId` to list only the views placed on that
+   * sheet.
+   *
+   * @param sheetId - Optional sheet id to filter by.
+   * @returns A {@linkcode PluginPresentationPlacedViewsListResult} with a
+   *   `placedViews` array (empty when Present mode is closed or nothing is
+   *   placed).
+   * @throws If `sheetId` is given but is not a sheet (with Present mode open).
+   *
+   * @examplePrompt Which views are placed on this sheet?
+   * @examplePrompt List all the placed views in the presentation
+   * @examplePrompt What's laid out on sheet 2?
+   * @examplePrompt Show me every view on the Present canvas
+   *
+   * # Example
+   * ```ts
+   * const { placedViews } = await snaptrude.presentation.placedViews.list("sheet_1")
+   * ```
+   */
+  public abstract list(
+    sheetId?: string,
+  ): PluginApiReturn<PluginPresentationPlacedViewsListResult>
+
+  /**
+   * Get a single placed view by its shape id.
+   *
+   * `shapeId` is the id `sheets.place` returned (also reported by `list`).
+   *
+   * @param shapeId - The id of the placed view shape to read.
+   * @returns The matching {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, or `shapeId` is unknown or is not a
+   *   placed view.
+   *
+   * @examplePrompt Get the placed view I just dropped on the sheet
+   * @examplePrompt Read the position and scale of this placed view
+   * @examplePrompt What's the crop on shape_123?
+   *
+   * # Example
+   * ```ts
+   * const placed = await snaptrude.presentation.placedViews.get(shapeId)
+   * console.log(placed.position, placed.scale)
+   * ```
+   */
+  public abstract get(shapeId: string): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Move a placed view.
+   *
+   * Repositions the placed view on its sheet — `position` is the new top-left
+   * in sheet coordinates (page coordinates when the view is not on a sheet).
+   * Pass `options.sheetId` to move it onto another sheet: the view is
+   * reparented to that sheet and then positioned at `position` in the new
+   * sheet's coordinates. A grouped placed view (e.g. a sustainability 3D view
+   * with its legend) moves as one unit. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to move.
+   * @param position - New top-left position (sheet-local; page coordinates
+   *   when off-sheet).
+   * @param options - Optional `sheetId` — move the view onto that sheet.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `options.sheetId` is given but is not a sheet.
+   *
+   * @examplePrompt Move the site plan view to the top-left of sheet 2
+   * @examplePrompt Reposition this placed view to 100, 200
+   * @examplePrompt Move the hero perspective onto the cover sheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.move(shapeId, { x: 50, y: 50 }, {
+   *   sheetId: "sheet_2",
+   * })
+   * ```
+   */
+  public abstract move(
+    shapeId: string,
+    position: PluginSheetPosition,
+    options?: { sheetId?: string },
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Resize a placed view by a uniform factor.
+   *
+   * Scales the placed view about its top-left corner — the same resize as
+   * dragging a corner handle, aspect ratio held. Works for 2D and 3D views;
+   * labels and grouped legends resize with it. For a 2D view the **printed
+   * architectural scale changes proportionally** (doubling the size of a
+   * 1:100 plan makes it a 1:50 plan) — use
+   * {@linkcode PluginPresentationPlacedViewsApi.setScale} to land on an exact
+   * standard scale instead. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to resize.
+   * @param factor - Uniform scale factor, between `0.01` and `100`
+   *   (`2` doubles the size, `0.5` halves it).
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `factor` is not a finite number between 0.01 and 100.
+   *
+   * @examplePrompt Make this placed view twice as big
+   * @examplePrompt Shrink the placed 3D view to half its size
+   * @examplePrompt Scale the placed plan up by 50%
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.scale(shapeId, 2)
+   * ```
+   */
+  public abstract scale(
+    shapeId: string,
+    factor: number,
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Set a placed view's architectural scale.
+   *
+   * 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
+   * one throws. Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to set the scale of.
+   * @param scale - A standard scale value for the project's unit system.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, `scale` is not a standard value for the project's unit
+   *   system, or the placed view is a 3D view.
+   *
+   * @examplePrompt Set the plan to 1:100
+   * @examplePrompt Change the placed floor plan to 1:50 scale
+   * @examplePrompt Make this view print at quarter-inch scale
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.placedViews.setScale(shapeId, 100) // 1:100
+   * ```
+   */
+  public abstract setScale(
+    shapeId: string,
+    scale: number,
+  ): PluginApiReturn<PluginPlacedView>
+
+  /**
+   * Crop a placed view, or clear its crop.
+   *
+   * `crop` selects the visible window as **fractions (0–1) of the uncropped
+   * view** — `topLeft` must be strictly less than `bottomRight` on both axes.
+   * The visible region stays anchored on the page (the same behavior as the
+   * interactive crop), labels that fall outside the crop are hidden, and the
+   * view's architectural scale is untouched. Pass `null` to clear the crop
+   * and restore the full view in its uncropped footprint (the interactive
+   * double-click-edge reset). The crop **survives a content refresh**
+   * (`sheets.updatePlacedView` recomputes it against the refreshed content
+   * and only clears it when the refreshed view no longer overlaps the cropped
+   * region). Requires Present mode to be open.
+   *
+   * @param shapeId - The placed view shape to crop.
+   * @param crop - The crop window ({@linkcode PluginPlacedViewCrop},
+   *   fractions of the uncropped view), or `null` to clear.
+   * @returns The updated {@linkcode PluginPlacedView}.
+   * @throws If Present mode is not open, `shapeId` is unknown or is not a
+   *   placed view, or `crop` is not a valid 0–1 rectangle with
+   *   `topLeft < bottomRight` on both axes.
+   *
+   * @examplePrompt Crop the placed view to its left half
+   * @examplePrompt Crop this view to the top-right quarter
+   * @examplePrompt Remove the crop from the placed plan
+   *
+   * # Example
+   * ```ts
+   * // keep the left half of the view
+   * await snaptrude.presentation.placedViews.setCrop(shapeId, {
+   *   topLeft: { x: 0, y: 0 },
+   *   bottomRight: { x: 0.5, y: 1 },
+   * })
+   * await snaptrude.presentation.placedViews.setCrop(shapeId, null) // clear
+   * ```
+   */
+  public abstract setCrop(
+    shapeId: string,
+    crop: PluginPlacedViewCrop | null,
+  ): PluginApiReturn<PluginPlacedView>
+}
+
+/** A point in crop space — fractions (0–1) of the uncropped view. */
+const PluginPlacedViewCropPoint = z.object({
+  x: z.number().min(0).max(1),
+  y: z.number().min(0).max(1),
+})
+
+/**
+ * A crop window on a placed view, as fractions (0–1) of the **uncropped**
+ * view. `topLeft` must be strictly less than `bottomRight` on both axes.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `topLeft` | `{ x: number, y: number }` | Top-left of the visible window (fractions 0–1) |
+ * | `bottomRight` | `{ x: number, y: number }` | Bottom-right of the visible window (fractions 0–1) |
+ */
+export const PluginPlacedViewCrop = z
+  .object({
+    topLeft: PluginPlacedViewCropPoint,
+    bottomRight: PluginPlacedViewCropPoint,
+  })
+  .refine(
+    (c) => c.topLeft.x < c.bottomRight.x && c.topLeft.y < c.bottomRight.y,
+    { message: "topLeft must be strictly less than bottomRight on both axes" },
+  )
+export type PluginPlacedViewCrop = z.infer<typeof PluginPlacedViewCrop>
+
+/**
+ * A view placed on the Present canvas.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the placed view shape (the id `sheets.place` returns) |
+ * | `sheetId` | `string \| null` | The sheet it sits on (`null` when placed loose on the canvas) |
+ * | `title` | `string` | The saved view's title |
+ * | `viewId` | `string` | Id of the saved view it was placed from |
+ * | `position` | {@linkcode PluginSheetPosition} | Top-left position — sheet-local when on a sheet, page coordinates otherwise |
+ * | `size` | `{ width: number, height: number }` | Displayed size on the canvas |
+ * | `scale` | `number \| null` | Architectural scale (e.g. `100` = 1:100); `null` for 3D views |
+ * | `is3d` | `boolean` | Whether it is a 3D view (no architectural scale) |
+ * | `rotation` | `number` | Rotation in radians (nonzero only for 3D views) |
+ * | `crop` | {@linkcode PluginPlacedViewCrop}` \| null` | Crop window (`null` when uncropped) |
+ * | `isUnlinked` | `boolean` | Whether the source proposal was removed (an unlinked view no longer refreshes) |
+ */
+export const PluginPlacedView = z.object({
+  shapeId: z.string(),
+  sheetId: z.string().nullable(),
+  title: z.string(),
+  viewId: z.string(),
+  position: PluginSheetPosition,
+  size: z.object({ width: z.number(), height: z.number() }),
+  scale: z.number().nullable(),
+  is3d: z.boolean(),
+  rotation: z.number(),
+  crop: PluginPlacedViewCrop.nullable(),
+  isUnlinked: z.boolean(),
+})
+export type PluginPlacedView = z.infer<typeof PluginPlacedView>
+
+/** Arguments for {@linkcode PluginPresentationPlacedViewsApi.list}. */
+export const PluginPresentationPlacedViewsListArgs = z.object({
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationPlacedViewsListArgs = z.infer<
+  typeof PluginPresentationPlacedViewsListArgs
+>
+
+/** Result of {@linkcode PluginPresentationPlacedViewsApi.list}. */
+export const PluginPresentationPlacedViewsListResult = z.object({
+  placedViews: z.array(PluginPlacedView),
+})
+export type PluginPresentationPlacedViewsListResult = z.infer<
+  typeof PluginPresentationPlacedViewsListResult
+>
+
+/** Arguments for {@linkcode PluginPresentationPlacedViewsApi.get}. */
+export const PluginPresentationPlacedViewsGetArgs = z.object({
+  shapeId: z.string(),
+})
+export type PluginPresentationPlacedViewsGetArgs = z.infer<
+  typeof PluginPresentationPlacedViewsGetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to move |
+ * | `position` | {@linkcode PluginSheetPosition} | New top-left position (sheet-local; page coordinates when off-sheet) |
+ * | `sheetId` | `string`? | Move the view onto this sheet |
+ */
+export const PluginPresentationPlacedViewsMoveArgs = z.object({
+  shapeId: z.string(),
+  position: PluginSheetPosition,
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationPlacedViewsMoveArgs = z.infer<
+  typeof PluginPresentationPlacedViewsMoveArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.scale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to resize |
+ * | `factor` | `number` | Uniform scale factor (0.01–100) |
+ */
+export const PluginPresentationPlacedViewsScaleArgs = z.object({
+  shapeId: z.string(),
+  factor: z.number().finite().min(0.01).max(100),
+})
+export type PluginPresentationPlacedViewsScaleArgs = z.infer<
+  typeof PluginPresentationPlacedViewsScaleArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.setScale}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to set the scale of |
+ * | `scale` | `number` | A standard scale value for the project's unit system |
+ */
+export const PluginPresentationPlacedViewsSetScaleArgs = z.object({
+  shapeId: z.string(),
+  scale: z.number().positive(),
+})
+export type PluginPresentationPlacedViewsSetScaleArgs = z.infer<
+  typeof PluginPresentationPlacedViewsSetScaleArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationPlacedViewsApi.setCrop}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The placed view shape to crop |
+ * | `crop` | {@linkcode PluginPlacedViewCrop}` \| null` | The crop window, or `null` to clear |
+ */
+export const PluginPresentationPlacedViewsSetCropArgs = z.object({
+  shapeId: z.string(),
+  crop: PluginPlacedViewCrop.nullable(),
+})
+export type PluginPresentationPlacedViewsSetCropArgs = z.infer<
+  typeof PluginPresentationPlacedViewsSetCropArgs
+>