@miliastry/quasar 1.0.6 → 1.2.0

package/src/Edits/Rules/reorderWrappers.ts

@@ -0,0 +1,154 @@
+/**
+ * Quasar — `reorder-wrappers` (opt-in)
+ *
+ * Puts a chain of single-child wrappers into a canonical order:
+ *
+ *   [color=#F00][b]x[/b][/color]  →  [b][color=#F00]x[/color][/b]
+ *
+ * ## It saves no bytes, and that is why it is not in the default preset
+ *
+ * Reordering removes nothing. Its value is canonical form — two documents that
+ * differ only in wrapper order become byte-identical, which is what lets other
+ * rules recognise runs they would otherwise miss. On its own, in a *minifier*,
+ * it produces a diff across someone's document in exchange for zero
+ * characters, so `defaultRules()` leaves it out and callers opt in.
+ *
+ * ## Byte-swaps, never regeneration
+ *
+ * The delimiters are moved, not rebuilt: each slot receives the exact source
+ * bytes of the delimiter that belongs there. `[Color = "#F00"]` comes out the
+ * other side character for character, which a tag-rebuilding implementation
+ * could not promise.
+ *
+ * ## Maximal
+ *
+ * The whole chain is sorted at once. Swapping one adjacent pair at a time
+ * would need repeated passes over offsets that no longer exist, so
+ * `[color][b][i]x[/i][/b][/color]` is permuted in a single step. The sort is
+ * stable, so equal-rank wrappers keep the order the author wrote.
+ */
+
+import type { PlannedEdit } from '../EditPlan'
+import {
+  type OptimizationRule,
+  type RuleContext,
+  type Positioned,
+  positionedChildren,
+  openRange,
+  closeRange,
+  hasBothDelimiters,
+} from './Rule'
+
+export const REORDER_WRAPPERS_PRIORITY = 5
+
+/**
+ * Nesting rank — lower belongs further out.
+ *
+ * Links outermost (a link wrapping styled text is the common authoring
+ * intent), then metrics, then weight/decoration, then colour innermost. Kinds
+ * absent from the table are not reordered at all: an unranked tag may carry
+ * layout or semantics that nesting order changes.
+ */
+const RANK: Readonly<Record<string, number>> = {
+  url: 1,
+  email: 1,
+  profile: 1,
+  font_size: 2,
+  font: 2,
+  bold: 3,
+  italic: 3,
+  underline: 3,
+  strikethrough: 3,
+  color: 4,
+}
+
+export class ReorderWrappersRule implements OptimizationRule {
+  readonly id = 'reorder-wrappers'
+  readonly priority = REORDER_WRAPPERS_PRIORITY
+  readonly label = 'Canonicalise nested wrapper order'
+
+  run(context: RuleContext): PlannedEdit[] {
+    const sink: PlannedEdit[] = []
+    this.scan({ node: context.root, start: 0 }, context.source, sink)
+    sink.sort((a, b) => a.start - b.start || a.end - b.end)
+    return sink
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private scan(item: Positioned, source: string, sink: PlannedEdit[]): void {
+    for (const child of positionedChildren(item)) {
+      const chain = this.chainFrom(child)
+
+      if (chain.length >= 2) {
+        this.emitPermutation(chain, source, sink)
+        // Continue below the chain. `scan` iterates its argument's children,
+        // so the innermost wrapper is what gets handed down — passing its
+        // children instead would skip a level.
+        this.scan(chain[chain.length - 1], source, sink)
+        continue
+      }
+
+      this.scan(child, source, sink)
+    }
+  }
+
+  /** The maximal run of rankable single-child wrappers starting at `item`. */
+  private chainFrom(item: Positioned): Positioned[] {
+    const chain: Positioned[] = []
+    let current: Positioned | undefined = item
+
+    while (
+      current &&
+      RANK[current.node.kind] !== undefined &&
+      hasBothDelimiters(current) &&
+      current.node.children.length === 1
+    ) {
+      chain.push(current)
+      const [only] = positionedChildren(current)
+      current = only
+    }
+    return chain
+  }
+
+  private emitPermutation(
+    chain: readonly Positioned[],
+    source: string,
+    sink: PlannedEdit[],
+  ): void {
+    const order = chain.map((_, index) => index)
+    // Stable by construction: ties fall back to the original index.
+    order.sort((a, b) => RANK[chain[a].node.kind] - RANK[chain[b].node.kind] || a - b)
+
+    if (order.every((sourceIndex, slot) => sourceIndex === slot)) return
+
+    const label = `Canonicalise ${chain.map(c => `[${c.node.kind}]`).join('')}`
+
+    for (let slot = 0; slot < chain.length; slot++) {
+      const from = chain[order[slot]]
+      if (order[slot] === slot) continue
+
+      const openSlot = openRange(chain[slot])
+      const closeSlot = closeRange(chain[slot])
+      const openFrom = openRange(from)
+      const closeFrom = closeRange(from)
+
+      sink.push({
+        start: openSlot.start,
+        end: openSlot.end,
+        text: source.slice(openFrom.start, openFrom.end),
+        ruleId: this.id,
+        priority: this.priority,
+        label,
+      })
+      sink.push({
+        start: closeSlot.start,
+        end: closeSlot.end,
+        text: source.slice(closeFrom.start, closeFrom.end),
+        ruleId: this.id,
+        priority: this.priority,
+        label,
+      })
+    }
+  }
+}

package/src/Edits/Rules/shortenHex.ts

@@ -0,0 +1,79 @@
+/**
+ * Quasar — `shorten-hex`
+ *
+ * `[color=#FFAA00]` → `[color=#FA0]`, three characters per tag.
+ *
+ * Only fires when every channel is a doubled digit, which is exactly the set
+ * of six-digit colours the three-digit form can express — `#FA0` expands back
+ * to `#FFAA00` by duplication, so the rendered colour is bit-identical. This
+ * was verified against the engine before the rule was written: three-digit hex
+ * parses to a `color` node and reaches CSS as `color:#FA0`.
+ *
+ * The edit replaces the hex token alone, located inside the opening
+ * delimiter — never the delimiter itself. `[Color = "#FFAA00"]` therefore
+ * becomes `[Color = "#FA0"]`, keeping the capital C, the spaces and the
+ * quotes the author typed.
+ *
+ * Three bytes sounds trivial and is not: an expanded gradient spends one
+ * colour tag per character, so a 400-character ramp gives back 1.200.
+ */
+
+import type { PlannedEdit } from '../EditPlan'
+import {
+  type OptimizationRule,
+  type RuleContext,
+  type Positioned,
+  positionedChildren,
+  openRange,
+} from './Rule'
+import { attributeValue, shortenableHex } from './tagValue'
+
+export const SHORTEN_HEX_PRIORITY = 10
+
+const HEX6_TOKEN = /#[0-9a-fA-F]{6}/
+
+export class ShortenHexRule implements OptimizationRule {
+  readonly id = 'shorten-hex'
+  readonly priority = SHORTEN_HEX_PRIORITY
+  readonly label = 'Shorten 6-digit hex colours'
+
+  run(context: RuleContext): PlannedEdit[] {
+    const sink: PlannedEdit[] = []
+    this.scan({ node: context.root, start: 0 }, context.source, sink)
+    return sink
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private scan(item: Positioned, source: string, sink: PlannedEdit[]): void {
+    for (const child of positionedChildren(item)) {
+      if (child.node.kind === 'color') {
+        const edit = this.shorten(child, source)
+        if (edit) sink.push(edit)
+      }
+      this.scan(child, source, sink)
+    }
+  }
+
+  private shorten(item: Positioned, source: string): PlannedEdit | null {
+    const short = shortenableHex(attributeValue(item.node))
+    if (short === null) return null
+
+    const open = openRange(item)
+    const delimiter = source.slice(open.start, open.end)
+    const match = HEX6_TOKEN.exec(delimiter)
+    // The attribute said there was a six-digit hex; if it is not visible in the
+    // delimiter the two disagree, and guessing an offset would corrupt bytes.
+    if (!match) return null
+
+    const start = open.start + match.index
+    return {
+      start,
+      end: start + match[0].length,
+      text: short,
+      ruleId: this.id,
+      priority: this.priority,
+      label: `${match[0]} → ${short}`,
+    }
+  }
+}

package/src/Edits/Rules/tagValue.ts

@@ -0,0 +1,105 @@
+/**
+ * Quasar — Tag attribute reading & normalisation for optimization rules
+ *
+ * Rules compare tags by what they *mean*, not by how they are spelled:
+ * `[Color = "#FF0000"]`, `[color=#ff0000]` and `[color=#F00]` all name the
+ * same colour and must be treated as one. Normalising here is what lets the
+ * merge rule fuse them while still leaving the author's own bytes in place.
+ *
+ * `Analysis/Utils/color-utils.extractHex` is deliberately stricter — it
+ * accepts only six-digit hex, because a *recolouring* pass must not rewrite a
+ * spelling the author chose. These rules have the opposite need: they only
+ * ever delete or shorten, so recognising more spellings is pure upside.
+ */
+
+import type { GreenNode } from '../../Syntax/GreenNode'
+
+const QUOTES = new Set(['"', "'"])
+
+/**
+ * The attribute value a tag node carries, unquoted and trimmed.
+ *
+ * A node's `text` holds the raw attribute segment of its opening delimiter —
+ * `=#FF0000`, `= "#FF0000"`, or `''` for a bare tag.
+ */
+export function attributeValue(node: GreenNode): string {
+  const text = node.text || ''
+  const eq = text.indexOf('=')
+  let value = (eq >= 0 ? text.slice(eq + 1) : text).trim()
+
+  if (value.length >= 2 && QUOTES.has(value[0]) && value[value.length - 1] === value[0]) {
+    value = value.slice(1, -1).trim()
+  }
+  return value
+}
+
+const HEX6 = /^#[0-9a-fA-F]{6}$/
+const HEX3 = /^#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])$/
+
+/**
+ * Canonical form of a colour value, for equality only.
+ *
+ * Never written back to the document — `#F00` and `#FF0000` normalise to the
+ * same string so the two tags can merge, but whichever one the author wrote is
+ * the one that survives.
+ */
+export function normalizeColorValue(raw: string): string {
+  const short = HEX3.exec(raw)
+  if (short) return `#${short[1]}${short[1]}${short[2]}${short[2]}${short[3]}${short[3]}`.toUpperCase()
+  if (HEX6.test(raw)) return raw.toUpperCase()
+  // Keywords (`red`, `Transparent`) are case-insensitive in CSS.
+  return raw.toLowerCase()
+}
+
+/** Six-digit hex whose channels are all doubled digits, e.g. `#FFAA00`. */
+export function shortenableHex(raw: string): string | null {
+  if (!HEX6.test(raw)) return null
+  const r = raw.slice(1)
+  if (r[0].toLowerCase() !== r[1].toLowerCase()) return null
+  if (r[2].toLowerCase() !== r[3].toLowerCase()) return null
+  if (r[4].toLowerCase() !== r[5].toLowerCase()) return null
+  // Keep the author's own digit casing; only the redundant half is dropped.
+  return `#${r[0]}${r[2]}${r[4]}`
+}
+
+/**
+ * The identity two sibling tags must share to be mergeable.
+ *
+ * Returns `null` for kinds this optimizer does not fuse.
+ */
+export function mergeIdentity(node: GreenNode): string | null {
+  if (node.kind === 'color') return `color|${normalizeColorValue(attributeValue(node))}`
+  if (MERGEABLE_INLINE.has(node.kind)) return `${node.kind}|${attributeValue(node).toLowerCase()}`
+  return null
+}
+
+/**
+ * Inline formatting tags that fuse when adjacent and identically attributed.
+ *
+ * Block kinds are absent on purpose. Merging `[box]a[/box][box]b[/box]` into
+ * one box is not a rewrite of the same document — it renders one frame where
+ * the author drew two.
+ */
+export const MERGEABLE_INLINE: ReadonlySet<string> = new Set([
+  'bold',
+  'italic',
+  'underline',
+  'strikethrough',
+  'font_size',
+  'font',
+  'sup',
+  'sub',
+  'mark',
+])
+
+/**
+ * Kinds that may absorb the whitespace sitting between two merged siblings.
+ *
+ * `[color=X]a[/color] [color=X]b[/color]` → `[color=X]a b[/color]` is safe: a
+ * coloured space and an uncoloured space are the same pixels. The same move on
+ * `[u]` is **not** — the underline would extend across the gap, which is a
+ * visible change to a document the user only asked to make smaller. Size and
+ * font are excluded for the same reason: a space in another size or face can
+ * change advance width and line height.
+ */
+export const BRIDGES_WHITESPACE: ReadonlySet<string> = new Set(['color', 'bold', 'italic'])

package/src/Edits/Rules/unwrapInvisibleColor.ts

@@ -0,0 +1,93 @@
+/**
+ * Quasar — `unwrap-invisible-color`
+ *
+ * Removes a `[color]` whose entire content is whitespace.
+ *
+ *   [color=#6A4C93]BARCA[/color][color=#6F518D] [/color][color=#755687]·[/color]
+ *                               ╰── 24 bytes to colour a space ──╯
+ *
+ * A space has no glyph, and `[color]` sets `color` and nothing else — no
+ * background, no decoration — so painting one is a guaranteed no-op. Deleting
+ * the two delimiters turns 24 bytes into 1 and cannot change a pixel.
+ *
+ * This is the dominant waste in expanded gradients, and it is easy to see why:
+ * the tool that expands `[gradient]` into per-character `[color]` spans walks
+ * characters without asking which of them draw ink, so every space in the ramp
+ * gets its own fully-spelled tag.
+ *
+ * ## Only colour
+ *
+ * The same shape is *not* removable for other tags, and the difference is not
+ * subtle:
+ *
+ * - `[u]` / `[s]` draw a line through the gap — visible on a space.
+ * - `[mark]` paints a background — visible on a space.
+ * - `[size]` and `[font]` change the advance width of the space itself.
+ *
+ * Only `color` is invisible on whitespace, so only `color` is unwrapped.
+ */
+
+import type { GreenNode } from '../../Syntax/GreenNode'
+import type { PlannedEdit } from '../EditPlan'
+import {
+  type OptimizationRule,
+  type RuleContext,
+  type Positioned,
+  positionedChildren,
+  openRange,
+  closeRange,
+  hasBothDelimiters,
+  deletion,
+} from './Rule'
+
+export const UNWRAP_INVISIBLE_COLOR_PRIORITY = 85
+
+/**
+ * Whether a node contributes nothing but whitespace.
+ *
+ * Recursive through nested colours, so `[color=A][color=B] [/color][/color]`
+ * counts. `spacing` is whitespace too — a newline inside a colour tag is as
+ * invisible as a space.
+ */
+export function isInvisibleWhitespace(node: GreenNode): boolean {
+  if (node.kind === 'text') return /^\s*$/.test(node.text ?? '')
+  if (node.kind === 'spacing' || node.kind === 'empty_line') return true
+  if (node.kind !== 'color') return false
+
+  const children = node.children as readonly GreenNode[]
+  if (children.length === 0) return node.width - node.leadingWidth - node.trailingWidth === 0
+  return children.every(isInvisibleWhitespace)
+}
+
+export class UnwrapInvisibleColorRule implements OptimizationRule {
+  readonly id = 'unwrap-invisible-color'
+  readonly priority = UNWRAP_INVISIBLE_COLOR_PRIORITY
+  readonly label = 'Unwrap colour tags around whitespace'
+
+  run(context: RuleContext): PlannedEdit[] {
+    const sink: PlannedEdit[] = []
+    this.scan({ node: context.root, start: 0 }, sink)
+    sink.sort((a, b) => a.start - b.start || a.end - b.end)
+    return sink
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private scan(item: Positioned, sink: PlannedEdit[]): void {
+    for (const child of positionedChildren(item)) {
+      if (
+        child.node.kind === 'color' &&
+        hasBothDelimiters(child) &&
+        isInvisibleWhitespace(child.node)
+      ) {
+        const label = 'Unwrap colour around whitespace'
+        sink.push(deletion(openRange(child), this.id, this.priority, label))
+        sink.push(deletion(closeRange(child), this.id, this.priority, label))
+        // Nested colours inside are invisible too; keep unwrapping them.
+        this.scan(child, sink)
+        continue
+      }
+      this.scan(child, sink)
+    }
+  }
+}

package/src/Edits/applyEdits.ts

@@ -0,0 +1,54 @@
+/**
+ * Quasar — applying a resolved edit set to source text
+ *
+ * The string-rewriting half of the two appliers. Monaco is the other: it takes
+ * the very same `SurgicalEdit[]` and resolves the offsets against its model
+ * itself, which is why neither side ever re-serializes the document and the
+ * two cannot drift.
+ */
+
+import type { SurgicalEdit } from '../Reconciler/SurgicalReconciler'
+
+/**
+ * Apply edits carrying ORIGINAL offsets, in one pass.
+ *
+ * The obvious implementation splices the string once per edit:
+ *
+ *     for (const edit of backToFront) out = out.slice(0, s) + text + out.slice(e)
+ *
+ * which is correct and quadratic — every splice copies the whole document, so
+ * a 250.000-character page with ~3.800 edits copies roughly a billion
+ * characters and takes about half a second. Measured, not guessed. Collecting
+ * the untouched spans and joining them once is linear and turns that into a
+ * few milliseconds, which is the difference between a minify command that
+ * feels instant and one that visibly stalls the editor.
+ *
+ * Going forwards rather than backwards is what makes the single pass possible,
+ * and it costs nothing: each edit is measured against the original string
+ * either way.
+ *
+ * ## Contract
+ *
+ * The edits must be pairwise conflict-free — run them through
+ * `resolveEditConflicts` first. An edit that reaches back into a span already
+ * written is a contract violation with no meaningful answer, so it is skipped
+ * rather than allowed to interleave into nonsense; the result stays a valid
+ * document that is merely missing one change.
+ */
+export function applyEditsToSource(source: string, edits: readonly SurgicalEdit[]): string {
+  if (edits.length === 0) return source
+
+  const ordered = [...edits].sort((a, b) => a.start - b.start || a.end - b.end)
+  const segments: string[] = []
+  let cursor = 0
+
+  for (const edit of ordered) {
+    if (edit.start < cursor) continue
+    if (edit.start > cursor) segments.push(source.slice(cursor, edit.start))
+    if (edit.text) segments.push(edit.text)
+    cursor = edit.end
+  }
+
+  if (cursor < source.length) segments.push(source.slice(cursor))
+  return segments.join('')
+}

package/src/Edits/index.ts

@@ -0,0 +1,22 @@
+export {
+  classifyOverlap,
+  editsConflict,
+  compareEditPriority,
+  resolveEditConflicts,
+} from './EditPlan'
+export type {
+  PlannedEdit,
+  RejectedEdit,
+  ResolvedEditPlan,
+  EditRejectionReason,
+  OverlapRelation,
+} from './EditPlan'
+export { applyEditsToSource } from './applyEdits'
+export {
+  optimizeBBCode,
+  optimizeTree,
+  defaultRules,
+  allRules,
+} from './Optimizer'
+export type { OptimizationResult, OptimizeOptions, RuleStat } from './Optimizer'
+export * from './Rules'

package/src/Events/EventBus.ts

@@ -45,6 +45,24 @@ export interface DocumentEvent {
    * of changes it applied itself. Absent on events with no single cause.
    */
   origin?: string
+  /**
+   * On `diagnostics_updated`: how the analysis that produced them was
+   * obtained — `'full'` (every node revalidated) or `'window'` (only the
+   * nodes the edit could have changed; every other node kept its verdict).
+   *
+   * The `diagnostics` on the event are the WHOLE document's either way, so a
+   * subscriber renders them the same in both cases. This is here for the
+   * cases where the difference is the point: a performance overlay, a test
+   * that must notice the incremental path going away, a log line explaining a
+   * slow frame. See `AnalyzeScope`.
+   */
+  analysisScope?: 'full' | 'window'
+  /**
+   * On `diagnostics_updated` with `analysisScope === 'window'`: the span of
+   * the current source that was re-validated, in current coordinates.
+   * `null`/absent when the whole document was.
+   */
+  analysisWindow?: { start: number; end: number } | null
   timestamp: number
   [key: string]: unknown
 }