@miliastry/quasar 1.0.6 → 1.1.0

package/dist/types/Reconciler/SurgicalReconciler.d.ts

@@ -0,0 +1,23 @@
+import { RedNode } from '../Syntax/RedNode';
+import { BBCodeExporter } from '../Visitors/BBCodeExporter';
+import { HTMLRenderer } from '../Visitors/HTMLRenderer';
+export interface SurgicalEdit {
+    start: number;
+    end: number;
+    text: string;
+}
+export interface ReconcileResult {
+    edits: SurgicalEdit[];
+    hasChanges: boolean;
+    resultingSource: string;
+}
+/**
+ * Computes the minimal single-range text edit (common prefix + suffix diff)
+ * between two strings, ensuring Monaco only replaces the exact changed characters.
+ */
+export declare function computeTextDelta(original: string, updated: string): SurgicalEdit[];
+/**
+ * Reconciles the visual DOM of a contenteditable container against the original BBCode document AST.
+ * Produces minimal, non-destructive surgical edits preserving untouched BBCode blocks and structure.
+ */
+export declare function reconcileVisualDOMToBBCode(originalSource: string, originalAST: RedNode | null, editorContainer: HTMLElement, exporter?: BBCodeExporter, renderer?: HTMLRenderer): ReconcileResult;

package/dist/types/RenderPipeline/RenderPipeline.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { type RenderNode, type RenderVariant } from './RenderTree';
+import type { TagRegistry } from '../Model/TagRegistry';
+export type RenderPhase = 'build' | 'transform' | 'serialize';
+export interface RenderHook {
+    phase: RenderPhase;
+    hook: (node: RenderNode, context: RenderContext) => RenderNode | null;
+}
+export interface RenderContext {
+    variant: RenderVariant;
+    registry: TagRegistry;
+    source: string;
+}
+export declare class RenderPipeline {
+    private hooks;
+    /**
+     * Register a render hook.
+     */
+    register(hook: RenderHook): void;
+    /**
+     * Unregister a render hook.
+     */
+    unregister(hook: RenderHook): void;
+    /**
+     * Render a RedNode tree to a string.
+     */
+    render(root: RedNode, variant: RenderVariant | undefined, registry: TagRegistry, source?: string): string;
+    /**
+     * Build a RenderNode tree from a RedNode tree.
+     */
+    private buildRenderTree;
+}

package/dist/types/RenderPipeline/RenderTree.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 } 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 declare class RenderTree {
+    /**
+     * Create a render tree from a document node.
+     */
+    static fromNode(kind: NodeKind | string, text?: string, children?: RenderNode[], props?: Record<string, unknown>): RenderNode;
+    /**
+     * Create a text render node.
+     */
+    static text(content: string): RenderNode;
+    /**
+     * Create a container render node.
+     */
+    static container(kind: NodeKind | string, children: RenderNode[], props?: Record<string, unknown>): RenderNode;
+    /**
+     * Serialize a render tree to HTML.
+     */
+    static toHTML(node: RenderNode): string;
+    private static kindToTag;
+    private static propsToHtml;
+    private static escapeHtml;
+}

package/dist/types/RenderPipeline/index.d.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';

package/dist/types/Repair/NestingRepair.d.ts

@@ -0,0 +1,48 @@
+import { RedNode } from '../Syntax/RedNode';
+import type { SurgicalEdit } from '../Reconciler/SurgicalReconciler';
+/** A closing tag the source never opened, kept by the parser as literal text. */
+export interface OrphanCloser {
+    /** The tag name as written, lowercased. */
+    tag: string;
+    /** Where the `[/tag]` sits in the source. */
+    range: {
+        start: number;
+        end: number;
+    };
+}
+/** An opening tag the parser had to close on the author's behalf. */
+export interface UnclosedOpener {
+    tag: string;
+    /** Where its `[/tag]` belongs. */
+    at: number;
+}
+export interface NestingRepair {
+    /** Deletions for the orphans and insertions for the missing closers. */
+    edits: SurgicalEdit[];
+    orphans: OrphanCloser[];
+    unclosed: UnclosedOpener[];
+    /** The repaired source, for callers that want it whole. */
+    source: string;
+    hasChanges: boolean;
+}
+/**
+ * Repairs BBCode nesting without touching a byte the author wrote elsewhere.
+ *
+ * Two kinds of damage, two kinds of edit:
+ *
+ *  - a closing tag with no opener is deleted, because that is what osu! does
+ *    with it — Quasar renders it as literal text, which is the one place the
+ *    two disagree (see `Tests/OsuNestingFidelity.test.ts`);
+ *  - an opener the parser had to close silently gets its `[/tag]` written in,
+ *    at the offset the parser already chose.
+ *
+ * Crossed tags need no rule of their own. `[a][b]x[/a][/b]` already parses to
+ * the same tree as `[a][b]x[/b][/a]`; removing the leftover `[/b]` is all the
+ * repair it takes.
+ *
+ * Deliberately *not* an export of the tree. Round-tripping through
+ * `BBCodeExporter` also yields balanced BBCode, but it rewrites the whole
+ * document — re-spelling attributes, collapsing spacing — and none of that is
+ * a change the author asked for. Edits keep the blast radius at the damage.
+ */
+export declare function repairNesting(source: string, root: RedNode | null): NestingRepair;

