@tessera-editor/core 0.1.0

package/src/index.ts

@@ -0,0 +1,80 @@
+// nodes & marks
+export { Hint } from './nodes/hint'
+export type { HintVariant, HintOptions } from './nodes/hint'
+export { Collapsible, CollapsibleSummary, CollapsibleContent } from './nodes/collapsible'
+export type { CollapsibleOptions } from './nodes/collapsible'
+export { ImageBlock } from './nodes/image'
+export type { ImageAlign, ImageBlockOptions } from './nodes/image'
+export { AiTable, AiTableRow, AiTableCell, AiTableHeader, TABLE_COLUMN_KINDS, normalizeTypes, tableNodeToCsv, tableToCsvAt } from './nodes/table'
+export type { TableColumnKind } from './nodes/table'
+export { EmbedBlock } from './nodes/embed'
+export { TocBlock } from './nodes/toc'
+export { AiAttribution } from './marks/ai'
+export type { AiAttributionOptions } from './marks/ai'
+export { CommentMark, CommentCommands, listCommentRanges } from './marks/comment'
+export { PlaceholderMark, PlaceholderCommands } from './marks/placeholder'
+export type { PlaceholderKind } from './marks/placeholder'
+
+// extensions
+export { TesseraInputRules } from './extensions/input-rules'
+export { TesseraShortcuts } from './extensions/shortcuts'
+export { TesseraFindReplace, findReplaceKey } from './extensions/find-replace'
+export type { FindMatch, FindReplaceState } from './extensions/find-replace'
+export { SlashMenu, defaultSlashItems } from './extensions/slash'
+export type { SlashMenuItem, SlashMenuOptions, SlashRenderFactory } from './extensions/slash'
+export { EmojiMenu, EMOJI_ITEMS, filterEmojiItems } from './extensions/emoji'
+export type { EmojiItem, EmojiMenuOptions } from './extensions/emoji'
+export { TesseraHistory, historyKey } from './extensions/history'
+export type { HistorySnapshotOptions } from './extensions/history'
+export { BlockContextMenu } from './extensions/context-menu'
+export { TesseraGallery, galleryKey, findGalleryRuns } from './extensions/gallery'
+export { TesseraMetrics, getTesseraMetrics, measureTesseraMetrics } from './extensions/metrics'
+export type { TesseraMetricsSnapshot } from './extensions/metrics'
+export { TesseraWordPaste } from './extensions/word-paste'
+export { isWordHtml, cleanWordHtml } from './wordpaste'
+export { findBlockPosById, deleteBlockById, blockAnchorUrl } from './blockmenu'
+
+// preset
+export { createTesseraExtensions, ID_BLOCK_TYPES } from './preset'
+export type { TesseraPresetOptions } from './preset'
+
+// i18n
+export { createTesseraT, tesseraMessages } from './i18n'
+export type { TesseraLocale, TesseraMessageKey, TesseraTranslator } from './i18n'
+
+// services
+export {
+  TesseraServices,
+  getUploadService,
+  getStorageService,
+  getCommentStore,
+  getIdentityService,
+} from './services'
+export type {
+  UploadService,
+  UploadedAsset,
+  TesseraServicesStorage,
+  StorageService,
+  DocSnapshot,
+  CommentStore,
+  CommentThread,
+  CommentEntry,
+  IdentityService,
+} from './services'
+
+// format layer
+export { docToMarkdown, markdownToDoc, createMarkdownSerializer, stableJson } from './markdown'
+
+// diff (history panel)
+export { diffDocs, wordDiff, diffSummary } from './diff'
+export type { WordDiffPart, BlockDiffEntry } from './diff'
+
+// write-back protocol
+export {
+  getTopLevelBlocks,
+  getBlockJson,
+  modifyRange,
+  appendBlocks,
+  removeBlocks,
+} from './writeback'
+export type { BlockHandle, ModifyRangeOptions, AppendBlocksOptions } from './writeback'

