@miliastry/quasar 1.0.6 → 1.1.0

package/dist/types/Edits/EditPlan.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Quasar — Surgical Edit Plan & Conflict Resolution
+ *
+ * The optimizer has exactly one output: a set of `SurgicalEdit`s over the
+ * ORIGINAL source. Two appliers consume it — Monaco in-place, and a pure
+ * string rewrite for export — so neither ever re-serializes the document and
+ * neither can drift from the other.
+ *
+ * That design has one hard prerequisite, which is what this file is:
+ * **the edits handed to an applier must be pairwise conflict-free.**
+ * Monaco is explicit that it will not arbitrate:
+ *
+ *   > Overlapping ranges are the caller's responsibility — Monaco has no
+ *   > answer for two edits claiming the same character.
+ *   — `packages/core/Editor/Core_Editor.tsx`
+ *
+ * Rules are authored independently and WILL collide: merging a run of
+ * identical `[color=#FF0000]` tags and shortening that same `#FF0000` to
+ * `#F00` claim overlapping bytes. The resolution must never be "last writer
+ * wins", because that makes the output depend on the order rules happen to be
+ * registered in. Everything here exists to make the outcome a pure function of
+ * the edit set itself.
+ *
+ * @see resolveEditConflicts
+ */
+import type { SurgicalEdit } from '../Reconciler/SurgicalReconciler';
+/**
+ * A `SurgicalEdit` plus the provenance the resolver needs to arbitrate and
+ * the UI needs to explain itself.
+ *
+ * `priority` is declared by the rule, not derived from the edit. A rule that
+ * rewrites a whole region outranks one that tweaks a token inside it, and
+ * that relationship is a property of the rules — not something you can read
+ * off two ranges.
+ */
+export interface PlannedEdit extends SurgicalEdit {
+    /** Identifies the rule that produced this edit. Also the final tie-break. */
+    readonly ruleId: string;
+    /** Higher wins. See {@link compareEditPriority} for the full order. */
+    readonly priority: number;
+    /** Human-readable intent, for the "what did the minifier do" panel. */
+    readonly label?: string;
+}
+/**
+ * Why an edit did not make it into the applied set.
+ *
+ * - `invalid-range` — the rule emitted a range that is not a valid slice of
+ *   the source. A rule bug; dropped rather than thrown so one broken rule
+ *   cannot destroy an otherwise good batch.
+ * - `subsumed` — a winning edit's range fully contains this one (equal ranges
+ *   included). The winner rewrites these bytes wholesale, so this edit's
+ *   intent is either already covered or no longer meaningful.
+ * - `straddle` — partial overlap where NEITHER range contains the other.
+ *   Reported separately from `subsumed` on purpose: see the note on
+ *   {@link classifyOverlap}.
+ */
+export type EditRejectionReason = 'invalid-range' | 'subsumed' | 'straddle';
+export interface RejectedEdit {
+    readonly edit: PlannedEdit;
+    readonly reason: EditRejectionReason;
+    /** The accepted edit that displaced it. Absent for `invalid-range`. */
+    readonly winner?: PlannedEdit;
+}
+export interface ResolvedEditPlan {
+    /**
+     * Pairwise conflict-free, sorted by ascending `start`. Safe to hand
+     * verbatim to `applySurgicalEdits` (Monaco resolves original offsets
+     * itself) or to a back-to-front string rewrite.
+     */
+    readonly accepted: readonly PlannedEdit[];
+    /** Everything dropped, with the reason and the edit that displaced it. */
+    readonly rejected: readonly RejectedEdit[];
+}
+/** How two claimed ranges relate. */
+export type OverlapRelation = 'disjoint' | 'subsumption' | 'straddle';
+/**
+ * Classify two edits by the bytes they claim.
+ *
+ * Ranges are half-open `[start, end)` over the original source, so edits that
+ * merely touch (`a.end === b.start`) are disjoint — adjacent replacements are
+ * perfectly legal and common.
+ *
+ * Zero-width edits (insertions, `start === end`) need two special cases that
+ * pure interval intersection gets wrong:
+ *
+ * 1. Two insertions at the SAME offset have an empty intersection, yet both
+ *    write at one point with no defined order between them. That is a
+ *    conflict, classified as `subsumption` so priority decides it.
+ * 2. An insertion strictly inside a replacement also has an empty
+ *    intersection, but the replacement destroys the bytes the insertion point
+ *    refers to, so the insertion is meaningless. Also `subsumption`.
+ *
+ * An insertion exactly at a replacement's boundary stays disjoint — it is
+ * unambiguously before or after, and both appliers agree on that.
+ *
+ * `straddle` is deliberately its own relation rather than folded into
+ * `subsumption`. It is resolved the same way (drop the loser), but two
+ * *maximal* rules should never straddle each other: a straddle almost always
+ * means a rule computed a partial range instead of the whole normal form.
+ * Keeping it distinct is what makes that bug visible instead of silent.
+ */
+export declare function classifyOverlap(a: SurgicalEdit, b: SurgicalEdit): OverlapRelation;
+/** Whether two edits may not be applied together. */
+export declare function editsConflict(a: SurgicalEdit, b: SurgicalEdit): boolean;
+/**
+ * The arbitration order, as a comparator: negative means `a` is considered
+ * first and therefore wins any conflict against `b`.
+ *
+ * The chain is **total** — it never returns 0 for two distinguishable edits.
+ * That is the whole point. A partial order would leave ties broken by
+ * `Array.prototype.sort` stability, i.e. by the order rules were registered,
+ * which is exactly the non-determinism this contract exists to prevent.
+ *
+ * 1. `priority` descending — the rule's own declaration, and the only lever a
+ *    rule author has.
+ * 2. Width descending — at equal priority the wider claim wins, because a
+ *    broader rewrite subsumes the work of a narrower one more often than the
+ *    reverse. (A zero-width insertion therefore loses to any replacement it
+ *    ties with, which is what you want: the replacement carries text anyway.)
+ * 3. `start` ascending — earlier in the document.
+ * 4. `ruleId`, then `text`, lexicographically — no semantic meaning, purely
+ *    the guarantee that the order is total.
+ */
+export declare function compareEditPriority(a: PlannedEdit, b: PlannedEdit): number;
+/**
+ * Reduce a rule-authored edit set to a conflict-free one.
+ *
+ * Greedy by {@link compareEditPriority}: walk the edits in arbitration order
+ * and accept each one that collides with nothing already accepted.
+ *
+ * This is deliberately **not** a maximum-weight independent set. Greedy can
+ * drop two small edits to keep one large one that saves fewer bytes, and that
+ * is an accepted trade: the optimizer's contract is that the same document
+ * always minifies to the same output, not that it minifies to the smallest
+ * possible output. Predictability is worth more than the last few bytes in a
+ * tool that rewrites someone's document.
+ *
+ * The result is order-independent — shuffling `edits` cannot change
+ * `accepted` — which is the property the tests pin down.
+ *
+ * @param edits        Rule output, in any order.
+ * @param sourceLength Length of the ORIGINAL source every range indexes into.
+ */
+export declare function resolveEditConflicts(edits: readonly PlannedEdit[], sourceLength: number): ResolvedEditPlan;

