@miliastry/quasar 1.0.0

package/src/Plugins/PluginAPI.ts

@@ -0,0 +1,119 @@
+/**
+ * DocumentEngine — PluginAPI
+ *
+ * The public API exposed to plugins.
+ * Plugin authors use this to register tags, commands, validators, etc.
+ *
+ * Inspired by VSCode's `vscode` module.
+ */
+
+import { DocumentModel } from '../Model/DocumentModel'
+import { TagRegistry, type TagDefinition } from '../Model/TagRegistry'
+import { CommandRegistry, type Command } from '../Commands'
+import { SemanticAnalyzer, type Validator } from '../Semantic/SemanticAnalyzer'
+import { Linter, type LintRule } from '../Linter/Linter'
+import { RenderPipeline, type RenderHook } from '../RenderPipeline/RenderPipeline'
+import { PluginRegistry, type PluginManifest, type PluginContribution } from './PluginRegistry'
+
+export class PluginAPI {
+  readonly model: DocumentModel
+  readonly tags: TagRegistry
+  readonly commands: CommandRegistry
+  readonly semantic: SemanticAnalyzer
+  readonly linter: Linter
+  readonly renderer: RenderPipeline
+  readonly plugins: PluginRegistry
+
+  constructor(model: DocumentModel) {
+    this.model = model
+    this.tags = model.tagRegistry
+    this.commands = new CommandRegistry()
+    this.semantic = model.semanticAnalyzer
+    this.linter = new Linter()
+    this.renderer = new RenderPipeline()
+    this.plugins = new PluginRegistry()
+  }
+
+  /**
+   * Register a plugin with all its contributions.
+   *
+   * Example:
+   * ```ts
+   * api.registerPlugin({
+   *   name: 'my-plugin',
+   *   version: '1.0.0'
+   * }, {
+   *   tags: [{ name: 'blur', kind: 'custom', ... }],
+   *   commands: [{ id: 'my-command', ... }]
+   * })
+   * ```
+   */
+  registerPlugin(manifest: PluginManifest, contributions: PluginContribution): void {
+    const plugin = this.plugins.register(manifest, contributions)
+
+    // Apply contributions
+    if (contributions.tags) {
+      for (const tag of contributions.tags) {
+        this.tags.register(tag)
+      }
+    }
+
+    if (contributions.commands) {
+      for (const cmd of contributions.commands) {
+        this.commands.register(cmd)
+      }
+    }
+
+    if (contributions.validators) {
+      for (const v of contributions.validators) {
+        this.semantic.register(v)
+      }
+    }
+
+    if (contributions.lintRules) {
+      for (const rule of contributions.lintRules) {
+        this.linter.register(rule)
+      }
+    }
+
+    if (contributions.renderHooks) {
+      for (const hook of contributions.renderHooks) {
+        this.renderer.register(hook)
+      }
+    }
+
+    // Activate
+    this.plugins.activate(plugin)
+  }
+
+  /**
+   * Unregister a plugin and remove its contributions.
+   */
+  unregisterPlugin(name: string): void {
+    const plugin = this.plugins.get(name)
+    if (!plugin) return
+
+    if (plugin.contributions.tags) {
+      for (const tag of plugin.contributions.tags) {
+        this.tags.unregister(tag.name)
+      }
+    }
+    if (plugin.contributions.commands) {
+      for (const cmd of plugin.contributions.commands) {
+        this.commands.unregister(cmd.id)
+      }
+    }
+    if (plugin.contributions.validators) {
+      for (const v of plugin.contributions.validators) {
+        this.semantic.unregister(v.code)
+      }
+    }
+    if (plugin.contributions.lintRules) {
+      for (const rule of plugin.contributions.lintRules) {
+        this.linter.unregister(rule.code)
+      }
+    }
+
+    this.plugins.unregister(name)
+  }
+}

package/src/Plugins/PluginRegistry.ts

