@imenam/mcp-documentor 1.0.94 → 1.0.95

package/README.md

@@ -139,6 +139,9 @@ that work on a whole project (`list_docs`, `get_doc_tree`, `check_freshness` wit
 | `get_code_source` | Show each project's code source (local working copy or GitHub branch) and its code root on this machine |
 | `set_code_source` | Make a project read its local working copy or one branch of a GitHub repository (checked before saving) |
 | `set_code_root` | Set the code root of a project, or the machine default, on this machine |
+| `list_comments` | List readers' comments on published documents (`project` required; one doc with `path`; `status`: `all`, `unread` or `detached`) |
+| `mark_comments_read` | Mark comments of a published doc as read, or unread with `read: false`; every comment of the doc when `ids` is omitted (`project` required) |
+| `delete_comments` | Delete comments of a published doc, replies included (`project` required) |
 
 ## Images in documents
 
@@ -175,9 +178,28 @@ A document can be shared, read-only, with anyone who holds its link — no accou
 - **Unpublish** — revokes the link after a confirmation: it answers 404 at once. Publishing again creates a new link.
 - **Publications page** — the globe of the rail lists every published document of the current project: version note, publication date, state (*Up to date*, *Changed · v12 → v14*, or *Document removed*), with Update, copy, open and Unpublish on each row. *Changed* keeps only the publications that lag behind their document.
 
-What the reader sees is the viewer's rendering (code highlighting, Mermaid, tables, images) without any action. The page shows the document alone — title, publication date, version and note — and nothing about where it comes from: no project name, no header bar. An *On this page* table of contents of the document's headings sits on the right and follows the scroll; it is hidden below 1024 px wide. Web links stay active and open in a new tab; links to other documents become plain text; in-page anchors work. Images uploaded to the project are copied into the snapshot when it is frozen, so the page never changes until the publication is updated.
+What the reader sees is the viewer's rendering (code highlighting, Mermaid, tables, images) without any action. The page shows the document alone — title, publication date, version and note — and nothing about where it comes from: no project name, no header bar. A **Contents** button lists the document's headings. Web links stay active and open in a new tab; links to other documents become plain text; in-page anchors work. Images uploaded to the project are copied into the snapshot when it is frozen, so the page never changes until the publication is updated.
 
-**The link** is a *capability URL*: its last segment is a 32-byte random token, and holding it is the only authorization. The page is served under `public/<token>/` next to the GUI, or under `/_pub/<route of the GUI>/<token>/` behind the mcp-gateway-manager hub, which relays that prefix without a session. Every public response carries `X-Robots-Tag: noindex, nofollow, noarchive` and `Referrer-Policy: no-referrer` (the token never leaks to the sites the reader opens), and the page has a strict Content-Security-Policy. The page embeds the frozen document: it makes no API call.
+### Comments
+
+Readers can comment on a published document, without an account:
+
+- **Commenting** — a click on a word selects it, a drag selects a passage (over several lines if needed); a **Comment** button appears above it. The form takes an optional name, remembered by the browser, and the comment (Ctrl/⌘ + Enter sends it). Readers can reply to a comment.
+- **In the margins** — each comment is a card next to its passage, in the margin on the passage's side (left half of the text: left margin), linked to it by a line; the passage is highlighted. Cards that would overlap are pushed down. From 1080 to 1400 px wide every card goes to the right margin; below 1080 px, a click on a highlighted passage opens its comment in a panel at the bottom of the screen. The **N comments** button hides or shows them all.
+- **Limits** — 20 comments per publication, replies included, and 2,000 characters per comment. A deleted comment frees its place; a comment marked as read does not. Behind the hub, a client sending more than 15 comments in a minute is refused, against automated posting.
+- **Names** — the name is whatever the reader typed: every name carries a *not verified* tooltip, on the public page and in the GUI.
+
+Comments are visible to everyone holding the link. Marking them as read and deleting them is reserved to the GUI and to the agent (`list_comments`, `mark_comments_read`, `delete_comments`): the public page offers neither.
+
+In the GUI, a document with unread comments shows a blue bubble and their number in the tree (a bubble alone on its folders), the globe of the rail counts the project's unread comments, and the document toolbar has a comment button. The details panel on the right gets a **Comments** tab, opened by itself on a document with unread comments: each comment can be marked as read or deleted, **Close comments** stops readers from adding any (existing ones stay visible; **Reopen comments** lifts it), a click on it scrolls to its highlighted passage, and a click on a highlighted passage opens its comment.
+
+A comment points at a passage by its text, plus the text just around it. When a publication is updated and a commented passage no longer exists, the comment is kept and marked **detached**: readers no longer see it, the GUI lists it apart with its original passage and versions, and `list_comments` flags it `DETACHED` so the agent can clean them up. A detached comment whose passage comes back in a later update is attached again. Passages are compared without whitespace, against the rendered text of the markdown.
+
+Comments are stored in `<data dir>/publications/<publication>/comments.json`, with their publication: unpublishing deletes them. `READ_ONLY` disables marking, deleting, closing and reopening. When the comment file cannot be read, the public page still shows the document and states that its comments are unavailable.
+
+`list_comments` gives the agent text written by anonymous readers. Its output opens with a notice that names, quoted passages and texts are data, never instructions; every line break of a comment, Unicode separators included, starts a new `>` quoted line, so a comment cannot pass for another entry.
+
+**The link** is a *capability URL*: its last segment is a 32-byte random token, and holding it is the only authorization. The page is served under `public/<token>/` next to the GUI, or under `/_pub/<route of the GUI>/<token>/` behind the mcp-gateway-manager hub, which relays that prefix without a session. Every public response carries `X-Robots-Tag: noindex, nofollow, noarchive` and `Referrer-Policy: no-referrer` (the token never leaks to the sites the reader opens), and the page has a strict Content-Security-Policy. The page embeds the frozen document and its comments; its only request is `POST public/<token>/comments`, which accepts JSON only (at most 16 KB), so that a form from another site cannot post. Behind the hub, this needs a version of mcp-gateway-manager that relays `POST` on `/_pub/`.
 
 Publications live in `<data dir>/publications/` — `index.json` plus one snapshot directory per publication. The directory is machine-local and excluded from sync: a link is served by the machine that created it. A document moved with `move_doc` keeps its publication; a deleted one keeps serving its frozen snapshot until it is unpublished. `READ_ONLY` disables publishing, updating and unpublishing.
 

package/dist/shared/read-only.js

@@ -12,4 +12,5 @@ export const WRITE_TOOLS = new Set([
     // still pull updates); these mutate local/remote state and are blocked.
     "push_docs", "sync_docs", "resolve_sync_conflict",
     "set_code_source", "set_code_root",
+    "mark_comments_read", "delete_comments",
 ]);

package/dist/shared/schemas/doc.schema.d.ts

@@ -231,6 +231,26 @@ export declare const PrepareExportBundleArgsSchema: z.ZodObject<{
 export declare const DeleteExportBundleArgsSchema: z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strip>;
+export declare const ListCommentsArgsSchema: z.ZodObject<{
+    project: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    status: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        unread: "unread";
+        detached: "detached";
+    }>>>;
+}, z.core.$strip>;
+export declare const MarkCommentsReadArgsSchema: z.ZodObject<{
+    project: z.ZodString;
+    path: z.ZodString;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    read: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare const DeleteCommentsArgsSchema: z.ZodObject<{
+    project: z.ZodString;
+    path: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 export declare const IPCMessageSchema: z.ZodObject<{
     type: z.ZodString;
     correlationId: z.ZodOptional<z.ZodString>;

package/dist/shared/schemas/doc.schema.js

@@ -215,6 +215,26 @@ export const PrepareExportBundleArgsSchema = z.object({
 export const DeleteExportBundleArgsSchema = z.object({
     id: z.string().describe("Bundle identifier to delete (slug)"),
 });
+export const ListCommentsArgsSchema = z.object({
+    project: requiredProject("the comment lookup"),
+    path: z.string().optional().describe("Published document whose comments are listed. Every published document of the project if omitted."),
+    status: z
+        .enum(["all", "unread", "detached"])
+        .optional()
+        .default("all")
+        .describe("'unread': not yet marked as read. 'detached': their passage disappeared when the publication was updated."),
+});
+export const MarkCommentsReadArgsSchema = z.object({
+    project: requiredProject("the update"),
+    path: z.string().describe("Published document the comments belong to"),
+    ids: z.array(z.string()).min(1).optional().describe("Comments to mark, as listed by list_comments. Every comment of the document if omitted."),
+    read: z.boolean().optional().default(true).describe("false marks them as unread again"),
+});
+export const DeleteCommentsArgsSchema = z.object({
+    project: requiredProject("the deletion"),
+    path: z.string().describe("Published document the comments belong to"),
+    ids: z.array(z.string()).min(1).describe("Comments to delete, as listed by list_comments. Deleting a comment deletes its replies."),
+});
 export const IPCMessageSchema = z.object({
     type: z.string(),
     correlationId: z.string().optional(),

package/dist/src/core/comment-store.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Comments left by readers of a public link, in `<data dir>/publications/<publication id>/comments.json`.
+ * They live with their publication: unpublishing deletes them.
+ *
+ * A comment is anchored to a passage of the published text by a quote selector — the passage
+ * itself plus the text just before and after it. Replies carry no anchor: they belong to the
+ * thread of their root comment. When a publication is updated and its passage no longer exists,
+ * the comment is kept and marked detached.
+ */
+/** Passage a comment points at, as text of the rendered document. */
+export interface CommentAnchor {
+    exact: string;
+    /** Text just before the passage, to tell apart two identical passages. */
+    prefix: string;
+    /** Text just after the passage. */
+    suffix: string;
+}
+export interface CommentDetachment {
+    at: string;
+    /** Version the comment was anchored in. */
+    fromVersion: number | null;
+    /** Version published without its passage. */
+    toVersion: number | null;
+}
+export interface PublicationComment {
+    id: string;
+    /** Root comment of the thread, null for a root comment. */
+    parentId: string | null;
+    /** Null for a reply. */
+    anchor: CommentAnchor | null;
+    /** Name given by the reader, "" when none was given. */
+    author: string;
+    body: string;
+    createdAt: string;
+    /** Publication version the comment was written on. */
+    version: number | null;
+    /** Marked as read by the documentation owner. */
+    read: boolean;
+    /** Set when the passage disappeared from the published version. Replies follow their root. */
+    detached: CommentDetachment | null;
+}
+/** What the public page shows of a comment. */
+export interface PublicComment {
+    id: string;
+    parentId: string | null;
+    anchor: CommentAnchor | null;
+    author: string;
+    body: string;
+    createdAt: string;
+}
+export interface NewCommentInput {
+    parentId?: unknown;
+    anchor?: unknown;
+    author?: unknown;
+    body?: unknown;
+}
+/** Comments a publication accepts, replies included. */
+export declare const MAX_COMMENTS = 20;
+export declare const MAX_BODY_LENGTH = 2000;
+export declare const MAX_AUTHOR_LENGTH = 80;
+export declare const MAX_QUOTE_LENGTH = 500;
+export declare const MAX_CONTEXT_LENGTH = 64;
+/** A request a reader can correct (400), or a limit the publication reached (409). */
+export declare class CommentInputError extends Error {
+    readonly status: 400 | 409;
+    constructor(message: string, status?: 400 | 409);
+}
+export declare function toPublicComment(comment: PublicationComment): PublicComment;
+export declare class CommentStore {
+    private readonly dataDir;
+    constructor(dataDir: string);
+    private filePath;
+    list(publicationId: string): PublicationComment[];
+    /** Comments the public page shows: detached ones have no passage to sit next to. */
+    listPublic(publicationId: string): PublicComment[];
+    add(publicationId: string, version: number | null, input: NewCommentInput): PublicationComment;
+    /** Marks comments as read or unread; returns how many changed. */
+    setRead(publicationId: string, ids: string[] | null, read: boolean): number;
+    /** Deletes comments, and the replies of the root comments deleted; returns how many were removed. */
+    delete(publicationId: string, ids: string[]): number;
+    /**
+     * Checks every root comment against the text of a newly published version: a comment whose
+     * passage is gone becomes detached, one whose passage is back is attached again.
+     */
+    reanchor(publicationId: string, publishedText: string, version: number | null): number;
+    private write;
+}

package/dist/src/core/comment-store.js

@@ -0,0 +1,189 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { compactText } from "./markdown-text.js";
+/** Comments a publication accepts, replies included. */
+export const MAX_COMMENTS = 20;
+export const MAX_BODY_LENGTH = 2000;
+export const MAX_AUTHOR_LENGTH = 80;
+export const MAX_QUOTE_LENGTH = 500;
+export const MAX_CONTEXT_LENGTH = 64;
+/** A request a reader can correct (400), or a limit the publication reached (409). */
+export class CommentInputError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}
+function requireString(value, field) {
+    if (typeof value !== "string")
+        throw new CommentInputError(`${field} must be a string`);
+    return value;
+}
+function optionalString(value, field) {
+    if (value === undefined || value === null)
+        return "";
+    return requireString(value, field);
+}
+function collapseWhitespace(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function parseAnchor(value) {
+    if (!value || typeof value !== "object")
+        throw new CommentInputError("anchor is required");
+    const raw = value;
+    const exact = collapseWhitespace(requireString(raw.exact, "anchor.exact"));
+    if (compactText(exact) === "")
+        throw new CommentInputError("anchor.exact is empty");
+    if (exact.length > MAX_QUOTE_LENGTH) {
+        throw new CommentInputError(`The selected passage is limited to ${MAX_QUOTE_LENGTH} characters`);
+    }
+    const prefix = collapseWhitespace(optionalString(raw.prefix, "anchor.prefix")).slice(-MAX_CONTEXT_LENGTH);
+    const suffix = collapseWhitespace(optionalString(raw.suffix, "anchor.suffix")).slice(0, MAX_CONTEXT_LENGTH);
+    return { exact, prefix, suffix };
+}
+export function toPublicComment(comment) {
+    return {
+        id: comment.id,
+        parentId: comment.parentId,
+        anchor: comment.anchor,
+        author: comment.author,
+        body: comment.body,
+        createdAt: comment.createdAt,
+    };
+}
+/** Root comment of a thread, or the comment itself when it is a root. */
+function rootOf(comments, comment) {
+    return comment.parentId ? comments.find((c) => c.id === comment.parentId) ?? comment : comment;
+}
+export class CommentStore {
+    dataDir;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    filePath(publicationId) {
+        return path.join(this.dataDir, "publications", publicationId, "comments.json");
+    }
+    list(publicationId) {
+        const file = this.filePath(publicationId);
+        if (!fs.existsSync(file))
+            return [];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+            if (!Array.isArray(parsed))
+                throw new Error("not an array");
+            return parsed;
+        }
+        catch (err) {
+            throw new Error(`${file} is not a valid comment file (${err.message}) — fix or delete it.`);
+        }
+    }
+    /** Comments the public page shows: detached ones have no passage to sit next to. */
+    listPublic(publicationId) {
+        const comments = this.list(publicationId);
+        return comments.filter((c) => !rootOf(comments, c).detached).map(toPublicComment);
+    }
+    add(publicationId, version, input) {
+        const comments = this.list(publicationId);
+        if (comments.length >= MAX_COMMENTS) {
+            throw new CommentInputError(`This document accepts no more comments (limit: ${MAX_COMMENTS})`, 409);
+        }
+        const body = requireString(input.body, "body").trim();
+        if (body === "")
+            throw new CommentInputError("The comment is empty");
+        if (body.length > MAX_BODY_LENGTH) {
+            throw new CommentInputError(`A comment is limited to ${MAX_BODY_LENGTH} characters`);
+        }
+        const author = collapseWhitespace(optionalString(input.author, "author"));
+        if (author.length > MAX_AUTHOR_LENGTH) {
+            throw new CommentInputError(`A name is limited to ${MAX_AUTHOR_LENGTH} characters`);
+        }
+        let parentId = null;
+        let anchor = null;
+        if (input.parentId !== undefined && input.parentId !== null) {
+            const parent = comments.find((c) => c.id === requireString(input.parentId, "parentId"));
+            const root = parent ? rootOf(comments, parent) : undefined;
+            if (!root || root.detached)
+                throw new CommentInputError("The comment answered no longer exists");
+            parentId = root.id;
+        }
+        else {
+            anchor = parseAnchor(input.anchor);
+        }
+        const comment = {
+            id: crypto.randomBytes(8).toString("hex"),
+            parentId,
+            anchor,
+            author,
+            body,
+            createdAt: new Date().toISOString(),
+            version,
+            read: false,
+            detached: null,
+        };
+        this.write(publicationId, [...comments, comment]);
+        return comment;
+    }
+    /** Marks comments as read or unread; returns how many changed. */
+    setRead(publicationId, ids, read) {
+        const comments = this.list(publicationId);
+        const wanted = ids ? new Set(ids) : null;
+        let changed = 0;
+        const next = comments.map((c) => {
+            if ((wanted && !wanted.has(c.id)) || c.read === read)
+                return c;
+            changed++;
+            return { ...c, read };
+        });
+        if (changed > 0)
+            this.write(publicationId, next);
+        return changed;
+    }
+    /** Deletes comments, and the replies of the root comments deleted; returns how many were removed. */
+    delete(publicationId, ids) {
+        const comments = this.list(publicationId);
+        const removed = new Set(ids.filter((id) => comments.some((c) => c.id === id)));
+        for (const c of comments)
+            if (c.parentId && removed.has(c.parentId))
+                removed.add(c.id);
+        if (removed.size === 0)
+            return 0;
+        this.write(publicationId, comments.filter((c) => !removed.has(c.id)));
+        return removed.size;
+    }
+    /**
+     * Checks every root comment against the text of a newly published version: a comment whose
+     * passage is gone becomes detached, one whose passage is back is attached again.
+     */
+    reanchor(publicationId, publishedText, version) {
+        const comments = this.list(publicationId);
+        const text = compactText(publishedText);
+        const now = new Date().toISOString();
+        let changed = 0;
+        const next = comments.map((c) => {
+            if (!c.anchor)
+                return c;
+            const found = text.includes(compactText(c.anchor.exact));
+            if (found && c.detached) {
+                changed++;
+                return { ...c, detached: null };
+            }
+            if (!found && !c.detached) {
+                changed++;
+                return { ...c, detached: { at: now, fromVersion: c.version, toVersion: version } };
+            }
+            return c;
+        });
+        if (changed > 0)
+            this.write(publicationId, next);
+        return changed;
+    }
+    write(publicationId, comments) {
+        const file = this.filePath(publicationId);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const temp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(temp, JSON.stringify(comments, null, 2), "utf-8");
+        fs.renameSync(temp, file);
+    }
+}

package/dist/src/core/markdown-text.d.ts

@@ -0,0 +1,7 @@
+/** Text a reader sees once the markdown is rendered: markup removed, code kept. */
+export declare function markdownText(content: string): string;
+/**
+ * Text with every whitespace removed. Rendered text and markdown text differ in the whitespace
+ * between blocks; comparing without it makes a passage found in one found in the other.
+ */
+export declare function compactText(text: string): string;

package/dist/src/core/markdown-text.js

@@ -0,0 +1,16 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { gfm } from "micromark-extension-gfm";
+import { toString } from "mdast-util-to-string";
+/** Text a reader sees once the markdown is rendered: markup removed, code kept. */
+export function markdownText(content) {
+    const tree = fromMarkdown(content, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] });
+    return toString(tree, { includeImageAlt: false });
+}
+/**
+ * Text with every whitespace removed. Rendered text and markdown text differ in the whitespace
+ * between blocks; comparing without it makes a passage found in one found in the other.
+ */
+export function compactText(text) {
+    return text.replace(/\s+/g, "");
+}

package/dist/src/core/publication-store.d.ts

@@ -28,6 +28,8 @@ export interface Publication {
     createdAt: string;
     /** When the current snapshot was frozen. */
     publishedAt: string;
+    /** True when readers can no longer add comments; absent or false when they can. */
+    commentsClosed?: boolean;
 }
 /** Content and images of a document at the moment it is frozen. */
 export interface FreezeInput {
@@ -66,6 +68,8 @@ export declare class PublicationStore {
     update(id: string, input: FreezeInput): Publication;
     /** Revokes the link: the publication and its snapshots are deleted. */
     unpublish(id: string): Publication;
+    /** Opens or closes the publication to new comments. Existing comments stay visible. */
+    setCommentsClosed(id: string, closed: boolean): Publication;
     /** Follows a document to its new place. Returns true when a publication was moved. */
     moveDoc(project: string, docId: string, newProject: string, newDocId: string): boolean;
     private require;

package/dist/src/core/publication-store.js

@@ -137,6 +137,12 @@ export class PublicationStore {
         fs.rmSync(path.join(this.rootDir, id), { recursive: true, force: true });
         return publication;
     }
+    /** Opens or closes the publication to new comments. Existing comments stay visible. */
+    setCommentsClosed(id, closed) {
+        const publication = { ...this.require(id), commentsClosed: closed };
+        this.writeIndex(this.list().map((p) => (p.id === id ? publication : p)));
+        return publication;
+    }
     /** Follows a document to its new place. Returns true when a publication was moved. */
     moveDoc(project, docId, newProject, newDocId) {
         const publications = this.list();

package/dist/src/gui-worker.js

@@ -16,6 +16,7 @@ import { createLogger, setupLogging } from "@imenam/mcp-gui-interface";
 import { resolveLogDir } from "./core/log-dir.js";
 import { isLogSource, logFileInfo, readGitHubLog, readServerLog } from "./core/log-reader.js";
 import { isSafeSegment, PublicationStore } from "./core/publication-store.js";
+import { CommentStore, MAX_AUTHOR_LENGTH, MAX_BODY_LENGTH, MAX_COMMENTS, MAX_QUOTE_LENGTH, } from "./core/comment-store.js";
 import matter from "gray-matter";
 import JSZip from "jszip";
 import puppeteer from "puppeteer-core";
@@ -180,6 +181,7 @@ const BROADCAST_TYPES = [
     "DOCS_CHANGED",
     "CODE_SOURCES_CHANGED",
     "PUBLICATIONS_CHANGED",
+    "COMMENTS_CHANGED",
 ];
 /** Number of pushed messages kept for clients catching up. */
 const CHANGE_JOURNAL_SIZE = 200;
@@ -237,6 +239,7 @@ const READ_ONLY_WRITE_ROUTES = [
     { method: "POST", prefix: "/api/code-roots/apply" },
     { method: "POST", prefix: "/api/publications" },
     { method: "DELETE", prefix: "/api/publications" },
+    { method: "POST", prefix: "/api/comments/" },
 ];
 app.use("*", async (c, next) => {
     if (isReadOnly()) {
@@ -431,11 +434,36 @@ app.post("/api/publications/:publicationId/update", async (c) => {
     return relay(c, "UPDATE_PUBLICATION", { publicationId: c.req.param("publicationId"), note }, 15000, 400);
 });
 app.delete("/api/publications/:publicationId", (c) => relay(c, "UNPUBLISH_DOC", { publicationId: c.req.param("publicationId") }, 15000, 400));
+// --- Comments ---
+// Written by the master; the GUI reads them per document and as counts for the badges.
+app.get("/api/comments/summary", (c) => relay(c, "COMMENTS_SUMMARY", { project: c.req.query("project") }, 15000));
+app.get("/api/comments", (c) => relay(c, "LIST_DOC_COMMENTS", { project: c.req.query("project"), docId: c.req.query("doc") }, 15000, 400));
+app.post("/api/comments/read", async (c) => {
+    const { publicationId, ids, read } = await readJson(c);
+    return relay(c, "SET_COMMENTS_READ", { publicationId, ids, read }, 15000, 400);
+});
+app.post("/api/comments/delete", async (c) => {
+    const { publicationId, ids } = await readJson(c);
+    return relay(c, "DELETE_COMMENTS", { publicationId, ids }, 15000, 400);
+});
+app.post("/api/comments/closed", async (c) => {
+    const { publicationId, closed } = await readJson(c);
+    return relay(c, "SET_COMMENTS_CLOSED", { publicationId, closed }, 15000, 400);
+});
 // --- Public pages ---
 // `/public/<token>/` serves a frozen document to anyone holding the link, with no session. It is
 // the only route a hub relays without authentication: everything it answers stays under it.
 // Read straight from the publication store, so a page never waits on the master.
 const publicationStore = new PublicationStore(dataDir);
+const commentStore = new CommentStore(dataDir);
+/** Largest comment request a public page may send. */
+const MAX_COMMENT_REQUEST_BYTES = 16 * 1024;
+const COMMENT_LIMITS = {
+    comments: MAX_COMMENTS,
+    body: MAX_BODY_LENGTH,
+    author: MAX_AUTHOR_LENGTH,
+    quote: MAX_QUOTE_LENGTH,
+};
 /** Tokens are 32 random bytes in base64url. */
 const PUBLIC_TOKEN = /^[A-Za-z0-9_-]{43}$/;
 const PUBLIC_HEADERS = {
@@ -477,9 +505,54 @@ function jsonForScript(value) {
 function escapeHtml(value) {
     return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-app.all("/public/*", (c) => {
-    if (c.req.method !== "GET" && c.req.method !== "HEAD") {
-        return publicResponse("Method not allowed", 405, { Allow: "GET, HEAD", "Cache-Control": "no-store" });
+/**
+ * Comments shown on a public page. An unreadable comment file is reported as `comments: null`:
+ * the page then states that its comments are unavailable, and the document stays readable.
+ */
+function publicCommentsOf(publicationId) {
+    try {
+        return { comments: commentStore.listPublic(publicationId), commentsUsed: commentStore.list(publicationId).length };
+    }
+    catch (err) {
+        logger.error(`Comments of publication ${publicationId} are unavailable: ${err.message}`);
+        return { comments: null, commentsUsed: 0 };
+    }
+}
+function publicJson(value, status = 200) {
+    return publicResponse(JSON.stringify(value), status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+    });
+}
+/**
+ * `POST /public/<token>/comments`: a reader's comment, JSON only. A cross-site form cannot send
+ * JSON without a preflight this server never answers, so only the page itself can post.
+ */
+async function postPublicComment(c, publicationId) {
+    const type = String(c.req.header("content-type") ?? "").toLowerCase();
+    if (!type.startsWith("application/json"))
+        return publicJson({ error: "Comments are sent as JSON" }, 415);
+    const raw = await c.req.text();
+    if (Buffer.byteLength(raw) > MAX_COMMENT_REQUEST_BYTES)
+        return publicJson({ error: "Request too large" }, 413);
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        return publicJson({ error: "Invalid JSON" }, 400);
+    }
+    const result = await ipcRequest("ADD_PUBLIC_COMMENT", { publicationId, input }, 15000);
+    if (result.error)
+        return publicJson({ error: "The comment could not be saved" }, 500);
+    if (result.data?.rejected)
+        return publicJson({ error: result.data.rejected.message }, result.data.rejected.status);
+    return publicJson({ comments: result.data.comments, used: result.data.used });
+}
+app.all("/public/*", async (c) => {
+    const method = c.req.method;
+    if (method !== "GET" && method !== "HEAD" && method !== "POST") {
+        return publicResponse("Method not allowed", 405, { Allow: "GET, HEAD, POST", "Cache-Control": "no-store" });
     }
     let segments;
     try {
@@ -494,6 +567,11 @@ app.all("/public/*", (c) => {
     const publication = publicationStore.findByToken(token);
     if (!publication)
         return publicNotFound();
+    if (method === "POST") {
+        if (tail.length === 1 && tail[0] === "comments")
+            return postPublicComment(c, publication.id);
+        return publicResponse("Method not allowed", 405, { Allow: "GET, HEAD", "Cache-Control": "no-store" });
+    }
     // Relative URLs of the page resolve under the token only when its URL ends with a slash.
     if (tail.length === 0) {
         return publicResponse(null, 302, { Location: `${encodeURIComponent(token)}/`, "Cache-Control": "no-store" });
@@ -509,11 +587,15 @@ app.all("/public/*", (c) => {
             note: publication.note,
             publishedAt: publication.publishedAt,
             content: publicationStore.readContent(publication),
+            ...publicCommentsOf(publication.id),
+            commentsClosed: publication.commentsClosed === true,
+            commentLimits: COMMENT_LIMITS,
         };
+        // Replacer functions: a `$` pattern in the title or in a comment must stay literal.
         const html = fs
             .readFileSync(shellPath, "utf8")
-            .replace(/<title>[^<]*<\/title>/, `<title>${escapeHtml(publication.title)}</title>`)
-            .replace("</head>", `  <script id="publication-data" type="application/json">${jsonForScript(data)}</script>\n  </head>`);
+            .replace(/<title>[^<]*<\/title>/, () => `<title>${escapeHtml(publication.title)}</title>`)
+            .replace("</head>", () => `  <script id="publication-data" type="application/json">${jsonForScript(data)}</script>\n  </head>`);
         return publicResponse(html, 200, {
             "Content-Type": "text/html; charset=utf-8",
             "Cache-Control": "no-store",