@tessera-editor/core 0.1.0

package/src/extensions/find-replace.ts

@@ -0,0 +1,229 @@
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+
+/**
+ * Find & replace (acceptance §3: ⌘F). The core plugin owns match computation
+ * and decorations; the binding renders the panel and calls these commands.
+ */
+
+export interface FindMatch {
+  from: number
+  to: number
+}
+
+export interface FindReplaceState {
+  query: string
+  matches: FindMatch[]
+  active: number
+  visible: boolean
+}
+
+interface FindReplaceStorage extends FindReplaceState {}
+
+export const findReplaceKey = new PluginKey<FindReplaceState>('tesseraFindReplace')
+
+function computeMatches(doc: import('@tiptap/pm/model').Node, query: string): FindMatch[] {
+  if (!query) {
+    return []
+  }
+  const matches: FindMatch[] = []
+  const needle = query.toLowerCase()
+  doc.descendants((node, pos) => {
+    if (node.isText && node.text) {
+      const haystack = node.text.toLowerCase()
+      let idx = haystack.indexOf(needle)
+      while (idx !== -1) {
+        matches.push({ from: pos + idx, to: pos + idx + needle.length })
+        idx = haystack.indexOf(needle, idx + needle.length)
+      }
+    }
+    return true
+  })
+  return matches
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    findReplace: {
+      openFindPanel: () => ReturnType
+      closeFindPanel: () => ReturnType
+      setFindQuery: (query: string) => ReturnType
+      findNext: () => ReturnType
+      findPrev: () => ReturnType
+      replaceCurrent: (replacement: string) => ReturnType
+      replaceAll: (replacement: string) => ReturnType
+    }
+  }
+}
+
+export const TesseraFindReplace = Extension.create<Record<string, never>, FindReplaceStorage>({
+  name: 'tesseraFindReplace',
+
+  addStorage() {
+    return {
+      query: '',
+      matches: [],
+      active: 0,
+      visible: false,
+    }
+  },
+
+  addCommands() {
+    return {
+      openFindPanel:
+        () =>
+        ({ tr, dispatch }) => {
+          if (dispatch) {
+            tr.setMeta(findReplaceKey, { type: 'open' })
+            dispatch(tr)
+          }
+          return true
+        },
+      closeFindPanel:
+        () =>
+        ({ tr, dispatch }) => {
+          if (dispatch) {
+            tr.setMeta(findReplaceKey, { type: 'close' })
+            dispatch(tr)
+          }
+          return true
+        },
+      setFindQuery:
+        (query: string) =>
+        ({ tr, dispatch }) => {
+          if (dispatch) {
+            tr.setMeta(findReplaceKey, { type: 'query', query })
+            dispatch(tr)
+          }
+          return true
+        },
+      findNext:
+        () =>
+        ({ tr, state, dispatch }) => {
+          const s = findReplaceKey.getState(state)
+          if (!s || s.matches.length === 0) {
+            return false
+          }
+          if (dispatch) {
+            tr.setMeta(findReplaceKey, { type: 'active', active: (s.active + 1) % s.matches.length })
+            dispatch(tr)
+          }
+          return true
+        },
+      findPrev:
+        () =>
+        ({ tr, state, dispatch }) => {
+          const s = findReplaceKey.getState(state)
+          if (!s || s.matches.length === 0) {
+            return false
+          }
+          if (dispatch) {
+            tr.setMeta(findReplaceKey, {
+              type: 'active',
+              active: (s.active - 1 + s.matches.length) % s.matches.length,
+            })
+            dispatch(tr)
+          }
+          return true
+        },
+      replaceCurrent:
+        (replacement: string) =>
+        ({ state, tr, dispatch }) => {
+          const s = findReplaceKey.getState(state)
+          if (!s || s.matches.length === 0) {
+            return false
+          }
+          const m = s.matches[s.active]
+          if (!m) {
+            return false
+          }
+          if (dispatch) {
+            tr.insertText(replacement, m.from, m.to)
+            tr.setMeta(findReplaceKey, { type: 'requery' })
+            dispatch(tr)
+          }
+          return true
+        },
+      replaceAll:
+        (replacement: string) =>
+        ({ state, tr, dispatch }) => {
+          const s = findReplaceKey.getState(state)
+          if (!s || s.matches.length === 0) {
+            return false
+          }
+          if (dispatch) {
+            for (let i = s.matches.length - 1; i >= 0; i--) {
+              const m = s.matches[i]
+              tr.insertText(replacement, m.from, m.to)
+            }
+            tr.setMeta(findReplaceKey, { type: 'requery' })
+            dispatch(tr)
+          }
+          return true
+        },
+    }
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin<FindReplaceState>({
+        key: findReplaceKey,
+        state: {
+          init: (): FindReplaceState => ({ query: '', matches: [], active: 0, visible: false }),
+          apply: (tr, prev, _oldState, newState) => {
+            const meta = tr.getMeta(findReplaceKey) as
+              | { type: 'open' | 'close' | 'requery' }
+              | { type: 'query'; query: string }
+              | { type: 'active'; active: number }
+              | undefined
+            let next: FindReplaceState | null = null
+            if (meta?.type === 'open') {
+              next = { ...prev, visible: true }
+            } else if (meta?.type === 'close') {
+              next = { ...prev, visible: false, matches: [], query: '', active: 0 }
+            } else if (meta?.type === 'query') {
+              const matches = computeMatches(newState.doc, meta.query)
+              next = { query: meta.query, matches, active: 0, visible: true }
+            } else if (meta?.type === 'active') {
+              next = { ...prev, active: meta.active }
+            } else if (meta?.type === 'requery') {
+              next = { ...prev, matches: [], active: 0 }
+            }
+
+            if (!next) {
+              // doc changed outside our commands: recompute if a query is live
+              if (prev.query && prev.visible && tr.docChanged) {
+                const matches = computeMatches(newState.doc, prev.query)
+                return { ...prev, matches, active: 0 }
+              }
+              return prev
+            }
+            // mirror state into editor storage for reactive UI
+            this.storage.query = next.query
+            this.storage.matches = next.matches
+            this.storage.active = next.active
+            this.storage.visible = next.visible
+            return next
+          },
+        },
+        props: {
+          decorations(state) {
+            const s = findReplaceKey.getState(state)
+            if (!s || !s.visible || s.matches.length === 0) {
+              return DecorationSet.empty
+            }
+            const decorations = s.matches.map((m, i) =>
+              Decoration.inline(m.from, m.to, {
+                class: i === s.active ? 'tessera-find-match tessera-find-match--active' : 'tessera-find-match',
+              }),
+            )
+            return DecorationSet.create(state.doc, decorations)
+          },
+        },
+      }),
+    ]
+  },
+})
+
+export type { FindReplaceStorage }

