@miliastry/quasar 1.0.0

package/src/Syntax/RedNodeStore.ts

@@ -0,0 +1,184 @@
+/**
+ * DocumentEngine — RedNodeStore
+ *
+ * Canonical store for RedNodes. Ensures that structurally identical subtrees
+ * share the EXACT SAME RedNode instance in RAM.
+ *
+ * This is the RedNode-level complement to GreenNodePool (which handles
+ * structural sharing at the GreenNode level).
+ *
+ * Architecture:
+ * - Keyed by GreenNode._hash (deterministic structural hash)
+ * - Bottom-up: children are stored first, then parents reference them
+ * - Immutable structural data: once a RedNode is in the store, its `children`
+ *   array and `green` reference never change
+ * - Mutable metadata: the store's RedNode has canonical metadata (derived from
+ *   green.text). Position-specific metadata lives in PositionRef.localOverlay.
+ *
+ * Benefits:
+ * - Memory deduplication: 100 identical blocks = 1 RedNode + 99 lightweight refs
+ * - Render caching: BBCodeCanvas can memoize by canonicalId
+ * - Faster incremental parse: unchanged subtrees keep their RedNode identity
+ * - HTMLRenderer cache: same canonicalId = same HTML (cache hits)
+ */
+
+import { GreenNode } from './GreenNode'
+import { RedNode } from './RedNode'
+import type { NodeKind, NodeMetadata } from '../Types/core'
+
+/**
+ * Derives a node's canonical metadata from its GreenNode.
+ *
+ * Injected rather than hardcoded: metadata extraction is *language* semantics
+ * (what `=#ff0000,#00ff00` means for a `gradient`), and this module sits in the
+ * language-agnostic `Syntax` layer. The BBCode implementation lives in
+ * `BBCode/BBCodeToGreenNode.ts`; pass it via the constructor.
+ */
+export type MetadataExtractor = (green: GreenNode) => NodeMetadata
+
+/** Default for callers with no language semantics to contribute. */
+const NO_METADATA: MetadataExtractor = () => ({})
+
+export class RedNodeStore {
+  private canonicals = new Map<string, RedNode>()
+  private _hits = 0
+  private _misses = 0
+  private _collisions = 0
+  private readonly extractMetadata: MetadataExtractor
+
+  /**
+   * @param extractMetadata  How to derive canonical metadata from a green node.
+   *   Defaults to producing none — the store stays language-agnostic unless a
+   *   caller supplies the mapping.
+   */
+  constructor(extractMetadata: MetadataExtractor = NO_METADATA) {
+    this.extractMetadata = extractMetadata
+  }
+
+  /**
+   * Get or create a canonical RedNode for the given GreenNode.
+   *
+   * The store is keyed by `green._hash` — a 32-bit FNV structural hash — so a
+   * matching key is necessary but NOT sufficient proof of identity. The
+   * canonical pipeline (GreenNodePool interning) guarantees that structurally
+   * identical greens ARE the same object, which is what makes reference
+   * equality a sound discriminator:
+   *
+   * - same hash + same green reference  → HIT, reuse the canonical
+   * - same hash + different green       → COLLISION: a distinct subtree shares
+   *   the 32-bit hash. It is never reused as the registered canonical and never
+   *   overwrites it (that would corrupt every future hit for the registered
+   *   node). The colliding subtree simply loses canonicalization — rebuilt on
+   *   each call. Guarding correctness costs a rare dedup miss; the alternative
+   *   costs a wrong AST.
+   * - no hash entry                     → MISS, create and register
+   *
+   * Invariant preserved: a hash collision can never make one structure be
+   * represented by another structure's RedNode.
+   *
+   * @param green  The GreenNode to wrap
+   * @param metadata  Optional metadata to set (overrides intrinsic metadata)
+   * @param kind  Optional kind override
+   * @returns The canonical RedNode (shared if already exists)
+   */
+  getOrCreate(
+    green: GreenNode,
+    metadata?: NodeMetadata,
+    kind?: NodeKind,
+  ): RedNode {
+    const hash = green._hash.toString()
+    const existing = this.canonicals.get(hash)
+    if (existing) {
+      if (existing.green === green) {
+        this._hits++
+        return existing
+      }
+      // Hash collision: different green, same 32-bit hash. Never reuse the
+      // registered canonical and never overwrite it — build a fresh node and
+      // leave the registered entry untouched.
+      this._collisions++
+      return this.buildCanonical(green, metadata, kind)
+    }
+
+    this._misses++
+    const red = this.buildCanonical(green, metadata, kind)
+    this.canonicals.set(hash, red)
+    return red
+  }
+
+  /**
+   * Build a canonical RedNode for `green` WITHOUT registering it.
+   *
+   * Shared by the miss path (which registers the result) and the collision
+   * path (which must not). Both need the same bottom-up construction:
+   * children are canonicalized first, then the parent references them.
+   */
+  private buildCanonical(
+    green: GreenNode,
+    metadata?: NodeMetadata,
+    kind?: NodeKind,
+  ): RedNode {
+    // First, recursively store children (bottom-up construction)
+    const childRedNodes: RedNode[] = []
+    for (const childGreen of green.children as GreenNode[]) {
+      // Children inherit parent's kind from green, no metadata override
+      childRedNodes.push(this.getOrCreate(childGreen))
+    }
+
+    // Create the RedNode with canonical metadata from green.text
+    const red = new RedNode(green, {
+      kind: kind ?? (green.kind as NodeKind),
+      metadata: metadata ?? this.extractMetadata(green),
+    })
+
+    // Populate children (construction-time, outside the mutation lock)
+    red.initChildren(childRedNodes)
+    return red
+  }
+
+  /**
+   * Look up a canonical RedNode by its structural hash.
+   */
+  getByHash(hash: string): RedNode | undefined {
+    return this.canonicals.get(hash)
+  }
+
+  /**
+   * Check if a GreenNode already has a canonical RedNode.
+   */
+  has(green: GreenNode): boolean {
+    return this.canonicals.has(green._hash.toString())
+  }
+
+  /**
+   * Get the number of unique canonical nodes.
+   */
+  get size(): number {
+    return this.canonicals.size
+  }
+
+  /**
+   * Get store statistics.
+   */
+  get stats() {
+    return {
+      size: this.canonicals.size,
+      hits: this._hits,
+      misses: this._misses,
+      collisions: this._collisions,
+      deduplicationRatio: this._hits > 0
+        ? (this._hits / (this._hits + this._misses) * 100).toFixed(1) + '%'
+        : '0%',
+    }
+  }
+
+  /**
+   * Clear all canonical nodes.
+   */
+  clear(): void {
+    this.canonicals.clear()
+    this._hits = 0
+    this._misses = 0
+    this._collisions = 0
+  }
+}

