RichRender Engine — API Reference

Version: 0.6-dev

Date: March 2026

Status: Core engine complete, 79/79 tests passing

Executive Summary

RichRender is a compact binary format for rich text, with a modular JavaScript engine that handles encoding, inflation (rendering to HTML), interactive editing, and format conversion.

The Problem

Rich text on the web relies on HTML — a verbose, parser-heavy format designed for documents, not data. A bold red word costs 50+ bytes in HTML. Email clients, chat systems, IoT devices, and editors all pay this tax. TinyMCE (the dominant open-source rich text editor) ships 500KB+ minified just to manipulate it.

The Solution

RichRender encodes the same bold red word in 5 bytes: one control character, two style-pip bytes, and the text. The format uses bitwise flags — bold is a single bit, color is a 4-bit index, font size is a 3-bit index. No parsing, no tree walking, no configuration files.

The engine is six JavaScript files totaling 20KB minified (6KB gzipped). It provides:

• A universal inflator that renders any RichRender stream to semantic HTML
• An editor data model with cursor operations and a bitwise painting API
• Format converters between wire format and editor format
• Optional MDR (Markdown) import

Performance

For comparison: TinyMCE is 500KB+ minified. CKEditor is 300KB+.

Four Tiers, One Format

RichRender is one format at four depths. Each tier is a superset of the one below:

A Bit-Wise stream is valid Lite-Wire. A Lite-Wire stream is valid Wire Format. One inflator reads all tiers.

File Structure

richrender-core.js    Constants, element tables, stream builder, disassembler
rr-inflate.js         Universal inflator (any tier → Render-HTML)
rr-editor.js          Editor format: EditorDoc, painting API
rr-convert.js         Format converters (wire ↔ editor ↔ HTML)
mdr-to-rich.js        MDR Markdown → RichRender encoder
rich-to-html.js       Bit-Wise-only inflator (minimal/legacy)

Cherry-pick by use case:

• Read-only viewer: core + rr-inflate
• Interactive editor: core + rr-inflate + rr-editor + rr-convert
• MDR import: add mdr-to-rich

API Reference

richrender-core.js — RR

The shared foundation. All other modules depend on this.

Control Characters

Style-Pip Byte One — Flags

Style-Pip Byte Two — Color and Font

Style-Pip Byte Three — Size and Extras

Default Palettes

RR.DEFAULT_FG[0..15]    // Foreground colors: inherit, black, dark gray, red,
                        // maroon, orange, green, dark green, blue, navy,
                        // purple, teal, brown, light gray, white, gold

RR.DEFAULT_BG[0..3]     // Background colors: none, yellow, green, pink

RR.DEFAULT_SIZES[0..7]  // Font sizes: inherit, 2em, 1.5em, 1.17em, 1em,
                        // 0.85em, 0.75em, 0.6em

Element Tables

RR.BLOCK.p          // 15 — paragraph
RR.BLOCK.h1         //  9 — through h6 (14)
RR.BLOCK.blockquote // 17
RR.BLOCK.ul         // 18
RR.BLOCK.ol         // 19
RR.BLOCK.li         // 20
RR.BLOCK.hr         // 40
// ... 43 block elements total (see BLOCK object)

RR.INLINE.code      //  1
RR.INLINE.a         // 15
// ... 26 inline elements total (see INLINE object)

RR.BLOCK_NAMES[idx]   // Reverse lookup: index → tag name
RR.INLINE_NAMES[idx]  // Reverse lookup: index → tag name

Heading Patterns

RR.HEADING_PATTERNS  // { 1:'h1', 2:'h2', 3:'h3', 4:'h4' }
                     // Inflator matches: size index + bold flag → heading tag

RichStream — Byte Stream Builder

var s = new RR.RichStream();

s.write(byte)               // Write a single byte (number) or Uint8Array
s.writeText(string)         // Write UTF-8 encoded text
s.openBlock(idx)            // SOH + block index
s.closeBlock()              // EOT
s.openInline(idx)           // SO + inline index
s.closeInline()             // SI
s.openStyle(pip)            // STX + pip byte
s.closeStyle(resumePip?)    // ETX + optional resuming pip
s.meta(type, content)       // META_OPEN + type + text + META_CLOSE
s.toBytes()                 // → Uint8Array

Debugging Utilities

RR.describePip(b1, b2?, b3?)   // → "bold+italic+fg:3+sans" (human-readable)
RR.hexDump(bytes, perLine?)     // → hex dump string
RR.disassemble(bytes)           // → annotated disassembly with indentation

