@miliastry/quasar 1.0.6 → 1.1.0

package/dist/types/BBCode/BBCodeDocumentModel.d.ts

@@ -0,0 +1,92 @@
+/**
+ * DocumentEngine — BBCodeDocumentModel
+ *
+ * A DocumentModel subclass that uses the DocumentEngine's built-in
+ * BBCode Lexer + Parser to produce GreenNode/RedNode trees.
+ *
+ * This COMPLETELY replaces the old BBCode parser (MiliastryNovaFeatures/BBCode/Parser).
+ * The old parser is DEPRECATED.
+ *
+ * Architecture:
+ *   BBCode text
+ *     ↓ BBCodeLexer.scanBBCode()
+ *   BBCodeToken[]
+ *     ↓ Parser.parseTokensToGreen()
+ *   GreenNode
+ *     ↓ BBCodeToGreenNode.greenToRedNode()
+ *   RedNode
+ *     ↓ HTMLRenderer.render()
+ *   HTML preview
+ *
+ * Usage:
+ *   const model = new BBCodeDocumentModel({ source: '[b]Hello[/b]' })
+ *   const html = new HTMLRenderer().render(model.redRoot!)
+ */
+import { DocumentModel, type DocumentModelOptions } from '../Model/DocumentModel';
+import type { ReparseParseOptions } from '../Incremental/IncrementalParser';
+import { type InterningMode } from '../Syntax/GreenNodePool';
+import { GreenNode } from '../Syntax/GreenNode';
+import { RedNode } from '../Syntax/RedNode';
+import { type BBCodeDialect } from './BBCodeToGreenNode';
+import { HTMLRenderer } from '../Visitors/HTMLRenderer';
+export interface BBCodeDocumentModelOptions extends DocumentModelOptions {
+    /** Source BBCode text to parse */
+    source?: string;
+    /** Language identifier (default: 'bbcode') */
+    language?: string;
+    /** Enforce strict tag nesting (disables osu! auto-close legacy behavior) */
+    strictMode?: boolean;
+    /** BBCode dialect to parse against ('osu' | 'miliastry' | 'lyne'). Default: 'miliastry'. */
+    dialect?: BBCodeDialect;
+    /** Alias for dialect ('osu' | 'miliastry' | 'lyne') */
+    mode?: BBCodeDialect;
+    /**
+     * Deduplicate structurally identical green nodes across the document.
+     *
+     * Off by default. It is correct now — see the header of `GreenNodePool.ts`
+     * for why it was not — but it is a memory/latency trade, and this engine's
+     * declared budget is latency: on the 19.6 KB reference document `'leaves'`
+     * costs 16% more parse time to save 42% of the green tree's memory. Turn it
+     * on for workloads that hold many documents at once; leave it off to type
+     * into one.
+     */
+    interning?: InterningMode;
+}
+export declare class BBCodeDocumentModel extends DocumentModel {
+    private _strictMode;
+    private _dialect;
+    /** Per-document interner, or null when interning is off. */
+    private _interner;
+    /** Memoized parser `extraTags`, rebuilt only when the registry changes. */
+    private _extraTags;
+    private _extraTagsVersion;
+    constructor(options?: BBCodeDocumentModelOptions);
+    get dialect(): BBCodeDialect;
+    get root(): RedNode | null;
+    toHTML(renderer?: HTMLRenderer): string;
+    /**
+     * Parse BBCode text directly to a GreenNode tree using the
+     * DocumentEngine's built-in BBCode Lexer + Parser.
+     * No dependency on the deprecated old parser.
+     */
+    protected parseToGreen(source: string, options?: ReparseParseOptions): GreenNode;
+    /**
+     * Build a RedNode from a GreenNode, extracting metadata
+     * from BBCode attributes in the process.
+     */
+    protected buildRedFromGreen(green: GreenNode): RedNode;
+    /**
+     * Reuse-aware red build for the incremental path: adopts old red subtrees
+     * wherever the splice shared their green by reference. See the contract on
+     * `greenToRedNodeReusing` — the old tree is consumed.
+     */
+    protected buildRedFromGreenReusing(green: GreenNode, oldRed: RedNode, stats?: {
+        adopted: number;
+    }): RedNode;
+    /**
+     * Serialize the red tree back to BBCode, so `transact`/`undo`/`redo` can
+     * rebuild from text. Target 'miliastry' keeps native tags (gradient, grow,
+     * …) as-is instead of expanding them, which is what round-tripping needs.
+     */
+    protected exportSource(root: RedNode): string;
+}

