render-tag 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# render-tag
+
+Render HTML rich text onto a canvas element using pure 2D canvas API. No SVG, no `foreignObject` — just `fillText`, `measureText`, and drawing primitives.
+
+**Website & demos:** [https://polotno.com/render-tag/](https://polotno.com/render-tag/)
+
+## Why
+
+Browsers can render HTML into canvas via SVG `foreignObject`, but it's slow (~100ms) and inconsistent across browsers. `render-tag` parses your HTML, resolves styles via `getComputedStyle`, then lays out and draws everything with canvas 2D calls. It's **10-60x faster** than SVG-based approaches.
+
+## Install
+
+```bash
+npm install render-tag
+```
+
+## Usage
+
+```typescript
+import { renderHTML } from 'render-tag';
+
+const { canvas, height } = renderHTML(
+  '<p>Hello <strong>world</strong></p>',
+  { width: 400 }
+);
+
+document.body.appendChild(canvas);
+```
+
+### With CSS
+
+```typescript
+const { canvas } = renderHTML(
+  '<p class="title">Styled text</p>',
+  {
+    width: 600,
+    css: `
+      .title {
+        font-family: Georgia, serif;
+        font-size: 24px;
+        color: #1a1a1a;
+      }
+    `,
+  }
+);
+```
+
+### With web fonts
+
+```typescript
+const { canvas } = renderHTML(
+  '<p>Custom font text</p>',
+  {
+    width: 500,
+    css: `
+      @font-face {
+        font-family: 'MyFont';
+        src: url('https://example.com/font.woff2') format('woff2');
+      }
+      p { font-family: 'MyFont', sans-serif; font-size: 18px; }
+    `,
+  }
+);
+```
+
+### High-DPI / Retina
+
+```typescript
+const { canvas } = renderHTML(html, {
+  width: 600,
+  pixelRatio: window.devicePixelRatio,
+});
+```
+
+### Render onto existing canvas
+
+```typescript
+const canvas = document.getElementById('my-canvas');
+renderHTML(html, { canvas, width: 800, height: 600 });
+```
+
+## API
+
+### `renderHTML(html, options): RenderResult`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `width` | `number` | *required* | Layout width in CSS pixels |
+| `height` | `number` | auto | Fixed height (auto-sized from content if omitted) |
+| `css` | `string` | `''` | CSS stylesheet (supports `@font-face`, classes, selectors) |
+| `canvas` | `HTMLCanvasElement` | created | Target canvas element |
+| `pixelRatio` | `number` | `1` | Device pixel ratio for sharp rendering |
+| `useDomMeasurements` | `boolean` | `true` | Use DOM probes for cross-browser line height accuracy. Disable for DOM-free rendering (pure canvas). |
+
+Returns `{ canvas: HTMLCanvasElement, height: number }`.
+
+The function is **synchronous**. Fonts must be loaded before calling.
+
+## What it renders
+
+- Paragraphs, headings, divs, spans
+- Bold, italic, underline, strikethrough, overline
+- Text colors, background colors
+- Font families, sizes, weights (100-900)
+- Line height, letter spacing, text alignment (left/center/right/justify)
+- Ordered and unordered lists with nesting
+- Inline styles and CSS classes
+- `@font-face` web fonts (loaded automatically)
+- Flexbox layout (row/column)
+- Table layout (basic)
+- Text shadows, text stroke, gradient text
+- Decoration styles: solid, dotted, dashed, double, wavy
+- RTL text, CJK characters, emoji
+- `pre-wrap` whitespace handling
+- `overflow-wrap: break-word`
+
+## Cross-browser consistency
+
+The library targets Chrome as the primary browser. For consistent rendering across Chrome and Firefox, add these CSS rules to your input:
+
+```css
+/* Suppress Firefox's ::marker extra line height (~1.5px per list item).
+   render-tag draws list markers itself, so this loses nothing visually. */
+li::marker { content: none; font-size: 0; line-height: 0; }
+
+/* Fix Firefox emoji position drift (apply to elements with emoji).
+   Firefox's canvas kerning differs from DOM kerning for emoji characters,
+   causing cumulative X position shift. Disabling kerning makes them match.
+   Note: this slightly affects letter pair spacing for regular text. */
+.has-emoji { font-kerning: none; }
+```
+
+With `useDomMeasurements: true` (the default), the library uses hidden DOM probes to match Firefox's actual line box heights. If you disable DOM measurements (`useDomMeasurements: false`), the CSS above becomes especially important for Firefox consistency.
+
+## How it works
+
+1. **Parse** HTML with `DOMParser`
+2. **Resolve styles** via hidden DOM + `getComputedStyle` (CSS cascade for free)
+3. **Layout** with pure canvas `measureText` (block flow, inline wrapping, margin collapsing)
+4. **Render** with canvas 2D API (`fillText`, `fillRect`, `strokeText`, etc.)
+
+Layout is computed from CSS values and canvas text metrics. Optional DOM probes (`useDomMeasurements`) improve cross-browser accuracy for line heights and mixed-font wrapping.
+
+## Development
+
+```bash
+npm install
+npx playwright install chromium
+
+# Run visual comparison demo
+npm run dev
+
+# Run tests (60 cases, Chromium via Playwright)
+npm test
+```
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+import type { RenderOptions, RenderResult, LayoutLine } from './types.js';
+export type { RenderOptions, RenderResult, LayoutLine };
+/**
+ * Render an HTML string onto a canvas element using pure 2D canvas API.
+ * Fonts must already be loaded on the page before calling this function.
+ *
+ * @param html - HTML string to render
+ * @param options - Rendering options (width is required)
+ * @returns The canvas element and computed content height
+ */
+export declare function renderHTML(html: string, options: RenderOptions): RenderResult;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAc,MAAM,YAAY,CAAC;AAMtF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;AAExD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GACrB,YAAY,CAgEd"}

package/lib/index.js

@@ -0,0 +1,69 @@
+import { parseHTML } from './parse.js';
+import { resolveStyles } from './style-resolver.js';
+import { buildLayoutTree } from './layout.js';
+import { renderNode } from './render.js';
+/**
+ * Render an HTML string onto a canvas element using pure 2D canvas API.
+ * Fonts must already be loaded on the page before calling this function.
+ *
+ * @param html - HTML string to render
+ * @param options - Rendering options (width is required)
+ * @returns The canvas element and computed content height
+ */
+export function renderHTML(html, options) {
+    const { width, height, css: extraCSS, pixelRatio = 1, useDomMeasurements = true, debug } = options;
+    // 1. Parse HTML and extract CSS
+    const { fragment, css } = parseHTML(html, extraCSS);
+    // 2. Resolve styles using hidden DOM (getComputedStyle only, no measurements)
+    const { tree, cleanup } = resolveStyles(fragment, css, width, height);
+    // 3. Create canvas
+    const canvas = options.canvas || document.createElement('canvas');
+    const tmpCanvas = document.createElement('canvas');
+    const ctx = tmpCanvas.getContext('2d');
+    ctx.fontKerning = 'normal';
+    // 4. Build layout tree using pure canvas measurement
+    const { root, height: contentHeight } = buildLayoutTree(ctx, tree, width, useDomMeasurements, debug);
+    // 5. Size the output canvas
+    const finalHeight = height || contentHeight;
+    canvas.width = Math.ceil(width * pixelRatio);
+    canvas.height = Math.ceil(finalHeight * pixelRatio);
+    canvas.style.width = `${width}px`;
+    canvas.style.height = `${finalHeight}px`;
+    const renderCtx = canvas.getContext('2d');
+    renderCtx.scale(pixelRatio, pixelRatio);
+    // 6. Render to canvas
+    renderNode(renderCtx, root);
+    // 7. Extract lines from layout tree — group by Y with tolerance.
+    // Use fontSize as proxy for height when grouping. Sub/sup text has
+    // different Y but belongs on the same visual line as parent text.
+    const wordPositions = [];
+    function walkLines(node) {
+        if (node.type === 'text' && node.text.trim()) {
+            wordPositions.push({ y: node.y, fontSize: node.style.fontSize, text: node.text });
+        }
+        if (node.type === 'box') {
+            for (const child of node.children)
+                walkLines(child);
+        }
+    }
+    walkLines(root);
+    wordPositions.sort((a, b) => a.y - b.y);
+    const lines = [];
+    let lineMaxFontSize = 0;
+    for (const wp of wordPositions) {
+        const lastLine = lines[lines.length - 1];
+        const tolerance = Math.max(lineMaxFontSize, wp.fontSize) * 0.5;
+        if (lastLine && Math.abs(wp.y - lastLine.y) < tolerance) {
+            lastLine.text += wp.text;
+            lineMaxFontSize = Math.max(lineMaxFontSize, wp.fontSize);
+        }
+        else {
+            lines.push({ y: Math.round(wp.y), text: wp.text });
+            lineMaxFontSize = wp.fontSize;
+        }
+    }
+    // 8. Cleanup
+    cleanup();
+    return { canvas, height: finalHeight, layoutRoot: root, lines };
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/layout.d.ts

@@ -0,0 +1,16 @@
+import type { StyledNode, LayoutBox, ResolvedStyle } from './types.js';
+/**
+ * Build a canvas font string from resolved style.
+ */
+export declare function buildCanvasFont(style: ResolvedStyle): string;
+/**
+ * Build the layout tree from the styled tree using pure canvas measurement.
+ * No DOM measurements used — all positions computed from CSS values + canvas.measureText.
+ */
+export declare function getDomMeasureCount(): number;
+export declare function resetDomMeasureCount(): void;
+export declare function buildLayoutTree(ctx: CanvasRenderingContext2D, styledTree: StyledNode, containerWidth: number, useDomMeasurements?: boolean, debug?: (entry: import('./types.ts').DebugEntry) => void): {
+    root: LayoutBox;
+    height: number;
+};
+//# sourceMappingURL=layout.d.ts.map

package/lib/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAc,SAAS,EAAc,aAAa,EAAE,MAAM,YAAY,CAAC;AAqG/F;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAO5D;AA+0CD;;;GAGG;AACH,wBAAgB,kBAAkB,WAA+B;AACjE,wBAAgB,oBAAoB,SAA4B;AAEhE,wBAAgB,eAAe,CAC7B,GAAG,EAAE,wBAAwB,EAC7B,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,MAAM,EACtB,kBAAkB,UAAO,EACzB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,YAAY,EAAE,UAAU,KAAK,IAAI,GACvD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAcrC"}