sonorance 0.1.0-beta.4.1

package/src/ui/at-mention.mjs

@@ -0,0 +1,67 @@
+// "@" mention for the Tiptap surface — type "@" to summon the agent and leave a
+// comment for it, from the keyboard, without reaching for the mouse.
+//
+// In Sonorance a comment IS a message to the agent (the composer says "leave a
+// comment for the agent to address"), so "@agent" is the natural, self-marketing
+// trigger: it reads as addressing the AI. Built on Tiptap's Suggestion utility,
+// mirroring slash.mjs (same self-rendered popup, no tippy).
+//
+// The mention is a pure TRIGGER: picking "@agent" deletes the typed "@…" (the
+// document is never mutated with mention text) and hands off to the app, which
+// opens the comment composer anchored to the block the caret is in. The mention
+// list is built to grow — add "@person" here when collaboration lands.
+import { Extension } from '@tiptap/core';
+import { Suggestion } from '@tiptap/suggestion';
+import { PluginKey } from '@tiptap/pm/state';
+import { makeRenderer } from './slash.mjs';
+
+// The mention roster. `run()` clears the typed trigger, then the app callback
+// opens the composer on the current block (see onAtComment in app.js).
+function targets(onComment) {
+  return [
+    { title: '@agent — ask the agent', keys: 'agent ai ask comment', run: ({ editor, range }) => {
+      editor.chain().focus().deleteRange(range).run();
+      // Defer so ProseMirror's DOM selection settles on the (now shortened) block
+      // before the app reads it to anchor the comment.
+      setTimeout(() => onComment && onComment(), 0);
+    } },
+  ];
+}
+
+function filter(list, query) {
+  const q = (query || '').toLowerCase().trim();
+  if (!q) return list;
+  return list.filter(c => (c.title + ' ' + c.keys).toLowerCase().includes(q));
+}
+
+// Factory: the "@" extension needs the app's composer callback, so it's built
+// per editor (like the comments plugin) rather than shared statically.
+export function atMention({ onComment } = {}) {
+  const list = targets(onComment);
+  return Extension.create({
+    name: 'atMention',
+    addProseMirrorPlugins() {
+      return [
+        Suggestion({
+          editor: this.editor,
+          pluginKey: new PluginKey('atSuggestion'),
+          char: '@',
+          startOfLine: false,
+          allowSpaces: false,
+          // Fire only when "@" opens a word (start of block or after whitespace),
+          // never mid-token — so an email address (a@b) never pops the menu, and
+          // never inside a code block.
+          allow: ({ state, range }) => {
+            const $from = state.doc.resolve(range.from);
+            if ($from.parent.type.spec.code) return false;
+            const before = $from.parent.textBetween(0, $from.parentOffset, undefined, ' ');
+            return /(^|\s)@?$/.test(before);
+          },
+          items: ({ query }) => filter(list, query),
+          command: ({ editor, range, props }) => props.run({ editor, range }),
+          render: makeRenderer,
+        }),
+      ];
+    },
+  });
+}

package/src/ui/comments-plugin.mjs

