@miliastry/quasar 1.0.6 → 1.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,154 @@
+/**
+ * MiliastryPlatform / DocumentEngine — Public API
+ *
+ * Language Platform agnóstica. El BBCode es solo una representación.
+ * Todo pasa por el Document Model.
+ *
+ * @see MILIASTRY_DOCUMENT_ENGINE_ARCHITECTURE.md
+ */
+export { DocumentModel } from './Model/DocumentModel';
+export type { DocumentNode, NodeKind, NodeAttributes, NodeMetadata, DocumentChangeEvent, SourceRange } from './Types/core';
+export { Lexer, type LexerOptions } from './Lexer/Lexer';
+export { BBCODE_RAW_TAGS } from './Lexer/BBCodeLexer';
+export type { Token, TokenKind, Trivia, TriviaKind } from './Types/tokens';
+export { GreenNode, greenNode, greenLeaf } from './Syntax/GreenNode';
+export { RedNode } from './Syntax/RedNode';
+export { RedNodeStore } from './Syntax/RedNodeStore';
+export { TreeBuilder, type BuildResult } from './Syntax/TreeBuilder';
+export { NodeMatcher, type MatchResult } from './Syntax/NodeMatcher';
+export { SemanticAnalyzer, type AnalyzeResult, type SemanticAnalyzerOptions, type CrossedTags, type UnknownTag } from './Semantic/SemanticAnalyzer';
+/**
+ * Whether an analysis walked the document or only the edit — see
+ * {@link AnalyzeResult.scope}.
+ *
+ * `'full'` every node was validated afresh; `'window'` only the nodes an edit
+ * could have changed were, and every other node kept the verdict it already
+ * had. The DIAGNOSTICS ARE THE SAME EITHER WAY: this says how they were
+ * arrived at, not what they are.
+ *
+ * Worth reading if you are timing the engine, deciding whether a slow frame
+ * was the analysis, or writing a test that must not silently lose the
+ * incremental path. NOT worth branching your rendering on — a consumer that
+ * treats `'window'` results as partial and merges them into what it already
+ * had will double-report, because `AnalyzeResult.diagnostics` is always the
+ * whole document's.
+ *
+ * `AnalyzeResult.window` carries the span that was re-validated on a
+ * `'window'` pass, and is `null` on a full one.
+ */
+export type { AnalyzeScope } from './Semantic/SemanticAnalyzer';
+/**
+ * `AnalyzeResult` plus the id→node index — see
+ * {@link SemanticAnalyzer.analyze}. `allNodes` is a getter that builds the
+ * index on first read, so a caller that never asks never pays for the walk.
+ */
+export type { IndexedAnalyzeResult } from './Semantic/SemanticAnalyzer';
+export type { Diagnostic, DiagnosticSeverity, DiagnosticTag, DiagnosticFix, FixOperation } from './Types/diagnostics';
+export { TagRegistry, type TagDefinition, type TagHandler } from './Model/TagRegistry';
+export { extractTextContent } from './Model/TagRegistry';
+export { NodeFactory } from './Model/NodeFactory';
+export { IncrementalParser, type EditOperation } from './Incremental/IncrementalParser';
+export { ChangeTracker, type TextChange } from './Incremental/ChangeTracker';
+/**
+ * A half-open span of the source, `[start, end)`, in the coordinates of the
+ * text whose result carries it.
+ *
+ * The same shape everywhere it appears — {@link ReparseResult.window},
+ * `AnalyzeResult.window`, `DocumentModel.lastReparseWindow` — because it
+ * always means the same thing: the part of the CURRENT text that the engine
+ * actually looked at.
+ */
+export type { SourceSpan } from './Incremental/IncrementalParser';
+/**
+ * What a reparse did, including {@link ReparseResult.window} — the span of the
+ * new text that went through the parser, or `null` after a full rebuild,
+ * where the answer is "all of it".
+ *
+ * Everything outside that span came across from the previous tree by
+ * reference, so a consumer holding per-node state (a rendered block, a
+ * measured height, a decoration) can keep it for every node the span does not
+ * touch. `DocumentModel.lastReparseWindow` is the same value for the model's
+ * last edit, which is usually the easier place to read it.
+ */
+export type { ReparseResult } from './Incremental/IncrementalParser';
+/**
+ * Why a reparse rebuilt the whole document instead of splicing a window.
+ *
+ * Useful when a document is unexpectedly slow to edit: a reason that repeats
+ * on every keystroke is a document shape the window guards will not accept —
+ * an unclosed `[` before the caret (`open-bracket-before`), a stray closing
+ * tag inside the window (`region-not-isolated`), an edit that changes what the
+ * parser leaves pending for the text after it (`pending-auto-close`).
+ */
+export type { FallbackReason } from './Incremental/IncrementalParser';
+export { TreeDiffer, type DiffOperation, type DiffKind } from './Diff/TreeDiffer';
+export { Visitor, type VisitorContext } from './Visitors/Visitor';
+export { BBCodeExporter, MILIASTRY_ONLY_TAGS, LYNE_ONLY_TAGS, type ExportTarget, type BBCodeExporterOptions, type BBCodeExportOptions } from './Visitors/BBCodeExporter';
+export { BBBlocksExporter, type UIBBBlock } from './Visitors/BBBlocksExporter';
+export { HTMLRenderer, type HTMLRendererOptions } from './Visitors/HTMLRenderer';
+export { morphHTML } from './Visitors/DOMMorpher';
+export { patchBlocksInto, clearPatchCache, type PatchBlocksOptions, type PatchBlocksStats } from './Visitors/BlockPatcher';
+export { SVGRenderer } from './Visitors/SVGRenderer';
+export { MarkdownExporter } from './Visitors/MarkdownExporter';
+export { JSONExporter } from './Visitors/JSONExporter';
+export { TiptapExporter } from './Visitors/TiptapExporter';
+export { Transaction } from './Transactions/Transaction';
+export type { Operation } from './Types/operations';
+export { UndoManager, type UndoEntry } from './Transactions/UndoManager';
+export { CommandRegistry } from './Commands/CommandRegistry';
+export type { Command, CommandContext, CommandResult } from './Commands/Command';
+export { InsertText } from './Commands/InsertText';
+export { DeleteNode } from './Commands/DeleteNode';
+export { WrapInTag } from './Commands/WrapInTag';
+export { SplitNode, MergeNode } from './Commands/SplitMerge';
+export { QueryEngine } from './Queries/QueryEngine';
+export type { Query, QueryMatch, QueryResult } from './Types/queries';
+export { Formatter, type FormatOptions } from './Formatter/Formatter';
+export { Linter, type LintRule, type LintResult } from './Linter/Linter';
+export { SymbolTable } from './Symbols/SymbolTable';
+export type { SymbolInfo, SymbolKind, Reference, SymbolSearchResult } from './Types/symbols';
+export { RenderPipeline } from './RenderPipeline/RenderPipeline';
+export { RenderTree, type RenderNode, type RenderVariant } from './RenderPipeline/RenderTree';
+export { PluginAPI } from './Plugins/PluginAPI';
+export { PluginRegistry, type PluginManifest, type PluginContribution } from './Plugins/PluginRegistry';
+export { repairNesting, type NestingRepair, type OrphanCloser, type UnclosedOpener } from './Repair/NestingRepair';
+export { reconcileVisualDOMToBBCode, computeTextDelta, type SurgicalEdit as QuasarSurgicalEdit, type ReconcileResult } from './Reconciler/SurgicalReconciler';
+export * from './Edits';
+export { BBCodeDocumentModel } from './BBCode/BBCodeDocumentModel';
+export type { BBCodeDocumentModelOptions } from './BBCode/BBCodeDocumentModel';
+export { bbBlocksToRedTree, bbBlocksToGreenTree, bbBlockToGreenNode, greenToRedNode, tagToNodeKind, nodeKindToTag, isBlockKind, BBCODE_TAG_NAMES, getBBCodeTagNames, type BBCodeDialect, } from './BBCode/BBCodeToGreenNode';
+export type { BBBlock } from './BBCode/BBCodeToGreenNode';
+export { DocumentEventBus, type DocumentEvent, type DocumentEventHandler } from './Events/EventBus';
+export { transformOffset, transformRange, type TransformBias } from './Collab/positions';
+export { visualThemes } from './Visuals/index';
+export type { VisualThemeId } from './Visuals/index';
+export { bindBoxDrawer, toggleBoxWithDrawer } from './Visuals/BoxDrawer';
+export type { BoxDrawerOptions } from './Visuals/BoxDrawer';
+export { applyGradient, applyGrow, applyRainbow, applyCentralGradient, applyMultiGradient, applyEffect, countTextLength } from './Utils/treeTransformers';
+export type { GradientEffect, GrowEffect, RainbowEffect, CentralGradientEffect, MultiGradientEffect, TreeEffect } from './Utils/treeTransformers';
+export { domToSVG, domToSVGResult } from './Utils/dom-to-svg';
+export type { DomToSVGOptions, DomToSVGResult, SVGLayerInfo } from './Utils/dom-to-svg';
+export type { Transformer } from './Transformers/Transformer';
+export { ASTOptimizer } from './Transformers/ASTOptimizer';
+export { SineWaveTransformer, type SineWaveOptions } from './Transformers/SineWaveTransformer';
+export { RainbowTransformer, type RainbowOptions } from './Transformers/RainbowTransformer';
+export { GradientTransformer, type GradientOptions } from './Transformers/GradientTransformer';
+export { GrowTransformer, type GrowOptions } from './Transformers/GrowTransformer';
+export { MilHibriDocumentModel, type MilHibriDocumentModelOptions } from './MilHibri/MilHibriDocumentModel';
+export { MarkdownDocumentModel } from './Markdown/MarkdownDocumentModel';
+export { markdownAstToGreenTree, markdownAstToRedTree } from './Markdown/MarkdownToGreenNode';
+export { HTMLDocumentModel } from './HTML/HTMLDocumentModel';
+export { htmlStringToGreenTree } from './HTML/HTMLToGreenNode';
+export { ease, solveCubicBezierY, hslToHex, hexToRgb, hexToHsl, hexToOklab, mixHex, mixHexOklab, mixMultiple, mixMultipleStops, perceptualDistance, } from './Utils/ColorMath';
+export type { Easing, ColorStop } from './Utils/ColorMath';
+export { isHexColor } from './Utils/ColorMath';
+export { hashSeed, randAt, valueNoise, fbm, validateExpression, compileExpression, EXPRESSION_VARS, waveform, WAVE_KINDS, DEFAULT_WAVE_OPTIONS, clamp01, blendHex, BLEND_MODES, rgbToHex, adjustHsl, posterizeHex, clampRange, buildSampleTable, buildRangeScope, documentScope, axisValue, expressionVars, AXES, effectiveAxis, mergeStyledSegments, normalizeHex, parseColorStops, stringifyColorStops, parseEffectParams, stringifyEffectParams, EFFECT_PARAM_KEYS, EFFECT_UNITS, evaluateEffect, GRADIENT_DEFAULTS, RAINBOW_DEFAULTS, GROW_DEFAULTS, NEUTRAL_SIZE, PAINT_DEFAULTS, SPATIAL_DEFAULTS, SPATIAL_AXES, DEFAULT_CELL_ASPECT, DEFAULT_SPATIAL, spatialPoint, MASK_SHAPES, DEFAULT_MASK, maskValue, maskDistance, spatialFromParams, maskFromParams, gridFromParams, PAINT_MAX_COLORS, parsePaintGrid, samplePaintGrid, stringifyPaintCells, stringifyPaintPalette, } from './Utils/EffectMath';
+export type { WaveKind, WaveOptions, BlendMode, ExpressionVars, CompiledExpression, CharSample, SampleTable, RangeScope, SampleContext, Axis, EffectParams, EffectUnit, EffectKind, EffectSpan, StyledSegment, SpatialOptions, SpatialPoint, MaskShape, MaskOptions, PaintGrid, } from './Utils/EffectMath';
+export { attributeVocabularyFor, allAttributeVocabularies, EFFECT_TYPES, ANIM_TYPES, CONTAINER_TYPES, SEPARATOR_VARIANTS, TABLE_FLAGS, IMG_MODIFIERS, } from './Utils/TagVocabulary';
+export type { AttributeVocabulary, VocabularySyntax } from './Utils/TagVocabulary';
+export { Pipeline, PipelineBuilder, PipelineStage, ContributionKind, PipelineMode, CharacterCountAnalyzer, MergeableColorAnalyzer, GradientAnalyzer, findCollapsibleGradients, formatGradientTag, RainbowAnalyzer, WaveAnalyzer, SymbolAnalyzer, ColorUsageAnalyzer, DefaultDecision, PaletteRemapDecision, CollapseGradientTransform, RainbowCollapseTransform, WaveCollapseTransform, MergeColorsTransform, } from './Analysis/index';
+export type { CollapsibleGradient, Pass, AnalyzerPass, DecisionPass, TransformPass, TransformationPlan, TransformAction, Contribution, SemanticContribution, DiagnosticContribution, OptimizationContribution, MetricsContribution, AnalysisReport, PipelineContext, PipelineResult, GradientModel, GradientDiagnostics, GradientStop, RainbowModel, RainbowDiagnostics, WaveModel, WaveDiagnostics, SymbolGlyph, SymbolRunModel, ColorUsageModel, Palette, PaletteRemapOptions, RemapAction, } from './Analysis/index';
+export { nodeAttrValue, parseImgAttr, sanitizeColor, sanitizeFontSize, sanitizeFontFamily, } from './Syntax/nodeAttr';
+export type { ImgAttr } from './Syntax/nodeAttr';
+export { toTokenResolver, resolveTokenValue, } from './Tokens/index';
+export type { DocumentTokens, TokenResolverFn, TokenSource, } from './Tokens/index';

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@miliastry/quasar",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Quasar Document Engine - Advanced BBCode/Markdown/HTML AST Engine",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/types/index.d.ts",
   "license": "MSL-1.0",
   "sideEffects": [
     "./src/Visuals/*.css",
@@ -12,11 +13,11 @@
   "exports": {
     ".": {
       "import": {
-        "types": "./dist/index.d.mts",
+        "types": "./dist/types/index.d.ts",
         "default": "./dist/index.mjs"
       },
       "require": {
-        "types": "./dist/index.d.ts",
+        "types": "./dist/types/index.d.ts",
         "default": "./dist/index.js"
       }
     },
@@ -27,7 +28,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsup && node scripts/copy-css.mjs",
+    "build": "tsup && tsc -p tsconfig.build.json && node scripts/copy-css.mjs",
     "prepublishOnly": "npm run verify && npm run build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -38,12 +39,15 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/Tests",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts"
   ],
-  "dependencies": {},
   "devDependencies": {
-    "@miliastry/quasar-studio": "*",
+    "@types/node": "^22",
     "tsup": "^8.5.1",
-    "typescript": "5.7.3"
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.8"
   }
 }

