@miliastry/quasar 1.0.6 → 1.1.0

package/dist/types/Visitors/HTMLRenderer.d.ts

@@ -0,0 +1,380 @@
+/**
+ * DocumentEngine — HTMLRenderer
+ *
+ * Renders the Document Model to HTML for preview.
+ * This is the main renderer for the visual BBCode preview.
+ *
+ * Uses the TagRegistry for custom rendering.
+ * Plugins can register custom renderers for preview components.
+ */
+import { RedNode } from '../Syntax/RedNode';
+import { Visitor } from './Visitor';
+import type { TagRegistry } from '../Model/TagRegistry';
+import type { BBCodeDialect } from '../BBCode/BBCodeToGreenNode';
+import { type TokenResolverFn, type TokenSource } from '../Tokens';
+export interface HTMLRendererOptions {
+    /**
+     * Replicate osu! forum BBCode spacing quirks.
+     * Defaults to true for full compatibility with Miliastry.
+     * Set to false for a more logical, predictable rendering engine.
+     */
+    osuBehaviour?: boolean;
+    /** Registry for resolving custom tags */
+    registry?: TagRegistry;
+    /** BBCode dialect to render for ('osu' | 'miliastry' | 'lyne') */
+    dialect?: BBCodeDialect;
+    /** Visual theme for markup classes ('osu' | 'lyne' | 'miliastry') */
+    theme?: 'osu' | 'lyne' | 'miliastry';
+    /** Safe media proxy callback to rewrite image and media URLs */
+    mediaProxy?: (url: string) => string;
+    /** Resolver for entity links like profile, guild, map */
+    entityLinkResolver?: (kind: string, value: string) => {
+        href: string;
+        external?: boolean;
+    } | null;
+    /**
+     * Forum-style `@mention` linkifier. Called with the bare name (no `@`);
+     * return null to leave the mention as plain text. Used by forum hosts that
+     * linkify `@username` to a profile route.
+     */
+    mentionResolver?: (name: string) => {
+        href: string;
+        external?: boolean;
+    } | null;
+    /**
+     * Timestamp chip linkifier (`1:23`, `01:23.456`, `01:23:456`). Called with
+     * the millisecond offset and the display label; return null to leave the
+     * timestamp as plain text. Used by map hosts that deep-link into an editor.
+     */
+    timestampResolver?: (ms: number, label: string) => {
+        href: string;
+        external?: boolean;
+    } | null;
+    /** Design tokens or resolver function */
+    tokens?: TokenSource;
+}
+export declare class HTMLRenderer extends Visitor<string> {
+    private tokenResolver?;
+    private options;
+    constructor(options?: HTMLRendererOptions);
+    setTokens(tokens?: TokenSource): void;
+    getTokenResolver(): TokenResolverFn | undefined;
+    private readonly BLOCK_TAGS;
+    private readonly INLINE_TAGS;
+    /**
+     * The ` data-node-id="…"` attribute, or `''` for nodes nobody looks up.
+     *
+     * ─── Why this is not emitted on everything ──────────────────────────────
+     *
+     * It used to be, carrying `node.id` — a process-global counter minted per
+     * RedNode, so a reparse renames every node in the document. Measured on a
+     * one-character edit: zero ids survive.
+     *
+     * `DOMMorpher` already noted that this rules the ids out as morph KEYS. The
+     * larger cost is that it also breaks the morpher's prefix/suffix trim, which
+     * uses `isEqualNode` — a comparison that includes attributes. An attribute
+     * that always differs makes every element compare unequal, so the trim never
+     * fires and the morpher walks the whole document. Measured on one keystroke
+     * in the reference document: **1665 `setAttribute` calls across 1725
+     * elements**, to write new numbers meaning the same thing, when the actual
+     * change was 10 insertions and 9 removals.
+     *
+     * ─── Why BLOCKS, and not stable ids ─────────────────────────────────────
+     *
+     * Making the id stable was the obvious repair and it does not work. Keying on
+     * the node's SPAN was measured: an edit at the END drops the writes to 6, but
+     * an insertion shifts every offset after it, so an edit near the START still
+     * cost 1637 — and spans are longer strings than `nN`, so the emitted HTML grew
+     * 10%. Stability under insertion is not something a position can have.
+     *
+     * The real observation is that no consumer ever wanted these on inline nodes.
+     * Both readers in the app are block-level: `usePreviewClick` walks up with
+     * `closest('[data-node-id]')` for *block selection*, and `useBlockHighlight`
+     * highlights and scrolls to a *block*. Emitting ids on the per-character
+     * spans of a gradient did not just cost — it made `closest()` stop at a
+     * character instead of the block the click meant.
+     *
+     * So the attribute goes where it is read. Inline nodes carry no id, compare
+     * equal, and let `isEqualNode` skip their subtrees natively; the handful of
+     * block containers that do carry one are few enough that their churn is
+     * noise.
+     */
+    /**
+     * Text leaves emit their content directly, with no wrapper element.
+     *
+     * They used to come wrapped in `<span class="bb-text">` — one extra DOM
+     * element per text leaf, which is HALF the preview's elements (measured:
+     * 1726 → 851 on a 19.6 KB post, 17251 → 8510 on a 196 KB one). The class
+     * earned none of it: it has no CSS rule anywhere in the repo, carries no
+     * `data-node-id` (text is not an id-bearing kind, so click mapping and
+     * highlighting never looked at it), and every style a text leaf can have
+     * still emits its own `<span style="…">` below.
+     *
+     * A/B in a production build, steady state: flush 41.4 → 39.7 ms at 19.6 KB
+     * and 55.4 → 46.4 ms at 196 KB, plus ~27% less HTML to serialize and parse.
+     */
+    private textWrap;
+    /**
+     * A qué elementos se les pone `data-node-id`.
+     *
+     * `'all'` (por defecto) — a todos. Es lo que permite que un clic en
+     * CUALQUIER punto del preview señale ese nodo exacto en el editor: en un
+     * degradado cada carácter es su propio nodo, y sin id no hay nada a lo que
+     * `closest()` pueda agarrarse.
+     *
+     * Esto estuvo desactivado por una buena razón que ya no aplica. Los ids se
+     * regeneraban en cada parseo, así que el atributo cambiaba en TODOS los
+     * elementos por pulsación: `isEqualNode` no casaba nunca, el morpher no
+     * podía saltarse ningún subárbol y se medían 1665 `setAttribute` sobre 1725
+     * elementos para escribir números nuevos que significaban lo mismo. Con la
+     * identidad estable entre reparseos eso desapareció: un nodo que no cambia
+     * conserva su id, su HTML es idéntico y el camino rápido del morpher sigue
+     * funcionando.
+     *
+     * El coste que queda es el tamaño: ~10 bytes por elemento, que hay que
+     * serializar y parsear. Medido con A/B en la misma sesión sobre el post con
+     * degradados (19,6 KB, 852 elementos):
+     *
+     *   solo bloques (9 con id):   latencia 48 ms · p95  72 ms
+     *   todos      (808 con id):   latencia 56 ms · p95 104 ms
+     *
+     * Se paga a propósito: la precisión del clic es una función que se pidió, y
+     * 56 ms sigue holgadamente dentro de lo que se percibe como inmediato.
+     * `'blocks'` queda disponible para quien priorice la latencia, y `'none'`
+     * para los consumidores de solo lectura (foros, render estático): sin
+     * `data-node-id` en absoluto, el HTML es más pequeño y no hay nada que
+     * mantenga vivos los nodos del árbol.
+     */
+    static idMode: 'blocks' | 'all' | 'none';
+    /**
+     * Nesting depth of `[tables]` while rendering. `[col]`/`[row]`/`[th]` are
+     * table cells only INSIDE a `[tables]`; orphaned ones (e.g. `[col]` inside
+     * `[columns]`, or stray cells) render as plain inline spans — the same rule
+     * LYNE's forum renderer applies.
+     */
+    private tableDepth;
+    private idAttr;
+    /**
+     * Kinds that carry `data-node-id`.
+     *
+     * The block containers a user can select or be scrolled to, plus the media
+     * nodes, which are atomic and clickable in their own right. Deliberately NOT
+     * `text` or any inline formatting kind — see {@link idAttr}.
+     */
+    private static readonly ID_BEARING_KINDS;
+    visit(node: RedNode): string;
+    /**
+     * Ancho de cada tabla abierta, apilado igual que `tableDepth`.
+     *
+     * `getTableContext` corre una vez POR CELDA y recorría todas las filas de
+     * la tabla en cada llamada, con un `.filter()` —y su array— por fila: una
+     * tabla de 20×20 hacía 8.000 arrays intermedios por renderizado para
+     * llegar 400 veces al mismo número. Ahora se calcula una vez al entrar en
+     * la tabla. Va en una pila y no en un caché por nodo porque los hijos de un
+     * `RedNode` SON mutables (`appendChild`/`removeChild`), así que la
+     * identidad del nodo no garantiza que su estructura siga siendo la misma
+     * entre renderizados.
+     */
+    private maxColsStack;
+    render(root: RedNode): string;
+    /**
+     * Render every child and concatenate.
+     *
+     * Replaces the `children.map(c => this.renderNode(c)).join('')` idiom, which
+     * was repeated at 16 call sites and allocated a closure plus an intermediate
+     * array of N strings at every level of the tree. Appending to one string lets
+     * the engine use its rope representation instead.
+     */
+    /**
+     * Render the direct children of `node` to HTML (no wrapper element).
+     *
+     * Public so the incremental preview (`BlockPatcher`) can morph a block
+     * element's inner content without re-rendering the whole document.
+     */
+    renderChildren(node: RedNode): string;
+    private renderNode;
+    /** osu! quirk: newlines immediately preceding a [code] block are completely ignored */
+    private isNextCodeBlock;
+    /** Checks if this is the LAST empty_line right before a code block (skipping only spacing) */
+    private isImmediateEmptyLineBeforeCode;
+    private isPrevBlockBoundary;
+    private isTrailingBlockBoundary;
+    private renderError;
+    private wrapInline;
+    private wrapBlock;
+    /** Characters `escapeHtml` has to rewrite. Non-global on purpose: `test` must not carry `lastIndex`. */
+    private static readonly HTML_ESCAPE_RE;
+    private static readonly NAMED_COLORS;
+    /** Keyword-or-number CSS values (font-weight, font-style, text-decoration). */
+    private isCssKeyword;
+    /** Read a metadata field, falling back to the raw tag attribute. */
+    private colorStyle;
+    private fontSizeStyle;
+    private fontStyle;
+    private renderLink;
+    private renderProfile;
+    private renderEntity;
+    /**
+     * El aviso que ocupa el sitio de un medio que no se puede pintar.
+     *
+     * Lleva `data-bb-empty` con la etiqueta de origen porque el camino
+     * HTML→BBCode lee de vuelta lo que hay en el lienzo: sin la marca, el texto
+     * del aviso entraba al documento como contenido y se comía la etiqueta. En
+     * `docs/ai/hxovc.bbcode`, con cinco `[img][/img]` vacíos, cada edición del
+     * bloque convertía otro en la frase «[img] missing source URL».
+     */
+    private mediaError;
+    private renderImage;
+    private renderVideo;
+    private renderAudio;
+    private hexToRgba;
+    private renderNotice;
+    private renderTables;
+    /** Celdas directas de una fila, sin materializar un array intermedio. */
+    private static countCells;
+    /**
+     * Columnas de la tabla más ancha bajo `tableNode`, memoizado por tabla.
+     *
+     * `getTableContext` se llama una vez POR CELDA, y recorría todas las filas
+     * de la tabla en cada llamada, con un `.filter()` —y su array— por fila.
+     * Una tabla de 20×20 hacía 8.000 arrays intermedios en cada renderizado
+     * para llegar 400 veces al mismo número. El caché se vacía al empezar cada
+     * render, así que no retiene nodos entre documentos.
+     */
+    private static widestRow;
+    private getTableContext;
+    private renderGallery;
+    private renderColumns;
+    private renderSeparator;
+    private renderScroll;
+    private renderAbbr;
+    private renderTooltip;
+    private renderRaw;
+    private renderPlain;
+    private renderAlign;
+    private renderEffect;
+    private renderAnim;
+    private renderContainer;
+    private static readonly STYLE_PROP_WHITELIST;
+    private renderStyleTag;
+    private renderQuote;
+    private renderSpoilerbox;
+    private renderBox;
+    /**
+     * Marca un `[box]`/`[spoilerbox]` sin título propio.
+     *
+     * El `<summary>` siempre lleva texto ("Box", "Spoiler"), así que sin esta
+     * marca el camino HTML→BBCode leía ese relleno como si el autor lo hubiera
+     * escrito y devolvía `[box=Box]`.
+     */
+    private bareTitleAttr;
+    private renderTitle;
+    /**
+     * `[box=Title:#hex]`, `[tables=striped:#hex]`, `[columns=2:#hex]` → un
+     * ` style="--<suffix>-accent:#hex;"` del que el CSS deriva la paleta
+     * (título + chevron y borde en boxw; gradientes/header/hover en tables;
+     * borde + fondo en columns). Devuelve '' si no hay color válido.
+     */
+    private boxAccentStyle;
+    private renderList;
+    private renderListItem;
+    private renderCode;
+    private renderSVG;
+    /**
+     * Render an osu! BBCode imagemap.
+     *
+     * Structure:
+     *   [imagemap]
+     *   https://example.com/image.png    ← first line = image URL
+     *   10 20 50 60 https://... Label    ← subsequent lines = clickable areas
+     *   [/imagemap]
+     *
+     * Each area line format: x y width height url [label]
+     * All values are PERCENTAGES (0–100) relative to the image dimensions.
+     * Uses CSS absolute positioning with percentage coordinates.
+     */
+    private renderImagemap;
+    private collectNodeText;
+    /**
+     * Effect parameters off a node, with every colour re-validated.
+     *
+     * `startsWith('#')` was NOT a filter: `#a" onmouseover="alert(1)` passes
+     * it. Every stop has to survive the full colour allowlist or be dropped,
+     * because these values end up inside a `style` attribute.
+     */
+    private effectParams;
+    /** Text inside an effect node, ignoring layout-only children. */
+    /**
+     * The plain text an effect modulates, line breaks included.
+     *
+     * A break is a childless `spacing` leaf carrying no text, so collecting
+     * it naively contributes nothing and the effect sees one long line.
+     * Every two-dimensional axis then collapses: `line` reports zero for
+     * the whole block, `column` stretches one row across the paragraph, and
+     * `radial` measures a rectangle one line tall. The break was being
+     * dropped from the OUTPUT as well, so a multi-line effect previewed as
+     * a single run-on line.
+     *
+     * The document's own plain text spells a break `\n` — that is what
+     * `stripColorWrappers` and the studio's sampler both count — so this
+     * agrees with them rather than inventing a third answer.
+     */
+    private effectText;
+    private effectChildText;
+    /**
+     * Paint an effect's computed segments as spans.
+     *
+     * Shared by rainbow, grow and any modulated gradient, so the preview
+     * shows exactly the colours and sizes the BBCode export will contain
+     * rather than an approximation of them.
+     */
+    private renderEffectSegments;
+    /**
+     * A gradient previews as a real CSS gradient when it is a plain
+     * left-to-right ramp, and as computed per-character spans otherwise.
+     *
+     * The CSS path is genuinely smoother — it interpolates per pixel rather
+     * than per glyph — but it can only express a linear sweep. A gradient
+     * with a waveform, a non-index axis or quantisation steps looked
+     * nothing like its own export while this was the only path.
+     */
+    private renderGradient;
+    /**
+     * Escape for both text content and double-quoted attribute values.
+     *
+     * `'` is included because attribute values elsewhere in the codebase (and in
+     * consumer-supplied tag handlers) may be single-quoted; leaving it raw makes
+     * the escaping context-dependent, which is how injections get reintroduced.
+     */
+    /**
+     * Escape the five HTML-significant characters.
+     *
+     * Was five chained `.replace(/x/g, …)` calls: five full scans of the string
+     * and up to five intermediate allocations for *every* text node, even though
+     * ordinary prose contains none of these characters. This tests once and
+     * returns the input untouched in that common case, then does a single pass
+     * when there is actually something to escape.
+     */
+    /** Resolver configured at construction (read through a getter for brevity). */
+    private get mentionResolver();
+    /**
+     * `@mention` shape used by forum hosts: 3-15 word chars, boundaries that
+     * exclude longer usernames (same rule LYNE's forum uses). Non-global so
+     * `lastIndex` never leaks between calls.
+     */
+    private static readonly MENTION_RE;
+    /**
+     * Linkify a plain-text leaf: `@mention` runs and (optionally) timestamp
+     * chips. Both run through their resolver; null leaves the run as text.
+     * Every interpolated string is HTML-escaped, and hrefs with dangerous
+     * protocols (javascript:, data:, vbscript:) are rejected (defence in depth;
+     * the resolvers themselves should never produce one).
+     */
+    private linkifyText;
+    /** `1:23`, `01:23.456`, `01:23:456` — the editor deep-link shape. */
+    private static readonly TS_RE;
+    private linkifyTimestamps;
+    /** Root-relative, http(s), mailto and line:// hrefs are the only safe shapes. */
+    private isSafeHref;
+    private escapeHtml;
+}