package/src/Syntax/TreeBuilder.ts

@@ -0,0 +1,214 @@
+/**
+ * DocumentEngine — TreeBuilder
+ *
+ * Converts a TokenStream into a GreenNode tree.
+ * This is the bridge between the Lexer and the Syntax Tree.
+ *
+ * The TreeBuilder is language-agnostic — it uses registry-based
+ * node factories to build the appropriate tree structure.
+ */
+
+import { GreenNode, greenNode, greenLeaf } from './GreenNode'
+import { RedNode } from './RedNode'
+import type { TokenStream, Token } from '../Types/tokens'
+import type { NodeKind } from '../Types/core'
+
+// ─── Build Result ──────────────────────────────────────────────
+
+export interface BuildResult {
+  green: GreenNode
+  red: RedNode
+  tokens: Token[]
+}
+
+// ─── Node Factory Interface ────────────────────────────────────
+
+export interface NodeFactory {
+  /** Create a GreenNode from a token or sequence of tokens */
+  createGreen(tokens: Token[], stream: TokenStream): GreenNode | null
+  /** Create a RedNode from a green node */
+  createRed(green: GreenNode, parent?: RedNode | null): RedNode
+}
+
+// ─── TreeBuilder ───────────────────────────────────────────────
+
+export class TreeBuilder {
+  private factories: Map<string, NodeFactory> = new Map()
+  private defaultKind: NodeKind = 'unknown'
+
+  constructor(defaultKind?: NodeKind) {
+    if (defaultKind) this.defaultKind = defaultKind
+  }
+
+  /**
+   * Register a node factory for a specific token kind or tag name.
+   */
+  register(kind: string, factory: NodeFactory): void {
+    this.factories.set(kind, factory)
+  }
+
+  /**
+   * Build a tree from a token stream.
+   */
+  build(stream: TokenStream): BuildResult {
+    const tokens: Token[] = []
+
+    // Collect all tokens
+    while (!stream.isEof()) {
+      tokens.push(stream.advance())
+    }
+
+    // Build the green tree
+    const green = this.buildGreen(tokens)
+
+    // Build the red tree
+    const red = this.buildRed(green)
+
+    return { green, red, tokens }
+  }
+
+  /**
+   * Build a green tree from a token array.
+   * Uses registered factories to determine node structure.
+   *
+   * By default, creates a flat document structure.
+   * Language-specific builders (like BBCodeParser) override this.
+   */
+  buildGreen(tokens: Token[]): GreenNode {
+    // Default: create a document node with all tokens as direct children
+    const children: GreenNode[] = []
+    let start = tokens.length > 0 ? tokens[0].range.start : 0
+    let end = tokens.length > 0 ? tokens[tokens.length - 1].range.end : 0
+
+    for (const token of tokens) {
+      // Try registered factories
+      let green: GreenNode | null = null
+
+      if (token.name && this.factories.has(token.name)) {
+        green = this.factories.get(token.name)!.createGreen([token], {
+          peek: () => token,
+          advance: () => token,
+          lookAhead: () => token,
+          isEof: () => true,
+          position: () => 0,
+          seek: () => {},
+          remaining: () => [],
+          getAll: () => [token],
+        } as TokenStream)
+      }
+
+      if (!green && this.factories.has(token.kind)) {
+        green = this.factories.get(token.kind)!.createGreen([token], {
+          peek: () => token,
+          advance: () => token,
+          lookAhead: () => token,
+          isEof: () => true,
+          position: () => 0,
+          seek: () => {},
+          remaining: () => [],
+          getAll: () => [token],
+        } as TokenStream)
+      }
+
+      if (!green) {
+        // Default: create a text leaf or tag leaf
+        if (token.kind === 'text' || token.kind === 'newline') {
+          green = greenLeaf('text', token.text)
+        } else if (token.kind === 'open_tag' || token.kind === 'close_tag' || token.kind === 'self_closing_tag') {
+          green = greenLeaf(token.name ? `tag:${token.name}` : 'tag', token.text)
+        } else {
+          green = greenLeaf(token.kind, token.text)
+        }
+      }
+
+      children.push(green)
+    }
+
+    return greenNode('document', '', children)
+  }
+
+  /**
+   * Build a red tree from a green tree.
+   */
+  buildRed(green: GreenNode, parent?: RedNode | null, kind?: NodeKind): RedNode {
+    const red = new RedNode(green, {
+      parent: parent ?? null,
+      kind: kind ?? this.defaultKind,
+    })
+
+    for (const childGreen of green.children as GreenNode[]) {
+      // Determine child kind based on green node kind
+      let childKind: NodeKind = childGreen.kind as NodeKind
+      if (childGreen.kind.startsWith('tag:')) {
+        const tagName = childGreen.kind.slice(4)
+        childKind = this.tagToKind(tagName)
+      }
+
+      const childRed = this.buildRed(childGreen, red, childKind)
+      red.appendChild(childRed)
+    }
+
+    return red
+  }
+
+  /**
+   * Create a RedNode directly from children (for language-specific parsers).
+   */
+  createRedFromChildren(
+    kind: NodeKind,
+    text: string,
+    children: RedNode[],
+    parent?: RedNode | null,
+  ): RedNode {
+    const green = greenNode(kind, text, children.map(c => c.green))
+    const red = new RedNode(green, { parent: parent ?? null, kind })
+    for (const child of children) {
+      child.parent = red
+      red.appendChild(child)
+    }
+    return red
+  }
+
+  // ─── Tag to Kind Mapping ────────────────────────────────
+
+  private tagToKind(tag: string): NodeKind {
+    const map: Record<string, NodeKind> = {
+      'b': 'bold',
+      'i': 'italic',
+      'u': 'underline',
+      's': 'strikethrough',
+      'strike': 'strikethrough',
+      'color': 'color',
+      'size': 'font_size',
+      'font': 'font',
+      'c': 'inline_code',
+      'code': 'code',
+      'spoiler': 'spoiler',
+      'centre': 'center',
+      'right': 'right',
+      'left': 'left',
+      'center': 'center',
+      'url': 'url',
+      'email': 'email',
+      'profile': 'profile',
+      'img': 'image',
+      'youtube': 'video',
+      'audio': 'audio',
+      'imagemap': 'imagemap',
+      'quote': 'quote',
+      'notice': 'notice',
+      'spoilerbox': 'spoilerbox',
+      'box': 'box',
+      'boxw': 'boxw',
+      'list': 'list',
+      '*': 'list_item',
+      'heading': 'heading',
+      'zalgo': 'zalgo',
+      'aesthetic': 'aesthetic',
+      'sparkle': 'sparkle',
+      'bubble': 'bubble',
+      'flower': 'flower',
+    }
+    return map[tag] ?? 'custom'
+  }
+}