package/src/extensions/gallery.ts

@@ -0,0 +1,111 @@
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+import type { DecorationAttrs } from '@tiptap/pm/view'
+
+/**
+ * Image gallery (acceptance §6, v1.1): runs of two or more consecutive
+ * top-level image blocks are flagged with data-gallery attributes so the
+ * theme can lay them out three per row (CSS: inline-block thirds).
+ * Purely presentational — the document format is unchanged (still
+ * sibling imageBlock nodes), so Markdown/JSON round-trips are unaffected.
+ */
+
+export const galleryKey = new PluginKey('tesseraGallery')
+
+interface GalleryRun {
+  from: number
+  to: number
+  size: number
+}
+
+/** Shared run detection so tests and the plugin agree on the definition. */
+export function findGalleryRuns(doc: ProseMirrorNode): GalleryRun[] {
+  const runs: GalleryRun[] = []
+  let start = -1
+  let size = 0
+  doc.forEach((node, offset) => {
+    if (node.type.name === 'imageBlock') {
+      if (start < 0) {
+        start = offset
+        size = 0
+      }
+      size += 1
+    } else if (start >= 0) {
+      if (size >= 2) {
+        runs.push({ from: start, to: offset, size })
+      }
+      start = -1
+      size = 0
+    }
+  })
+  if (start >= 0 && size >= 2) {
+    runs.push({ from: start, to: doc.content.size, size })
+  }
+  return runs
+}
+
+function galleryDecorations(doc: ProseMirrorNode): DecorationSet {
+  const decorations: Decoration[] = []
+  for (const run of findGalleryRuns(doc)) {
+    let index = 0
+    doc.nodesBetween(run.from, run.to, (node: ProseMirrorNode, pos: number) => {
+      if (node.type.name !== 'imageBlock') {
+        return false
+      }
+      const attrs: DecorationAttrs = {
+        'data-gallery': 'true',
+        'data-gallery-index': String(index),
+        'data-gallery-size': String(run.size),
+      }
+      decorations.push(Decoration.node(pos, pos + node.nodeSize, attrs))
+      index += 1
+      return false
+    })
+  }
+  // props.decorations must yield a DecorationSet — a plain array breaks
+  // DecorationGroup.from (it flattens only set members)
+  return DecorationSet.create(doc, decorations)
+}
+
+export const TesseraGallery = Extension.create({
+  name: 'tesseraGallery',
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: galleryKey,
+        state: {
+          init: (_config, state) => galleryDecorations(state.doc),
+          apply: (tr, old) => (tr.docChanged ? galleryDecorations(tr.doc) : old),
+        },
+        props: {
+          decorations(state) {
+            return galleryKey.getState(state)
+          },
+        },
+      }),
+    ]
+  },
+})
+
+/**
+ * Read the gallery attributes (if any) a NodeView should apply for `node`:
+ * finds the node decoration covering `pos` that carries data-gallery attrs.
+ * NodeViews must apply these themselves — custom NodeViews bypass PM's
+ * automatic decoration-attr application.
+ */
+export function galleryAttrsFor(
+  decorations: readonly Decoration[],
+  pos: number,
+): DecorationAttrs | null {
+  for (const deco of decorations) {
+    const attrs = (deco as unknown as { type?: { attrs?: DecorationAttrs } }).type?.attrs
+    if (attrs && 'data-gallery' in attrs && deco.from <= pos && pos <= deco.to) {
+      return attrs
+    }
+  }
+  return null
+}