package/src/markdown.ts

@@ -0,0 +1,260 @@
+import MarkdownIt from 'markdown-it'
+import { DOMParser as PMDOMParser, DOMSerializer } from '@tiptap/pm/model'
+import { MarkdownSerializer, defaultMarkdownSerializer } from 'prosemirror-markdown'
+import type { Node as PMNode, Schema } from '@tiptap/pm/model'
+import type { JSONContent } from '@tiptap/core'
+
+/**
+ * Interchange format layer (ADR-0004): the canonical format is JSON; Markdown
+ * is the interchange format with guaranteed two-way conversion.
+ *
+ * Standard blocks → plain Markdown. Task lists → GFM `- [x]`.
+ * Tessera structural blocks (hint / collapsible / imageBlock) → semantic HTML,
+ * which round-trips through our parseHTML rules and stays portable elsewhere.
+ *
+ * Export limitations (documented): text color and AI attribution marks do not
+ * carry into Markdown (no static syntax); they survive JSON only.
+ */
+
+/** markdown-it plugin: GFM task lists (`- [x] text`) → ul/li[data-*]. */
+interface MdToken {
+  type: string
+  content?: string
+  children?: MdToken[]
+  attrSet?: (name: string, value: string) => void
+}
+interface MdState {
+  tokens: MdToken[]
+}
+interface MarkdownItLike {
+  core: {
+    ruler: {
+      after: (afterName: string, ruleName: string, fn: (state: MdState) => void) => void
+    }
+  }
+}
+
+function taskListPlugin(md: MarkdownItLike): void {
+  md.core.ruler.after('inline', 'tessera-tasklist', state => {
+    const tokens = state.tokens
+    const taskItems = new Set<number>()
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i]!.type !== 'inline') continue
+      let p = -1
+      if (tokens[i - 1]?.type === 'paragraph_open') p = i - 2
+      if (p === -1 || tokens[p]?.type !== 'list_item_open') continue
+      const children = tokens[i]!.children
+      if (!children || children.length === 0) continue
+      const first = children[0]!
+      const m = /^\[([ xX])\]\s+/.exec(first.content ?? '')
+      if (!m) continue
+      first.content = (first.content ?? '').slice(m[0].length)
+      for (let j = 1; j < children.length; j++) {
+        const child = children[j]!
+        child.content = (child.content ?? '').replace(/^\[([ xX])\]\s+/, '')
+      }
+      tokens[p]!.attrSet?.('data-type', 'taskItem')
+      tokens[p]!.attrSet?.('data-checked', m[1] === ' ' ? 'false' : 'true')
+      taskItems.add(p)
+    }
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i]!.type !== 'bullet_list_open') continue
+      for (let j = i + 1; j < tokens.length; j++) {
+        if (tokens[j]!.type === 'bullet_list_close') break
+        if (tokens[j]!.type === 'list_item_open' && taskItems.has(j)) {
+          tokens[i]!.attrSet?.('data-type', 'taskList')
+          break
+        }
+      }
+    }
+  })
+}
+
+const md = MarkdownIt({ html: true, linkify: true }).use(
+  // structural mismatch is only in the type layer (markdown-it Token typings)
+  taskListPlugin as unknown as Parameters<ReturnType<typeof MarkdownIt>['use']>[0],
+)
+
+interface SerializerState {
+  write: (s: string) => void
+  renderContent: (n: PMNode) => void
+  renderList: (n: PMNode, delim: string, firstDelim: (index: number) => string) => void
+  closeBlock: (n: PMNode) => void
+}
+
+function stripIds(json: JSONContent): JSONContent {
+  const walk = (node: JSONContent): JSONContent => {
+    const attrs = node.attrs && 'id' in node.attrs
+      ? Object.fromEntries(Object.entries(node.attrs).filter(([k]) => k !== 'id'))
+      : node.attrs
+    return {
+      ...node,
+      attrs,
+      content: node.content?.map(walk),
+    } as JSONContent
+  }
+  return walk(json)
+}
+
+function nodeToHtml(node: PMNode): string {
+  // strip ids: interchange HTML must not leak internal block identity
+  const clean = node.type.schema.nodeFromJSON(stripIds(node.toJSON()))
+  const dom = DOMSerializer.fromSchema(node.type.schema).serializeNode(clean) as HTMLElement
+  return dom.outerHTML
+}
+
+export function createMarkdownSerializer(schema: Schema): MarkdownSerializer {
+  const nodes: Record<string, (state: SerializerState, node: PMNode) => void> = {
+    ...defaultMarkdownSerializer.nodes,
+  } as never
+
+  // prosemirror-markdown's defaults use example-schema snake_case node
+  // names; provide camelCase (TipTap) equivalents.
+  const rep = (s: string, n: number) => ' '.repeat(n)
+  nodes.bulletList = (state, node) => {
+    state.renderList(node, '  ', () => '- ')
+    state.closeBlock(node)
+  }
+  nodes.orderedList = (state, node) => {
+    const start = Number(node.attrs.order ?? 1)
+    const maxW = String(start + node.childCount - 1).length
+    const space = rep(' ', maxW + 2)
+    state.renderList(node, space, i => {
+      const n = String(start + i)
+      return rep(' ', maxW - n.length) + n + '. '
+    })
+    state.closeBlock(node)
+  }
+  nodes.listItem = (state, node) => {
+    state.renderContent(node)
+  }
+  nodes.codeBlock = (state, node) => {
+    state.write('```' + (node.attrs.language ?? '') + '\n')
+    state.write(node.textContent)
+    state.write('\n```')
+    state.closeBlock(node)
+  }
+  nodes.horizontalRule = (state, node) => {
+    state.write('---')
+    state.closeBlock(node)
+  }
+  nodes.hardBreak = state => {
+    state.write('\\\n')
+  }
+
+  nodes.taskList = (state, node) => {
+    state.renderList(node, '  ', () => '- ')
+    state.closeBlock(node)
+  }
+  nodes.taskItem = (state, node) => {
+    state.write(node.attrs.checked ? '[x] ' : '[ ] ')
+    state.renderContent(node)
+  }
+  nodes.hint = (state, node) => {
+    state.write(nodeToHtml(node))
+    state.closeBlock(node)
+  }
+  nodes.collapsible = (state, node) => {
+    state.write(nodeToHtml(node))
+    state.closeBlock(node)
+  }
+  nodes.imageBlock = (state, node) => {
+    state.write(nodeToHtml(node))
+    state.closeBlock(node)
+  }
+  nodes.table = (state, node) => {
+    // tables carry typed-column metadata in attrs — HTML keeps it round-trip
+    state.write(nodeToHtml(node))
+    state.closeBlock(node)
+  }
+  nodes.tableRow = () => {}
+  nodes.tableCell = () => {}
+  nodes.tableHeader = () => {}
+  nodes.embedBlock = (state, node) => {
+    state.write(nodeToHtml(node))
+    state.closeBlock(node)
+  }
+  nodes.tocBlock = (state, node) => {
+    state.write('<div data-type="tessera-toc"></div>')
+    state.closeBlock(node)
+  }
+
+  // prosemirror-markdown's defaults use the example-schema mark names
+  // (strong/em); map TipTap's names explicitly.
+  const marks = {
+    ...defaultMarkdownSerializer.marks,
+    bold: { open: '**', close: '**', mixable: true, expelEnclosingWhitespace: true },
+    italic: { open: '*', close: '*', mixable: true, expelEnclosingWhitespace: true },
+    strike: { open: '~~', close: '~~', mixable: true, expelEnclosingWhitespace: true },
+    code: { open: '`', close: '`', escape: false },
+    link: {
+      open: '[',
+      close: (state: { out: string }, mark: { attrs: { href: string } }) => `](${mark.attrs.href})`,
+      mixable: false,
+    } as never,
+    underline: { open: '<u>', close: '</u>', mixable: true, expelEnclosingWhitespace: true },
+    highlight: { open: '<mark>', close: '</mark>', mixable: true, expelEnclosingWhitespace: true },
+    // transparent passthroughs: these marks carry no Markdown syntax.
+    // Omitting them makes prosemirror-markdown THROW on export (crashes the
+    // host app) — textStyle always accompanies Color, and aiAttribution rides
+    // on AI-written text.
+    textStyle: { open: '', close: '', mixable: true },
+    color: { open: '', close: '', mixable: true },
+    aiAttribution: { open: '', close: '', mixable: true },
+    tesseraPlaceholder: { open: '', close: '', mixable: true },
+    comment: { open: '', close: '', mixable: true },
+  }
+
+  return new MarkdownSerializer(nodes as never, marks as never)
+}
+
+/** Canonical JSON (or doc node) → Markdown. */
+export function docToMarkdown(doc: PMNode | JSONContent, schema: Schema): string {
+  const isNode = typeof (doc as PMNode).nodeSize === 'number' && typeof (doc as PMNode).type === 'object'
+  const realDoc = isNode ? (doc as PMNode) : schema.nodeFromJSON(doc as JSONContent)
+  return createMarkdownSerializer(schema).serialize(realDoc)
+}
+
+/** Markdown → canonical JSON (authoritative format). Requires DOM (browser/jsdom). */
+export function markdownToDoc(markdown: string, schema: Schema): JSONContent {
+  const html = md.render(markdown)
+  const container = document.createElement('div')
+  container.innerHTML = html
+  const parsed = PMDOMParser.fromSchema(schema).parse(container)
+  return parsed.toJSON()
+}
+
+/** Strip volatile/whitespace-irrelevant fields for round-trip comparisons. */
+export function stableJson(json: JSONContent): JSONContent {
+  const clone = JSON.parse(JSON.stringify(json)) as JSONContent
+  const walk = (node: JSONContent) => {
+    if (node.attrs && 'id' in node.attrs) {
+      const { id: _drop, ...rest } = node.attrs
+      if (Object.keys(rest).length === 0) {
+        delete node.attrs
+      } else {
+        node.attrs = rest
+      }
+    }
+    // highlight color: null (default) vs "" (parsed) are equivalent absence
+    node.marks = node.marks?.map(mark => {
+      if (mark.attrs) {
+        const attrs = Object.fromEntries(
+          Object.entries(mark.attrs).filter(([, v]) => v !== null && v !== ''),
+        )
+        return { ...mark, attrs }
+      }
+      return mark
+    })
+    // code blocks: trailing whitespace-only diff is not semantic
+    if (node.type === 'codeBlock' && node.content) {
+      node.content = node.content.map(child =>
+        child.type === 'text' ? { ...child, text: (child.text ?? '').replace(/\s+$/, '') } : child,
+      )
+      node.content = node.content.filter(child => !(child.type === 'text' && child.text === ''))
+    }
+    node.content?.forEach(walk)
+  }
+  walk(clone)
+  return clone
+}

