@snaptrude/plugin-core 0.7.1 → 0.9.0

package/src/api/core/comment/index.ts

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { Vec3Handle, ComponentHandle } from "../../../handles"
+import { Vec3Handle, ComponentHandle, Vec3Components } from "../../../handles"
 
 /**
  * Comments — create, edit, resolve, tag, and list scene/project comments.
@@ -140,7 +140,10 @@ export abstract class PluginCommentApi {
    * await snaptrude.core.comment.tag(comment, "alex@acme.com")
    * ```
    */
-  public abstract tag(comment: CommentHandle, email: string): PluginApiReturn<boolean>
+  public abstract tag(
+    comment: CommentHandle,
+    email: string,
+  ): PluginApiReturn<boolean>
 
   /**
    * Permanently remove a comment from the project.
@@ -176,6 +179,57 @@ export abstract class PluginCommentApi {
    * ```
    */
   public abstract list(): PluginApiReturn<CommentHandle[]>
+
+  /**
+   * Read a comment's full detail — its text, author, pin location, resolved
+   * state, and reply thread. Comments are otherwise write-only; this is the read
+   * side. Pass a top-level comment handle or a reply handle (a reply has an empty
+   * `thread`). Returns `null` if the handle doesn't match a live comment.
+   *
+   * @param comment - The comment (or reply) to read.
+   * @returns the {@link PluginCommentDetails}, or `null` if not found.
+   *
+   * @examplePrompt Read the comment on this wall and tell me what it says
+   * @examplePrompt Who left this comment and where is it pinned?
+   * @examplePrompt Show me the full thread for this comment
+   * @examplePrompt Get the text and author of the selected comment
+   *
+   * # Example
+   * ```ts
+   * const [first] = await snaptrude.core.comment.list()
+   * const details = await snaptrude.core.comment.get(first)
+   * console.log(details?.content, "by", details?.author?.name)
+   * console.log(`${details?.thread.length ?? 0} replies`)
+   * ```
+   */
+  public abstract get(
+    comment: CommentHandle,
+  ): PluginApiReturn<PluginCommentDetails | null>
+
+  /**
+   * Reply to a comment — posts a new comment threaded under `comment` (which must
+   * be a top-level comment, not itself a reply). Notifies the thread's
+   * participants, mirroring the sidebar Reply action.
+   *
+   * @param comment - The top-level comment to reply to.
+   * @param text - The reply text (emojis = plain unicode).
+   * @returns the new reply's {@link CommentHandle}.
+   *
+   * @examplePrompt Reply to this comment saying I fixed the wall height
+   * @examplePrompt Add a reply to the review note confirming it's done
+   * @examplePrompt Respond to the comment about the door with "looks good now"
+   * @examplePrompt Post a follow-up on the selected comment thread
+   *
+   * # Example
+   * ```ts
+   * const [thread] = await snaptrude.core.comment.list()
+   * const reply = await snaptrude.core.comment.reply(thread, "Fixed 👍")
+   * ```
+   */
+  public abstract reply(
+    comment: CommentHandle,
+    text: string,
+  ): PluginApiReturn<CommentHandle>
 }
 
 /**
@@ -256,3 +310,67 @@ export const PluginCommentTagArgs = z.object({
 })
 
 export type PluginCommentTagArgs = z.infer<typeof PluginCommentTagArgs>
+
+/**
+ * Arguments for {@link PluginCommentApi.reply}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `comment` | {@link CommentHandle} | The top-level comment to reply to |
+ * | `text` | `string` | The reply text (emojis = unicode) |
+ */
+export const PluginCommentReplyArgs = z.object({
+  comment: CommentHandle,
+  text: z.string(),
+})
+
+export type PluginCommentReplyArgs = z.infer<typeof PluginCommentReplyArgs>
+
+/**
+ * The author of a comment or reply — the display name and email of the teammate
+ * who posted it. `null` on the rare comment with no recorded author.
+ */
+export interface PluginCommentAuthor {
+  /** The author's display name (falls back to their email). */
+  name: string
+  /** The author's email. */
+  email: string
+}
+
+/**
+ * One reply in a comment's thread (returned by {@link PluginCommentApi.get}).
+ */
+export interface PluginCommentReply {
+  /** The reply's own {@link CommentHandle}. */
+  id: CommentHandle
+  /** The reply text. */
+  content: string
+  /** Who posted the reply. */
+  author: PluginCommentAuthor | null
+  /** ISO-8601 timestamp of when the reply was posted (empty if unknown). */
+  createdAt: string
+}
+
+/**
+ * The read model of a comment — returned by {@link PluginCommentApi.get}. The
+ * inverse of {@link PluginCommentApi.create}: `content`/`component`/`position`
+ * echo what was posted, plus the resolved state and reply `thread`.
+ */
+export interface PluginCommentDetails {
+  /** The comment's {@link CommentHandle}. */
+  id: CommentHandle
+  /** The comment text. */
+  content: string
+  /** Who posted the comment. */
+  author: PluginCommentAuthor | null
+  /** The pin point (engine world coordinates), or `null` if un-anchored. */
+  position: Vec3Components | null
+  /** The component the comment is anchored to, or `null` if un-anchored. */
+  component: ComponentHandle | null
+  /** Whether the comment has been marked resolved. */
+  isResolved: boolean
+  /** ISO-8601 timestamp of when the comment was posted (empty if unknown). */
+  createdAt: string
+  /** The reply thread, oldest first. Empty for a comment with no replies. */
+  thread: PluginCommentReply[]
+}