@@ -0,0 +1,107 @@
+// Comment highlighting for the Tiptap surface, as a ProseMirror plugin.
+//
+// The hand-rolled live-preview highlighted comment anchors by injecting <span
+// class="cmark"> into the DOM (surroundContents). That fights ProseMirror,
+// which owns and re-renders its DOM. The correct mechanism is a decoration
+// set: we locate each comment's anchor (its `quote`, scoped to the section
+// under its `heading`) in the current doc and render an inline decoration.
+// Decorations survive edits (they re-derive from doc state) and never mutate
+// the document.
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+
+export const commentsKey = new PluginKey('sonorance-comments');
+
+// Flatten the doc into a plain string with a parallel map from each character
+// index to its ProseMirror position, plus the char index at which each heading
+// (by trimmed text) starts — so a quote can be scoped to its section.
+function flatten(doc) {
+  let text = '';
+  const posAt = [];              // posAt[i] = PM position of character i
+  const headingStart = [];       // { text, at } in order
+  let curHeadingText = null, curHeadingAt = -1;
+  doc.descendants((node, pos) => {
+    if (node.type.name === 'heading') { curHeadingText = ''; curHeadingAt = text.length; return; }
+    if (node.isText) {
+      const t = node.text || '';
+      for (let i = 0; i < t.length; i++) { posAt.push(pos + i); }
+      text += t;
+      if (curHeadingText !== null) curHeadingText += t;
+    } else if (node.isBlock && text.length && text[text.length - 1] !== '\n') {
+      // block boundary — keep quotes from spanning across blocks
+      text += '\n'; posAt.push(pos);
+      if (curHeadingText !== null && curHeadingText.trim()) {
+        headingStart.push({ text: curHeadingText.trim(), at: curHeadingAt });
+        curHeadingText = null;
+      }
+    }
+  });
+  if (curHeadingText !== null && curHeadingText.trim()) headingStart.push({ text: curHeadingText.trim(), at: curHeadingAt });
+  return { text, posAt, headingStart };
+}
+
+// Locate a comment anchor -> { from, to } PM positions, or null. Prefers a
+// quote match scoped to its heading's section; falls back to a whole-doc quote
+// search, then to the heading itself.
+export function findRange(doc, anchor) {
+  if (!anchor) return null;
+  const { text, posAt, headingStart } = flatten(doc);
+  const quote = (anchor.quote || '').trim();
+  const heading = (anchor.heading || '').trim();
+
+  let scopeStart = 0;
+  if (heading) {
+    const h = headingStart.find(x => x.text === heading);
+    if (h) scopeStart = h.at;
+  }
+  if (quote && quote.length >= 2) {
+    let idx = text.indexOf(quote, scopeStart);
+    if (idx < 0) idx = text.indexOf(quote);           // fall back to a global search
+    if (idx >= 0 && posAt[idx] != null) {
+      const from = posAt[idx];
+      const to = (posAt[idx + quote.length - 1] ?? from) + 1;
+      return { from, to };
+    }
+  }
+  // No usable quote: highlight the heading line if we found it.
+  if (heading) {
+    const h = headingStart.find(x => x.text === heading);
+    if (h && posAt[h.at] != null) return { from: posAt[h.at], to: (posAt[h.at + heading.length - 1] ?? posAt[h.at]) + 1 };
+  }
+  return null;
+}
+
+function buildDecorations(doc, comments) {
+  const decos = [];
+  for (const c of comments || []) {
+    const r = findRange(doc, c.anchor);
+    if (!r || r.to <= r.from) continue;
+    decos.push(Decoration.inline(r.from, r.to, { class: 'cmark', 'data-comment': c.id }));
+  }
+  return DecorationSet.create(doc, decos);
+}
+
+// A Tiptap-compatible ProseMirror plugin. `onClick(id)` fires when a highlight
+// is clicked (to focus the matching comment card).
+export function commentsPlugin({ onClick } = {}) {
+  return new Plugin({
+    key: commentsKey,
+    state: {
+      init: () => ({ comments: [], decos: DecorationSet.empty }),
+      apply(tr, value) {
+        const meta = tr.getMeta(commentsKey);
+        if (meta && meta.comments) return { comments: meta.comments, decos: buildDecorations(tr.doc, meta.comments) };
+        if (tr.docChanged) return { comments: value.comments, decos: buildDecorations(tr.doc, value.comments) };
+        return value;
+      },
+    },
+    props: {
+      decorations(state) { return commentsKey.getState(state)?.decos; },
+      handleClick(view, pos, event) {
+        const el = event.target.closest?.('.cmark');
+        if (el && el.dataset.comment) { onClick?.(el.dataset.comment); return true; }
+        return false;
+      },
+    },
+  });
+}

package/src/ui/diff-plugin.mjs