package/src/marks/ai.ts

@@ -0,0 +1,55 @@
+import { Mark, mergeAttributes } from '@tiptap/core'
+
+/**
+ * Attribution mark for AI-written content — the Slite-style "human vs Agent"
+ * provenance signal. Lifecycle:
+ *
+ *   pending: true  → suggestion awaiting Accept / Reject (styled prominently)
+ *   pending: false → accepted AI content (subtle permanent attribution)
+ *
+ * Reject deletes the marked range; Accept flips `pending` and stamps metadata.
+ */
+export interface AiAttributionOptions {
+  HTMLAttributes: Record<string, unknown>
+}
+
+export const AiAttribution = Mark.create<AiAttributionOptions>({
+  name: 'aiAttribution',
+
+  inclusive: false,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+    }
+  },
+
+  addAttributes() {
+    return {
+      pending: {
+        default: true,
+        parseHTML: element => element.getAttribute('data-pending') !== 'false',
+        renderHTML: attributes => ({ 'data-pending': String(attributes.pending) }),
+      },
+      action: {
+        default: null,
+        parseHTML: element => element.getAttribute('data-action'),
+        renderHTML: attributes => (attributes.action ? { 'data-action': String(attributes.action) } : {}),
+      },
+      agent: {
+        default: 'ai',
+        parseHTML: element => element.getAttribute('data-agent') ?? 'ai',
+        renderHTML: attributes => ({ 'data-agent': String(attributes.agent) }),
+      },
+      ts: { default: null },
+    }
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-ai]' }]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['span', mergeAttributes({ 'data-ai': '' }, this.options.HTMLAttributes, HTMLAttributes)]
+  },
+})