package/dist/types/BBCode/BBCodeToGreenNode.d.ts

@@ -0,0 +1,111 @@
+/**
+ * DocumentEngine — BBCodeToGreenNode
+ *
+ * Bridge between the existing BBCode Parser (BBBlock[]) and the
+ * DocumentEngine's GreenNode/RedNode syntax tree.
+ *
+ * This is how we integrate the mature, battle-tested BBCode parser
+ * with the new Language Platform architecture.
+ *
+ * The flow:
+ *   BBCode text
+ *   → parseBBCode() [existing] → BBBlock[]
+ *   → convertToGreenNode() [this] → GreenNode
+ *   → buildRedNode() [this] → RedNode
+ *   → DocumentModel
+ */
+import { GreenNode } from '../Syntax/GreenNode';
+import { RedNode } from '../Syntax/RedNode';
+import { RedNodeStore } from '../Syntax/RedNodeStore';
+import type { NodeKind } from '../Types/core';
+export type BBCodeDialect = 'osu' | 'miliastry' | 'lyne';
+export declare const BBCODE_TAG_NAMES: readonly string[];
+export declare function getBBCodeTagNames(dialect?: BBCodeDialect): readonly string[];
+export declare function tagToNodeKind(tag: string | null, dialect?: BBCodeDialect): NodeKind;
+export declare function nodeKindToTag(kind: NodeKind): string | null;
+export declare function isBlockKind(kind: NodeKind): boolean;
+export interface BBBlock {
+    id: string;
+    tag: string | null;
+    attrs: string;
+    content: string;
+    rawStart: number;
+    rawEnd: number;
+    children: BBBlock[];
+    attrChildren?: BBBlock[];
+    html?: string;
+}
+/**
+ * Convert a single BBBlock to a GreenNode.
+ * Recursively converts children.
+ */
+export declare function bbBlockToGreenNode(block: BBBlock): GreenNode;
+/**
+ * Convert an array of BBBlock[] (the root of the existing parser's output)
+ * to a GreenNode tree.
+ *
+ * Note: This function is kept for backward compatibility with the old parser.
+ * The new DocumentEngine parser (Parser.ts + BBCodeLexer) produces GreenNode
+ * directly and does NOT go through BBBlock[].
+ */
+export declare function bbBlocksToGreenTree(blocks: BBBlock[], source: string): GreenNode;
+export declare function extractGreenNodeMetadata(green: GreenNode): Record<string, unknown>;
+/**
+ * Build a RedNode tree from a GreenNode.
+ * Similar to TreeBuilder.buildRed but uses actual kind from the green node
+ * and extracts BBCode metadata from attributes.
+ *
+ * When a RedNodeStore is provided, instance RedNodes are created with
+ * correct parent references copied from the canonical's metadata.
+ * The canonicalId (from green._hash) enables:
+ * - React.memo in BBCodeCanvas by canonicalId
+ * - HTMLRenderer cache by canonicalId
+ * - Diff optimization (same canonicalId = unchanged subtree)
+ * - Future PositionRef-based sharing
+ */
+export declare function greenToRedNode(green: GreenNode, parent?: RedNode | null, store?: RedNodeStore, start?: number): RedNode;
+/**
+ * Build the red tree for `green`, adopting subtrees of the PREVIOUS red tree
+ * wherever the new green shares a green node by reference with the old one.
+ *
+ * The incremental splice (`spliceGreen`) rebuilds only the spine of ancestors
+ * around an edit; every untouched sibling keeps its exact green object. Yet
+ * `greenToRedNode` reconstructed all ~1700 red nodes on every keystroke —
+ * measured as the single largest phase of a keystroke (0.30 of 0.94 ms).
+ * Reference equality of greens is proof the subtree did not change, so its old
+ * red subtree — ids, metadata, diagnostics and all — can be adopted wholesale.
+ * Adoption is one `parent` reassignment (done by `initChildren`) plus, only
+ * when the subtree moved, a `setStart` walk that adds a delta to two ints per
+ * node. Both are far cheaper than re-extracting metadata and reallocating.
+ *
+ * ⚠ Contract: the OLD red tree is consumed. Adopted subtrees are reparented
+ * into the new tree, so the previous `redRoot` must not be used again after
+ * this returns. Nothing in the engine or the app reads a superseded red tree
+ * (verified), and `DocumentModelOptions.reuseRed` is the kill-switch if a
+ * future consumer ever needs the old tree to stay intact.
+ *
+ * The child walk mirrors `NodeMatcher` Phase 0 / `preserveNodeIds`: trim the
+ * common prefix and suffix by green reference, descend into the changed window
+ * only when it is the single-child shape a keystroke produces, and build the
+ * rest fresh. Positional lockstep also makes double-adoption impossible: each
+ * old red child is adopted at most once, even when interning makes distinct
+ * positions share one green object.
+ */
+export declare function greenToRedNodeReusing(green: GreenNode, oldRed: RedNode, start?: number, stats?: {
+    adopted: number;
+}): RedNode;
+/**
+ * A `RedNodeStore` wired with BBCode metadata semantics.
+ *
+ * `RedNodeStore` used to carry its own verbatim copy of
+ * `extractGreenNodeMetadata` — its comment even said *"Mirrors
+ * extractGreenNodeMetadata"* — which meant two sources of truth for the
+ * attrs→metadata mapping, and they had already drifted apart. The store now
+ * takes the extractor as a dependency; this is the BBCode wiring.
+ */
+export declare function createBBCodeRedNodeStore(): RedNodeStore;
+/**
+ * Convert a BBBlock array directly to a RedNode root.
+ * This is the main entry point for the bridge.
+ */
+export declare function bbBlocksToRedTree(blocks: BBBlock[], source: string): RedNode;