package/src/Syntax/__tests__/GreenNode.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest'
+import { greenNode, greenLeaf } from '../GreenNode'
+
+describe('GreenNode', () => {
+  it('creates a green node with correct properties', () => {
+    const leaf1 = greenLeaf('Text', 'hello ')
+    const leaf2 = greenLeaf('Text', 'world')
+    const node = greenNode('Paragraph', '', [leaf1, leaf2])
+
+    expect(node.kind).toBe('Paragraph')
+    expect(node.text).toBe('')
+    expect(node.width).toBe(11)
+    expect(node.childCount).toBe(2)
+    expect(node.isLeaf).toBe(false)
+    
+    expect(leaf1.isLeaf).toBe(true)
+    expect(leaf1.text).toBe('hello ')
+    expect(leaf1.width).toBe(6)
+  })
+
+  it('is immutable', () => {
+    const leaf1 = greenLeaf('Text', 'hello')
+    const leaf2 = greenLeaf('Text', 'world')
+    const input = [leaf1]
+    const node = greenNode('Paragraph', '', input)
+    
+    // Children should be a copy, not the same reference as input
+    expect(node.children).not.toBe(input)
+    // But should contain the same elements
+    expect(node.children.length).toBe(1)
+    expect(node.children[0]).toBe(leaf1)
+  })
+})

