render-tag 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+Render HTML rich text onto canvas with the 2D API. No SVG, no `foreignObject` — just `fillText`, `measureText`, and drawing primitives.
 
 **Website & demos:** [https://polotno.com/render-tag/](https://polotno.com/render-tag/)
 
@@ -8,6 +8,8 @@ Render HTML rich text onto a canvas element using pure 2D canvas API. No SVG, no
 
 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.
 
+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.
+
 ## Install
 
 ```bash
@@ -17,85 +19,145 @@ npm install render-tag
 ## Usage
 
 ```typescript
-import { renderHTML } from 'render-tag';
+import { render } from 'render-tag';
 
-const { canvas, height } = renderHTML(
-  '<p>Hello <strong>world</strong></p>',
-  { width: 400 }
-);
+const { canvas, height } = render({
+  html: '<p>Hello <strong>world</strong></p>',
+  width: 400,
+});
 
 document.body.appendChild(canvas);
 ```
 
 ### With CSS
 
+Include `<style>` tags in your HTML string:
+
 ```typescript
-const { canvas } = renderHTML(
-  '<p class="title">Styled text</p>',
-  {
-    width: 600,
-    css: `
+const { canvas } = render({
+  html: `
+    <style>
       .title {
         font-family: Georgia, serif;
         font-size: 24px;
         color: #1a1a1a;
       }
-    `,
-  }
-);
+    </style>
+    <p class="title">Styled text</p>
+  `,
+  width: 600,
+});
 ```
 
-### With web fonts
+### Font loading
+
+`render` is **synchronous** and does not load fonts. You must ensure fonts are loaded before calling it. If a font isn't loaded, the browser falls back to a default font and text metrics will be wrong.
 
 ```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; }
-    `,
-  }
-);
+// Load fonts before rendering
+await document.fonts.load('400 16px "Roboto"');
+await document.fonts.load('700 16px "Roboto"');
+
+// Now render — fonts are guaranteed to be available
+const { canvas } = render({ html, width: 500 });
+
+// Re-render if fonts load later
+document.fonts.onloadingdone = () => {
+  render({ html, width: 500 });
+};
 ```
 
+You do **not** need to pass `@font-face` rules separately. As long as fonts are loaded in the document (via `<link>`, `@font-face` in a stylesheet, or the CSS Font Loading API), `render` can use them.
+
 ### High-DPI / Retina
 
+`pixelRatio` defaults to `devicePixelRatio`, so HiDPI displays are sharp out of the box. Override if needed:
+
 ```typescript
-const { canvas } = renderHTML(html, {
-  width: 600,
-  pixelRatio: window.devicePixelRatio,
-});
+const { canvas } = render({ html, width: 600, pixelRatio: 1 });
 ```
 
 ### Render onto existing canvas
 
 ```typescript
 const canvas = document.getElementById('my-canvas');
-renderHTML(html, { canvas, width: 800, height: 600 });
+render({ html, canvas, width: 800, height: 600 });
+```
+
+### Render onto existing context
+
+Draw directly onto a context you control (no canvas resizing or scaling):
+
+```typescript
+const ctx = myCanvas.getContext('2d');
+render({ html, ctx, width: 400 });
 ```
 
+This is useful for compositing multiple renders onto one canvas or rendering onto an `OffscreenCanvas`.
+
 ## API
 
-### `renderHTML(html, options): RenderResult`
+### `render(config): RenderResult`
+
+All-in-one: compute layout and draw in a single call.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
+| `html` | `string` | *required* | HTML string to render (include `<style>` tags for CSS) |
 | `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). |
+| `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. |
 
-Returns `{ canvas: HTMLCanvasElement, height: number }`.
+Returns `{ canvas, height, layoutRoot, lines }`.
 
 The function is **synchronous**. Fonts must be loaded before calling.
 