package/dist/types/Edits/Optimizer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Quasar — BBCode Optimizer
+ *
+ * Parses a document, runs every optimization rule over the tree, arbitrates
+ * the edits they produce, and hands back one conflict-free `SurgicalEdit[]`
+ * addressed to the ORIGINAL source.
+ *
+ * That edit set is the optimizer's only output. There is deliberately no
+ * "optimized tree" — two appliers consume the edits instead:
+ *
+ *   in-place →  applySurgicalEdits(result.edits)     (Monaco, one undo stop)
+ *   export   →  result.output                        (applyEditsToSource)
+ *
+ * Keeping a tree optimizer *and* a range optimizer in step forever was the
+ * alternative, and it was rejected before the first rule was written. A tree
+ * optimizer's output can only reach the document through a whole-document
+ * re-export, which silently rewrites spellings the author chose (`[B]`→`[b]`,
+ * `\r\n`→`\n`, unclosed tags closed). That is fine for an export and
+ * unacceptable for someone's open buffer.
+ */
+import type { BBCodeDialect } from '../BBCode/BBCodeToGreenNode';
+import type { GreenNode } from '../Syntax/GreenNode';
+import { type PlannedEdit, type ResolvedEditPlan } from './EditPlan';
+import type { OptimizationRule } from './Rules/Rule';
+/**
+ * The rules a plain "minify" run applies.
+ *
+ * Ordered by descending priority, which is also the order in which their
+ * regions subsume one another: a merge deletes the delimiters that a hex
+ * shortening inside them would have edited.
+ *
+ * `ReorderWrappersRule` is **not** here. It is a real, tested rule, but it
+ * saves exactly zero bytes — it canonicalises nesting order rather than
+ * removing anything. A minifier that rewrites someone's document without
+ * making it smaller is a diff with no upside, so it is opt-in.
+ */
+export declare function defaultRules(): OptimizationRule[];
+/** Every rule that exists, including the ones outside the default preset. */
+export declare function allRules(): OptimizationRule[];
+export interface RuleStat {
+    readonly ruleId: string;
+    readonly label: string;
+    /** Edits this rule contributed to the applied set. */
+    readonly edits: number;
+    /** Characters removed by those edits. Never negative for the shipped rules. */
+    readonly savedChars: number;
+}
+export interface OptimizationResult {
+    /** The document as given. */
+    readonly source: string;
+    /** Conflict-free, sorted by ascending start. Hand straight to either applier. */
+    readonly edits: readonly PlannedEdit[];
+    /** Full arbitration record, including what was dropped and why. */
+    readonly plan: ResolvedEditPlan;
+    /** `source` with `edits` applied. */
+    readonly output: string;
+    readonly savedChars: number;
+    /** Per-rule breakdown of the *applied* edits, in descending saving order. */
+    readonly stats: readonly RuleStat[];
+}
+export interface OptimizeOptions {
+    readonly rules?: readonly OptimizationRule[];
+    /** Dialect to parse against. Defaults to `'lyne'`, the superset. */
+    readonly dialect?: BBCodeDialect;
+}
+/**
+ * Optimize a parsed tree.
+ *
+ * Prefer this when the caller already holds a green tree — the editor reparses
+ * on every keystroke and has no reason to pay for another parse.
+ *
+ * `root.width` must equal `source.length`; the rules address offsets into that
+ * exact string. A mismatch means the tree describes a different document, and
+ * every range would land in the wrong place, so it is refused outright.
+ */
+export declare function optimizeTree(source: string, root: GreenNode, options?: OptimizeOptions): OptimizationResult;
+/** Parse `source` and optimize it. */
+export declare function optimizeBBCode(source: string, options?: OptimizeOptions): OptimizationResult;