package/src/Syntax/__tests__/RedNode.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest'
+import { RedNode } from '../RedNode'
+import { greenNode, greenLeaf } from '../GreenNode'
+
+describe('RedNode', () => {
+  it('creates a red node from a green node', () => {
+    const green = greenLeaf('Text', 'hello')
+    const red = new RedNode(green)
+
+    expect(red.kind).toBe('Text')
+    expect(red.text).toBe('hello')
+    expect(red.version).toBe(1)
+    expect(red.id).toBeDefined()
+    expect(red.parent).toBeNull()
+  })
+
+  it('supports tree navigation', () => {
+    const rootGreen = greenNode('Root', '')
+    const childGreen = greenLeaf('Text', 'hello')
+    
+    const root = new RedNode(rootGreen)
+    const child = new RedNode(childGreen)
+    
+    RedNode.allowMutation(() => {
+      root.appendChild(child)
+    })
+    
+    expect(child.parent).toBe(root)
+    expect(root.childCount).toBe(1)
+    expect(root.childAt(0)).toBe(child)
+    expect(child.root).toBe(root)
+    expect(child.depth).toBe(1)
+    expect(root.depth).toBe(0)
+  })
+
+  it('supports mutation and bumps version', () => {
+    const rootGreen = greenNode('Root', '')
+    const childGreen = greenLeaf('Text', 'hello')
+    
+    const root = new RedNode(rootGreen)
+    const child = new RedNode(childGreen)
+    
+    expect(root.version).toBe(1)
+    
+    RedNode.allowMutation(() => {
+      root.appendChild(child)
+    })
+    expect(root.version).toBe(2)
+    
+    RedNode.allowMutation(() => {
+      root.removeChild(child.id)
+    })
+    expect(root.version).toBe(3)
+    expect(root.childCount).toBe(0)
+    expect(child.parent).toBeNull()
+  })
+
+  it('throws an error if mutation methods are called without an active transaction or lock', () => {
+    const rootGreen = greenNode('Root', '')
+    const childGreen = greenLeaf('Text', 'hello')
+    
+    const root = new RedNode(rootGreen)
+    const child = new RedNode(childGreen)
+    
+    expect(() => {
+      root.appendChild(child)
+    }).toThrow(/mutation boundary/)
+    
+    RedNode.allowMutation(() => {
+      root.appendChild(child)
+    })
+    
+    expect(() => {
+      root.removeChild(child.id)
+    }).toThrow(/mutation boundary/)
+    
+    expect(() => {
+      root.bumpVersion()
+    }).toThrow(/mutation boundary/)
+  })
+})

