@snaptrude/plugin-core 0.6.0 → 0.7.1

package/src/api/presentation/import.ts

@@ -4,9 +4,10 @@ import { PluginApiReturn } from "../../types"
 /**
  * Presentation import — bring external reference assets onto the Present canvas.
  *
- * `import.image` places a reference image and `import.pdf` places a PDF (each
- * page vectorized to SVG) onto the current Present sheet, returning the created
- * canvas shape ids. Requires Present mode to be open.
+ * `import.image` places a reference image, `import.pdf` places a PDF (each
+ * page vectorized to SVG), and `import.svg` places a validated SVG onto
+ * the current Present sheet, returning the created canvas shape ids. Requires
+ * Present mode to be open.
  *
  * The host engine takes a browser `File`, which a plugin worker cannot supply,
  * so these accept a `url`/`dataUrl` that the host adapts into a `File`.
@@ -72,11 +73,51 @@ export abstract class PluginPresentationImportApi {
     source: { url?: string; dataUrl?: string },
     options?: { position?: { x: number; y: number } },
   ): PluginApiReturn<PluginPresentationImportResult>
+
+  /**
+   * Import an SVG onto the current Present sheet as a vector asset.
+   *
+   * An SVG-validating variant of {@linkcode PluginPresentationImportApi.image}:
+   * `import.image` already passes SVG sources through, but this method first
+   * validates that the source really is an SVG and forces the vector mime
+   * type. Throws if the source is not an SVG.
+   *
+   * **Rendering is vector up to a complexity cap.** Simple SVGs (up to ~1500
+   * SVG element nodes and ~2 MB) render true-vector and stay crisp at every
+   * zoom. Beyond that cap the shared canvas renderer **intentionally falls
+   * back to a 1920px raster** to protect canvas performance, so very complex
+   * SVGs can look rasterized when zoomed in. The stored asset is the original
+   * SVG either way; only the on-canvas rendering falls back.
+   *
+   * @param source - The SVG to import: exactly one of `url` or `dataUrl`.
+   * @param options - Optional `position` — where to place the SVG on the sheet.
+   * @returns A {@linkcode PluginPresentationImportResult} with the created
+   *   `shapeIds`.
+   * @throws If Present mode is not open, the source is not an SVG, or it cannot
+   *   be loaded.
+   *
+   * @examplePrompt Import this SVG diagram onto the present canvas
+   * @examplePrompt Add a vector logo to my presentation board
+   * @examplePrompt Place this SVG floor plan on the current sheet as vectors
+   * @examplePrompt Bring a crisp vector graphic into Present mode
+   *
+   * # Example
+   * ```ts
+   * const { shapeIds } = await snaptrude.presentation.import.svg({
+   *   url: "https://example.com/diagram.svg",
+   * })
+   * ```
+   */
+  public abstract svg(
+    source: { url?: string; dataUrl?: string },
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginPresentationImportResult>
 }
 
 /**
  * Arguments for {@linkcode PluginPresentationImportApi.image} /
- * {@linkcode PluginPresentationImportApi.pdf}. Provide exactly one source.
+ * {@linkcode PluginPresentationImportApi.pdf} /
+ * {@linkcode PluginPresentationImportApi.svg}. Provide exactly one source.
  *
  * | Property | Type | Description |
  * |---|---|---|

package/src/api/presentation/index.ts

@@ -33,10 +33,9 @@ export abstract class PluginPresentationApi {
   public abstract import: PluginPresentationImportApi
   /**
    * Present-mode AI Inspiration image/video generation. See
-   * {@linkcode PluginPresentationAIInspirationApi}. _(authored ahead — optional
-   * until the host lands; the host implementation today is a stub.)_
+   * {@linkcode PluginPresentationAIInspirationApi}.
    */
-  public aiInspiration?: PluginPresentationAIInspirationApi
+  public abstract aiInspiration: PluginPresentationAIInspirationApi
 
   constructor() {}
 }

package/src/api/presentation/views.ts

@@ -6,12 +6,12 @@ import { PluginApiReturn } from "../../types"
  *
  * 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.
+ * the camera to it), save the current camera as a new view, and read/update a
+ * view's display settings (background, color mode, axis, edges, labels).
  *
