Comment

Comments — create, read, edit, reply, resolve, tag, and list scene/project comments. A comment is an opaque CommentHandle (its server id). Comments may be anchored to a component at a 3D point, carry @mentions (by email) and emojis, be resolved / reopened, and hold a reply thread. Accessed via snaptrude.core.comment.

Types

CommentHandle

Opaque handle to a comment — its server-assigned id (entity-style: a raw, persistable string resolved live, not a registry-minted value handle).

PluginCommentCreateArgs

Wire schema for create.

Property	Type	Description
component	ComponentHandle?	Component to anchor the comment to
position	Vec3Handle?	Pin point; defaults to the component's center
message	string	Comment text (emojis = unicode)
mentions	string[]?	User emails to @mention

PluginCommentUpdateArgs

Wire schema for update.

Property	Type	Description
comment	CommentHandle	The comment to edit
message	string	New message text
mentions	string[]?	User emails to @mention

PluginCommentRefArgs

Wire schema for resolve / reopen / isResolved / delete / get.

Property	Type	Description
comment	CommentHandle	The target comment

PluginCommentTagArgs

Wire schema for tag.

Property	Type	Description
comment	CommentHandle	The comment to add a mention to
email	string	The user's email to @mention

PluginCommentReplyArgs

Wire schema for reply.

Property	Type	Description
comment	CommentHandle	The top-level comment to reply to
text	string	The reply text (emojis = unicode)

PluginCommentAuthor

The author of a comment or reply.

Property	Type	Description
name	string	Display name (falls back to the email)
email	string	The author's email

PluginCommentReply

One reply in a comment's thread.

Property	Type	Description
id	CommentHandle	The reply's own handle
content	string	The reply text
author	PluginCommentAuthor?	Who posted it (null if unknown)
createdAt	string	ISO-8601 timestamp (empty if unknown)

PluginCommentDetails

The read model of a comment — returned by get. The inverse of create.

Property	Type	Description
id	CommentHandle	The comment's handle
content	string	The comment text
author	PluginCommentAuthor?	Who posted it (null if unknown)
position	Vec3Components?	Pin point (world coords), null if un-anchored
component	ComponentHandle?	Anchored component, null if un-anchored
isResolved	boolean	Whether it has been marked resolved
createdAt	string	ISO-8601 timestamp (empty if unknown)
thread	PluginCommentReply[]	The reply thread, oldest first

Functions

create(message, component?, position?, mentions?)

Create a comment.

• Parameters:
  • message: string — Comment text (emojis = plain unicode)
  • component: ComponentHandle (optional) — Component to anchor the comment to
  • position: Vec3Handle (optional) — Pin point; defaults to the component's center
  • mentions: string[] (optional) — User emails, appended as real @mention tags
• Returns: CommentHandle — The new comment's handle.

const c = await snaptrude.core.comment.create("Check this wall 🎉", spaceId, undefined, [
  "alex@acme.com"
]);

---

update(comment, message, mentions?)

Edit a comment's message (and optional @mentions).

• Parameters:
  • comment: CommentHandle — The comment to edit
  • message: string — New message text
  • mentions: string[] (optional) — User emails to @mention
• Returns: boolean

---

resolve(comment)

Mark a comment resolved. Paired with reopen.

• Parameters:
  • comment: CommentHandle — The target comment
• Returns: boolean

---

reopen(comment)

Reopen a resolved comment. Paired with resolve.

• Parameters:
  • comment: CommentHandle — The target comment
• Returns: boolean

---

isResolved(comment)

Whether a comment is resolved.

• Parameters:
  • comment: CommentHandle — The target comment
• Returns: boolean

---

tag(comment, email)

Tag (mention) a user on an existing comment, by email.

• Parameters:
  • comment: CommentHandle — The comment to add a mention to
  • email: string — The user's email to @mention
• Returns: boolean

---

delete(comment)

Delete a comment.

• Parameters:
  • comment: CommentHandle — The target comment
• Returns: boolean

---

list()

List all (non-deleted) comment handles in the project.

• Returns: CommentHandle[] — Possibly empty, never null.

const comments = await snaptrude.core.comment.list();
for (const comment of comments) {
  const resolved = await snaptrude.core.comment.isResolved(comment);
  console.log(comment, resolved);
}

---

get(comment)

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. Accepts a top-level comment handle or a reply handle (a reply has an empty thread).

• Parameters:
  • comment: CommentHandle — The comment (or reply) to read
• Returns: PluginCommentDetails | null — null if the handle doesn't match a live comment (reads never throw for a miss). Deleted replies are excluded from thread.

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`);

---

reply(comment, text)

Reply to a comment — posts a new comment threaded under comment, mirroring the sidebar Reply action.

• Parameters:
  • comment: CommentHandle — The top-level comment to reply to (native threading is single-level; the target may not itself be a reply)
  • text: string — The reply text (emojis = plain unicode)
• Returns: CommentHandle — The new reply's handle.

const [thread] = await snaptrude.core.comment.list();
const reply = await snaptrude.core.comment.reply(thread, "Fixed 👍");

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
HANDLE_INVALID	create	The position vec3 handle cannot be resolved	kind: "vec3"
HANDLE_INVALID	reply	The target is unknown or is itself a reply	kind: "comment"
OPERATION_FAILED	create, reply	The server rejected the new comment / reply	—

update, resolve, reopen, tag, and delete never throw for a failed or unknown comment — they report the outcome as false by contract; isResolved likewise returns false for an unknown handle, and get returns null. An unresolvable component anchor in create is not an error either — the comment is created un-anchored.