@@ -0,0 +1,132 @@
+/**
+ * DocumentEngine — PluginRegistry
+ *
+ * Manages the lifecycle of plugins/extensions.
+ * Each plugin registers contributions (tags, commands, validators, etc.)
+ * and can be loaded/unloaded at runtime.
+ *
+ * Inspired by VSCode's extension system.
+ */
+
+import type { TagDefinition } from '../Model/TagRegistry'
+import type { Command } from '../Commands/Command'
+import type { Validator } from '../Semantic/SemanticAnalyzer'
+import type { LintRule } from '../Linter/Linter'
+import type { RenderHook } from '../RenderPipeline/RenderPipeline'
+
+export interface PluginManifest {
+  name: string
+  version: string
+  description?: string
+  author?: string
+  /** Dependencies on other plugins */
+  dependencies?: string[]
+}
+
+export interface PluginContribution {
+  /** Tags to register */
+  tags?: TagDefinition[]
+  /** Commands to register */
+  commands?: Command[]
+  /** Semantic validators */
+  validators?: Validator[]
+  /** Lint rules */
+  lintRules?: LintRule[]
+  /** Render hooks */
+  renderHooks?: RenderHook[]
+  /** CSS to inject */
+  styles?: string[]
+  /** Initialization function */
+  activate?: () => void | Promise<void>
+  /** Cleanup function */
+  deactivate?: () => void
+}
+
+export interface Plugin {
+  manifest: PluginManifest
+  contributions: PluginContribution
+  /** Whether the plugin is currently active */
+  active: boolean
+}
+
+export class PluginRegistry {
+  private plugins: Map<string, Plugin> = new Map()
+
+  /**
+   * Register a plugin.
+   */
+  register(manifest: PluginManifest, contributions: PluginContribution): Plugin {
+    const plugin: Plugin = { manifest, contributions, active: false }
+    this.plugins.set(manifest.name, plugin)
+    return plugin
+  }
+
+  /**
+   * Unregister and deactivate a plugin.
+   */
+  unregister(name: string): boolean {
+    const plugin = this.plugins.get(name)
+    if (!plugin) return false
+    this.deactivate(plugin)
+    this.plugins.delete(name)
+    return true
+  }
+
+  /**
+   * Get a plugin by name.
+   */
+  get(name: string): Plugin | undefined {
+    return this.plugins.get(name)
+  }
+
+  /**
+   * Get all registered plugins.
+   */
+  getAll(): Plugin[] {
+    return Array.from(this.plugins.values())
+  }
+
+  /**
+   * Activate a plugin (calls activate function).
+   */
+  activate(plugin: Plugin): void {
+    if (plugin.active) return
+    try {
+      plugin.contributions.activate?.()
+      plugin.active = true
+    } catch (error) {
+      console.warn(`[PluginRegistry] Failed to activate plugin "${plugin.manifest.name}":`, error)
+    }
+  }
+
+  /**
+   * Deactivate a plugin (calls deactivate function).
+   */
+  deactivate(plugin: Plugin): void {
+    if (!plugin.active) return
+    try {
+      plugin.contributions.deactivate?.()
+      plugin.active = false
+    } catch (error) {
+      console.warn(`[PluginRegistry] Failed to deactivate plugin "${plugin.manifest.name}":`, error)
+    }
+  }
+
+  /**
+   * Activate all registered plugins.
+   */
+  activateAll(): void {
+    for (const [, plugin] of this.plugins) {
+      this.activate(plugin)
+    }
+  }
+
+  /**
+   * Deactivate all plugins.
+   */
+  deactivateAll(): void {
+    for (const [, plugin] of this.plugins) {
+      this.deactivate(plugin)
+    }
+  }
+}

package/src/Plugins/index.ts

@@ -0,0 +1,3 @@
+export { PluginAPI } from './PluginAPI'
+export { PluginRegistry } from './PluginRegistry'
+export type { Plugin, PluginManifest, PluginContribution } from './PluginRegistry'

package/src/Queries/QueryEngine.ts