- * `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.
+ * `list`/`get`/`getActive`/`capture`/`getSettings` are reads;
+ * `setActive`/`create`/`updateSettings` are writes (a view is a camera bookmark
+ * — not geometry).
  *
  * Accessed via `snaptrude.presentation.views`.
  */
@@ -153,6 +153,85 @@ export abstract class PluginPresentationViewsApi {
     name?: string,
     options?: { kind?: "view" | "sitePlan" },
   ): PluginApiReturn<PluginPresentationViewsCreateResult>
+
+  /**
+   * Read a saved view's display settings (background, color mode, axis, edges,
+   * labels).
+   *
+   * @param viewId - The id of the view to read settings for.
+   * @returns The view's {@linkcode PluginPresentationViewSettings}, or `null` if
+   *   no view has that id.
+   *
+   * @examplePrompt What color mode is the Ground Floor view using?
+   * @examplePrompt Get the display settings for this view
+   * @examplePrompt Does the site plan view show axes and labels?
+   * @examplePrompt Read the background color of the active view
+   *
+   * # Example
+   * ```ts
+   * const settings = await snaptrude.presentation.views.getSettings("view_123")
+   * if (settings) console.log(settings.colorMode, settings.backgroundColor)
+   * ```
+   */
+  public abstract getSettings(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsGetSettingsResult>
+
+  /**
+   * Update a saved view's display settings (partial patch — only the fields you
+   * pass change).
+   *
+   * Persists and broadcasts the change; if the view is currently active, the
+   * scene updates live. **Not Ctrl+Z-undoable** — view-metadata edits publish
+   * directly and do not land on the local undo stack; this matches how the
+   * product's own view-settings UI behaves.
+   *
+   * Label patch semantics (mirroring the product, which stores no label
+   * selection while labels are off):
+   *
+   * - `{ showLabels: true }` alone turns labels on; if the view has no stored
+   *   selection, the product defaults (`objectLabels`, `areas`) are applied —
+   *   labels are never "on" with an empty selection (the product has no such
+   *   state; labels render only while the selection is non-empty).
+   * - `{ labels: [...] }` alone sets the selection **and turns labels on**.
+   * - `{ showLabels: false }` turns labels off and **clears the stored
+   *   selection** — a later read returns `labels: []`.
+   * - `{ showLabels: false, labels: [...] }` with a non-empty list is
+   *   contradictory and **rejected** (nothing is silently discarded).
+   * - `{ showLabels: true, labels: [] }` is likewise contradictory and
+   *   **rejected** — pass a non-empty list, or omit `labels` to get the
+   *   defaults.
+   *
+   * `colorMode` accepts the `tag:<categoryId>` scheme strings returned by
+   * {@linkcode PluginPresentationViewsApi.getSettings}, so read-then-write
+   * round-trips a tag-based color scheme unchanged.
+   *
+   * @param viewId - The id of the view to update.
+   * @param settings - A partial {@linkcode PluginPresentationViewSettings}; any
+   *   omitted field is left unchanged.
+   * @returns The updated view's `id`.
+   * @throws If writes are disabled, no view has the given id, or the patch is
+   *   contradictory (`showLabels: false` with a non-empty `labels`, or
+   *   `showLabels: true` with an explicitly empty `labels` list).
+   *
+   * @examplePrompt Switch this view to monochrome color mode
+   * @examplePrompt Turn off the axis in the Ground Floor view
+   * @examplePrompt Set the background of the active view to white
+   * @examplePrompt Show area labels on this view
+   * @examplePrompt Enable hidden-line mode for the section view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.views.updateSettings("view_123", {
+   *   colorMode: "monochrome",
+   *   showAxis: false,
+   * })
+   * ```
+   */
+  public abstract updateSettings(
+    viewId: string,
+    settings: Partial<PluginPresentationViewSettings>,
+  ): PluginApiReturn<PluginPresentationViewsUpdateSettingsResult>
 }
 
 /**
@@ -301,3 +380,140 @@ export const PluginPresentationViewsCreateResult = PluginPresentationView
 export type PluginPresentationViewsCreateResult = z.infer<
   typeof PluginPresentationViewsCreateResult
 >
+
+/**
+ * How the scene is colored in a view.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `monochrome` | Flat single-tone shading |
+ * | `texture` | Material textures/colors |
+ * | `department` | Colored by department |
+ * | `tag:<categoryId>` | Colored by a project tag category (e.g. `tag:ZONE`) |
+ *
+ * The `tag:<categoryId>` form carries the product's tag-based color schemes
+ * losslessly — reading a view that uses one returns the `tag:` string as-is,
+ * and writing it back preserves the scheme (read-then-write is safe).
+ */
+export const PluginPresentationViewColorMode = z.union([
+  z.enum(["monochrome", "texture", "department"]),
+  z.templateLiteral(["tag:", z.string()]),
+])
+export type PluginPresentationViewColorMode = z.infer<
+  typeof PluginPresentationViewColorMode
+>
+
+/**
+ * A category of on-canvas labels a view can show.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `objectLabels` | Per-object name labels |
+ * | `areas` | Area/room labels |
+ * | `department` | Department labels |
+ */
+export const PluginPresentationViewLabel = z.enum([
+  "objectLabels",
+  "areas",
+  "department",
+])
+export type PluginPresentationViewLabel = z.infer<
+  typeof PluginPresentationViewLabel
+>
+
+/**
+ * A view's display settings.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `backgroundColor` | `string` | Canvas background as a hex color (e.g. `#ffffff`) |
+ * | `colorMode` | {@linkcode PluginPresentationViewColorMode} | How the scene is colored (including `tag:<categoryId>` schemes) |
+ * | `showAxis` | `boolean` | Whether the X/Y/Z axes are shown |
+ * | `showEdges` | `boolean` | Whether edges are shown; `false` = hidden-line rendering |
+ * | `showLabels` | `boolean` | Master label switch — whether on-canvas labels are shown at all. `true` always pairs with a non-empty `labels` selection (labels render only while the selection is non-empty; there is no labels-on-with-empty-selection state) |
+ * | `labels` | {@linkcode PluginPresentationViewLabel}`[]` | Which label categories are selected. When `showLabels` is `false` the view stores no selection and this reads `[]` |
+ */
+export const PluginPresentationViewSettings = z.object({
+  backgroundColor: z.string(),
+  colorMode: PluginPresentationViewColorMode,
+  showAxis: z.boolean(),
+  showEdges: z.boolean(),
+  showLabels: z.boolean(),
+  labels: z.array(PluginPresentationViewLabel),
+})
+export type PluginPresentationViewSettings = z.infer<
+  typeof PluginPresentationViewSettings
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.getSettings}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to read settings for |
+ */
+export const PluginPresentationViewsGetSettingsArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsGetSettingsArgs = z.infer<
+  typeof PluginPresentationViewsGetSettingsArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.getSettings} — the settings,
+ * or `null` when no view has that id.
+ */
+export const PluginPresentationViewsGetSettingsResult =
+  PluginPresentationViewSettings.nullable()
+export type PluginPresentationViewsGetSettingsResult = z.infer<
+  typeof PluginPresentationViewsGetSettingsResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.updateSettings}. The
+ * `settings` patch is partial — any omitted field is left unchanged. A patch
+ * pairing `showLabels: false` with a non-empty `labels` list, or
+ * `showLabels: true` with an explicitly empty `labels` list, is rejected as
+ * contradictory (see the method JSDoc for the full label patch semantics).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to update |
+ * | `settings` | `Partial<`{@linkcode PluginPresentationViewSettings}`>` | The fields to change |
+ */
+export const PluginPresentationViewsUpdateSettingsArgs = z
+  .object({
+    id: z.string(),
+    settings: PluginPresentationViewSettings.partial(),
+  })
+  .refine(
+    (v) =>
+      !(v.settings.showLabels === false && (v.settings.labels?.length ?? 0) > 0),
+    {
+      message:
+        "Contradictory patch: labels cannot be set while showLabels is false",
+    },
+  )
+  .refine(
+    (v) =>
+      !(
+        v.settings.showLabels === true &&
+        v.settings.labels !== undefined &&
+        v.settings.labels.length === 0
+      ),
+    {
+      message:
+        "Contradictory patch: showLabels cannot be true with an explicitly empty labels list — pass a non-empty list, or omit labels to apply the defaults",
+    },
+  )
+export type PluginPresentationViewsUpdateSettingsArgs = z.infer<
+  typeof PluginPresentationViewsUpdateSettingsArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.updateSettings} — the updated view's id. */
+export const PluginPresentationViewsUpdateSettingsResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsUpdateSettingsResult = z.infer<
+  typeof PluginPresentationViewsUpdateSettingsResult
+>

