@plannotator/ui 0.33.0 → 0.35.0

package/utils/undoHistory.ts

@@ -0,0 +1,167 @@
+/** Direction in which a recorded history action is replayed. */
+export type HistoryDirection = 'undo' | 'redo';
+
+/** Immutable state for one bounded undo/redo context. */
+export interface UndoHistoryState<TAction> {
+  readonly past: readonly TAction[];
+  readonly future: readonly TAction[];
+}
+
+/** Result of taking one action from a history stack. */
+export interface UndoHistoryStep<TAction> {
+  readonly state: UndoHistoryState<TAction>;
+  readonly action: TAction | null;
+}
+
+/** Create an empty undo/redo state. */
+export function createUndoHistoryState<TAction>(): UndoHistoryState<TAction> {
+  return { past: [], future: [] };
+}
+
+/** Record an already-applied action and invalidate the redo branch. */
+export function recordUndoAction<TAction>(
+  state: UndoHistoryState<TAction>,
+  action: TAction,
+  capacity: number,
+): UndoHistoryState<TAction> {
+  const boundedCapacity = Math.max(1, Math.floor(capacity));
+  return {
+    past: [...state.past, action].slice(-boundedCapacity),
+    future: [],
+  };
+}
+
+/** Take the newest undo action, if one exists. */
+export function takeUndoAction<TAction>(state: UndoHistoryState<TAction>): UndoHistoryStep<TAction> {
+  const action = state.past.at(-1) ?? null;
+  if (action === null) return { state, action: null };
+  return {
+    action,
+    state: {
+      past: state.past.slice(0, -1),
+      future: [...state.future, action],
+    },
+  };
+}
+
+/** Take the newest redo action, if one exists. */
+export function takeRedoAction<TAction>(
+  state: UndoHistoryState<TAction>,
+  capacity: number,
+): UndoHistoryStep<TAction> {
+  const action = state.future.at(-1) ?? null;
+  if (action === null) return { state, action: null };
+  const boundedCapacity = Math.max(1, Math.floor(capacity));
+  return {
+    action,
+    state: {
+      past: [...state.past, action].slice(-boundedCapacity),
+      future: state.future.slice(0, -1),
+    },
+  };
+}
+
+/** One reversible mutation to an ID-addressed collection. */
+export type CollectionMutation<TItem> =
+  | { readonly kind: 'add'; readonly item: TItem; readonly index: number }
+  | { readonly kind: 'edit'; readonly before: TItem; readonly after: TItem }
+  | { readonly kind: 'delete'; readonly item: TItem; readonly index: number };
+
+function insertAt<TItem>(items: readonly TItem[], item: TItem, index: number): TItem[] {
+  const insertionIndex = Math.max(0, Math.min(index, items.length));
+  return [...items.slice(0, insertionIndex), item, ...items.slice(insertionIndex)];
+}
+
+/** Apply or invert one collection mutation while preserving the recorded item index. */
+export function applyCollectionMutation<TItem>(
+  items: readonly TItem[],
+  mutation: CollectionMutation<TItem>,
+  direction: HistoryDirection,
+  getId: (item: TItem) => string,
+): TItem[] {
+  switch (mutation.kind) {
+    case 'add':
+      return direction === 'undo'
+        ? items.filter((item) => getId(item) !== getId(mutation.item))
+        : insertAt(items, mutation.item, mutation.index);
+    case 'delete':
+      return direction === 'undo'
+        ? insertAt(items, mutation.item, mutation.index)
+        : items.filter((item) => getId(item) !== getId(mutation.item));
+    case 'edit': {
+      const replacement = direction === 'undo' ? mutation.before : mutation.after;
+      return items.map((item) => getId(item) === getId(replacement) ? replacement : item);
+    }
+  }
+}
+
+/** Apply a compound collection action in the order required for exact inversion. */
+export function applyCollectionMutations<TItem>(
+  items: readonly TItem[],
+  mutations: readonly CollectionMutation<TItem>[],
+  direction: HistoryDirection,
+  getId: (item: TItem) => string,
+): TItem[] {
+  const ordered = direction === 'undo' ? [...mutations].reverse() : mutations;
+  return ordered.reduce<TItem[]>(
+    (current, mutation) => applyCollectionMutation(current, mutation, direction, getId),
+    [...items],
+  );
+}
+
+const NATIVE_HISTORY_SELECTOR = [
+  'input',
+  'textarea',
+  '[contenteditable]:not([contenteditable="false"])',
+  '.cm-editor',
+  '[role="textbox"]',
+].join(',');
+
+const ACTIVE_HISTORY_OVERLAY_SELECTOR = [
+  '[role="dialog"]',
+  '[data-popover-layer]',
+  '[data-comment-popover="true"]',
+  '[data-history-owner]',
+  '.cm-editor.cm-focused',
+].join(',');
+
+/**
+ * Return whether the event belongs to native text history or another active
+ * tool. `composedPath()` is required for editors mounted inside shadow DOM.
+ */
+export function isNativeHistoryOwner(event: KeyboardEvent): boolean {
+  const first = event.composedPath()[0];
+  if (!(first instanceof Element)) return false;
+  return first.matches(NATIVE_HISTORY_SELECTOR)
+    || first.closest(NATIVE_HISTORY_SELECTOR) !== null;
+}
+
+/** Return whether a dialog, composer, or source editor currently owns history. */
+export function hasActiveHistoryOverlay(root: ParentNode): boolean {
+  return root.querySelector(ACTIVE_HISTORY_OVERLAY_SELECTOR) !== null;
+}
+
+/** External or agent-authored annotations never enter human undo history. */
+export function isHumanHistoryMutation(item: { readonly source?: string }): boolean {
+  return !item.source;
+}
+
+/** Minimal imperative highlight surface used by annotation-history replay. */
+export interface HistoryHighlightTarget<TItem extends { readonly id: string }> {
+  removeHighlight: (id: string) => void;
+  applySharedAnnotations: (items: TItem[]) => void;
+}
+
+/**
+ * Synchronize one replayed annotation without tombstoning retained highlights.
+ * Removal is reserved for actions whose result no longer contains the item.
+ */
+export function syncHistoryHighlight<TItem extends { readonly id: string }>(
+  target: HistoryHighlightTarget<TItem> | null,
+  item: TItem,
+  visible: boolean,
+): void {
+  if (!target) return;
+  if (visible) target.applySharedAnnotations([item]);
+  else target.removeHighlight(item.id);
+}