@@ -0,0 +1,152 @@
+/**
+ * DocumentEngine — QueryEngine
+ *
+ * CSS-inspired query engine for the document tree.
+ * Enables queries like:
+ *   query('paragraph > bold')
+ *   query('quote text')
+ *   query('[color]')
+ *   query('list > *')
+ *
+ * Useful for:
+ * - Finding nodes by structure
+ * - AI context gathering
+ * - Plugin discovery
+ * - Lint rule targeting
+ */
+
+import { RedNode } from '../Syntax/RedNode'
+import type { Query, QueryStep, QuerySelector, QueryMatch, QueryResult } from '../Types/queries'
+
+export class QueryEngine {
+  /**
+   * Execute a query against a RedNode tree.
+   */
+  execute(query: Query, root: RedNode): QueryResult {
+    const startTime = performance.now()
+    const matches: QueryMatch[] = []
+
+    // Start from root, apply each step
+    let candidates: RedNode[] = [root]
+
+    for (const step of query.steps) {
+      if (candidates.length === 0) break
+
+      if (step.combinator === 'root') {
+        // First step: match against root
+        candidates = this.matchStep(step, candidates)
+      } else if (step.combinator === 'descendant') {
+        // Space: any descendant
+        const allDescendants: RedNode[] = []
+        for (const c of candidates) {
+          c.walk(node => {
+            if (node !== c) allDescendants.push(node)
+          })
+        }
+        candidates = this.matchStep(step, allDescendants)
+      } else if (step.combinator === 'child') {
+        // > direct child
+        const children: RedNode[] = []
+        for (const c of candidates) {
+          children.push(...c.children)
+        }
+        candidates = this.matchStep(step, children)
+      } else if (step.combinator === 'adjacent') {
+        // + next sibling
+        const nextSiblings: RedNode[] = []
+        for (const c of candidates) {
+          const next = c.nextSibling
+          if (next) nextSiblings.push(next)
+        }
+        candidates = this.matchStep(step, nextSiblings)
+      } else if (step.combinator === 'sibling') {
+        // ~ any sibling
+        const siblings: RedNode[] = []
+        for (const c of candidates) {
+          if (c.parent) {
+            siblings.push(...c.parent.children.filter(s => s.id !== c.id))
+          }
+        }
+        candidates = this.matchStep(step, siblings)
+      }
+    }
+
+    for (const node of candidates) {
+      matches.push({
+        node,
+        score: 1,
+        matchedSelectors: [],
+      })
+    }
+
+    return {
+      matches,
+      total: matches.length,
+      time: performance.now() - startTime,
+    }
+  }
+
+  /**
+   * Filter candidates by applying a query step's selectors.
+   */
+  private matchStep(step: QueryStep, candidates: RedNode[]): RedNode[] {
+    return candidates.filter(node =>
+      step.selector.every(sel => this.matchesSelector(node, sel))
+    )
+  }
+
+  /**
+   * Check if a single node matches a single selector.
+   */
+  private matchesSelector(node: RedNode, selector: QuerySelector): boolean {
+    switch (selector.type) {
+      case 'kind':
+        return node.kind === selector.kind
+      case 'tag': {
+        const tagName = node.metadata?.tagName as string | undefined
+        return tagName === selector.tag || node.kind === selector.tag
+      }
+      case 'attribute': {
+        const val = node.metadata?.[selector.name]
+        if (selector.value !== undefined) {
+          return String(val) === selector.value
+        }
+        return val !== undefined && val !== null
+      }
+      case 'has_attribute':
+        return node.metadata?.[selector.name] !== undefined
+      case 'text': {
+        const text = node.text || ''
+        return text.includes(selector.pattern)
+      }
+      case 'has_child':
+        return node.children.some(c => this.matchesSelector(c, selector.selector))
+      case 'has_descendant': {
+        let found = false
+        node.walk(c => {
+          if (c !== node && this.matchesSelector(c, selector.selector)) {
+            found = true
+            return 'skip'
+          }
+        })
+        return found
+      }
+      case 'first_child':
+        return node.index === 0
+      case 'last_child':
+        return node.parent ? node.index === node.parent.children.length - 1 : false
+      case 'nth_child':
+        return node.index === selector.n - 1
+      case 'position':
+        if (selector.min !== undefined && node.index < selector.min) return false
+        if (selector.max !== undefined && node.index > selector.max) return false
+        return true
+      case 'depth':
+        if (selector.min !== undefined && node.depth < selector.min) return false
+        if (selector.max !== undefined && node.depth > selector.max) return false
+        return true
+      default:
+        return false
+    }
+  }
+}

