@snaptrude/plugin-core 0.0.0-dev-20260708130115

package/src/api/presentation/views.ts

@@ -0,0 +1,303 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation views — read the saved 2D/3D views used to prepare presentations.
+ *
+ * A **view** is a saved camera/plan: a sheet-ready 2D plan or a saved 3D view.
+ * A plugin can list and read views, capture them to images, activate one (move
+ * the camera to it), and save the current camera as a new view.
+ *
+ * `list`/`get`/`getActive`/`capture` are reads; `setActive`/`create` are writes
+ * (a view is a camera bookmark — not geometry). Members typed optional (`?`) are
+ * authored ahead of the host: declared for plugins/codegen but not yet on the
+ * live discovery surface until the host lands them.
+ *
+ * Accessed via `snaptrude.presentation.views`.
+ */
+export abstract class PluginPresentationViewsApi {
+  constructor() {}
+
+  /**
+   * List the saved views in the active project.
+   *
+   * @returns A {@linkcode PluginPresentationViewsListResult} with a `views` array
+   *   of 2D and 3D views (empty when the project has none).
+   *
+   * @examplePrompt List all the saved views
+   * @examplePrompt What 2D and 3D views are in this project?
+   * @examplePrompt Which view is currently active?
+   * @examplePrompt Get the names of every presentation view
+   * @examplePrompt Show me the 3D views I can put on a sheet
+   *
+   * # Example
+   * ```ts
+   * const { views } = await snaptrude.presentation.views.list()
+   * const active = views.find((v) => v.isActive)
+   * const plans = views.filter((v) => v.type === "2d")
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginPresentationViewsListResult>
+
+  /**
+   * Get a single saved view by id.
+   *
+   * @param viewId - The id of the view to read.
+   * @returns The matching {@linkcode PluginPresentationView}, or `null` if no view
+   *   has that id.
+   *
+   * @examplePrompt Get the view with id view_12345
+   * @examplePrompt Find the saved view called Ground Floor Plan
+   * @examplePrompt Look up a presentation view by its id
+   *
+   * # Example
+   * ```ts
+   * const view = await snaptrude.presentation.views.get("view_123")
+   * ```
+   */
+  public abstract get(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsGetResult>
+
+  /**
+   * Get the currently active view.
+   *
+   * @returns The active {@linkcode PluginPresentationView}, or `null` if none is
+   *   active.
+   *
+   * @examplePrompt Which view is active right now?
+   * @examplePrompt Get the current view
+   * @examplePrompt What view am I looking at?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.presentation.views.getActive()
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<PluginPresentationViewsGetResult>
+
+  /**
+   * Capture a screenshot of a view as a base64 image.
+   *
+   * 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.
+   *
+   * @param options - All optional: `viewId` (capture this saved view; omit for the
+   *   current viewport), `format` (default `"png"`), `resolution` (e.g. `"1280x720"`).
+   * @returns A {@linkcode PluginPresentationViewsCaptureResult} with the base64
+   *   `image` data URL.
+   * @throws If a given `viewId` does not exist.
+   *
+   * @examplePrompt Take a screenshot of the current view
+   * @examplePrompt Capture this view as a PNG
+   * @examplePrompt Render the Site Plan view to an image
+   * @examplePrompt Export a high-res image of what I'm looking at
+   *
+   * # Example
+   * ```ts
+   * const { image } = await snaptrude.presentation.views.capture({ format: "png" })
+   * ```
+   */
+  public abstract capture(options?: {
+    viewId?: string
+    format?: "png" | "jpeg"
+    resolution?: string
+  }): PluginApiReturn<PluginPresentationViewsCaptureResult>
+
+  /**
+   * Activate a saved view — move the camera to it and restore its scene state.
+   *
+   * Applies the view's camera, visibility, and storey state to the live scene.
+   * Paired with {@linkcode PluginPresentationViewsApi.getActive}.
+   *
+   * @param viewId - The id of the view to activate.
+   * @returns The id of the now-active view.
+   * @throws If no view has the given id.
+   *
+   * @examplePrompt Switch to the Ground Floor plan view
+   * @examplePrompt Make the 3D view active
+   * @examplePrompt Go to the view named Entrance
+   * @examplePrompt Load the site plan view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.views.setActive("view_123")
+   * ```
+   */
+  public abstract setActive(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsSetActiveResult>
+
+  /**
+   * Save the current camera/scene state as a new named view.
+   *
+   * Creates a camera bookmark (not geometry) from where the camera is now.
+   *
+   * @param name - Name for the new view (a default is used when omitted).
+   * @param options - Optional `kind`: what kind of view to save (default `"view"`).
+   * @returns The newly created {@linkcode PluginPresentationView}.
+   * @throws If the view could not be saved.
+   *
+   * @examplePrompt Save the current view as Lobby Perspective
+   * @examplePrompt Create a new saved view from where I'm looking
+   * @examplePrompt Bookmark this camera angle
+   * @examplePrompt Save the current 2D plan as a view
+   *
+   * # Example
+   * ```ts
+   * const view = await snaptrude.presentation.views.create("Lobby")
+   * ```
+   */
+  public abstract create(
+    name?: string,
+    options?: { kind?: "view" | "sitePlan" },
+  ): PluginApiReturn<PluginPresentationViewsCreateResult>
+}
+
+/**
+ * The kind of a saved view: a 2D plan view or a 3D view.
+ */
+export const PluginPresentationViewType = z.enum(["2d", "3d"])
+export type PluginPresentationViewType = z.infer<
+  typeof PluginPresentationViewType
+>
+
+/**
+ * A saved presentation view.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Unique view id |
+ * | `name` | `string` | Display name |
+ * | `type` | `"2d" \| "3d"` | Whether this is a 2D plan view or a 3D view |
+ * | `isActive` | `boolean` | Whether this view is the currently active view |
+ */
+export const PluginPresentationView = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: PluginPresentationViewType,
+  isActive: z.boolean(),
+})
+export type PluginPresentationView = z.infer<typeof PluginPresentationView>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `views` | {@linkcode PluginPresentationView}`[]` | All saved views in the project |
+ */
+export const PluginPresentationViewsListResult = z.object({
+  views: z.array(PluginPresentationView),
+})
+export type PluginPresentationViewsListResult = z.infer<
+  typeof PluginPresentationViewsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to read |
+ */
+export const PluginPresentationViewsGetArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsGetArgs = z.infer<
+  typeof PluginPresentationViewsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.get} and
+ * {@linkcode PluginPresentationViewsApi.getActive} — the view, or `null` when
+ * there is no match / no active view.
+ */
+export const PluginPresentationViewsGetResult =
+  PluginPresentationView.nullable()
+export type PluginPresentationViewsGetResult = z.infer<
+  typeof PluginPresentationViewsGetResult
+>
+
+/** Image format for {@linkcode PluginPresentationViewsApi.capture}. */
+export const PluginPresentationImageFormat = z.enum(["png", "jpeg"])
+export type PluginPresentationImageFormat = z.infer<
+  typeof PluginPresentationImageFormat
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.capture}. All optional.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `viewId` | `string \| undefined` | Capture this saved view; omit to capture the current viewport |
+ * | `format` | `"png" \| "jpeg" \| undefined` | Output image format (default `"png"`) |
+ * | `resolution` | `string \| undefined` | Optional resolution hint (e.g. `"1280x720"`) |
+ */
+export const PluginPresentationViewsCaptureArgs = z.object({
+  viewId: z.string().optional(),
+  format: PluginPresentationImageFormat.optional(),
+  resolution: z.string().optional(),
+})
+export type PluginPresentationViewsCaptureArgs = z.infer<
+  typeof PluginPresentationViewsCaptureArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.capture}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `image` | `string` | The captured image as a base64 data URL |
+ */
+export const PluginPresentationViewsCaptureResult = z.object({
+  image: z.string(),
+})
+export type PluginPresentationViewsCaptureResult = z.infer<
+  typeof PluginPresentationViewsCaptureResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to activate |
+ */
+export const PluginPresentationViewsSetActiveArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsSetActiveArgs = z.infer<
+  typeof PluginPresentationViewsSetActiveArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.setActive} — the active view's id. */
+export const PluginPresentationViewsSetActiveResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsSetActiveResult = z.infer<
+  typeof PluginPresentationViewsSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.create}. All optional.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string \| undefined` | Name for the new view (a default is used when omitted) |
+ * | `kind` | `"view" \| "sitePlan" \| undefined` | What kind of view to save (default `"view"`). `"plan"` is not offered — the host cannot create a plan view without a `planId` this API does not carry. |
+ */
+export const PluginPresentationViewsCreateArgs = z.object({
+  name: z.string().optional(),
+  kind: z.enum(["view", "sitePlan"]).optional(),
+})
+export type PluginPresentationViewsCreateArgs = z.infer<
+  typeof PluginPresentationViewsCreateArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.create} — the saved view. */
+export const PluginPresentationViewsCreateResult = PluginPresentationView
+export type PluginPresentationViewsCreateResult = z.infer<
+  typeof PluginPresentationViewsCreateResult
+>

package/src/api/program/adjacency.ts

@@ -0,0 +1,164 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program adjacency — the proximity relationships between departments or
+ * spaces.
+ *
+ * Adjacency is stage one of the product's space-planning workflow (compute →
+ * arrange → pack): the AI service scores which program elements need to be
+ * near each other, and the geometry contributes physical contact. Cell values:
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `2` | Direct — adjacency required |
+ * | `1` | Indirect — nearby preferred, or physical contact |
+ * | `-1` | Restricted — must NOT be adjacent |
+ * | `0` | No relationship — or adjacency was never computed |
+ *
+ * Zeros are ambiguous **by design** (the engine cannot distinguish "no
+ * relationship" from "never computed"): call
+ * {@linkcode PluginProgramAdjacencyApi.compute} first when you need fresh
+ * data. Persisted matrices auto-hydrate on scene load, so warm reads are the
+ * common case. The arrange/pack stages of the workflow live in
+ * {@linkcode PluginProgramLayoutApi} (`program.layout`).
+ *
+ * Accessed via `snaptrude.program.adjacency`.
+ */
+export abstract class PluginProgramAdjacencyApi {
+  constructor() {}
+
+  /**
+   * Read the adjacency matrix at the department or space level.
+   *
+   * Returns a square `matrix` whose rows/columns are aligned to `ids`
+   * (component ids). Pass `ids` to read a sub-matrix in that order; omit it to
+   * get every eligible element at that level. Cell values:
+   *
+   * | Value | Meaning |
+   * |---|---|
+   * | `2` | Direct — adjacency required |
+   * | `1` | Indirect — nearby preferred, or physical contact |
+   * | `-1` | Restricted — must NOT be adjacent |
+   * | `0` | No relationship — or adjacency was never computed |
+   *
+   * Zeros are ambiguous by design — call
+   * {@linkcode PluginProgramAdjacencyApi.compute} first for fresh data
+   * (persisted matrices auto-hydrate on scene load, so warm reads are the
+   * common case). Space-level relationships are computed within a storey:
+   * cross-storey pairs always read `0`. At the `department` level the result
+   * also carries `departmentIds`, a parallel array joining each row to the
+   * department entity ids returned by `program.departments.list` (the row
+   * `ids` are department-mass component ids, not department entity ids).
+   *
+   * @param level - Read the `"department"` or `"space"` matrix.
+   * @param ids - Component ids to read a sub-matrix for, in this order
+   *   (defaults to every eligible element at the level).
+   * @returns A {@linkcode PluginProgramAdjacencyGetMatrixResult} with `ids`,
+   *   the square `matrix`, and (at department level) `departmentIds`.
+   * @throws If an id is unknown or does not match the requested level.
+   *
+   * @examplePrompt Get the space adjacency matrix
+   * @examplePrompt Which departments must be adjacent?
+   * @examplePrompt Show the adjacency relationships between departments
+   * @examplePrompt Read the adjacency matrix for these spaces
+   * @examplePrompt Which rooms are restricted from being next to each other?
+   *
+   * # Example
+   * ```ts
+   * const { ids, matrix } = await snaptrude.program.adjacency.getMatrix("department")
+   * ```
+   */
+  public abstract getMatrix(
+    level: PluginAdjacencyLevel,
+    ids?: string[],
+  ): PluginApiReturn<PluginProgramAdjacencyGetMatrixResult>
+
+  /**
+   * Compute (or refresh) the adjacency data for the project.
+   *
+   * Runs the AI adjacency precompute and persists the result; a no-op when
+   * the stored data is already fresh. A real run takes **~2s at minimum**
+   * (engine pacing) plus the AI service round-trip. This is a write (it
+   * mutates and persists project analysis data), so it is blocked when plugin
+   * writes are disabled.
+   *
+   * @returns A {@linkcode PluginProgramAdjacencyComputeResult} —
+   *   `{ success: true }` when the data is fresh or the run completed;
+   *   `{ success: false, error }` when the AI service could not be reached.
+   *
+   * @examplePrompt Refresh adjacency analysis
+   * @examplePrompt Compute the adjacency matrix for this project
+   * @examplePrompt Recalculate which departments should be adjacent
+   *
+   * # Example
+   * ```ts
+   * const { success } = await snaptrude.program.adjacency.compute()
+   * if (success) {
+   *   const data = await snaptrude.program.adjacency.getMatrix("space")
+   * }
+   * ```
+   */
+  public abstract compute(): PluginApiReturn<PluginProgramAdjacencyComputeResult>
+}
+
+/**
+ * The level an adjacency matrix is read at.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"department"` | One row/column per department mass |
+ * | `"space"` | One row/column per space (within a storey) |
+ */
+export const PluginAdjacencyLevel = z.enum(["department", "space"])
+export type PluginAdjacencyLevel = z.infer<typeof PluginAdjacencyLevel>
+
+/**
+ * Arguments for {@linkcode PluginProgramAdjacencyApi.getMatrix}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `level` | {@linkcode PluginAdjacencyLevel} | Read the `"department"` or `"space"` matrix |
+ * | `ids` | `string[] \| undefined` | Component ids to read a sub-matrix for, in this order (defaults to every eligible element at the level) |
+ */
+export const PluginProgramAdjacencyGetMatrixArgs = z.object({
+  level: PluginAdjacencyLevel,
+  ids: z.array(z.string()).optional(),
+})
+export type PluginProgramAdjacencyGetMatrixArgs = z.infer<
+  typeof PluginProgramAdjacencyGetMatrixArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAdjacencyApi.getMatrix}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `ids` | `string[]` | Component ids, in matrix row/column order |
+ * | `departmentIds` | `(string \| null)[] \| undefined` | Department level only: parallel to `ids`, the department entity id each row belongs to (joinable against `program.departments.list`), `null` when unassigned |
+ * | `matrix` | `number[][]` | Square matrix aligned to `ids`; values in `{-1, 0, 1, 2}` |
+ */
+export const PluginProgramAdjacencyGetMatrixResult = z.object({
+  ids: z.array(z.string()),
+  departmentIds: z.array(z.string().nullable()).optional(),
+  matrix: z.array(z.array(z.number())),
+})
+export type PluginProgramAdjacencyGetMatrixResult = z.infer<
+  typeof PluginProgramAdjacencyGetMatrixResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramAdjacencyApi.compute}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | `true` when the data is fresh or the run completed |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export const PluginProgramAdjacencyComputeResult = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+export type PluginProgramAdjacencyComputeResult = z.infer<
+  typeof PluginProgramAdjacencyComputeResult
+>