@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

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

@@ -0,0 +1,467 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Presentation annotate — add annotations to Present-mode sheets.
+ *
+ * The scriptable counterparts to the Present toolbar's annotation tools (all
+ * require Present mode to be open; each returns the created canvas shape id):
+ *
+ * - {@linkcode PluginPresentationAnnotateApi.text} — text labels (titles, captions)
+ * - {@linkcode PluginPresentationAnnotateApi.arrow} — arrows pointing between two points
+ * - {@linkcode PluginPresentationAnnotateApi.note} — sticky notes
+ * - {@linkcode PluginPresentationAnnotateApi.shape} — geo shapes (rectangle, ellipse, cloud, …)
+ *
+ * The freehand Draw tool is not scriptable (a stroke is an interactive gesture,
+ * not a single call) and is intentionally not exposed here.
+ *
+ * Accessed via `snaptrude.presentation.annotate`.
+ */
+export declare abstract class PluginPresentationAnnotateApi {
+    constructor();
+    /**
+     * Add a text label to a sheet.
+     *
+     * Creates a text shape on the given sheet and returns the id of the created
+     * canvas shape. Requires Present mode to be open.
+     *
+     * Typography is optional: `fontFamily` takes a system family or any Google
+     * Font (loaded automatically, the same loader as the Present text panel);
+     * `fontWeight` is a numeric weight string like `"400"` or `"700"`,
+     * optionally with the `-italic` suffix (e.g. `"700-italic"`) — the Present
+     * text panel's value domain; a weight the chosen font does not provide
+     * falls back to regular. `fontSizePx` sets an exact pixel size, overriding
+     * the `size` preset when both are given (`size` alone keeps working).
+     *
+     * @param sheetId - The sheet to annotate.
+     * @param text - The label text.
+     * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
+     *   top-left, in canvas units — defaults to the sheet's top-left corner),
+     *   `size` (`"s" | "m" | "l" | "xl"`, default `"m"`), `color` (a named
+     *   palette color, default `"black"`), and typography: `fontFamily`,
+     *   `fontWeight` (numeric string, `-italic` suffix allowed), `fontSizePx`
+     *   (positive px size overriding the `size` preset).
+     * @returns A {@linkcode PluginPresentationAnnotateTextResult} with the created
+     *   `shapeId`.
+     * @throws If Present mode is not open or the sheet id is invalid.
+     *
+     * @examplePrompt Add a title "Ground Floor" to Sheet 1
+     * @examplePrompt Label the cover sheet with the project name
+     * @examplePrompt Caption this view with "Proposed layout"
+     * @examplePrompt Put a red note on the sheet
+     *
+     * # Example
+     * ```ts
+     * const { shapeId } = await snaptrude.presentation.annotate.text(
+     *   "sheet_1",
+     *   "Ground Floor",
+     *   { position: { x: 40, y: 40 }, size: "xl", color: "blue" },
+     * )
+     * ```
+     */
+    abstract text(sheetId: string, text: string, options?: {
+        position?: {
+            x: number;
+            y: number;
+        };
+        size?: PluginAnnotateTextSize;
+        color?: PluginAnnotateTextColor;
+        fontFamily?: string;
+        fontWeight?: string;
+        fontSizePx?: number;
+    }): PluginApiReturn<PluginPresentationAnnotateTextResult>;
+    /**
+     * Draw an arrow on a sheet.
+     *
+     * Creates an arrow shape from `start` to `end` (both relative to the sheet's
+     * top-left, in canvas units — the same Arrow tool as the Present toolbar) and
+     * returns the id of the created canvas shape. Requires Present mode to be open.
+     *
+     * @param sheetId - The sheet to annotate.
+     * @param start - Arrow tail position (`{ x, y }`, relative to the sheet's top-left).
+     * @param end - Arrow head position (`{ x, y }`, relative to the sheet's top-left).
+     * @param options - Optional `color` (a named palette color, default `"black"`)
+     *   and `size` (stroke weight preset, `"s" | "m" | "l" | "xl"`, default `"m"`).
+     * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
+     *   `shapeId`.
+     * @throws If Present mode is not open or the sheet id is invalid.
+     *
+     * @examplePrompt Draw an arrow pointing at the entrance on Sheet 1
+     * @examplePrompt Add a red arrow from the title to the plan view
+     * @examplePrompt Point an arrow at the top-left view on the cover sheet
+     *
+     * # Example
+     * ```ts
+     * const { shapeId } = await snaptrude.presentation.annotate.arrow(
+     *   "sheet_1",
+     *   { x: 100, y: 200 },
+     *   { x: 300, y: 250 },
+     *   { color: "red" },
+     * )
+     * ```
+     */
+    abstract arrow(sheetId: string, start: {
+        x: number;
+        y: number;
+    }, end: {
+        x: number;
+        y: number;
+    }, options?: {
+        color?: PluginAnnotateTextColor;
+        size?: PluginAnnotateTextSize;
+    }): PluginApiReturn<PluginPresentationAnnotateResult>;
+    /**
+     * Add a sticky note to a sheet.
+     *
+     * Creates a note shape (the same Note tool as the Present toolbar — a
+     * fixed-size sticky square that grows with its text) and returns the id of
+     * the created canvas shape. Requires Present mode to be open.
+     *
+     * @param sheetId - The sheet to annotate.
+     * @param text - The note text.
+     * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
+     *   top-left, in canvas units — defaults to the sheet's top-left corner),
+     *   `color` (a named palette color, default `"black"` — rendered as the
+     *   note's sticky fill), and `size` (text size preset,
+     *   `"s" | "m" | "l" | "xl"`, default `"m"`).
+     * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
+     *   `shapeId`.
+     * @throws If Present mode is not open or the sheet id is invalid.
+     *
+     * @examplePrompt Add a sticky note "Review this wall" to Sheet 1
+     * @examplePrompt Put a yellow note on the cover sheet
+     * @examplePrompt Leave a note next to the ground floor plan
+     *
+     * # Example
+     * ```ts
+     * const { shapeId } = await snaptrude.presentation.annotate.note(
+     *   "sheet_1",
+     *   "Review this wall",
+     *   { position: { x: 60, y: 120 }, color: "yellow" },
+     * )
+     * ```
+     */
+    abstract note(sheetId: string, text: string, options?: {
+        position?: {
+            x: number;
+            y: number;
+        };
+        color?: PluginAnnotateTextColor;
+        size?: PluginAnnotateTextSize;
+    }): PluginApiReturn<PluginPresentationAnnotateResult>;
+    /**
+     * Draw a geo shape (rectangle, ellipse, cloud, …) on a sheet.
+     *
+     * Creates a geo shape of the given `kind` — the same shapes as the Present
+     * toolbar's shape flyout — sized to `bounds` (relative to the sheet's
+     * top-left, in canvas units) and returns the id of the created canvas shape.
+     * Requires Present mode to be open.
+     *
+     * @param sheetId - The sheet to annotate.
+     * @param kind - The shape kind ({@linkcode PluginAnnotateGeoKind}), e.g.
+     *   `"rectangle"`, `"ellipse"`, `"cloud"`.
+     * @param bounds - Placement box `{ x, y, w, h }` — `x`/`y` are the shape's
+     *   top-left relative to the sheet's top-left; `w`/`h` must be positive.
+     * @param options - Optional `color` (a named palette color, default
+     *   `"black"`) and `fill` ({@linkcode PluginAnnotateFill}, default `"none"` —
+     *   outline only).
+     * @returns A {@linkcode PluginPresentationAnnotateResult} with the created
+     *   `shapeId`.
+     * @throws If Present mode is not open or the sheet id is invalid.
+     *
+     * @examplePrompt Draw a revision cloud around the kitchen on Sheet 2
+     * @examplePrompt Add a red rectangle highlight to the sheet
+     * @examplePrompt Draw an ellipse around the entrance on the cover sheet
+     *
+     * # Example
+     * ```ts
+     * const { shapeId } = await snaptrude.presentation.annotate.shape(
+     *   "sheet_1",
+     *   "cloud",
+     *   { x: 80, y: 80, w: 240, h: 160 },
+     *   { color: "red" },
+     * )
+     * ```
+     */
+    abstract shape(sheetId: string, kind: PluginAnnotateGeoKind, bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }, options?: {
+        color?: PluginAnnotateTextColor;
+        fill?: PluginAnnotateFill;
+    }): PluginApiReturn<PluginPresentationAnnotateResult>;
+}
+/** Text size preset (the same s/m/l/xl scale as the Present-mode text tool). */
+export declare const PluginAnnotateTextSize: z.ZodEnum<{
+    m: "m";
+    s: "s";
+    l: "l";
+    xl: "xl";
+}>;
+export type PluginAnnotateTextSize = z.infer<typeof PluginAnnotateTextSize>;
+/** Named palette color (the same swatches as the Present-mode style panel). */
+export declare const PluginAnnotateTextColor: z.ZodEnum<{
+    black: "black";
+    grey: "grey";
+    "light-violet": "light-violet";
+    violet: "violet";
+    blue: "blue";
+    "light-blue": "light-blue";
+    yellow: "yellow";
+    orange: "orange";
+    green: "green";
+    "light-green": "light-green";
+    "light-red": "light-red";
+    red: "red";
+    white: "white";
+}>;
+export type PluginAnnotateTextColor = z.infer<typeof PluginAnnotateTextColor>;
+/**
+ * Arguments for {@linkcode PluginPresentationAnnotateApi.text}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to annotate |
+ * | `text` | `string` | The label text |
+ * | `position` | `{ x: number; y: number } \| undefined` | Where to place it (relative to the sheet) |
+ * | `size` | {@linkcode PluginAnnotateTextSize}` \| undefined` | Text size preset |
+ * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Text color |
+ * | `fontFamily` | `string \| undefined` | System family or any Google Font (loaded automatically) |
+ * | `fontWeight` | `string \| undefined` | Numeric weight like `"400"`/`"700"`, `-italic` suffix allowed |
+ * | `fontSizePx` | `number \| undefined` | Exact px size (overrides the `size` preset) |
+ */
+export declare const PluginPresentationAnnotateTextArgs: z.ZodObject<{
+    sheetId: z.ZodString;
+    text: z.ZodString;
+    position: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        m: "m";
+        s: "s";
+        l: "l";
+        xl: "xl";
+    }>>;
+    color: z.ZodOptional<z.ZodEnum<{
+        black: "black";
+        grey: "grey";
+        "light-violet": "light-violet";
+        violet: "violet";
+        blue: "blue";
+        "light-blue": "light-blue";
+        yellow: "yellow";
+        orange: "orange";
+        green: "green";
+        "light-green": "light-green";
+        "light-red": "light-red";
+        red: "red";
+        white: "white";
+    }>>;
+    fontFamily: z.ZodOptional<z.ZodString>;
+    fontWeight: z.ZodOptional<z.ZodString>;
+    fontSizePx: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginPresentationAnnotateTextArgs = z.infer<typeof PluginPresentationAnnotateTextArgs>;
+/**
+ * Result of {@linkcode PluginPresentationAnnotateApi.text}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the created text shape |
+ */
+export declare const PluginPresentationAnnotateTextResult: z.ZodObject<{
+    shapeId: z.ZodString;
+}, z.core.$strip>;
+export type PluginPresentationAnnotateTextResult = z.infer<typeof PluginPresentationAnnotateTextResult>;
+/**
+ * Geo shape kind — the shapes offered by the Present-mode toolbar's shape
+ * flyout.
+ */
+export declare const PluginAnnotateGeoKind: z.ZodEnum<{
+    rectangle: "rectangle";
+    ellipse: "ellipse";
+    triangle: "triangle";
+    diamond: "diamond";
+    hexagon: "hexagon";
+    oval: "oval";
+    rhombus: "rhombus";
+    star: "star";
+    cloud: "cloud";
+    heart: "heart";
+    "x-box": "x-box";
+    "check-box": "check-box";
+    "arrow-left": "arrow-left";
+    "arrow-up": "arrow-up";
+    "arrow-right": "arrow-right";
+    "arrow-down": "arrow-down";
+}>;
+export type PluginAnnotateGeoKind = z.infer<typeof PluginAnnotateGeoKind>;
+/** Fill style for geo shapes (the same fills as the Present-mode style panel). */
+export declare const PluginAnnotateFill: z.ZodEnum<{
+    pattern: "pattern";
+    solid: "solid";
+    none: "none";
+    semi: "semi";
+}>;
+export type PluginAnnotateFill = z.infer<typeof PluginAnnotateFill>;
+/**
+ * Arguments for {@linkcode PluginPresentationAnnotateApi.arrow}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to annotate |
+ * | `start` | `{ x: number; y: number }` | Arrow tail (relative to the sheet) |
+ * | `end` | `{ x: number; y: number }` | Arrow head (relative to the sheet) |
+ * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Arrow color |
+ * | `size` | {@linkcode PluginAnnotateTextSize}` \| undefined` | Stroke weight preset |
+ */
+export declare const PluginPresentationAnnotateArrowArgs: z.ZodObject<{
+    sheetId: z.ZodString;
+    start: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    end: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodEnum<{
+        black: "black";
+        grey: "grey";
+        "light-violet": "light-violet";
+        violet: "violet";
+        blue: "blue";
+        "light-blue": "light-blue";
+        yellow: "yellow";
+        orange: "orange";
+        green: "green";
+        "light-green": "light-green";
+        "light-red": "light-red";
+        red: "red";
+        white: "white";
+    }>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        m: "m";
+        s: "s";
+        l: "l";
+        xl: "xl";
+    }>>;
+}, z.core.$strip>;
+export type PluginPresentationAnnotateArrowArgs = z.infer<typeof PluginPresentationAnnotateArrowArgs>;
+/**
+ * Arguments for {@linkcode PluginPresentationAnnotateApi.note}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to annotate |
+ * | `text` | `string` | The note text |
+ * | `position` | `{ x: number; y: number } \| undefined` | Where to place it (relative to the sheet) |
+ * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Sticky fill color |
+ * | `size` | {@linkcode PluginAnnotateTextSize}` \| undefined` | Text size preset |
+ */
+export declare const PluginPresentationAnnotateNoteArgs: z.ZodObject<{
+    sheetId: z.ZodString;
+    text: z.ZodString;
+    position: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    color: z.ZodOptional<z.ZodEnum<{
+        black: "black";
+        grey: "grey";
+        "light-violet": "light-violet";
+        violet: "violet";
+        blue: "blue";
+        "light-blue": "light-blue";
+        yellow: "yellow";
+        orange: "orange";
+        green: "green";
+        "light-green": "light-green";
+        "light-red": "light-red";
+        red: "red";
+        white: "white";
+    }>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        m: "m";
+        s: "s";
+        l: "l";
+        xl: "xl";
+    }>>;
+}, z.core.$strip>;
+export type PluginPresentationAnnotateNoteArgs = z.infer<typeof PluginPresentationAnnotateNoteArgs>;
+/**
+ * Arguments for {@linkcode PluginPresentationAnnotateApi.shape}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to annotate |
+ * | `kind` | {@linkcode PluginAnnotateGeoKind} | The shape kind |
+ * | `bounds` | `{ x: number; y: number; w: number; h: number }` | Placement box (relative to the sheet; `w`/`h` positive) |
+ * | `color` | {@linkcode PluginAnnotateTextColor}` \| undefined` | Outline color |
+ * | `fill` | {@linkcode PluginAnnotateFill}` \| undefined` | Fill style |
+ */
+export declare const PluginPresentationAnnotateShapeArgs: z.ZodObject<{
+    sheetId: z.ZodString;
+    kind: z.ZodEnum<{
+        rectangle: "rectangle";
+        ellipse: "ellipse";
+        triangle: "triangle";
+        diamond: "diamond";
+        hexagon: "hexagon";
+        oval: "oval";
+        rhombus: "rhombus";
+        star: "star";
+        cloud: "cloud";
+        heart: "heart";
+        "x-box": "x-box";
+        "check-box": "check-box";
+        "arrow-left": "arrow-left";
+        "arrow-up": "arrow-up";
+        "arrow-right": "arrow-right";
+        "arrow-down": "arrow-down";
+    }>;
+    bounds: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodEnum<{
+        black: "black";
+        grey: "grey";
+        "light-violet": "light-violet";
+        violet: "violet";
+        blue: "blue";
+        "light-blue": "light-blue";
+        yellow: "yellow";
+        orange: "orange";
+        green: "green";
+        "light-green": "light-green";
+        "light-red": "light-red";
+        red: "red";
+        white: "white";
+    }>>;
+    fill: z.ZodOptional<z.ZodEnum<{
+        pattern: "pattern";
+        solid: "solid";
+        none: "none";
+        semi: "semi";
+    }>>;
+}, z.core.$strip>;
+export type PluginPresentationAnnotateShapeArgs = z.infer<typeof PluginPresentationAnnotateShapeArgs>;
+/**
+ * Result of {@linkcode PluginPresentationAnnotateApi.arrow},
+ * {@linkcode PluginPresentationAnnotateApi.note}, and
+ * {@linkcode PluginPresentationAnnotateApi.shape}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the created canvas shape |
+ */
+export declare const PluginPresentationAnnotateResult: z.ZodObject<{
+    shapeId: z.ZodString;
+}, z.core.$strip>;
+export type PluginPresentationAnnotateResult = z.infer<typeof PluginPresentationAnnotateResult>;
+//# sourceMappingURL=annotate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/annotate.ts"],"names":[],"mappings":"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"}

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

