@snaptrude/plugin-core 0.7.1 → 0.8.0

package/src/api/entity/story.ts

@@ -102,21 +102,32 @@ export abstract class PluginStoryApi {
   ): PluginApiReturn<PluginStoryCreateResult>
 
   /**
-   * Update a story's floor-to-floor height, cascading the full geometry change.
+   * Update a story's floor-to-floor `height` and/or `name`.
    *
-   * This is the same operation as editing the height in the Stories panel: the
-   * walls, columns, and masses on the story are **stretched** to the new height,
-   * every story **above shifts up/down** by the delta so the stack stays
+   * **Height** is the same operation as editing the height in the Stories panel:
+   * the walls, columns, and masses on the story are **stretched** to the new
+   * height, every story **above shifts up/down** by the delta so the stack stays
    * contiguous, and coupled elements (staircases, parametric curtain walls,
-   * furniture offsets) are re-fitted. The whole cascade is committed as **one
-   * undo step**. Height-locked elements are left untouched.
+   * furniture offsets) are re-fitted. The whole height cascade is committed as
+   * **one undo step**. Height-locked elements are left untouched.
+   *
+   * **Name** is the same as renaming the story in the Stories panel: it is
+   * persisted immediately (saved to the project) but, mirroring the panel, is
+   * **not** part of the height undo step.
+   *
+   * At least one of `height` or `options.name` must be supplied. Omitting the
+   * `height` argument (e.g. for a rename-only update) leaves the height
+   * untouched.
    *
    * @param storyValue - Integer storey number
    *   identifying the story to update
    * @param height - New floor-to-floor height in
-   *   Babylon units
-   * @returns A {@linkcode PluginStoryUpdateResult} with the updated `storyValue` and `height`
+   *   Babylon units. Omit to leave the height unchanged.
+   * @param options - `name` (new display name for the story)
+   * @returns A {@linkcode PluginStoryUpdateResult} with the story's
+   *   `storyValue`, `height`, and `name` after the update
    * @throws `PRECONDITION_FAILED` if no story has the given value;
+   *   `VALIDATION` if neither `height` nor `options.name` is supplied;
    *   `STORY_HEIGHT_REJECTED` if the engine rejects the height (e.g. out of
    *   range — the change silently reverts host-side and is surfaced as this
    *   error); `STORY_UPDATE_FAILED` if the story cannot be re-read after the
@@ -124,21 +135,77 @@ export abstract class PluginStoryApi {
    *
    * @examplePrompt Change the ground floor height to 3.5 metres
    * @examplePrompt Make the second storey taller
+   * @examplePrompt Rename the ground floor to "Lobby"
    * @examplePrompt Set the floor-to-floor height of level 1
-   * @examplePrompt Increase the height of the third floor
+   * @examplePrompt Rename storey 2 and make it taller in one go
    *
    * # Example
    * ```ts
    * // Set ground floor height to 5 Babylon units — walls stretch and the
    * // floors above move up to match, all in a single undo step.
    * const result = await snaptrude.entity.story.update(1, 5)
+   * // Rename only, leaving the height untouched.
+   * await snaptrude.entity.story.update(1, undefined, { name: "Lobby" })
    * ```
    */
   public abstract update(
     storyValue: number,
-    height: number,
+    height?: number,
+    options?: { name?: string },
   ): PluginApiReturn<PluginStoryUpdateResult>
 
