@miliastry/quasar 1.0.0

package/src/Commands/WrapInTag.ts

@@ -0,0 +1,21 @@
+/**
+ * DocumentEngine — WrapInTag Command
+ *
+ * Wraps the current selection in a BBCode tag.
+ * E.g. selected text → [b]selected text[/b]
+ */
+
+import type { Command, CommandContext, CommandResult } from './Command'
+
+export const WrapInTag: Command = {
+  id: 'wrap-in-tag',
+  label: 'Wrap in Tag',
+  description: 'Wrap the current selection in a BBCode tag',
+
+  execute(ctx: CommandContext): CommandResult {
+    return {
+      success: true,
+      message: 'Wrapped in tag',
+    }
+  },
+}

package/src/Commands/index.ts

@@ -0,0 +1,6 @@
+export { CommandRegistry } from './CommandRegistry'
+export type { Command, CommandContext, CommandResult } from './Command'
+export { InsertText } from './InsertText'
+export { DeleteNode } from './DeleteNode'
+export { WrapInTag } from './WrapInTag'
+export { SplitNode, MergeNode } from './SplitMerge'

package/src/Diff/TreeDiffer.ts

@@ -0,0 +1,264 @@
+/**
+ * DocumentEngine — TreeDiffer
+ *
+ * Computes structural differences between two Red Trees.
+ * Produces a list of DiffOperations that can be used for:
+ * - Updating the UI with minimal DOM changes
+ * - Syncing with collaboration servers
+ * - Animation interpolation
+ * - Undo/redo granularity
+ *
+ * Inspired by React's reconciliation and ProseMirror's diff.
+ */
+
+import { RedNode } from '../Syntax/RedNode'
+
+// ─── Diff Kinds ────────────────────────────────────────────────
+
+export type DiffKind =
+  | 'insert'
+  | 'delete'
+  | 'update'
+  | 'move'
+  | 'preserve'
+
+export interface DiffOperation {
+  kind: DiffKind
+  node: RedNode
+  oldNode?: RedNode
+  /** Index in parent */
+  oldIndex?: number
+  newIndex?: number
+  /** Parent node ID */
+  parentId?: string
+}
+
+export interface DiffResult {
+  operations: DiffOperation[]
+  /** Count by kind */
+  stats: {
+    inserts: number
+    deletes: number
+    updates: number
+    moves: number
+    preserves: number
+  }
+  /** Time taken in ms */
+  duration: number
+}
+
+// ─── TreeDiffer ────────────────────────────────────────────────
+
+export class TreeDiffer {
+  /**
+   * Compute the diff between two Red Trees.
+   */
+  diff(oldRoot: RedNode, newRoot: RedNode): DiffResult {
+    const startTime = performance.now()
+    const operations: DiffOperation[] = []
+    const stats = { inserts: 0, deletes: 0, updates: 0, moves: 0, preserves: 0 }
+
+    this.diffChildren(
+      oldRoot.children,
+      newRoot.children,
+      oldRoot,
+      operations,
+      stats,
+    )
+
+    return {
+      operations,
+      stats,
+      duration: performance.now() - startTime,
+    }
+  }
+
+  private diffChildren(
+    oldChildren: RedNode[],
+    newChildren: RedNode[],
+    parent: RedNode,
+    ops: DiffOperation[],
+    stats: { inserts: number; deletes: number; updates: number; moves: number; preserves: number },
+  ): void {
+    // Build maps for quick lookup
+    const oldMap = new Map<string, RedNode>()
+    const oldIndexMap = new Map<string, number>()
+    oldChildren.forEach((child, i) => {
+      oldMap.set(child.id, child)
+      oldIndexMap.set(child.id, i)
+    })
+
+    const newMap = new Map<string, RedNode>()
+    newChildren.forEach((child, i) => {
+      newMap.set(child.id, child)
+    })
+
+    // Find deleted nodes (in old but not in new)
+    const deletedNodes = new Map<string, RedNode>()
+    for (const [id, node] of oldMap) {
+      if (!newMap.has(id)) {
+        deletedNodes.set(id, node)
+      }
+    }
+
+    const unmatchedNewNodes: { newChild: RedNode, newIdx: number }[] = []
+
+    // Process nodes that kept their ID
+    newChildren.forEach((newChild, newIdx) => {
+      const oldChild = oldMap.get(newChild.id)
+
+      if (!oldChild) {
+        unmatchedNewNodes.push({ newChild, newIdx })
+      } else {
+        const oldIdx = oldIndexMap.get(newChild.id)!
+
+        if (oldIdx !== newIdx) {
+          // Node moved
+          // Check content for update
+          const contentChanged = this.nodeContentChanged(oldChild, newChild)
+          if (contentChanged) {
+            ops.push({
+              kind: 'update',
+              node: newChild,
+              oldNode: oldChild,
+              oldIndex: oldIdx,
+              newIndex: newIdx,
+              parentId: parent.id,
+            })
+            stats.updates++
+          } else {
+            ops.push({
+              kind: 'move',
+              node: newChild,
+              oldNode: oldChild,
+              oldIndex: oldIdx,
+              newIndex: newIdx,
+              parentId: parent.id,
+            })
+            stats.moves++
+          }
+        } else {
+          // Same position, check content
+          const contentChanged = this.nodeContentChanged(oldChild, newChild)
+          if (contentChanged) {
+            ops.push({
+              kind: 'update',
+              node: newChild,
+              oldNode: oldChild,
+              oldIndex: oldIdx,
+              newIndex: newIdx,
+              parentId: parent.id,
+            })
+            stats.updates++
+          } else {
+            ops.push({
+              kind: 'preserve',
+              node: newChild,
+              oldNode: oldChild,
+              oldIndex: oldIdx,
+              newIndex: newIdx,
+              parentId: parent.id,
+            })
+            stats.preserves++
+          }
+
+          // Recurse into children
+          if (oldChild.children.length > 0 || newChild.children.length > 0) {
+            this.diffChildren(oldChild.children, newChild.children, newChild, ops, stats)
+          }
+        }
+      }
+    })
+
+    // Attempt to pair unmatched inserts and deletes based on content
+    const finalDeletes = new Set<string>(deletedNodes.keys())
+    
+    for (const { newChild, newIdx } of unmatchedNewNodes) {
+      let matchedOldNode: RedNode | null = null
+      let matchedOldId: string | null = null
+      
+      for (const [deletedId, deletedNode] of deletedNodes.entries()) {
+        if (finalDeletes.has(deletedId) && this.nodesAreEquivalent(deletedNode, newChild)) {
+          matchedOldNode = deletedNode
+          matchedOldId = deletedId
+          break
+        }
+      }
+      
+      if (matchedOldNode && matchedOldId) {
+        finalDeletes.delete(matchedOldId)
+        const oldIdx = oldIndexMap.get(matchedOldId)!
+        if (oldIdx !== newIdx) {
+          ops.push({
+            kind: 'move',
+            node: newChild,
+            oldNode: matchedOldNode,
+            oldIndex: oldIdx,
+            newIndex: newIdx,
+            parentId: parent.id,
+          })
+          stats.moves++
+        } else {
+          ops.push({
+            kind: 'update', // Treat as update since ID changed
+            node: newChild,
+            oldNode: matchedOldNode,
+            oldIndex: oldIdx,
+            newIndex: newIdx,
+            parentId: parent.id,
+          })
+          stats.updates++
+        }
+        
+        // Recurse into children (though they are equivalent, we might need to emit preserves)
+        if (matchedOldNode.children.length > 0 || newChild.children.length > 0) {
+          this.diffChildren(matchedOldNode.children, newChild.children, newChild, ops, stats)
+        }
+      } else {
+        ops.push({
+          kind: 'insert',
+          node: newChild,
+          newIndex: newIdx,
+          parentId: parent.id,
+        })
+        stats.inserts++
+      }
+    }
+
+    // Unmatched deletes remain deletes
+    for (const deletedId of finalDeletes) {
+      ops.push({
+        kind: 'delete',
+        node: deletedNodes.get(deletedId)!,
+        oldIndex: oldIndexMap.get(deletedId),
+        parentId: parent.id,
+      })
+      stats.deletes++
+    }
+  }
+
+  /**
+   * Check if a node's content has changed.
+   */
+  private nodeContentChanged(oldNode: RedNode, newNode: RedNode): boolean {
+    if (oldNode.kind !== newNode.kind) return true
+    if (oldNode.text !== newNode.text) return true
+    if (oldNode.children.length !== newNode.children.length) return true
+    return false
+  }
+
+  /**
+   * Deep equality check for content equivalence when pairing unmatched nodes.
+   */
+  private nodesAreEquivalent(oldNode: RedNode, newNode: RedNode): boolean {
+    if (oldNode.kind !== newNode.kind) return false
+    if (oldNode.text !== newNode.text) return false
+    if (oldNode.children.length !== newNode.children.length) return false
+    for (let i = 0; i < oldNode.children.length; i++) {
+      if (!this.nodesAreEquivalent(oldNode.children[i], newNode.children[i])) {
+        return false
+      }
+    }
+    return true
+  }
+}