package/src/marks/comment.ts

@@ -0,0 +1,137 @@
+import { Mark, Extension, mergeAttributes } from '@tiptap/core'
+import { TextSelection } from '@tiptap/pm/state'
+
+/**
+ * Inline comment mark (v1.1): anchors a comment thread to a text range.
+ * Thread data lives in the injected CommentStore; the mark only carries the
+ * thread id + resolved state so the doc stays host-persistable.
+ */
+export const CommentMark = Mark.create({
+  name: 'comment',
+
+  inclusive: false,
+
+  addAttributes() {
+    return {
+      threadId: {
+        default: null,
+        parseHTML: element => element.getAttribute('data-thread-id'),
+        renderHTML: attributes => ({ 'data-thread-id': String(attributes.threadId ?? '') }),
+      },
+      resolved: {
+        default: false,
+        parseHTML: element => element.getAttribute('data-resolved') === 'true',
+        renderHTML: attributes => ({ 'data-resolved': String(attributes.resolved) }),
+      },
+    }
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-thread-id]' }]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['span', mergeAttributes({ 'data-comment': '' }, HTMLAttributes)]
+  },
+})
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    tesseraComment: {
+      /** Attach a comment thread id to the current selection. */
+      addCommentThread: (threadId: string) => ReturnType
+      /** Flip resolved for every mark of `threadId`. */
+      setCommentResolved: (threadId: string, resolved: boolean) => ReturnType
+      /** Remove all marks of `threadId` (thread deleted). */
+      removeCommentThread: (threadId: string) => ReturnType
+      /** Select the next comment range from the caret (wraps around). */
+      focusNextCommentThread: () => ReturnType
+    }
+  }
+}
+
+/** All comment thread ranges in document order. */
+export function listCommentRanges(state: import('@tiptap/pm/state').EditorState): { threadId: string; from: number; to: number; resolved: boolean }[] {
+  const seen = new Map<string, { threadId: string; from: number; to: number; resolved: boolean }>()
+  state.doc.descendants((node, pos) => {
+    for (const m of node.marks) {
+      if (m.type.name === 'comment' && typeof m.attrs.threadId === 'string') {
+        const from = pos
+        const to = pos + node.nodeSize
+        const existing = seen.get(m.attrs.threadId)
+        if (!existing) {
+          seen.set(m.attrs.threadId, { threadId: m.attrs.threadId, from, to, resolved: Boolean(m.attrs.resolved) })
+        } else {
+          existing.to = Math.max(existing.to, to)
+          existing.resolved = existing.resolved && Boolean(m.attrs.resolved)
+        }
+      }
+    }
+    return true
+  })
+  return [...seen.values()].sort((a, b) => a.from - b.from)
+}
+
+export const CommentCommands = Extension.create({
+  name: 'tesseraCommentCommands',
+
+  addCommands() {
+    return {
+      addCommentThread:
+        (threadId: string) =>
+        ({ commands }) =>
+          commands.setMark('comment', { threadId, resolved: false }),
+      setCommentResolved:
+        (threadId: string, resolved: boolean) =>
+        ({ state, tr, dispatch }) => {
+          let touched = false
+          state.doc.descendants((node, pos) => {
+            node.marks
+              .filter(m => m.type.name === 'comment' && m.attrs.threadId === threadId)
+              .forEach(m => {
+                const next = state.schema.marks.comment!.create({ ...m.attrs, resolved })
+                tr.removeMark(pos, pos + node.nodeSize, m)
+                tr.addMark(pos, pos + node.nodeSize, next)
+                touched = true
+              })
+            return true
+          })
+          if (touched && dispatch) {
+            dispatch(tr)
+          }
+          return touched
+        },
+      removeCommentThread:
+        (threadId: string) =>
+        ({ state, tr, dispatch }) => {
+          let touched = false
+          state.doc.descendants((node, pos) => {
+            if (node.marks.some(m => m.type.name === 'comment' && m.attrs.threadId === threadId)) {
+              tr.removeMark(pos, pos + node.nodeSize, state.schema.marks.comment!)
+              touched = true
+            }
+            return true
+          })
+          if (touched && dispatch) {
+            dispatch(tr)
+          }
+          return touched
+        },
+      focusNextCommentThread:
+        () =>
+        ({ state, tr, dispatch }) => {
+          const ranges = listCommentRanges(state)
+          if (ranges.length === 0) {
+            return false
+          }
+          const anchor = state.selection.from
+          const next = ranges.find(r => r.from > anchor) ?? ranges[0]!
+          if (dispatch) {
+            tr.setSelection(TextSelection.create(state.doc, next.from, next.to))
+            dispatch(tr)
+          }
+          return true
+        },
+    }
+  },
+})

