@snaptrude/plugin-core 0.7.1 → 0.8.0

package/dist/api/presentation/diagrams.d.ts

@@ -1,22 +1,52 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../types";
 /**
- * Presentation diagrams — place diagram images onto sheets.
+ * Presentation diagrams — generate program diagrams from the model, and 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
+ * {@linkcode PluginPresentationDiagramsApi.generateProgram} runs the Present-mode
+ * **Program** action: it reads the project's spaces and departments and creates
+ * new layout sheets holding the generated diagram graphics.
+ * {@linkcode PluginPresentationDiagramsApi.place} drops ready diagram images (by
+ * URL) onto an existing sheet and returns the created canvas shape ids. Both
+ * require 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).
+ * There is intentionally no `generateAdjacency`: the host's adjacency generator
+ * runs its sheet-creation task fire-and-forget internally, so a single call
+ * cannot return the sheets it creates. Use the Present-mode Adjacency menu for
+ * those, then `place` a pre-rendered adjacency image if you need it via the API.
  *
  * Accessed via `snaptrude.presentation.diagrams`.
  */
 export declare abstract class PluginPresentationDiagramsApi {
     constructor();
+    /**
+     * Generate the program (space + department) diagrams for the current model,
+     * creating new layout sheets.
+     *
+     * Runs the same auto-generation as the Present-mode **Program** action: reads
+     * the project's spaces and departments, lays them out to scale, and creates one
+     * or more new sheets holding the generated diagram graphics. Unlike
+     * {@linkcode PluginPresentationDiagramsApi.place} (which pastes ready image URLs
+     * onto an existing sheet), this generates the graphics from the model and
+     * creates its own sheets. Requires Present mode to be open.
+     *
+     * @returns A {@linkcode PluginPresentationDiagramsGenerateResult} with the
+     *   `sheetIds` of the sheets created.
+     * @throws If Present mode is not open, or the model has no spaces/departments to
+     *   generate from.
+     *
+     * @examplePrompt Generate the program diagrams for this project
+     * @examplePrompt Auto-generate the space and department diagram sheets
+     * @examplePrompt Create the program layout sheets from the model
+     *
+     * # Example
+     * ```ts
+     * const { sheetIds } = await snaptrude.presentation.diagrams.generateProgram()
+     * ```
+     */
+    abstract generateProgram(): PluginApiReturn<PluginPresentationDiagramsGenerateResult>;
     /**
      * Place diagram images onto a sheet.
      *
@@ -78,4 +108,15 @@ export declare const PluginPresentationDiagramsPlaceResult: z.ZodObject<{
     shapeIds: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type PluginPresentationDiagramsPlaceResult = z.infer<typeof PluginPresentationDiagramsPlaceResult>;
+/**
+ * Result of {@linkcode PluginPresentationDiagramsApi.generateProgram}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetIds` | `string[]` | Ids of the sheets created by the generator |
+ */
+export declare const PluginPresentationDiagramsGenerateResult: z.ZodObject<{
+    sheetIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PluginPresentationDiagramsGenerateResult = z.infer<typeof PluginPresentationDiagramsGenerateResult>;
 //# sourceMappingURL=diagrams.d.ts.map

package/dist/api/presentation/diagrams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagrams.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/diagrams.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,6BAA6B;;IAGjD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,KAAK,CACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAChD,eAAe,CAAC,qCAAqC,CAAC;CAC1D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC;;;;;;;iBAI9C,CAAA;AACF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CACvD,OAAO,mCAAmC,CAC3C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC;;iBAEhD,CAAA;AACF,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CACzD,OAAO,qCAAqC,CAC7C,CAAA"}
+{"version":3,"file":"diagrams.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/diagrams.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,6BAA6B;;IAGjD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,eAAe,IAAI,eAAe,CAAC,wCAAwC,CAAC;IAE5F;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,KAAK,CACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAChD,eAAe,CAAC,qCAAqC,CAAC;CAC1D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC;;;;;;;iBAI9C,CAAA;AACF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CACvD,OAAO,mCAAmC,CAC3C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC;;iBAEhD,CAAA;AACF,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CACzD,OAAO,qCAAqC,CAC7C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wCAAwC;;iBAEnD,CAAA;AACF,MAAM,MAAM,wCAAwC,GAAG,CAAC,CAAC,KAAK,CAC5D,OAAO,wCAAwC,CAChD,CAAA"}

package/dist/api/presentation/export.d.ts

@@ -0,0 +1,104 @@
+import * as z from "zod";
+/**
+ * Presentation export — render the Present-mode layout sheets to a downloadable
+ * file (PDF / PNG / JPG) and hand the plugin the bytes as base64.
+ *
+ * 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).
+ *
+ * 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`.
+ *
+ * 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 declare const PluginPresentationExportFormat: z.ZodEnum<{
+    pdf: "pdf";
+    png: "png";
+    jpg: "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 declare const PluginPresentationExportResolution: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+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) |
+ */
+export declare const PluginPresentationExportArgs: z.ZodObject<{
+    format: z.ZodEnum<{
+        pdf: "pdf";
+        png: "png";
+        jpg: "jpg";
+    }>;
+    sheetIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    combine: z.ZodOptional<z.ZodBoolean>;
+    resolution: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    fileName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginPresentationExportArgs = z.infer<typeof PluginPresentationExportArgs>;
+/**
+ * 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 declare const PluginPresentationExportFile: z.ZodObject<{
+    fileName: z.ZodString;
+    mimeType: z.ZodString;
+    dataBase64: z.ZodString;
+}, z.core.$strip>;
+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 declare const PluginPresentationExportResult: z.ZodObject<{
+    files: z.ZodArray<z.ZodObject<{
+        fileName: z.ZodString;
+        mimeType: z.ZodString;
+        dataBase64: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginPresentationExportResult = z.infer<typeof PluginPresentationExportResult>;
+//# sourceMappingURL=export.d.ts.map

package/dist/api/presentation/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/export.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AAExB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,yEAAyE;AACzE,eAAO,MAAM,8BAA8B;;;;EAAgC,CAAA;AAC3E,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC;;;iBAG7C,CAAA;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CACtD,OAAO,kCAAkC,CAC1C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;iBAMvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;;;;iBAIvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B;;;;;;iBAEzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA"}

package/dist/api/presentation/index.d.ts

@@ -1,8 +1,11 @@
+import { PluginApiReturn } from "../../types";
 import { PluginPresentationViewsApi } from "./views";
 import { PluginPresentationAIInspirationApi } from "./aiInspiration";
 import { PluginPresentationSheetsApi } from "./sheets";
 import { PluginPresentationDiagramsApi } from "./diagrams";
+import { PluginPresentationAnnotateApi } from "./annotate";
 import { PluginPresentationImportApi } from "./import";
+import { PluginPresentationExportResult, type PluginPresentationExportFormat, type PluginPresentationExportResolution } from "./export";
 /**
  * Presentation APIs — prepare and assemble presentations.
  *
@@ -28,6 +31,8 @@ export declare abstract class PluginPresentationApi {
     abstract sheets: PluginPresentationSheetsApi;
     /** Program/adjacency/site diagrams — place images on sheets. See {@linkcode PluginPresentationDiagramsApi}. */
     abstract diagrams: PluginPresentationDiagramsApi;
+    /** Annotations on Present-mode sheets — text/arrows/notes/geo shapes. See {@linkcode PluginPresentationAnnotateApi}. */
+    abstract annotate: PluginPresentationAnnotateApi;
     /** Import reference images/PDFs onto the Present canvas. See {@linkcode PluginPresentationImportApi}. */
     abstract import: PluginPresentationImportApi;
     /**
@@ -35,11 +40,44 @@ export declare abstract class PluginPresentationApi {
      * {@linkcode PluginPresentationAIInspirationApi}.
      */
     abstract aiInspiration: PluginPresentationAIInspirationApi;
+    /**
+     * 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.
+     *
+     * @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).
+     * @throws If Present mode is not open, a `sheetId` is unknown, or a sheet
+     *   fails to serialize/encode.
+     *
+     * @examplePrompt Export the presentation as a PDF
+     * @examplePrompt Download all sheets as a single PDF
+     * @examplePrompt Export sheet 1 as a PNG
+     * @examplePrompt Save the presentation sheets as JPG images
+     * @examplePrompt Export these sheets to PDF at high resolution
+     *
+     * # Example
+     * ```ts
+     * const { files } = await snaptrude.presentation.export("pdf")
+     * ```
+     */
+    abstract export(format: PluginPresentationExportFormat, options?: {
+        sheetIds?: string[];
+        combine?: boolean;
+        resolution?: PluginPresentationExportResolution;
+        fileName?: string;
+    }): PluginApiReturn<PluginPresentationExportResult>;
     constructor();
 }
 export * from "./views";
 export * from "./sheets";
 export * from "./diagrams";
+export * from "./annotate";
 export * from "./import";
 export * from "./aiInspiration";
+export * from "./export";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/presentation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AACpD,OAAO,EAAE,kCAAkC,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,qBAAqB;IACzC,qEAAqE;IACrE,SAAgB,KAAK,EAAE,0BAA0B,CAAA;IACjD,mHAAmH;IACnH,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,+GAA+G;IAC/G,SAAgB,QAAQ,EAAE,6BAA6B,CAAA;IACvD,yGAAyG;IACzG,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD;;;OAGG;IACH,SAAgB,aAAa,EAAE,kCAAkC,CAAA;;CAGlE;AAED,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AACpD,OAAO,EAAE,kCAAkC,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EACL,8BAA8B,EAC9B,KAAK,8BAA8B,EACnC,KAAK,kCAAkC,EACxC,MAAM,UAAU,CAAA;AAEjB;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,qBAAqB;IACzC,qEAAqE;IACrE,SAAgB,KAAK,EAAE,0BAA0B,CAAA;IACjD,mHAAmH;IACnH,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD,+GAA+G;IAC/G,SAAgB,QAAQ,EAAE,6BAA6B,CAAA;IACvD,wHAAwH;IACxH,SAAgB,QAAQ,EAAE,6BAA6B,CAAA;IACvD,yGAAyG;IACzG,SAAgB,MAAM,EAAE,2BAA2B,CAAA;IACnD;;;OAGG;IACH,SAAgB,aAAa,EAAE,kCAAkC,CAAA;IAEjE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,MAAM,CACpB,MAAM,EAAE,8BAA8B,EACtC,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;QACnB,OAAO,CAAC,EAAE,OAAO,CAAA;QACjB,UAAU,CAAC,EAAE,kCAAkC,CAAA;QAC/C,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,GACA,eAAe,CAAC,8BAA8B,CAAC;;CAGnD;AAED,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,UAAU,CAAA"}