package/src/Syntax/__tests__/RedNodeStore.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest'
+import { greenLeaf } from '../GreenNode'
+import { RedNodeStore } from '../RedNodeStore'
+
+/**
+ * Forge a deterministic FNV-32 collision for a test green node.
+ *
+ * `GreenNode._hash` is a lazy getter over `_hashCache` (computed once, then
+ * memoized). The store keys purely on `green._hash`, so forcing two
+ * structurally DIFFERENT greens to the same cached hash is a faithful
+ * simulation of a real 32-bit hash collision — the store cannot and should
+ * not distinguish how the collision arose.
+ */
+function forceHash(green: ReturnType<typeof greenLeaf>, hash: number): void {
+  ;(green as unknown as { _hashCache: number })._hashCache = hash
+}
+
+describe('RedNodeStore', () => {
+  it('canonicalizes: same green reference reuses the same RedNode', () => {
+    const store = new RedNodeStore()
+    const green = greenLeaf('Text', 'hello')
+
+    const first = store.getOrCreate(green)
+    const second = store.getOrCreate(green)
+
+    expect(second).toBe(first)
+    expect(store.size).toBe(1)
+    expect(store.stats.hits).toBe(1)
+    expect(store.stats.misses).toBe(1)
+    expect(store.stats.collisions).toBe(0)
+  })
+
+  it('treats a hash collision as neither a hit nor an overwrite', () => {
+    const store = new RedNodeStore()
+
+    // Two genuinely different structures that share a hash.
+    const greenA = greenLeaf('Text', 'alpha')
+    const greenB = greenLeaf('Text', 'bravo')
+    expect(greenA).not.toBe(greenB)
+    expect(greenA.text).not.toBe(greenB.text)
+
+    const COLLISION_HASH = 0xdeadbeef
+    forceHash(greenA, COLLISION_HASH)
+    forceHash(greenB, COLLISION_HASH)
+    expect(greenA._hash).toBe(greenB._hash)
+
+    const canonicalA = store.getOrCreate(greenA)
+    expect(store.stats.misses).toBe(1)
+
+    // The colliding green must NOT be answered with A's canonical...
+    const fromB = store.getOrCreate(greenB)
+    expect(fromB).not.toBe(canonicalA)
+    // ...and the returned node must wrap B, never A.
+    expect(fromB.green).toBe(greenB)
+
+    // The registered entry under the hash is still A — never overwritten.
+    expect(store.getByHash(COLLISION_HASH.toString())).toBe(canonicalA)
+    expect(store.stats.collisions).toBe(1)
+    expect(store.size).toBe(1)
+
+    // A still canonicalizes normally after the collision.
+    expect(store.getOrCreate(greenA)).toBe(canonicalA)
+    expect(store.stats.hits).toBe(1)
+  })
+
+  it('does not register the colliding green (no canonicalization for it)', () => {
+    const store = new RedNodeStore()
+
+    const greenA = greenLeaf('Tag', 'same-hash-a')
+    const greenB = greenLeaf('Tag', 'same-hash-b')
+    forceHash(greenA, 42)
+    forceHash(greenB, 42)
+
+    store.getOrCreate(greenA)
+    const b1 = store.getOrCreate(greenB)
+    const b2 = store.getOrCreate(greenB)
+
+    // v1 semantic: a colliding subtree is rebuilt on each request rather than
+    // risk returning the wrong canonical.
+    expect(b1).not.toBe(b2)
+    expect(b1.green).toBe(greenB)
+    expect(b2.green).toBe(greenB)
+    expect(store.stats.collisions).toBe(2)
+    expect(store.size).toBe(1)
+  })
+
+  it('resets collision stats on clear', () => {
+    const store = new RedNodeStore()
+    const greenA = greenLeaf('Text', 'x')
+    const greenB = greenLeaf('Text', 'y')
+    forceHash(greenA, 7)
+    forceHash(greenB, 7)
+
+    store.getOrCreate(greenA)
+    store.getOrCreate(greenB)
+    expect(store.stats.collisions).toBe(1)
+
+    store.clear()
+    expect(store.size).toBe(0)
+    expect(store.stats.hits).toBe(0)
+    expect(store.stats.misses).toBe(0)
+    expect(store.stats.collisions).toBe(0)
+  })
+})