@snaptrude/plugin-core 0.7.0 → 0.8.0

package/dist/api/core/handles/index.d.ts

@@ -0,0 +1,210 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+import type { AnyArenaHandle } from "../../../handles";
+/**
+ * The 12 registry-arena handle kinds — the releasable families. Entity-style
+ * handles (component / material / underlay / terrain / importJob / comment) are
+ * raw engine ids with no arena entry and therefore no lifecycle: passing one to
+ * `release` is a silent no-op like any other unknown id.
+ */
+export declare const ArenaKind: z.ZodEnum<{
+    vec3: "vec3";
+    quat: "quat";
+    line: "line";
+    arc: "arc";
+    circle: "circle";
+    profile: "profile";
+    contour: "contour";
+    brep: "brep";
+    face: "face";
+    edge: "edge";
+    halfedge: "halfedge";
+    vertex: "vertex";
+}>;
+export type ArenaKind = z.infer<typeof ArenaKind>;
+/** Max handles accepted by a single `release` / `endScope(retain)` call. */
+export declare const RELEASE_BATCH_MAX = 10000;
+/**
+ * An opaque token identifying a handle scope opened by
+ * {@linkcode PluginCoreHandlesApi.beginScope}. It is NOT an arena handle —
+ * it pins no memory, and `release(token)` is a silent no-op; only
+ * {@linkcode PluginCoreHandlesApi.endScope} consumes it.
+ */
+export type ScopeToken = string;
+/**
+ * Handle lifecycle — free host-side handle registry entries the plugin no
+ * longer needs, individually ({@linkcode release}), by kind
+ * ({@linkcode releaseAll}), or as a mint-recording region
+ * ({@linkcode beginScope} / {@linkcode endScope}).
+ *
+ * Releasing is a handle-lifecycle operation only: it frees the registry entry
+ * (host memory + quota room) and makes the handle unresolvable. It never
+ * deletes engine-side geometry or scene entities.
+ *
+ * Accessed via `snaptrude.core.handles`.
+ */
+export declare abstract class PluginCoreHandlesApi {
+    constructor();
+    /**
+     * Free arena handles in bulk. Unknown, foreign, or already-released ids are
+     * silent no-ops — there is no per-id result and no count, so responses can
+     * never be used as an existence oracle.
+     *
+     * @param handles The handles to release (max {@linkcode RELEASE_BATCH_MAX} per call)
+     * @returns Nothing
+     *
+     * # Example
+     * ```ts
+     * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+     * // ... read what you need ...
+     * await snaptrude.core.handles.release(faces)
+     * ```
+     */
+    abstract release(handles: ReadonlyArray<AnyArenaHandle>): PluginApiReturn<void>;
+    /**
+     * Free every live arena handle of one kind, or ALL arena handles when the
+     * kind is omitted. Useful at batch boundaries — e.g. a poll loop that mints
+     * a fresh footprint contour per tick.
+     *
+     * @param kind Optional arena kind to restrict the sweep to
+     * @returns Nothing
+     *
+     * # Example
+     * ```ts
+     * const footprint = await snaptrude.design.query.spaces.getFootprint(space)
+     * // ... measure ...
+     * await snaptrude.core.handles.releaseAll("contour")
+     * ```
+     */
+    abstract releaseAll(kind?: ArenaKind): PluginApiReturn<void>;
+    /**
+     * Open a mint-recording scope: every arena handle MINTED after this call
+     * (fresh mints only — identity-deduped re-registrations of pre-existing
+     * objects are not captured) is freed when the matching
+     * {@linkcode endScope} runs. Scopes nest, up to 64 deep — always pair
+     * begin/end in try/finally.
+     *
+     * @returns The scope token to pass to {@linkcode endScope}
+     *
+     * # Example
+     * ```ts
+     * for (const space of spaces) {
+     *   const scope = await snaptrude.core.handles.beginScope()
+     *   try {
+     *     const footprint = await snaptrude.design.query.spaces.getFootprint(space)
+     *     const area = await snaptrude.core.geom.query.contour.getArea(footprint)
+     *   } finally {
+     *     await snaptrude.core.handles.endScope(scope) // footprint (and intermediates) freed
+     *   }
+     * }
+     * ```
+     */
+    abstract beginScope(): PluginApiReturn<ScopeToken>;
+    /**
+     * Close a scope by its token and free every handle it recorded, except those
+     * listed in `retain`. Retained handles are promoted to the enclosing scope
+     * (if any), so nesting composes like block scopes. Closing is
+     * token-addressed: an out-of-order close (interleaved async tasks) frees
+     * only that scope's mints and leaves other open scopes intact. Always pair
+     * begin/end in try/finally so a thrown body cannot leak the scope.
+     *
+     * @param scope The token returned by the matching {@linkcode beginScope}
+     * @param retain Handles minted inside the scope that must survive it
+     * @returns Nothing
+     *
+     * # Example
+     * ```ts
+     * const scope = await snaptrude.core.handles.beginScope()
+     * const outline = await snaptrude.design.query.spaces.getFootprint(space)
+     * const outer = await snaptrude.core.geom.query.contour.getOuterProfile(outline)
+     * await snaptrude.core.handles.endScope(scope, [outer]) // outline freed, outer survives
+     * ```
+     */
+    abstract endScope(scope: ScopeToken, retain?: ReadonlyArray<AnyArenaHandle>): PluginApiReturn<void>;
+    /**
+     * Live handle-registry statistics for the calling plugin, plus the host
+     * page's JS heap usage (when the browser exposes it). Diagnostic surface for
+     * verifying that releases actually shrink host memory.
+     *
+     * @returns Arena entry counts, open scope depth, and host heap bytes
+     *
+     * # Example
+     * ```ts
+     * const before = await snaptrude.core.handles.stats()
+     * await snaptrude.core.handles.releaseAll("vec3")
+     * const after = await snaptrude.core.handles.stats()
+     * console.log(`freed ${before.values - after.values} value entries`)
+     * ```
+     */
+    abstract stats(): PluginApiReturn<PluginHandlesStatsResult>;
+}
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.release}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `handles` | `string[]` | Handles to release (≤ {@linkcode RELEASE_BATCH_MAX}) |
+ */
+export declare const PluginHandlesReleaseArgs: z.ZodObject<{
+    handles: z.ZodArray<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>>;
+}, z.core.$strip>;
+export type PluginHandlesReleaseArgs = z.infer<typeof PluginHandlesReleaseArgs>;
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.releaseAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode ArenaKind} (optional) | Restrict the sweep to one kind |
+ */
+export declare const PluginHandlesReleaseAllArgs: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodEnum<{
+        vec3: "vec3";
+        quat: "quat";
+        line: "line";
+        arc: "arc";
+        circle: "circle";
+        profile: "profile";
+        contour: "contour";
+        brep: "brep";
+        face: "face";
+        edge: "edge";
+        halfedge: "halfedge";
+        vertex: "vertex";
+    }>>;
+}, z.core.$strip>;
+export type PluginHandlesReleaseAllArgs = z.infer<typeof PluginHandlesReleaseAllArgs>;
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.endScope}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `scope` | {@linkcode ScopeToken} | Token from the matching `beginScope` |
+ * | `retain` | `string[]` (optional) | Scope-minted handles that must survive |
+ */
+export declare const PluginHandlesEndScopeArgs: z.ZodObject<{
+    scope: z.ZodString;
+    retain: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>>>;
+}, z.core.$strip>;
+export type PluginHandlesEndScopeArgs = z.infer<typeof PluginHandlesEndScopeArgs>;
+/**
+ * Result of {@linkcode PluginCoreHandlesApi.stats}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `resources` | `number` | Live resource-arena entries (profile/contour) |
+ * | `values` | `number` | Live value-arena entries (vec3/quat/line/arc/circle) |
+ * | `topology` | `number` | Live topology-arena entries (brep/face/edge/halfedge/vertex) |
+ * | `scopes` | `number` | Currently open handle scopes |
+ * | `hostHeapUsedBytes` | `number \| null` | Host page `usedJSHeapSize` (null where unsupported) |
+ * | `hostHeapTotalBytes` | `number \| null` | Host page `totalJSHeapSize` (null where unsupported) |
+ */
+export declare const PluginHandlesStatsResult: z.ZodObject<{
+    resources: z.ZodNumber;
+    values: z.ZodNumber;
+    topology: z.ZodNumber;
+    scopes: z.ZodNumber;
+    hostHeapUsedBytes: z.ZodNullable<z.ZodNumber>;
+    hostHeapTotalBytes: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginHandlesStatsResult = z.infer<typeof PluginHandlesStatsResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/handles/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/handles/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGtD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;EAapB,CAAA;AACF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAEjD,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,QAAS,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAE/B;;;;;;;;;;;GAWG;AACH,8BAAsB,oBAAoB;;IAGxC;;;;;;;;;;;;;;OAcG;aACa,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC;IAEtF;;;;;;;;;;;;;;OAcG;aACa,UAAU,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,eAAe,CAAC,IAAI,CAAC;IAEnE;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,UAAU,IAAI,eAAe,CAAC,UAAU,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,QAAQ,CACtB,KAAK,EAAE,UAAU,EACjB,MAAM,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,GACrC,eAAe,CAAC,IAAI,CAAC;IAExB;;;;;;;;;;;;;;OAcG;aACa,KAAK,IAAI,eAAe,CAAC,wBAAwB,CAAC;CACnE;AAoBD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;iBAEnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;iBAEtC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;iBAGpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB;;;;;;;iBAOnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA"}

package/dist/api/core/index.d.ts

@@ -10,7 +10,10 @@ 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 { PluginUserApi } from "./user";
 /**
  * Core primitives and infrastructure used across the plugin API.
  *
@@ -19,6 +22,8 @@ import { PluginCoreProposalsApi } from "./proposals";
  * - {@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
@@ -26,6 +31,7 @@ import { PluginCoreProposalsApi } from "./proposals";
  * - {@linkcode PluginCoreApi.layers} — Read & toggle storey drawing/reference 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 declare abstract class PluginCoreApi {
@@ -39,6 +45,10 @@ export declare abstract class PluginCoreApi {
     abstract units: PluginUnitsApi;
     /** Camera zoom controls. See {@linkcode PluginZoomApi}. */
     abstract zoom: PluginZoomApi;
+    /** Camera controls — position, standard views, 2D/3D mode. See {@linkcode PluginCameraApi}. */
+    abstract camera: PluginCameraApi;
+    /** User locale — timezone & language. See {@linkcode PluginUserApi}. */
+    abstract user: PluginUserApi;
     /** Project-level settings and info. See {@linkcode PluginProjectApi}. */
     abstract project: PluginProjectApi;
     /** Comments — create, edit, resolve, tag, list. See {@linkcode PluginCommentApi}. */
@@ -53,6 +63,8 @@ export declare abstract class PluginCoreApi {
     abstract tags: PluginCoreTagsApi;
     /** I/O — file import, import jobs, and underlay management. See {@linkcode PluginCoreIoApi}. */
     abstract io: PluginCoreIoApi;
+    /** Handle lifecycle — release, releaseAll, and mint-recording scopes. See {@linkcode PluginCoreHandlesApi}. */
+    abstract handles: PluginCoreHandlesApi;
     /** Proposals — design options: read, create, rename, switch, delete. See {@linkcode PluginCoreProposalsApi}. */
     abstract proposals: PluginCoreProposalsApi;
     constructor();
@@ -62,6 +74,8 @@ 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";
@@ -69,5 +83,6 @@ export * from "./buildings";
 export * from "./layers";
 export * from "./tags";
 export * from "./io";
+export * from "./handles";
 export * from "./proposals";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,aAAa;IACjC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,kFAAkF;IAClF,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,wEAAwE;IACxE,SAAgB,KAAK,EAAE,cAAc,CAAA;IACrC,2DAA2D;IAC3D,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,yEAAyE;IACzE,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,qFAAqF;IACrF,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,qFAAqF;IACrF,SAAgB,MAAM,EAAE,mBAAmB,CAAA;IAC3C,mGAAmG;IACnG,SAAgB,SAAS,EAAE,sBAAsB,CAAA;IACjD,mGAAmG;IACnG,SAAgB,MAAM,EAAE,mBAAmB,CAAA;IAC3C,0EAA0E;IAC1E,SAAgB,IAAI,EAAE,iBAAiB,CAAA;IACvC,gGAAgG;IAChG,SAAgB,EAAE,EAAE,eAAe,CAAA;IACnC,gHAAgH;IAChH,SAAgB,SAAS,EAAE,sBAAsB,CAAA;;CAGlD;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,MAAM,CAAA;AACpB,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8BAAsB,aAAa;IACjC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,kFAAkF;IAClF,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,wEAAwE;IACxE,SAAgB,KAAK,EAAE,cAAc,CAAA;IACrC,2DAA2D;IAC3D,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,+FAA+F;IAC/F,SAAgB,MAAM,EAAE,eAAe,CAAA;IACvC,wEAAwE;IACxE,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,yEAAyE;IACzE,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,qFAAqF;IACrF,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,qFAAqF;IACrF,SAAgB,MAAM,EAAE,mBAAmB,CAAA;IAC3C,mGAAmG;IACnG,SAAgB,SAAS,EAAE,sBAAsB,CAAA;IACjD,mGAAmG;IACnG,SAAgB,MAAM,EAAE,mBAAmB,CAAA;IAC3C,0EAA0E;IAC1E,SAAgB,IAAI,EAAE,iBAAiB,CAAA;IACvC,gGAAgG;IAChG,SAAgB,EAAE,EAAE,eAAe,CAAA;IACnC,+GAA+G;IAC/G,SAAgB,OAAO,EAAE,oBAAoB,CAAA;IAC7C,gHAAgH;IAChH,SAAgB,SAAS,EAAE,sBAAsB,CAAA;;CAGlD;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,MAAM,CAAA;AACpB,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA"}

package/dist/api/core/io/export/index.d.ts

@@ -0,0 +1,132 @@
+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 declare const ExportModelFormat: z.ZodEnum<{
+    fbx: "fbx";
+    obj: "obj";
+    "3ds": "3ds";
+    glb: "glb";
+}>;
+export type ExportModelFormat = z.infer<typeof ExportModelFormat>;
+/**
+ * What to export: the whole model (`"scene"`, default) or only the current
+ * selection (`"selection"`).
+ */
+export declare const ExportScope: z.ZodEnum<{
+    scene: "scene";
+    selection: "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 declare const ExportedFile: z.ZodObject<{
+    fileName: z.ZodString;
+    mimeType: z.ZodString;
+    dataBase64: z.ZodString;
+}, z.core.$strip>;
+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). 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 declare 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)
+     * ```
+     */
+    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 declare const PluginExportModelArgs: z.ZodObject<{
+    format: z.ZodEnum<{
+        fbx: "fbx";
+        obj: "obj";
+        "3ds": "3ds";
+        glb: "glb";
+    }>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        scene: "scene";
+        selection: "selection";
+    }>>;
+}, z.core.$strip>;
+export type PluginExportModelArgs = z.infer<typeof PluginExportModelArgs>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/io/export/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/core/io/export/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;;;;EAAuC,CAAA;AACrE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE;;;GAGG;AACH,eAAO,MAAM,WAAW;;;EAAiC,CAAA;AACzD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;;;;iBAIvB,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,8BAAsB,qBAAqB;;IAGzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;aACa,KAAK,CACnB,MAAM,EAAE,iBAAiB,EACzB,KAAK,CAAC,EAAE,WAAW,GAClB,eAAe,CAAC,YAAY,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;iBAGhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA"}

package/dist/api/core/io/import/index.d.ts

@@ -360,7 +360,7 @@ export declare const PluginImportModelArgs: z.ZodObject<{
         "3ds": "3ds";
         zip: "zip";
     }>>;
-    position: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>>;
+    position: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>>;
     label: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PluginImportModelArgs = z.infer<typeof PluginImportModelArgs>;

package/dist/api/core/io/index.d.ts

@@ -3,6 +3,7 @@ import { PluginCoreIoJobApi } from "./job";
 import { PluginCoreIoUnderlayApi } from "./underlay";
 import { PluginCoreIoTerrainApi } from "./terrain";
 import { PluginCoreIoQueryApi } from "./query";
+import { PluginCoreIoExportApi } from "./export";
 /**
  * I/O — bring external files into the project and manage what was imported.
  *
@@ -11,6 +12,7 @@ import { PluginCoreIoQueryApi } from "./query";
  * - {@linkcode PluginCoreIoApi.job} — poll long-running async imports (e.g. DWG)
  * - {@linkcode PluginCoreIoApi.underlay} — inspect/scale/opacity/delete placed underlays
  * - {@linkcode PluginCoreIoApi.terrain} — inspect/edit the site terrain (datum, layers, delete)
+ * - {@linkcode PluginCoreIoApi.export} — serialize the model to glb/obj (base64 bytes)
  *
  * Accessed via `snaptrude.core.io`.
  */
@@ -25,6 +27,8 @@ export declare abstract class PluginCoreIoApi {
     abstract underlay: PluginCoreIoUnderlayApi;
     /** Inspect and manage the site terrain. See {@linkcode PluginCoreIoTerrainApi}. */
     abstract terrain: PluginCoreIoTerrainApi;
+    /** Serialize the model to a downloadable 3D file. See {@linkcode PluginCoreIoExportApi}. */
+    abstract export: PluginCoreIoExportApi;
     constructor();
 }
 export * from "./import";
@@ -32,4 +36,5 @@ export * from "./job";
 export * from "./underlay";
 export * from "./terrain";
 export * from "./query";
+export * from "./export";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/core/io/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/io/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;GAUG;AACH,8BAAsB,eAAe;IACnC,mFAAmF;IACnF,SAAgB,MAAM,EAAE,qBAAqB,CAAA;IAC7C,gFAAgF;IAChF,SAAgB,KAAK,EAAE,oBAAoB,CAAA;IAC3C,yEAAyE;IACzE,SAAgB,GAAG,EAAE,kBAAkB,CAAA;IACvC,kFAAkF;IAClF,SAAgB,QAAQ,EAAE,uBAAuB,CAAA;IACjD,mFAAmF;IACnF,SAAgB,OAAO,EAAE,sBAAsB,CAAA;;CAGhD;AAED,cAAc,UAAU,CAAA;AACxB,cAAc,OAAO,CAAA;AACrB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/io/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAEhD;;;;;;;;;;;GAWG;AACH,8BAAsB,eAAe;IACnC,mFAAmF;IACnF,SAAgB,MAAM,EAAE,qBAAqB,CAAA;IAC7C,gFAAgF;IAChF,SAAgB,KAAK,EAAE,oBAAoB,CAAA;IAC3C,yEAAyE;IACzE,SAAgB,GAAG,EAAE,kBAAkB,CAAA;IACvC,kFAAkF;IAClF,SAAgB,QAAQ,EAAE,uBAAuB,CAAA;IACjD,mFAAmF;IACnF,SAAgB,OAAO,EAAE,sBAAsB,CAAA;IAC/C,4FAA4F;IAC5F,SAAgB,MAAM,EAAE,qBAAqB,CAAA;;CAG9C;AAED,cAAc,UAAU,CAAA;AACxB,cAAc,OAAO,CAAA;AACrB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA"}

package/dist/api/core/layers.d.ts

@@ -134,8 +134,8 @@ export declare abstract class PluginCoreLayersApi {
  * read-only imported underlays (`image`, `cad`, `pdf`, `terrain`, `buildings`).
  */
 export declare const PluginCoreLayerType: z.ZodEnum<{
-    terrain: "terrain";
     default: "default";
+    terrain: "terrain";
     buildings: "buildings";
     floor: "floor";
     wall: "wall";
@@ -172,8 +172,8 @@ export declare const PluginCoreLayer: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     layerType: z.ZodEnum<{
-        terrain: "terrain";
         default: "default";
+        terrain: "terrain";
         buildings: "buildings";
         floor: "floor";
         wall: "wall";
@@ -205,8 +205,8 @@ export type PluginCoreLayer = z.infer<typeof PluginCoreLayer>;
 export declare const PluginCoreLayersListArgs: z.ZodObject<{
     storeyId: z.ZodString;
     layerType: z.ZodOptional<z.ZodEnum<{
-        terrain: "terrain";
         default: "default";
+        terrain: "terrain";
         buildings: "buildings";
         floor: "floor";
         wall: "wall";
@@ -230,8 +230,8 @@ export declare const PluginCoreLayersListResult: z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
         layerType: z.ZodEnum<{
-            terrain: "terrain";
             default: "default";
+            terrain: "terrain";
             buildings: "buildings";
             floor: "floor";
             wall: "wall";
@@ -272,8 +272,8 @@ export declare const PluginCoreLayersGetResult: z.ZodNullable<z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     layerType: z.ZodEnum<{
-        terrain: "terrain";
         default: "default";
+        terrain: "terrain";
         buildings: "buildings";
         floor: "floor";
         wall: "wall";
@@ -313,8 +313,8 @@ export declare const PluginCoreLayersGetActiveResult: z.ZodNullable<z.ZodObject<
     id: z.ZodString;
     name: z.ZodString;
     layerType: z.ZodEnum<{
-        terrain: "terrain";
         default: "default";
+        terrain: "terrain";
         buildings: "buildings";
         floor: "floor";
         wall: "wall";
@@ -377,8 +377,8 @@ export declare const PluginCoreLayersUpdateResult: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     layerType: z.ZodEnum<{
-        terrain: "terrain";
         default: "default";
+        terrain: "terrain";
         buildings: "buildings";
         floor: "floor";
         wall: "wall";

package/dist/api/core/proposals/index.d.ts

@@ -125,29 +125,71 @@ export declare abstract class PluginCoreProposalsApi {
      */
     abstract isActive(proposalId: string): PluginApiReturn<boolean>;
     /**
-     * Create a new design option (proposal).
+     * Create a new design option (proposal) — blank, or configured from a base
+     * proposal (the New Proposal modal's two paths).
      *
      * **Pro-gated** (creating proposals requires a Pro plan, matching the UI) and
-     * **not undoable**. Creates a bare proposal with a single empty default
-     * bucket — it does **not** carry forward the current proposal's layers, views,
-     * or targets. The name is capped at 24 characters.
+     * **not undoable**. The name is capped at 24 characters.
+     *
+     * **Blank** (no `options`) — creates a bare proposal with a single empty
+     * default bucket; it does **not** carry forward the current proposal's
+     * layers, views, or targets, and the active proposal does **not** change.
+     *
+     * **Configured** (`options.baseProposalId`) — the modal's Configure path:
+     * carries the base proposal's buckets (layers) forward per `options.layers`,
+     * where each entry names a bucket of the base proposal and an action —
+     * `"share"` (the new proposal references the same live bucket) or
+     * `"duplicate"` (an independent copy of the bucket and its contents).
+     * Buckets not listed are left behind. Omitting `layers` carries **every**
+     * base bucket forward as a `"duplicate"` (the modal's default). The base
+     * proposal's views and area targets are copied either way, and the new
+     * proposal becomes the **active** one (implicit switch — blocked with
+     * `PROPOSAL_SWITCH_BLOCKED` while an in-canvas agent run is in flight, like
+     * {@linkcode PluginCoreProposalsApi.setActive}).
      *
      * @param name - Display name of the new proposal (capped at 24 chars).
+     * @param options - Optional configure path: `baseProposalId` (the proposal to
+     *   carry forward from) and `layers` (per-bucket `"share"` / `"duplicate"`
+     *   actions; omitted buckets are excluded, omitted `layers` duplicates all).
      * @returns The new proposal's id (read the full record back with
      *   {@linkcode PluginCoreProposalsApi.get}).
-     * @throws If the caller is not on a Pro plan, or the proposal could not be
-     *   created.
+     * @throws If the caller is not on a Pro plan, the name is empty/duplicate,
+     *   `layers` is passed without `baseProposalId`, the base proposal or a
+     *   listed bucket does not exist / does not belong to the base proposal, or
+     *   (configured only) `PROPOSAL_SWITCH_BLOCKED` while a canvas-agent run is
+     *   in flight.
      *
      * @examplePrompt Create a design option called Scheme B
      * @examplePrompt Add a new proposal named Option 2
-     * @examplePrompt Make a fresh design variant to explore
+     * @examplePrompt Duplicate the current proposal as Scheme C
+     * @examplePrompt Create a design option based on Proposal 1 that shares its site layer
      *
      * # Example
      * ```ts