package/src/api/program/areas.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { PluginAreaUnit } from "./metrics"
+import { PluginAreaClass } from "../entity/space"
 import { ComponentHandle } from "../../handles"
 
 /**
@@ -12,15 +13,25 @@ import { ComponentHandle } from "../../handles"
  * department-allocation lens (targets vs allocated area per department); this
  * namespace is the whole-program area/FAR summary and its groupings.
  *
+ * **Net vs gross:** the `carpet` / `builtUp` / `excluded` figures are the three
+ * area *classes* — every space's whole footprint lands in exactly one, chosen
+ * by its `areaClass` (see {@linkcode PluginProgramAreaMember.areaClass}). In UI
+ * terms `carpet` is the **Net Internal Area** (Σ of `NET`-classed spaces), and
+ * `builtUp` is the **Gross External Area** (Σ of `GROSS`-classed spaces) — so
+ * "net" and "gross" are the plain-English synonyms for `carpet` and `builtUp`.
+ * These are not wall-thickness carpet-vs-super-built-up; there is no common-area
+ * math. Note the summary also folds in non-mass elements (floors count as NET,
+ * slabs as GROSS), so **summing `listMembers` spaces does not reconcile to the
+ * summary totals**.
+ *
  * `achievedFar` is **derived and read-only** — computed from built-up area and
  * site area. `targetFar` is the goal you set (via {@linkcode
  * PluginProgramAreasApi.update}); the two are the same ratio, one measured and
  * one intended. The surface speaks **FAR only** — there is no FSI alias.
  *
- * Reads return plain records and never throw. The write member typed as optional
- * (`?`) is **authored ahead of the host** — declared so plugins and codegen can
- * see the shape, but kept out of the discovery manifest until the host lands it
- * (at which point it is promoted to a required `abstract` member).
+ * Reads return plain records and never throw. The only write —
+ * {@linkcode PluginProgramAreasApi.update} — is a non-undoable settings write
+ * for the FAR inputs.
  *
  * Accessed via `snaptrude.program.areas`.
  */