package/dist/types/Visitors/JSONExporter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DocumentEngine — JSONExporter
+ *
+ * Exports the Document Model to JSON.
+ * Useful for:
+ * - Saving/loading documents in a structured format
+ * - Sending over the wire (collaboration)
+ * - Debugging and inspecting the document tree
+ * - Import/export between different tools
+ */
+import { RedNode } from '../Syntax/RedNode';
+import { Visitor } from './Visitor';
+export interface JSONDocument {
+    version: number;
+    kind: string;
+    nodes: JSONNode[];
+    metadata?: Record<string, unknown>;
+}
+export interface JSONNode {
+    id: string;
+    kind: string;
+    text: string;
+    version: number;
+    children: JSONNode[];
+    attributes?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+export declare class JSONExporter extends Visitor<string> {
+    /**
+     * Export a RedNode tree to a JSON string.
+     */
+    visit(node: RedNode): string;
+    /**
+     * Export to a JSON object.
+     */
+    toJSON(node: RedNode): JSONDocument;
+    private serializeNode;
+}

package/dist/types/Visitors/MarkdownExporter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DocumentEngine — MarkdownExporter
+ *
+ * Exports the Document Model to Markdown with hybrid BBCode embedding
+ * for features not natively supported in standard CommonMark (color, size,
+ * underline, alignment, collapsible boxes).
+ */
+import { RedNode } from '../Syntax/RedNode';
+import { Visitor } from './Visitor';
+export declare class MarkdownExporter extends Visitor<string> {
+    visit(node: RedNode): string;
+    export(node: RedNode): string;
+    private exportNode;
+    private renderTitleMarkdown;
+    /**
+     * Read a BBCode tag's `=VALUE` attribute.
+     */
+    /**
+     * El atributo del nodo, o `undefined` si no lleva.
+     *
+     * El recorte lo hace `nodeAttrValue`, el mismo lector del `HTMLRenderer`;
+     * aquí sólo se cambia el contrato del caso vacío. Este exportador encadena
+     * `metadata ?? atributo ?? contenido`, así que necesita un `undefined`
+     * explícito donde `nodeAttrValue` devuelve el texto crudo — es la única
+     * diferencia, y por eso no se llama directamente.
+     */
+    private extractValue;
+}

package/dist/types/Visitors/SVGRenderer.d.ts

@@ -0,0 +1,16 @@
+import { RedNode } from '../Syntax/RedNode';
+import { Visitor } from './Visitor';
+import type { VisitorContext } from './Visitor';
+/**
+ * SVGRenderer (Runtime ForeignObject Strategy)
+ *
+ * Instead of attempting to calculate CSS layouts manually,
+ * this runtime renderer wraps the exact HTML output in an SVG <foreignObject>.
+ *
+ * This gives 100% precision with zero DOM scanning overhead for real-time previews.
+ */
+export declare class SVGRenderer extends Visitor<string> {
+    private htmlRenderer;
+    visit(node: RedNode, context?: VisitorContext): string;
+    render(root: RedNode): string;
+}

package/dist/types/Visitors/TiptapExporter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * DocumentEngine — TiptapExporter
+ *
+ * Exports the Document Model to Tiptap (ProseMirror) JSON format.
+ * This proves how easily Quasar's AST bridges to visual WYSIWYG editors.
+ *
+ * Tiptap uses a JSON format structured like:
+ * {
+ *   type: "doc",
+ *   content: [
+ *     {
+ *       type: "paragraph",
+ *       content: [
+ *         { type: "text", text: "Hello ", marks: [{ type: "bold" }] }
+ *       ]
+ *     }
+ *   ]
+ * }
+ */
+import { RedNode } from '../Syntax/RedNode';
+import { Visitor } from './Visitor';
+export interface TiptapNode {
+    type: string;
+    attrs?: Record<string, any>;
+    content?: TiptapNode[];
+    marks?: TiptapMark[];
+    text?: string;
+}
+export interface TiptapMark {
+    type: string;
+    attrs?: Record<string, any>;
+}
+export declare class TiptapExporter extends Visitor<string> {
+    visit(node: RedNode): string;
+    toTiptap(node: RedNode): TiptapNode;
+    private processChildren;
+    private processNode;
+    private kindToMark;
+    private kindToBlockType;
+}

package/dist/types/Visitors/Visitor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * DocumentEngine — Visitor
+ *
+ * Base visitor pattern for traversing the Red Tree.
+ * All exporters and renderers extend this.
+ *
+ * Instead of switch statements on tag names, use the visitor pattern.
+ * New languages/exporters don't modify existing code.
+ *
+ * Inspired by SwiftSyntax's Visitor pattern.
+ */
+import { RedNode } from '../Syntax/RedNode';
+export interface VisitorContext {
+    source: string;
+    options: Record<string, unknown>;
+}
+export declare abstract class Visitor<T = string> {
+    protected context: VisitorContext;
+    /**
+     * Visit a node and produce an output value.
+     */
+    abstract visit(node: RedNode, context?: VisitorContext): T;
+    /**
+     * Visit all children and combine results.
+     */
+    visitChildren(node: RedNode, separator?: string): T[];
+    /**
+     * Get the text content of a node.
+     */
+    getText(node: RedNode): string;
+    /**
+     * Set the visitor context.
+     */
+    setContext(context: VisitorContext): void;
+}

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

@@ -0,0 +1,9 @@
+export { Visitor } from './Visitor';
+export type { VisitorContext } from './Visitor';
+export { BBCodeExporter } from './BBCodeExporter';
+export { HTMLRenderer } from './HTMLRenderer';
+export { morphHTML } from './DOMMorpher';
+export { MarkdownExporter } from './MarkdownExporter';
+export { JSONExporter } from './JSONExporter';
+export { SVGRenderer } from './SVGRenderer';
+export type { JSONDocument, JSONNode } from './JSONExporter';

package/dist/types/Visuals/BoxDrawer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * DocumentEngine — BoxDrawer
+ *
+ * Drawer-style open/close animation for the `<details>` elements that
+ * HTMLRenderer emits for `[box]` and `[spoilerbox]`. The box grows downwards
+ * and progressively uncovers its content, which stays anchored under the
+ * summary instead of popping in all at once.
+ *
+ * This lives in Quasar rather than in a consumer because Quasar is what emits
+ * the `<details>` in the first place — the same reason `morphHTML` lives here.
+ * Any host that renders Quasar output gets the behaviour by binding it once.
+ *
+ * Why not CSS: while a `<details>` is closed its content is not rendered, so
+ * there is no height to interpolate between. `::details-content` combined with
+ * `interpolate-size: allow-keywords` would solve it, but it is Chromium-only in
+ * practice and hosts running on WebKit would silently lose the animation.
+ * Measuring the real height and driving it with the Web Animations API works on
+ * every engine.
+ *
+ * Heights are measured, not computed from summary + padding + borders, because
+ * that arithmetic breaks as soon as a theme puts margins on the summary or the
+ * boxes are nested. Toggling `open` and reading the rect yields the exact
+ * height the element will settle at, whatever the stylesheet does.
+ */
+export interface BoxDrawerOptions {
+    /** Length of a full open or close, in milliseconds. Partial travel is scaled down. */
+    durationMs?: number;
+    /** CSS easing function. */
+    easing?: string;
+}
+/**
+ * Animate one `<details>` to its opposite state, reversing cleanly when it is
+ * already mid-animation.
+ *
+ * Exported so hosts that toggle boxes programmatically (a keyboard command, an
+ * "expand all" action) go through the same animation as a click.
+ */
+export declare function toggleBoxWithDrawer(details: HTMLDetailsElement, options?: BoxDrawerOptions): void;
+/**
+ * Intercept the native toggle of every box inside `root`.
+ *
+ * The listener is delegated rather than attached per box: hosts typically feed
+ * the preview through `morphHTML` on every keystroke, and per-element listeners
+ * would be torn down and re-attached continuously.
+ *
+ * @param root - container holding the rendered BBCode
+ * @returns disposer that removes the listener
+ */
+export declare function bindBoxDrawer(root: HTMLElement, options?: BoxDrawerOptions): () => void;

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

@@ -0,0 +1,38 @@
+/**
+ * DocumentEngine — Visuals
+ *
+ * Catálogo de estilos visuales por plataforma para la previsualización
+ * de BBCode. Cada plataforma puede tener su propia apariencia sin
+ * modificar el renderer HTML.
+ *
+ * Uso:
+ *   // Desde la FUENTE, que es como lo consume el monorepo (Next.js, Vite,
+ *   // Webpack): esta ruta funciona sin haber compilado nada.
+ *   import '@miliastry/quasar/src/Visuals/osu.css'
+ *
+ *   // Desde el paquete PUBLICADO. Solo resuelve tras `npm run build`, que es
+ *   // lo que copia los CSS a dist/Visuals (ver scripts/copy-css.mjs).
+ *   import '@miliastry/quasar/Visuals/osu.css'
+ *
+ *   // Luego en el JSX: <div className="bbcode-preview" ...
+ *
+ * Para cambiar de tema visual, solo cambia el import del CSS.
+ *
+ * Temas disponibles:
+ *   - osu  → Estilo visual inspirado en los foros de osu!
+ *   - miliastry → Estilo por defecto de Miliastry (próximamente)
+ */
+export { bindBoxDrawer, toggleBoxWithDrawer } from './BoxDrawer';
+export type { BoxDrawerOptions } from './BoxDrawer';
+export declare const visualThemes: readonly [{
+    readonly id: 'osu';
+    readonly name: 'osu! Forum Style';
+    readonly description: 'Estilo visual inspirado en los foros de osu!';
+    readonly cssFile: 'osu.css';
+}, {
+    readonly id: 'lyne';
+    readonly name: 'Lyne Style';
+    readonly description: 'Estilo visual cyberpunk con cortes a 45° inspirado en Lyne';
+    readonly cssFile: 'lyne.css';
+}];
+export type VisualThemeId = (typeof visualThemes)[number]['id'];