@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.1

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

@@ -1,376 +1,376 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { Vec3Handle, ComponentHandle, Vec3Components } from "../../../handles"
-
-/**
- * Comments — create, edit, resolve, tag, and list scene/project comments.
- *
- * A comment is an opaque {@link CommentHandle} (its server id). Comments may be
- * anchored to a component at a 3D point, carry @mentions (by email) and emojis,
- * and be resolved / reopened. Accessed via `snaptrude.core.comment`.
- */
-export abstract class PluginCommentApi {
-  constructor() {}
-
-  /**
-   * Create a comment in the project — optionally pinned to a component at a 3D
-   * point — with optional @mentions that notify teammates by email.
-   *
-   * @param message - Comment text (emojis = plain unicode).
-   * @param component - Optional component to anchor the comment to.
-   * @param position - Optional pin point; defaults to the component's center.
-   * @param mentions - Optional user emails to @mention (appended as real @mention tags).
-   * @returns the new {@link CommentHandle}.
-   *
-   * @examplePrompt Add a comment on this wall saying the height looks wrong
-   * @examplePrompt Leave a note on the selected room for the design team
-   * @examplePrompt Comment "verify the door swing" and tag alex@acme.com
-   * @examplePrompt Pin a review note at this point on the slab
-   *
-   * # Example
-   * ```ts
-   * const c = await snaptrude.core.comment.create(
-   *   "Check this wall 🎉",
-   *   spaceId,
-   *   undefined,
-   *   ["alex@acme.com"],
-   * )
-   * ```
-   */
-  public abstract create(
-    message: string,
-    component?: ComponentHandle,
-    position?: Vec3Handle,
-    mentions?: string[],
-  ): PluginApiReturn<CommentHandle>
-
-  /**
-   * Edit a comment's message (and optional @mentions).
-   *
-   * @param comment - The comment to edit.
-   * @param message - New message text.
-   * @param mentions - Optional user emails to @mention.
-   *
-   * @examplePrompt Edit my comment to say the beam depth is 600mm
-   * @examplePrompt Change the text of this comment
-   * @examplePrompt Update the note on the wall and mention priya@studio.com
-   * @examplePrompt Reword the comment I just added
-   *
-   * # Example
-   * ```ts
-   * const c = await snaptrude.core.comment.create("Beam depth TBD")
-   * await snaptrude.core.comment.update(c, "Beam depth is 600mm", ["priya@studio.com"])
-   * ```
-   */
-  public abstract update(
-    comment: CommentHandle,
-    message: string,
-    mentions?: string[],
-  ): PluginApiReturn<boolean>
-
-  /**
-   * Mark a comment resolved. Paired with {@link PluginCommentApi.reopen}.
-   *
-   * @param comment - The target comment.
-   *
-   * @examplePrompt Mark this comment as resolved
-   * @examplePrompt Resolve the comment about the staircase
-   * @examplePrompt Close out this review note
-   * @examplePrompt Set that comment to done
-   *
-   * # Example
-   * ```ts
-   * const c = await snaptrude.core.comment.create("Verify the door swing")
-   * await snaptrude.core.comment.resolve(c)
-   * ```
-   */
-  public abstract resolve(comment: CommentHandle): PluginApiReturn<boolean>
-
-  /**
-   * Reopen a resolved comment. Paired with {@link PluginCommentApi.resolve}.
-   *
-   * @param comment - The target comment.
-   *
-   * @examplePrompt Reopen this resolved comment
-   * @examplePrompt Mark the comment as unresolved again
-   * @examplePrompt Bring back the closed note about the window heights
-   * @examplePrompt Un-resolve that comment so we can keep discussing it
-   *
-   * # Example
-   * ```ts
-   * const [comment] = await snaptrude.core.comment.list()
-   * await snaptrude.core.comment.reopen(comment)
-   * ```
-   */
-  public abstract reopen(comment: CommentHandle): PluginApiReturn<boolean>
-
-  /**
-   * Check whether a comment has been marked resolved.
-   *
-   * @param comment - The target comment.
-   *
-   * @examplePrompt Is this comment resolved yet?
-   * @examplePrompt Check if the note about the roof has been closed
-   * @examplePrompt Has my comment been resolved?
-   * @examplePrompt Tell me whether that comment is still open
-   *
-   * # Example
-   * ```ts
-   * const [comment] = await snaptrude.core.comment.list()
-   * const resolved = await snaptrude.core.comment.isResolved(comment)
-   * console.log(resolved ? "resolved" : "still open")
-   * ```
-   */
-  public abstract isResolved(comment: CommentHandle): PluginApiReturn<boolean>
-
-  /**
-   * Tag (mention) a user on an existing comment, by email.
-   *
-   * @param comment - The comment to add a mention to.
-   * @param email - The user's email to @mention.
-   *
-   * @examplePrompt Tag alex@acme.com on this comment
-   * @examplePrompt Mention the structural engineer in that note
-   * @examplePrompt Add priya@studio.com to the comment about the lobby
-   * @examplePrompt Notify a teammate about an existing comment
-   *
-   * # Example
-   * ```ts
-   * const [comment] = await snaptrude.core.comment.list()
-   * await snaptrude.core.comment.tag(comment, "alex@acme.com")
-   * ```
-   */
-  public abstract tag(
-    comment: CommentHandle,
-    email: string,
-  ): PluginApiReturn<boolean>
-
-  /**
-   * Permanently remove a comment from the project.
-   *
-   * @param comment - The target comment.
-   *
-   * @examplePrompt Delete this comment
-   * @examplePrompt Remove the note about the old layout
-   * @examplePrompt Get rid of my last comment
-   * @examplePrompt Clear that resolved comment off the wall
-   *
-   * # Example
-   * ```ts
-   * const [comment] = await snaptrude.core.comment.list()
-   * await snaptrude.core.comment.delete(comment)
-   * ```
-   */
-  public abstract delete(comment: CommentHandle): PluginApiReturn<boolean>
-
-  /**
-   * List every comment in the project (deleted ones are excluded), returned as
-   * comment handles you can pass to the other comment methods.
-   *
-   * @examplePrompt List all the comments in this project
-   * @examplePrompt How many comments are on this model?
-   * @examplePrompt Show every note in the file
-   * @examplePrompt Get all comments so I can check which are resolved
-   *
-   * # Example
-   * ```ts
-   * const comments = await snaptrude.core.comment.list()
-   * console.log(`${comments.length} comments in the project`)
-   * ```
-   */
-  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>
-}
-
-/**
- * Opaque handle to a comment — its server-assigned id (entity-style: a raw,
- * persistable string resolved live, not a registry-minted value handle).
- */
-export type CommentHandle = string & { readonly __handle: "comment" }
-export const CommentHandle = z
-  .string()
-  .min(1)
-  .transform((s) => s as CommentHandle)
-
-/** `ComponentHandle` is defined in `handles.ts` (imported above) and exported from the
- *  package root via `export * from "./handles"`. Not re-exported here to avoid an
- *  ambiguous double `export *` at the barrel. */
-
-/**
- * Arguments for {@link PluginCommentApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `component` | {@link ComponentHandle}? | Component to anchor the comment to |
- * | `position` | {@link Vec3Handle}? | Pin point; defaults to the component's center |
- * | `message` | `string` | Comment text (emojis = unicode) |
- * | `mentions` | `string[]`? | User emails to @mention |
- */
-export const PluginCommentCreateArgs = z.object({
-  component: ComponentHandle.optional(),
-  position: Vec3Handle.optional(),
-  message: z.string(),
-  mentions: z.array(z.string()).optional(),
-})
-
-export type PluginCommentCreateArgs = z.infer<typeof PluginCommentCreateArgs>
-
-/**
- * Arguments for {@link PluginCommentApi.update}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `comment` | {@link CommentHandle} | The comment to edit |
- * | `message` | `string` | New message text |
- * | `mentions` | `string[]`? | User emails to @mention |
- */
-export const PluginCommentUpdateArgs = z.object({
-  comment: CommentHandle,
-  message: z.string(),
-  mentions: z.array(z.string()).optional(),
-})
-
-export type PluginCommentUpdateArgs = z.infer<typeof PluginCommentUpdateArgs>
-
-/**
- * Arguments for {@link PluginCommentApi.resolve} / {@link PluginCommentApi.reopen}
- * / {@link PluginCommentApi.isResolved} / {@link PluginCommentApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `comment` | {@link CommentHandle} | The target comment |
- */
-export const PluginCommentRefArgs = z.object({
-  comment: CommentHandle,
-})
-
-export type PluginCommentRefArgs = z.infer<typeof PluginCommentRefArgs>
-
-/**
- * Arguments for {@link PluginCommentApi.tag}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `comment` | {@link CommentHandle} | The comment to add a mention to |
- * | `email` | `string` | The user's email to @mention |
- */
-export const PluginCommentTagArgs = z.object({
-  comment: CommentHandle,
-  email: z.string(),
-})
-
-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[]
-}
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { Vec3Handle, ComponentHandle, Vec3Components } from "../../../handles"
+
+/**
+ * Comments — create, edit, resolve, tag, and list scene/project comments.
+ *
+ * A comment is an opaque {@link CommentHandle} (its server id). Comments may be
+ * anchored to a component at a 3D point, carry @mentions (by email) and emojis,
+ * and be resolved / reopened. Accessed via `snaptrude.core.comment`.
+ */
+export abstract class PluginCommentApi {
+  constructor() {}
+
+  /**
+   * Create a comment in the project — optionally pinned to a component at a 3D
+   * point — with optional @mentions that notify teammates by email.
+   *
+   * @param message - Comment text (emojis = plain unicode).
+   * @param component - Optional component to anchor the comment to.
+   * @param position - Optional pin point; defaults to the component's center.
+   * @param mentions - Optional user emails to @mention (appended as real @mention tags).
+   * @returns the new {@link CommentHandle}.
+   *
+   * @examplePrompt Add a comment on this wall saying the height looks wrong
+   * @examplePrompt Leave a note on the selected room for the design team
+   * @examplePrompt Comment "verify the door swing" and tag alex@acme.com
+   * @examplePrompt Pin a review note at this point on the slab
+   *
+   * # Example
+   * ```ts
+   * const c = await snaptrude.core.comment.create(
+   *   "Check this wall 🎉",
+   *   spaceId,
+   *   undefined,
+   *   ["alex@acme.com"],
+   * )
+   * ```
+   */
+  public abstract create(
+    message: string,
+    component?: ComponentHandle,
+    position?: Vec3Handle,
+    mentions?: string[],
+  ): PluginApiReturn<CommentHandle>
+
+  /**
+   * Edit a comment's message (and optional @mentions).
+   *
+   * @param comment - The comment to edit.
+   * @param message - New message text.
+   * @param mentions - Optional user emails to @mention.
+   *
+   * @examplePrompt Edit my comment to say the beam depth is 600mm
+   * @examplePrompt Change the text of this comment
+   * @examplePrompt Update the note on the wall and mention priya@studio.com
+   * @examplePrompt Reword the comment I just added
+   *
+   * # Example
+   * ```ts
+   * const c = await snaptrude.core.comment.create("Beam depth TBD")
+   * await snaptrude.core.comment.update(c, "Beam depth is 600mm", ["priya@studio.com"])
+   * ```
+   */
+  public abstract update(
+    comment: CommentHandle,
+    message: string,
+    mentions?: string[],
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Mark a comment resolved. Paired with {@link PluginCommentApi.reopen}.
+   *
+   * @param comment - The target comment.
+   *
+   * @examplePrompt Mark this comment as resolved
+   * @examplePrompt Resolve the comment about the staircase
+   * @examplePrompt Close out this review note
+   * @examplePrompt Set that comment to done
+   *
+   * # Example
+   * ```ts
+   * const c = await snaptrude.core.comment.create("Verify the door swing")
+   * await snaptrude.core.comment.resolve(c)
+   * ```
+   */
+  public abstract resolve(comment: CommentHandle): PluginApiReturn<boolean>
+
+  /**
+   * Reopen a resolved comment. Paired with {@link PluginCommentApi.resolve}.
+   *
+   * @param comment - The target comment.
+   *
+   * @examplePrompt Reopen this resolved comment
+   * @examplePrompt Mark the comment as unresolved again
+   * @examplePrompt Bring back the closed note about the window heights
+   * @examplePrompt Un-resolve that comment so we can keep discussing it
+   *
+   * # Example
+   * ```ts
+   * const [comment] = await snaptrude.core.comment.list()
+   * await snaptrude.core.comment.reopen(comment)
+   * ```
+   */
+  public abstract reopen(comment: CommentHandle): PluginApiReturn<boolean>
+
+  /**
+   * Check whether a comment has been marked resolved.
+   *
+   * @param comment - The target comment.
+   *
+   * @examplePrompt Is this comment resolved yet?
+   * @examplePrompt Check if the note about the roof has been closed
+   * @examplePrompt Has my comment been resolved?
+   * @examplePrompt Tell me whether that comment is still open
+   *
+   * # Example
+   * ```ts
+   * const [comment] = await snaptrude.core.comment.list()
+   * const resolved = await snaptrude.core.comment.isResolved(comment)
+   * console.log(resolved ? "resolved" : "still open")
+   * ```
+   */
+  public abstract isResolved(comment: CommentHandle): PluginApiReturn<boolean>
+
+  /**
+   * Tag (mention) a user on an existing comment, by email.
+   *
+   * @param comment - The comment to add a mention to.
+   * @param email - The user's email to @mention.
+   *
+   * @examplePrompt Tag alex@acme.com on this comment
+   * @examplePrompt Mention the structural engineer in that note
+   * @examplePrompt Add priya@studio.com to the comment about the lobby
+   * @examplePrompt Notify a teammate about an existing comment
+   *
+   * # Example
+   * ```ts
+   * const [comment] = await snaptrude.core.comment.list()
+   * await snaptrude.core.comment.tag(comment, "alex@acme.com")
+   * ```
+   */
+  public abstract tag(
+    comment: CommentHandle,
+    email: string,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Permanently remove a comment from the project.
+   *
+   * @param comment - The target comment.
+   *
+   * @examplePrompt Delete this comment
+   * @examplePrompt Remove the note about the old layout
+   * @examplePrompt Get rid of my last comment
+   * @examplePrompt Clear that resolved comment off the wall
+   *
+   * # Example
+   * ```ts
+   * const [comment] = await snaptrude.core.comment.list()
+   * await snaptrude.core.comment.delete(comment)
+   * ```
+   */
+  public abstract delete(comment: CommentHandle): PluginApiReturn<boolean>
+
+  /**
+   * List every comment in the project (deleted ones are excluded), returned as
+   * comment handles you can pass to the other comment methods.
+   *
+   * @examplePrompt List all the comments in this project
+   * @examplePrompt How many comments are on this model?
+   * @examplePrompt Show every note in the file
+   * @examplePrompt Get all comments so I can check which are resolved
+   *
+   * # Example
+   * ```ts
+   * const comments = await snaptrude.core.comment.list()
+   * console.log(`${comments.length} comments in the project`)
+   * ```
+   */
+  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>
+}
+
+/**
+ * Opaque handle to a comment — its server-assigned id (entity-style: a raw,
+ * persistable string resolved live, not a registry-minted value handle).
+ */
+export type CommentHandle = string & { readonly __handle: "comment" }
+export const CommentHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as CommentHandle)
+
+/** `ComponentHandle` is defined in `handles.ts` (imported above) and exported from the
+ *  package root via `export * from "./handles"`. Not re-exported here to avoid an
+ *  ambiguous double `export *` at the barrel. */
+
+/**
+ * Arguments for {@link PluginCommentApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@link ComponentHandle}? | Component to anchor the comment to |
+ * | `position` | {@link Vec3Handle}? | Pin point; defaults to the component's center |
+ * | `message` | `string` | Comment text (emojis = unicode) |
+ * | `mentions` | `string[]`? | User emails to @mention |
+ */
+export const PluginCommentCreateArgs = z.object({
+  component: ComponentHandle.optional(),
+  position: Vec3Handle.optional(),
+  message: z.string(),
+  mentions: z.array(z.string()).optional(),
+})
+
+export type PluginCommentCreateArgs = z.infer<typeof PluginCommentCreateArgs>
+
+/**
+ * Arguments for {@link PluginCommentApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `comment` | {@link CommentHandle} | The comment to edit |
+ * | `message` | `string` | New message text |
+ * | `mentions` | `string[]`? | User emails to @mention |
+ */
+export const PluginCommentUpdateArgs = z.object({
+  comment: CommentHandle,
+  message: z.string(),
+  mentions: z.array(z.string()).optional(),
+})
+
+export type PluginCommentUpdateArgs = z.infer<typeof PluginCommentUpdateArgs>
+
+/**
+ * Arguments for {@link PluginCommentApi.resolve} / {@link PluginCommentApi.reopen}
+ * / {@link PluginCommentApi.isResolved} / {@link PluginCommentApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `comment` | {@link CommentHandle} | The target comment |
+ */
+export const PluginCommentRefArgs = z.object({
+  comment: CommentHandle,
+})
+
+export type PluginCommentRefArgs = z.infer<typeof PluginCommentRefArgs>
+
+/**
+ * Arguments for {@link PluginCommentApi.tag}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `comment` | {@link CommentHandle} | The comment to add a mention to |
+ * | `email` | `string` | The user's email to @mention |
+ */
+export const PluginCommentTagArgs = z.object({
+  comment: CommentHandle,
+  email: z.string(),
+})
+
+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[]
+}