package/dist/types/BBCode/Parser.d.ts

@@ -0,0 +1,78 @@
+/**
+ * DocumentEngine — BBCode Parser
+ *
+ * Builds a GreenNode (immutable syntax tree) from BBCode tokens.
+ *
+ * This is the core parsing logic that replaces the old BBCode parser.
+ * Unlike the old parser, this produces GreenNode directly — no BBBlock[]
+ * intermediate step. The flow is:
+ *
+ *   BBCode text
+ *     ↓ scanBBCode() [BBCodeLexer]
+ *   BBCodeToken[]
+ *     ↓ parseTokensToGreen() [this]
+ *   GreenNode
+ *     ↓ greenToRedNode()
+ *   RedNode
+ *
+ * Key differences from the old parser:
+ * - Newlines are explicit tokens (not mixed into text) → precise empty_line detection
+ * - All syntactically valid tags are parsed (not just BLOCK_TAGS)
+ * - Produces GreenNode directly (no BBBlock[] intermediate)
+ * - No newline stripping between block-level tags
+ * - Consecutive newlines (2+) = empty_line node (paragraph break)
+ * - Single newlines between inline content = ignored (CSS handles spacing)
+ */
+import { GreenNode } from '../Syntax/GreenNode';
+import type { NodeKind } from '../Types/core';
+import { GreenNodePool } from '../Syntax/GreenNodePool';
+import { type BBCodeDialect } from './BBCodeToGreenNode';
+import type { BBCodeToken } from '../Lexer/BBCodeLexer';
+/**
+ * Parse BBCode tokens into a GreenNode tree.
+ *
+ * @param tokens  Flat array of tokens from scanBBCode()
+ * @param source  Original source text (used for fallback error text)
+ * @returns       A GreenNode tree with 'document' as root
+ */
+export interface ParseOptions {
+    strictMode?: boolean;
+    /** BBCode dialect to parse against ('osu' | 'miliastry' | 'lyne'). Default: 'miliastry'. */
+    dialect?: BBCodeDialect;
+    /** Optional interner for structural sharing. If provided, identical subtrees
+     *  share the same GreenNode reference in memory. */
+    interner?: GreenNodePool;
+    /**
+     * Group top-level inline nodes into `paragraph` nodes. Default `true`.
+     *
+     * Paragraph grouping happens at the ROOT ONLY — inside `[centre]` or `[box]`
+     * the children stay flat. So when the incremental parser re-parses the inner
+     * span of such a container in isolation, that span's content is not root
+     * content and must not be grouped, or the re-parsed subtree would gain
+     * paragraphs the full parse never produces.
+     */
+    normalizeParagraphs?: boolean;
+    /**
+     * Plugin-registered tags: tag name → the kind their nodes get.
+     *
+     * The built-in table deliberately turns unknown tags into literal text
+     * (`[Gateron]` in prose must stay visible), which also meant a plugin's tag
+     * could render and export but never PARSE. This is the missing link: a tag
+     * present here parses as a normal paired container. `BBCodeDocumentModel`
+     * fills it from the `TagRegistry`'s non-builtin entries; everything not
+     * registered still falls to literal text exactly as before.
+     */
+    extraTags?: ReadonlyMap<string, NodeKind>;
+}
+export declare function parseTokensToGreen(tokens: BBCodeToken[], source: string, options?: ParseOptions): GreenNode;
+/**
+ * Full parse: BBCode text → GreenNode.
+ *
+ * Convenience function that combines the lexer and parser.
+ * BBCodeDocumentModel internally uses scanBBCode() + parseTokensToGreen() directly.
+ *
+ * Usage:
+ *   import { parseBBCode } from '../BBCode/Parser'
+ *   const tree = parseBBCode('[b]Hello[/b]')
+ */
+export declare function parseBBCode(source: string, options?: ParseOptions): GreenNode;

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

