@miliastry/quasar 1.0.6 → 1.1.0

package/src/Model/TagRegistry.ts

@@ -20,7 +20,10 @@ import type { RedNode } from '../Syntax/RedNode'
 import { GreenNode } from '../Syntax/GreenNode'
 import type { RenderNode } from '../RenderPipeline/RenderTree'
 import type { Validator } from '../Semantic/SemanticAnalyzer'
-import { mixMultiple, ease, clamp, hslToHex, type Easing } from '../Utils/color'
+import {
+  evaluateEffect,
+  type EffectKind, type EffectParams, type EffectSpan, type StyledSegment,
+} from '../Utils/EffectMath'
 
 // ─── Tag Handler ───────────────────────────────────────────────
 
@@ -101,25 +104,21 @@ export interface PropertyDefinition {
 
 // ─── Internal tag helpers (gradient/grow export) ──────────────
 
-/** Recursively extract plain text from a RedNode tree */
-function extractTextContent(node: RedNode): string {
+/**
+ * Recursively extract plain text from a RedNode tree.
+ *
+ * A line break is a childless `spacing` leaf with no text of its own, so
+ * it has to be spelled out here or an effect spanning two lines is handed
+ * one line and exports without its break — silent data loss, and the
+ * reason every two-dimensional axis (`line`, `column`, `radial`) measured
+ * a block one line tall.
+ */
+export function extractTextContent(node: RedNode): string {
   if (node.kind === 'text') return node.text
+  if (node.kind === 'spacing' || node.kind === 'empty_line') return '\n'
   return node.children.map(extractTextContent).join('')
 }
 
-/** Split text by unit: 'character', 'word', or 'line' */
-function splitByUnit(text: string, unit: string): string[] {
-  if (!text) return []
-  switch (unit) {
-    case 'word':
-      return text.split(/(\s+)/).filter(s => s.length > 0)
-    case 'line':
-      return text.split('\n')
-    default: // 'character'
-      return [...text]
-  }
-}
-
 /** Escape [ and ] inside BBCode content so they're not parsed as tags */
 function escapeBracket(ch: string): string {
   // BBCode has no standard escape. For internal tags produced by TextStudio,
@@ -128,109 +127,37 @@ function escapeBracket(ch: string): string {
   return ch.replace(/\[/g, '\\[').replace(/\]/g, '\\]')
 }
 
-// ─── Effect segment math — one source of truth per effect ─────
-//
-// Each effect (gradient, sinewave, grow, rainbow) serializes two ways: to
-// osu!-compatible BBCode (`toBBCode`) and to a RenderNode tree
-// (`toRenderNode`). Both used to carry their own copy of the per-segment
-// math — t-progression, easing, color mixing, wave sizing — differing only in
-// presentation, which is exactly how the two drift apart. The math now lives
-// in ONE `*Segments` function per effect; the handlers are thin presenters.
+// ─── Effect segments ──────────────────────────────────────────
 //
-// Note this is deliberately NOT the same algorithm as `HTMLRenderer`'s own
-// `renderGradient`: the preview paints a smooth CSS `linear-gradient` with
-// `background-clip: text`, while these segments reproduce the DISCRETE
-// per-chunk colors that the exported `[color=…]` BBCode will actually have.
-
-/**
- * A run of text with the style its effect computed. `color` and `size` are
- * mutually exclusive; neither set means the run passes through unstyled
- * (whitespace between sized words).
- */
-interface StyledSegment {
-  text: string
-  color?: string
-  size?: number
-}
-
-/**
- * Effect progression t ∈ [0,1] for segment `i` of `count`, honoring the
- * document-wide fields (`globalOffset`/`documentLength`) that let one logical
- * effect span several nodes. `single` is the t for a one-segment run — the
- * effects legitimately disagree on it (gradient/rainbow use 0, grow 0.5).
- */
-function progressAt(i: number, count: number, node: RedNode, single: number): number {
-  const globalOffset = (node.metadata?.globalOffset as number) || 0
-  const documentLength = (node.metadata?.documentLength as number) || count
-  if (documentLength > 1) return (globalOffset + i) / (documentLength - 1)
-  return count > 1 ? i / (count - 1) : single
-}
-
-function gradientSegments(node: RedNode): StyledSegment[] {
-  const colors = (node.metadata?.colors as string[]) || ['#FF0000', '#00FF00']
-  const unit = (node.metadata?.unit as string) || 'character'
-  const easing = (node.metadata?.easing as Easing) || 'linear'
-  const text = extractTextContent(node)
-  if (!text) return []
-  const parts = splitByUnit(text, unit)
-  return parts.map((seg, i) => ({
-    text: seg,
-    color: mixMultiple(colors, ease(clamp(progressAt(i, parts.length, node, 0)), easing)),
-  }))
-}
-
-function sinewaveSegments(node: RedNode): StyledSegment[] {
-  const min = (node.metadata?.min as number) ?? 20
-  const max = (node.metadata?.max as number) ?? 80
-  const freq = (node.metadata?.freq as number) ?? 0.4
-  const step = (node.metadata?.step as string) ?? 'char'
-  const text = extractTextContent(node)
-  if (!text) return []
-  const amplitude = (max - min) / 2
-  const center = min + amplitude
-
-  if (step === 'word') {
-    let wordIndex = 0
-    return text.split(/(\s+)/).map(chunk => {
-      if (chunk.trim() === '') return { text: chunk }
-      const size = Math.round(center + Math.sin(wordIndex * freq) * amplitude)
-      wordIndex++
-      return { text: chunk, size }
-    })
+// The maths lives in `Utils/EffectMath`, not here. It used to live in
+// this file, in four `*Segments` functions, while Text Studio kept its
+// own copy and the HTML renderer kept a third — so the same document
+// exported one way, previewed another, and lost every parameter the
+// studio grew. These handlers now only read the node and present the
+// result.
+
+/** Effect parameters carried on a node, plus its span in a longer effect. */
+function effectParamsOf(node: RedNode): { params: EffectParams; span: EffectSpan } {
+  const meta = (node.metadata ?? {}) as Record<string, unknown>
+  const params: EffectParams = {}
+  for (const [key, value] of Object.entries(meta)) {
+    if (key === 'globalOffset' || key === 'documentLength') continue
+    ;(params as Record<string, unknown>)[key] = value
+  }
+  return {
+    params,
+    span: {
+      globalOffset: meta.globalOffset as number | undefined,
+      documentLength: meta.documentLength as number | undefined,
+    },
   }
-
-  return [...text].map((ch, i) => ({
-    text: ch,
-    size: Math.round(center + Math.sin(i * freq) * amplitude),
-  }))
-}
-
-function growSegments(node: RedNode): StyledSegment[] {
-  const min = (node.metadata?.min as number) ?? 50
-  const max = (node.metadata?.max as number) ?? 200
-  const cycles = (node.metadata?.cycles as number) ?? 1
-  const text = extractTextContent(node)
-  if (!text) return []
-  const chars = [...text]
-  return chars.map((ch, i) => {
-    const sine = Math.sin(progressAt(i, chars.length, node, 0.5) * cycles * Math.PI * 2)
-    const normalized = (sine + 1) / 2
-    return { text: ch, size: Math.round(min + (max - min) * normalized) }
-  })
 }
 
-function rainbowSegments(node: RedNode): StyledSegment[] {
-  const saturation = ((node.metadata?.saturation as number) ?? 80) / 100
-  const lightness = ((node.metadata?.lightness as number) ?? 60) / 100
-  const spread = (node.metadata?.spread as number) ?? 300
-  const offset = (node.metadata?.offset as number) ?? 0
+function effectSegments(node: RedNode, kind: EffectKind): StyledSegment[] {
   const text = extractTextContent(node)
   if (!text) return []
-  const chars = [...text]
-  return chars.map((ch, i) => ({
-    text: ch,
-    color: hslToHex(offset + progressAt(i, chars.length, node, 0) * spread, saturation, lightness),
-  }))
+  const { params, span } = effectParamsOf(node)
+  return evaluateEffect(text, kind, params, span)
 }
 
 /** Present styled segments as osu!-compatible BBCode. */
@@ -264,11 +191,44 @@ export type TagHandler = {
   [K in keyof TagDefinition]: TagDefinition[K]
 }
 
+/**
+ * The language's own tags, built once for the process.
+ *
+ * `registerBuiltins` allocates ~130 definition objects, several of them
+ * carrying closures. Constructing a registry cost 14.7 µs because of it, and
+ * a registry is constructed by every `DocumentModel`, every
+ * `SemanticAnalyzer` and every exporter that is handed no registry — so a
+ * throwaway parse paid for the whole table three times over. The table never
+ * changes, so it is shared, and a registry only takes a private copy when a
+ * plugin actually mutates it.
+ */
+let BUILTIN_TAGS: ReadonlyMap<string, TagDefinition> | null = null
+let BUILTIN_KINDS: ReadonlyMap<NodeKind, TagDefinition> | null = null
+let BUILTIN_NAMES: ReadonlySet<string> | null = null
+
+function ensureBuiltins(): void {
+  if (BUILTIN_TAGS !== null) return
+  const tags = new Map<string, TagDefinition>()
+  const kinds = new Map<NodeKind, TagDefinition>()
+  for (const tag of builtinTagDefinitions()) {
+    tags.set(tag.name, tag)
+    kinds.set(tag.kind, tag)
+  }
+  BUILTIN_TAGS = tags
+  BUILTIN_KINDS = kinds
+  BUILTIN_NAMES = new Set(tags.keys())
+}
+
 export class TagRegistry {
-  private tags: Map<string, TagDefinition> = new Map()
-  private kinds: Map<NodeKind, TagDefinition> = new Map()
+  private tags: Map<string, TagDefinition>
+  private kinds: Map<NodeKind, TagDefinition>
   /** Names registered by the constructor — the language's own tags. */
-  private builtins: Set<string> = new Set()
+  private builtins: ReadonlySet<string>
+  /**
+   * Whether `tags`/`kinds` are still the process-wide builtin maps. While
+   * they are, this registry must not write to them.
+   */
+  private shared: boolean = true
 
   /**
    * Bumped on every register/unregister, so consumers that derive something
@@ -278,14 +238,25 @@ export class TagRegistry {
   version: number = 0
 
   constructor() {
-    this.registerBuiltins()
-    for (const name of this.tags.keys()) this.builtins.add(name)
+    ensureBuiltins()
+    this.tags = BUILTIN_TAGS as Map<string, TagDefinition>
+    this.kinds = BUILTIN_KINDS as Map<NodeKind, TagDefinition>
+    this.builtins = BUILTIN_NAMES!
+  }
+
+  /** Take a private copy of the builtin maps before the first write. */
+  private own(): void {
+    if (!this.shared) return
+    this.tags = new Map(this.tags)
+    this.kinds = new Map(this.kinds)
+    this.shared = false
   }
 
   /**
    * Register a tag definition.
    */
   register(tag: TagDefinition): void {
+    this.own()
     this.tags.set(tag.name, tag)
     this.kinds.set(tag.kind, tag)
     this.version++
@@ -295,6 +266,8 @@ export class TagRegistry {
    * Unregister a tag definition.
    */
   unregister(name: string): void {
+    if (!this.tags.has(name)) return
+    this.own()
     const tag = this.tags.get(name)
     if (tag) {
       this.tags.delete(name)
@@ -320,6 +293,7 @@ export class TagRegistry {
    * costs one size comparison and no allocation.
    */
   customTags(): Map<string, NodeKind> | null {
+    if (this.shared) return null
     if (this.tags.size === this.builtins.size) return null
     const out = new Map<string, NodeKind>()
     for (const [name, def] of this.tags) {
@@ -377,10 +351,16 @@ export class TagRegistry {
     return this.getAll().filter(t => !t.isInline && !t.isSelfClosing)
   }
 
-  /**
-   * Register the built-in BBCode tags.
-   */
-  private registerBuiltins(): void {
+}
+
+/**
+ * The built-in BBCode tags.
+ *
+ * Called once per process, through `ensureBuiltins`. It used to be a private
+ * method that registered each definition into `this`, which meant rebuilding
+ * this whole table for every registry.
+ */
+function builtinTagDefinitions(): TagDefinition[] {
     const tags: TagDefinition[] = [
       // ── Formatting ──
       { name: 'b', kind: 'bold', label: 'Bold', category: 'formatting', isInline: true, isSelfClosing: false, canHaveChildren: true, toolbar: { group: 'formatting', label: 'Bold', icon: 'Bold', shortcut: 'Ctrl+B' } },
@@ -409,10 +389,10 @@ export class TagRegistry {
         isSelfClosing: false,
         canHaveChildren: true,
         toBBCode: (ctx) => {
-          const segments = gradientSegments(ctx.node)
+          const segments = effectSegments(ctx.node, 'gradient')
           return segments.length === 0 ? ctx.visitChildren(ctx.node) : segmentsToBBCode(segments)
         },
-        toRenderNode: (ctx) => segmentsToRenderNode('gradient', gradientSegments(ctx.node)),
+        toRenderNode: (ctx) => segmentsToRenderNode('gradient', effectSegments(ctx.node, 'gradient')),
       },
       {
         name: 'sinewave',
@@ -423,10 +403,10 @@ export class TagRegistry {
         isSelfClosing: false,
         canHaveChildren: true,
         toBBCode: (ctx) => {
-          const segments = sinewaveSegments(ctx.node)
+          const segments = effectSegments(ctx.node, 'sinewave')
           return segments.length === 0 ? ctx.visitChildren(ctx.node) : segmentsToBBCode(segments)
         },
-        toRenderNode: (ctx) => segmentsToRenderNode('sinewave', sinewaveSegments(ctx.node)),
+        toRenderNode: (ctx) => segmentsToRenderNode('sinewave', effectSegments(ctx.node, 'sinewave')),
       },
       {
         name: 'grow',
@@ -437,10 +417,28 @@ export class TagRegistry {
         isSelfClosing: false,
         canHaveChildren: true,
         toBBCode: (ctx) => {
-          const segments = growSegments(ctx.node)
+          const segments = effectSegments(ctx.node, 'grow')
+          return segments.length === 0 ? ctx.visitChildren(ctx.node) : segmentsToBBCode(segments)
+        },
+        toRenderNode: (ctx) => segmentsToRenderNode('grow', effectSegments(ctx.node, 'grow')),
+      },
+      {
+        // Colour driven by a picture rather than a ramp: the tag carries a
+        // small indexed grid, and each character takes the colour of the
+        // cell it lands on. Nothing about the text changes — this is the
+        // one effect whose whole point is that the art keeps its shape.
+        name: 'paint',
+        kind: 'paint',
+        label: 'Paint',
+        category: 'text',
+        isInline: true,
+        isSelfClosing: false,
+        canHaveChildren: true,
+        toBBCode: (ctx) => {
+          const segments = effectSegments(ctx.node, 'paint')
           return segments.length === 0 ? ctx.visitChildren(ctx.node) : segmentsToBBCode(segments)
         },
-        toRenderNode: (ctx) => segmentsToRenderNode('grow', growSegments(ctx.node)),
+        toRenderNode: (ctx) => segmentsToRenderNode('paint', effectSegments(ctx.node, 'paint')),
       },
       {
         name: 'rainbow',
@@ -451,10 +449,10 @@ export class TagRegistry {
         isSelfClosing: false,
         canHaveChildren: true,
         toBBCode: (ctx) => {
-          const segments = rainbowSegments(ctx.node)
+          const segments = effectSegments(ctx.node, 'rainbow')
           return segments.length === 0 ? ctx.visitChildren(ctx.node) : segmentsToBBCode(segments)
         },
-        toRenderNode: (ctx) => segmentsToRenderNode('rainbow', rainbowSegments(ctx.node)),
+        toRenderNode: (ctx) => segmentsToRenderNode('rainbow', effectSegments(ctx.node, 'rainbow')),
       },
 
       // ── Layout ──
@@ -491,8 +489,5 @@ export class TagRegistry {
       { name: 'group', kind: 'group', label: 'Group', category: 'layout', isInline: false, isSelfClosing: false, canHaveChildren: true },
     ]
 
-    for (const tag of tags) {
-      this.register(tag)
-    }
-  }
+    return tags
 }