package/dist/types/Repair/index.d.ts

@@ -0,0 +1 @@
+export { repairNesting, type NestingRepair, type OrphanCloser, type UnclosedOpener } from './NestingRepair';

package/dist/types/Semantic/SemanticAnalyzer.d.ts

@@ -0,0 +1,321 @@
+/**
+ * DocumentEngine — SemanticAnalyzer
+ *
+ * Walks the Red Tree and produces diagnostics by applying
+ * semantic rules to the syntax tree.
+ *
+ * This is where language-specific validation happens.
+ * The analyzer is extensible via registered validators.
+ *
+ * Inspired by Roslyn's Semantic Model and LSP diagnostics.
+ */
+import { RedNode } from '../Syntax/RedNode';
+import { type BBCodeDialect } from '../BBCode/BBCodeToGreenNode';
+import type { Diagnostic, DiagnosticSeverity, DiagnosticCollection } from '../Types/diagnostics';
+import { type CollapsibleGradient } from '../Analysis/Passes/Analysis/GradientAnalyzer';
+import type { SourceSpan } from '../Incremental/IncrementalParser';
+import { type TokenResolverFn, type TokenSource } from '../Tokens';
+export interface Validator {
+    /** Unique code for this validator (e.g. 'invalid-color') */
+    code: string;
+    /** Severity of issues found by this validator */
+    severity: DiagnosticSeverity;
+    /**
+     * Node kinds this validator can ever fire on. Omit to run on every node.
+     *
+     * Three of the five built-ins open with nothing but a kind test, so on a
+     * document of 1736 nodes they were called 1736 times each to answer a
+     * question the dispatcher can answer once. Declaring the kinds turns the
+     * call into a lookup that never happens.
+     */
+    kinds?: readonly string[];
+    /**
+     * What a verdict on one node depends on. Default `'node'`.
+     *
+     * `'node'`: the node itself, its ancestors, its own source span, and the
+     * document-scope maps on the context (`crossings`, `unknownTags`,
+     * `orphanClosers`, `collapsibleGradients`) — everything the incremental
+     * analysis knows how to keep current. Every built-in is `'node'`-scoped.
+     *
+     * `'document'`: anything else — counting headings, comparing a node with
+     * an unrelated one, reading `allNodes`. A verdict like that can change for
+     * a node the edit never touched, which the window pass cannot see, so
+     * registering one turns every analysis into a full pass until it is
+     * unregistered. Reading `allNodes` from a `'node'`-scoped validator is
+     * treated the same way, at runtime.
+     */
+    scope?: 'node' | 'document';
+    /** Validate a node. Return diagnostics or null */
+    validate(node: RedNode, context: AnalyzerContext): Diagnostic | Diagnostic[] | null;
+}
+export interface AnalyzerContext {
+    /**
+     * Every node in the tree, by id, for cross-reference validation.
+     *
+     * A getter, and deliberately: building this Map cost a second full walk of
+     * the tree plus 1736 `Map.set` calls — 23% of `analyze()` — and **no
+     * validator has ever read it**. It was built so that the caller could look up
+     * by id the node to attach each diagnostic to, which is the node the
+     * validator was looking at when it produced it. Validators that genuinely
+     * need cross-references still get it; everyone else stops paying for it.
+     */
+    readonly allNodes: Map<string, RedNode>;
+    /**
+     * Openers whose `[/tag]` does exist but arrived too late, keyed by the
+     * opener's node id.
+     *
+     * A getter for the same reason `allNodes` is one, and asked for even more
+     * rarely: the only way to reach it is through a node that is already known
+     * to be unclosed, which on a healthy document never happens. Both validators
+     * that read it test `isUnclosedTag` first, so a document with no auto-closed
+     * tag never pays for the walk.
+     */
+    readonly crossings: ReadonlyMap<string, CrossedTags>;
+    /**
+     * Unknown tags that were written as a PAIR, keyed by the opener's node id.
+     *
+     * Same lazy contract as `crossings`, and reached through an even tighter
+     * gate: only a text leaf whose first and last characters are brackets can
+     * be in it, which is three integer compares per text node.
+     */
+    readonly unknownTags: ReadonlyMap<string, UnknownTag>;
+    /**
+     * Closing tags no opener claims, node id → tag name.
+     *
+     * Same walk as `unknownTags`, cached together, because the two answers are
+     * two halves of one pairing: what is left over after every unknown opener
+     * has taken its closer is a `[/tag]` that closes nothing.
+     */
+    readonly orphanClosers: ReadonlyMap<string, string>;
+    /** Sequences of [color] tags that form a gradient, keyed by the first node's id */
+    readonly collapsibleGradients: ReadonlyMap<string, CollapsibleGradient>;
+    /** Previously collected diagnostics */
+    diagnostics: DiagnosticCollection;
+    /** Source text for position lookups */
+    source: string;
+}
+/**
+ * How much of the tree a pass looked at.
+ *
+ * `'full'` — every node was validated afresh. `'window'` — only the nodes an
+ * edit could have changed were: the ones inside the reparse window, the
+ * ancestors on the path down to it, and any node elsewhere whose
+ * document-scope facts (a pairing, a crossing, a colour run) the edit
+ * altered. The diagnostics are complete and identical either way; the scope
+ * says how they were obtained.
+ */
+export type AnalyzeScope = 'full' | 'window';
+export interface AnalyzeResult {
+    diagnostics: DiagnosticCollection;
+    /** Time taken in ms */
+    duration: number;
+    /** Number of nodes analyzed */
+    nodesAnalyzed: number;
+    /** See {@link AnalyzeScope}. */
+    scope: AnalyzeScope;
+    /** The span re-validated by a `'window'` pass; `null` for a full one. */
+    window: SourceSpan | null;
+}
+/**
+ * What `analyze()` actually returns: an {@link AnalyzeResult} plus the node
+ * index it had to build anyway for cross-reference lookups.
+ *
+ * Kept as a separate type, and deliberately NOT part of `AnalyzeResult`,
+ * because the index holds a strong reference to every node in the tree. A
+ * caller that stores an `AnalyzeResult` long-term (as `DocumentModel` does)
+ * must not pin an entire stale tree; one that needs the index gets it here and
+ * owns that decision explicitly.
+ */
+export interface IndexedAnalyzeResult extends AnalyzeResult {
+    allNodes: Map<string, RedNode>;
+}
+/**
+ * Whether the parser had to close this tag itself because the author never did.
+ *
+ * Exact, not heuristic. A tag the author closed ends exactly at its own
+ * `[/tag]`, because that is where the parser sets the node's end. A tag closed
+ * *for* the author ends wherever the parser gave up — at the end of the
+ * document, or at the mismatched `[/other]` that forced the issue — and the
+ * text up to that point does not end in its closing form.
+ *
+ * That single rule covers both shapes: `[b]x` (never closed) and `[b][i]x[/b]`
+ * (where `[i]` is auto-closed by the legacy nesting rules).
+ */
+export declare function isUnclosedTag(node: RedNode, source: string): boolean;
+/**
+ * An opener the parser closed on the author's behalf, together with the
+ * `[/tag]` the author *did* write — just too late for it to count.
+ */
+export interface CrossedTags {
+    /** The tag name as written, lowercased. */
+    tag: string;
+    /** Where its closing tag belongs: the offset the parser already closed it at. */
+    at: number;
+    /** Where the ignored `[/tag]` sits in the source. */
+    closer: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * The tag name as the author actually spelled it, read back from the source.
+ *
+ * The tree cannot answer this. Several spellings collapse onto one `NodeKind`
+ * — `[strike]` and `[s]` both become `strikethrough` — and a node's `text`
+ * holds its attributes, not its name. A node's range does start at the opening
+ * bracket, so the name is the identifier immediately after it.
+ *
+ * Returns null for nodes that do not correspond to a written tag.
+ */
+export declare function openingTagName(node: RedNode, source: string): string | null;
+/**
+ * The span of the *name* inside this node's closing tag, or null if the author
+ * never wrote one.
+ *
+ * A rename has to touch both ends: rewriting only the opening `[strike]` to
+ * `[s]` leaves an orphan `[/strike]` that osu! renders as literal text — worse
+ * than the deprecation it was fixing. The name sits between `[/` and `]`, so it
+ * ends one character before the node and runs back its own length.
+ */
+export declare function closingTagNameRange(node: RedNode, source: string, name: string): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * An unknown tag the author wrote as a pair: `[bold]x[/bold]`.
+ *
+ * The pairing is the whole signal. An unknown tag becomes literal text on
+ * purpose — `[Gateron]` in prose has to stay visible, and a real corpus of 53
+ * userpages carries `[gb]`, `[insane]`, `[rm120]` and a dozen more of those —
+ * so a bare `[name]` is not evidence of anything. A `[name]` with a matching
+ * `[/name]` is: nobody closes a bracketed aside. That same corpus contains
+ * exactly ZERO of them, which is the false-positive budget this rule spends.
+ */
+export interface UnknownTag {
+    /** The name as written, lowercased. */
+    tag: string;
+    /** The `[tag]` the parser refused, kept as literal text. */
+    opener: {
+        start: number;
+        end: number;
+    };
+    /** Its `[/tag]` — what makes this a misspelling rather than prose. */
+    closer: {
+        start: number;
+        end: number;
+    };
+}
+export interface SemanticAnalyzerOptions {
+    dialect?: BBCodeDialect;
+    tokens?: TokenSource;
+}
+export declare class SemanticAnalyzer {
+    private validators;
+    /**
+     * The same validators, arranged for the walk instead of for lookup.
+     *
+     * `_always` run on every node; `_byKind` are the ones that declared their
+     * kinds. Iterating the Map itself allocated an iterator and a destructuring
+     * pair per node — 9% of `analyze()` spent on bookkeeping, not on validating.
+     *
+     * Rebuilt on register/unregister, which happen once at construction and
+     * essentially never afterwards.
+     */
+    private _always;
+    private _byKind;
+    /** Set by register/unregister; cleared by the next `rebuildDispatch`. */
+    private _dispatchDirty;
+    /**
+     * The dialect this analyzer validates against.
+     *
+     * Only the suggestion for an unknown tag reads it — detection never needs a
+     * name list, because the parser already refused the tag. `DocumentModel`
+     * builds the analyzer before a subclass knows its dialect, so this is set
+     * afterwards rather than taken by the constructor.
+     */
+    dialect: BBCodeDialect;
+    private _tokens?;
+    private _tokenResolver?;
+    private _validatorsVersion;
+    private _tokensVersion;
+    private _snapshot;
+    get tokens(): TokenSource | undefined;
+    set tokens(val: TokenSource | undefined);
+    get tokenResolver(): TokenResolverFn | undefined;
+    setTokens(tokens?: TokenSource): void;
+    constructor(options?: SemanticAnalyzerOptions | BBCodeDialect);
+    /**
+     * Register a validator.
+     */
+    register(validator: Validator): void;
+    /**
+     * Remove a validator.
+     */
+    unregister(code: string): void;
+    /** Whether any registered validator declared `'document'` scope. */
+    private hasDocumentScopedValidator;
+    /**
+     * Rebuild the kind buckets, unless they are already current.
+     *
+     * `register` used to rebuild them itself, so constructing an analyzer —
+     * which registers thirteen built-ins — rebuilt the whole table thirteen
+     * times and threw away the first twelve. A plugin registering a batch paid
+     * the same way. Registration now only marks the table stale and `analyze`
+     * rebuilds it at most once, whatever the batch size.
+     */
+    private rebuildDispatch;
+    /**
+     * Analyze a Red Tree and produce diagnostics — every node, from scratch.
+     *
+     * Also the base a later {@link analyzeWindow} builds on: the pass remembers
+     * which nodes carry diagnostics and which ones feed the document-scope
+     * maps, so the next edit can re-validate its window alone.
+     */
+    analyze(root: RedNode, source: string, tokensOrOptions?: TokenSource | {
+        tokens?: TokenSource;
+    }): IndexedAnalyzeResult;
+    /**
+     * Re-validate only what an edit could have changed, on top of the previous
+     * pass over this analyzer.
+     *
+     * `root` must be the tree the previous pass's root turned into through
+     * incremental reparses WITH red-subtree reuse — that is what makes every
+     * node outside `window` (the union of those reparses' windows, carried
+     * into `root`'s coordinates) the same object over the same text. The
+     * `DocumentModel` tracks exactly that and calls this only when it holds;
+     * anyone else should prefer `DocumentModel.analyzeIncremental`.
+     *
+     * Returns `null` when no window pass can be trusted: there is no previous
+     * pass, the validators or the tokens changed since it, or a validator with
+     * document scope is registered (see `Validator.scope`). The caller runs a
+     * full `analyze` then. The result's diagnostics are complete — the whole
+     * document's, identical to what a full pass would produce — and come out
+     * in document order like a full pass's do.
+     *
+     * What happens, in order:
+     *   1. descend the window (see `descendWindow`), collecting its candidates;
+     *   2. keep every previous candidate outside it that is still in the tree,
+     *      at its current offsets; derive the maps from kept plus fresh;
+     *   3. diff the maps against the previous ones for nodes outside the
+     *      window, and mark the nodes whose entry changed for re-validation;
+     *   4. move the kept diagnostics of displaced nodes by their displacement;
+     *   5. validate the window nodes and the marked ones;
+     *   6. assemble the collection from every diagnostic-bearing node.
+     */
+    analyzeWindow(root: RedNode, source: string, window: SourceSpan): IndexedAnalyzeResult | null;
+    /**
+     * The context validators see. The maps are ready-made; `allNodes` is
+     * built on demand and, being the one cross-document index a validator can
+     * reach without declaring itself, its use is recorded (see
+     * `Validator.scope`).
+     */
+    private makeContext;
+    /** Run every applicable validator over `nodes`, in order. */
+    private validateNodes;
+    private registerBuiltinValidators;
+    /**
+     * Create a validator for a specific tag/kind.
+     * Convenience method for plugin authors.
+     */
+    createValidator(code: string, severity: DiagnosticSeverity, predicate: (node: RedNode, ctx: AnalyzerContext) => string | null): Validator;
+}

package/dist/types/Semantic/index.d.ts

@@ -0,0 +1,2 @@
+export { SemanticAnalyzer } from './SemanticAnalyzer';
+export type { Validator, AnalyzerContext, AnalyzeResult } from './SemanticAnalyzer';

package/dist/types/Symbols/SymbolTable.d.ts

@@ -0,0 +1,47 @@
+/**
+ * DocumentEngine — SymbolTable
+ *
+ * Tracks symbols (definitions and references) in the document.
+ * Enables IDE features like:
+ * - Go to definition
+ * - Find all references
+ * - Rename symbol
+ * - Document outline
+ *
+ * In BBCode, symbols include:
+ * - [id=hero] → Definition
+ * - [goto=hero] → Reference
+ * - Named anchors and targets
+ */
+import { RedNode } from '../Syntax/RedNode';
+import type { SymbolInfo, SymbolSearchResult } from '../Types/symbols';
+export declare class SymbolTable {
+    private symbols;
+    private nodeToSymbolId;
+    /**
+     * Build the symbol table from a RedNode tree.
+     */
+    build(root: RedNode): void;
+    /**
+     * Get a symbol by name.
+     */
+    get(name: string): SymbolInfo | undefined;
+    /**
+     * Get the symbol associated with a node.
+     */
+    getSymbolForNode(nodeId: string): SymbolInfo | undefined;
+    /**
+     * Search for symbols by name.
+     */
+    search(query: string, maxResults?: number): SymbolSearchResult[];
+    /**
+     * Get all symbols.
+     */
+    getAll(): SymbolInfo[];
+    /**
+     * Clear all symbols.
+     */
+    clear(): void;
+    private addSymbol;
+    private createSymbolId;
+}

package/dist/types/Symbols/index.d.ts

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