package/src/Queries/index.ts

@@ -0,0 +1 @@
+export { QueryEngine } from './QueryEngine'

package/src/RenderPipeline/RenderPipeline.ts

@@ -0,0 +1,125 @@
+/**
+ * DocumentEngine — RenderPipeline
+ *
+ * The Render Pipeline transforms a DocumentModel into renderable output.
+ * It sits between the model and the view layer.
+ *
+ * The pipeline is:
+ *   DocumentModel → RenderTree → HTML/SVG/Canvas/React
+ *
+ * Plugins can intercept at any stage:
+ * - Add/transform render nodes
+ * - Provide custom renderers for custom tags
+ * - Post-process the output
+ */
+
+import { RedNode } from '../Syntax/RedNode'
+import { RenderTree, type RenderNode, type RenderVariant } from './RenderTree'
+import type { TagRegistry, TagHandlerContext } from '../Model/TagRegistry'
+
+export type RenderPhase =
+  | 'build'      // DocumentModel → RenderNode tree
+  | 'transform'  // Plugin transforms
+  | 'serialize'  // RenderNode → Output string
+
+export interface RenderHook {
+  phase: RenderPhase
+  hook: (node: RenderNode, context: RenderContext) => RenderNode | null
+}
+
+export interface RenderContext {
+  variant: RenderVariant
+  registry: TagRegistry
+  source: string
+}
+
+export class RenderPipeline {
+  private hooks: RenderHook[] = []
+
+  /**
+   * Register a render hook.
+   */
+  register(hook: RenderHook): void {
+    this.hooks.push(hook)
+  }
+
+  /**
+   * Unregister a render hook.
+   */
+  unregister(hook: RenderHook): void {
+    const idx = this.hooks.indexOf(hook)
+    if (idx >= 0) this.hooks.splice(idx, 1)
+  }
+
+  /**
+   * Render a RedNode tree to a string.
+   */
+  render(
+    root: RedNode,
+    variant: RenderVariant = 'html',
+    registry: TagRegistry,
+    source: string = '',
+  ): string {
+    const context: RenderContext = { variant, registry, source }
+
+    // Phase 1: Build render tree
+    let renderTree = this.buildRenderTree(root, context)
+
+    // Phase 2: Apply transformations
+    for (const hook of this.hooks) {
+      if (hook.phase === 'transform') {
+        renderTree = hook.hook(renderTree, context) ?? renderTree
+      }
+    }
+
+    // Phase 3: Serialize
+    for (const hook of this.hooks) {
+      if (hook.phase === 'serialize') {
+        const result = hook.hook(renderTree, context)
+        if (result) return result.text
+      }
+    }
+
+    // Default serialization
+    return RenderTree.toHTML(renderTree)
+  }
+
+  /**
+   * Build a RenderNode tree from a RedNode tree.
+   */
+  private buildRenderTree(node: RedNode, context: RenderContext): RenderNode {
+    // Text nodes
+    if (node.kind === 'text') {
+      return RenderTree.text(node.text)
+    }
+
+    // Document root
+    if (node.kind === 'document') {
+      const children = node.children.map(c => this.buildRenderTree(c, context))
+      return RenderTree.container('document', children)
+    }
+
+    // Check tag registry for custom render handlers
+    const tagDef = context.registry.getByKind(node.kind)
+    if (tagDef?.toRenderNode) {
+      return tagDef.toRenderNode({
+        node,
+        source: context.source,
+        visitChildren: (n) => {
+          const r = this.buildRenderTree(n, context)
+          return RenderTree.toHTML(r)
+        },
+        renderChild: (n) => this.buildRenderTree(n, context),
+      })
+    }
+
+    // Default rendering
+    const children = node.children.map(c => this.buildRenderTree(c, context))
+    const kind = node.kind
+
+    return RenderTree.container(kind, children, {
+      tag: node.metadata?.tagName,
+      ...node.metadata,
+    })
+  }
+}

package/src/RenderPipeline/RenderTree.ts