package/src/Diff/__tests__/TreeDiffer.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest'
+import { TreeDiffer } from '../TreeDiffer'
+import { RedNode } from '../../Syntax/RedNode'
+import { GreenNode } from '../../Syntax/GreenNode'
+import type { NodeId } from '../../Types/core'
+
+/** Fixed, readable NodeIds. `NodeId` is branded, so literals need the cast. */
+const nid = (s: string) => s as unknown as NodeId
+
+describe('TreeDiffer', () => {
+  it('should detect moves/updates by content when IDs differ', () => {
+    // Create old tree
+    const oldChild = new RedNode(new GreenNode('paragraph', 'hello', [], 0, 0, 5), { id: nid('old-id'), kind: 'paragraph' })
+    const oldRoot = new RedNode(new GreenNode('document', '', [], 0, 0, 5), { id: nid('root'), kind: 'document' })
+    oldRoot.children.push(oldChild)
+    oldChild.parent = oldRoot
+
+    // Create new tree with different ID but same content
+    const newChild = new RedNode(new GreenNode('paragraph', 'hello', [], 0, 0, 5), { id: nid('new-id'), kind: 'paragraph' })
+    const newRoot = new RedNode(new GreenNode('document', '', [], 0, 0, 5), { id: nid('root'), kind: 'document' })
+    newRoot.children.push(newChild)
+    newChild.parent = newRoot
+
+    const differ = new TreeDiffer()
+    const result = differ.diff(oldRoot, newRoot)
+
+    // Should detect as 1 preserve/update since index is same, not a delete and insert
+    // Because the position didn't change it's treated as update when IDs change but content is same.
+    expect(result.stats.inserts).toBe(0)
+    expect(result.stats.deletes).toBe(0)
+    expect(result.stats.updates).toBe(1)
+    
+    expect(result.operations[0].kind).toBe('update')
+    expect(result.operations[0].node.id).toBe(nid('new-id'))
+    expect(result.operations[0].oldNode?.id).toBe(nid('old-id'))
+  })
+
+  it('should detect moves when content matches and index changes', () => {
+    const oldChild1 = new RedNode(new GreenNode('paragraph', 'a', [], 0, 0, 1), { id: nid('id1'), kind: 'paragraph' })
+    const oldChild2 = new RedNode(new GreenNode('paragraph', 'b', [], 0, 0, 1), { id: nid('id2'), kind: 'paragraph' })
+    const oldRoot = new RedNode(new GreenNode('document', '', [], 0, 0, 2), { id: nid('root'), kind: 'document' })
+    oldRoot.children.push(oldChild1, oldChild2)
+    oldChild1.parent = oldRoot
+    oldChild2.parent = oldRoot
+
+    const newChild1 = new RedNode(new GreenNode('paragraph', 'a', [], 0, 0, 1), { id: nid('id1'), kind: 'paragraph' }) // same id
+    const newChild2 = new RedNode(new GreenNode('paragraph', 'b', [], 0, 0, 1), { id: nid('id3'), kind: 'paragraph' }) // different id, same content
+    const newRoot = new RedNode(new GreenNode('document', '', [], 0, 0, 2), { id: nid('root'), kind: 'document' })
+    // Swap order to trigger move
+    newRoot.children.push(newChild2, newChild1)
+    newChild1.parent = newRoot
+    newChild2.parent = newRoot
+
+    const differ = new TreeDiffer()
+    const result = differ.diff(oldRoot, newRoot)
+
+    // id2 moved to index 0 (and changed id to id3), id1 moved to index 1
+    expect(result.stats.inserts).toBe(0)
+    expect(result.stats.deletes).toBe(0)
+    
+    // We should have ops for moves/updates
+    const hasMoveOrUpdateId3 = result.operations.some(op => op.node.id === nid('id3') && (op.kind === 'move' || op.kind === 'update'))
+    expect(hasMoveOrUpdateId3).toBe(true)
+  })
+})

