@snaptrude/plugin-core 0.9.14 → 0.9.16-networks-20261008.1

package/src/api/design/types/index.ts

@@ -1,23 +1,25 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 
+/** An exact saved native wall family. Access is checked on every use; Draw selection is not registration. */
+export const PluginNativeWallType = z.object({
+  id: z.string().min(1),
+  version: z.number().int().positive(),
+})
+export type PluginNativeWallType = z.infer<typeof PluginNativeWallType>
+
+/** Legacy project type name/id, or an exact authorized native wall family pin. */
+export const PluginWallType = z.union([z.string().trim().min(1), PluginNativeWallType])
+export type PluginWallType = z.infer<typeof PluginWallType>
+
 /**
- * `snaptrude.design.types` — READ-ONLY reference over the project's building
- * **type / assembly** system (the Project Properties layer stacks: External /
- * Internal walls, slabs, floors, ceilings, roofs). A type bundles a labelled
- * layer stack — each layer's role, thickness (engine units) and material — plus a
- * summed total thickness. Both the built-in defaults and any team/user-added types
- * are surfaced.
- *
- * Types are plain value records ({@linkcode PluginBuildingType}) — NOT scene
- * entities/handles. A type's `id` is a stable `"<kind>:<name>"` token
- * (e.g. `"wall:brickWithPlasterAndPaint"`) returned by
- * {@linkcode PluginDesignTypesApi.list} and consumed by
- * {@linkcode PluginDesignTypesApi.get}. Reads never throw — an unknown id yields
- * `null`; a kind with no types yields `[]`.
- *
- * These are reads only: there is no engine seam to author a type from a plugin
- * (types are created through the construction/project-properties UI).
+ * Read-only project assemblies and authorized saved native wall families.
+ * Legacy ids use `"<kind>:<name>"`. Native wall records carry `nativeFamily`:
+ * pass that exact `{ id, version }` pin to get, create.walls, create.wallRuns,
+ * or update.wall. Labels and bare definition ids do not select native families.
+ * Native lengths use Snaptrude units (1 SU = 254 mm).
+ * Missing ids return null; catalog/network failures reject rather than return
+ * an incomplete catalog. Author native families with design.family.
  */
 export abstract class PluginDesignTypesApi {
   constructor() {}
@@ -46,10 +48,10 @@ export abstract class PluginDesignTypesApi {
   ): PluginApiReturn<PluginBuildingTypeSummary[]>
 
   /**
-   * Get one building type by its `"<kind>:<name>"` id — its labelled layer stack
+   * Get one building type by its legacy id or exact native wall pin — its labelled layer stack
    * (each layer's role, thickness and material) plus the summed total thickness.
    *
-   * @param typeId The type id from {@linkcode PluginDesignTypesApi.list} (e.g. `"wall:exposedConcrete"`)
+   * @param typeId The legacy id or nativeFamily pin from {@linkcode PluginDesignTypesApi.list}
    * @returns The full type, or `null` if no type matches
    *
    * @examplePrompt What layers make up this wall type?
@@ -60,11 +62,11 @@ export abstract class PluginDesignTypesApi {
    * # Example
    * ```ts
    * const [first] = await snaptrude.design.types.list("wall")
-   * const type = await snaptrude.design.types.get(first.id)
+   * const type = await snaptrude.design.types.get(first.nativeFamily ?? first.id)
    * if (type) for (const layer of type.layers) console.log(layer.name, layer.thickness)
    * ```
    */
-  public abstract get(typeId: string): PluginApiReturn<PluginBuildingType | null>
+  public abstract get(typeId: PluginWallType): PluginApiReturn<PluginBuildingType | null>
 }
 
 /** The building-type families exposed by {@linkcode PluginDesignTypesApi}. */
