@snaptrude/plugin-core 0.9.15 → 0.9.16

package/src/api/presentation/walkthroughs.ts

@@ -0,0 +1,1201 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle, Vec3Components } from "../../handles"
+
+/**
+ * Walkthroughs: camera paths through the model, played in the viewport and
+ * exported as videos.
+ *
+ * A walkthrough is a list of keyframes (camera positions and where each looks)
+ * joined by a smooth path that the camera travels at a steady speed. Make one
+ * from full keyframes (`create`), from points on the floor (`createFromPoints`)
+ * or from a camera move around what is selected (`createFromPreset`); inspect
+ * it (`sample`, `listIssues`, `capture`); play it (`start`/`stop`/`getState`);
+ * and export it as a video onto the Present canvas (`export` plus the job
+ * methods). Edits are write-gated and each is one step of the walkthrough undo
+ * history, which is separate from the model's. Walkthroughs are not saved with
+ * the project yet: they last until the project is closed or reloaded, while an
+ * exported video stays on the Present canvas.
+ *
+ * Positions are world coordinates in internal `babylon` units (1 unit =
+ * 0.254 m, Y up); yaw is degrees clockwise from +z seen from above, pitch is
+ * degrees above level. Accessed via `snaptrude.presentation.walkthroughs`.
+ */
+export abstract class PluginPresentationWalkthroughsApi {
+  constructor() {}
+
+  /**
+   * List the open project's walkthroughs, oldest first.
+   *
+   * @returns `{ walkthroughs }` — every {@linkcode PluginWalkthrough} (`[]` when there are none).
+   *
+   * @examplePrompt Which walkthroughs are there?
+   * @examplePrompt List the camera paths in this project
+   *
+   * # Example
+   * ```ts
+   * const { walkthroughs } = await snaptrude.presentation.walkthroughs.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginWalkthroughsListResult>
+
+  /**
+   * Get one walkthrough by id.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @returns The {@linkcode PluginWalkthrough}, or `null` when there is none with that id.
+   *
+   * @examplePrompt Show me the keyframes of the orbit walkthrough
+   * @examplePrompt How long does this walkthrough take?
+   *
+   * # Example
+   * ```ts
+   * const walkthrough = await snaptrude.presentation.walkthroughs.get(walkthroughId)
+   * console.log(walkthrough?.durationInSeconds)
+   * ```
+   */
+  public abstract get(
+    walkthroughId: string,
+  ): PluginApiReturn<PluginWalkthrough | null>
+
+  /**
+   * Create a walkthrough from full keyframes: where the camera stands at each
+   * and how it looks there (ahead along the path, at a target, or in a fixed
+   * direction). A keyframe that follows the floor stands at the walkthrough's
+   * eye height above the floor, stair, terrain or ground at or below its `eye`,
+   * and the path between two such keyframes climbs stairs and ramps. The new walkthrough opens in the
+   * walkthrough dock. Write-gated; one undo step.
+   *
+   * @param keyframes - At least one {@linkcode PluginWalkthroughKeyframeInput}, in order
+   * @param options - Name, loop, repeat, and speed or duration ({@linkcode PluginWalkthroughCreateOptions})
+   * @returns The new {@linkcode PluginWalkthrough}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. VALIDATION when
+   *   `isLoop` is set with fewer than three keyframes. PRECONDITION_FAILED when a
+   *   floor-following keyframe lies below the ground with nothing under it.
+   *
+   * @examplePrompt Make a walkthrough through these three viewpoints
+   * @examplePrompt Create a camera path that looks at the atrium the whole way
+   *
+   * # Example
+   * ```ts
+   * const walkthrough = await snaptrude.presentation.walkthroughs.create(
+   *   [
+   *     { eye: { x: 0, y: 30, z: 80 }, look: { mode: "target", target: { x: 0, y: 10, z: 0 } } },
+   *     { eye: { x: 60, y: 30, z: 0 }, look: { mode: "target", target: { x: 0, y: 10, z: 0 } } },
+   *   ],
+   *   { name: "Approach", durationInSeconds: 10 },
+   * )
+   * ```
+   */
+  public abstract create(
+    keyframes: PluginWalkthroughKeyframeInput[],
+    options?: PluginWalkthroughCreateOptions,
+  ): PluginApiReturn<PluginWalkthrough>
+
+  /**
+   * Create a walkthrough that walks through points on the floor, the way the
+   * Walkthrough tool draws a route: the camera stands at eye height above the
+   * floor, stair, terrain or ground at each point, climbs stairs and ramps between them, and looks ahead
+   * along the path, or at `options.lookAt` the whole way. Write-gated; one undo
+   * step.
+   *
+   * @param points - 2 to 200 points on or above the floor, in order
+   * @param options - Name, loop, repeat, speed or duration, and `lookAt` ({@linkcode PluginWalkthroughCreateFromPointsOptions})
+   * @returns The new {@linkcode PluginWalkthrough}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. VALIDATION when
+   *   `isLoop` is set with fewer than three points. PRECONDITION_FAILED when a point
+   *   lies below the ground with nothing under it.
+   *
+   * @examplePrompt Walk from the entrance through the lobby to the stairs
+   * @examplePrompt Make a walkthrough that visits every room on this floor
+   * @examplePrompt Create a loop around the courtyard
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.createFromPoints(
+   *   [{ x: 0, y: 0, z: 0 }, { x: 40, y: 0, z: 0 }, { x: 40, y: 0, z: 30 }],
+   *   { name: "Ground floor tour" },
+   * )
+   * ```
+   */
+  public abstract createFromPoints(
+    points: Vec3Components[],
+    options?: PluginWalkthroughCreateFromPointsOptions,
+  ): PluginApiReturn<PluginWalkthrough>
+
+  /**
+   * Create a walkthrough from a camera move around a subject, as the
+   * Walkthrough button's menu does: `orbit` circles it facing its middle,
+   * `flyOver` passes above it looking ahead and down, `pushIn` and `pullBack`
+   * move toward and away from it, and `rise` cranes up from eye level. The
+   * subject is `options.subject`, else the selection, else the visible model
+   * without its terrain; the move is sized to fit it in view and starts on the
+   * side the camera is on. While the walkthrough is still a preset,
+   * {@linkcode PluginPresentationWalkthroughsApi.update} can change its
+   * distance, height and direction; editing a keyframe makes it ordinary.
+   * Write-gated; one undo step.
+   *
+   * @param kind - The camera move ({@linkcode PluginWalkthroughPresetKind})
+   * @param options - Subject, distance, height, direction, duration, name, repeat ({@linkcode PluginWalkthroughCreateFromPresetOptions})
+   * @returns The new {@linkcode PluginWalkthrough}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when a
+   *   subject handle does not resolve. PRECONDITION_FAILED when there is nothing to frame.
+   *
+   * @examplePrompt Orbit around the selected building
+   * @examplePrompt Make a drone fly-over of the site
+   * @examplePrompt Push in slowly toward the entrance
+   * @examplePrompt Crane up to reveal the whole campus
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.createFromPreset("orbit", {
+   *   subject: [towerId],
+   *   heightInDegrees: 35,
+   *   durationInSeconds: 20,
+   * })
+   * ```
+   */
+  public abstract createFromPreset(
+    kind: PluginWalkthroughPresetKind,
+    options?: PluginWalkthroughCreateFromPresetOptions,
+  ): PluginApiReturn<PluginWalkthrough>
+
+  /**
+   * Change a walkthrough: only the fields given change. Speed and duration are
+   * two ways to set one thing, so give at most one of them. `preset` changes a
+   * preset walkthrough's camera move and makes its keyframes again, keeping its
+   * duration; changing `isLoop` of a preset walkthrough makes it ordinary.
+   * Write-gated; one undo step.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param patch - The fields to change ({@linkcode PluginWalkthroughPatch})
+   * @returns The updated {@linkcode PluginWalkthrough}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   there is no walkthrough with that id. VALIDATION when `isLoop` is set on a
+   *   walkthrough of fewer than three keyframes. PRECONDITION_FAILED when `preset`
+   *   is given for a walkthrough that is not a preset.
+   *
+   * @examplePrompt Slow the walkthrough down to 30 seconds
+   * @examplePrompt Rename it to "Evening approach"
+   * @examplePrompt Make the orbit go the other way round and higher up
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.update(walkthroughId, {
+   *   durationInSeconds: 30,
+   *   isRepeating: true,
+   * })
+   * ```
+   */
+  public abstract update(
+    walkthroughId: string,
+    patch: PluginWalkthroughPatch,
+  ): PluginApiReturn<PluginWalkthrough>
+
+  /**
+   * Delete a walkthrough. Write-gated; one undo step.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @returns `true` once it has been deleted.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   there is no walkthrough with that id.
+   *
+   * @examplePrompt Delete the old walkthrough
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.delete(walkthroughId)
+   * ```
+   */
+  public abstract delete(walkthroughId: string): PluginApiReturn<boolean>
+
+  /**
+   * Add a keyframe to a walkthrough at `index` (0 to the keyframe count;
+   * default: the end). A preset walkthrough becomes ordinary. Write-gated; one
+   * undo step.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param keyframe - The {@linkcode PluginWalkthroughKeyframeInput} to add
+   * @param index - Where to insert it (default: after the last keyframe)
+   * @returns The updated {@linkcode PluginWalkthrough}; the new keyframe is at `index`.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   there is no walkthrough with that id. VALIDATION when `index` is out of range.
+   *
+   * @examplePrompt Add a stop in the kitchen after the second point
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.createKeyframe(
+   *   walkthroughId,
+   *   { eye: { x: 12, y: 0, z: 30 }, followsFloor: true, holdInSeconds: 2 },
+   *   2,
+   * )
+   * ```
+   */
+  public abstract createKeyframe(
+    walkthroughId: string,
+    keyframe: PluginWalkthroughKeyframeInput,
+    index?: number,
+  ): PluginApiReturn<PluginWalkthrough>
+
+  /**
+   * Change a keyframe: only the fields given change. A preset walkthrough
+   * becomes ordinary. Write-gated; one undo step.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param keyframeId - The keyframe's id
+   * @param patch - The fields to change ({@linkcode PluginWalkthroughKeyframePatch})
+   * @returns The updated {@linkcode PluginWalkthrough}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   the walkthrough or keyframe does not exist.
+   *
+   * @examplePrompt Pause for three seconds at the second point
+   * @examplePrompt Make the last point look at the fireplace
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.updateKeyframe(walkthroughId, keyframeId, {
+   *   look: { mode: "target", target: { x: 5, y: 4, z: 10 } },
+   * })
+   * ```
+   */
+  public abstract updateKeyframe(
+    walkthroughId: string,
+    keyframeId: string,
+    patch: PluginWalkthroughKeyframePatch,
+  ): PluginApiReturn<PluginWalkthrough>
+
+  /**
+   * Remove a keyframe; the path then runs straight from the keyframe before it
+   * to the one after. Removing the last keyframe deletes the walkthrough. A
+   * preset walkthrough becomes ordinary. Write-gated; one undo step.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param keyframeId - The keyframe's id
+   * @returns The updated {@linkcode PluginWalkthrough}, or `null` when removing the last keyframe deleted it.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   the walkthrough or keyframe does not exist.
+   *
+   * @examplePrompt Remove the third stop from the walkthrough
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.deleteKeyframe(walkthroughId, keyframeId)
+   * ```
+   */
+  public abstract deleteKeyframe(
+    walkthroughId: string,
+    keyframeId: string,
+  ): PluginApiReturn<PluginWalkthrough | null>
+
+  /**
+   * Move a keyframe to position `index` in the walkthrough's order (the
+   * `presentation.sheets.reorder` convention). A preset walkthrough becomes
+   * ordinary. Write-gated; one undo step.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param keyframeId - The keyframe's id
+   * @param index - Its new 0-based position (0 to the keyframe count - 1)
+   * @returns The updated {@linkcode PluginWalkthrough}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   the walkthrough or keyframe does not exist. VALIDATION when `index` is out of range.
+   *
+   * @examplePrompt Visit the terrace before the living room
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.reorderKeyframe(walkthroughId, keyframeId, 0)
+   * ```
+   */
+  public abstract reorderKeyframe(
+    walkthroughId: string,
+    keyframeId: string,
+    index: number,
+  ): PluginApiReturn<PluginWalkthrough>
+
+  /**
+   * Sample where the camera is and which way it looks at given moments of a
+   * walkthrough's playback, without moving the camera.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param timesInSeconds - 1 to 500 moments, each clamped to the walkthrough's duration
+   * @returns `{ samples }` — one {@linkcode PluginWalkthroughSample} per time, in order.
+   * @throws HANDLE_INVALID when there is no walkthrough with that id.
+   *
+   * @examplePrompt Where is the camera halfway through the walkthrough?
+   * @examplePrompt Check how high the camera flies over the roof
+   *
+   * # Example
+   * ```ts
+   * const walkthrough = await snaptrude.presentation.walkthroughs.get(walkthroughId)
+   * const { samples } = await snaptrude.presentation.walkthroughs.sample(walkthroughId, [
+   *   0,
+   *   walkthrough!.durationInSeconds / 2,
+   * ])
+   * ```
+   */
+  public abstract sample(
+    walkthroughId: string,
+    timesInSeconds: number[],
+  ): PluginApiReturn<PluginWalkthroughSampleResult>
+
+  /**
+   * Find places where a walkthrough's camera passes through the model: through
+   * anything walking would stop at, such as a wall, glazing, a column, a slab or
+   * a roof, which would show the inside of the geometry on screen. Doors,
+   * furniture and room masses don't count, as walking passes through them. Each
+   * issue gives the first moment and point of one pass. The camera itself does
+   * not move.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @returns `{ issues }` — every {@linkcode PluginWalkthroughIssue} in playback order (`[]` when the path is clear).
+   * @throws HANDLE_INVALID when there is no walkthrough with that id.
+   *
+   * @examplePrompt Does the walkthrough go through any walls?
+   * @examplePrompt Check the camera path for clashes and fix them
+   *
+   * # Example
+   * ```ts
+   * const { issues } = await snaptrude.presentation.walkthroughs.listIssues(walkthroughId)
+   * for (const issue of issues) console.log(issue.timeInSeconds, issue.componentId)
+   * ```
+   */
+  public abstract listIssues(
+    walkthroughId: string,
+  ): PluginApiReturn<PluginWalkthroughListIssuesResult>
+
+  /**
+   * Capture frames of a walkthrough as one contact-sheet image: a grid of
+   * views at evenly spaced moments (or at `options.timesInSeconds`), read left
+   * to right and top to bottom. The camera goes back to where it was
+   * afterwards. Switches from 2D plan view to 3D first.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param options - How many frames or which moments, image width and format ({@linkcode PluginWalkthroughCaptureOptions})
+   * @returns `{ image, frames }` — the contact sheet as a base64 data URL and the moment of each frame.
+   * @throws HANDLE_INVALID when there is no walkthrough with that id. PRECONDITION_FAILED
+   *   when a walkthrough is playing or being exported.
+   *
+   * @examplePrompt Show me what the walkthrough looks like
+   * @examplePrompt Capture six frames of the fly-over
+   *
+   * # Example
+   * ```ts
+   * const { image } = await snaptrude.presentation.walkthroughs.capture(walkthroughId, {
+   *   count: 6,
+   * })
+   * ```
+   */
+  public abstract capture(
+    walkthroughId: string,
+    options?: PluginWalkthroughCaptureOptions,
+  ): PluginApiReturn<PluginWalkthroughCaptureResult>
+
+  /**
+   * Play a walkthrough in the viewport, from the start or `options.fromTimeInSeconds`.
+   * Arrow-key navigation pauses while it plays; {@linkcode PluginPresentationWalkthroughsApi.stop}
+   * puts the camera back where it was. Switches from 2D plan view to 3D first.
+   * Resolves once playback has started; a walkthrough that is already playing
+   * keeps playing.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param options - `fromTimeInSeconds` (default 0)
+   * @returns The {@linkcode PluginWalkthroughPlaybackState} after starting.
+   * @throws HANDLE_INVALID when there is no walkthrough with that id. PRECONDITION_FAILED
+   *   when a walkthrough is being exported.
+   *
+   * @examplePrompt Play the walkthrough
+   * @examplePrompt Show me the orbit
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.start(walkthroughId)
+   * ```
+   */
+  public abstract start(
+    walkthroughId: string,
+    options?: PluginWalkthroughStartOptions,
+  ): PluginApiReturn<PluginWalkthroughPlaybackState>
+
+  /**
+   * Stop playback and put the camera back where it was before it started. A
+   * no-op when nothing is playing.
+   *
+   * @returns The {@linkcode PluginWalkthroughPlaybackState} after stopping.
+   *
+   * @examplePrompt Stop the walkthrough
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.stop()
+   * ```
+   */
+  public abstract stop(): PluginApiReturn<PluginWalkthroughPlaybackState>
+
+  /**
+   * Read the playback state: which walkthrough is playing or paused, and how
+   * far through it.
+   *
+   * @returns The current {@linkcode PluginWalkthroughPlaybackState}.
+   *
+   * @examplePrompt Is the walkthrough still playing?
+   *
+   * # Example
+   * ```ts
+   * const { status, timeInSeconds } = await snaptrude.presentation.walkthroughs.getState()
+   * ```
+   */
+  public abstract getState(): PluginApiReturn<PluginWalkthroughPlaybackState>
+
+  /**
+   * Record a walkthrough as a video and place it on the Present canvas, as an
+   * asynchronous job: this resolves at once with the queued job, and
+   * {@linkcode PluginPresentationWalkthroughsApi.getJob} reports it until it
+   * completes, fails or is cancelled. Recording plays the walkthrough in real
+   * time at the chosen size, so it takes about as long as the walkthrough plus
+   * the upload; the editor switches to Present mode to place the video, which
+   * keeps playing muted in a loop there. Only one export runs at a time.
+   * Write-gated.
+   *
+   * @param walkthroughId - The walkthrough's id
+   * @param options - Video quality and frame rate ({@linkcode PluginWalkthroughExportOptions})
+   * @returns The queued {@linkcode PluginWalkthroughExportJob}.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   there is no walkthrough with that id. PRECONDITION_FAILED when another export
+   *   is running or this browser cannot record video.
+   *
+   * @examplePrompt Export the walkthrough as a video
+   * @examplePrompt Put a 1080p video of the orbit on a sheet
+   *
+   * # Example
+   * ```ts
+   * const walkthroughs = snaptrude.presentation.walkthroughs
+   * let job = await walkthroughs.export(walkthroughId, { quality: "1080p" })
+   * while (job.status === "queued" || job.status === "running") {
+   *   await new Promise((resolve) => setTimeout(resolve, 2000))
+   *   job = (await walkthroughs.getJob(job.jobId))!
+   * }
+   * console.log(job.result?.shapeId)
+   * ```
+   */
+  public abstract export(
+    walkthroughId: string,
+    options?: PluginWalkthroughExportOptions,
+  ): PluginApiReturn<PluginWalkthroughExportJob>
+
+  /**
+   * Get an export job by id.
+   *
+   * @param jobId - The job's id, from {@linkcode PluginPresentationWalkthroughsApi.export}
+   * @returns The {@linkcode PluginWalkthroughExportJob}, or `null` when there is none
+   *   with that id (finished jobs are forgotten after 30 minutes).
+   *
+   * @examplePrompt Is the video export done yet?
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.presentation.walkthroughs.getJob(jobId)
+   * ```
+   */
+  public abstract getJob(
+    jobId: string,
+  ): PluginApiReturn<PluginWalkthroughExportJob | null>
+
+  /**
+   * Cancel an export job. The recording stops and nothing is placed; a job that
+   * has already finished is returned unchanged. Write-gated.
+   *
+   * @param jobId - The job's id
+   * @returns The {@linkcode PluginWalkthroughExportJob} after cancelling.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled. HANDLE_INVALID when
+   *   there is no job with that id.
+   *
+   * @examplePrompt Cancel the video export
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.walkthroughs.cancelJob(jobId)
+   * ```
+   */
+  public abstract cancelJob(
+    jobId: string,
+  ): PluginApiReturn<PluginWalkthroughExportJob>
+
+  /**
+   * List export jobs, newest first: running ones and those that finished in the
+   * last 30 minutes.
+   *
+   * @returns `{ jobs }` — each {@linkcode PluginWalkthroughExportJob} (`[]` when there are none).
+   *
+   * @examplePrompt Which video exports are running?
+   *
+   * # Example
+   * ```ts
+   * const { jobs } = await snaptrude.presentation.walkthroughs.listJobs()
+   * ```
+   */
+  public abstract listJobs(): PluginApiReturn<PluginWalkthroughListJobsResult>
+}
+
+// Plain {x, y, z} record with finite components (the brepFromRevolution `axisOrigin` pattern).
+const FiniteVec3Components = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  z: z.number().finite(),
+})
+
+const PositiveFinite = z.number().finite().positive()
+
+/**
+ * How a keyframe's camera looks — exactly one of:
+ *
+ * | Shape | Meaning |
+ * |---|---|
+ * | `{ mode: "path" }` | Ahead along the path, level |
+ * | `{ mode: "target", target }` | At a point in the model |
+ * | `{ mode: "fixed", yawInDegrees, pitchInDegrees }` | In a fixed direction (pitch within ±89°) |
+ */
+export const PluginWalkthroughLook = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("path") }).strict(),
+  z
+    .object({ mode: z.literal("target"), target: FiniteVec3Components })
+    .strict(),
+  z
+    .object({
+      mode: z.literal("fixed"),
+      yawInDegrees: z.number().finite(),
+      pitchInDegrees: z.number().finite().min(-89).max(89),
+    })
+    .strict(),
+])
+export type PluginWalkthroughLook = z.infer<typeof PluginWalkthroughLook>
+
+/**
+ * A keyframe of a {@linkcode PluginWalkthrough}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `keyframeId` | `string` | The keyframe's id |
+ * | `eye` | `{ x, y, z }` | Camera position (world, `babylon` units) |
+ * | `look` | {@linkcode PluginWalkthroughLook} | How the camera looks here |
+ * | `followsFloor` | `boolean` | Stands at eye height above the floor; paths between two such keyframes follow the floor |
+ * | `holdInSeconds` | `number` | Pause here before moving on |
+ */
+export const PluginWalkthroughKeyframe = z.object({
+  keyframeId: z.string(),
+  eye: Vec3Components,
+  look: PluginWalkthroughLook,
+  followsFloor: z.boolean(),
+  holdInSeconds: z.number(),
+})
+export type PluginWalkthroughKeyframe = z.infer<
+  typeof PluginWalkthroughKeyframe
+>
+
+/**
+ * A keyframe to add, for {@linkcode PluginPresentationWalkthroughsApi.create} and
+ * {@linkcode PluginPresentationWalkthroughsApi.createKeyframe}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `eye` | `{ x, y, z }` | Camera position; with `followsFloor`, a point on or above the floor |
+ * | `look` | {@linkcode PluginWalkthroughLook} `\| undefined` | How the camera looks here (default `{ mode: "path" }`) |
+ * | `followsFloor` | `boolean \| undefined` | Stand at eye height above the floor at or below `eye` (default `false`: `eye` as given) |
+ * | `holdInSeconds` | `number \| undefined` | Pause here, 0 to 60 (default 0) |
+ */
+export const PluginWalkthroughKeyframeInput = z
+  .object({
+    eye: FiniteVec3Components,
+    look: PluginWalkthroughLook.optional(),
+    followsFloor: z.boolean().optional(),
+    holdInSeconds: z.number().finite().min(0).max(60).optional(),
+  })
+  .strict()
+export type PluginWalkthroughKeyframeInput = z.infer<
+  typeof PluginWalkthroughKeyframeInput
+>
+
+/**
+ * The fields to change in {@linkcode PluginPresentationWalkthroughsApi.updateKeyframe};
+ * omitted fields keep their value.
+ */
+export const PluginWalkthroughKeyframePatch = z
+  .object({
+    eye: FiniteVec3Components.optional(),
+    look: PluginWalkthroughLook.optional(),
+    followsFloor: z.boolean().optional(),
+    holdInSeconds: z.number().finite().min(0).max(60).optional(),
+  })
+  .strict()
+export type PluginWalkthroughKeyframePatch = z.infer<
+  typeof PluginWalkthroughKeyframePatch
+>
+
+/**
+ * A camera move for {@linkcode PluginPresentationWalkthroughsApi.createFromPreset}:
+ * `orbit` (circle the subject facing its middle), `flyOver` (pass above it
+ * looking ahead and down), `pushIn` / `pullBack` (move toward / away from it),
+ * `rise` (crane up from eye level).
+ */
+export const PluginWalkthroughPresetKind = z.enum([
+  "orbit",
+  "flyOver",
+  "pushIn",
+  "pullBack",
+  "rise",
+])
+export type PluginWalkthroughPresetKind = z.infer<
+  typeof PluginWalkthroughPresetKind
+>
+
+/**
+ * The camera move a preset walkthrough was made from.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode PluginWalkthroughPresetKind} | The move |
+ * | `distance` | `number` | Camera distance, as a multiple of the distance at which the subject just fits in view |
+ * | `heightInDegrees` | `number` | Camera height, in degrees above level seen from the subject's middle |
+ * | `isClockwise` | `boolean` | Orbits only: goes round clockwise seen from above |
+ */
+export const PluginWalkthroughPreset = z.object({
+  kind: PluginWalkthroughPresetKind,
+  distance: z.number(),
+  heightInDegrees: z.number(),
+  isClockwise: z.boolean(),
+})
+export type PluginWalkthroughPreset = z.infer<typeof PluginWalkthroughPreset>
+
+/** The Distance setting: 0.8 to 3 times the distance at which the subject just fits. */
+const PresetDistance = z.number().finite().min(0.8).max(3)
+/** The Height setting, in degrees above level. */
+const PresetHeightInDegrees = z.number().finite().min(0).max(75)
+
+/**
+ * A walkthrough.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `walkthroughId` | `string` | The walkthrough's id |
+ * | `name` | `string` | Its name |
+ * | `keyframes` | {@linkcode PluginWalkthroughKeyframe}`[]` | Its keyframes, in order |
+ * | `isLoop` | `boolean` | The path returns from the last keyframe to the first |
+ * | `isRepeating` | `boolean` | Playback starts again when it reaches the end |
+ * | `speed` | `number` | Travel speed, `babylon` units per second |
+ * | `durationInSeconds` | `number` | How long playback takes, including easing and holds |
+ * | `pathLength` | `number` | Length of the path, `babylon` units |
+ * | `eyeHeight` | `number` | Eye height above the floor for floor-following keyframes, `babylon` units |
+ * | `preset` | {@linkcode PluginWalkthroughPreset} `\| null` | The camera move it was made from, while it is still a preset |
+ */
+export const PluginWalkthrough = z.object({
+  walkthroughId: z.string(),
+  name: z.string(),
+  keyframes: z.array(PluginWalkthroughKeyframe),
+  isLoop: z.boolean(),
+  isRepeating: z.boolean(),
+  speed: z.number(),
+  durationInSeconds: z.number(),
+  pathLength: z.number(),
+  eyeHeight: z.number(),
+  preset: PluginWalkthroughPreset.nullable(),
+})
+export type PluginWalkthrough = z.infer<typeof PluginWalkthrough>
+
+/**
+ * Result of {@linkcode PluginPresentationWalkthroughsApi.list}.
+ */
+export const PluginWalkthroughsListResult = z.object({
+  walkthroughs: z.array(PluginWalkthrough),
+})
+export type PluginWalkthroughsListResult = z.infer<
+  typeof PluginWalkthroughsListResult
+>
+
+const CreateOptionFields = {
+  name: z.string().trim().min(1).max(120).optional(),
+  isLoop: z.boolean().optional(),
+  isRepeating: z.boolean().optional(),
+  speed: PositiveFinite.optional(),
+  durationInSeconds: PositiveFinite.optional(),
+}
+
+const atMostOneOfSpeedAndDuration = (value: {
+  speed?: number
+  durationInSeconds?: number
+}) => value.speed === undefined || value.durationInSeconds === undefined
+const SPEED_AND_DURATION_MESSAGE = "Give speed or durationInSeconds, not both"
+
+/**
+ * Options for {@linkcode PluginPresentationWalkthroughsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | Its name (default "Walkthrough N") |
+ * | `isLoop` | `boolean \| undefined` | Return from the last keyframe to the first (default `false`; needs 3 keyframes) |
+ * | `isRepeating` | `boolean \| undefined` | Play again from the start at the end (default `false`) |
+ * | `speed` | `number \| undefined` | Travel speed, `babylon` units per second (default 1 m/s) |
+ * | `durationInSeconds` | `number \| undefined` | Take this long instead; sets the speed. Give `speed` or this, not both |
+ */
+export const PluginWalkthroughCreateOptions = z
+  .object(CreateOptionFields)
+  .strict()
+  .refine(atMostOneOfSpeedAndDuration, SPEED_AND_DURATION_MESSAGE)
+export type PluginWalkthroughCreateOptions = z.infer<
+  typeof PluginWalkthroughCreateOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.create}.
+ */
+export const PluginWalkthroughCreateArgs = z.object({
+  keyframes: z.array(PluginWalkthroughKeyframeInput).min(1).max(200),
+  options: PluginWalkthroughCreateOptions.optional(),
+})
+export type PluginWalkthroughCreateArgs = z.infer<
+  typeof PluginWalkthroughCreateArgs
+>
+
+/**
+ * Options for {@linkcode PluginPresentationWalkthroughsApi.createFromPoints}: those of
+ * {@linkcode PluginWalkthroughCreateOptions}, plus:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `lookAt` | `{ x, y, z } \| undefined` | Look at this point the whole way (default: ahead along the path) |
+ */
+export const PluginWalkthroughCreateFromPointsOptions = z
+  .object({ ...CreateOptionFields, lookAt: FiniteVec3Components.optional() })
+  .strict()
+  .refine(atMostOneOfSpeedAndDuration, SPEED_AND_DURATION_MESSAGE)
+export type PluginWalkthroughCreateFromPointsOptions = z.infer<
+  typeof PluginWalkthroughCreateFromPointsOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.createFromPoints}.
+ */
+export const PluginWalkthroughCreateFromPointsArgs = z.object({
+  points: z.array(FiniteVec3Components).min(2).max(200),
+  options: PluginWalkthroughCreateFromPointsOptions.optional(),
+})
+export type PluginWalkthroughCreateFromPointsArgs = z.infer<
+  typeof PluginWalkthroughCreateFromPointsArgs
+>
+
+/**
+ * Options for {@linkcode PluginPresentationWalkthroughsApi.createFromPreset}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `subject` | {@linkcode ComponentHandle}`[] \| undefined` | What to frame (default: the selection, else the visible model without terrain) |
+ * | `distance` | `number \| undefined` | 0.8 to 3 times the distance at which the subject just fits (default per move) |
+ * | `heightInDegrees` | `number \| undefined` | 0 to 75 degrees above level (default per move) |
+ * | `isClockwise` | `boolean \| undefined` | Orbits only: go round clockwise seen from above (default `false`) |
+ * | `durationInSeconds` | `number \| undefined` | How long the move takes (default per move: orbit 24, fly over 12, others 8) |
+ * | `name` | `string \| undefined` | Its name (default the move's name and a number) |
+ * | `isRepeating` | `boolean \| undefined` | Play again from the start at the end (default `false`) |
+ */
+export const PluginWalkthroughCreateFromPresetOptions = z
+  .object({
+    subject: z.array(ComponentHandle).min(1).max(1000).optional(),
+    distance: PresetDistance.optional(),
+    heightInDegrees: PresetHeightInDegrees.optional(),
+    isClockwise: z.boolean().optional(),
+    durationInSeconds: PositiveFinite.optional(),
+    name: z.string().trim().min(1).max(120).optional(),
+    isRepeating: z.boolean().optional(),
+  })
+  .strict()
+export type PluginWalkthroughCreateFromPresetOptions = z.infer<
+  typeof PluginWalkthroughCreateFromPresetOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.createFromPreset}.
+ */
+export const PluginWalkthroughCreateFromPresetArgs = z.object({
+  kind: PluginWalkthroughPresetKind,
+  options: PluginWalkthroughCreateFromPresetOptions.optional(),
+})
+export type PluginWalkthroughCreateFromPresetArgs = z.infer<
+  typeof PluginWalkthroughCreateFromPresetArgs
+>
+
+/**
+ * The fields to change in {@linkcode PluginPresentationWalkthroughsApi.update};
+ * omitted fields keep their value.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | New name |
+ * | `isLoop` | `boolean \| undefined` | Return from the last keyframe to the first (needs 3 keyframes); makes a preset ordinary |
+ * | `isRepeating` | `boolean \| undefined` | Play again from the start at the end |
+ * | `speed` | `number \| undefined` | Travel speed, `babylon` units per second |
+ * | `durationInSeconds` | `number \| undefined` | Take this long; sets the speed. Give `speed` or this, not both |
+ * | `preset` | `{ distance?, heightInDegrees?, isClockwise? } \| undefined` | A preset walkthrough's move settings; its keyframes are made again |
+ */
+export const PluginWalkthroughPatch = z
+  .object({
+    name: z.string().trim().min(1).max(120).optional(),
+    isLoop: z.boolean().optional(),
+    isRepeating: z.boolean().optional(),
+    speed: PositiveFinite.optional(),
+    durationInSeconds: PositiveFinite.optional(),
+    preset: z
+      .object({
+        distance: PresetDistance.optional(),
+        heightInDegrees: PresetHeightInDegrees.optional(),
+        isClockwise: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+  .refine(atMostOneOfSpeedAndDuration, SPEED_AND_DURATION_MESSAGE)
+export type PluginWalkthroughPatch = z.infer<typeof PluginWalkthroughPatch>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.update}.
+ */
+export const PluginWalkthroughUpdateArgs = z.object({
+  walkthroughId: z.string().min(1),
+  patch: PluginWalkthroughPatch,
+})
+export type PluginWalkthroughUpdateArgs = z.infer<
+  typeof PluginWalkthroughUpdateArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.createKeyframe}.
+ */
+export const PluginWalkthroughCreateKeyframeArgs = z.object({
+  walkthroughId: z.string().min(1),
+  keyframe: PluginWalkthroughKeyframeInput,
+  index: z.number().int().min(0).optional(),
+})
+export type PluginWalkthroughCreateKeyframeArgs = z.infer<
+  typeof PluginWalkthroughCreateKeyframeArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.updateKeyframe}.
+ */
+export const PluginWalkthroughUpdateKeyframeArgs = z.object({
+  walkthroughId: z.string().min(1),
+  keyframeId: z.string().min(1),
+  patch: PluginWalkthroughKeyframePatch,
+})
+export type PluginWalkthroughUpdateKeyframeArgs = z.infer<
+  typeof PluginWalkthroughUpdateKeyframeArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.deleteKeyframe}.
+ */
+export const PluginWalkthroughDeleteKeyframeArgs = z.object({
+  walkthroughId: z.string().min(1),
+  keyframeId: z.string().min(1),
+})
+export type PluginWalkthroughDeleteKeyframeArgs = z.infer<
+  typeof PluginWalkthroughDeleteKeyframeArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.reorderKeyframe}.
+ */
+export const PluginWalkthroughReorderKeyframeArgs = z.object({
+  walkthroughId: z.string().min(1),
+  keyframeId: z.string().min(1),
+  index: z.number().int().min(0),
+})
+export type PluginWalkthroughReorderKeyframeArgs = z.infer<
+  typeof PluginWalkthroughReorderKeyframeArgs
+>
+
+/**
+ * Where the camera is at one moment — an item of
+ * {@linkcode PluginWalkthroughSampleResult}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `timeInSeconds` | `number` | The moment (clamped to the walkthrough's duration) |
+ * | `eye` | `{ x, y, z }` | Camera position |
+ * | `direction` | `{ x, y, z }` | Unit view direction |
+ * | `yawInDegrees` | `number` | View direction, degrees clockwise from +z seen from above |
+ * | `pitchInDegrees` | `number` | View direction, degrees above level |
+ */
+export const PluginWalkthroughSample = z.object({
+  timeInSeconds: z.number(),
+  eye: Vec3Components,
+  direction: Vec3Components,
+  yawInDegrees: z.number(),
+  pitchInDegrees: z.number(),
+})
+export type PluginWalkthroughSample = z.infer<typeof PluginWalkthroughSample>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.sample}.
+ */
+export const PluginWalkthroughSampleArgs = z.object({
+  walkthroughId: z.string().min(1),
+  timesInSeconds: z.array(z.number().finite()).min(1).max(500),
+})
+export type PluginWalkthroughSampleArgs = z.infer<
+  typeof PluginWalkthroughSampleArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationWalkthroughsApi.sample}.
+ */
+export const PluginWalkthroughSampleResult = z.object({
+  samples: z.array(PluginWalkthroughSample),
+})
+export type PluginWalkthroughSampleResult = z.infer<
+  typeof PluginWalkthroughSampleResult
+>
+
+/**
+ * What is wrong at a walkthrough issue: `throughGeometry` — the camera passes
+ * through the model (a wall, glazing, a column, a slab, a roof or other solid
+ * that walking would stop at).
+ */
+export const PluginWalkthroughIssueKind = z.enum(["throughGeometry"])
+export type PluginWalkthroughIssueKind = z.infer<
+  typeof PluginWalkthroughIssueKind
+>
+
+/**
+ * A place where a walkthrough's camera passes through the model — an item of
+ * {@linkcode PluginWalkthroughListIssuesResult}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode PluginWalkthroughIssueKind} | What is wrong |
+ * | `timeInSeconds` | `number` | When the camera reaches it during playback |
+ * | `point` | `{ x, y, z }` | Where the path enters the geometry |
+ * | `componentId` | `string \| null` | The component passed through, when it is one |
+ */
+export const PluginWalkthroughIssue = z.object({
+  kind: PluginWalkthroughIssueKind,
+  timeInSeconds: z.number(),
+  point: Vec3Components,
+  componentId: z.string().nullable(),
+})
+export type PluginWalkthroughIssue = z.infer<typeof PluginWalkthroughIssue>
+
+/**
+ * Result of {@linkcode PluginPresentationWalkthroughsApi.listIssues}.
+ */
+export const PluginWalkthroughListIssuesResult = z.object({
+  issues: z.array(PluginWalkthroughIssue),
+})
+export type PluginWalkthroughListIssuesResult = z.infer<
+  typeof PluginWalkthroughListIssuesResult
+>
+
+/**
+ * Options for {@linkcode PluginPresentationWalkthroughsApi.capture}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `count` | `number \| undefined` | Frames at evenly spaced moments, first to last, 1 to 12 (default 6) |
+ * | `timesInSeconds` | `number[] \| undefined` | Capture these 1 to 12 moments instead. Give `count` or this, not both |
+ * | `width` | `number \| undefined` | Width of the whole image in pixels, 256 to 2048 (default 1536) |
+ * | `format` | `"png" \| "jpeg" \| undefined` | Image format (default `"jpeg"`) |
+ */
+export const PluginWalkthroughCaptureOptions = z
+  .object({
+    count: z.number().int().min(1).max(12).optional(),
+    timesInSeconds: z.array(z.number().finite()).min(1).max(12).optional(),
+    width: z.number().int().min(256).max(2048).optional(),
+    format: z.enum(["png", "jpeg"]).optional(),
+  })
+  .strict()
+  .refine(
+    (value) => value.count === undefined || value.timesInSeconds === undefined,
+    "Give count or timesInSeconds, not both",
+  )
+export type PluginWalkthroughCaptureOptions = z.infer<
+  typeof PluginWalkthroughCaptureOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.capture}.
+ */
+export const PluginWalkthroughCaptureArgs = z.object({
+  walkthroughId: z.string().min(1),
+  options: PluginWalkthroughCaptureOptions.optional(),
+})
+export type PluginWalkthroughCaptureArgs = z.infer<
+  typeof PluginWalkthroughCaptureArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationWalkthroughsApi.capture}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `image` | `string` | The contact sheet as a base64 data URL |
+ * | `frames` | `{ timeInSeconds }[]` | The moment of each frame, left to right and top to bottom |
+ */
+export const PluginWalkthroughCaptureResult = z.object({
+  image: z.string(),
+  frames: z.array(z.object({ timeInSeconds: z.number() })),
+})
+export type PluginWalkthroughCaptureResult = z.infer<
+  typeof PluginWalkthroughCaptureResult
+>
+
+/**
+ * Options for {@linkcode PluginPresentationWalkthroughsApi.start}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `fromTimeInSeconds` | `number \| undefined` | Start this far in (default 0) |
+ */
+export const PluginWalkthroughStartOptions = z
+  .object({ fromTimeInSeconds: z.number().finite().min(0).optional() })
+  .strict()
+export type PluginWalkthroughStartOptions = z.infer<
+  typeof PluginWalkthroughStartOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.start}.
+ */
+export const PluginWalkthroughStartArgs = z.object({
+  walkthroughId: z.string().min(1),
+  options: PluginWalkthroughStartOptions.optional(),
+})
+export type PluginWalkthroughStartArgs = z.infer<
+  typeof PluginWalkthroughStartArgs
+>
+
+/**
+ * The playback state — result of {@linkcode PluginPresentationWalkthroughsApi.start},
+ * {@linkcode PluginPresentationWalkthroughsApi.stop} and
+ * {@linkcode PluginPresentationWalkthroughsApi.getState}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `status` | `"stopped" \| "playing" \| "paused"` | Playback status |
+ * | `walkthroughId` | `string \| null` | The walkthrough playing or paused (`null` when stopped) |
+ * | `timeInSeconds` | `number` | How far through it |
+ * | `durationInSeconds` | `number` | Its duration (0 when stopped) |
+ * | `isRecording` | `boolean` | Whether playback is being recorded by an export |
+ */
+export const PluginWalkthroughPlaybackState = z.object({
+  status: z.enum(["stopped", "playing", "paused"]),
+  walkthroughId: z.string().nullable(),
+  timeInSeconds: z.number(),
+  durationInSeconds: z.number(),
+  isRecording: z.boolean(),
+})
+export type PluginWalkthroughPlaybackState = z.infer<
+  typeof PluginWalkthroughPlaybackState
+>
+
+/**
+ * Options for {@linkcode PluginPresentationWalkthroughsApi.export}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `quality` | `"720p" \| "1080p" \| "4k" \| undefined` | Video size (default `"1080p"`) |
+ * | `framesPerSecond` | `30 \| 60 \| undefined` | Frame rate (default 30) |
+ */
+export const PluginWalkthroughExportOptions = z
+  .object({
+    quality: z.enum(["720p", "1080p", "4k"]).optional(),
+    framesPerSecond: z.union([z.literal(30), z.literal(60)]).optional(),
+  })
+  .strict()
+export type PluginWalkthroughExportOptions = z.infer<
+  typeof PluginWalkthroughExportOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationWalkthroughsApi.export}.
+ */
+export const PluginWalkthroughExportArgs = z.object({
+  walkthroughId: z.string().min(1),
+  options: PluginWalkthroughExportOptions.optional(),
+})
+export type PluginWalkthroughExportArgs = z.infer<
+  typeof PluginWalkthroughExportArgs
+>
+
+/**
+ * The status of a {@linkcode PluginWalkthroughExportJob}.
+ */
+export const PluginWalkthroughExportJobStatus = z.enum([
+  "queued",
+  "running",
+  "completed",
+  "failed",
+  "cancelled",
+])
+export type PluginWalkthroughExportJobStatus = z.infer<
+  typeof PluginWalkthroughExportJobStatus
+>
+
+/**
+ * What a completed export made.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | The video shape on the Present canvas |
+ * | `videoUrl` | `string \| null` | Where the uploaded video is stored |
+ * | `width` / `height` | `number` | Video size in pixels |
+ * | `mimeType` | `string` | Video type, e.g. `video/mp4` |
+ * | `durationInSeconds` | `number` | Video length |
+ */
+export const PluginWalkthroughExportResult = z.object({
+  shapeId: z.string(),
+  videoUrl: z.string().nullable(),
+  width: z.number(),
+  height: z.number(),
+  mimeType: z.string(),
+  durationInSeconds: z.number(),
+})
+export type PluginWalkthroughExportResult = z.infer<
+  typeof PluginWalkthroughExportResult
+>
+
+/**
+ * A walkthrough video export job.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `jobId` | `string` | The job's id |
+ * | `walkthroughId` | `string` | The walkthrough being exported |
+ * | `status` | {@linkcode PluginWalkthroughExportJobStatus} | Where the job is |
+ * | `createdAt` / `updatedAt` | `number` | Epoch milliseconds |
+ * | `completedAt` | `number \| undefined` | When it completed, failed or was cancelled |
+ * | `progress` | `number \| undefined` | 0 to 1 while running |
+ * | `result` | {@linkcode PluginWalkthroughExportResult} `\| undefined` | What it made, once completed |
+ * | `error` | `string \| undefined` | Why it failed |
+ */
+export const PluginWalkthroughExportJob = z.object({
+  jobId: z.string(),
+  walkthroughId: z.string(),
+  status: PluginWalkthroughExportJobStatus,
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  completedAt: z.number().optional(),
+  progress: z.number().min(0).max(1).optional(),
+  result: PluginWalkthroughExportResult.optional(),
+  error: z.string().optional(),
+})
+export type PluginWalkthroughExportJob = z.infer<
+  typeof PluginWalkthroughExportJob
+>
+
+/**
+ * Result of {@linkcode PluginPresentationWalkthroughsApi.listJobs}.
+ */
+export const PluginWalkthroughListJobsResult = z.object({
+  jobs: z.array(PluginWalkthroughExportJob),
+})
+export type PluginWalkthroughListJobsResult = z.infer<
+  typeof PluginWalkthroughListJobsResult
+>