package/dist/types/Edits/Rules/Rule.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Quasar — Optimization Rule contract
+ *
+ * Every rule reads the Green Tree and returns `PlannedEdit[]` addressed to
+ * offsets in the ORIGINAL source. Rules never mutate the tree, never build a
+ * new one, and never see each other's output — the only thing that arbitrates
+ * between them is `resolveEditConflicts`.
+ *
+ * Three obligations, all of them load-bearing:
+ *
+ * 1. **Maximal.** A rule emits the final form in one pass. It may not rely on
+ *    being run again: applying an edit invalidates every later offset, so
+ *    there is no second pass to be had. Where `ASTOptimizer` merged pairwise
+ *    and iterated to a fixpoint, a rule here recognises the whole run.
+ * 2. **Deterministic.** Same tree in, same edits out, in the same order.
+ * 3. **Spelling-preserving.** Prefer deleting the author's bytes over
+ *    generating replacements. `[Color = "#FF0000"]` must survive a merge
+ *    intact; the exporter would have rewritten it to `[color=#FF0000]`.
+ *
+ * @see resolveEditConflicts
+ */
+import type { GreenNode } from '../../Syntax/GreenNode';
+import type { PlannedEdit } from '../EditPlan';
+export interface RuleContext {
+    /** The document exactly as the author wrote it. */
+    readonly source: string;
+    /** Green root, whose width equals `source.length`. */
+    readonly root: GreenNode;
+}
+export interface OptimizationRule {
+    /** Stable identifier; also the final tie-break in the conflict order. */
+    readonly id: string;
+    /**
+     * Arbitration weight. A rule that rewrites a whole region must outrank the
+     * rules that tweak tokens inside it, so the region's own normal form wins.
+     */
+    readonly priority: number;
+    /** Short human label, shown in the "what did the minifier do" list. */
+    readonly label: string;
+    run(context: RuleContext): PlannedEdit[];
+}
+/**
+ * A node together with its absolute start offset in the source.
+ *
+ * Green nodes carry widths, not positions, so every rule that wants a range
+ * has to accumulate offsets on the way down. This pairing is what the rules
+ * pass around instead of bare nodes.
+ */
+export interface Positioned {
+    readonly node: GreenNode;
+    readonly start: number;
+}
+/** Absolute end offset (exclusive). */
+export declare function endOf(p: Positioned): number;
+/** The range of the opening delimiter — `[color=#F00]`. */
+export declare function openRange(p: Positioned): {
+    start: number;
+    end: number;
+};
+/** The range of the closing delimiter — `[/color]`. */
+export declare function closeRange(p: Positioned): {
+    start: number;
+    end: number;
+};
+/** Children paired with their absolute offsets, in document order. */
+export declare function positionedChildren(p: Positioned): Positioned[];
+/**
+ * A node that actually has both delimiters in the source.
+ *
+ * The parser synthesises a closing tag for `[b]never closed`, which comes back
+ * as `trailingWidth === 0`. Deleting a delimiter that occupies no bytes is a
+ * no-op at best; treating a synthetic close as if it were real is a
+ * correctness bug. Rules that move or remove delimiters check this first.
+ */
+export declare function hasBothDelimiters(p: Positioned): boolean;
+/** A deletion of an exact source range. */
+export declare function deletion(range: {
+    start: number;
+    end: number;
+}, ruleId: string, priority: number, label?: string): PlannedEdit;
+/**
+ * Merge deletions that touch into single edits.
+ *
+ * Two deletions `[a,b)` and `[b,c)` are legal side by side — the conflict
+ * resolver calls them disjoint — but they describe one contiguous removal.
+ * Emitting them separately inflates the edit count for no benefit and makes
+ * the "N optimisations applied" number lie about how much happened.
+ *
+ * Input must be sorted by `start` and non-overlapping.
+ */
+export declare function coalesceDeletions(edits: readonly PlannedEdit[]): PlannedEdit[];