package/src/Diff/index.ts

@@ -0,0 +1,2 @@
+export { TreeDiffer } from './TreeDiffer'
+export type { DiffOperation, DiffKind, DiffResult } from './TreeDiffer'

package/src/Events/EventBus.ts

@@ -0,0 +1,160 @@
+/**
+ * DocumentEngine — EventBus
+ *
+ * Publish/subscribe event system for document changes.
+ * Each DocumentModel has its own EventBus instance.
+ *
+ * Events include:
+ * - document_changed (rebuild, edit, undo/redo)
+ * - node_changed (insert, delete, update, move)
+ * - diagnostic_updated
+ * - transaction_applied
+ * - cursor_moved
+ * - selection_changed
+ */
+
+import type { DocumentChangeKind, NodeId } from '../Types/core'
+import type { Operation } from '../Types/operations'
+import type { NodeMatch } from '../Syntax/NodeMatcher'
+import type { TextChange } from '../Incremental/ChangeTracker'
+
+export type DocumentEventType =
+  | 'document_changed'
+  | 'node_inserted'
+  | 'node_deleted'
+  | 'node_updated'
+  | 'diagnostics_updated'
+  | 'transaction_applied'
+  | 'undo_performed'
+  | 'redo_performed'
+  | 'cursor_moved'
+  | 'selection_changed'
+
+export interface DocumentEvent {
+  type: DocumentEventType
+  kind?: DocumentChangeKind
+  version?: number
+  source?: string
+  nodeId?: NodeId
+  nodeMatch?: NodeMatch | null
+  change?: TextChange
+  operations?: Operation[]
+  /**
+   * Where the change came from: `'local'` for user editing, anything else for
+   * programmatic/synced sources. Lets a collaboration layer ignore the echo
+   * of changes it applied itself. Absent on events with no single cause.
+   */
+  origin?: string
+  timestamp: number
+  [key: string]: unknown
+}
+
+export type DocumentEventHandler = (event: DocumentEvent) => void
+
+export class DocumentEventBus {
+  private listeners: Map<DocumentEventType, Set<DocumentEventHandler>> = new Map()
+  private history: DocumentEvent[] = []
+  private maxHistory: number = 50
+
+  /**
+   * Record emitted events so `getHistory()` returns them. Off by default:
+   * nothing reads the history today, and a retained event pins its `source`
+   * string — and, through the lazy `nodeMatch` accessor, the entire previous
+   * red/green tree — so an always-on history held megabytes per document
+   * for nobody. Turn it on for debugging or replay tooling.
+   */
+  recordHistory: boolean = false
+
+  /**
+   * Subscribe to an event type.
+   */
+  on(type: DocumentEventType, handler: DocumentEventHandler): () => void {
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, new Set())
+    }
+    this.listeners.get(type)!.add(handler)
+
+    // Return unsubscribe function
+    return () => {
+      this.listeners.get(type)?.delete(handler)
+    }
+  }
+
+  /**
+   * Whether any handler is subscribed to `type` (or to anything, if omitted).
+   *
+   * Emitters use this to skip building event payloads nobody will see — the
+   * common case, since a headless model has no subscribers at all.
+   */
+  hasListeners(type?: DocumentEventType): boolean {
+    if (type !== undefined) {
+      return (this.listeners.get(type)?.size ?? 0) > 0
+    }
+    for (const handlers of this.listeners.values()) {
+      if (handlers.size > 0) return true
+    }
+    return false
+  }
+
+  /**
+   * Subscribe to all events.
+   */
+  onAny(handler: DocumentEventHandler): () => void {
+    const unsubscribers: (() => void)[] = []
+    const types: DocumentEventType[] = [
+      'document_changed', 'node_inserted', 'node_deleted', 'node_updated',
+      'diagnostics_updated', 'transaction_applied', 'undo_performed', 'redo_performed',
+      'cursor_moved', 'selection_changed',
+    ]
+    for (const type of types) {
+      unsubscribers.push(this.on(type, handler))
+    }
+    return () => unsubscribers.forEach(u => u())
+  }
+
+  /**
+   * Emit an event.
+   */
+  emit(event: DocumentEvent): void {
+    const handlers = this.listeners.get(event.type)
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(event)
+        } catch (error) {
+          console.warn(`[EventBus] Handler error for ${event.type}:`, error)
+        }
+      }
+    }
+
+    // Store in history — only when someone opted in (see `recordHistory`).
+    if (this.recordHistory) {
+      this.history.push(event)
+      if (this.history.length > this.maxHistory) {
+        this.history.shift()
+      }
+    }
+  }
+
+  /**
+   * Remove a specific handler.
+   */
+  off(type: DocumentEventType, handler: DocumentEventHandler): void {
+    this.listeners.get(type)?.delete(handler)
+  }
+
+  /**
+   * Get event history.
+   */
+  getHistory(): DocumentEvent[] {
+    return [...this.history]
+  }
+
+  /**
+   * Clear all listeners and history.
+   */
+  clear(): void {
+    this.listeners.clear()
+    this.history = []
+  }
+}