+     * // blank design option
      * const { id } = await snaptrude.core.proposals.create("Scheme B")
+     *
+     * // configured from the active proposal: duplicate every layer
+     * const base = await snaptrude.core.proposals.getActive()
+     * if (base) {
+     *   const { id: dup } = await snaptrude.core.proposals.create("Scheme C", {
+     *     baseProposalId: base.id,
+     *   })
+     *   // …or share one layer and leave the rest behind
+     *   const { id: shared } = await snaptrude.core.proposals.create("Scheme D", {
+     *     baseProposalId: base.id,
+     *     layers: [{ bucketId: base.defaultBucketId, action: "share" }],
+     *   })
+     * }
      * ```
      */
-    abstract create(name: string): PluginApiReturn<PluginCoreProposalsCreateResult>;
+    abstract create(name: string, options?: {
+        baseProposalId: string;
+        layers?: {
+            bucketId: string;
+            action: "share" | "duplicate";
+        }[];
+    }): PluginApiReturn<PluginCoreProposalsCreateResult>;
     /**
      * Rename a proposal.
      *
@@ -374,14 +416,28 @@ export declare const PluginCoreProposalsIsActiveArgs: z.ZodObject<{
 }, z.core.$strip>;
 export type PluginCoreProposalsIsActiveArgs = z.infer<typeof PluginCoreProposalsIsActiveArgs>;
 /**
- * Arguments for {@linkcode PluginCoreProposalsApi.create}.
+ * Arguments for {@linkcode PluginCoreProposalsApi.create}. A bare `name` makes
+ * a blank proposal; `baseProposalId` switches to the configured (carry-forward)
+ * path. `layers` requires `baseProposalId` — each entry names a bucket of the
+ * base proposal; omitted buckets are excluded, and omitting `layers` entirely
+ * duplicates every base bucket.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `name` | `string` | Display name of the new proposal (capped at 24 chars) |
+ * | `baseProposalId` | `string \| undefined` | Proposal to carry forward from (configured path) |
+ * | `layers` | `{ bucketId: string; action: "share" \| "duplicate" }[] \| undefined` | Per-bucket carry-forward actions (requires `baseProposalId`) |
  */
 export declare const PluginCoreProposalsCreateArgs: z.ZodObject<{
     name: z.ZodString;
+    baseProposalId: z.ZodOptional<z.ZodString>;
+    layers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        bucketId: z.ZodString;
+        action: z.ZodEnum<{
+            share: "share";
+            duplicate: "duplicate";
+        }>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type PluginCoreProposalsCreateArgs = z.infer<typeof PluginCoreProposalsCreateArgs>;
 /**