@voltro/plugin-comments 0.81.0 → 0.82.0

package/dist/rpc-DlFs6xXs.js

@@ -0,0 +1,188 @@
+import { CommentAccessRefused as e, CommentNotFound as t, CommentNotYours as n } from "./errors.js";
+import { Schema as r } from "effect";
+import { defineMutation as i, defineQuery as a, reactivityChannel as o } from "@voltro/protocol";
+//#region src/quote.ts
+var s = 1e3, c = 32, l = (e, t, n) => {
+	let r = Math.max(0, Math.min(t, n)), i = Math.min(e.length, Math.max(t, n), r + s), a = e.slice(Math.max(0, r - c), r), o = e.slice(i, i + c);
+	return {
+		exact: e.slice(r, i),
+		...a === "" ? {} : { prefix: a },
+		...o === "" ? {} : { suffix: o }
+	};
+}, u = (e, t) => {
+	if (t.exact === "") return null;
+	let n = null;
+	for (let r = e.indexOf(t.exact); r !== -1; r = e.indexOf(t.exact, r + 1)) {
+		let i = e.slice(0, r), a = e.slice(r + t.exact.length), o = (t.prefix !== void 0 && i.endsWith(t.prefix) ? 1 : 0) + (t.suffix !== void 0 && a.startsWith(t.suffix) ? 1 : 0);
+		(n === null || o > n.score) && (n = {
+			start: r,
+			score: o
+		});
+	}
+	return n === null ? null : {
+		start: n.start,
+		end: n.start + t.exact.length
+	};
+}, d = "@voltro/plugin-comments", f = o("comments"), p = r.Struct({
+	id: r.String,
+	threadId: r.String,
+	body: r.String,
+	authorSubjectId: r.String,
+	mentions: r.Array(r.String),
+	editedAt: r.NullOr(r.String),
+	createdAt: r.String,
+	reactions: r.Array(r.Struct({
+		emoji: r.String,
+		count: r.Number,
+		mine: r.Boolean
+	}))
+}), m = r.Struct({
+	exact: r.String.pipe(r.minLength(1), r.maxLength(s)),
+	prefix: r.optional(r.String.pipe(r.maxLength(32))),
+	suffix: r.optional(r.String.pipe(r.maxLength(32)))
+}), h = r.Struct({
+	id: r.String,
+	anchor: r.String,
+	quote: r.NullOr(m),
+	status: r.Literal("open", "resolved"),
+	createdBy: r.String,
+	createdAt: r.String,
+	comments: r.Array(p),
+	unreadCount: r.Number
+}), g = a({
+	name: "comments.list",
+	source: f,
+	input: r.Struct({ anchor: r.String }),
+	output: r.Array(h),
+	error: e,
+	openAccess: "delegated: the executor runs the app-declared anchor access rule (viaEntity guard or scope) and is fail-closed — an undeclared rule refuses every read"
+}), _ = i({
+	name: "comments.create",
+	input: r.Struct({
+		anchor: r.String,
+		body: r.String,
+		threadId: r.optional(r.String),
+		mentions: r.optional(r.Array(r.String)),
+		quote: r.optional(m)
+	}),
+	output: r.Struct({
+		threadId: r.String,
+		commentId: r.String
+	}),
+	error: r.Union(e, t),
+	openAccess: "delegated: the executor runs the app-declared anchor access rule before any write; the author is always the calling subject"
+}), v = i({
+	name: "comments.edit",
+	input: r.Struct({
+		commentId: r.String,
+		body: r.String
+	}),
+	output: r.Struct({ ok: r.Boolean }),
+	error: r.Union(e, t, n),
+	openAccess: "author-scoped: only the comment's own author may edit, checked in the executor on top of the anchor access rule"
+}), y = i({
+	name: "comments.resolve",
+	input: r.Struct({
+		threadId: r.String,
+		resolved: r.Boolean
+	}),
+	output: r.Struct({ ok: r.Boolean }),
+	error: r.Union(e, t),
+	openAccess: "delegated: anchor access rule in the executor — anyone who may read the anchor may resolve/reopen (the Liveblocks semantic)"
+}), b = i({
+	name: "comments.delete",
+	input: r.Struct({ commentId: r.String }),
+	output: r.Struct({ ok: r.Boolean }),
+	error: r.Union(e, t, n),
+	openAccess: "author-scoped, with a comments:moderate scope override — both checked in the executor on top of the anchor access rule"
+}), x = i({
+	name: "comments.react",
+	input: r.Struct({
+		commentId: r.String,
+		emoji: r.String
+	}),
+	output: r.Struct({ reacted: r.Boolean }),
+	error: r.Union(e, t),
+	openAccess: "delegated: anchor access rule in the executor; the toggle writes only the calling subject's own reaction row"
+}), S = i({
+	name: "comments.markRead",
+	input: r.Struct({ threadId: r.String }),
+	output: r.Struct({ ok: r.Boolean }),
+	error: t,
+	openAccess: "self-scoped write: stamps only the calling subject's own read marker for the thread"
+}), C = a({
+	name: "comments.mentionSearch",
+	input: r.Struct({ query: r.String }),
+	output: r.Array(r.Struct({
+		subjectId: r.String,
+		label: r.String
+	})),
+	openAccess: "delegated: the app-declared mention resolver receives the CALLING subject and its default filters to the caller's tenant — cross-tenant subjects are structurally unreachable"
+}), w = [
+	{
+		tag: "comments.list",
+		kind: "query",
+		import: {
+			module: "@voltro/plugin-comments/rpc",
+			name: "listDescriptor"
+		}
+	},
+	{
+		tag: "comments.create",
+		kind: "mutation",
+		import: {
+			module: "@voltro/plugin-comments/rpc",
+			name: "createDescriptor"
+		}
+	},
+	{
+		tag: "comments.edit",
+		kind: "mutation",
+		import: {
+			module: "@voltro/plugin-comments/rpc",
+			name: "editDescriptor"
+		}
+	},
+	{
+		tag: "comments.resolve",
+		kind: "mutation",
+		import: {
+			module: "@voltro/plugin-comments/rpc",
+			name: "resolveDescriptor"
+		}
+	},
+	{
+		tag: "comments.delete",
+		kind: "mutation",
+		import: {
+			module: "@voltro/plugin-comments/rpc",
+			name: "deleteDescriptor"
+		}
+	},
+	{
+		tag: "comments.react",
+		kind: "mutation",
+		import: {
+			module: "@voltro/plugin-comments/rpc",
+			name: "reactDescriptor"
+		}
+	},
+	{
+		tag: "comments.markRead",
+		kind: "mutation",
+		import: {
+			module: "@voltro/plugin-comments/rpc",
+			name: "markReadDescriptor"
+		}
+	},
+	{
+		tag: "comments.mentionSearch",
+		kind: "query",
+		import: {
+			module: "@voltro/plugin-comments/rpc",
+			name: "mentionSearchDescriptor"
+		}
+	}
+];
+//#endregion
+export { b as a, S as c, y as d, s as f, _ as i, C as l, l as m, f as n, v as o, u as p, w as r, g as s, d as t, x as u };