@@ -85,6 +87,8 @@ export const PluginTypeLayer = z.object({
   name: z.string(),
   role: z.string(),
   thickness: z.number(),
+  /** Native authored core membership. Never inferred from material or layer name. */
+  isCore: z.boolean().optional(),
   material: z
     .object({
       name: z.string(),
@@ -99,7 +103,7 @@ export type PluginTypeLayer = z.infer<typeof PluginTypeLayer>
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `id` | `string` | Stable `"<kind>:<name>"` token — pass to `design.types.get` |
+ * | `id` | `string` | Legacy `"<kind>:<name>"` token or native definition id; native lookups use `nativeFamily` |
  * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
  * | `label` | `string` | Human-readable label |
  * | `isDefault` | `boolean` | `true` for a built-in type, `false` for a team/user type |
@@ -111,6 +115,8 @@ export const PluginBuildingTypeSummary = z.object({
   label: z.string(),
   isDefault: z.boolean(),
   thickness: z.number(),
+  /** Present for native walls. Pass the whole pin to get/create/update, not its label or bare id. */
+  nativeFamily: PluginNativeWallType.optional(),
 })
 export type PluginBuildingTypeSummary = z.infer<typeof PluginBuildingTypeSummary>
 
@@ -119,7 +125,7 @@ export type PluginBuildingTypeSummary = z.infer<typeof PluginBuildingTypeSummary
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `id` | `string` | Stable `"<kind>:<name>"` token |
+ * | `id` | `string` | Legacy type token or native definition id |
  * | `kind` | {@linkcode PluginBuildingTypeKind} | Which family it belongs to |
  * | `label` | `string` | Human-readable label |
  * | `isDefault` | `boolean` | `true` for a built-in type |
@@ -148,9 +154,10 @@ export type PluginDesignTypesListArgs = z.infer<typeof PluginDesignTypesListArgs
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `typeId` | `string` | The `"<kind>:<name>"` id from `design.types.list` |
+ * | `typeId` | {@linkcode PluginWallType} | A legacy `"<kind>:<name>"` id or exact `nativeFamily` pin from `design.types.list` |
  */
 export const PluginDesignTypesGetArgs = z.object({
-  typeId: z.string(),
+  // Preserve legacy lookup behavior: malformed string ids return null in the host.
+  typeId: z.union([z.string(), PluginNativeWallType]),
 })
 export type PluginDesignTypesGetArgs = z.infer<typeof PluginDesignTypesGetArgs>

package/src/api/design/update/index.ts

@@ -9,7 +9,10 @@ import {
   PluginSpaceUpdateResult,
 } from "../../entity/space"
 import { PluginDesignChangeResult } from "../lock"
-import { MassParametersPatch, type MassParametersRecord } from "../../../massParameters"
+import {
+  MassParametersPatch,
+  type MassParametersRecord,
+} from "../../../massParameters"
 import {
   PluginBuildableEnvelopePolygonVertex,
   PluginBuildableEnvelopeSetbackTier,
@@ -17,6 +20,13 @@ import {
   PluginBuildableEnvelopeUpdateResult,
 } from "../../entity/buildableEnvelope"
 import { PluginGridStyleOptions } from "../create/grids"
+import { PluginEntityType } from "../query"
+import { PluginWallType } from "../types"
+import {
+  PluginConstructionType,
+  PluginFamilyValues,
+  type PluginFamilyUpdates,
+} from "../catalog"
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -164,13 +174,14 @@ export type PluginDesignUpdateParametersArgs = z.infer<
  * |---|---|---|
  * | `thickness` | `number`? | Wall thickness, engine units (> 0) |
  * | `height` | `number`? | Wall height, engine units (> 0) |
- * | `type` | `string`? | Convert the wall to another wall type — a name (or `wall:`-prefixed id) from `design.types.list("wall")` |
+ * | `type` | {@linkcode PluginWallType}? | Legacy name/id or exact authorized native `{ id, version }` pin from `design.types.list("wall")` |
  */
 export const PluginWallUpdates = z
   .object({
     thickness: z.number().positive().optional(),
     height: z.number().positive().optional(),
-    type: z.string().trim().min(1).optional(),
+    type: PluginWallType.optional(),
+    values: PluginFamilyValues.optional(),
   })
   .refine((p) => Object.keys(p).length > 0, {
     message: "PluginWallUpdates requires at least one field to change",
@@ -195,6 +206,8 @@ export const PluginSlabUpdates = z
   .object({
     thickness: z.number().positive().optional(),
     overhang: z.number().optional(),
+    type: PluginConstructionType.optional(),
+    values: PluginFamilyValues.optional(),
   })
   .refine((p) => Object.keys(p).length > 0, {
     message: "PluginSlabUpdates requires at least one field to change",
@@ -256,6 +269,34 @@ export type PluginDesignSetStoreyArgs = z.infer<
   typeof PluginDesignSetStoreyArgs
 >
 
+/**
+ * Object types {@linkcode PluginDesignUpdateApi.setObjectType} can turn a mass
+ * into — the `design.query` `type` vocabulary.
+ */
+export const PluginObjectType = PluginEntityType.extract([
+  "wall",
+  "roof",
+  "slab",
+  "floor",
+])
+export type PluginObjectType = z.infer<typeof PluginObjectType>
+
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.setObjectType}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The masses to convert (>= 1) |
+ * | `objectType` | {@linkcode PluginObjectType} | Target object type (`"wall"`, `"roof"`, `"slab"`, `"floor"`) |
+ */
+export const PluginDesignSetObjectTypeArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  objectType: PluginObjectType,
+})
+export type PluginDesignSetObjectTypeArgs = z.infer<
+  typeof PluginDesignSetObjectTypeArgs
+>
+
 /**
  * The sparse GROUP-LEVEL patch accepted by {@linkcode PluginDesignUpdateApi.grid}.
  * Only provided fields change. Wing- and line-level updates live on the grids
@@ -275,13 +316,20 @@ export const PluginDesignUpdateGridArgs = z.object({
   grid: ComponentHandle,
   patch: PluginGridPatch,
 })
-export type PluginDesignUpdateGridArgs = z.infer<typeof PluginDesignUpdateGridArgs>
+export type PluginDesignUpdateGridArgs = z.infer<
+  typeof PluginDesignUpdateGridArgs
+>
 
 /**
  * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
  *
  * Migrated from the removed `entity.space.{update, updateGeometryFromProfile, bulkUpdate}`.
  * Only provided fields change; each call is undoable. Failures throw (RPC rejects).
+ *
+ * Native family edits accept `type` and/or sparse `values` from `design.catalog`.
+ * Length overrides use mm; dimensional arguments use SU. Contours and axes stay unchanged.
+ * Shared/type overrides are refused. A thickness argument must agree with the layer values.
+ * Family roof overhang is unsupported; use the native slab path for family overhang edits.
  */
 export abstract class PluginDesignUpdateApi {
   constructor() {}
@@ -535,6 +583,9 @@ export abstract class PluginDesignUpdateApi {
    *   chamfer (the kernel numbers its faces differently): send the twist/taper
    *   keys with `operations: []` first (the message names them), re-select on
    *   the new shape, then send `{ operations }` back.
+   *   Graph-bound spaces accept amount-only extrusion edits. Footprint, twist,
+   *   taper and operation edits require the owning boundary tools, so generated
+   *   walls, junctions and hosted openings remain synchronized.
    * @throws VALIDATION for a key the kind does not have (the message lists the
    *   kind's keys), `kind` or `version` in a partial patch, or a value outside
    *   the constructor's own rules (torus tube ≥ ring, revolution angle ∉
@@ -742,6 +793,24 @@ export abstract class PluginDesignUpdateApi {
     updates: PluginSlabUpdates,
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /** Replace a native beam family while preserving its authored axis. Values use mm/degrees.
+   * @param component Native beam. @param updates Saved family reference and optional instance values.
+   * @returns Affected component IDs. One undoable operation; unsupported geometry fails before mutation.
+   */
+  public abstract beam(
+    component: ComponentHandle,
+    updates: PluginFamilyUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /** Replace a native column family while preserving its authored axis. Values use mm/degrees.
+   * @param component Native column. @param updates Saved family reference and optional instance values.
+   * @returns Affected component IDs. One undoable operation; unsupported geometry fails before mutation.
+   */
+  public abstract column(
+    component: ComponentHandle,
+    updates: PluginFamilyUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
   /**
    * Set a component's **absolute world elevation** — moves it vertically so its
    * base (the bounding-box bottom, world Y) lands at `elevation`. Composed over
@@ -849,6 +918,54 @@ export abstract class PluginDesignUpdateApi {
     storey: number,
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /**
+   * Change the **object type** of one or more masses — turn a mass into a real
+   * wall, roof, slab or floor: the properties panel's Object Type dropdown,
+   * headless. The geometry is kept exactly as it is (a wedge stays a wedge;
+   * nothing is flattened to a default thickness), so a sloped mass built with
+   * `design.create.massFromBrep` becomes a sloped roof or a raked wall. The
+   * component keeps its handle, label and storey; it gains the target type's
+   * construction layers and properties, and the type's default material when
+   * the mass still wore the default. One undoable operation for the whole
+   * list; undo turns them back into masses.
+   *
+   * Instances convert as a family: passing one instance (or the source) of an
+   * instanced mass converts its source and every sibling; `affected` echoes
+   * every visible member (the hidden instancing template converts too but is
+   * not listed). A converted component cannot be converted again (same rule
+   * as the panel). A converted wall has no parametric centerline: it hosts
+   * doors and windows and exports, but neighbours do not re-mitre against it.
+   *
+   * Throws before anything changes (all-or-nothing) when a component is not a
+   * mass, is a plinth, is locked or in a locked bucket, already had its type
+   * changed, or when a handle is gone/forged.
+   *
+   * @param components - The masses to convert
+   * @param objectType - Target type: `"wall"`, `"roof"`, `"slab"` or `"floor"`
+   *   (the `design.query.getEntityType` vocabulary)
+   * @returns the visible components converted — the same handles, plus any
+   *   instance siblings pulled in by family expansion
+   *
+   * @examplePrompt Convert this mass into a wall
+   * @examplePrompt Turn the sloped mass into a roof
+   * @examplePrompt Make these masses real slabs
+   * @examplePrompt Change the object type of the selection to wall
+   * @examplePrompt Convert the wedge I built into a raked wall
+   * @examplePrompt Turn this mass into a floor
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromFaces(wedgeFaces)
+   * const wedge = await snaptrude.design.create.massFromBrep(brep, "Gable end")
+   * const { affected } = await snaptrude.design.update.setObjectType([wedge], "wall")
+   * console.log(await snaptrude.design.query.getEntityType(affected[0])) // "wall"
+   * ```
+   */
+  public abstract setObjectType(
+    components: ComponentHandle[],
+    objectType: PluginObjectType,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
   /**
    * Update an existing parametric buildable envelope — regenerate the zoning
    * volume from a revised site polygon, setbacks, vertical cap, or FAR and

package/src/api/presentation/camera.ts

@@ -0,0 +1,289 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginPresentationImageFormat } from "./views"
+
+/**
+ * The Present-mode canvas camera — the Present-mode twin of
+ * {@linkcode PluginCameraApi} (`core.camera`).
+ *
+ * Present mode lays sheets out on an infinite 2D canvas; its camera is a pan
+ * (`x`, `y`) and a `zoom`. A plugin can screenshot what that canvas currently
+ * shows, read the camera, pan/zoom it, or frame all sheets or one shape.
+ *
+ * These are transient VIEW-STATE changes: not model edits, so they are not
+ * write-gated and not undoable. Every method requires **Present mode to be
+ * open** (the documentation editor) and throws `PRECONDITION_FAILED` when it is
+ * closed. `capture` is the Present-mode counterpart of
+ * {@linkcode PluginPresentationViewsApi.capture}, which shoots the Design
+ * (3D) canvas; for whole sheets at their own size use
+ * {@linkcode PluginPresentationApi.export}.
+ *
+ * Coordinates are Present canvas page units (pixels at 100% zoom), the same
+ * space `sheets`, `placedViews` and `shapes` report positions in. `zoom` is a
+ * factor: `1` = 100%, `0.5` = zoomed out to half size.
+ *
+ * Accessed via `snaptrude.presentation.camera`.
+ */
+export abstract class PluginPresentationCameraApi {
+  constructor() {}
+
+  /**
+   * Screenshot what the Present canvas currently shows.
+   *
+   * Captures exactly the visible area — the canvas as clipped by the window,
+   * minus the strip under the floating left sidebar — at the current pan and
+   * zoom, rendered
+   * through the same pipeline as the Present-mode Export dialog, so sheets,
+   * placed views, text, annotations and imported images look as they do on
+   * screen. Selection handles, cursors and the UI itself are not part of the
+   * image. Nothing on screen still yields an image (the export backdrop).
+   * Export-pipeline details, as in the Export dialog: sheet frames themselves
+   * are not drawn (no paper, margin guides or name label — editor chrome), the
+   * backdrop is tldraw's near-white export backdrop rather than the on-screen
+   * canvas grey, and with exactly one sheet in view it is white. Only the left
+   * sidebar is subtracted from the view; floating right-hand panels are not.
+   *
+   * @param options - All optional: `format` (`"png"` default, or `"jpeg"`),
+   *   `pixelRatio` (output pixels per screen pixel, `1`–`4`, default `1`;
+   *   `2` for a retina-sharp image).
+   * @returns A {@linkcode PluginPresentationCameraCaptureResult}: the base64
+   *   data URL and its pixel size.
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Take a screenshot of the Present canvas
+   * @examplePrompt Capture what I am looking at in Present mode
+   * @examplePrompt Screenshot the presentation canvas as a JPEG
+   * @examplePrompt Grab a high-res image of the current sheet view
+   *
+   * # Example
+   * ```ts
+   * const { image, width, height } = await snaptrude.presentation.camera.capture({
+   *   format: "png",
+   *   pixelRatio: 2,
+   * })
+   * ```
+   */
+  public abstract capture(options?: {
+    format?: PluginPresentationImageFormat
+    pixelRatio?: number
+  }): PluginApiReturn<PluginPresentationCameraCaptureResult>
+
+  /**
+   * Read the Present camera: pan, zoom, the visible page-space rectangle and
+   * the sheet under the centre of the view.
+   *
+   * @returns The current {@linkcode PluginPresentationCameraState}.
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Where is the Present canvas camera?
+   * @examplePrompt What zoom level is Present mode at?
+   * @examplePrompt Which sheet is on screen right now?
+   * @examplePrompt Read the visible area of the presentation canvas
+   *
+   * # Example
+   * ```ts
+   * const { zoom, sheetId } = await snaptrude.presentation.camera.get()
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginPresentationCameraState>
+
+  /**
+   * Pan and/or zoom the Present canvas. Fields left out keep their current
+   * value, so `{ zoom: 2 }` changes only the zoom (the page point at the
+   * viewport's top-left corner stays put) and `{ x, y }` pans at the current
+   * zoom. `zoom` is clamped to the editor's range (1% to 1000%); the requested
+   * `x`/`y` are always honoured. Immediate (no animation). View-state only —
+   * not undoable.
+   *
+   * `x`/`y` are the camera offset in page units: the page point that lands at
+   * the viewport's top-left corner is `(-x, -y)`. Read them back from
+   * {@linkcode PluginPresentationCameraApi.get} to reproduce a framing later.
+   *
+   * @param camera - Any of `x`, `y`, `zoom` ({@linkcode PluginPresentationCameraSetArgs}); at least one.
+   * @returns The resulting {@linkcode PluginPresentationCameraState}.
+   * @throws If Present mode is not open, or another Present-mode control has
+   *   locked the camera (an open style dropdown, AI Inspiration's layout mode).
+   *
+   * @examplePrompt Zoom the Present canvas to 50%
+   * @examplePrompt Pan the presentation canvas to the right
+   * @examplePrompt Restore the Present camera I saved earlier
+   * @examplePrompt Set the Present zoom to 200% without moving
+   *
+   * # Example
+   * ```ts
+   * const saved = await snaptrude.presentation.camera.get()
+   * await snaptrude.presentation.camera.set({ zoom: 0.5 })
+   * // …later, restore the exact framing
+   * await snaptrude.presentation.camera.set({ x: saved.x, y: saved.y, zoom: saved.zoom })
+   * ```
+   */
+  public abstract set(camera: {
+    x?: number
+    y?: number
+    zoom?: number
+  }): PluginApiReturn<PluginPresentationCameraState>
+
+  /**
+   * Frame everything on the Present canvas — every sheet and loose shape — the
+   * Present-mode "zoom to fit". View-state only — not undoable.
+   *
+   * @returns The resulting {@linkcode PluginPresentationCameraState}.
+   * @throws If Present mode is not open, or the camera is locked.
+   *
+   * @examplePrompt Zoom out to see all the sheets
+   * @examplePrompt Fit the whole presentation in the Present view
+   * @examplePrompt Zoom to fit in Present mode
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.camera.zoomToFit()
+   * ```
+   */
+  public abstract zoomToFit(): PluginApiReturn<PluginPresentationCameraState>
+
+  /**
+   * Frame one shape on the Present canvas: a sheet, a placed view, a keyed
+   * shape or an annotation — any id the other `presentation` namespaces hand
+   * out. Pair with {@linkcode PluginPresentationCameraApi.capture} to
+   * screenshot a single sheet or placed view as it appears on screen.
+   * Immediate, unlike `sheets.setActive`, which animates its move over half a
+   * second. View-state only — not undoable.
+   *
+   * @param shapeId - The id of the sheet or shape to frame.
+   * @returns The resulting {@linkcode PluginPresentationCameraState}.
+   * @throws If Present mode is not open, the id is unknown, or the camera is locked.
+   *
+   * @examplePrompt Zoom in on sheet 2 in Present mode
+   * @examplePrompt Frame this placed view on the Present canvas
+   * @examplePrompt Go to the cover sheet and screenshot it
+   * @examplePrompt Centre the presentation view on that table
+   *
+   * # Example
+   * ```ts
+   * const { sheets } = await snaptrude.presentation.sheets.list()
+   * await snaptrude.presentation.camera.zoomTo(sheets[1].id)
+   * const { image } = await snaptrude.presentation.camera.capture()
+   * ```
+   */
+  public abstract zoomTo(
+    shapeId: string,
+  ): PluginApiReturn<PluginPresentationCameraState>
+}
+
+/**
+ * The visible area of the Present canvas in page units — the canvas as
+ * clipped by the window, minus the strip under the floating left sidebar.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number` | Left edge (page units) |
+ * | `y` | `number` | Top edge (page units) |
+ * | `width` | `number` | Width (page units) |
+ * | `height` | `number` | Height (page units) |
+ */
+export const PluginPresentationCameraViewport = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  width: z.number().finite().nonnegative(),
+  height: z.number().finite().nonnegative(),
+})
+export type PluginPresentationCameraViewport = z.infer<
+  typeof PluginPresentationCameraViewport
+>
+
+/**
+ * The Present canvas camera as returned by every
+ * {@linkcode PluginPresentationCameraApi} method.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number` | Camera pan offset (page units): the page point at the tldraw viewport's top-left corner (under the sidebar) is `(-x, -y)` |
+ * | `y` | `number` | Camera pan offset (page units) |
+ * | `zoom` | `number` | Zoom factor, `1` = 100% |
+ * | `viewport` | {@linkcode PluginPresentationCameraViewport} | The visible page-space rectangle |
+ * | `sheetId` | `string \| null` | The sheet under the centre of the view, or `null` when none |
+ */
+export const PluginPresentationCameraState = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  zoom: z.number().finite().positive(),
+  viewport: PluginPresentationCameraViewport,
+  sheetId: z.string().nullable(),
+})
+export type PluginPresentationCameraState = z.infer<
+  typeof PluginPresentationCameraState
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationCameraApi.set}. All optional, at
+ * least one required; omitted fields keep their current value.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `x` | `number \| undefined` | Camera pan offset (page units) |
+ * | `y` | `number \| undefined` | Camera pan offset (page units) |
+ * | `zoom` | `number \| undefined` | Zoom factor, `> 0` (`1` = 100%); clamped to the editor's range (`0.01`–`10`), `x`/`y` still honoured |
+ */
+export const PluginPresentationCameraSetArgs = z
+  .object({
+    x: z.number().finite().optional(),
+    y: z.number().finite().optional(),
+    zoom: z.number().finite().positive().optional(),
+  })
+  .refine(
+    (c) => c.x !== undefined || c.y !== undefined || c.zoom !== undefined,
+    {
+      message: "Pass at least one of x, y, zoom",
+    },
+  )
+export type PluginPresentationCameraSetArgs = z.infer<
+  typeof PluginPresentationCameraSetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationCameraApi.zoomTo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The sheet or shape to frame |
+ */
+export const PluginPresentationCameraZoomToArgs = z.object({
+  shapeId: z.string().min(1),
+})
+export type PluginPresentationCameraZoomToArgs = z.infer<
+  typeof PluginPresentationCameraZoomToArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationCameraApi.capture}. All optional.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | `"png" \| "jpeg" \| undefined` | Output image format (default `"png"`) |
+ * | `pixelRatio` | `number \| undefined` | Output pixels per screen pixel, `1`–`4` (default `1`) |
+ */
+export const PluginPresentationCameraCaptureArgs = z.object({
+  format: PluginPresentationImageFormat.optional(),
+  pixelRatio: z.number().finite().min(1).max(4).optional(),
+})
+export type PluginPresentationCameraCaptureArgs = z.infer<
+  typeof PluginPresentationCameraCaptureArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationCameraApi.capture}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `image` | `string` | The screenshot as a base64 data URL (`data:image/png;base64,…`) |
+ * | `width` | `number` | Image width in pixels |
+ * | `height` | `number` | Image height in pixels |
+ */
+export const PluginPresentationCameraCaptureResult = z.object({
+  image: z.string(),
+  width: z.number().int().nonnegative(),
+  height: z.number().int().nonnegative(),
+})
+export type PluginPresentationCameraCaptureResult = z.infer<
+  typeof PluginPresentationCameraCaptureResult
+>

package/src/api/presentation/index.ts

@@ -1,5 +1,6 @@
 import { PluginApiReturn } from "../../types"
 import { PluginPresentationViewsApi } from "./views"
+import { PluginPresentationCameraApi } from "./camera"
 import { PluginPresentationAIInspirationApi } from "./aiInspiration"
 import { PluginPresentationSheetsApi } from "./sheets"
 import { PluginPresentationPlacedViewsApi } from "./placedViews"
@@ -9,6 +10,7 @@ import { PluginPresentationShapesApi } from "./shapes"
 import { PluginPresentationTablesApi } from "./tables"
 import { PluginPresentationSlideshowApi } from "./slideshow"
 import { PluginPresentationImportApi } from "./import"
+import { PluginPresentationWalkthroughsApi } from "./walkthroughs"
 import {
   PluginPresentationExportResult,
   type PluginPresentationExportFormat,
@@ -26,6 +28,7 @@ import {
  * sheets, diagram placement, and import.
  *
  * - {@linkcode PluginPresentationApi.views} — Saved 2D/3D views (list, get, capture, activate, create)
+ * - {@linkcode PluginPresentationApi.camera} — The Present canvas camera (screenshot, pan/zoom, frame sheets)
  * - {@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} — Generate program/site diagram sheets, place diagram images
@@ -33,12 +36,15 @@ import {
  * - {@linkcode PluginPresentationApi.slideshow} — Run the Present-mode slideshow
  * - {@linkcode PluginPresentationApi.import} — Import reference images/PDFs onto the canvas
  * - {@linkcode PluginPresentationApi.aiInspiration} — Present-mode AI image/video generation
+ * - {@linkcode PluginPresentationApi.walkthroughs} — Camera paths through the model: create, play, capture, export as video
  *
  * Accessed via `snaptrude.presentation`.
  */
 export abstract class PluginPresentationApi {
   /** Saved 2D/3D views. See {@linkcode PluginPresentationViewsApi}. */
   public abstract views: PluginPresentationViewsApi
+  /** The Present canvas camera — screenshot what is on screen, read/pan/zoom it, frame sheets (Present mode). See {@linkcode PluginPresentationCameraApi}. */
+  public abstract camera: PluginPresentationCameraApi
   /** 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}. */
@@ -60,6 +66,12 @@ export abstract class PluginPresentationApi {
    * {@linkcode PluginPresentationAIInspirationApi}.
    */
   public abstract aiInspiration: PluginPresentationAIInspirationApi
+  /**
+   * Walkthroughs — camera paths through the model: create (keyframes, floor
+   * points, camera-move presets), play, capture and export as video onto the
+   * Present canvas. See {@linkcode PluginPresentationWalkthroughsApi}.
+   */
+  public abstract walkthroughs: PluginPresentationWalkthroughsApi
 
   /**
    * Export the presentation's layout sheets to a downloadable file (PDF / PNG /
@@ -100,6 +112,7 @@ export abstract class PluginPresentationApi {
 }
 
 export * from "./views"
+export * from "./camera"
 export * from "./sheets"
 export * from "./placedViews"
 export * from "./diagrams"
@@ -109,4 +122,5 @@ export * from "./tables"
 export * from "./slideshow"
 export * from "./import"
 export * from "./aiInspiration"
+export * from "./walkthroughs"
 export * from "./export"

package/src/api/presentation/views.ts

@@ -83,7 +83,9 @@ export abstract class PluginPresentationViewsApi {
    *
    * Captures the **current** viewport by default; pass `viewId` to capture a
    * specific saved view (which briefly applies that view to the scene). Use
-   * `format`/`resolution` to control the output.
+   * `format`/`resolution` to control the output. This shoots the Design (3D)
+   * canvas; to screenshot the Present canvas use
+   * {@linkcode PluginPresentationCameraApi.capture}.
    *
    * @param options - All optional: `viewId` (capture this saved view; omit for the
    *   current viewport), `format` (default `"png"`), `resolution` (e.g. `"1280x720"`).