package/src/Events/index.ts

@@ -0,0 +1,2 @@
+export { DocumentEventBus } from './EventBus'
+export type { DocumentEvent, DocumentEventType, DocumentEventHandler } from './EventBus'

package/src/Formatter/Formatter.ts

@@ -0,0 +1,54 @@
+/**
+ * DocumentEngine — Formatter
+ *
+ * Formats the document tree into "pretty" BBCode.
+ * Normalizes indentation, spacing, and whitespace.
+ *
+ * Uses the TagRegistry and Visitor pattern.
+ * Plugins can register custom formatters for custom tags.
+ */
+
+import { RedNode } from '../Syntax/RedNode'
+import { BBCodeExporter } from '../Visitors/BBCodeExporter'
+import type { TagRegistry } from '../Model/TagRegistry'
+
+export interface FormatOptions {
+  /** Whether to add newlines between block elements */
+  blockNewlines?: boolean
+  /** Whether to normalize whitespace inside inline elements */
+  normalizeInlineWhitespace?: boolean
+  /** Maximum line width (0 = no limit) */
+  maxLineWidth?: number
+  /** Whether to collapse consecutive empty lines */
+  collapseEmptyLines?: boolean
+  /** Indentation string */
+  indent?: string
+}
+
+export class Formatter {
+  /**
+   * Format a RedNode tree (extracts text while preserving exact layout/spacing).
+   */
+  format(root: RedNode): string {
+    return this.formatNode(root)
+  }
+
+  /**
+   * Format a single node at a given depth.
+   */
+  private formatNode(node: RedNode): string {
+    if (node.kind === 'text') {
+      return node.text
+    }
+
+    if (node.kind === 'spacing' || node.kind === 'empty_line') {
+      return '\n'
+    }
+
+    if (node.children) {
+      return node.children.map(c => this.formatNode(c)).join('')
+    }
+
+    return ''
+  }
+}