@@ -0,0 +1,134 @@
+/**
+ * DocumentEngine — RenderTree
+ *
+ * An intermediate representation between DocumentModel and final output.
+ * The RenderTree is what the RenderPipeline processes.
+ *
+ * This abstraction allows:
+ * - Same DocumentModel → multiple render outputs (HTML, Canvas, SVG, PDF)
+ * - Plugin renderers that intercept/modify render nodes
+ * - Smooth visual transitions between document states
+ * - Partial rendering for performance
+ */
+
+import type { NodeKind, NodeAttributes } from '../Types/core'
+
+export type RenderVariant = 'html' | 'canvas' | 'svg' | 'pdf' | 'react' | 'text'
+
+export interface RenderNode {
+  /** Semantic kind */
+  kind: NodeKind | string
+  /** Text content */
+  text: string
+  /** Child render nodes */
+  children: RenderNode[]
+  /** Props/attributes for the renderer */
+  props: Record<string, unknown>
+  /** Which render variant this node targets */
+  variant?: RenderVariant
+  /** CSS class names */
+  className?: string
+  /** Inline styles */
+  style?: Record<string, string | number>
+  /** Events/handlers (for interactive renders) */
+  events?: Record<string, string>
+  /** Metadata for renderers */
+  metadata?: Record<string, unknown>
+}
+
+export class RenderTree {
+  /**
+   * Create a render tree from a document node.
+   */
+  static fromNode(
+    kind: NodeKind | string,
+    text: string = '',
+    children: RenderNode[] = [],
+    props: Record<string, unknown> = {},
+  ): RenderNode {
+    return { kind, text, children, props }
+  }
+
+  /**
+   * Create a text render node.
+   */
+  static text(content: string): RenderNode {
+    return { kind: 'text', text: content, children: [], props: {} }
+  }
+
+  /**
+   * Create a container render node.
+   */
+  static container(
+    kind: NodeKind | string,
+    children: RenderNode[],
+    props: Record<string, unknown> = {},
+  ): RenderNode {
+    return { kind, text: '', children, props }
+  }
+
+  /**
+   * Serialize a render tree to HTML.
+   */
+  static toHTML(node: RenderNode): string {
+    if (node.kind === 'text') return this.escapeHtml(node.text)
+
+    const tag = this.kindToTag(node.kind)
+    const propsStr = this.propsToHtml(node)
+    const childrenStr = node.children.map(c => this.toHTML(c)).join('')
+
+    if (tag) {
+      return `<${tag}${propsStr}>${childrenStr}</${tag}>`
+    }
+
+    return childrenStr
+  }
+
+  private static kindToTag(kind: string): string | null {
+    const map: Record<string, string> = {
+      bold: 'strong',
+      italic: 'em',
+      underline: 'u',
+      strikethrough: 's',
+      inline_code: 'code',
+      code: 'pre',
+      heading: 'h2',
+      paragraph: 'p',
+      list: 'ul',
+      list_item: 'li',
+      quote: 'blockquote',
+      center: 'div',
+      notice: 'div',
+      image: 'img',
+      video: 'iframe',
+      audio: 'audio',
+      spoiler: 'span',
+      url: 'a',
+      email: 'a',
+      profile: 'a',
+      document: 'div',
+      group: 'div',
+      text: 'span',
+    }
+    return map[kind] ?? 'span'
+  }
+
+  private static propsToHtml(node: RenderNode): string {
+    const parts: string[] = []
+    if (node.className) parts.push(`class="${node.className}"`)
+    if (node.style && Object.keys(node.style).length > 0) {
+      const styles = Object.entries(node.style)
+        .map(([k, v]) => `${k}:${v}`)
+        .join(';')
+      parts.push(`style="${styles}"`)
+    }
+    return parts.length > 0 ? ' ' + parts.join(' ') : ''
+  }
+
+  private static escapeHtml(text: string): string {
+    return text
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+  }
+}

package/src/RenderPipeline/index.ts

@@ -0,0 +1,4 @@
+export { RenderPipeline } from './RenderPipeline'
+export type { RenderPhase, RenderHook, RenderContext } from './RenderPipeline'
+export { RenderTree } from './RenderTree'
+export type { RenderNode, RenderVariant } from './RenderTree'