package/src/Analysis/Passes/Analysis/ColorUsageAnalyzer.ts

@@ -0,0 +1,103 @@
+/**
+ * Quasar Analysis Framework — Color Usage Analyzer
+ *
+ * Reports every `[color=#RRGGBB]` in the document, one contribution per tag.
+ *
+ * ## Why this exists alongside GradientAnalyzer
+ *
+ * `GradientAnalyzer` recognises that a run of colour tags forms a gradient and
+ * describes its *shape* — the stops, the easing, the span. What it does not
+ * describe is where each individual tag sits, because a gradient is modelled
+ * as one continuous ramp rather than as the tags that spell it out.
+ *
+ * A consumer that wants to recolour a document needs both: the shape, to know
+ * what the gradient is doing, and the tag positions, to know what to edit.
+ * This pass supplies the second half. A DecisionPass sees both contributions
+ * in the same report and can join them — which is exactly how the framework is
+ * meant to compose, since analyzer passes cannot observe each other.
+ *
+ * ## What gets reported
+ *
+ * Every colour tag, gradient member or not. Deciding which ones are
+ * interesting is a decision, and decisions belong in the decision stage.
+ *
+ * Only full six-digit hex is recognised, because that is what `extractHex`
+ * accepts. `[color=red]` and `[color=#F00]` are parsed as colours by the
+ * engine but are invisible here — a deliberate limit, since rewriting them
+ * would mean choosing a canonical spelling the author did not use.
+ *
+ * @see SemanticContribution
+ * @see GradientAnalyzer
+ */
+
+import type { AnalyzerPass } from '../../Contracts/Pass'
+import type { PipelineContext } from '../../Contracts/PipelineContext'
+import type { Contribution } from '../../Contracts/Contribution'
+import { ContributionKind } from '../../Contracts/Contribution'
+import type { GreenNode } from '../../../Syntax/GreenNode'
+import { childOffsets } from '../../../Syntax/GreenNode'
+import { extractHex } from '../../Utils/color-utils'
+
+// ── Types ─────────────────────────────────────────────────────────
+
+export interface ColorUsageModel {
+  /** Normalised to uppercase `#RRGGBB` by `extractHex`. */
+  readonly hex: string
+  /**
+   * Source offsets of the opening delimiter alone — `[color=#D194B3]`.
+   *
+   * Recolouring replaces this span rather than the attribute inside it. The
+   * attribute's own position would have to be derived from the delimiter's
+   * width and the hex's length, which breaks the moment the author writes
+   * `[color = #D194B3]`; the delimiter's bounds are read straight off the
+   * node. The cost is that a rewritten tag comes back in canonical spelling,
+   * which is acceptable for a tag being edited anyway.
+   */
+  readonly openStart: number
+  readonly openEnd: number
+}
+
+// ── Analyzer ──────────────────────────────────────────────────────
+
+export class ColorUsageAnalyzer implements AnalyzerPass {
+  readonly id = 'color-usage'
+
+  run(tree: GreenNode, _context: PipelineContext): Contribution[] {
+    const contributions: Contribution[] = []
+    this.walk(tree, contributions, 0)
+    return contributions
+  }
+
+  // ── Private ─────────────────────────────────────────────────────
+
+  private walk(node: GreenNode, sink: Contribution[], start: number): void {
+    const hex = extractHex(node)
+
+    if (hex !== null) {
+      const model: ColorUsageModel = {
+        hex,
+        openStart: start,
+        openEnd: start + node.leadingWidth,
+      }
+
+      sink.push({
+        kind: ContributionKind.Semantic,
+        label: 'Color',
+        // A parsed colour tag is a fact, not an inference: unlike a gradient
+        // or a decorative glyph, there is nothing here to be unsure about.
+        confidence: 1,
+        range: { start, end: start + node.width },
+        metadata: { model },
+        description: `Colour ${hex}`,
+      })
+    }
+
+    const children = node.children as readonly GreenNode[]
+    if (children.length === 0) return
+
+    const offsets = childOffsets(node, start)
+    for (let i = 0; i < children.length; i++) {
+      this.walk(children[i], sink, offsets[i])
+    }
+  }
+}