+  /**
+   * Make a story the active story — the same as clicking it in the storey/layer
+   * panel. Subsequent draws and creates target this story, and in 2D the
+   * viewport switches to it. This is a view/navigation change: it is **not**
+   * undoable and commits nothing to the model.
+   *
+   * @param storyValue - Integer storey number to activate
+   * @returns A {@linkcode PluginStorySetActiveResult} echoing the now-active `storyValue`
+   * @throws `PRECONDITION_FAILED` if no story has the given value
+   *
+   * @examplePrompt Switch to the second floor
+   * @examplePrompt Make the ground storey active
+   * @examplePrompt Go to the basement level
+   * @examplePrompt Set level 3 as the current storey
+   *
+   * # Example
+   * ```ts
+   * // Activate story 2, then draw a wall — it lands on story 2.
+   * await snaptrude.entity.story.setActive(2)
+   * ```
+   */
+  public abstract setActive(
+    storyValue: number,
+  ): PluginApiReturn<PluginStorySetActiveResult>
+
+  /**
+   * Delete a story and everything on it — the same as removing it from the
+   * storey panel. Every element placed on the story (walls, floors, masses, …)
+   * is deleted with it, the remaining stories are re-stacked, and the active
+   * story falls back to an adjacent one. Committed as a single undo step.
+   *
+   * @param storyValue - Integer storey number to delete
+   * @returns A {@linkcode PluginStoryDeleteResult} with the deleted `storyValue`
+   *   and the `newActiveStory` the editor fell back to
+   * @throws `PRECONDITION_FAILED` if no story has the given value; or if plugin
+   *   writes are disabled
+   *
+   * @examplePrompt Delete the top floor
+   * @examplePrompt Remove the basement level
+   * @examplePrompt Get rid of storey 3
+   * @examplePrompt Delete the second floor and everything on it
+   *
+   * # Example
+   * ```ts
+   * const { newActiveStory } = await snaptrude.entity.story.delete(3)
+   * console.log(`Deleted story 3; now on story ${newActiveStory}`)
+   * ```
+   */
+  public abstract delete(
+    storyValue: number,
+  ): PluginApiReturn<PluginStoryDeleteResult>
+
   /**
    * Duplicate a story into the adjacent level, up or down.
    *
@@ -301,35 +368,94 @@ export const PluginStoryCreateResult = z.object({
 export type PluginStoryCreateResult = z.infer<typeof PluginStoryCreateResult>
 
 /**
- * Arguments for {@linkcode PluginStoryApi.update}.
+ * Arguments for {@linkcode PluginStoryApi.update}. At least one of `height` or
+ * `name` must be supplied.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `storyValue` | `number` (int) | Storey number of the story to update |
- * | `height` | `number` | New height in Babylon units |
+ * | `height` | `number?` | New height in Babylon units (omit to leave unchanged) |
+ * | `name` | `string?` | New display name for the story (omit to leave unchanged) |
  */
 export const PluginStoryUpdateArgs = z.object({
   storyValue: z.number().int(),
-  height: z.number(),
+  height: z.number().optional(),
+  name: z.string().optional(),
 })
 
 export type PluginStoryUpdateArgs = z.infer<typeof PluginStoryUpdateArgs>
 
 /**
- * Result of {@linkcode PluginStoryApi.update}.
+ * Result of {@linkcode PluginStoryApi.update} — the story's state after the update.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `storyValue` | `number` | The storey number of the updated story |
- * | `height` | `number` | The new height after the update |
+ * | `height` | `number` | The height after the update |
+ * | `name` | `string` | The name after the update |
  */
 export const PluginStoryUpdateResult = z.object({
   storyValue: z.number(),
   height: z.number(),
+  name: z.string(),
 })
 
 export type PluginStoryUpdateResult = z.infer<typeof PluginStoryUpdateResult>
 