@@ -0,0 +1,4 @@
+export { BBCodeDocumentModel } from './BBCodeDocumentModel';
+export { parseBBCode, parseTokensToGreen } from './Parser';
+export { bbBlocksToGreenTree, greenToRedNode, bbBlocksToRedTree, bbBlockToGreenNode, tagToNodeKind, nodeKindToTag, isBlockKind, } from './BBCodeToGreenNode';
+export type { BBBlock } from './BBCodeToGreenNode';

package/dist/types/Collab/positions.d.ts

@@ -0,0 +1,55 @@
+/**
+ * DocumentEngine — Position transforms
+ *
+ * Where does a position end up after a text edit?
+ *
+ * This is the primitive collaboration stands on: keeping carets, selections
+ * and remote cursors pointing at the same *content* while the text shifts
+ * under them — whether the edit came from the local user, a remote peer, or
+ * a programmatic `transact`. See `QuasarCollab.MD` for the architecture; the
+ * short version is that Quasar syncs TEXT, so mapping positions through
+ * `TextChange`s is all the transform machinery the engine needs. This module
+ * transforms positions, not changes-against-changes: convergence of
+ * concurrent edits is the CRDT's job, not ours.
+ */
+import type { TextChange } from '../Incremental/ChangeTracker';
+/**
+ * Which side a position sticks to when an edit happens exactly at it.
+ *
+ * A caret usually wants `'right'`: text inserted at the caret by someone else
+ * should push it forward (you keep typing after their insertion). The start
+ * of a persistent highlight usually wants `'left'`: text inserted exactly at
+ * its start belongs before the highlight, not inside it.
+ */
+export type TransformBias = 'left' | 'right';
+/**
+ * Map `offset` through one change or an ordered sequence of changes.
+ *
+ * Rules, in order:
+ * - strictly before the edit → unchanged;
+ * - strictly after the replaced span → shifted by the length delta;
+ * - inside the replaced span → collapsed to the edit's boundary (`'left'` →
+ *   where the replacement starts, `'right'` → where it ends). A position
+ *   inside deleted text has no content to point at anymore; the boundary is
+ *   the only honest answer;
+ * - exactly at a pure insertion point → `bias` decides which side of the
+ *   inserted text it lands on.
+ */
+export declare function transformOffset(offset: number, changes: TextChange | readonly TextChange[], bias?: TransformBias): number;
+/**
+ * Map a `{start, end}` range through one change or a sequence.
+ *
+ * The start sticks RIGHT and the end sticks LEFT, which is what preserves the
+ * selected content: text inserted exactly at a boundary lands OUTSIDE the
+ * range, so the range keeps covering exactly the characters it covered — it
+ * neither absorbs a neighbour's insertion nor leaks its own content. The
+ * result is clamped so it can never come out inverted; a range entirely
+ * inside deleted text collapses to a point at the edit boundary.
+ */
+export declare function transformRange(range: {
+    start: number;
+    end: number;
+}, changes: TextChange | readonly TextChange[]): {
+    start: number;
+    end: number;
+};

package/dist/types/Commands/Command.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DocumentEngine — Command
+ *
+ * Commands are high-level user actions that MAY produce
+ * a Transaction (or multiple) to modify the document.
+ *
+ * Commands are stateless — they receive context and produce operations.
+ * This makes them testable, undoable, and safe for AI use.
+ *
+ * Inspired by ProseMirror's Commands and VSCode's Command system.
+ */
+import { DocumentModel } from '../Model/DocumentModel';
+import type { Operation } from '../Types/operations';
+import type { RedNode } from '../Syntax/RedNode';
+export interface CommandContext {
+    model: DocumentModel;
+    root: RedNode;
+    selection?: {
+        nodeId: string;
+        start: number;
+        end: number;
+    };
+}
+export type CommandResult = {
+    success: boolean;
+    operations?: Operation[];
+    message?: string;
+};
+export interface Command {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly shortcut?: string;
+    execute(ctx: CommandContext): CommandResult;
+    canExecute?(ctx: CommandContext): boolean;
+}
+export declare function canExecute(command: Command, ctx: CommandContext): boolean;

