@snaptrude/plugin-core 0.0.0-dev-20260708130115

package/src/api/presentation/diagrams.ts

@@ -0,0 +1,84 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation diagrams — place diagram images onto sheets.
+ *
+ * {@linkcode PluginPresentationDiagramsApi.place} drops diagram images (by
+ * URL) onto a sheet and returns the created canvas shape ids (requires Present
+ * mode to be open). Adjacency data itself is read and computed via
+ * `program.adjacency` (see {@linkcode PluginProgramAdjacencyApi}).
+ *
+ * A future one-step spec-based `place` — which would render a diagram spec
+ * and place it in a single call — awaits a public generator from the
+ * documentation engine; until that generator exists, `place` takes ready
+ * image `urls` (we do not ship a spec-based `place` that would only throw).
+ *
+ * Accessed via `snaptrude.presentation.diagrams`.
+ */
+export abstract class PluginPresentationDiagramsApi {
+  constructor() {}
+
+  /**
+   * Place diagram images onto a sheet.
+   *
+   * Drops the given diagram image URLs onto a sheet and returns the ids of the
+   * created canvas shapes. Requires Present mode to be open.
+   *
+   * @param sheetId - The sheet to place onto.
+   * @param urls - Diagram image URLs to place.
+   * @param options - Optional `position` (`{ x, y }`, relative to the sheet)
+   *   for the placed images.
+   * @returns A {@linkcode PluginPresentationDiagramsPlaceResult} with the created
+   *   `shapeIds`.
+   * @throws If Present mode is not open or the sheet id is invalid.
+   *
+   * @examplePrompt Place the adjacency diagram on Sheet 1
+   * @examplePrompt Add the program diagram to the cover sheet
+   * @examplePrompt Drop these diagram images onto the layout
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.diagrams.place("sheet_1", [
+   *   "https://example.com/program-diagram.png",
+   * ])
+   * ```
+   */
+  public abstract place(
+    sheetId: string,
+    urls: string[],
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginPresentationDiagramsPlaceResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationDiagramsApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to place onto |
+ * | `urls` | `string[]` | Diagram image URLs |
+ * | `position` | `{ x: number; y: number } \| undefined` | Where to place them |
+ */
+export const PluginPresentationDiagramsPlaceArgs = z.object({
+  sheetId: z.string(),
+  urls: z.array(z.string()),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+})
+export type PluginPresentationDiagramsPlaceArgs = z.infer<
+  typeof PluginPresentationDiagramsPlaceArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationDiagramsApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeIds` | `string[]` | Ids of the created canvas shapes |
+ */
+export const PluginPresentationDiagramsPlaceResult = z.object({
+  shapeIds: z.array(z.string()),
+})
+export type PluginPresentationDiagramsPlaceResult = z.infer<
+  typeof PluginPresentationDiagramsPlaceResult
+>

package/src/api/presentation/import.ts

@@ -0,0 +1,112 @@
+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 and `import.pdf` places a PDF (each
+ * page vectorized to 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.
+   *
+   * @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.
+   *
+   * @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>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationImportApi.image} /
+ * {@linkcode PluginPresentationImportApi.pdf}. 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
+>

package/src/api/presentation/index.ts

@@ -0,0 +1,47 @@
+import { PluginPresentationViewsApi } from "./views"
+import { PluginPresentationAIInspirationApi } from "./aiInspiration"
+import { PluginPresentationSheetsApi } from "./sheets"
+import { PluginPresentationDiagramsApi } from "./diagrams"
+import { PluginPresentationImportApi } from "./import"
+
+/**
+ * Presentation APIs — prepare and assemble presentations.
+ *
+ * Reads describe the artifacts a presentation is built from (saved views, layout
+ * sheets); writes assemble them (place views/diagrams on sheets, import
+ * references, capture/save views). Present-mode AI Inspiration also lives here.
+ *
+ * Several members require **Present mode to be open** (the documentation editor):
+ * 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.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
+ *
+ * Accessed via `snaptrude.presentation`.
+ */
+export abstract class PluginPresentationApi {
+  /** Saved 2D/3D views. See {@linkcode PluginPresentationViewsApi}. */
+  public abstract views: PluginPresentationViewsApi
+  /** Layout sheets — list/get/create and place views (Present mode). See {@linkcode PluginPresentationSheetsApi}. */
+  public abstract sheets: PluginPresentationSheetsApi
+  /** Program/adjacency/site diagrams — place images on sheets. See {@linkcode PluginPresentationDiagramsApi}. */
+  public abstract diagrams: PluginPresentationDiagramsApi
+  /** Import reference images/PDFs onto the Present canvas. See {@linkcode PluginPresentationImportApi}. */
+  public abstract import: PluginPresentationImportApi
+  /**
+   * Present-mode AI Inspiration image/video generation. See
+   * {@linkcode PluginPresentationAIInspirationApi}.
+   */
+  public abstract aiInspiration: PluginPresentationAIInspirationApi
+
+  constructor() {}
+}
+
+export * from "./views"
+export * from "./sheets"
+export * from "./diagrams"
+export * from "./import"
+export * from "./aiInspiration"

package/src/api/presentation/sheets.ts

@@ -0,0 +1,198 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation sheets — the layout sheets a presentation is assembled on.
+ *
+ * A **sheet** is a page in Present mode that views and diagrams are placed onto.
+ * These methods require **Present mode to be open** (the documentation editor) —
+ * reads return `[]`/`null` and writes throw when it is not.
+ *
+ * `list`/`get` are reads; `create` adds a sheet and `place` drops a saved view
+ * onto a sheet (returning the id of the created canvas shape).
+ *
+ * Accessed via `snaptrude.presentation.sheets`.
+ */
+export abstract class PluginPresentationSheetsApi {
+  constructor() {}
+
+  /**
+   * List the layout sheets in the presentation.
+   *
+   * @returns A {@linkcode PluginPresentationSheetsListResult} with a `sheets`
+   *   array (empty when Present mode is closed or there are no sheets).
+   *
+   * @examplePrompt List all the sheets
+   * @examplePrompt How many layout sheets are there?
+   * @examplePrompt Show me the presentation sheets
+   * @examplePrompt What sheets can I place views on?
+   *
+   * # Example
+   * ```ts
+   * const { sheets } = await snaptrude.presentation.sheets.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginPresentationSheetsListResult>
+
+  /**
+   * Get a single sheet by id.
+   *
+   * @param sheetId - The id of the sheet to read.
+   * @returns The matching {@linkcode PluginPresentationSheet}, or `null`.
+   *
+   * @examplePrompt Get the sheet with id sheet_1
+   * @examplePrompt Find the sheet called Cover
+   * @examplePrompt Look up a layout sheet by id
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.get("sheet_1")
+   * ```
+   */
+  public abstract get(
+    sheetId: string,
+  ): PluginApiReturn<PluginPresentationSheetsGetResult>
+
+  /**
+   * Create a new layout sheet.
+   *
+   * Requires Present mode to be open.
+   *
+   * @param name - Display name for the new sheet (optional).
+   * @returns The newly created {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Create a new sheet called Cover
+   * @examplePrompt Add a layout sheet
+   * @examplePrompt Make a new presentation sheet named Floor Plans
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.create("Cover")
+   * ```
+   */
+  public abstract create(
+    name?: string,
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Place a saved view onto a sheet.
+   *
+   * Drops the given view onto the sheet at an optional position and returns the
+   * id of the created canvas shape. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to place onto.
+   * @param viewId - The id of the saved view to place.
+   * @param options - Optional `position` ({@linkcode PluginSheetPosition}) —
+   *   where to place it (a default is used when omitted).
+   * @returns A {@linkcode PluginPresentationSheetsPlaceResult} with the created
+   *   `shapeId`.
+   * @throws If Present mode is not open, or the sheet/view id is invalid.
+   *
+   * @examplePrompt Place the floor plan on Sheet 1
+   * @examplePrompt Add this 3D view to the cover sheet
+   * @examplePrompt Drop the site plan onto the layout sheet at 100, 200
+   * @examplePrompt Put the Ground Floor view on sheet_1
+   *
+   * # Example
+   * ```ts
+   * const { shapeId } = await snaptrude.presentation.sheets.place("sheet_1", "view_123")
+   * ```
+   */
+  public abstract place(
+    sheetId: string,
+    viewId: string,
+    options?: { position?: PluginSheetPosition },
+  ): PluginApiReturn<PluginPresentationSheetsPlaceResult>
+}
+
+/**
+ * A layout sheet in the presentation.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Unique sheet id |
+ * | `name` | `string` | Display name |
+ */
+export const PluginPresentationSheet = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+export type PluginPresentationSheet = z.infer<typeof PluginPresentationSheet>
+
+/**
+ * A position on a sheet/canvas (sheet coordinates).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number` | X coordinate |
+ * | `y` | `number` | Y coordinate |
+ */
+export const PluginSheetPosition = z.object({
+  x: z.number(),
+  y: z.number(),
+})
+export type PluginSheetPosition = z.infer<typeof PluginSheetPosition>
+
+/** Result of {@linkcode PluginPresentationSheetsApi.list}. */
+export const PluginPresentationSheetsListResult = z.object({
+  sheets: z.array(PluginPresentationSheet),
+})
+export type PluginPresentationSheetsListResult = z.infer<
+  typeof PluginPresentationSheetsListResult
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.get}. */
+export const PluginPresentationSheetsGetArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationSheetsGetArgs = z.infer<
+  typeof PluginPresentationSheetsGetArgs
+>
+
+/** Result of {@linkcode PluginPresentationSheetsApi.get} — the sheet, or `null`. */
+export const PluginPresentationSheetsGetResult =
+  PluginPresentationSheet.nullable()
+export type PluginPresentationSheetsGetResult = z.infer<
+  typeof PluginPresentationSheetsGetResult
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.create}. */
+export const PluginPresentationSheetsCreateArgs = z.object({
+  name: z.string().optional(),
+})
+export type PluginPresentationSheetsCreateArgs = z.infer<
+  typeof PluginPresentationSheetsCreateArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to place onto |
+ * | `viewId` | `string` | The saved view to place |
+ * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (a default is used when omitted) |
+ */
+export const PluginPresentationSheetsPlaceArgs = z.object({
+  sheetId: z.string(),
+  viewId: z.string(),
+  position: PluginSheetPosition.optional(),
+})
+export type PluginPresentationSheetsPlaceArgs = z.infer<
+  typeof PluginPresentationSheetsPlaceArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the created canvas shape |
+ */
+export const PluginPresentationSheetsPlaceResult = z.object({
+  shapeId: z.string(),
+})
+export type PluginPresentationSheetsPlaceResult = z.infer<
+  typeof PluginPresentationSheetsPlaceResult
+>