@hienlh/ppm 0.23.13 → 0.23.15

package/src/services/design/comments/design-comments-store.ts

@@ -1,8 +1,13 @@
 import { copyFile } from "node:fs/promises";
 import { join } from "node:path";
 import {
-  COMMENT_ID_RE, COMMENT_LIMITS, parseCommentAnchor, type DesignComment,
+  COMMENT_ID_RE, COMMENT_LIMITS, parseCommentAnchor, parsePpmId, type PinnedAnchor,
 } from "../../../shared/design-comment-types.ts";
+import {
+  GUEST_KEY_HASH_RE, parseGuestName, SHARE_LINK_ID_RE,
+  type StoredCommentAuthor, type StoredCommentReply, type StoredDesignComment,
+} from "../../../shared/design-comment-thread-types.ts";
+import { DESIGN_GEN_RE, isSnapshotId } from "../../../shared/design-types.ts";
 import { dotDesignDir, lstatOrNull } from "../design-paths.ts";
 import { ensureDotDesign, writeFileAtomic } from "../design-fs.ts";
 import { readDesignFileSafe } from "../design-safe-walk.ts";
@@ -18,22 +23,77 @@ const log = createLogger("design");
  * as untrusted: every entry is re-validated and capped, and a file that does not parse is
  * treated as empty — after a copy is kept as `comments.json.bak`, so a hand edit gone wrong
  * is recoverable rather than silently replaced by the next save.
+ *
+ * Fields added after the first version (`author`, `replies`, `pinnedAnchor`) are optional
+ * and only written when present, so a file from before reviewers existed reads and writes
+ * back with the same meaning. An entry naming an author this parser cannot accept is
+ * dropped rather than read as the owner's.
  */
 
 export const COMMENTS_FILE = "comments.json";
 const MAX_FILE_BYTES = 16 * 1024 * 1024;
+/** Roots a file may hold: the owner's cap plus the most guest roots there can be. */
+const MAX_STORED_ROOTS = COMMENT_LIMITS.maxComments + COMMENT_LIMITS.maxGuestEntries;
 
 type Raw = Record<string, unknown>;
 const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
 const isoOrUndefined = (v: unknown): string | undefined =>
   typeof v === "string" && v.length <= 40 && !Number.isNaN(Date.parse(v)) ? v : undefined;
+const parseText = (v: unknown): string | null =>
+  typeof v === "string" && v.trim() ? v.slice(0, COMMENT_LIMITS.body) : null;
+
+/** Undefined when absent (the owner), null when present but not an author. */
+function parseAuthor(v: unknown): StoredCommentAuthor | undefined | null {
+  if (v === undefined) return undefined;
+  if (!isRaw(v)) return null;
+  if (v.kind === "owner") return { kind: "owner" };
+  if (v.kind !== "guest") return null;
+  const name = parseGuestName(v.name);
+  if (!name.ok || typeof v.linkId !== "string" || !SHARE_LINK_ID_RE.test(v.linkId)) return null;
+  if (typeof v.keyHash !== "string" || !GUEST_KEY_HASH_RE.test(v.keyHash)) return null;
+  return { kind: "guest", name: name.name, linkId: v.linkId, keyHash: v.keyHash };
+}
+
+function parsePinnedAnchor(v: unknown): PinnedAnchor | undefined {
+  if (!isRaw(v) || !isSnapshotId(v.snapshotId)) return undefined;
+  const ppmId = parsePpmId(v.ppmId);
+  const gen = v.gen === null ? null : typeof v.gen === "string" && DESIGN_GEN_RE.test(v.gen) ? v.gen : undefined;
+  if (ppmId === undefined || gen === undefined) return undefined;
+  return { snapshotId: v.snapshotId, ppmId, gen };
+}
+
+function parseReply(v: unknown): StoredCommentReply | null {
+  if (!isRaw(v) || typeof v.id !== "string" || !COMMENT_ID_RE.test(v.id)) return null;
+  const body = parseText(v.body);
+  const createdAt = isoOrUndefined(v.createdAt);
+  // A reply is written with its author; one without is read as the owner's, like a root.
+  const author = v.author === undefined ? { kind: "owner" as const } : parseAuthor(v.author);
+  if (!body || !createdAt || !author) return null;
+  return { id: v.id, body, author, createdAt, updatedAt: isoOrUndefined(v.updatedAt) ?? createdAt };
+}
 