package/dist/rpc.d.ts

@@ -66,6 +66,12 @@ export declare const createDescriptor: MutationProcedureDescriptor<"comments.cre
     /** Reply into an existing thread; absent opens a new thread. */
     threadId: Schema.optional<typeof Schema.String>;
     mentions: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    /** A new thread's passage; ignored on a reply. */
+    quote: Schema.optional<Schema.Struct<{
+        exact: Schema.filter<Schema.filter<typeof Schema.String>>;
+        prefix: Schema.optional<Schema.filter<typeof Schema.String>>;
+        suffix: Schema.optional<Schema.filter<typeof Schema.String>>;
+    }>>;
 }>, Schema.Struct<{
     threadId: typeof Schema.String;
     commentId: typeof Schema.String;
@@ -89,6 +95,12 @@ export declare const listDescriptor: QueryProcedureDescriptor<"comments.list", S
 }>, Schema.Array$<Schema.Struct<{
     id: typeof Schema.String;
     anchor: typeof Schema.String;
+    /** The selected passage the thread was opened on, if any. */
+    quote: Schema.NullOr<Schema.Struct<{
+        exact: Schema.filter<Schema.filter<typeof Schema.String>>;
+        prefix: Schema.optional<Schema.filter<typeof Schema.String>>;
+        suffix: Schema.optional<Schema.filter<typeof Schema.String>>;
+    }>>;
     status: Schema.Literal<["open", "resolved"]>;
     createdBy: typeof Schema.String;
     createdAt: typeof Schema.String;

package/dist/rpc.js

@@ -1,161 +1,2 @@
-import { CommentAccessRefused as e, CommentNotFound as t, CommentNotYours as n } from "./errors.js";
-import { Schema as r } from "effect";
-import { defineMutation as i, defineQuery as a, reactivityChannel as o } from "@voltro/protocol";
-//#region src/rpc.ts
-var s = "@voltro/plugin-comments", c = o("comments"), l = r.Struct({
-	id: r.String,
-	threadId: r.String,
-	body: r.String,
-	authorSubjectId: r.String,
-	mentions: r.Array(r.String),
-	editedAt: r.NullOr(r.String),
-	createdAt: r.String,
-	reactions: r.Array(r.Struct({
-		emoji: r.String,
-		count: r.Number,
-		mine: r.Boolean
-	}))
-}), u = r.Struct({
-	id: r.String,
-	anchor: r.String,
-	status: r.Literal("open", "resolved"),
-	createdBy: r.String,
-	createdAt: r.String,
-	comments: r.Array(l),
-	unreadCount: r.Number
-}), d = a({
-	name: "comments.list",
-	source: c,
-	input: r.Struct({ anchor: r.String }),
-	output: r.Array(u),
-	error: e,
-	openAccess: "delegated: the executor runs the app-declared anchor access rule (viaEntity guard or scope) and is fail-closed — an undeclared rule refuses every read"
-}), f = i({
-	name: "comments.create",
-	input: r.Struct({
-		anchor: r.String,
-		body: r.String,
-		threadId: r.optional(r.String),
-		mentions: r.optional(r.Array(r.String))
-	}),
-	output: r.Struct({
-		threadId: r.String,
-		commentId: r.String
-	}),
-	error: r.Union(e, t),
-	openAccess: "delegated: the executor runs the app-declared anchor access rule before any write; the author is always the calling subject"
-}), p = i({
-	name: "comments.edit",
-	input: r.Struct({
-		commentId: r.String,
-		body: r.String
-	}),
-	output: r.Struct({ ok: r.Boolean }),
-	error: r.Union(e, t, n),
-	openAccess: "author-scoped: only the comment's own author may edit, checked in the executor on top of the anchor access rule"
-}), m = i({
-	name: "comments.resolve",
-	input: r.Struct({
-		threadId: r.String,
-		resolved: r.Boolean
-	}),
-	output: r.Struct({ ok: r.Boolean }),
-	error: r.Union(e, t),
-	openAccess: "delegated: anchor access rule in the executor — anyone who may read the anchor may resolve/reopen (the Liveblocks semantic)"
-}), h = i({
-	name: "comments.delete",
-	input: r.Struct({ commentId: r.String }),
-	output: r.Struct({ ok: r.Boolean }),
-	error: r.Union(e, t, n),
-	openAccess: "author-scoped, with a comments:moderate scope override — both checked in the executor on top of the anchor access rule"
-}), g = i({
-	name: "comments.react",
-	input: r.Struct({
-		commentId: r.String,
-		emoji: r.String
-	}),
-	output: r.Struct({ reacted: r.Boolean }),
-	error: r.Union(e, t),
-	openAccess: "delegated: anchor access rule in the executor; the toggle writes only the calling subject's own reaction row"
-}), _ = i({
-	name: "comments.markRead",
-	input: r.Struct({ threadId: r.String }),
-	output: r.Struct({ ok: r.Boolean }),
-	error: t,
-	openAccess: "self-scoped write: stamps only the calling subject's own read marker for the thread"
-}), v = a({
-	name: "comments.mentionSearch",
-	input: r.Struct({ query: r.String }),
-	output: r.Array(r.Struct({
-		subjectId: r.String,
-		label: r.String
-	})),
-	openAccess: "delegated: the app-declared mention resolver receives the CALLING subject and its default filters to the caller's tenant — cross-tenant subjects are structurally unreachable"
-}), y = [
-	{
-		tag: "comments.list",
-		kind: "query",
-		import: {
-			module: "@voltro/plugin-comments/rpc",
-			name: "listDescriptor"
-		}
-	},
-	{
-		tag: "comments.create",
-		kind: "mutation",
-		import: {
-			module: "@voltro/plugin-comments/rpc",
-			name: "createDescriptor"
-		}
-	},
-	{
-		tag: "comments.edit",
-		kind: "mutation",
-		import: {
-			module: "@voltro/plugin-comments/rpc",
-			name: "editDescriptor"
-		}
-	},
-	{
-		tag: "comments.resolve",
-		kind: "mutation",
-		import: {
-			module: "@voltro/plugin-comments/rpc",
-			name: "resolveDescriptor"
-		}
-	},
-	{
-		tag: "comments.delete",
-		kind: "mutation",
-		import: {
-			module: "@voltro/plugin-comments/rpc",
-			name: "deleteDescriptor"
-		}
-	},
-	{
-		tag: "comments.react",
-		kind: "mutation",
-		import: {
-			module: "@voltro/plugin-comments/rpc",
-			name: "reactDescriptor"
-		}
-	},
-	{
-		tag: "comments.markRead",
-		kind: "mutation",
-		import: {
-			module: "@voltro/plugin-comments/rpc",
-			name: "markReadDescriptor"
-		}
-	},
-	{
-		tag: "comments.mentionSearch",
-		kind: "query",
-		import: {
-			module: "@voltro/plugin-comments/rpc",
-			name: "mentionSearchDescriptor"
-		}
-	}
-];
-//#endregion
-export { s as BASE_NAME, c as commentsFeed, y as commentsRpcClientImports, f as createDescriptor, h as deleteDescriptor, p as editDescriptor, d as listDescriptor, _ as markReadDescriptor, v as mentionSearchDescriptor, g as reactDescriptor, m as resolveDescriptor };
+import { a as e, c as t, d as n, i as r, l as i, n as a, o, r as s, s as c, t as l, u } from "./rpc-DlFs6xXs.js";
+export { l as BASE_NAME, a as commentsFeed, s as commentsRpcClientImports, r as createDescriptor, e as deleteDescriptor, o as editDescriptor, c as listDescriptor, t as markReadDescriptor, i as mentionSearchDescriptor, u as reactDescriptor, n as resolveDescriptor };

package/dist/web.d.ts

@@ -1,3 +1,12 @@
+export declare interface CommentQuote {
+    /** The selected text. */
+    readonly exact: string;
+    /** Up to 32 characters just before it, to tell repeated passages apart. */
+    readonly prefix?: string;
+    /** Up to 32 characters just after it. */
+    readonly suffix?: string;
+}
+
 export declare interface CommentReactionView {
     readonly emoji: string;
     readonly count: number;
@@ -15,9 +24,28 @@ export declare interface CommentView {
     readonly reactions: ReadonlyArray<CommentReactionView>;
 }
 
+/**
+ * Where `quote` stands in `text` now: `{ start, end }`, or null when the text
+ * no longer holds the passage. With the passage more than once, the one whose
+ * surroundings match the quote's prefix and suffix best wins (the first on a
+ * tie).
+ */
+export declare const findQuote: (text: string, quote: CommentQuote) => {
+    readonly start: number;
+    readonly end: number;
+} | null;
+
+/** The longest quoted passage a thread keeps. */
+export declare const QUOTE_MAX_LENGTH = 1000;
+
+/** The quote for `text` between `start` and `end` (a text control's selection). */
+export declare const textQuote: (text: string, start: number, end: number) => CommentQuote;
+
 export declare interface ThreadView {
     readonly id: string;
     readonly anchor: string;
+    /** The selected passage the thread was opened on, if any. */
+    readonly quote: CommentQuote | null;
     readonly status: 'open' | 'resolved';
     readonly createdBy: string;
     readonly createdAt: string;
@@ -37,9 +65,11 @@ export declare interface UseCommentsResult {
     readonly pending: boolean;
     /** Sum of the threads' unread counters — the badge number. */
     readonly unreadCount: number;
+    /** A reply with `threadId`; a new thread otherwise, on the passage `quote` if given. */
     readonly create: (body: string, opts?: {
         threadId?: string;
         mentions?: ReadonlyArray<string>;
+        quote?: CommentQuote;
     }) => Promise<unknown>;
     readonly edit: (commentId: string, body: string) => Promise<unknown>;
     readonly resolve: (threadId: string, resolved?: boolean) => Promise<unknown>;

package/dist/web.js

@@ -1,18 +1,19 @@
-import { BASE_NAME as e } from "./rpc.js";
-import { pluginTag as t } from "@voltro/protocol";
-import { useMutation as n, useSubscription as r } from "@voltro/client";
+import { f as e, m as t, p as n, t as r } from "./rpc-DlFs6xXs.js";
+import { pluginTag as i } from "@voltro/protocol";
+import { useMutation as a, useSubscription as o } from "@voltro/client";
 //#region src/web.ts
-var i = (n) => t(e, n), a = (e, t = "app") => {
-	let { data: a, loading: o } = r(t, i("list"), { anchor: e }), s = n(t, i("create")), c = n(t, i("edit")), l = n(t, i("resolve")), u = n(t, i("delete")), d = n(t, i("react")), f = n(t, i("markRead")), p = a ?? [];
+var s = (e) => i(r, e), c = (e, t = "app") => {
+	let { data: n, loading: r } = o(t, s("list"), { anchor: e }), i = a(t, s("create")), c = a(t, s("edit")), l = a(t, s("resolve")), u = a(t, s("delete")), d = a(t, s("react")), f = a(t, s("markRead")), p = n ?? [];
 	return {
 		threads: p,
-		pending: o,
+		pending: r,
 		unreadCount: p.reduce((e, t) => e + t.unreadCount, 0),
-		create: (t, n) => s.mutate({
+		create: (t, n) => i.mutate({
 			anchor: e,
 			body: t,
 			...n?.threadId === void 0 ? {} : { threadId: n.threadId },
-			...n?.mentions === void 0 ? {} : { mentions: n.mentions }
+			...n?.mentions === void 0 ? {} : { mentions: n.mentions },
+			...n?.quote === void 0 ? {} : { quote: n.quote }
 		}),
 		edit: (e, t) => c.mutate({
 			commentId: e,
@@ -29,9 +30,9 @@ var i = (n) => t(e, n), a = (e, t = "app") => {
 		}),
 		markRead: (e) => f.mutate({ threadId: e })
 	};
-}, o = (e, t, n = "app") => a(e, n).threads.find((e) => e.id === t), s = (e, t = "app") => {
-	let { data: n } = r(t, i("mentionSearch"), { query: e });
+}, l = (e, t, n = "app") => c(e, n).threads.find((e) => e.id === t), u = (e, t = "app") => {
+	let { data: n } = o(t, s("mentionSearch"), { query: e });
 	return n ?? [];
 };
 //#endregion
-export { a as useComments, s as useMentionSearch, o as useThread };
+export { e as QUOTE_MAX_LENGTH, n as findQuote, t as textQuote, c as useComments, u as useMentionSearch, l as useThread };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-comments",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "description": "Comment threads on any anchor your app can name — replies, resolve/reopen, reactions, per-subject unread — live over the existing reactivity channel, with no second push mechanism. Access delegates to your app's own guard (access.viaEntity) or a scope and fails closed when neither is declared; @-mentions are re-filtered to the caller's tenant on search and re-validated at create, then delivered through plugin-notifications when it is installed. useComments / useThread / useMentionSearch in /web, an ejectable <CommentsThread> in @voltro/ui, plus inspect endpoints and a dashboard panel.",
   "keywords": [
     "voltro",
@@ -48,9 +48,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.81.0",
-    "@voltro/plugin-notifications": "0.81.0",
-    "@voltro/protocol": "0.81.0"
+    "@voltro/database": "0.82.0",
+    "@voltro/plugin-notifications": "0.82.0",
+    "@voltro/protocol": "0.82.0"
   },
   "peerDependencies": {
     "effect": "^3.22.2",