+### `layout(config): LayoutResult`
+
+Compute layout without rendering. Use when you need to measure content or render the same layout onto multiple targets.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `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 |
+
+Returns `{ layoutRoot, height, lines }`.
+
+### `drawLayout(config): { canvas }`
+
+Draw a pre-computed layout onto a canvas or context.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `layout` | `LayoutResult` | *required* | Result from `layout()` |
+| `width` | `number` | *required* | Width used during layout (must match) |
+| `ctx` | `CanvasRenderingContext2D` | — | Existing context to draw onto (no resizing/scaling) |
+| `canvas` | `HTMLCanvasElement \| OffscreenCanvas` | created | Target canvas (mutually exclusive with `ctx`) |
+| `pixelRatio` | `number` | `devicePixelRatio` | Device pixel ratio |
+
+### Example: layout once, draw many
+
+```typescript
+import { layout, drawLayout } from 'render-tag';
+
+const result = layout({ html, width: 400 });
+console.log('content height:', result.height);
+
+// Draw onto a thumbnail canvas
+drawLayout({ layout: result, width: 400, canvas: thumbnailCanvas });
+
+// Draw onto the main canvas
+drawLayout({ layout: result, width: 400, canvas: mainCanvas });
+
+// Draw onto an existing context
+drawLayout({ layout: result, width: 400, ctx: offscreenCtx });
+```
+
 ## What it renders
 
 - Paragraphs, headings, divs, spans
@@ -105,7 +167,6 @@ The function is **synchronous**. Fonts must be loaded before calling.
 - 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
@@ -113,6 +174,7 @@ The function is **synchronous**. Fonts must be loaded before calling.
 - RTL text, CJK characters, emoji
 - `pre-wrap` whitespace handling
 - `overflow-wrap: break-word`
+- Soft hyphens (`&shy;`)
 
 ## Cross-browser consistency
 
@@ -130,16 +192,16 @@ li::marker { content: none; font-size: 0; line-height: 0; }
 .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.
+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.
 
 ## 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)
+3. **Layout** with 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.
+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.
 
 ## Development
 

package/lib/index.d.ts

@@ -1,12 +1,25 @@
-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
+import type { RenderConfig, RenderOptions, RenderResult, LayoutConfig, LayoutResult, DrawConfig, LayoutLine, AnyCanvas } from './types.js';
+export type { RenderConfig, RenderOptions, RenderResult, LayoutConfig, LayoutResult, DrawConfig, LayoutLine };
+/**
+ * Compute layout for an HTML string without rendering.
+ * Returns a reusable LayoutResult that can be drawn onto multiple targets via drawLayout().
+ */
+export declare function layout(config: LayoutConfig): LayoutResult;
+/**
+ * Draw a pre-computed layout onto a canvas or context.
+ * Use with layout() to render the same content onto multiple targets.
+ */
+export declare function drawLayout(config: DrawConfig): {
+    canvas: AnyCanvas;
+};
+/**
+ * Render an HTML string onto a canvas using pure 2D canvas API.
+ * Convenience function combining layout() + drawLayout().
+ * Fonts must already be loaded before calling this function.
+ */
+export declare function render(config: RenderConfig): RenderResult;
+/**
+ * @deprecated Use `render()` instead.
  */
 export declare function renderHTML(html: string, options: RenderOptions): RenderResult;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAAE,aAAa,EAAE,YAAY,EACzC,YAAY,EAAE,YAAY,EAAE,UAAU,EACtC,UAAU,EAAc,SAAS,EAClC,MAAM,YAAY,CAAC;AAMpB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAmC9G;;;GAGG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CA6BzD;AAID;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAyCpE;AAID;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CA2BzD;AAID;;GAEG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GACrB,YAAY,CAUd"}

package/lib/index.js

@@ -2,51 +2,19 @@ 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.
+// ─── Line extraction ─────────────────────────────────────────────────
+function extractLines(root) {
     const wordPositions = [];
-    function walkLines(node) {
+    function walk(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);
+                walk(child);
         }
     }
-    walkLines(root);
+    walk(root);
     wordPositions.sort((a, b) => a.y - b.y);
     const lines = [];
     let lineMaxFontSize = 0;
@@ -62,8 +30,114 @@ export function renderHTML(html, options) {
             lineMaxFontSize = wp.fontSize;
         }
     }
-    // 8. Cleanup
+    return lines;
+}
+// ─── layout() ────────────────────────────────────────────────────────
+/**
+ * Compute layout for an HTML string without rendering.
+ * Returns a reusable LayoutResult that can be drawn onto multiple targets via drawLayout().
+ */
+export function layout(config) {
+    const { html, width, height, accuracy = 'balanced', debug, } = config;
+    if (!width || width <= 0 || Number.isNaN(width)) {
+        throw new TypeError(`layout: width must be a positive number, got ${width}`);
+    }
+    const useDomMeasurements = accuracy === 'balanced';
+    const { fragment, css } = parseHTML(html);
+    const { tree, cleanup } = resolveStyles(fragment, css, width, height);
+    const tmpCanvas = document.createElement('canvas');
+    const measureCtx = tmpCanvas.getContext('2d');
+    measureCtx.fontKerning = 'normal';
+    const { root, height: contentHeight } = buildLayoutTree(measureCtx, tree, width, useDomMeasurements, debug);
+    const finalHeight = height || contentHeight;
+    const lines = extractLines(root);
     cleanup();
-    return { canvas, height: finalHeight, layoutRoot: root, lines };
+    return { layoutRoot: root, height: finalHeight, lines };
+}
+// ─── drawLayout() ────────────────────────────────────────────────────
+/**
+ * Draw a pre-computed layout onto a canvas or context.
+ * Use with layout() to render the same content onto multiple targets.
+ */
+export function drawLayout(config) {
+    const { layout: layoutResult, width, pixelRatio = globalThis.devicePixelRatio ?? 1, } = config;
+    if (config.ctx && config.canvas) {
+        throw new TypeError('drawLayout: ctx and canvas are mutually exclusive — provide one or neither');
+    }
+    const finalHeight = layoutResult.height;
+    let canvas;
+    let renderCtx;
+    if (config.ctx) {
+        renderCtx = config.ctx;
+        canvas = config.ctx.canvas;
+    }
+    else if (config.canvas) {
+        canvas = config.canvas;
+        canvas.width = Math.ceil(width * pixelRatio);
+        canvas.height = Math.ceil(finalHeight * pixelRatio);
+        if ('style' in canvas) {
+            canvas.style.width = `${width}px`;
+            canvas.style.height = `${finalHeight}px`;
+        }
+        renderCtx = canvas.getContext('2d');
+        renderCtx.scale(pixelRatio, pixelRatio);
+    }
+    else {
+        canvas = document.createElement('canvas');
+        canvas.width = Math.ceil(width * pixelRatio);
+        canvas.height = Math.ceil(finalHeight * pixelRatio);
+        canvas.style.width = `${width}px`;
+        canvas.style.height = `${finalHeight}px`;
+        renderCtx = canvas.getContext('2d');
+        renderCtx.scale(pixelRatio, pixelRatio);
+    }
+    renderNode(renderCtx, layoutResult.layoutRoot);
+    return { canvas };
+}
+// ─── render() ────────────────────────────────────────────────────────
+/**
+ * Render an HTML string onto a canvas using pure 2D canvas API.
+ * Convenience function combining layout() + drawLayout().
+ * Fonts must already be loaded before calling this function.
+ */
+export function render(config) {
+    if (config.ctx && config.canvas) {
+        throw new TypeError('render: ctx and canvas are mutually exclusive — provide one or neither');
+    }
+    const layoutResult = layout({
+        html: config.html,
+        width: config.width,
+        height: config.height,
+        accuracy: config.accuracy,
+        debug: config.debug,
+    });
+    const { canvas } = drawLayout({
+        layout: layoutResult,
+        width: config.width,
+        ctx: config.ctx,
+        canvas: config.canvas,
+        pixelRatio: config.pixelRatio,
+    });
+    return {
+        canvas,
+        height: layoutResult.height,
+        layoutRoot: layoutResult.layoutRoot,
+        lines: layoutResult.lines,
+    };
+}
+// ─── Deprecated ──────────────────────────────────────────────────────
+/**
+ * @deprecated Use `render()` instead.
+ */
+export function renderHTML(html, options) {
+    return render({
+        html: options.css ? `<style>${options.css}</style>${html}` : html,
+        width: options.width,
+        height: options.height,
+        canvas: options.canvas,
+        pixelRatio: options.pixelRatio ?? 1,
+        accuracy: options.useDomMeasurements === false ? 'performance' : 'balanced',
+        debug: options.debug,
+    });
 }
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/layout.d.ts.map

@@ -1 +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"}
+{"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;AA83CD;;;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"}

package/lib/layout.js

@@ -309,10 +309,31 @@ function getSegmenter() {
 function tokenizeString(ctx, text, run, allWords) {
     // Split on zero-width spaces and soft hyphens (break opportunities)
     if (text.includes('\u200B') || text.includes('\u00AD')) {
-        const parts = text.split(/[\u200B\u00AD]/);
+        // Split but keep delimiters to distinguish soft hyphens from zero-width spaces
+        const parts = text.split(/(\u200B|\u00AD)/);
+        let nextIsSoftHyphen = false;
         for (const part of parts) {
-            if (part)
-                tokenizeString(ctx, part, run, allWords);
+            if (part === '\u00AD') {
+                // Mark the PREVIOUS word as a soft-hyphen break point
+                nextIsSoftHyphen = true;
+                continue;
+            }
+            if (part === '\u200B' || part === '') {
+                nextIsSoftHyphen = false;
+                continue;
+            }
+            const prevLen = allWords.length;
+            tokenizeString(ctx, part, run, allWords);
+            // If the previous delimiter was a soft hyphen, mark the word
+            // just before this part as having a soft-hyphen break opportunity
+            if (nextIsSoftHyphen && prevLen > 0) {
+                allWords[prevLen - 1].isSoftHyphenBreak = true;
+            }
+            nextIsSoftHyphen = false;
+        }
+        // If the text ends with a soft hyphen, mark the last word
+        if (nextIsSoftHyphen && allWords.length > 0) {
+            allWords[allWords.length - 1].isSoftHyphenBreak = true;
         }
         return;
     }
@@ -509,7 +530,7 @@ function isCJK(char) {
 function breakWordIfNeeded(ctx, word, contentWidth, currentLineWidth) {
     // Check if word has CJK characters — always break at character level
     const hasCJK = [...word.text].some(isCJK);
-    // Check if word needs break-word splitting
+    // Check if word needs break-word splitting — when it won't fit on a fresh line
     const needsBreak = word.width > contentWidth &&
         (word.style.overflowWrap === 'break-word' || word.style.wordBreak === 'break-all');
     if (!hasCJK && !needsBreak)
@@ -555,13 +576,29 @@ function flowWordsIntoLines(ctx, words, contentWidth, whiteSpace, useBulletProbe
     let currentLine = { words: [], totalWidth: 0, lineHeight: 0 };
     const noWrap = whiteSpace === 'nowrap' || whiteSpace === 'pre';
     const isPreWrap = whiteSpace === 'pre-wrap' || whiteSpace === 'pre' || whiteSpace === 'pre-line';
-    function pushLine() {
+    function pushLine(isSoftWrap = false) {
         const hadWords = currentLine.words.length > 0;
         // Trim trailing spaces
         while (currentLine.words.length > 0 && currentLine.words[currentLine.words.length - 1].isSpace) {
             currentLine.totalWidth -= currentLine.words[currentLine.words.length - 1].width;
             currentLine.words.pop();
         }
+        // Soft hyphen: if this is a soft wrap and the last word has a soft-hyphen
+        // break, append a visible '-' since the word is being broken here.
+        if (isSoftWrap && currentLine.words.length > 0) {
+            const lastWord = currentLine.words[currentLine.words.length - 1];
+            if (lastWord.isSoftHyphenBreak) {
+                applyFont(ctx, lastWord.style);
+                const hyphenWidth = ctx.measureText('-').width;
+                currentLine.words.push({
+                    text: '-',
+                    width: hyphenWidth,
+                    style: lastWord.style,
+                    isSpace: false,
+                });
+                currentLine.totalWidth += hyphenWidth;
+            }
+        }
         // In pre-wrap mode, space-only lines still need height (they are content)
         if (currentLine.words.length > 0 || (hadWords && isPreWrap)) {
             if (_debug) {
@@ -609,8 +646,14 @@ function flowWordsIntoLines(ctx, words, contentWidth, whiteSpace, useBulletProbe
             ? breakWordIfNeeded(ctx, word, contentWidth, currentLine.totalWidth)
             : [word];
         for (const piece of pieces) {
+            // Trailing punctuation (e.g. comma after </span>) should not wrap
+            // independently — browsers keep it with the preceding word.
+            const isTrailingPunct = !piece.isSpace && piece.text.length > 0 &&
+                /^[,.\;:!?\)\]\}'"»›]+$/.test(piece.text) &&
+                currentLine.words.length > 0 &&
+                !currentLine.words[currentLine.words.length - 1].isSpace;
             // Would this piece overflow?
-            if (!piece.isSpace && currentLine.words.length > 0 &&
+            if (!piece.isSpace && !isTrailingPunct && currentLine.words.length > 0 &&
                 currentLine.totalWidth + piece.width > contentWidth) {
                 const overflow = currentLine.totalWidth + piece.width - contentWidth;
                 // For borderline cases (overflow < 1px), word-by-word delta
@@ -638,7 +681,7 @@ function flowWordsIntoLines(ctx, words, contentWidth, whiteSpace, useBulletProbe
                             data: { text: piece.text, overflow, lineWidth: currentLine.totalWidth, pieceWidth: piece.width, contentWidth, lineText },
                         });
                     }
-                    pushLine();
+                    pushLine(true);
                     afterHardBreak = false;
                 }
             }
@@ -662,7 +705,7 @@ function flowWordsIntoLines(ctx, words, contentWidth, whiteSpace, useBulletProbe
                                 data: { text: piece.text, remaining, domWidth, contentWidth },
                             });
                         }
-                        pushLine();
+                        pushLine(true);
                         afterHardBreak = false;
                     }
                 }