package/dist/types/Commands/CommandRegistry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DocumentEngine — CommandRegistry
+ *
+ * Central registry for all document commands.
+ * Commands can be added by plugins.
+ *
+ * Enables:
+ * - Keyboard shortcut binding
+ * - Toolbar integration
+ * - AI command execution
+ * - Menu integration
+ */
+import type { Command, CommandContext, CommandResult } from './Command';
+export declare class CommandRegistry {
+    private commands;
+    /**
+     * Register a command.
+     */
+    register(command: Command): void;
+    /**
+     * Unregister a command.
+     */
+    unregister(id: string): void;
+    /**
+     * Get a command by ID.
+     */
+    get(id: string): Command | undefined;
+    /**
+     * Check if a command is registered.
+     */
+    has(id: string): boolean;
+    /**
+     * Execute a command by ID.
+     */
+    execute(id: string, ctx: CommandContext): CommandResult;
+    /**
+     * Get all registered commands.
+     */
+    getAll(): Command[];
+    /**
+     * Get commands by a filter function.
+     */
+    filter(predicate: (cmd: Command) => boolean): Command[];
+    /**
+     * Get the count of registered commands.
+     */
+    get size(): number;
+}

package/dist/types/Commands/DeleteNode.d.ts

@@ -0,0 +1,7 @@
+/**
+ * DocumentEngine — DeleteNode Command
+ *
+ * Deletes a node from the document tree.
+ */
+import type { Command } from './Command';
+export declare const DeleteNode: Command;

package/dist/types/Commands/InsertText.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DocumentEngine — InsertText Command
+ *
+ * Inserts text at the current cursor position.
+ * Creates or reuses a text node.
+ */
+import type { Command } from './Command';
+export declare const InsertText: Command;

package/dist/types/Commands/SplitMerge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DocumentEngine — SplitNode & MergeNodes Commands
+ *
+ * Split a node at a position, or merge two adjacent nodes.
+ * Essential for block editing and backspace handling.
+ */
+import type { Command } from './Command';
+export declare const SplitNode: Command;
+export declare const MergeNode: Command;

package/dist/types/Commands/WrapInTag.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DocumentEngine — WrapInTag Command
+ *
+ * Wraps the current selection in a BBCode tag.
+ * E.g. selected text → [b]selected text[/b]
+ */
+import type { Command } from './Command';
+export declare const WrapInTag: Command;

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

@@ -0,0 +1,6 @@
+export { CommandRegistry } from './CommandRegistry';
+export type { Command, CommandContext, CommandResult } from './Command';
+export { InsertText } from './InsertText';
+export { DeleteNode } from './DeleteNode';
+export { WrapInTag } from './WrapInTag';
+export { SplitNode, MergeNode } from './SplitMerge';

package/dist/types/Diff/TreeDiffer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * DocumentEngine — TreeDiffer
+ *
+ * Computes structural differences between two Red Trees.
+ * Produces a list of DiffOperations that can be used for:
+ * - Updating the UI with minimal DOM changes
+ * - Syncing with collaboration servers
+ * - Animation interpolation
+ * - Undo/redo granularity
+ *
+ * Inspired by React's reconciliation and ProseMirror's diff.
+ */
+import { RedNode } from '../Syntax/RedNode';
+export type DiffKind = 'insert' | 'delete' | 'update' | 'move' | 'preserve';
+export interface DiffOperation {
+    kind: DiffKind;
+    node: RedNode;
+    oldNode?: RedNode;
+    /** Index in parent */
+    oldIndex?: number;
+    newIndex?: number;
+    /** Parent node ID */
+    parentId?: string;
+}
+export interface DiffResult {
+    operations: DiffOperation[];
+    /** Count by kind */
+    stats: {
+        inserts: number;
+        deletes: number;
+        updates: number;
+        moves: number;
+        preserves: number;
+    };
+    /** Time taken in ms */
+    duration: number;
+}
+export declare class TreeDiffer {
+    /**
+     * Compute the diff between two Red Trees.
+     */
+    diff(oldRoot: RedNode, newRoot: RedNode): DiffResult;
+    private diffChildren;
+    /**
+     * Check if a node's content has changed.
+     */
+    private nodeContentChanged;
+    /**
+     * Deep equality check for content equivalence when pairing unmatched nodes.
+     */
+    private nodesAreEquivalent;
+}

package/dist/types/Diff/__tests__/TreeDiffer.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+export { TreeDiffer } from './TreeDiffer';
+export type { DiffOperation, DiffKind, DiffResult } from './TreeDiffer';