-export function parseStoredComment(v: unknown): DesignComment | null {
+function parseReplies(v: unknown): StoredCommentReply[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const seen = new Set<string>();
+  const out: StoredCommentReply[] = [];
+  for (const raw of v) {
+    if (out.length >= COMMENT_LIMITS.maxReplies) break;
+    const reply = parseReply(raw);
+    if (reply && !seen.has(reply.id)) {
+      seen.add(reply.id);
+      out.push(reply);
+    }
+  }
+  return out.length ? out : undefined;
+}
+
+export function parseStoredComment(v: unknown): StoredDesignComment | null {
   if (!isRaw(v) || typeof v.id !== "string" || !COMMENT_ID_RE.test(v.id)) return null;
   const anchor = parseCommentAnchor(v.anchor);
   const createdAt = isoOrUndefined(v.createdAt);
-  if (!anchor || !createdAt || typeof v.body !== "string" || !v.body.trim()) return null;
-  const comment: DesignComment = {
+  const author = parseAuthor(v.author);
+  if (!anchor || !createdAt || author === null || typeof v.body !== "string" || !v.body.trim()) return null;
+  const comment: StoredDesignComment = {
     id: v.id,
     file: anchor.file,
     anchor,
@@ -46,10 +106,15 @@ export function parseStoredComment(v: unknown): DesignComment | null {
   const sentAt = isoOrUndefined(v.sentAt);
   if (resolvedAt) comment.resolvedAt = resolvedAt;
   if (sentAt) comment.sentAt = sentAt;
+  if (author) comment.author = author;
+  const replies = parseReplies(v.replies);
+  if (replies) comment.replies = replies;
+  const pinnedAnchor = parsePinnedAnchor(v.pinnedAnchor);
+  if (pinnedAnchor) comment.pinnedAnchor = pinnedAnchor;
   return comment;
 }
 
-export async function readComments(designDir: string): Promise<DesignComment[]> {
+export async function readComments(designDir: string): Promise<StoredDesignComment[]> {
   const dir = dotDesignDir(designDir);
   const dirStat = await lstatOrNull(dir);
   if (!dirStat) return [];
@@ -69,8 +134,8 @@ export async function readComments(designDir: string): Promise<DesignComment[]>
   }
   const list = isRaw(parsed) && Array.isArray(parsed.comments) ? parsed.comments : [];
   const seen = new Set<string>();
-  const out: DesignComment[] = [];
-  for (const raw of list.slice(0, COMMENT_LIMITS.maxComments)) {
+  const out: StoredDesignComment[] = [];
+  for (const raw of list.slice(0, MAX_STORED_ROOTS)) {
     const comment = parseStoredComment(raw);
     if (comment && !seen.has(comment.id)) {
       seen.add(comment.id);
@@ -80,7 +145,15 @@ export async function readComments(designDir: string): Promise<DesignComment[]>
   return out;
 }
 
-export async function writeComments(designDir: string, comments: readonly DesignComment[]): Promise<void> {
+/**
+ * Refuses a write that would make the file larger than it may be read back: an oversized
+ * file reads as unreadable, which would lose every comment in it.
+ */
+export async function writeComments(designDir: string, comments: readonly StoredDesignComment[]): Promise<void> {
+  const text = `${JSON.stringify({ version: 1, comments }, null, 2)}\n`;
+  if (Buffer.byteLength(text, "utf8") > MAX_FILE_BYTES) {
+    throw new DesignError(409, "ETOOMANY", "This design's comments are at their size limit; delete resolved threads first");
+  }
   const dir = await ensureDotDesign(designDir);
-  await writeFileAtomic(join(dir, COMMENTS_FILE), `${JSON.stringify({ version: 1, comments }, null, 2)}\n`);
+  await writeFileAtomic(join(dir, COMMENTS_FILE), text);
 }

package/src/services/design/design-comment-replies.service.ts

@@ -0,0 +1,126 @@
+import { randomBytes } from "node:crypto";
+import { COMMENT_ID_RE } from "../../shared/design-comment-types.ts";
+import {
+  SHARE_LINK_ID_RE, type StoredCommentReply, type StoredDesignComment,
+} from "../../shared/design-comment-thread-types.ts";
+import { withRecoveredDesign } from "./design-restore-journal.ts";
+import { readComments, writeComments } from "./comments/design-comments-store.ts";
+import {
+  badRequest, commentsChanged, guestOf, guestTextIsTheirs, isRaw, newAuthor, notFound, notYours, parseBody, tooMany,
+} from "./comments/design-comment-input.ts";
+import { isMine, isOwnerEntry, quotaRefusal, visibleToLink, type GuestIdentity } from "./comments/design-comment-views.ts";
+import type { CommentWriteOptions } from "./design-comments.service.ts";
+
+/**
+ * Replies inside a comment thread, and removing every thread one share link brought in.
+ *
+ * Same discipline as the root comments: one design lock per change, an atomic write, and a
+ * `comments_changed` event. A reviewer reaches a thread only when their link started it
+ * (anything else is a 404, indistinguishable from a missing thread) and changes only their
+ * own replies. The owner may reply anywhere and delete any reply, but never edits a
+ * reviewer's words.
+ */
+
+export interface ReplyChange {
+  thread: StoredDesignComment;
+  reply: StoredCommentReply;
+}
+
+const notFoundIfBadId = (...ids: string[]): void => {
+  if (ids.some((id) => !COMMENT_ID_RE.test(id))) throw notFound();
+};
+
+/** Runs `change` on one thread under the lock and writes the result back. */
+async function changeThread<T>(
+  projectPath: string, slug: string, threadId: string, guest: GuestIdentity | null, recheck: (() => void) | undefined,
+  change: (thread: StoredDesignComment, all: StoredDesignComment[]) => { thread: StoredDesignComment; result: T },
+): Promise<T> {
+  const result = await withRecoveredDesign(projectPath, slug, async (designDir) => {
+    recheck?.();
+    const comments = await readComments(designDir);
+    const index = comments.findIndex((c) => c.id === threadId && (!guest || visibleToLink(c, guest.linkId)));
+    if (index < 0) throw notFound();
+    const out = change(comments[index]!, comments);
+    comments[index] = out.thread;
+    await writeComments(designDir, comments);
+    return out.result;
+  });
+  commentsChanged(projectPath, slug);
+  return result;
+}
+
+function findReply(thread: StoredDesignComment, replyId: string): StoredCommentReply {
+  const reply = thread.replies?.find((r) => r.id === replyId);
+  if (!reply) throw notFound();
+  return reply;
+}
+
+/** `{ body }`. Answers the thread as it now stands and the new reply. */
+export async function addReply(
+  projectPath: string, slug: string, threadId: string, input: unknown, opts: CommentWriteOptions = {},
+): Promise<ReplyChange> {
+  notFoundIfBadId(threadId);
+  if (!isRaw(input)) throw badRequest("Expected a JSON object");
+  const body = parseBody(input.body, true)!;
+  const author = newAuthor(opts.actor);
+  return changeThread(projectPath, slug, threadId, guestOf(opts.actor), opts.recheck, (thread, all) => {
+    const refusal = quotaRefusal(all, author, thread);
+    if (refusal) throw tooMany(refusal);
+    const now = new Date().toISOString();
+    const reply: StoredCommentReply = { id: randomBytes(6).toString("hex"), body, author, createdAt: now, updatedAt: now };
+    const next = { ...thread, replies: [...(thread.replies ?? []), reply] };
+    return { thread: next, result: { thread: next, reply } };
+  });
+}
+
+/** `{ body }`, on a reply the actor wrote. */
+export async function updateReply(
+  projectPath: string, slug: string, threadId: string, replyId: string, input: unknown, opts: CommentWriteOptions = {},
+): Promise<ReplyChange> {
+  notFoundIfBadId(threadId, replyId);
+  if (!isRaw(input)) throw badRequest("Expected a JSON object");
+  const body = parseBody(input.body, true)!;
+  const guest = guestOf(opts.actor);
+  return changeThread(projectPath, slug, threadId, guest, opts.recheck, (thread) => {
+    const current = findReply(thread, replyId);
+    if (guest && !isMine(current, guest)) throw notYours();
+    if (!guest && !isOwnerEntry(current)) throw guestTextIsTheirs();
+    const reply: StoredCommentReply = { ...current, body, updatedAt: new Date().toISOString() };
+    const next = { ...thread, replies: thread.replies!.map((r) => (r.id === replyId ? reply : r)) };
+    return { thread: next, result: { thread: next, reply } };
+  });
+}
+
+/** The owner deletes any reply; a reviewer only their own. Answers the thread as it now stands. */
+export async function deleteReply(
+  projectPath: string, slug: string, threadId: string, replyId: string, opts: CommentWriteOptions = {},
+): Promise<StoredDesignComment> {
+  notFoundIfBadId(threadId, replyId);
+  const guest = guestOf(opts.actor);
+  return changeThread(projectPath, slug, threadId, guest, opts.recheck, (thread) => {
+    const current = findReply(thread, replyId);
+    if (guest && !isMine(current, guest)) throw notYours();
+    const next: StoredDesignComment = { ...thread };
+    const rest = thread.replies!.filter((r) => r !== current);
+    if (rest.length) next.replies = rest;
+    else delete next.replies;
+    return { thread: next, result: next };
+  });
+}
+
+/**
+ * Deletes every thread reviewers on `linkId` started, replies included, and answers how many
+ * went. Works for a link whose row is already gone, which is when its threads are most
+ * likely to be cleared. Nothing is written, and no event sent, when there were none.
+ */
+export async function deleteThreadsOfLink(projectPath: string, slug: string, linkId: string): Promise<number> {
+  if (!SHARE_LINK_ID_RE.test(linkId)) throw notFound();
+  const removed = await withRecoveredDesign(projectPath, slug, async (designDir) => {
+    const comments = await readComments(designDir);
+    const rest = comments.filter((c) => !visibleToLink(c, linkId));
+    if (rest.length !== comments.length) await writeComments(designDir, rest);
+    return comments.length - rest.length;
+  });
+  if (removed > 0) commentsChanged(projectPath, slug);
+  return removed;
+}

package/src/services/design/design-comments.service.ts

@@ -1,17 +1,24 @@
 import { randomBytes } from "node:crypto";
 import {
-  COMMENT_ID_RE, COMMENT_LIMITS, parseCommentAnchor, parsePpmId, type CommentAnchor, type DesignComment,
+  COMMENT_ID_RE, parseCommentAnchor, parsePpmId, type CommentAnchor,
 } from "../../shared/design-comment-types.ts";
+import type { StoredDesignComment } from "../../shared/design-comment-thread-types.ts";
 import { DESIGN_GEN_RE } from "../../shared/design-types.ts";
 import { resolveDesignDir } from "./design-paths.ts";
 import { withRecoveredDesign } from "./design-restore-journal.ts";
-import { emitDesignEvent } from "./design-events.ts";
 import { DesignError } from "./design-error.ts";
 import { readComments, writeComments } from "./comments/design-comments-store.ts";
 import { elementContext, validateReanchor, type ElementContext } from "./comments/design-comment-element-context.ts";
+import {
+  badRequest, commentsChanged, guestOf, guestTextIsTheirs, isRaw, newAuthor, notFound, notYours, parseBody, tooMany, type Raw,
+} from "./comments/design-comment-input.ts";
+import {
+  guestMayDeleteRoot, isMine, isOwnerEntry, quotaRefusal, visibleToLink, type CommentActor,
+} from "./comments/design-comment-views.ts";
 
 /**
- * Pinned element comments of one design.
+ * Pinned element comments of one design: the root of each thread (replies are in
+ * `design-comment-replies.service.ts`).
  *
  * Every change runs under the design's lock (so two devices commenting at once cannot lose
  * each other's write), writes `comments.json` atomically, and announces itself as
@@ -21,18 +28,26 @@ import { elementContext, validateReanchor, type ElementContext } from "./comment
  * Input arrives from the browser, and anchors originate in the page, so everything is
  * validated and capped here. The element snippet is never taken from the request; it is
  * built from the source file (see `design-comment-element-context.ts`).
+ *
+ * Every write takes an optional `actor`; absent means the owner. A reviewer (`kind: "guest"`)
+ * acts only inside threads their link started, edits only their own text, and pins to the
+ * snapshot their link shows. Ownership and quotas are checked against the list read under
+ * the lock, never against an earlier read.
  */
 
-type Raw = Record<string, unknown>;
-const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
-const badRequest = (message: string): DesignError => new DesignError(400, "EBADCOMMENT", message);
-const notFound = (): DesignError => new DesignError(404, "ENOENT", "Comment not found");
+export interface CommentWriteOptions {
+  actor?: CommentActor;
+  /**
+   * Runs once the design lock is held, before anything is read or written; throwing refuses
+   * the change. A reviewer's write can queue behind a long snapshot, and this is where it
+   * finds out that its link was revoked meanwhile.
+   */
+  recheck?: () => void;
+}
 
-function parseBody(v: unknown, required: boolean): string | undefined {
-  if (v === undefined && !required) return undefined;
-  if (typeof v !== "string" || !v.trim()) throw badRequest("A comment needs some text");
-  if (v.length > COMMENT_LIMITS.body) throw badRequest(`A comment is at most ${COMMENT_LIMITS.body} characters`);
-  return v.trim();
+export interface AddCommentOptions extends CommentWriteOptions {
+  /** The snapshot a reviewer's page showed; required for a reviewer, refused for the owner. */
+  source?: { snapshotId: string };
 }
 
 function parseAnchorInput(input: Raw): CommentAnchor {
@@ -42,11 +57,7 @@ function parseAnchorInput(input: Raw): CommentAnchor {
   return anchor;
 }
 
-function changed(projectPath: string, slug: string): void {
-  emitDesignEvent("comments_changed", { projectPath, slug });
-}
-
-export async function listComments(projectPath: string, slug: string): Promise<DesignComment[]> {
+export async function listComments(projectPath: string, slug: string): Promise<StoredDesignComment[]> {
   return readComments(await resolveDesignDir(projectPath, slug));
 }
 
@@ -58,18 +69,25 @@ export async function previewElementContext(projectPath: string, slug: string, i
   return elementContext(projectPath, slug, anchor);
 }
 
-export async function addComment(projectPath: string, slug: string, input: unknown): Promise<DesignComment> {
+export async function addComment(
+  projectPath: string, slug: string, input: unknown, opts: AddCommentOptions = {},
+): Promise<StoredDesignComment> {
   if (!isRaw(input)) throw badRequest("Expected a JSON object");
   const anchor = parseAnchorInput(input);
   const body = parseBody(input.body, true)!;
+  const author = newAuthor(opts.actor);
+  const guest = author.kind === "guest";
+  if (guest && !opts.source) throw badRequest("A reviewer's comment needs the snapshot it was made on");
+  if (!guest && opts.source) throw badRequest("Only a reviewer's comment is pinned to a snapshot");
+  const snapshotId = opts.source?.snapshotId;
   const comment = await withRecoveredDesign(projectPath, slug, async (designDir) => {
+    opts.recheck?.();
     const comments = await readComments(designDir);
-    if (comments.length >= COMMENT_LIMITS.maxComments) {
-      throw new DesignError(409, "ETOOMANY", `A design holds at most ${COMMENT_LIMITS.maxComments} comments; delete resolved ones first`);
-    }
-    const context = await elementContext(projectPath, slug, anchor);
+    const refusal = quotaRefusal(comments, author);
+    if (refusal) throw tooMany(refusal);
+    const context = await elementContext(projectPath, slug, anchor, { snapshotId });
     const now = new Date().toISOString();
-    const created: DesignComment = {
+    const created: StoredDesignComment = {
       id: randomBytes(6).toString("hex"),
       file: anchor.file,
       anchor: { ...anchor, quote: context.quote },
@@ -78,21 +96,32 @@ export async function addComment(projectPath: string, slug: string, input: unkno
       createdAt: now,
       updatedAt: now,
     };
+    if (guest && snapshotId !== undefined) {
+      created.author = author;
+      // Only ids the server confirmed against the snapshot are kept for the reviewer's page.
+      const confirmed = context.snippet !== null;
+      created.pinnedAnchor = { snapshotId, ppmId: confirmed ? anchor.ppmId : null, gen: confirmed ? anchor.gen : null };
+    }
     await writeComments(designDir, [...comments, created]);
     return created;
   });
-  changed(projectPath, slug);
+  commentsChanged(projectPath, slug);
   return comment;
 }
 
 /**
  * `body`, `resolved` (true/false), `sent` (true: stamp `sentAt`) and `anchor` (`{ppmId,
  * gen}` the canvas found the element under, re-validated against the source; 409 if it
- * does not hold up). At least one must be given.
+ * does not hold up). At least one must be given. A reviewer may send `body` only, on their
+ * own root; the owner may send anything but `body` on a reviewer's root. A re-anchor moves
+ * `anchor` only: a reviewer's `pinnedAnchor` stays where they pinned it.
  */
-export async function updateComment(projectPath: string, slug: string, id: string, patch: unknown): Promise<DesignComment> {
+export async function updateComment(
+  projectPath: string, slug: string, id: string, patch: unknown, opts: CommentWriteOptions = {},
+): Promise<StoredDesignComment> {
   if (!COMMENT_ID_RE.test(id)) throw notFound();
   if (!isRaw(patch)) throw badRequest("Expected a JSON object");
+  const guest = guestOf(opts.actor);
   const body = parseBody(patch.body, false);
   const resolved = patch.resolved === undefined ? undefined : patch.resolved === true ? true : patch.resolved === false ? false : null;
   if (resolved === null) throw badRequest("resolved must be true or false");
@@ -105,13 +134,20 @@ export async function updateComment(projectPath: string, slug: string, id: strin
     move = { ppmId, gen: a.gen };
   }
   if (body === undefined && resolved === undefined && patch.sent === undefined && !move) throw badRequest("Nothing to update");
+  if (guest && (resolved !== undefined || patch.sent !== undefined || move)) {
+    throw new DesignError(403, "ENOTALLOWED", "A reviewer can only edit the text of their comment");
+  }
 
   const updated = await withRecoveredDesign(projectPath, slug, async (designDir) => {
+    opts.recheck?.();
     const comments = await readComments(designDir);
-    const index = comments.findIndex((c) => c.id === id);
+    const index = comments.findIndex((c) => c.id === id && (!guest || visibleToLink(c, guest.linkId)));
     if (index < 0) throw notFound();
+    const current = comments[index]!;
+    if (guest && !isMine(current, guest)) throw notYours();
+    if (!guest && body !== undefined && !isOwnerEntry(current)) throw guestTextIsTheirs();
     const now = new Date().toISOString();
-    const next: DesignComment = { ...comments[index]!, updatedAt: now };
+    const next: StoredDesignComment = { ...current, updatedAt: now };
     if (body !== undefined) next.body = body;
     if (resolved === true && !next.resolvedAt) next.resolvedAt = now;
     if (resolved === false) delete next.resolvedAt;
@@ -124,17 +160,24 @@ export async function updateComment(projectPath: string, slug: string, id: strin
     await writeComments(designDir, comments);
     return next;
   });
-  changed(projectPath, slug);
+  commentsChanged(projectPath, slug);
   return updated;
 }
 
-export async function deleteComment(projectPath: string, slug: string, id: string): Promise<void> {
+/** The owner deletes any thread; a reviewer only their own, and only while it has no replies. */
+export async function deleteComment(projectPath: string, slug: string, id: string, opts: CommentWriteOptions = {}): Promise<void> {
   if (!COMMENT_ID_RE.test(id)) throw notFound();
+  const guest = guestOf(opts.actor);
   await withRecoveredDesign(projectPath, slug, async (designDir) => {
+    opts.recheck?.();
     const comments = await readComments(designDir);
-    const rest = comments.filter((c) => c.id !== id);
-    if (rest.length === comments.length) throw notFound();
-    await writeComments(designDir, rest);
+    const target = comments.find((c) => c.id === id && (!guest || visibleToLink(c, guest.linkId)));
+    if (!target) throw notFound();
+    if (guest && !isMine(target, guest)) throw notYours();
+    if (guest && !guestMayDeleteRoot(target, guest)) {
+      throw new DesignError(409, "EHASREPLIES", "This comment has replies, so it can no longer be deleted; edit it instead");
+    }
+    await writeComments(designDir, comments.filter((c) => c !== target));
   });
-  changed(projectPath, slug);
+  commentsChanged(projectPath, slug);
 }

package/src/services/design/design-restore.service.ts

@@ -9,6 +9,8 @@ import {
 } from "./design-restore-journal.ts";
 import { readSnapshotInfo, snapshotFilesDir } from "./design-snapshot-history.ts";
 import { readDesignTree, takeSnapshotLocked, writeTreeFiles } from "./design-snapshots.service.ts";
+import { pinnedSnapshotIds } from "./share/design-share-links-store.ts";
+import { projectKey } from "../project-name-for-path.ts";
 
 export { recoverRestoreJournal } from "./design-restore-journal.ts";
 
@@ -26,7 +28,8 @@ export interface RestoreResult {
  * Replace a design's working files with a snapshot's, as a journaled swap.
  *
  *  1. Snapshot the current state (`pre-restore`), protecting the target from that
- *     snapshot's pruning so restoring the oldest entry cannot evict the entry itself.
+ *     snapshot's pruning so restoring the oldest entry cannot evict the entry itself (and
+ *     protecting every snapshot a share link pins, as all pruning does).
  *  2. Stage a full copy of the target in `.design/tmp-<id>/`, journal `staged`.
  *  3. Journal `swapping`, then swap (see `completeSwap`).
  *  4. Remove the journal and the empty staging dir.
@@ -40,7 +43,8 @@ export async function restoreSnapshot(projectPath: string, slug: string, id: str
   const result = await withRecoveredDesign(projectPath, slug, async (designDir) => {
     if (!(await readSnapshotInfo(designDir, id))) throw new DesignError(404, "ENOENT", `Snapshot not found: ${id}`);
 
-    const before = await takeSnapshotLocked(designDir, "pre-restore", { restoreOf: id }, new Set([id]));
+    const keep = new Set([id, ...pinnedSnapshotIds(projectKey(projectPath), slug)]);
+    const before = await takeSnapshotLocked(designDir, "pre-restore", { restoreOf: id }, keep);
     if ("skipped" in before && before.skipped !== "unchanged") {
       throw new DesignError(409, "ETOOLARGE", "The current design is too large to back up, so restoring would lose it");
     }

package/src/services/design/design-snapshots.service.ts

@@ -13,6 +13,8 @@ import {
 import { withRecoveredDesign } from "./design-restore-journal.ts";
 import { emitDesignEvent } from "./design-events.ts";
 import { DesignError, isDesignError } from "./design-error.ts";
+import { pinnedSnapshotIds } from "./share/design-share-links-store.ts";
+import { projectKey } from "../project-name-for-path.ts";
 
 /**
  * Snapshots are plain file copies of a design folder (minus `.design/`) kept in
@@ -131,7 +133,7 @@ export async function takeSnapshotLocked(
 
 /**
  * Snapshot a design (`turn` after an AI turn, `before-edit` ahead of a canvas write-back,
- * `manual` on request). Announces the change with one `history_changed` event when a
+ * `manual` on request). Snapshots a share link pins are never pruned. Announces the change with one `history_changed` event when a
  * snapshot was actually taken. A design that does not exist is reported as skipped, since
  * a turn can end in a session whose design was deleted.
  */
@@ -146,7 +148,11 @@ export async function snapshotDesign(
   }
   let result: SnapshotResult;
   try {
-    result = await withRecoveredDesign(projectPath, slug, (dir) => takeSnapshotLocked(dir, reason, meta));
+    // Read under the lock, so a link pinning an old snapshot cannot be inserted between the
+    // read and the prune that would otherwise take its snapshot away.
+    result = await withRecoveredDesign(projectPath, slug, (dir) => (
+      takeSnapshotLocked(dir, reason, meta, pinnedSnapshotIds(projectKey(projectPath), slug))
+    ));
   } catch (e) {
     if (isDesignError(e) && e.status === 404) return { skipped: "missing" };
     throw e;

package/src/services/design/design-store.service.ts

@@ -15,6 +15,8 @@ import { DesignError } from "./design-error.ts";
 import { designLockKey, withDesignLock } from "./design-lock.ts";
 import { withRecoveredDesign } from "./design-restore-journal.ts";
 import { resolveDesignVariants } from "./design-variants-resolve.ts";
+import { deleteShareLinksForDesign } from "./share/design-share-links-store.ts";
+import { projectKey } from "../project-name-for-path.ts";
 
 /** Designs listed per project, newest first. */
 export const MAX_LISTED_DESIGNS = 200;
@@ -161,12 +163,16 @@ export async function renameDesign(projectPath: string, slug: string, rawTitle:
   });
 }
 
-/** Delete a design folder, `.design/` and its history included. */
+/**
+ * Delete a design folder, `.design/` and its history included, and then its share links:
+ * left behind, they would be inherited by a later design that reuses the slug.
+ */
 export async function deleteDesign(projectPath: string, slug: string): Promise<void> {
   await withDesignLock(designLockKey(projectPath, slug), async () => {
     const dir = await resolveDesignDir(projectPath, slug);
     // rm never follows a symlink inside the tree; the folder itself was checked not to be one.
     await rm(dir, { recursive: true, force: false });
+    deleteShareLinksForDesign(projectKey(projectPath), slug);
   });
 }
 

package/src/services/design/design-write-rate-limit.ts

@@ -1,5 +1,6 @@
 import { DesignError } from "./design-error.ts";
 import { designLockKey } from "./design-lock.ts";
+import { createSlidingWindowLimiter } from "../sliding-window-limiter.ts";
 
 /**
  * How often the canvas may write into one design: at most one write per 500 ms and 30 per
@@ -16,36 +17,29 @@ import { designLockKey } from "./design-lock.ts";
 export const WRITE_MIN_INTERVAL_MS = 500;
 export const WRITES_PER_MINUTE = 30;
 const WINDOW_MS = 60_000;
+/** Designs tracked at once; far more than are edited in any one minute. */
+const MAX_TRACKED_DESIGNS = 2048;
 
 /** Test seam: the clock the limiter reads. */
 export const designWriteClock = { now: (): number => Date.now() };
 
-const recent = new Map<string, number[]>();
-
-function sweep(now: number): void {
-  for (const [key, times] of recent) {
-    if (times.length === 0 || now - times[times.length - 1]! >= WINDOW_MS) recent.delete(key);
-  }
-}
+const limiter = createSlidingWindowLimiter(
+  { windowMs: WINDOW_MS, max: WRITES_PER_MINUTE, minIntervalMs: WRITE_MIN_INTERVAL_MS },
+  { maxKeys: MAX_TRACKED_DESIGNS },
+);
 
 /** Counts one write, or throws a 429 without counting it. */
 export function takeDesignWrite(projectPath: string, slug: string): void {
-  const now = designWriteClock.now();
-  sweep(now);
-  const key = designLockKey(projectPath, slug);
-  const times = (recent.get(key) ?? []).filter((t) => now - t < WINDOW_MS);
-  const last = times[times.length - 1];
-  if (last !== undefined && now - last < WRITE_MIN_INTERVAL_MS) {
+  const refusal = limiter.take(designLockKey(projectPath, slug), designWriteClock.now());
+  if (refusal?.reason === "interval") {
     throw new DesignError(429, "rate-limited", "Too many canvas edits at once; wait a moment and try again");
   }
-  if (times.length >= WRITES_PER_MINUTE) {
+  if (refusal) {
     throw new DesignError(429, "rate-limited", `At most ${WRITES_PER_MINUTE} canvas edits a minute; wait a moment and try again`);
   }
-  times.push(now);
-  recent.set(key, times);
 }
 
 /** Forget every count; for tests. */
 export function resetDesignWriteLimits(): void {
-  recent.clear();
+  limiter.reset();
 }