@@ -0,0 +1,73 @@
+// Change decorations for the Tiptap surface, as a ProseMirror plugin.
+//
+// The hand-rolled live-preview decorated diffs by mutating the rendered DOM
+// (inserting `.diffdel` islands, toggling `.diff-add`/`.diff-mod` on `.blk`
+// elements). That fights ProseMirror, which owns its DOM. Here the diff is a
+// decoration set instead: added/modified top-level blocks get a NODE
+// decoration (a class), and removed blocks are shown as WIDGET decorations
+// (read-only red islands rendered from pre-computed HTML) before the block
+// that follows them.
+//
+// The diff itself is computed in the app (over serialized Markdown, reusing the
+// same LCS the live-preview path uses) and handed in as instructions keyed by
+// top-level block index — this module only turns those into decorations, and
+// bails safely (renders nothing) if the block count no longer lines up with the
+// document (e.g. mid-edit), exactly like the live-preview `diffWorkUnits` guard.
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+
+export const diffKey = new PluginKey('sonorance-diff');
+
+// Absolute positions of each top-level block node, in document order.
+function topLevelPositions(doc) {
+  const out = [];
+  doc.forEach((node, offset) => { out.push({ pos: offset, size: node.nodeSize }); });
+  return out;
+}
+
+function buildDecorations(doc, diff) {
+  if (!diff) return DecorationSet.empty;
+  const { nodeClasses = [], deletions = [], count } = diff;
+  const blocks = topLevelPositions(doc);
+  // Bail (show nothing) if the document no longer matches the diff we were
+  // handed — a transient mid-edit state; the app re-derives on the next tick.
+  if (typeof count === 'number' && blocks.length !== count) return DecorationSet.empty;
+
+  const decos = [];
+  for (let i = 0; i < blocks.length; i++) {
+    const cls = nodeClasses[i];
+    if (cls) decos.push(Decoration.node(blocks[i].pos, blocks[i].pos + blocks[i].size, { class: cls }));
+  }
+  for (const d of deletions || []) {
+    const at = d.at;
+    const pos = at >= 0 && at < blocks.length ? blocks[at].pos
+      : (blocks.length ? blocks[blocks.length - 1].pos + blocks[blocks.length - 1].size : 0);
+    const side = at >= 0 && at < blocks.length ? -1 : 1;
+    decos.push(Decoration.widget(pos, () => {
+      const wrap = document.createElement('div');
+      wrap.className = 'diffdel-wrap';
+      wrap.setAttribute('contenteditable', 'false');
+      wrap.innerHTML = d.html || '';
+      return wrap;
+    }, { side, ignoreSelection: true, key: 'del-' + at + '-' + (d.key || '') }));
+  }
+  return DecorationSet.create(doc, decos);
+}
+
+export function diffPlugin() {
+  return new Plugin({
+    key: diffKey,
+    state: {
+      init: () => ({ diff: null, decos: DecorationSet.empty }),
+      apply(tr, value) {
+        const meta = tr.getMeta(diffKey);
+        if (meta !== undefined) return { diff: meta, decos: buildDecorations(tr.doc, meta) };
+        if (tr.docChanged) return { diff: value.diff, decos: buildDecorations(tr.doc, value.diff) };
+        return value;
+      },
+    },
+    props: {
+      decorations(state) { return diffKey.getState(state)?.decos; },
+    },
+  });
+}

package/src/ui/editor.mjs

