@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/core/index.ts

@@ -1,99 +1,99 @@
-import { PluginMathApi } from "./math"
-import { PluginGeomApi } from "./geom"
-import { PluginHistoryApi } from "./history"
-import { PluginUnitsApi } from "./units"
-import { PluginZoomApi } from "./zoom"
-import { PluginProjectApi } from "./project"
-import { PluginCommentApi } from "./comment"
-import { PluginCoreGroupsApi } from "./groups"
-import { PluginCoreBuildingsApi } from "./buildings"
-import { PluginCoreLayersApi } from "./layers"
-import { PluginCoreTagsApi } from "./tags"
-import { PluginCoreIoApi } from "./io"
-import { PluginCoreHandlesApi } from "./handles"
-import { PluginCoreProposalsApi } from "./proposals"
-import { PluginCameraApi } from "./camera"
-import { PluginCoreStoreysApi } from "./storeys"
-import { PluginCoreModeApi } from "./mode"
-import { PluginUserApi } from "./user"
-
-/**
- * Core primitives and infrastructure used across the plugin API.
- *
- * - {@linkcode PluginCoreApi.math} — Vector and quaternion operations
- * - {@linkcode PluginCoreApi.geom} — Geometry primitives (lines, arcs, curves, profiles)
- * - {@linkcode PluginCoreApi.history} — Undo / redo of committed history entries
- * - {@linkcode PluginCoreApi.units} — Unit-type queries and conversion
- * - {@linkcode PluginCoreApi.zoom} — Camera zoom controls (extents / selection)
- * - {@linkcode PluginCoreApi.camera} — Camera controls — position, standard views, 2D/3D mode
- * - {@linkcode PluginCoreApi.user} — User locale — timezone & language
- * - {@linkcode PluginCoreApi.project} — Project-level settings and info
- * - {@linkcode PluginCoreApi.comment} — Comments: create, edit, resolve, tag, list
- * - {@linkcode PluginCoreApi.groups} — Read & edit the group hierarchy
- * - {@linkcode PluginCoreApi.buildings} — Read & edit buildings and their storeys
- * - {@linkcode PluginCoreApi.storeys} — Create, read & edit storeys (floors); `storeys.layers` reads & toggles each storey's sketch surfaces and underlays
- * - {@linkcode PluginCoreApi.layers} — The Layers panel in the left sidebar: list, create, rename, lock, hide, activate, delete, move objects between layers
- * - {@linkcode PluginCoreApi.tags} — Tag catalog + assignment
- * - {@linkcode PluginCoreApi.io} — Import files (image/pdf/cad/model/terrain), poll jobs, manage underlays
- * - {@linkcode PluginCoreApi.handles} — Handle lifecycle: release, releaseAll, scopes
- * - {@linkcode PluginCoreApi.proposals} — Design options: read, create, rename, switch, delete
- */
-export abstract class PluginCoreApi {
-  /** Vector and quaternion math utilities. See {@linkcode PluginMathApi}. */
-  public abstract math: PluginMathApi
-  /** Geometry primitives and constructors. See {@linkcode PluginGeomApi}. */
-  public abstract geom: PluginGeomApi
-  /** Undo / redo of committed history entries. See {@linkcode PluginHistoryApi}. */
-  public abstract history: PluginHistoryApi
-  /** Unit-type queries and conversion. See {@linkcode PluginUnitsApi}. */
-  public abstract units: PluginUnitsApi
-  /** Camera zoom controls. See {@linkcode PluginZoomApi}. */
-  public abstract zoom: PluginZoomApi
-  /** Camera controls — position, standard views, 2D/3D mode. See {@linkcode PluginCameraApi}. */
-  public abstract camera: PluginCameraApi
-  /** User locale — timezone & language. See {@linkcode PluginUserApi}. */
-  public abstract user: PluginUserApi
-  /** Project-level settings and info. See {@linkcode PluginProjectApi}. */
-  public abstract project: PluginProjectApi
-  /** Comments — create, edit, resolve, tag, list. See {@linkcode PluginCommentApi}. */
-  public abstract comment: PluginCommentApi
-  /** Groups — read & edit the group hierarchy. See {@linkcode PluginCoreGroupsApi}. */
-  public abstract groups: PluginCoreGroupsApi
-  /** Buildings — read & edit buildings and their storeys. See {@linkcode PluginCoreBuildingsApi}. */
-  public abstract buildings: PluginCoreBuildingsApi
-  /** Storeys — create, read & edit storeys (floors), plus each storey's sketch surfaces and underlays (`storeys.layers`). See {@linkcode PluginCoreStoreysApi}. */
-  public abstract storeys: PluginCoreStoreysApi
-  /** Application mode — read & switch the editor's top-bar mode. See {@linkcode PluginCoreModeApi}. */
-  public abstract mode: PluginCoreModeApi
-  /** Layers — the Layers panel's layers: list, create, rename, lock, hide, activate, delete, assign objects. See {@linkcode PluginCoreLayersApi}. */
-  public abstract layers: PluginCoreLayersApi
-  /** Tags — tag catalog + assignment. See {@linkcode PluginCoreTagsApi}. */
-  public abstract tags: PluginCoreTagsApi
-  /** I/O — file import, import jobs, and underlay management. See {@linkcode PluginCoreIoApi}. */
-  public abstract io: PluginCoreIoApi
-  /** Handle lifecycle — release, releaseAll, and mint-recording scopes. See {@linkcode PluginCoreHandlesApi}. */
-  public abstract handles: PluginCoreHandlesApi
-  /** Proposals — design options: read, create, rename, switch, delete. See {@linkcode PluginCoreProposalsApi}. */
-  public abstract proposals: PluginCoreProposalsApi
-
-  constructor() {}
-}
-
-export * from "./math"
-export * from "./geom"
-export * from "./history"
-export * from "./units"
-export * from "./zoom"
-export * from "./camera"
-export * from "./user"
-export * from "./project"
-export * from "./comment"
-export * from "./groups"
-export * from "./buildings"
-export * from "./storeys"
-export * from "./mode"
-export * from "./layers"
-export * from "./tags"
-export * from "./io"
-export * from "./handles"
-export * from "./proposals"
+import { PluginMathApi } from "./math"
+import { PluginGeomApi } from "./geom"
+import { PluginHistoryApi } from "./history"
+import { PluginUnitsApi } from "./units"
+import { PluginZoomApi } from "./zoom"
+import { PluginProjectApi } from "./project"
+import { PluginCommentApi } from "./comment"
+import { PluginCoreGroupsApi } from "./groups"
+import { PluginCoreBuildingsApi } from "./buildings"
+import { PluginCoreLayersApi } from "./layers"
+import { PluginCoreTagsApi } from "./tags"
+import { PluginCoreIoApi } from "./io"
+import { PluginCoreHandlesApi } from "./handles"
+import { PluginCoreProposalsApi } from "./proposals"
+import { PluginCameraApi } from "./camera"
+import { PluginCoreStoreysApi } from "./storeys"
+import { PluginCoreModeApi } from "./mode"
+import { PluginUserApi } from "./user"
+
+/**
+ * Core primitives and infrastructure used across the plugin API.
+ *
+ * - {@linkcode PluginCoreApi.math} — Vector and quaternion operations
+ * - {@linkcode PluginCoreApi.geom} — Geometry primitives (lines, arcs, curves, profiles)
+ * - {@linkcode PluginCoreApi.history} — Undo / redo of committed history entries
+ * - {@linkcode PluginCoreApi.units} — Unit-type queries and conversion
+ * - {@linkcode PluginCoreApi.zoom} — Camera zoom controls (extents / selection)
+ * - {@linkcode PluginCoreApi.camera} — Camera controls — position, standard views, 2D/3D mode
+ * - {@linkcode PluginCoreApi.user} — User locale — timezone & language
+ * - {@linkcode PluginCoreApi.project} — Project-level settings and info
+ * - {@linkcode PluginCoreApi.comment} — Comments: create, edit, resolve, tag, list
+ * - {@linkcode PluginCoreApi.groups} — Read & edit the group hierarchy
+ * - {@linkcode PluginCoreApi.buildings} — Read & edit buildings and their storeys
+ * - {@linkcode PluginCoreApi.storeys} — Create, read & edit storeys (floors); `storeys.layers` reads & toggles each storey's sketch surfaces and underlays
+ * - {@linkcode PluginCoreApi.layers} — The Layers panel in the left sidebar: list, create, rename, lock, hide, activate, delete, move objects between layers
+ * - {@linkcode PluginCoreApi.tags} — Tag catalog + assignment
+ * - {@linkcode PluginCoreApi.io} — Import files (image/pdf/cad/model/terrain), poll jobs, manage underlays
+ * - {@linkcode PluginCoreApi.handles} — Handle lifecycle: release, releaseAll, scopes
+ * - {@linkcode PluginCoreApi.proposals} — Design options: read, create, rename, switch, delete
+ */
+export abstract class PluginCoreApi {
+  /** Vector and quaternion math utilities. See {@linkcode PluginMathApi}. */
+  public abstract math: PluginMathApi
+  /** Geometry primitives and constructors. See {@linkcode PluginGeomApi}. */
+  public abstract geom: PluginGeomApi
+  /** Undo / redo of committed history entries. See {@linkcode PluginHistoryApi}. */
+  public abstract history: PluginHistoryApi
+  /** Unit-type queries and conversion. See {@linkcode PluginUnitsApi}. */
+  public abstract units: PluginUnitsApi
+  /** Camera zoom controls. See {@linkcode PluginZoomApi}. */
+  public abstract zoom: PluginZoomApi
+  /** Camera controls — position, standard views, 2D/3D mode. See {@linkcode PluginCameraApi}. */
+  public abstract camera: PluginCameraApi
+  /** User locale — timezone & language. See {@linkcode PluginUserApi}. */
+  public abstract user: PluginUserApi
+  /** Project-level settings and info. See {@linkcode PluginProjectApi}. */
+  public abstract project: PluginProjectApi
+  /** Comments — create, edit, resolve, tag, list. See {@linkcode PluginCommentApi}. */
+  public abstract comment: PluginCommentApi
+  /** Groups — read & edit the group hierarchy. See {@linkcode PluginCoreGroupsApi}. */
+  public abstract groups: PluginCoreGroupsApi
+  /** Buildings — read & edit buildings and their storeys. See {@linkcode PluginCoreBuildingsApi}. */
+  public abstract buildings: PluginCoreBuildingsApi
+  /** Storeys — create, read & edit storeys (floors), plus each storey's sketch surfaces and underlays (`storeys.layers`). See {@linkcode PluginCoreStoreysApi}. */
+  public abstract storeys: PluginCoreStoreysApi
+  /** Application mode — read & switch the editor's top-bar mode. See {@linkcode PluginCoreModeApi}. */
+  public abstract mode: PluginCoreModeApi
+  /** Layers — the Layers panel's layers: list, create, rename, lock, hide, activate, delete, assign objects. See {@linkcode PluginCoreLayersApi}. */
+  public abstract layers: PluginCoreLayersApi
+  /** Tags — tag catalog + assignment. See {@linkcode PluginCoreTagsApi}. */
+  public abstract tags: PluginCoreTagsApi
+  /** I/O — file import, import jobs, and underlay management. See {@linkcode PluginCoreIoApi}. */
+  public abstract io: PluginCoreIoApi
+  /** Handle lifecycle — release, releaseAll, and mint-recording scopes. See {@linkcode PluginCoreHandlesApi}. */
+  public abstract handles: PluginCoreHandlesApi
+  /** Proposals — design options: read, create, rename, switch, delete. See {@linkcode PluginCoreProposalsApi}. */
+  public abstract proposals: PluginCoreProposalsApi
+
+  constructor() {}
+}
+
+export * from "./math"
+export * from "./geom"
+export * from "./history"
+export * from "./units"
+export * from "./zoom"
+export * from "./camera"
+export * from "./user"
+export * from "./project"
+export * from "./comment"
+export * from "./groups"
+export * from "./buildings"
+export * from "./storeys"
+export * from "./mode"
+export * from "./layers"
+export * from "./tags"
+export * from "./io"
+export * from "./handles"
+export * from "./proposals"