@@ -1,22 +1,91 @@
 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.generateSite} runs the site-diagram
+ * flow (location / streetview / climate sheets from the map terrain).
+ * {@linkcode PluginPresentationDiagramsApi.place} drops ready diagram images (by
+ * URL) onto an existing sheet and returns the created canvas shape ids. All
+ * 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>;
+    /**
+     * Generate the site diagrams (location, streetview, climate) for the
+     * current model, creating new layout sheets.
+     *
+     * Runs the same auto-generation as the Present-mode site-diagram flow:
+     * each requested type renders its diagram from the project's map terrain
+     * and creates a new sheet holding it. `options.types` selects which
+     * diagrams to generate (default: all three). Generation is tracked
+     * per-proposal — a type whose diagram already exists for the active
+     * proposal is **skipped, not duplicated** (the same semantics as the
+     * mount-time flow; existing site-diagram sheets are never replaced), so
+     * `sheetIds` contains only the sheets created by this call and can be
+     * empty when everything already exists. Requires Present mode to be open
+     * and the project to have a map terrain to generate from.
+     *
+     * @param options - Optional `types` — which site diagrams to generate
+     *   (default: `["location", "streetview", "climate"]`).
+     * @returns A {@linkcode PluginPresentationDiagramsGenerateResult} with the
+     *   `sheetIds` of the sheets created by this call (empty when all requested
+     *   types were already generated).
+     * @throws If Present mode is not open or the project has no map terrain to
+     *   generate from.
+     *
+     * @examplePrompt Generate the site diagrams for this project
+     * @examplePrompt Create the location, streetview and climate sheets
+     * @examplePrompt Add a climate diagram sheet to the presentation
+     *
+     * # Example
+     * ```ts
+     * const { sheetIds } = await snaptrude.presentation.diagrams.generateSite({
+     *   types: ["location", "climate"],
+     * })
+     * ```
+     */
+    abstract generateSite(options?: {
+        types?: PluginPresentationSiteDiagramType[];
+    }): PluginApiReturn<PluginPresentationDiagramsGenerateResult>;
     /**
      * Place diagram images onto a sheet.
      *
@@ -78,4 +147,38 @@ export declare const PluginPresentationDiagramsPlaceResult: z.ZodObject<{
     shapeIds: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type PluginPresentationDiagramsPlaceResult = z.infer<typeof PluginPresentationDiagramsPlaceResult>;
+/** A site diagram type — the three diagrams of the Present-mode site flow. */
+export declare const PluginPresentationSiteDiagramType: z.ZodEnum<{
+    location: "location";
+    streetview: "streetview";
+    climate: "climate";
+}>;
+export type PluginPresentationSiteDiagramType = z.infer<typeof PluginPresentationSiteDiagramType>;
+/**
+ * Arguments for {@linkcode PluginPresentationDiagramsApi.generateSite}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `types` | {@linkcode PluginPresentationSiteDiagramType}`[] \| undefined` | Which site diagrams to generate (default: all three) |
+ */
+export declare const PluginPresentationDiagramsGenerateSiteArgs: z.ZodObject<{
+    types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        location: "location";
+        streetview: "streetview";
+        climate: "climate";
+    }>>>;
+}, z.core.$strip>;
+export type PluginPresentationDiagramsGenerateSiteArgs = z.infer<typeof PluginPresentationDiagramsGenerateSiteArgs>;
+/**
+ * Result of {@linkcode PluginPresentationDiagramsApi.generateProgram} and
+ * {@linkcode PluginPresentationDiagramsApi.generateSite}.
+ *
+ * | 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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,6BAA6B;;IAGjD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,eAAe,IAAI,eAAe,CAAC,wCAAwC,CAAC;IAE5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;aACa,YAAY,CAAC,OAAO,CAAC,EAAE;QACrC,KAAK,CAAC,EAAE,iCAAiC,EAAE,CAAA;KAC5C,GAAG,eAAe,CAAC,wCAAwC,CAAC;IAE7D;;;;;;;;;;;;;;;;;;;;;;;;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,8EAA8E;AAC9E,eAAO,MAAM,iCAAiC;;;;EAI5C,CAAA;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CACrD,OAAO,iCAAiC,CACzC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0CAA0C;;;;;;iBAErD,CAAA;AACF,MAAM,MAAM,0CAA0C,GAAG,CAAC,CAAC,KAAK,CAC9D,OAAO,0CAA0C,CAClD,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wCAAwC;;iBAEnD,CAAA;AACF,MAAM,MAAM,wCAAwC,GAAG,CAAC,CAAC,KAAK,CAC5D,OAAO,wCAAwC,CAChD,CAAA"}