+/**
+ * Arguments for {@linkcode PluginStoryApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number to activate |
+ */
+export const PluginStorySetActiveArgs = z.object({
+  storyValue: z.number().int(),
+})
+
+export type PluginStorySetActiveArgs = z.infer<typeof PluginStorySetActiveArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` | The storey number that is now active |
+ */
+export const PluginStorySetActiveResult = z.object({
+  storyValue: z.number(),
+})
+
+export type PluginStorySetActiveResult = z.infer<typeof PluginStorySetActiveResult>
+
+/**
+ * Arguments for {@linkcode PluginStoryApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number to delete |
+ */
+export const PluginStoryDeleteArgs = z.object({
+  storyValue: z.number().int(),
+})
+
+export type PluginStoryDeleteArgs = z.infer<typeof PluginStoryDeleteArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` | The storey number that was deleted |
+ * | `newActiveStory` | `number` | The storey the editor fell back to as active |
+ */
+export const PluginStoryDeleteResult = z.object({
+  storyValue: z.number(),
+  newActiveStory: z.number(),
+})
+
+export type PluginStoryDeleteResult = z.infer<typeof PluginStoryDeleteResult>
+
 /**
  * Arguments for {@linkcode PluginStoryApi.duplicate} (options flattened).
  *

package/src/api/presentation/annotate.ts

@@ -0,0 +1,360 @@
+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 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.
+   *
+   * @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"`), and `color` (a named
+   *   palette color, default `"black"`).
+   * @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" },
+   * )
+   * ```
+   */
+  public abstract text(
+    sheetId: string,
+    text: string,
+    options?: {
+      position?: { x: number; y: number }
+      size?: PluginAnnotateTextSize
+      color?: PluginAnnotateTextColor
+    },
+  ): 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" },
+   * )
+   * ```
+   */
+  public 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" },
+   * )
+   * ```
+   */
+  public 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" },
+   * )
+   * ```
+   */
+  public 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 const PluginAnnotateTextSize = z.enum(["s", "m", "l", "xl"])
+export type PluginAnnotateTextSize = z.infer<typeof PluginAnnotateTextSize>
+
+/** Named palette color (the same swatches as the Present-mode style panel). */
+export const PluginAnnotateTextColor = z.enum([
+  "black",
+  "grey",
+  "light-violet",
+  "violet",
+  "blue",
+  "light-blue",
+  "yellow",
+  "orange",
+  "green",
+  "light-green",
+  "light-red",
+  "red",
+  "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 |
+ */
+export const PluginPresentationAnnotateTextArgs = z.object({
+  sheetId: z.string(),
+  text: z.string(),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+  size: PluginAnnotateTextSize.optional(),
+  color: PluginAnnotateTextColor.optional(),
+})
+export type PluginPresentationAnnotateTextArgs = z.infer<
+  typeof PluginPresentationAnnotateTextArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationAnnotateApi.text}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the created text shape |
+ */
+export const PluginPresentationAnnotateTextResult = z.object({
+  shapeId: z.string(),
+})
+export type PluginPresentationAnnotateTextResult = z.infer<
+  typeof PluginPresentationAnnotateTextResult
+>
+
+/**
+ * Geo shape kind — the shapes offered by the Present-mode toolbar's shape
+ * flyout.
+ */
+export const PluginAnnotateGeoKind = z.enum([
+  "rectangle",
+  "ellipse",
+  "triangle",
+  "diamond",
+  "hexagon",
+  "oval",
+  "rhombus",
+  "star",
+  "cloud",
+  "heart",
+  "x-box",
+  "check-box",
+  "arrow-left",
+  "arrow-up",
+  "arrow-right",
+  "arrow-down",
+])
+export type PluginAnnotateGeoKind = z.infer<typeof PluginAnnotateGeoKind>
+
+/** Fill style for geo shapes (the same fills as the Present-mode style panel). */
+export const PluginAnnotateFill = z.enum(["none", "semi", "solid", "pattern"])
+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 const PluginPresentationAnnotateArrowArgs = z.object({
+  sheetId: z.string(),
+  start: z.object({ x: z.number(), y: z.number() }),
+  end: z.object({ x: z.number(), y: z.number() }),
+  color: PluginAnnotateTextColor.optional(),
+  size: PluginAnnotateTextSize.optional(),
+})
+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 const PluginPresentationAnnotateNoteArgs = z.object({
+  sheetId: z.string(),
+  text: z.string(),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+  color: PluginAnnotateTextColor.optional(),
+  size: PluginAnnotateTextSize.optional(),
+})
+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 const PluginPresentationAnnotateShapeArgs = z.object({
+  sheetId: z.string(),
+  kind: PluginAnnotateGeoKind,
+  bounds: z.object({
+    x: z.number(),
+    y: z.number(),
+    w: z.number().positive(),
+    h: z.number().positive(),
+  }),
+  color: PluginAnnotateTextColor.optional(),
+  fill: PluginAnnotateFill.optional(),
+})
+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 const PluginPresentationAnnotateResult = z.object({
+  shapeId: z.string(),
+})
+export type PluginPresentationAnnotateResult = z.infer<
+  typeof PluginPresentationAnnotateResult
+>

package/src/api/presentation/diagrams.ts

@@ -2,23 +2,54 @@ 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 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()
+   * ```
+   */
+  public abstract generateProgram(): PluginApiReturn<PluginPresentationDiagramsGenerateResult>
+
   /**
    * Place diagram images onto a sheet.
    *
@@ -82,3 +113,17 @@ export const PluginPresentationDiagramsPlaceResult = z.object({
 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 const PluginPresentationDiagramsGenerateResult = z.object({
+  sheetIds: z.array(z.string()),
+})
+export type PluginPresentationDiagramsGenerateResult = z.infer<
+  typeof PluginPresentationDiagramsGenerateResult
+>