package/dist/types/Edits/Rules/dropEmptyTags.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Quasar — `drop-empty-tags`
+ *
+ * Removes formatting tags that enclose nothing: `[b][/b]`, `[color=#F00][/color]`.
+ *
+ * ## Only tags whose absence is invisible
+ *
+ * The droppable set is an explicit allowlist of inline formatting, not "any
+ * tag with no children". An empty `[box]` still draws a frame, an empty
+ * `[quote]` still draws a quote block, and `[img]`/`[youtube]` carry their
+ * payload in the attribute rather than in children — deleting any of those
+ * changes what the reader sees. Anything not on the list stays, including
+ * tags this engine does not recognise.
+ *
+ * ## Outermost-first, so no second pass is needed
+ *
+ * `[b][i][/i][/b]` is empty all the way down. Dropping the inner tag would
+ * leave `[b][/b]`, which is empty again — the classic reason `ASTOptimizer`
+ * needs a fixpoint. Instead this rule asks whether a node renders nothing
+ * *transitively* and deletes the outermost one it finds, in a single edit,
+ * without descending into it.
+ */
+import type { PlannedEdit } from '../EditPlan';
+import { type OptimizationRule, type RuleContext } from './Rule';
+export declare const DROP_EMPTY_PRIORITY = 80;
+/**
+ * Inline formatting whose empty form is guaranteed to render nothing.
+ *
+ * Deliberately conservative. A kind is only here if an empty instance of it
+ * produces no glyphs, no box, no line break and no side effect.
+ */
+export declare const DROPPABLE_WHEN_EMPTY: ReadonlySet<string>;
+export declare class DropEmptyTagsRule implements OptimizationRule {
+    readonly id = "drop-empty-tags";
+    readonly priority = 80;
+    readonly label = "Remove empty formatting tags";
+    run(context: RuleContext): PlannedEdit[];
+    private scan;
+    private isDroppable;
+}