package/webmcp/changes.ts

@@ -57,6 +57,15 @@ export function hashAnnotation(annotation: TrackedAnnotation): string {
 
 const CURSOR_PREFIX = 'w:';
 
+/**
+ * Tombstones kept per tracker. A removal past this many is forgotten oldest
+ * first (FIFO by seq), together with the agent-ownership records of the
+ * forgotten id, so a create/delete loop cannot grow the tracker for the
+ * life of the tab. A tombstone older than 2,000 later removals is one no
+ * `since` in practice still asks about.
+ */
+export const MAX_TOMBSTONES = 2000;
+
 export class AnnotationChangeTracker {
   private readonly entries = new Map<string, ChangeEntry>();
   private readonly tombstones = new Map<string, Tombstone>();
@@ -151,12 +160,27 @@ export class AnnotationChangeTracker {
       this.tombstones.set(id, tombstone);
       delta.removed.push(tombstone);
     }
+    this.pruneTombstones();
     // A re-added id is a fresh record: forget any agent-removal claim on it.
     for (const id of seen) this.agentRemoved.delete(id);
     if (touched) this.lastActivity = this.now();
     return delta;
   }
 
+  /** Bounded eviction (MAX_TOMBSTONES): the oldest tombstones go, and with
+   *  them the ownership and agent-removal records that only mattered while
+   *  the id could still be asked about. Live entries keep theirs. */
+  private pruneTombstones(): void {
+    while (this.tombstones.size > MAX_TOMBSTONES) {
+      const oldest = this.tombstones.keys().next().value;
+      if (oldest === undefined) break;
+      this.tombstones.delete(oldest);
+      this.ownHashes.delete(oldest);
+      this.ownSeqs.delete(oldest);
+      this.agentRemoved.delete(oldest);
+    }
+  }
+
   seqOf(id: string): number | undefined {
     return this.entries.get(id)?.seq;
   }

package/webmcp/nudges.ts

@@ -50,11 +50,23 @@ export interface NudgeSnapshot {
 }
 
 export const MAX_OTHER_DOCUMENT_NUDGES = 10;
+/** Ids listed on one nudge; a burst past this names the first ones and says how many more. */
+export const MAX_NUDGE_IDS = 100;
 
 function plural(count: number, noun: string): string {
   return `${count} ${noun}${count === 1 ? '' : 's'}`;
 }
 
+/** The first MAX_NUDGE_IDS ids plus a suffix for the message when some are left out. */
+function capIds(ids: string[]): { ids: string[]; suffix: string } {
+  if (ids.length <= MAX_NUDGE_IDS) return { ids, suffix: '' };
+  const more = ids.length - MAX_NUDGE_IDS;
+  return {
+    ids: ids.slice(0, MAX_NUDGE_IDS),
+    suffix: ` The first ${MAX_NUDGE_IDS} ids are listed; ${more} more ${more === 1 ? 'is' : 'are'} not (read the document for the rest).`,
+  };
+}
+
 export function buildNudges(
   snapshot: NudgeSnapshot,
   tracker: AnnotationChangeTracker,
@@ -71,29 +83,32 @@ export function buildNudges(
   });
   const plain = fresh.filter((id) => !replies.includes(id));
   if (plain.length > 0) {
+    const capped = capIds(plain);
     nudges.push({
       code: 'annotations_new',
-      message: `The human added or edited ${plural(plain.length, 'comment')} since your last read.`,
-      ids: plain,
+      message: `The human added or edited ${plural(plain.length, 'comment')} since your last read.${capped.suffix}`,
+      ids: capped.ids,
     });
   }
   if (replies.length > 0) {
+    const capped = capIds(replies);
     nudges.push({
       code: 'replies_new',
-      message: `The human replied to your comments (${replies.length} new ${replies.length === 1 ? 'reply' : 'replies'}).`,
-      ids: replies,
+      message: `The human replied to your comments (${replies.length} new ${replies.length === 1 ? 'reply' : 'replies'}).${capped.suffix}`,
+      ids: capped.ids,
     });
   }
 
   const removed = tracker.removedSince(since);
   if (removed.length > 0) {
     const own = removed.filter((t) => t.agent);
+    const capped = capIds(removed.map((t) => t.id));
     nudges.push({
       code: 'annotations_removed',
-      message: own.length > 0
+      message: (own.length > 0
         ? `The human removed ${own.length} of your comments; treat that as resolved and do not re-add them.`
-        : `${plural(removed.length, 'comment')} you had seen ${removed.length === 1 ? 'was' : 'were'} removed.`,
-      ids: removed.map((t) => t.id),
+        : `${plural(removed.length, 'comment')} you had seen ${removed.length === 1 ? 'was' : 'were'} removed.`) + capped.suffix,
+      ids: capped.ids,
     });
   }