package/src/extensions/history.ts

@@ -0,0 +1,133 @@
+import { Extension } from '@tiptap/core'
+import type { JSONContent } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import { getStorageService, type DocSnapshot } from '../services'
+
+/**
+ * Version history capture (v1.1): snapshots the canonical JSON into the
+ * injected StorageService. Auto-capture fires after `idleMs` of inactivity
+ * (Slite: 5 minutes); manual capture is always available as a command.
+ */
+
+export interface HistorySnapshotOptions {
+  /** idle window before auto-capture (default 5 minutes) */
+  idleMs?: number
+  /** minimum ms between two auto-captures (default 60s) */
+  minIntervalMs?: number
+  /** snapshot label source */
+  label?: () => string | undefined
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    tesseraHistory: {
+      captureSnapshot: (label?: string) => ReturnType
+    }
+  }
+  interface EditorEvents {
+    'tessera:snapshotSaved': { snapshot: DocSnapshot }
+  }
+}
+
+export const historyKey = new PluginKey('tesseraHistory')
+
+export const TesseraHistory = Extension.create<HistorySnapshotOptions>({
+  name: 'tesseraHistory',
+
+  addOptions() {
+    return {
+      idleMs: 5 * 60 * 1000,
+      minIntervalMs: 60 * 1000,
+      label: undefined,
+    }
+  },
+
+  addCommands() {
+    return {
+      captureSnapshot:
+        (label?: string) =>
+        ({ editor, state }) => {
+          const storage = getStorageService(editor)
+          if (!storage) {
+            return false
+          }
+          const doc = editor.getJSON() as JSONContent
+          const snapshot: DocSnapshot = {
+            id: `snap-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+            ts: Date.now(),
+            doc,
+            label: label ?? this.options.label?.(),
+          }
+          void storage.saveSnapshot(snapshot).then(() => {
+            editor.emit('tessera:snapshotSaved', { snapshot })
+          })
+          const tr = state.tr.setMeta(historyKey, { type: 'captured', ts: snapshot.ts })
+          editor.view.dispatch(tr)
+          return true
+        },
+    }
+  },
+
+  addProseMirrorPlugins() {
+    const editor = this.editor
+    const options = this.options
+    return [
+      new Plugin({
+        key: historyKey,
+        state: {
+          init: () => ({ lastChange: 0, lastCapture: 0, timer: null as ReturnType<typeof setTimeout> | null }),
+          apply: (tr, prev) => {
+            const meta = tr.getMeta(historyKey) as { type: string; ts?: number } | undefined
+            if (meta?.type === 'captured') {
+              return { ...prev, lastCapture: meta.ts ?? Date.now() }
+            }
+            if (!tr.docChanged) {
+              return prev
+            }
+            return { ...prev, lastChange: Date.now() }
+          },
+        },
+        view() {
+          return {
+            update: (_view, prevState) => {
+              const before = historyKey.getState(prevState)
+              const after = historyKey.getState(editor.state)
+              if (!before || !after || after.lastChange === before.lastChange) {
+                return
+              }
+              const storage = getStorageService(editor)
+              if (!storage) {
+                return
+              }
+              const s = historyKey.getState(editor.state)
+              if (s?.timer) {
+                clearTimeout(s.timer)
+              }
+              const timer = setTimeout(() => {
+                const now = Date.now()
+                const cur = historyKey.getState(editor.state)
+                if (!cur || now - cur.lastChange < options.idleMs! - 50) {
+                  return
+                }
+                if (now - cur.lastCapture < options.minIntervalMs!) {
+                  return
+                }
+                editor.commands.captureSnapshot()
+              }, options.idleMs!)
+              const st = historyKey.getState(editor.state)
+              if (st) {
+                st.timer = timer
+              }
+            },
+            destroy() {
+              const s = historyKey.getState(editor.state)
+              if (s?.timer) {
+                clearTimeout(s.timer)
+              }
+            },
+          }
+        },
+      }),
+    ]
+  },
+})

package/src/extensions/input-rules.ts

@@ -0,0 +1,34 @@
+import { Extension, wrappingInputRule, markInputRule } from '@tiptap/core'
+
+/**
+ * Tessera-specific input rules beyond the StarterKit defaults:
+ *   `[] ` + typing  → task list (mirrors Slite's trigger)
+ *   `::text::`      → highlight mark
+ */
+export const TesseraInputRules = Extension.create({
+  name: 'tesseraInputRules',
+
+  addInputRules() {
+    const taskList = this.editor.schema.nodes.taskList
+    const highlight = this.editor.schema.marks.highlight
+    const rules = []
+
+    if (taskList) {
+      rules.push(
+        wrappingInputRule({
+          find: /^\[\] $/,
+          type: taskList,
+        }),
+      )
+    }
+    if (highlight) {
+      rules.push(
+        markInputRule({
+          find: /::([^:]+)::$/,
+          type: highlight,
+        }),
+      )
+    }
+    return rules
+  },
+})

package/src/extensions/metrics.ts

@@ -0,0 +1,61 @@
+import { Extension } from '@tiptap/core'
+import type { Editor } from '@tiptap/core'
+import { docToMarkdown } from '../markdown'
+
+/**
+ * Performance metrics (acceptance §8, v1.1): long-document observability.
+ * The architecture keeps per-block NodeViews and lazy decoration passes in
+ * place; this exposes the numbers a host needs to watch (block/word counts,
+ * heavy-node counts, markdown serialize cost) so virtualization work can be
+ * measured rather than guessed. Usage: `getTesseraMetrics(editor)`.
+ */
+
+export interface TesseraMetricsSnapshot {
+  /** Top-level blocks in the document. */
+  blocks: number
+  /** Whitespace-split word count of the document text. */
+  words: number
+  /** imageBlock nodes. */
+  images: number
+  /** aiTable nodes. */
+  tables: number
+  /** NodeView wrapper elements currently mounted. */
+  mountedNodeViews: number
+  /** Milliseconds for a full Markdown serialization of the current doc. */
+  serializeMs: number
+}
+
+export function measureTesseraMetrics(editor: Editor): TesseraMetricsSnapshot {
+  let images = 0
+  let tables = 0
+  editor.state.doc.descendants(node => {
+    if (node.type.name === 'imageBlock') images += 1
+    if (node.type.name === 'table') tables += 1
+    return true
+  })
+
+  const started = performance.now()
+  docToMarkdown(editor.state.doc, editor.state.schema)
+  const serializeMs = Math.round((performance.now() - started) * 100) / 100
+
+  return {
+    blocks: editor.state.doc.childCount,
+    words: editor.state.doc.textBetween(0, editor.state.doc.content.size, ' ', ' ')
+      .split(/\s+/)
+      .filter(Boolean).length,
+    images,
+    tables,
+    mountedNodeViews: editor.view
+      ? editor.view.dom.querySelectorAll('[data-node-view-wrapper]').length
+      : 0,
+    serializeMs,
+  }
+}
+
+export const TesseraMetrics = Extension.create({
+  name: 'tesseraMetrics',
+})
+
+export function getTesseraMetrics(editor: Editor): TesseraMetricsSnapshot {
+  return measureTesseraMetrics(editor)
+}

package/src/extensions/shortcuts.ts

@@ -0,0 +1,118 @@
+import { Extension } from '@tiptap/core'
+import type { Editor } from '@tiptap/core'
+import { TextSelection } from '@tiptap/pm/state'
+import type { EditorState, Transaction } from '@tiptap/pm/state'
+
+/**
+ * The Tessera keyboard map (acceptance checklist §3). Panel-opening shortcuts
+ * emit `tessera:*` events that the binding's UI layer listens to, keeping this
+ * extension UI-free.
+ */
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    tesseraShortcuts: {
+      /** Move the top-level block containing the caret up one position. */
+      moveBlockUp: () => ReturnType
+      /** Move the top-level block containing the caret down one position. */
+      moveBlockDown: () => ReturnType
+    }
+  }
+  interface EditorEvents {
+    'tessera:formatPanel': { kind: 'color' | 'highlight' }
+    'tessera:linkPanel': Record<string, never>
+    'tessera:findPanel': Record<string, never>
+    'tessera:insertImage': Record<string, never>
+    'tessera:askPanel': Record<string, never>
+    'tessera:historyPanel': Record<string, never>
+    'tessera:commentPanel': Record<string, never>
+  }
+}
+
+export const TesseraShortcuts = Extension.create({
+  name: 'tesseraShortcuts',
+  priority: 500,
+
+  addCommands() {
+    return {
+      moveBlockUp:
+        () =>
+        ({ state, tr, dispatch }) =>
+          swapBlock(state, tr, dispatch, -1),
+      moveBlockDown:
+        () =>
+        ({ state, tr, dispatch }) =>
+          swapBlock(state, tr, dispatch, 1),
+    }
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      'Mod-Shift-1': () => this.editor.commands.toggleHeading({ level: 1 }),
+      'Mod-Shift-2': () => this.editor.commands.toggleHeading({ level: 2 }),
+      'Mod-Shift-3': () => this.editor.commands.toggleHeading({ level: 3 }),
+      'Mod-Shift-4': () => this.editor.commands.toggleHeading({ level: 4 }),
+      'Mod-Shift-7': () => this.editor.commands.toggleOrderedList(),
+      'Mod-Shift-8': () => this.editor.commands.toggleBulletList(),
+      'Mod-Shift-c': () => this.editor.commands.toggleTaskList(),
+      'Mod-Alt-h': () => this.editor.commands.toggleHint(),
+      'Mod-j': () => this.editor.commands.toggleCode(),
+      'Mod-Shift-9': () => this.editor.commands.toggleCodeBlock(),
+      'Mod-Shift-.': () => this.editor.commands.toggleBlockquote(),
+      'Mod-e': () => {
+        this.editor.emit('tessera:formatPanel', { kind: 'color' })
+        return true
+      },
+      'Mod-k': () => {
+        this.editor.emit('tessera:linkPanel', {})
+        return true
+      },
+      'Mod-f': () => {
+        this.editor.emit('tessera:findPanel', {})
+        return true
+      },
+      'Mod-Shift-k': () => {
+        this.editor.emit('tessera:askPanel', {})
+        return true
+      },
+      'Mod-Alt-s': () => this.editor.commands.insertTableTyped({ withHeaderRow: true }),
+      'Mod-Alt-t': () => this.editor.commands.insertTableTyped({ withHeaderRow: false }),
+      'Mod-Alt-p': () => this.editor.commands.togglePlaceholderMark('text'),
+      'Mod-Alt-m': () => {
+        this.editor.emit('tessera:commentPanel', {})
+        return true
+      },
+      'Alt-ArrowUp': () => this.editor.commands.moveBlockUp(),
+      'Alt-ArrowDown': () => this.editor.commands.moveBlockDown(),
+    }
+  },
+})
+
+type Dispatch = ((args?: unknown) => void) | undefined
+
+function swapBlock(state: EditorState, tr: Transaction, dispatch: Dispatch, direction: -1 | 1): boolean {
+  const { $from } = state.selection
+  if ($from.depth < 1) {
+    return false
+  }
+  const index = $from.index(0)
+  const other = index + direction
+  if (other < 0 || other >= state.doc.childCount) {
+    return false
+  }
+  const node = state.doc.child(index)
+  const otherNode = state.doc.child(other)
+  const pos = $from.before(1)
+  const nodeStart = direction === -1 ? pos - otherNode.nodeSize : pos
+  const rangeEnd = nodeStart + otherNode.nodeSize + node.nodeSize
+  if (dispatch) {
+    const content = direction === -1 ? [node, otherNode] : [otherNode, node]
+    tr.replaceWith(nodeStart, rangeEnd, content)
+    const anchor = tr.mapping.map(state.selection.anchor)
+    tr.setSelection(TextSelection.near(tr.doc.resolve(Math.min(anchor, tr.doc.content.size))))
+    dispatch(tr)
+  }
+  return true
+}
+
+export type { Editor }