render-tag 0.1.2 → 0.1.4

package/README.md

@@ -6,7 +6,7 @@ Render HTML rich text onto canvas with the 2D API. No SVG, no `foreignObject`
 
 ## 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.
+When you need rich text as part of a canvas — design editors, image export, canvas-based apps — the standard SVG `foreignObject` approach is slow. `render-tag` parses your HTML, resolves styles with a built-in CSS parser, then lays out and draws everything with pure canvas 2D calls. It's significantly faster than SVG-based approaches.
 
 By design, render-tag focuses on **rich text only** — paragraphs, headings, lists, tables, inline formatting. It is not designed for interactive elements (buttons, inputs, iframes) or complex HTML layouts. This focus is what makes it fast.
 
@@ -109,7 +109,7 @@ All-in-one: compute layout and draw in a single call.
 | `ctx` | `CanvasRenderingContext2D` | — | Existing context to draw onto (no resizing/scaling) |
 | `canvas` | `HTMLCanvasElement \| OffscreenCanvas` | created | Target canvas element (mutually exclusive with `ctx`) |
 | `pixelRatio` | `number` | `devicePixelRatio` | Device pixel ratio for sharp rendering |
-| `accuracy` | `'balanced' \| 'performance'` | `'balanced'` | `'balanced'` uses DOM probes for cross-browser line height accuracy. `'performance'` uses pure canvas API only. |
+| `accuracy` | `'balanced' \| 'performance'` | `'performance'` | `'balanced'` uses DOM probes for cross-browser line height accuracy. `'performance'` uses pure canvas API only. |
 
 Returns `{ canvas, height, layoutRoot, lines }`.
 
@@ -124,7 +124,7 @@ Compute layout without rendering. Use when you need to measure content or render
 | `html` | `string` | *required* | HTML string (include `<style>` tags for CSS) |
 | `width` | `number` | *required* | Layout width in CSS pixels |
 | `height` | `number` | auto | Fixed height (auto-sized from content if omitted) |
-| `accuracy` | `'balanced' \| 'performance'` | `'balanced'` | Measurement accuracy mode |
+| `accuracy` | `'balanced' \| 'performance'` | `'performance'` | Measurement accuracy mode |
 
 Returns `{ layoutRoot, height, lines }`.
 
@@ -176,11 +176,16 @@ drawLayout({ layout: result, width: 400, ctx: offscreenCtx });
 - `overflow-wrap: break-word`
 - Soft hyphens (`&shy;`)
 
-## Cross-browser consistency
+## Recommended CSS reset
 
-The library targets Chrome as the primary browser. For consistent rendering across Chrome and Firefox, add these CSS rules to your input:
+For best consistency between DOM and canvas rendering, add these CSS rules to your input HTML:
 
 ```css
+/* Normalize monospace font size.
+   Chrome reduces <code>/<pre> font-size via a UA quirk that canvas can't replicate.
+   This makes DOM and canvas render code at the same size. */
+code, pre, kbd, samp { font-size: inherit; }
+
 /* 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; }
@@ -192,29 +197,28 @@ li::marker { content: none; font-size: 0; line-height: 0; }
 .has-emoji { font-kerning: none; }
 ```
 
-With `accuracy: 'balanced'` (the default), the library uses hidden DOM probes to match Firefox's actual line box heights. With `accuracy: 'performance'`, the CSS above becomes especially important for Firefox consistency.
+The default `accuracy: 'performance'` uses pure canvas API measurements with no DOM touches, producing consistent canvas output across browsers. Use `accuracy: 'balanced'` if you need each browser's canvas output to match its own native DOM rendering more closely (at the cost of cross-browser canvas consistency).
 
-## How it works
+## Design decisions
 
-1. **Parse** HTML with `DOMParser`
-2. **Resolve styles** via hidden DOM + `getComputedStyle` (CSS cascade for free)
-3. **Layout** with canvas `measureText` (block flow, inline wrapping, margin collapsing)
-4. **Render** with canvas 2D API (`fillText`, `fillRect`, `strokeText`, etc.)
+### Chrome-first rendering
 
-Style resolution uses a hidden DOM element with `getComputedStyle` to get the full CSS cascade. Layout and rendering are done entirely with the canvas 2D API. Optional DOM probes (`accuracy: 'balanced'`) improve cross-browser accuracy for line heights and mixed-font wrapping.
+Chrome is the primary target browser. When a rendering choice must favor one browser over another, Chrome wins. All development and CI testing defaults to Chromium.
 
-## Development
+### Cross-browser consistency over per-browser accuracy
 
-```bash
-npm install
-npx playwright install chromium
+The library prioritizes producing **the same canvas output in every browser** over matching each browser's native DOM rendering pixel-for-pixel. If Chrome and Firefox render a `<p>` slightly differently in DOM, our canvas output should match Chrome's version in both browsers — not adapt to each browser's quirks.
 
-# Run visual comparison demo
-npm run dev
+In other words: identical canvas output everywhere > perfect DOM fidelity per browser. Users expect the same visual result regardless of which browser their audience uses.
 
-# Run tests (60 cases, Chromium via Playwright)
-npm test
-```
+## How it works
+
+1. **Parse** HTML with `DOMParser`
+2. **Resolve styles** via built-in CSS resolver (selector matching, cascade, inheritance — no DOM insertion)
+3. **Layout** with canvas `measureText` (block flow, inline wrapping, margin collapsing)
+4. **Render** with canvas 2D API (`fillText`, `fillRect`, `strokeText`, etc.)
+
+Style resolution uses a built-in CSS parser and resolver that handles selectors, specificity, cascade, and inheritance without inserting HTML into the document. Layout and rendering are done entirely with the canvas 2D API.
 
 ## License
 

package/lib/css-resolver.d.ts

@@ -0,0 +1,10 @@
+import type { StyledNode } from './types.js';
+/**
+ * Resolve styles for a DOM tree without inserting into the document.
+ * Parses CSS rules, matches selectors, resolves cascade + inheritance.
+ */
+export declare function resolveStylesFromCSS(fragment: DocumentFragment, css: string, containerWidth: number): {
+    tree: StyledNode;
+    cleanup: () => void;
+};
+//# sourceMappingURL=css-resolver.d.ts.map

package/lib/css-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-resolver.d.ts","sourceRoot":"","sources":["../src/css-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,UAAU,EAAE,MAAM,YAAY,CAAC;AAm4B5D;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GACrB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAiZ3C"}