@chatpanel/events 0.2.0 → 0.3.0

package/index.js

@@ -42,3 +42,5 @@ export { explainMcpError, packageFromArgs } from './mcp-errors.js';
 export { createManifest, ManifestError, SOURCES } from './manifest.js';
 export { createKernel, meetDecisions, KernelError, REQUIRED_PLUGINS, ALLOW_ALL } from './kernel.js';
 export { replay, formatReport, parseJsonl, toJsonl } from './harness.js';
+export { compileQuery, findMatches, matchIndexFor, expandReplacement, replaceMatch, replaceAll, replaceAllInRange, MAX_MATCHES } from './text-search.js';
+export { outlineOf, parseListItem, continueList, indentSelection, toggleWrap, toggleLinePrefix, toggleTask, toggleLink, docStats, selectionStats } from './markdown-authoring.js';

package/markdown-authoring.js

@@ -0,0 +1,288 @@
+// The editing gestures that make writing markdown feel like writing, not like typing syntax.
+//
+// Outline, list continuation, format toggles and document stats are all the same shape of
+// problem: given the document text and where the caret is, what should the text and the
+// caret become. None of them needs a DOM — which is precisely why they do not belong in a
+// `<textarea>` keydown handler, where Notes would have had to write them twice (once for
+// the classic surface, once for CodeMirror) and a mobile client a third time.
+//
+// Every function here is pure and returns an EDIT ({ text, selStart, selEnd }) rather than
+// mutating a surface, so the caller only has to apply a range and set a selection.
+
+/** ``` or ~~~ opening/closing a fenced block. Headings inside a fence are code, not structure. */
+const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
+
+/**
+ * The heading structure of a markdown document.
+ *
+ * Fenced code is skipped: a `# comment` inside a shell example is not a section, and an
+ * outline that jumps into code is worse than no outline. Setext headings (`===` / `---`
+ * underlines) are recognised too, because notes pasted from other tools use them.
+ */
+export function outlineOf(markdown) {
+  const doc = String(markdown ?? '');
+  const lines = doc.split('\n');
+  const out = [];
+  let offset = 0;
+  let fence = '';
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const fenceHit = line.match(FENCE_RE);
+    if (fenceHit) {
+      if (!fence) fence = fenceHit[1][0];
+      else if (fenceHit[1][0] === fence) fence = '';
+      offset += line.length + 1;
+      continue;
+    }
+    if (!fence) {
+      const atx = line.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
+      const next = lines[i + 1];
+      const setext = !atx && line.trim() && next && next.match(/^\s{0,3}(=+|-+)\s*$/);
+      if (atx) {
+        out.push({ level: atx[1].length, text: atx[2].trim(), line: i, start: offset, end: offset + line.length });
+      } else if (setext) {
+        out.push({ level: setext[1][0] === '=' ? 1 : 2, text: line.trim(), line: i, start: offset, end: offset + line.length });
+      }
+    }
+    offset += line.length + 1;
+  }
+  return out;
+}
+
+/** `  - [ ] item` → its indent, marker, checkbox and content. Null when the line is not a list item. */
+export function parseListItem(line) {
+  const m = String(line ?? '').match(/^(\s*)([-*+]|\d{1,9}[.)])\s+(\[[ xX]\]\s+)?(.*)$/);
+  if (!m) return null;
+  return {
+    indent: m[1],
+    marker: m[2],
+    ordered: /\d/.test(m[2]),
+    checkbox: m[3] ? m[3].trimEnd() : '',
+    content: m[4],
+  };
+}
+
+function lineBoundsAt(doc, pos) {
+  const start = doc.lastIndexOf('\n', Math.max(0, pos - 1)) + 1;
+  const nl = doc.indexOf('\n', pos);
+  return { start, end: nl === -1 ? doc.length : nl };
+}
+
+/**
+ * What Enter should do inside a list.
+ *
+ * Continues the list with the same indent and marker (incrementing an ordered one), and
+ * ENDS it when the item is empty — pressing Enter twice is how everyone expects to leave a
+ * list, and without that rule the user is left deleting a bullet they did not ask for.
+ *
+ * Returns null when the caret is not in a list item, so the caller can let the key fall
+ * through to the surface's own newline handling.
+ */
+export function continueList(text, cursor) {
+  const doc = String(text ?? '');
+  const pos = Math.max(0, Math.min(cursor, doc.length));
+  const { start, end } = lineBoundsAt(doc, pos);
+  const item = parseListItem(doc.slice(start, end));
+  if (!item) return null;
+
+  // Empty item → the user is done with the list. Clear the marker instead of adding another.
+  if (!item.content.trim()) {
+    return { text: `${doc.slice(0, start)}\n${doc.slice(end)}`, selStart: start + 1, selEnd: start + 1 };
+  }
+
+  const marker = item.ordered
+    ? `${(parseInt(item.marker, 10) || 0) + 1}${item.marker.slice(-1)}`
+    : item.marker;
+  // A checked box never continues as checked — the next item is new work, not done work.
+  const box = item.checkbox ? '[ ] ' : '';
+  const insert = `\n${item.indent}${marker} ${box}`;
+  const caret = pos + insert.length;
+  return { text: doc.slice(0, pos) + insert + doc.slice(pos), selStart: caret, selEnd: caret };
+}
+
+/**
+ * Indent or outdent every list item the selection touches.
+ *
+ * Whole lines, not the caret's line alone, so Tab on a multi-line selection does the
+ * obvious thing. Outdent removes at most one level and never eats non-space characters.
+ */
+export function indentSelection(text, selStart, selEnd, dir = 1, unit = '  ') {
+  const doc = String(text ?? '');
+  const from = lineBoundsAt(doc, Math.min(selStart, selEnd)).start;
+  const to = lineBoundsAt(doc, Math.max(selStart, selEnd)).end;
+  const lines = doc.slice(from, to).split('\n');
+  let firstDelta = 0;
+  let total = 0;
+  const shifted = lines.map((line, i) => {
+    let next = line;
+    if (dir >= 0) {
+      if (line.trim()) next = unit + line;
+    } else {
+      const m = line.match(new RegExp(`^(${unit}|\\t|\\s{1,${unit.length}})`));
+      if (m) next = line.slice(m[0].length);
+    }
+    const delta = next.length - line.length;
+    if (i === 0) firstDelta = delta;
+    total += delta;
+    return next;
+  });
+  return {
+    text: doc.slice(0, from) + shifted.join('\n') + doc.slice(to),
+    selStart: Math.max(from, Math.min(selStart, selEnd) + firstDelta),
+    selEnd: Math.max(from, Math.max(selStart, selEnd) + total),
+  };
+}
+
+/** Inline formats, as the pair of markers that wrap the selection. */
+const WRAPS = {
+  bold: '**',
+  italic: '*',
+  code: '`',
+  strike: '~~',
+  highlight: '==',
+};
+
+/**
+ * Toggle an inline format around the selection.
+ *
+ * Toggle, not apply: selecting already-bold text and pressing ⌘B must UNbold it, both when
+ * the markers are inside the selection and when they sit just outside it (which is what a
+ * double-click on the word gives you). Getting only the first case right is the usual bug,
+ * and it leaves users with `****text****`.
+ */
+export function toggleWrap(text, selStart, selEnd, kind) {
+  const doc = String(text ?? '');
+  const mark = WRAPS[kind];
+  if (!mark) return null;
+  let a = Math.min(selStart, selEnd);
+  let b = Math.max(selStart, selEnd);
+
+  // Nothing selected: grow to the word under the caret so ⌘B on a word just works.
+  if (a === b) {
+    const { start, end } = lineBoundsAt(doc, a);
+    const line = doc.slice(start, end);
+    let ws = a - start;
+    let we = a - start;
+    while (ws > 0 && /\w/.test(line[ws - 1])) ws -= 1;
+    while (we < line.length && /\w/.test(line[we])) we += 1;
+    if (we > ws) { a = start + ws; b = start + we; }
+  }
+
+  const inner = doc.slice(a, b);
+  // Markers inside the selection.
+  if (inner.length >= mark.length * 2 && inner.startsWith(mark) && inner.endsWith(mark)) {
+    const stripped = inner.slice(mark.length, -mark.length);
+    return { text: doc.slice(0, a) + stripped + doc.slice(b), selStart: a, selEnd: a + stripped.length };
+  }
+  // Markers hugging the selection.
+  if (doc.slice(a - mark.length, a) === mark && doc.slice(b, b + mark.length) === mark) {
+    return {
+      text: doc.slice(0, a - mark.length) + inner + doc.slice(b + mark.length),
+      selStart: a - mark.length,
+      selEnd: b - mark.length,
+    };
+  }
+  return {
+    text: doc.slice(0, a) + mark + inner + mark + doc.slice(b),
+    selStart: a + mark.length,
+    selEnd: b + mark.length,
+  };
+}
+
+/**
+ * Toggle a line-level prefix (quote, bullet, number, checkbox) over the selected lines.
+ *
+ * Uniformly: if EVERY touched line already has the prefix the gesture removes it, otherwise
+ * it adds it to all of them. A per-line toggle on a mixed selection scrambles the block.
+ */
+export function toggleLinePrefix(text, selStart, selEnd, kind) {
+  const doc = String(text ?? '');
+  const from = lineBoundsAt(doc, Math.min(selStart, selEnd)).start;
+  const to = lineBoundsAt(doc, Math.max(selStart, selEnd)).end;
+  const lines = doc.slice(from, to).split('\n');
+  const RE = {
+    quote: /^(\s*)>\s?/,
+    bullet: /^(\s*)[-*+]\s+/,
+    number: /^(\s*)\d{1,9}[.)]\s+/,
+    task: /^(\s*)[-*+]\s+\[[ xX]\]\s+/,
+  }[kind];
+  if (!RE) return null;
+  const on = lines.every((l) => !l.trim() || RE.test(l));
+  let n = 0;
+  const next = lines.map((line) => {
+    if (!line.trim()) return line;
+    if (on) return line.replace(RE, '$1');
+    const indent = line.match(/^\s*/)[0];
+    const body = line.slice(indent.length).replace(/^(>\s?|[-*+]\s+(\[[ xX]\]\s+)?|\d{1,9}[.)]\s+)/, '');
+    n += 1;
+    const prefix = { quote: '> ', bullet: '- ', number: `${n}. `, task: '- [ ] ' }[kind];
+    return indent + prefix + body;
+  });
+  const body = next.join('\n');
+  return { text: doc.slice(0, from) + body + doc.slice(to), selStart: from, selEnd: from + body.length };
+}
+
+/** Toggle `- [ ]` ⇄ `- [x]` on the line at `cursor`. Null when that line has no checkbox. */
+export function toggleTask(text, cursor) {
+  const doc = String(text ?? '');
+  const { start, end } = lineBoundsAt(doc, Math.max(0, Math.min(cursor, doc.length)));
+  const line = doc.slice(start, end);
+  const m = line.match(/^(\s*[-*+]\s+\[)([ xX])(\]\s*)/);
+  if (!m) return null;
+  const flipped = `${m[1]}${m[2] === ' ' ? 'x' : ' '}${m[3]}${line.slice(m[0].length)}`;
+  return { text: doc.slice(0, start) + flipped + doc.slice(end), selStart: cursor, selEnd: cursor };
+}
+
+/**
+ * Wrap the selection as a markdown link.
+ *
+ * When the selection already looks like a URL it becomes the TARGET with an empty label,
+ * otherwise it becomes the label — which is what the user meant in each case, and saves
+ * retyping the half they already have. The caret lands on the empty half.
+ */
+export function toggleLink(text, selStart, selEnd, url = '') {
+  const doc = String(text ?? '');
+  const a = Math.min(selStart, selEnd);
+  const b = Math.max(selStart, selEnd);
+  const inner = doc.slice(a, b);
+  const looksUrl = /^(https?:\/\/|mailto:)\S+$/i.test(inner.trim());
+  const label = looksUrl ? '' : inner;
+  const target = url || (looksUrl ? inner.trim() : '');
+  const out = `[${label}](${target})`;
+  const caret = looksUrl ? a + 1 : a + out.length - 1;
+  return { text: doc.slice(0, a) + out + doc.slice(b), selStart: caret, selEnd: caret + (looksUrl ? 0 : 0) };
+}
+
+/** Words in a string, counting a run of any non-whitespace as one word. */
+function countWords(s) {
+  const t = String(s ?? '').trim();
+  return t ? t.split(/\s+/).length : 0;
+}
+
+/**
+ * Word / character counts and a reading estimate.
+ *
+ * 200 wpm is the usual prose figure. Reading time is reported in whole minutes with a floor
+ * of one, because "0 min read" is noise and a sub-minute note does not need a number at all.
+ */
+export function docStats(text, { wpm = 200 } = {}) {
+  const doc = String(text ?? '');
+  const words = countWords(doc);
+  return {
+    words,
+    chars: doc.length,
+    charsNoSpaces: doc.replace(/\s/g, '').length,
+    lines: doc ? doc.split('\n').length : 0,
+    readingMinutes: words ? Math.max(1, Math.round(words / wpm)) : 0,
+  };
+}
+
+/** Stats for the selection when there is one, otherwise for the whole document. */
+export function selectionStats(text, selStart, selEnd, opts) {
+  const doc = String(text ?? '');
+  const a = Math.min(selStart, selEnd);
+  const b = Math.max(selStart, selEnd);
+  return a === b
+    ? { ...docStats(doc, opts), selection: false }
+    : { ...docStats(doc.slice(a, b), opts), selection: true };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.2.0",
-  "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
+  "version": "0.3.0",
+  "description": "The canonical ChatPanel event-log and capability contracts — typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -15,6 +15,7 @@
     "./kernel.js": "./kernel.js",
     "./loop.js": "./loop.js",
     "./manifest.js": "./manifest.js",
+    "./markdown-authoring.js": "./markdown-authoring.js",
     "./mcp-errors.js": "./mcp-errors.js",
     "./meeting-analyzers.js": "./meeting-analyzers.js",
     "./order.js": "./order.js",
@@ -27,22 +28,24 @@
     "./sources-retrieval.js": "./sources-retrieval.js",
     "./sources.js": "./sources.js",
     "./store.js": "./store.js",
+    "./text-search.js": "./text-search.js",
     "./tool-groups.js": "./tool-groups.js",
     "./tool-need.js": "./tool-need.js",
     "./trajectory.js": "./trajectory.js",
     "./upcast.js": "./upcast.js"
   },
   "files": [
-    "index.js",
     "adapters.js",
     "capability.js",
     "citations.js",
     "event.js",
     "harness.js",
+    "index.js",
     "invariants.js",
     "kernel.js",
     "loop.js",
     "manifest.js",
+    "markdown-authoring.js",
     "mcp-errors.js",
     "meeting-analyzers.js",
     "order.js",
@@ -55,6 +58,7 @@
     "sources-retrieval.js",
     "sources.js",
     "store.js",
+    "text-search.js",
     "tool-groups.js",
     "tool-need.js",
     "trajectory.js",

package/text-search.js

@@ -0,0 +1,155 @@
+// Find, find-all and replace over a plain-text document.
+//
+// Every editing surface ChatPanel will ever ship needs this same answer: given a document,
+// a query and a few toggles, WHERE are the matches and what does the document look like
+// after a replace. The Notes editor asks it twice already — once for the `<textarea>` and
+// once for the CodeMirror surface — and a mobile notes client would ask it a third time.
+// Three implementations of "what counts as a whole word" become three different answers,
+// so the rule lives here once and the surfaces only decide how to PAINT the ranges.
+//
+// Pure over strings: no DOM, no editor, no document object. That is what makes it testable
+// without a browser and reusable from a `<textarea>`, a CM6 EditorState, a SwiftUI
+// TextEditor, or the gateway rewriting a note server-side.
+
+/** Escape a literal string so it can be embedded in a RegExp verbatim. */
+function escapeLiteral(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Build the RegExp for a query, or explain why it can't be built.
+ *
+ * Returns a RESULT rather than throwing because an invalid regex is a normal thing for a
+ * user to type mid-keystroke ("(" on the way to "(a|b)") — the find bar wants to show a
+ * quiet hint, not catch an exception on every input event.
+ *
+ * Whole-word uses lookarounds instead of `\b` because `\b` is defined against word
+ * characters: `\bfoo(\b` never matches, since there is no word boundary after `(`. The
+ * lookarounds ask the question that was actually meant — "not glued to a word character".
+ */
+export function compileQuery(query, { caseSensitive = false, wholeWord = false, regex = false } = {}) {
+  const q = String(query ?? '');
+  if (!q) return { ok: false, error: 'empty' };
+  let source = regex ? q : escapeLiteral(q);
+  if (wholeWord) source = `(?<!\\w)(?:${source})(?!\\w)`;
+  try {
+    return { ok: true, re: new RegExp(source, caseSensitive ? 'gu' : 'giu') };
+  } catch {
+    // `u` mode rejects patterns older engines tolerate (e.g. a bare `\d` inside a class is
+    // fine, but `\-` is not). Retry without it so a user's plain regex still works.
+    try {
+      return { ok: true, re: new RegExp(source, caseSensitive ? 'g' : 'gi') };
+    } catch (e) {
+      return { ok: false, error: e?.message || 'invalid regular expression' };
+    }
+  }
+}
+
+/**
+ * Every match of `query` in `text`, in document order.
+ *
+ * Zero-length matches (a user types `a*`, or `^` in multiline) would spin the loop forever
+ * on a global regex, because `lastIndex` never advances on its own. They are skipped and
+ * the cursor is nudged, so an empty-matching pattern degrades to "no matches" instead of
+ * hanging the editor — a find bar runs this on every keystroke.
+ */
+export function findMatches(text, query, opts = {}) {
+  const compiled = compileQuery(query, opts);
+  if (!compiled.ok) return [];
+  const doc = String(text ?? '');
+  const { re } = compiled;
+  const out = [];
+  re.lastIndex = 0;
+  for (let m = re.exec(doc); m; m = re.exec(doc)) {
+    if (m[0].length === 0) { re.lastIndex += 1; continue; }
+    out.push({ start: m.index, end: m.index + m[0].length, text: m[0], groups: m.slice(1) });
+    if (out.length > MAX_MATCHES) break;
+  }
+  return out;
+}
+
+/** A find bar that highlights 100k ranges janks the editor; past this we stop counting. */
+export const MAX_MATCHES = 10000;
+
+/**
+ * Which match should "Find next / previous" land on, given where the caret is.
+ *
+ * Next takes the first match STARTING at or after the caret; previous takes the last one
+ * ENDING at or before it. The asymmetry is deliberate: with the caret sitting inside the
+ * current match — which is exactly where "find next" just left it — a `start < cursor`
+ * rule for previous selects that same match again and the button appears dead.
+ *
+ * Both wrap, because a find bar that dead-ends at the last match makes the user scroll back
+ * to the top by hand. Returns -1 only when there is nothing to land on at all.
+ */
+export function matchIndexFor(matches, cursor = 0, dir = 1) {
+  if (!matches?.length) return -1;
+  if (dir >= 0) {
+    const i = matches.findIndex((m) => m.start >= cursor);
+    return i === -1 ? 0 : i;
+  }
+  for (let i = matches.length - 1; i >= 0; i -= 1) if (matches[i].end <= cursor) return i;
+  return matches.length - 1;
+}
+
+/**
+ * Expand `$1` / `$&` / `$$` in a replacement against one match.
+ *
+ * Only in regex mode. In literal mode a `$` the user typed is a dollar sign they want in
+ * the document — silently eating it as a group reference would corrupt the text and there
+ * would be no way to type a literal `$` at all.
+ */
+export function expandReplacement(replacement, match, regex = false) {
+  const r = String(replacement ?? '');
+  if (!regex) return r;
+  return r.replace(/\$(\$|&|\d{1,2})/g, (whole, token) => {
+    if (token === '$') return '$';
+    if (token === '&') return match.text;
+    const g = match.groups?.[Number(token) - 1];
+    return g === undefined ? whole : g; // an unmatched group stays literal, like String.replace
+  });
+}
+
+/** Replace one already-located match. Returns the new text and the caret to leave behind. */
+export function replaceMatch(text, match, replacement, { regex = false } = {}) {
+  const doc = String(text ?? '');
+  if (!match) return { text: doc, cursor: 0, changed: false };
+  const insert = expandReplacement(replacement, match, regex);
+  return {
+    text: doc.slice(0, match.start) + insert + doc.slice(match.end),
+    cursor: match.start + insert.length,
+    changed: true,
+  };
+}
+
+/**
+ * Replace every match in one pass.
+ *
+ * Applied right-to-left so each splice leaves the offsets of the matches still to come
+ * untouched — replacing left-to-right would shift every subsequent range by the length
+ * delta and quietly corrupt the document whenever the replacement is a different length
+ * from the match.
+ */
+export function replaceAll(text, query, replacement, opts = {}) {
+  const matches = findMatches(text, query, opts);
+  let doc = String(text ?? '');
+  for (let i = matches.length - 1; i >= 0; i -= 1) {
+    const m = matches[i];
+    doc = doc.slice(0, m.start) + expandReplacement(replacement, m, opts.regex) + doc.slice(m.end);
+  }
+  return { text: doc, count: matches.length };
+}
+
+/**
+ * Replace only inside a selected range — "Replace All in selection".
+ *
+ * The range is searched as a substring and the offsets are rebased, so the same matching
+ * rules apply; a caller must not have to reason about anchoring the pattern.
+ */
+export function replaceAllInRange(text, query, replacement, from, to, opts = {}) {
+  const doc = String(text ?? '');
+  const a = Math.max(0, Math.min(from, to, doc.length));
+  const b = Math.min(doc.length, Math.max(from, to, 0));
+  const { text: replaced, count } = replaceAll(doc.slice(a, b), query, replacement, opts);
+  return { text: doc.slice(0, a) + replaced + doc.slice(b), count };
+}