package/src/marks/placeholder.ts

@@ -0,0 +1,63 @@
+import { Mark, mergeAttributes, Extension } from '@tiptap/core'
+
+/**
+ * Placeholder mark (v1.1, Slite's 占位符): dashed-underline token marking a
+ * spot to fill in later — text / person / date / doc-link. ⌘⌥P toggles it on
+ * a selection; slash items insert ready-made tokens.
+ */
+export type PlaceholderKind = 'text' | 'person' | 'date' | 'doc'
+
+export const PlaceholderMark = Mark.create({
+  name: 'tesseraPlaceholder',
+
+  addAttributes() {
+    return {
+      kind: {
+        default: 'text' as PlaceholderKind,
+        parseHTML: element => (element.getAttribute('data-kind') as PlaceholderKind) ?? 'text',
+        renderHTML: attributes => ({ 'data-kind': String(attributes.kind) }),
+      },
+    }
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-type="tessera-placeholder"]' }]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['span', mergeAttributes({ 'data-type': 'tessera-placeholder' }, HTMLAttributes)]
+  },
+})
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    tesseraPlaceholder: {
+      togglePlaceholderMark: (kind?: PlaceholderKind) => ReturnType
+      /** Insert a placeholder token at the caret (selection replaced). */
+      insertPlaceholderToken: (kind: PlaceholderKind, label: string) => ReturnType
+    }
+  }
+}
+
+export const PlaceholderCommands = Extension.create({
+  name: 'tesseraPlaceholderCommands',
+
+  addCommands() {
+    return {
+      togglePlaceholderMark:
+        (kind: PlaceholderKind = 'text') =>
+        ({ commands }) =>
+          commands.toggleMark('tesseraPlaceholder', { kind }),
+      insertPlaceholderToken:
+        (kind: PlaceholderKind, label: string) =>
+        ({ chain }) =>
+          chain()
+            .insertContent({
+              type: 'text',
+              text: label,
+              marks: [{ type: 'tesseraPlaceholder', attrs: { kind } }],
+            })
+            .run(),
+    }
+  },
+})