@@ -0,0 +1,210 @@
+// The Sonorance editor core — a thin controller over a Tiptap/ProseMirror
+// editor. The app talks to this module, never to Tiptap directly, so the rest
+// of the UI (open/save, ToC, comments, diff) has one stable seam.
+//
+// Markdown is the on-disk format; the editor's live truth is a ProseMirror
+// doc. Leading YAML frontmatter is split out on load (kept verbatim, hidden)
+// and re-attached on serialize. See md.mjs for the bridge.
+import { Editor } from '@tiptap/core';
+import { StarterKit } from '@tiptap/starter-kit';
+import { Link } from '@tiptap/extension-link';
+import { TaskList } from '@tiptap/extension-task-list';
+import { TaskItem } from '@tiptap/extension-task-item';
+import { TableKit } from '@tiptap/extension-table';
+import { Placeholder } from '@tiptap/extension-placeholder';
+import { Extension } from '@tiptap/core';
+import { mdToDoc, docToMd } from './md.mjs';
+import { commentsPlugin, commentsKey, findRange } from './comments-plugin.mjs';
+import { diffPlugin, diffKey } from './diff-plugin.mjs';
+import { activeLinePlugin } from './active-line.mjs';
+import { SlashCommands } from './slash.mjs';
+import { atMention } from './at-mention.mjs';
+import { markdownPastePlugin } from './paste-md.mjs';
+
+// Slug a heading's text into a stable id (matches the old reindexHeadings so
+// ToC links + comment heading-anchors keep working).
+function slug(text) {
+  return String(text).toLowerCase().trim()
+    .replace(/[^\w\s-]/g, '').replace(/\s+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || 'section';
+}
+
+function textOf(node) {
+  let out = '';
+  node.descendants?.((n) => { if (n.isText) out += n.text; });
+  return out;
+}
+
+// Split a Markdown string into its top-level block sources, normalized through
+// the SAME PM-JSON -> Markdown path the live editor uses (so a block's text is
+// byte-identical whether it comes from the committed base here or from the live
+// document via blockSources()). Used by the app's WYSIWYG diff. Frontmatter is
+// dropped (it isn't a document block).
+export function mdBlocks(md) {
+  const { doc } = mdToDoc(md || '');
+  const kids = (doc && doc.content) || [];
+  return kids.map((node) => docToMd({ type: 'doc', content: [node] }, '').trimEnd());
+}
+
+export function baseExtensions({ placeholder } = {}) {
+  const ext = [
+    StarterKit.configure({ link: false }),
+    Link.configure({ openOnClick: false, autolink: true }),
+    TaskList,
+    TaskItem.configure({ nested: true }),
+    TableKit.configure({ table: { resizable: true } }),
+    SlashCommands,
+  ];
+  if (placeholder) ext.push(Placeholder.configure({
+    // Per-block hint (only the block with the caret, see showOnlyCurrent): the
+    // empty document gets the passed prompt; any other empty block advertises the
+    // two keyboard affordances so "/" and "@" are discoverable in place.
+    includeChildren: false,
+    showOnlyCurrent: true,
+    placeholder: ({ editor, node }) => {
+      if (editor.isEmpty) return placeholder;
+      if (node.type.name === 'paragraph') return 'Type “/” for blocks, “@” to ask the agent…';
+      return '';
+    },
+  }));
+  return ext;
+}
+
+export function createEditor({ element, editable = true, placeholder, onChange, onSelectionChange, onCommentClick, onAtComment, onLinkClick, extensions } = {}) {
+  let frontmatter = '';
+
+  const commentExt = Extension.create({
+    name: 'sonoranceComments',
+    addProseMirrorPlugins() { return [commentsPlugin({ onClick: onCommentClick }), diffPlugin(), activeLinePlugin(), markdownPastePlugin()]; },
+  });
+
+  const editor = new Editor({
+    element,
+    editable,
+    extensions: (extensions || baseExtensions({ placeholder })).concat(commentExt, atMention({ onComment: onAtComment })),
+    content: { type: 'doc', content: [{ type: 'paragraph' }] },
+    // Links stay `openOnClick: false` (so a plain click still places the caret for editing the
+    // surrounding text), but a click that lands ON the anchor jumps out. The app handler opens
+    // external targets in a new tab and scrolls in-page `#anchor` links.
+    editorProps: {
+      handleClick(view, pos, event) {
+        const a = event.target && event.target.closest && event.target.closest('a[href]');
+        if (a && onLinkClick) { onLinkClick(a, event); return true; }
+        return false;
+      },
+    },
+    onUpdate: () => { onChange?.(); },
+    onSelectionUpdate: () => { onSelectionChange?.(); },
+  });
+
+  return {
+    editor,
+
+    // Load a Markdown string (frontmatter split off + remembered).
+    setMarkdown(md, { emit = false } = {}) {
+      const { frontmatter: fm, doc } = mdToDoc(md || '');
+      frontmatter = fm;
+      editor.commands.setContent(doc, { emitUpdate: emit });
+    },
+
+    // Serialize the current doc back to Markdown (frontmatter re-attached).
+    getMarkdown() {
+      return docToMd(editor.getJSON(), frontmatter);
+    },
+
+    frontmatter() { return frontmatter; },
+    setFrontmatter(fm) { frontmatter = fm || ''; },
+
+    setEditable(on) { editor.setEditable(!!on); },
+    isEditable() { return editor.isEditable; },
+    focus() { editor.commands.focus(); },
+    hasFocus() { try { return editor.view.hasFocus(); } catch { return false; } },
+    isEmpty() { return editor.isEmpty; },
+
+    // Whether a mark/node is active at the current selection — for lighting the
+    // bubble-menu buttons (bold/italic/link/H2) and detecting a table context.
+    isActive(name, attrs) { try { return editor.isActive(name, attrs); } catch { return false; } },
+
+    // Inline formatting toggles from the selection bubble menu (thin wrappers so
+    // the app never reaches into Tiptap directly). Each keeps the selection.
+    toggleBold() { editor.chain().focus().toggleBold().run(); },
+    toggleItalic() { editor.chain().focus().toggleItalic().run(); },
+    toggleHeading(level = 2) { editor.chain().focus().toggleHeading({ level }).run(); },
+    // Set (or clear when href is empty) a link on the current selection.
+    setLink(href) {
+      const h = (href || '').trim();
+      if (!h) editor.chain().focus().unsetLink().run();
+      else editor.chain().focus().setLink({ href: h }).run();
+    },
+
+    // Table structure edits from the in-table toolbar.
+    addRow() { editor.chain().focus().addRowAfter().run(); },
+    addColumn() { editor.chain().focus().addColumnAfter().run(); },
+    deleteRow() { editor.chain().focus().deleteRow().run(); },
+    deleteColumn() { editor.chain().focus().deleteColumn().run(); },
+    deleteTable() { editor.chain().focus().deleteTable().run(); },
+
+    // Show a set of comments as inline highlight decorations (no DOM mutation).
+    setComments(comments) {
+      const tr = editor.state.tr.setMeta(commentsKey, { comments: comments || [] });
+      editor.view.dispatch(tr);
+    },
+
+    // Show change decorations (added/modified block classes + removed-block
+    // widget islands). Pass null to clear. See diff-plugin.mjs for the shape.
+    setDiff(diff) {
+      const tr = editor.state.tr.setMeta(diffKey, diff || null);
+      editor.view.dispatch(tr);
+    },
+
+    // The top-level block sources of the current doc, in order — the unit the
+    // app's diff compares against the committed base. Serialized per block so
+    // block index lines up 1:1 with the ProseMirror top-level nodes.
+    blockSources() {
+      const json = editor.getJSON();
+      const kids = (json && json.content) || [];
+      return kids.map((node) => docToMd({ type: 'doc', content: [node] }, '').trimEnd());
+    },
+
+    // The PM range { from, to } a comment anchors to in the current doc, or null.
+    commentRange(anchor) { return findRange(editor.state.doc, anchor); },
+
+    // The DOM rect of a comment's anchor (for placing/scrolling its card).
+    commentRect(anchor) {
+      const r = findRange(editor.state.doc, anchor);
+      if (!r) return null;
+      try { const s = editor.view.coordsAtPos(r.from); return { top: s.top, bottom: s.bottom, left: s.left }; } catch { return null; }
+    },
+
+    // The anchor { quote, heading } for the current (non-empty) selection, or
+    // null when the selection is collapsed. Used to create a new comment.
+    selectionAnchor() {
+      const { from, to, empty } = editor.state.selection;
+      if (empty || to <= from) return null;
+      const quote = editor.state.doc.textBetween(from, to, ' ').trim();
+      if (!quote) return null;
+      let heading = '';
+      editor.state.doc.nodesBetween(0, from, (node, pos) => {
+        if (node.type.name === 'heading' && pos <= from) heading = node.textContent;
+      });
+      return { quote: quote.slice(0, 2000), heading: heading.trim() };
+    },
+
+    // Heading list for the ToC / scroll-spy, with stable, de-duplicated ids.
+    headings() {
+      const out = [];
+      const seen = new Map();
+      editor.state.doc.descendants((node) => {
+        if (node.type.name !== 'heading') return;
+        const text = textOf(node);
+        let id = slug(text);
+        const n = (seen.get(id) || 0) + 1;
+        seen.set(id, n);
+        if (n > 1) id = `${id}-${n}`;
+        out.push({ level: node.attrs.level, text, id });
+      });
+      return out;
+    },
+
+    destroy() { editor.destroy(); },
+  };
+}