package/dist/types/Edits/Rules/dropRedundantNesting.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Quasar — `drop-redundant-nesting`
+ *
+ * Removes a tag nested directly inside an identical one:
+ *
+ *   [color=#F00]a[color=#F00]b[/color][/color]  →  [color=#F00]ab[/color]
+ *
+ * The inner delimiters are the ones deleted, so the outer tag — and the
+ * author's spelling of it — is what survives.
+ *
+ * Identity is the same normalised comparison the merge rule uses, so
+ * `[color=#F00]` inside `[color=#FF0000]` counts as redundant: the colours are
+ * equal even though the spellings are not.
+ *
+ * Siblings do not disqualify anything. In `[color=X]a[color=X]b[/color][/color]`
+ * the inner tag is still setting a colour that is already in force, so
+ * dropping its delimiters cannot change the render.
+ *
+ * ## Only tags that do nothing when nested in themselves
+ *
+ * "Redundant" has to be earned, not assumed. `[size=50]` renders as
+ * `font-size:50%`, and a percentage is relative to its parent — so
+ * `[size=50][size=50]x[/size][/size]` is 25%, not 50%, and the inner tag is
+ * doing real work. `[sup]` stacks its vertical offset the same way. Removing
+ * either would shrink or lift the text, which is not a smaller document, it is
+ * a different one.
+ *
+ * @see IDEMPOTENT_WHEN_NESTED
+ */
+import type { PlannedEdit } from '../EditPlan';
+import { type OptimizationRule, type RuleContext } from './Rule';
+export declare const DROP_REDUNDANT_NESTING_PRIORITY = 90;
+/**
+ * Kinds whose effect is unchanged by being applied twice.
+ *
+ * A colour inside the same colour is still that colour; bold inside bold is
+ * still bold. Excluded are the properties that **compound**: `font_size`
+ * multiplies percentages, and `sup`/`sub` add their vertical offsets. Anything
+ * not listed is left alone, unknown tags included.
+ */
+export declare const IDEMPOTENT_WHEN_NESTED: ReadonlySet<string>;
+export declare class DropRedundantNestingRule implements OptimizationRule {
+    readonly id = "drop-redundant-nesting";
+    readonly priority = 90;
+    readonly label = "Remove tags nested inside an identical tag";
+    run(context: RuleContext): PlannedEdit[];
+    /**
+     * `inForce` maps a node kind to the identity its NEAREST ancestor of that
+     * kind established.
+     *
+     * Keyed by kind rather than carrying a single inherited identity, because an
+     * ancestor's colour survives an intervening tag of another kind:
+     * `[color=X][b][color=X]…` is still redundant. Overwriting on the way down
+     * is what makes it the *nearest* ancestor — in
+     * `[color=X][color=Y][color=X]…` the innermost tag restores a colour that Y
+     * had overridden, so it is doing real work and must stay.
+     */
+    private scan;
+}

package/dist/types/Edits/Rules/index.d.ts

@@ -0,0 +1,9 @@
+export type { OptimizationRule, RuleContext, Positioned } from './Rule';
+export { endOf, openRange, closeRange, positionedChildren, hasBothDelimiters, deletion, coalesceDeletions, } from './Rule';
+export { attributeValue, normalizeColorValue, shortenableHex, mergeIdentity, MERGEABLE_INLINE, BRIDGES_WHITESPACE, } from './tagValue';
+export { MergeAdjacentRule, MERGE_ADJACENT_PRIORITY, type MergeAdjacentOptions } from './mergeAdjacent';
+export { DropEmptyTagsRule, DROP_EMPTY_PRIORITY, DROPPABLE_WHEN_EMPTY } from './dropEmptyTags';
+export { DropRedundantNestingRule, DROP_REDUNDANT_NESTING_PRIORITY } from './dropRedundantNesting';
+export { ShortenHexRule, SHORTEN_HEX_PRIORITY } from './shortenHex';
+export { UnwrapInvisibleColorRule, UNWRAP_INVISIBLE_COLOR_PRIORITY, isInvisibleWhitespace, } from './unwrapInvisibleColor';
+export { ReorderWrappersRule, REORDER_WRAPPERS_PRIORITY } from './reorderWrappers';

package/dist/types/Edits/Rules/mergeAdjacent.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Quasar — `merge-adjacent`
+ *
+ * Fuses runs of identically-attributed sibling tags into one:
+ *
+ *   [color=#FF0000]H[/color][color=#FF0000]e[/color][color=#FF0000]y[/color]
+ *   → [color=#FF0000]Hey[/color]
+ *
+ * This is where the bytes are. A per-character gradient spends ~23 bytes of
+ * delimiter on every 1 byte of text; collapsing a run of identical colours is
+ * the single largest saving available on a real userpage.
+ *
+ * ## It only ever deletes
+ *
+ * The merged tag is not generated. The first member's opening delimiter and
+ * the last member's closing delimiter are left exactly as the author typed
+ * them, and only the seams between members are removed:
+ *
+ *   [Color = "#F00"]a[/color][color=#ff0000]b[/color]
+ *   [Color = "#F00"]a‹  deleted  ›b[/color]
+ *
+ * So `[Color = "#F00"]` survives with its capital C, its spaces and its
+ * quotes. A rule that rebuilt the tag would have normalised all three, which
+ * is exactly the drift that makes whole-document re-export unusable in an
+ * editor.
+ *
+ * ## Maximal in one pass
+ *
+ * `ASTOptimizer` merges pairwise and iterates to a fixpoint. Edits addressed
+ * to the original source cannot do that — applying one invalidates every later
+ * offset — so this rule recognises the **whole run at once**, and then
+ * descends into the content the merge is about to create:
+ *
+ *   [b][color=X]a[/color][/b][b][color=X]bc[/color][/b]
+ *
+ * Merging the two `[b]` makes their colour children siblings, and those merge
+ * too. The recursion walks that *virtual* child list, so both levels come out
+ * of a single pass. Crucially the inner seams sit inside the members' content
+ * and the outer seams sit between members, so the two sets never overlap.
+ *
+ * @see mergeIdentity — what "identically attributed" means
+ * @see BRIDGES_WHITESPACE — when a gap between members may be absorbed
+ */
+import type { PlannedEdit } from '../EditPlan';
+import { type OptimizationRule, type RuleContext } from './Rule';
+export declare const MERGE_ADJACENT_PRIORITY = 100;
+export interface MergeAdjacentOptions {
+    /**
+     * Restrict the rule to these node kinds. Omitted, every kind
+     * {@link mergeIdentity} recognises is eligible.
+     */
+    readonly kinds?: ReadonlySet<string>;
+}
+export declare class MergeAdjacentRule implements OptimizationRule {
+    readonly id = "merge-adjacent";
+    readonly priority = 100;
+    readonly label = "Merge adjacent identical tags";
+    private readonly kinds?;
+    constructor(options?: MergeAdjacentOptions);
+    run(context: RuleContext): PlannedEdit[];
+    private identityOf;
+    /**
+     * A node that may sit between two members and be absorbed by the merge.
+     *
+     * Blank text, or a colour tag wrapping nothing but blank text — the shape
+     * `unwrap-invisible-color` exists to delete. Treating it as a gap rather
+     * than as a wall lets `[color=A]x[/color][color=B] [/color][color=A]y[/color]`
+     * still fuse its two `A` members; the `B` tag survives this rule untouched
+     * and is removed by the other one, whose edits are disjoint from these.
+     */
+    private isBridge;
+    /**
+     * Walk one sibling list, fusing every maximal run it contains.
+     *
+     * The list is not always a real node's children: after a merge is planned,
+     * the members' children are spliced together and scanned as the sibling list
+     * the merged tag will actually have.
+     */
+    private scan;
+    /**
+     * Delete each member's closing delimiter and the next member's opening one.
+     *
+     * Two edits per seam rather than one span, because a bridge may sit between
+     * them and must survive. When nothing separates them the two deletions touch
+     * and `coalesceDeletions` folds them back into a single edit.
+     */
+    private emitSeams;
+    /**
+     * The sibling list the merged tag will hold: every member's children in
+     * order, with any bridging text kept in place between them.
+     */
+    private virtualContent;
+}

package/dist/types/Edits/Rules/reorderWrappers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 } from './Rule';
+export declare const REORDER_WRAPPERS_PRIORITY = 5;
+export declare class ReorderWrappersRule implements OptimizationRule {
+    readonly id = "reorder-wrappers";
+    readonly priority = 5;
+    readonly label = "Canonicalise nested wrapper order";
+    run(context: RuleContext): PlannedEdit[];
+    private scan;
+    /** The maximal run of rankable single-child wrappers starting at `item`. */
+    private chainFrom;
+    private emitPermutation;
+}

package/dist/types/Edits/Rules/shortenHex.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 } from './Rule';
+export declare const SHORTEN_HEX_PRIORITY = 10;
+export declare class ShortenHexRule implements OptimizationRule {
+    readonly id = "shorten-hex";
+    readonly priority = 10;
+    readonly label = "Shorten 6-digit hex colours";
+    run(context: RuleContext): PlannedEdit[];
+    private scan;
+    private shorten;
+}

package/dist/types/Edits/Rules/tagValue.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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';
+/**
+ * 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 declare function attributeValue(node: GreenNode): string;
+/**
+ * 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 declare function normalizeColorValue(raw: string): string;
+/** Six-digit hex whose channels are all doubled digits, e.g. `#FFAA00`. */
+export declare function shortenableHex(raw: string): string | null;
+/**
+ * The identity two sibling tags must share to be mergeable.
+ *
+ * Returns `null` for kinds this optimizer does not fuse.
+ */
+export declare function mergeIdentity(node: GreenNode): string | 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 declare const MERGEABLE_INLINE: ReadonlySet<string>;
+/**
+ * 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 declare const BRIDGES_WHITESPACE: ReadonlySet<string>;