rr-inflate.js — rrInflate(bytes)

Universal inflator. Reads any RichRender byte stream and produces Render-HTML.

var html = rrInflate(bytes);   // Uint8Array → HTML string

Handles all control characters: STX/ETX (style spans), SOH/EOT (blocks), SO/SI (inlines), META (attributes, comments).

Heading detection: Size + bold pattern → <h1> through <h4>.

Double underline: Overrides single underline when both set.

Highlight: Byte-one variant → <mark> with default yellow. Byte-two bg overrides color.

Round-trip classes: Every output element carries mdr- prefixed classes:

Meta attributes: Parsed as key=value pairs (newline-separated). Emitted as HTML attributes.

rr-editor.js — RREditor.EditorDoc

Per-character pip array for cursor-addressable editing. All style operations are bitwise math.

Creating a Document

var doc = RREditor.EditorDoc.fromText('hello world');
var doc = new RREditor.EditorDoc(charArray);  // from existing char array

Each character is { ch: string, p1: number, p2: number, p3: number }.

Cursor Operations

doc.length()                    // → number of characters
doc.text(from?, to?)            // → plain text string
doc.charAt(pos)                 // → { ch, p1, p2, p3 } or null
doc.insertAt(pos, text, p1?, p2?, p3?)  // insert text with optional style
doc.deleteRange(from, to)       // delete characters in range
doc.slice(from, to)             // → new EditorDoc (deep copy)

Painting — Byte One Flags

doc.applyFlag(from, to, flag)   // Set bits:   pip |= flag
doc.removeFlag(from, to, flag)  // Clear bits:  pip &= ~flag
doc.toggleFlag(from, to, flag)  // Toggle: if all set → remove, else apply
doc.hasFlag(pos, flag)          // → boolean
doc.rangeHasFlag(from, to, flag) // → boolean (all chars in range)

Flags: RR.PIP_BOLD, RR.PIP_ITALIC, RR.PIP_UNDERLINE, RR.PIP_STRIKETHROUGH

Painting — Byte One Variant

doc.setVariant(from, to, variant)  // RR.PIP_SUPER, RR.PIP_SUB, RR.PIP_HIGHLIGHT
doc.clearVariant(from, to)         // Reset to normal

Painting — Byte Two (Color, Font)

doc.setFgColor(from, to, index)  // 0–15 (see DEFAULT_FG)
doc.getFgColor(pos)              // → index
doc.setBgColor(from, to, index)  // 0–3 (see DEFAULT_BG)
doc.getBgColor(pos)              // → index
doc.setFont(from, to, sans)      // true=sans-serif, false=serif

Painting — Byte Three (Size, Extras)

doc.setSize(from, to, index)     // 0–7 (see DEFAULT_SIZES)
doc.getSize(pos)                 // → index
doc.applyP3Flag(from, to, flag)  // RR.P3_SMALLCAPS, RR.P3_OVERLINE, RR.P3_DOUBLE_UNDERLINE
doc.removeP3Flag(from, to, flag)
doc.toggleP3Flag(from, to, flag)

Style Query

doc.styleAt(pos)  // → { bold, italic, underline, strikethrough, variant,
                  //      fgColor, bgColor, sans, size, smallCaps,
                  //      overline, doubleUnder, p1, p2, p3 }

Continuation Auto-Sync

All byte-two and byte-three setters automatically maintain continuation bits. Setting a foreground color automatically sets PIP_CONTINUATION on byte one. Setting a font size automatically sets P2_CONTINUATION on byte two. Clearing all higher-byte content clears the continuation chain. The caller never manages continuation bits manually.

rr-convert.js — RRConvert

Format converters between wire/Lite-Wire/Bit-Wise streams and the editor format.

var doc = RRConvert.wireToEditor(bytes);   // Uint8Array → EditorDoc
var bytes = RRConvert.editorToWire(doc);   // EditorDoc → Uint8Array
var html = RRConvert.editorToHtml(doc);    // EditorDoc → HTML (shortcut)

wireToEditor expands a byte stream into per-character pip tuples. Style spans (STX/ETX) set the current pip state; text characters inherit it. Nested spans (PIP_NESTED) merge delta bits into the current state; resuming pips after ETX are consumed. Block markers become newline characters with metadata. Inline markers become zero-width entries with metadata.

editorToWire compresses an editor document into a byte stream. Detects pip transitions and emits optimal span structure:

• Run-length: Consecutive characters with identical pips share one span.
• Nested spans: When a style transition is additive (adds flags/colors without removing existing ones), emits a nested STX with only the delta bits and PIP_NESTED set. On revert, emits ETX with a resuming pip to restore the outer style.
• Whitespace bridging: Unstyled newlines and tabs inside a styled run keep the span open when the same style resumes after, avoiding redundant ETX/STX pairs.

editorToHtml is a convenience: editorToWire → rrInflate.

mdr-to-rich.js — mdrToRich(text)

MDR (Markdown) to RichRender encoder. Currently handles byte-one style markers:

var bytes = mdrToRich('This is **bold** and *italic*.');  // → Uint8Array

Supported markers:

Linear scanner — walks text left-to-right, toggles pip bits on marker boundaries. Handles nesting (italic inside bold), adjacent markers, and combined markers.

rich-to-html.js — richToHtml(bytes)

Bit-Wise-only inflator. Handles STX/ETX style spans with all three pip bytes. Does NOT handle SOH/EOT blocks or SO/SI inlines.

Use rrInflate instead unless you need the smallest possible file for a Bit-Wise-only deployment. This file exists for size-constrained environments where block/inline support is unnecessary.

Render-HTML Conventions

Document Declaration

<meta name="richrender" content="full" data-tier="bitwise|litewire|wire">

Embedded Boundaries

<div data-mdr="root" data-mdr-tier="bitwise">
  <!-- Clean Render-HTML, mdr- classes throughout -->
</div>

Outside Boundaries

Three strategies for non-Render-HTML content (implementation guidance, not mandated):

1. Ignore — treat as opaque, no conversion
2. Best-effort — heuristic mapping to pips (lossy)
3. Passthrough — wrap in meta region, preserve for round-trip

Tab Character

Tab (U+0009) is a normal text byte in the wire format — 0x09 sits outside the control character range. In the editor format it is stored as { ch: '\t', p1, p2, p3 }.

Render-HTML (TODO): The inflator will emit <span class="mdr-tab" style="display:inline-block;width:2em"></span>. Not yet implemented in rrInflate. The mdr-tab class enables CSS customization. Default width is 2em, configurable via future config file.

MDR round-trip: No special syntax. The 0x09 byte survives encoding/decoding as plain text. The text editor is responsible for rendering; RichRender stores it faithfully.

Editor Palette (Demo / Reference Implementation)

Interactive editors may maintain a document-specific mutable palette separate from the spec defaults. The demo editor (richrender-demo.html) implements this pattern.

Concept

spec defaults:    [inherit, #000, #555, #CC0000, ...]   (immutable, 16 FG / 4 BG)
editor palette:   [  —,      —,    —,   #51653f, ...]   (mutable, sparse)
resolved:         [inherit, #000, #555, #51653f, ...]   (editor wins, default fallback)

resolveFg(idx) / resolveBg(idx) check the editor palette first, then fall back to RR.DEFAULT_FG / RR.DEFAULT_BG.

Color Matching (paste pipeline)

When HTML is pasted, getComputedStyle() is read per text node and mapped to pip bytes:

Color matching uses Euclidean RGB distance with:

• Threshold: 500 (below = match, above = claim new slot)
• Chromatic guard: Saturated colors (max−min channel spread > 30) cannot match achromatic colors (grays, black, white)
• Transparent filter: rgba with alpha ≈ 0, transparent, inherit → bg index 0

Scope

The editor palette is per-document, editor-only state. It is not encoded in the wire format. Documents saved as wire streams use spec default colors (or preamble overrides). Future preamble extensions may bridge this gap.

Interactive Demo — richrender-demo.html

Reference implementation of an interactive RichRender editor. Includes all engine files and demonstrates the full editing pipeline.

Architecture

• Input model: beforeinput-driven. The browser never modifies the DOM directly. All input events are intercepted, applied to the EditorDoc, and re-rendered.
• Source of truth: EditorDoc (from rr-editor.js). The DOM is a projection of the doc state.
• Caret tracking: selectionchange event syncs DOM selection to a JS caret object. A _rendering guard prevents overwrite during re-render.
• Rendering: editorDocToEditableHtml() builds HTML with inline styles from pip bytes. Cursor markers (zero-width spans) are injected to preserve caret position across re-renders.

Panels

Key Functions (demo-specific, not part of the engine)

Test Coverage

79 tests across five sections:

All tests in richrender-test.html.