package/src/api/core/io/export/index.ts

@@ -1,126 +1,126 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-
-/**
- * Serialization format for {@link PluginCoreIoExportApi.model}.
- *
- * `glb` / `obj` serialize in the browser; `fbx` / `3ds` run the same server
- * conversion the app's Export dialog uses and return a **zip** containing the
- * converted file.
- */
-export const ExportModelFormat = z.enum(["glb", "obj", "fbx", "3ds"])
-export type ExportModelFormat = z.infer<typeof ExportModelFormat>
-
-/**
- * What to export: the whole model (`"scene"`, default) or only the current
- * selection (`"selection"`).
- */
-export const ExportScope = z.enum(["scene", "selection"])
-export type ExportScope = z.infer<typeof ExportScope>
-
-/**
- * A serialized model file returned by {@link PluginCoreIoExportApi.model}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `fileName` | `string` | Suggested file name incl. extension (e.g. `"model.glb"`) |
- * | `mimeType` | `string` | MIME type (`"model/gltf-binary"` for glb, `"text/plain"` for obj) |
- * | `dataBase64` | `string` | The file's bytes, base64-encoded (decode to save/download) |
- */
-export const ExportedFile = z.object({
-  fileName: z.string(),
-  mimeType: z.string(),
-  dataBase64: z.string(),
-})
-export type ExportedFile = z.infer<typeof ExportedFile>
-
-/**
- * Model export — serialize the scene (or selection) to a downloadable 3D file.
- *
- * `core.io.export.model` hands you the file bytes as base64 — no download
- * dialog opens; the plugin decides what to do with the result (save it, POST
- * it, diff it). For a different export intent, see `presentation.export`
- * (Present-mode layout sheets to PDF/PNG/JPG) and `program.spreadsheet.export`
- * (the area-program / takeoff workbook). Four formats:
- *
- * - `"glb"` — binary glTF (`model/gltf-binary`); geometry + materials,
- *   serialized in the browser (nothing is uploaded).
- * - `"obj"` — Wavefront OBJ text (`text/plain`); geometry only, serialized in
- *   the browser.
- * - `"fbx"` / `"3ds"` — Autodesk FBX / 3D Studio; the scene is uploaded to the
- *   same `/exportmodel/` conversion service the app's Export dialog uses, and
- *   the call resolves once the converted artifact is fetched back — a **zip**
- *   (`application/zip`) containing the `.fbx`/`.3ds` file. Whole-scene only
- *   (`scope: "selection"` is rejected). Conversion runs on the server and is
- *   bounded by the per-call plugin timeout (60 s) — very large models may
- *   exceed it and reject with `TIMEOUT`.
- *
- * For the browser formats, only real model geometry is exported (walls, slabs,
- * roofs, floors, doors, windows, furniture, staircases, masses, ceilings,
- * mullions, beams, columns, terrain); UI helpers, hidden objects, and
- * hidden-bucket objects are excluded — matching the app's GLB export. The
- * server formats convert the full serialized scene (hidden-bucket objects
- * excluded), exactly like the Export dialog. This is a **read**: it never
- * mutates the model.
- *
- * > Server-backed BIM exports (RVT / IFC / DWG) are **not** exposed here — those
- * > run as fire-and-forget Forge jobs that stream a browser download and return
- * > no retrievable bytes. Use the app's Export menu for those.
- *
- * Accessed via `snaptrude.core.io.export`.
- */
-export abstract class PluginCoreIoExportApi {
-  constructor() {}
-
-  /**
-   * Export the model to a 3D file and return its bytes as base64.
-   *
-   * @param format - `"glb"` (binary glTF, geometry + materials), `"obj"`
-   *   (Wavefront OBJ text, geometry only) — both serialized in the browser —
-   *   or `"fbx"` / `"3ds"`, converted by the app's export service and returned
-   *   as a zip containing the converted file.
-   * @param scope - `"scene"` (default) for the whole model, or `"selection"` for
-   *   only the currently selected objects (browser formats only — `"fbx"`/`"3ds"`
-   *   reject it). An empty selection yields an empty file.
-   * @returns an {@linkcode ExportedFile} — `{ fileName, mimeType, dataBase64 }`.
-   * @throws if the format is unsupported, `scope: "selection"` is combined with a
-   *   server format, or the serialization/conversion fails.
-   *
-   * @examplePrompt Export the model as a GLB
-   * @examplePrompt Give me the whole scene as an OBJ file
-   * @examplePrompt Export just my selection to GLB
-   * @examplePrompt Download the model as an FBX file
-   * @examplePrompt Export the scene to 3DS for 3ds Max
-   *
-   * # Example
-   * ```ts
-   * const file = await snaptrude.core.io.export.model("glb")
-   * // decode base64 → bytes and save/download in the plugin UI
-   * const bytes = Uint8Array.from(atob(file.dataBase64), (c) => c.charCodeAt(0))
-   * const blob = new Blob([bytes], { type: file.mimeType })
-   * // ...offer blob for download as file.fileName
-   *
-   * // Only the current selection, as OBJ text:
-   * const obj = await snaptrude.core.io.export.model("obj", "selection")
-   * const text = atob(obj.dataBase64)
-   * ```
-   */
-  public abstract model(
-    format: ExportModelFormat,
-    scope?: ExportScope,
-  ): PluginApiReturn<ExportedFile>
-}
-
-/**
- * Arguments for {@link PluginCoreIoExportApi.model}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `format` | {@link ExportModelFormat} | `"glb"`, `"obj"`, `"fbx"`, or `"3ds"` |
- * | `scope` | {@link ExportScope} | `"scene"` (default) or `"selection"` (browser formats only) |
- */
-export const PluginExportModelArgs = z.object({
-  format: ExportModelFormat,
-  scope: ExportScope.optional(),
-})
-export type PluginExportModelArgs = z.infer<typeof PluginExportModelArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+
+/**
+ * Serialization format for {@link PluginCoreIoExportApi.model}.
+ *
+ * `glb` / `obj` serialize in the browser; `fbx` / `3ds` run the same server
+ * conversion the app's Export dialog uses and return a **zip** containing the
+ * converted file.
+ */
+export const ExportModelFormat = z.enum(["glb", "obj", "fbx", "3ds"])
+export type ExportModelFormat = z.infer<typeof ExportModelFormat>
+
+/**
+ * What to export: the whole model (`"scene"`, default) or only the current
+ * selection (`"selection"`).
+ */
+export const ExportScope = z.enum(["scene", "selection"])
+export type ExportScope = z.infer<typeof ExportScope>
+
+/**
+ * A serialized model file returned by {@link PluginCoreIoExportApi.model}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `fileName` | `string` | Suggested file name incl. extension (e.g. `"model.glb"`) |
+ * | `mimeType` | `string` | MIME type (`"model/gltf-binary"` for glb, `"text/plain"` for obj) |
+ * | `dataBase64` | `string` | The file's bytes, base64-encoded (decode to save/download) |
+ */
+export const ExportedFile = z.object({
+  fileName: z.string(),
+  mimeType: z.string(),
+  dataBase64: z.string(),
+})
+export type ExportedFile = z.infer<typeof ExportedFile>
+
+/**
+ * Model export — serialize the scene (or selection) to a downloadable 3D file.
+ *
+ * `core.io.export.model` hands you the file bytes as base64 — no download
+ * dialog opens; the plugin decides what to do with the result (save it, POST
+ * it, diff it). For a different export intent, see `presentation.export`
+ * (Present-mode layout sheets to PDF/PNG/JPG) and `program.spreadsheet.export`
+ * (the area-program / takeoff workbook). Four formats:
+ *
+ * - `"glb"` — binary glTF (`model/gltf-binary`); geometry + materials,
+ *   serialized in the browser (nothing is uploaded).
+ * - `"obj"` — Wavefront OBJ text (`text/plain`); geometry only, serialized in
+ *   the browser.
+ * - `"fbx"` / `"3ds"` — Autodesk FBX / 3D Studio; the scene is uploaded to the
+ *   same `/exportmodel/` conversion service the app's Export dialog uses, and
+ *   the call resolves once the converted artifact is fetched back — a **zip**
+ *   (`application/zip`) containing the `.fbx`/`.3ds` file. Whole-scene only
+ *   (`scope: "selection"` is rejected). Conversion runs on the server and is
+ *   bounded by the per-call plugin timeout (60 s) — very large models may
+ *   exceed it and reject with `TIMEOUT`.
+ *
+ * For the browser formats, only real model geometry is exported (walls, slabs,
+ * roofs, floors, doors, windows, furniture, staircases, masses, ceilings,
+ * mullions, beams, columns, terrain); UI helpers, hidden objects, and
+ * hidden-bucket objects are excluded — matching the app's GLB export. The
+ * server formats convert the full serialized scene (hidden-bucket objects
+ * excluded), exactly like the Export dialog. This is a **read**: it never
+ * mutates the model.
+ *
+ * > Server-backed BIM exports (RVT / IFC / DWG) are **not** exposed here — those
+ * > run as fire-and-forget Forge jobs that stream a browser download and return
+ * > no retrievable bytes. Use the app's Export menu for those.
+ *
+ * Accessed via `snaptrude.core.io.export`.
+ */
+export abstract class PluginCoreIoExportApi {
+  constructor() {}
+
+  /**
+   * Export the model to a 3D file and return its bytes as base64.
+   *
+   * @param format - `"glb"` (binary glTF, geometry + materials), `"obj"`
+   *   (Wavefront OBJ text, geometry only) — both serialized in the browser —
+   *   or `"fbx"` / `"3ds"`, converted by the app's export service and returned
+   *   as a zip containing the converted file.
+   * @param scope - `"scene"` (default) for the whole model, or `"selection"` for
+   *   only the currently selected objects (browser formats only — `"fbx"`/`"3ds"`
+   *   reject it). An empty selection yields an empty file.
+   * @returns an {@linkcode ExportedFile} — `{ fileName, mimeType, dataBase64 }`.
+   * @throws if the format is unsupported, `scope: "selection"` is combined with a
+   *   server format, or the serialization/conversion fails.
+   *
+   * @examplePrompt Export the model as a GLB
+   * @examplePrompt Give me the whole scene as an OBJ file
+   * @examplePrompt Export just my selection to GLB
+   * @examplePrompt Download the model as an FBX file
+   * @examplePrompt Export the scene to 3DS for 3ds Max
+   *
+   * # Example
+   * ```ts
+   * const file = await snaptrude.core.io.export.model("glb")
+   * // decode base64 → bytes and save/download in the plugin UI
+   * const bytes = Uint8Array.from(atob(file.dataBase64), (c) => c.charCodeAt(0))
+   * const blob = new Blob([bytes], { type: file.mimeType })
+   * // ...offer blob for download as file.fileName
+   *
+   * // Only the current selection, as OBJ text:
+   * const obj = await snaptrude.core.io.export.model("obj", "selection")
+   * const text = atob(obj.dataBase64)
+   * ```
+   */
+  public abstract model(
+    format: ExportModelFormat,
+    scope?: ExportScope,
+  ): PluginApiReturn<ExportedFile>
+}
+
+/**
+ * Arguments for {@link PluginCoreIoExportApi.model}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `format` | {@link ExportModelFormat} | `"glb"`, `"obj"`, `"fbx"`, or `"3ds"` |
+ * | `scope` | {@link ExportScope} | `"scene"` (default) or `"selection"` (browser formats only) |
+ */
+export const PluginExportModelArgs = z.object({
+  format: ExportModelFormat,
+  scope: ExportScope.optional(),
+})
+export type PluginExportModelArgs = z.infer<typeof PluginExportModelArgs>