@@ -38,6 +49,8 @@ export abstract class PluginProgramAreasApi {
    *
    * @examplePrompt What's my FAR right now?
    * @examplePrompt Give me the program area summary
+   * @examplePrompt What is my net internal area vs gross external area?
+   * @examplePrompt How much net and gross area do I have?
    * @examplePrompt How much built-up area have I used against the site area?
    * @examplePrompt Am I within my FAR target?
    *
@@ -62,6 +75,7 @@ export abstract class PluginProgramAreasApi {
    *   (empty when the program has no spaces).
    *
    * @examplePrompt Break down the area by storey
+   * @examplePrompt Break down net vs gross area by storey
    * @examplePrompt Show the area rollup per department
    * @examplePrompt Group the built-up area by building
    *
@@ -92,6 +106,7 @@ export abstract class PluginProgramAreasApi {
    *   array (empty when the group is missing or empty).
    *
    * @examplePrompt List the spaces on this storey with their areas
+   * @examplePrompt Which spaces are net and which are gross on this storey?
    * @examplePrompt What rooms are in the Bedrooms department bucket?
    * @examplePrompt Break the storey area down into individual spaces
    *
@@ -142,9 +157,9 @@ export abstract class PluginProgramAreasApi {
  * |---|---|---|
  * | `count` | `number` | Number of spaces in the program (a count, not an area) |
  * | `hiddenCount` | `number` | Number of those spaces that are currently hidden |
- * | `carpet` | `number` | Total carpet area in `areaUnit` |
- * | `builtUp` | `number` | Total built-up area in `areaUnit` |
- * | `excluded` | `number` | Total excluded area in `areaUnit` |
+ * | `carpet` | `number` | Total **Net Internal Area** ("net") — Σ `NET`-classed spaces + floors — in `areaUnit` |
+ * | `builtUp` | `number` | Total **Gross External Area** ("gross") — Σ `GROSS`-classed spaces + slabs — in `areaUnit` |
+ * | `excluded` | `number` | Total **Excluded Area** — Σ `EXCLUDED`-classed spaces — in `areaUnit` |
  * | `farBuiltUp` | `number` | Built-up area that counts toward FAR, in `areaUnit` |
  * | `siteArea` | `number` | Site/plot area in `areaUnit` |
  * | `achievedFar` | `number \| null` | Derived FAR (`farBuiltUp / siteArea`); `null` when site area or target FAR is unset |
@@ -177,8 +192,8 @@ export type PluginProgramAreaSummary = z.infer<typeof PluginProgramAreaSummary>
  * | `groupId` | `string` | Stable id of the group (e.g. storey id, department id) |
  * | `name` | `string` | Display name of the group |
  * | `color` | `string` | CSS hex color string for the group |
- * | `carpet` | `number` | Carpet area for this group |
- * | `builtUp` | `number` | Built-up area for this group |
+ * | `carpet` | `number` | Net Internal Area ("net") for this group |
+ * | `builtUp` | `number` | Gross External Area ("gross") for this group |
  * | `excluded` | `number` | Excluded area for this group |
  * | `count` | `number` | Number of spaces in this group |
  * | `targetArea` | `number` | Target area for this group, in `targetUnit` |
@@ -201,18 +216,25 @@ export type PluginProgramAreaGroup = z.infer<typeof PluginProgramAreaGroup>
  * A single space within an area group. Area figures are in the program's area
  * unit (see {@linkcode PluginProgramAreaSummary.areaUnit}).
  *
+ * `areaClass` is the space's effective classification — it decides which of the
+ * three buckets the space's whole footprint lands in: `NET` → `carpet` ("net"),
+ * `GROSS` → `builtUp` ("gross"), `EXCLUDED` → `excluded`. So for any one member
+ * exactly one of `carpet` / `builtUp` / `excluded` is non-zero.
+ *
  * | Property | Type | Description |
  * |---|---|---|
  * | `id` | `ComponentHandle` | `Component.id` of the space (never a mesh handle) |
  * | `label` | `string` | Display label of the space |
- * | `carpet` | `number` | Carpet area of the space |
- * | `builtUp` | `number` | Built-up area of the space |
- * | `excluded` | `number` | Excluded area of the space |
+ * | `areaClass` | {@linkcode PluginAreaClass} | Effective area class — `"NET"` (→ `carpet`), `"GROSS"` (→ `builtUp`), or `"EXCLUDED"` |
+ * | `carpet` | `number` | Net area of the space (non-zero when `areaClass` is `"NET"`) |
+ * | `builtUp` | `number` | Gross area of the space (non-zero when `areaClass` is `"GROSS"`) |
+ * | `excluded` | `number` | Excluded area of the space (non-zero when `areaClass` is `"EXCLUDED"`) |
  * | `isVisible` | `boolean` | Whether the space is currently visible |
  */
 export const PluginProgramAreaMember = z.object({
   id: ComponentHandle,
   label: z.string(),
+  areaClass: PluginAreaClass,
   carpet: z.number(),
   builtUp: z.number(),
   excluded: z.number(),

package/src/api/program/index.ts

@@ -19,7 +19,7 @@ import { PluginProgramAreasApi } from "./areas"
  *
  * - {@linkcode PluginProgramApi.departments} — Read & edit program departments (groupings + targets)
  * - {@linkcode PluginProgramApi.adjacency} — Read & compute the department/space adjacency matrix
- * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope (authored ahead)
+ * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope
  * - {@linkcode PluginProgramApi.metrics} — Read the area-program summary
  * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
  * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets and read it back
@@ -27,11 +27,6 @@ import { PluginProgramAreasApi } from "./areas"
  * - {@linkcode PluginProgramApi.cores} — Read & trigger vertical-circulation cores
  * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
  *
- * Sub-namespaces typed as optional (`?`) are **authored ahead of the host** —
- * declared so plugins and codegen can see the shape, but not required of host
- * implementations and kept out of the discovery manifest until the host lands
- * them (at which point they are promoted to required `abstract` members).
- *
  * Accessed via `snaptrude.program`.
  */
 export abstract class PluginProgramApi {
@@ -39,11 +34,8 @@ export abstract class PluginProgramApi {
   public abstract departments: PluginProgramDepartmentsApi
   /** Adjacency matrix — read & compute proximity relationships. See {@linkcode PluginProgramAdjacencyApi}. */
   public abstract adjacency: PluginProgramAdjacencyApi
-  /**
-   * Arrange/pack spaces in the envelope. See {@linkcode PluginProgramLayoutApi}.
-   * _(authored ahead — optional until the host lands it next increment.)_
-   */
-  public layout?: PluginProgramLayoutApi
+  /** Arrange/pack spaces in the envelope (async job family). See {@linkcode PluginProgramLayoutApi}. */
+  public abstract layout: PluginProgramLayoutApi
   /** Area-program summary — targets vs allocated area. See {@linkcode PluginProgramMetricsApi}. */
   public abstract metrics: PluginProgramMetricsApi
   /** FAR / built-up-area rollup and groupings. See {@linkcode PluginProgramAreasApi}. */