package/src/Formatter/index.ts

@@ -0,0 +1,2 @@
+export { Formatter } from './Formatter'
+export type { FormatOptions } from './Formatter'

package/src/HTML/HTMLDocumentModel.ts

@@ -0,0 +1,35 @@
+import { DocumentModel, type DocumentModelOptions } from '../Model/DocumentModel';
+import { GreenNode, greenLeaf } from '../Syntax/GreenNode';
+import { RedNode } from '../Syntax/RedNode';
+import { htmlStringToGreenTree, greenToRedNode } from './HTMLToGreenNode';
+
+export interface HTMLDocumentModelOptions extends DocumentModelOptions {
+  source?: string;
+  language?: string;
+}
+
+export class HTMLDocumentModel extends DocumentModel {
+  constructor(options: HTMLDocumentModelOptions = {}) {
+    super({ source: '', language: options.language ?? 'html' });
+    if (options.source) {
+      this.rebuild(options.source);
+    }
+  }
+
+  static fromHTML(source: string): HTMLDocumentModel {
+    return new HTMLDocumentModel({ source });
+  }
+
+  protected parseToGreen(source: string): GreenNode {
+    try {
+      return htmlStringToGreenTree(source);
+    } catch (error) {
+      console.warn('[HTMLDocumentModel] Parse error:', error);
+      return greenLeaf('text', source);
+    }
+  }
+
+  protected buildRedFromGreen(green: GreenNode): RedNode {
+    return greenToRedNode(green);
+  }
+}