package/src/api/core/geom/create/index.ts

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../../types"
-import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle } from "../../../../handles"
+import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, Vec3Components } from "../../../../handles"
 
 /**
  * Curve creation — construct new geometric curves from point handles (all-handle
@@ -177,6 +177,260 @@ export abstract class PluginGeomCreateApi {
     outer: ProfileHandle,
     holes?: ProfileHandle[],
   ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Create a closed solid **B-rep** from explicit face loops. Host API call —
+   * returns a {@linkcode BrepHandle}. Faces are plain arrays of `{x, y, z}`
+   * point components, NOT point handles (bulk-data precedent:
+   * `design.query.geometry.getTriangulatedMeshes`), in raw Babylon units.
+   *
+   * Each face is one planar loop of at least 3 points; at least 4 faces are
+   * required. Loops may be authored in any consistent winding — the host
+   * validates edge coherence (every edge shared by exactly two faces, in
+   * opposite directions) and fixes the global orientation so faces point
+   * outward. Faces must be planar and the solid must be closed; holes in faces
+   * are not supported (v1).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param faces Face loops — each an ordered array of `{x, y, z}` points (≥3 points per face, ≥4 faces)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if a face is degenerate or non-planar, an edge is not shared by
+   *   exactly two faces (open shell, non-manifold, or inconsistent winding), or
+   *   the faces do not form a valid closed solid
+   *
+   * @examplePrompt Create a brep from faces
+   * @examplePrompt Build a custom solid from a set of faces
+   * @examplePrompt Make a pyramid from triangular faces
+   *
+   * # Example
+   * ```ts
+   * // A pyramid: square base + 4 triangular sides
+   * const apex = { x: 0, y: 4, z: 0 }
+   * const a = { x: -2, y: 0, z: -2 }
+   * const b = { x: 2, y: 0, z: -2 }
+   * const c = { x: 2, y: 0, z: 2 }
+   * const d = { x: -2, y: 0, z: 2 }
+   * const brep = await snaptrude.core.geom.create.brepFromFaces([
+   *   [a, d, c, b], // base
+   *   [a, b, apex],
+   *   [b, c, apex],
+   *   [c, d, apex],
+   *   [d, a, apex],
+   * ])
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 5
+   * ```
+   */
+  public abstract brepFromFaces(faces: Vec3Components[][]): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** by extruding a contour along a direction.
+   * Host API call — returns a {@linkcode BrepHandle}. The direction is
+   * normalised by the host, so `amount` is the extrusion distance in raw
+   * Babylon units (negative extrudes the opposite way). The contour is copied —
+   * the input handle is never mutated. Holes and arc/circle profiles extrude
+   * natively (a circle profile yields a cylinder).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param contour The cross-section to extrude (outer profile + optional holes)
+   * @param direction Extrusion direction as plain `{x, y, z}` components (non-zero, normalised by the host)
+   * @param amount Extrusion distance (non-zero; negative extrudes opposite to `direction`)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if the extrusion is degenerate (zero amount, zero direction, or a
+   *   direction lying in the contour plane) or the contour cannot be extruded
+   *   into a valid solid
+   *
+   * @examplePrompt Extrude this profile 3 metres up
+   * @examplePrompt Make a solid by extruding this outline
+   * @examplePrompt Create a cylinder from a circle profile
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6
+   * ```
+   */
+  public abstract brepFromExtrusion(
+    contour: ContourHandle,
+    direction: Vec3Components,
+    amount: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** by lofting between a bottom and a top
+   * contour. Host API call — returns a {@linkcode BrepHandle}. Both contours
+   * must have the same number of edges (and matching hole counts); side faces
+   * connect corresponding edges by authored index. Corresponding edges must
+   * stay coplanar — a twisted loft would produce non-planar side faces and is
+   * rejected. The contours are copied — the input handles are never mutated.
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param bottomContour The bottom cross-section
+   * @param topContour The top cross-section (same edge and hole counts as the bottom)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if the contours are coincident, their edge or hole counts differ,
+   *   a side face between corresponding edges would be non-planar, or the
+   *   contours cannot be lofted into a valid solid
+   *
+   * @examplePrompt Make a tapered tower from these two outlines
+   * @examplePrompt Loft between a large base and a smaller top
+   * @examplePrompt Create a frustum from two squares
+   *
+   * # Example
+   * ```ts
+   * // A square frustum: 4m base lofted to a 2m top, 3m up
+   * const base = await snaptrude.core.geom.create.profileRect(4, 4)
+   * const top = await snaptrude.core.geom.create.profileRect(2, 2, await snaptrude.core.math.vec3.new(0, 3, 0))
+   * const brep = await snaptrude.core.geom.create.brepFromLoft(
+   *   await snaptrude.core.geom.create.contourFromProfile(base),
+   *   await snaptrude.core.geom.create.contourFromProfile(top),
+   * )
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6
+   * ```
+   */
+  public abstract brepFromLoft(
+    bottomContour: ContourHandle,
+    topContour: ContourHandle,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** from indexed mesh data: a vertex position
+   * array plus face loops of indices into it. Host API call — returns a
+   * {@linkcode BrepHandle}. The indexed form of
+   * {@linkcode PluginGeomCreateApi.brepFromFaces} — same validation (planar
+   * faces, closed manifold solid, every edge shared by exactly two faces) after
+   * the indices are expanded to point loops.
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param positions Vertex positions as plain `{x, y, z}` components (≥4)
+   * @param faces Face loops — each an ordered array of indices into `positions` (≥3 indices per face, ≥4 faces)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if an index is not an integer within `positions` bounds, a face is
+   *   degenerate or non-planar, or the faces do not form a valid closed solid
+   *
+   * @examplePrompt Create a brep from mesh vertices and indices
+   * @examplePrompt Turn this indexed mesh into a solid
+   * @examplePrompt Build a solid from vertex positions and face indices
+   *
+   * # Example
+   * ```ts
+   * // A tetrahedron from 4 vertices and 4 triangular faces
+   * const positions = [
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 4, y: 0, z: 0 },
+   *   { x: 2, y: 0, z: 4 },
+   *   { x: 2, y: 3, z: 1.5 },
+   * ]
+   * const brep = await snaptrude.core.geom.create.brepFromMesh(positions, [
+   *   [0, 2, 1], // base
+   *   [0, 1, 3],
+   *   [1, 2, 3],
+   *   [2, 0, 3],
+   * ])
+   * const vertexCount = await snaptrude.core.geom.query.brep.getVertexCount(brep) // 4
+   * ```
+   */
+  public abstract brepFromMesh(
+    positions: Vec3Components[],
+    faces: number[][],
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **union** of two breps
+   * (`a ∪ b`). Host API call — returns a new {@linkcode BrepHandle}. Inputs are
+   * read-only and may be authored breps (any `core.geom.create` brep
+   * constructor) or scene-derived breps from `design.query.geometry.getBrep`;
+   * coordinates are combined as-is, so both inputs must share a frame. The
+   * result must be a single solid — disjoint inputs are rejected.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a First solid
+   * @param b Second solid
+   * @returns The union as a new {@linkcode BrepHandle}
+   * @throws if the inputs do not overlap or touch (the union would be disjoint
+   *   solids) or the result cannot be built as a valid single solid
+   *
+   * @examplePrompt Union these two solids
+   * @examplePrompt Merge these breps into one mass
+   * @examplePrompt Combine the tower and the podium into a single solid
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.geom.create.brepFromExtrusion(baseContour, { x: 0, y: 1, z: 0 }, 3)
+   * const b = await snaptrude.core.geom.create.brepFromExtrusion(overlappingContour, { x: 0, y: 1, z: 0 }, 5)
+   * const merged = await snaptrude.core.geom.create.brepFromUnion(a, b)
+   * ```
+   */
+  public abstract brepFromUnion(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **subtraction** of two
+   * breps: **`a` minus `b`** — `b` is cut away from `a`. Host API call —
+   * returns a new {@linkcode BrepHandle}. Argument order matters:
+   * `brepFromSubtraction(a, b)` removes `b`'s volume from `a`. Inputs are
+   * read-only and may be authored or scene-derived breps (see
+   * {@linkcode PluginGeomCreateApi.brepFromUnion}); coordinates are combined
+   * as-is.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a The solid to subtract from
+   * @param b The solid to remove from `a`
+   * @returns `a` minus `b` as a new {@linkcode BrepHandle}
+   * @throws if `b` consumes `a` entirely (empty result), the result splits into
+   *   disjoint solids, or it cannot be built as a valid single solid
+   *
+   * @examplePrompt Subtract the courtyard from the building mass
+   * @examplePrompt Cut this solid out of that one
+   * @examplePrompt Punch a hole through the slab with this box
+   *
+   * # Example
+   * ```ts
+   * // buildingBrep minus courtyardBrep — order matters
+   * const carved = await snaptrude.core.geom.create.brepFromSubtraction(buildingBrep, courtyardBrep)
+   * ```
+   */
+  public abstract brepFromSubtraction(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **intersection** of two
+   * breps (`a ∩ b` — the shared volume only). Host API call — returns a new
+   * {@linkcode BrepHandle}. Inputs are read-only and may be authored or
+   * scene-derived breps (see {@linkcode PluginGeomCreateApi.brepFromUnion});
+   * coordinates are combined as-is.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a First solid
+   * @param b Second solid
+   * @returns The shared volume as a new {@linkcode BrepHandle}
+   * @throws if the inputs do not overlap (empty intersection), the result
+   *   splits into disjoint solids, or it cannot be built as a valid single
+   *   solid
+   *
+   * @examplePrompt Keep only the overlap of these two solids
+   * @examplePrompt Intersect these two masses
+   * @examplePrompt Clip the tower to the zoning envelope
+   *
+   * # Example
+   * ```ts
+   * const overlap = await snaptrude.core.geom.create.brepFromIntersection(towerBrep, envelopeBrep)
+   * ```
+   */
+  public abstract brepFromIntersection(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
 }
 
 /**
@@ -291,3 +545,92 @@ export const PluginGeomCreateContourFromProfilesArgs = z.object({
 export type PluginGeomCreateContourFromProfilesArgs = z.infer<
   typeof PluginGeomCreateContourFromProfilesArgs
 >
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromFaces}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `faces` | {@linkcode Vec3Components}`[][]` | Face loops — each an ordered array of `{x, y, z}` points (≥3 points per face, ≥4 faces) |
+ */
+export const PluginGeomCreateBrepFromFacesArgs = z.object({
+  faces: z.array(z.array(Vec3Components).min(3)).min(4),
+})
+
+export type PluginGeomCreateBrepFromFacesArgs = z.infer<
+  typeof PluginGeomCreateBrepFromFacesArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromExtrusion}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The cross-section to extrude |
+ * | `direction` | {@linkcode Vec3Components} | Extrusion direction (non-zero, finite components) |
+ * | `amount` | `number` | Extrusion distance (finite, non-zero) |
+ */
+export const PluginGeomCreateBrepFromExtrusionArgs = z.object({
+  contour: ContourHandle,
+  direction: z.object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    z: z.number().finite(),
+  }),
+  amount: z
+    .number()
+    .finite()
+    .refine((value) => value !== 0, { message: "amount must be non-zero" }),
+})
+
+export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
+  typeof PluginGeomCreateBrepFromExtrusionArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromLoft}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `bottomContour` | {@linkcode ContourHandle} | The bottom cross-section |
+ * | `topContour` | {@linkcode ContourHandle} | The top cross-section |
+ */
+export const PluginGeomCreateBrepFromLoftArgs = z.object({
+  bottomContour: ContourHandle,
+  topContour: ContourHandle,
+})
+
+export type PluginGeomCreateBrepFromLoftArgs = z.infer<typeof PluginGeomCreateBrepFromLoftArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromMesh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `positions` | {@linkcode Vec3Components}`[]` | Vertex positions (≥4) |
+ * | `faces` | `number[][]` | Face loops of indices into `positions` (≥3 indices per face, ≥4 faces) |
+ */
+export const PluginGeomCreateBrepFromMeshArgs = z.object({
+  positions: z.array(Vec3Components).min(4),
+  faces: z.array(z.array(z.number()).min(3)).min(4),
+})
+
+export type PluginGeomCreateBrepFromMeshArgs = z.infer<typeof PluginGeomCreateBrepFromMeshArgs>
+
+/**
+ * Arguments for the brep boolean constructors —
+ * {@linkcode PluginGeomCreateApi.brepFromUnion},
+ * {@linkcode PluginGeomCreateApi.brepFromSubtraction} (`a` minus `b`), and
+ * {@linkcode PluginGeomCreateApi.brepFromIntersection}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `a` | {@linkcode BrepHandle} | First solid (the subtraction target) |
+ * | `b` | {@linkcode BrepHandle} | Second solid (the subtraction tool) |
+ */
+export const PluginGeomCreateBrepBooleanArgs = z.object({
+  a: BrepHandle,
+  b: BrepHandle,
+})
+
+export type PluginGeomCreateBrepBooleanArgs = z.infer<typeof PluginGeomCreateBrepBooleanArgs>

package/src/api/core/geom/delete/index.ts

@@ -20,6 +20,9 @@ export abstract class PluginGeomDeleteApi {
    * reclaims its share of the plugin's resource quota. This is a handle-lifecycle
    * operation only and does NOT tear down any engine-side geometry.
    *
+   * @deprecated Use `core.handles.release([profile])` — the universal, batched
+   * release API for every arena handle kind.
+   *
    * @param profile The transient profile handle to release
    * @returns Nothing
    *
@@ -37,6 +40,9 @@ export abstract class PluginGeomDeleteApi {
    * reclaims its share of the plugin's resource quota. Handle-lifecycle only; does
    * NOT tear down engine-side geometry, nor the contour's child profile handles.
    *
+   * @deprecated Use `core.handles.release([contour])` — the universal, batched
+   * release API for every arena handle kind.
+   *
    * @param contour The transient contour handle to release
    * @returns Nothing
    *