ntk 3.2.0 → 3.4.0

package/lib/text/layout.js

@@ -30,8 +30,13 @@ function isWsGlyph(g) {
  * - `direction` — 'ltr' | 'rtl' | 'auto' base paragraph direction
  *
  * The result is inspectable before/without drawing: `width`, `height`, and
- * `lines[] = { x, y, baseline, width, ascent, descent, runs }` with
- * `runs[] = { x, width, run, span }` in visual order.
+ * `lines[] = { x, y, baseline, width, ascent, descent, runs, start, end }`
+ * with `runs[] = { x, width, run, span, start, end }` in visual order
+ * (`start`/`end` are logical UTF-16 ranges into the full text).
+ *
+ * `caretPosition(index)` / `indexAt(x, y)` map logical code-point indices
+ * to visual caret geometry and back (bidi/ligature/trailing-whitespace
+ * aware) — see docs/text.md.
  */
 export class TextLayout {
   constructor(fonts, content, style = {}, options = {}) {
@@ -59,6 +64,8 @@ export class TextLayout {
     });
 
     const text = spans.map((s) => s.text).join('');
+    this._text = text;
+    this._cpOffsets = null; // lazy code-point index -> code-unit offset table
     const emb = embeddingLevels(text, options.direction);
     const levels = emb.levels;
     this.baseLevel = emb.paragraphs.length ? emb.paragraphs[0].level & 1 : 0;
@@ -139,16 +146,31 @@ export class TextLayout {
     let layoutWidth = 0;
 
     for (const toks of lineTokens) {
-      // entries carry .level so reorderRuns can order them (UAX#9 L2)
+      // entries carry .level so reorderRuns can order them (UAX#9 L2);
+      // .start/.end are absolute code-unit ranges into the full text, kept
+      // for caret positioning (caretPosition / indexAt)
       let entries = [];
       for (const token of toks) {
         for (const frag of token.fragments) {
           for (const run of frag.shaped.runs) {
-            entries.push({ run, span: frag.span, level: run.level });
+            entries.push({
+              run,
+              span: frag.span,
+              level: run.level,
+              start: frag.start + run.start,
+              end: frag.start + run.end
+            });
           }
         }
       }
-      stripTrailingWhitespace(entries);
+      const lineStart = toks[0].start;
+      const lineEnd = toks[toks.length - 1].end;
+      const trailing = stripTrailingWhitespace(entries);
+      const contentEnd = trailing
+        ? trailing.start
+        : entries.length
+          ? entries[entries.length - 1].end
+          : lineStart;
       entries = reorderRuns(entries);
 
       let ascent = 0;
@@ -157,7 +179,7 @@ export class TextLayout {
       const runs = [];
       let x = 0;
       for (const e of entries) {
-        runs.push({ x, width: e.run.width, run: e.run, span: e.span });
+        runs.push({ x, width: e.run.width, run: e.run, span: e.span, start: e.start, end: e.end });
         x += e.run.width;
         const m = e.run.font.metrics(e.run.size);
         if (m.ascent > ascent) ascent = m.ascent;
@@ -172,7 +194,19 @@ export class TextLayout {
         natural = m.lineHeight;
       }
       if (x > layoutWidth) layoutWidth = x;
-      this.lines.push({ x: 0, y, baseline: y + ascent, width: x, ascent, descent, runs });
+      this.lines.push({
+        x: 0,
+        y,
+        baseline: y + ascent,
+        width: x,
+        ascent,
+        descent,
+        runs,
+        start: lineStart,
+        end: lineEnd,
+        _contentEnd: contentEnd,
+        _trailing: trailing
+      });
       y += natural * lineHeightMul;
     }
 
@@ -204,7 +238,7 @@ export class TextLayout {
       if (fragText.length > 0) {
         const fragLevels = normalizedLevels(levels, pos, pos + fragText.length);
         const shaped = this.fonts._shapeCached(fragText, span, fragLevels);
-        fragments.push({ text: fragText, span, shaped });
+        fragments.push({ text: fragText, span, shaped, start: pos });
         width += shaped.width;
       }
       pos = fragEnd;
@@ -219,7 +253,7 @@ export class TextLayout {
         wsWidth = m[0].length * spaceGlyph.advanceWidth * last.span.font.scale(last.span.size);
       }
     }
-    return { fragments, width, wsWidth, required };
+    return { fragments, width, wsWidth, required, start, end };
   }
 
   // split an over-wide token at the widest cluster boundary that fits
@@ -249,7 +283,9 @@ export class TextLayout {
           hi = mid - 1;
         }
       }
-      if (best) headFrags.push({ text: best.text, span: frag.span, shaped: best.shaped });
+      if (best) {
+        headFrags.push({ text: best.text, span: frag.span, shaped: best.shaped, start: frag.start });
+      }
 
       const restFrags = [];
       const restText = frag.text.slice(best ? best.len : 0);
@@ -257,26 +293,30 @@ export class TextLayout {
         restFrags.push({
           text: restText,
           span: frag.span,
-          shaped: this.fonts._shapeCached(restText, frag.span, '0')
+          shaped: this.fonts._shapeCached(restText, frag.span, '0'),
+          start: frag.start + (best ? best.len : 0)
         });
       }
       restFrags.push(...token.fragments.slice(i + 1));
       const sum = (frags) => frags.reduce((w, f) => w + f.shaped.width, 0);
+      const splitAt = restFrags.length ? restFrags[0].start : token.end;
       const head = headFrags.length
-        ? { fragments: headFrags, width: sum(headFrags), wsWidth: 0, required: false }
+        ? { fragments: headFrags, width: sum(headFrags), wsWidth: 0, required: false, start: token.start, end: splitAt }
         : null;
       const rest = {
         fragments: restFrags,
         width: sum(restFrags),
         wsWidth: token.wsWidth,
-        required: token.required
+        required: token.required,
+        start: splitAt,
+        end: token.end
       };
       return [head, rest];
     }
     // everything fit after all (float rounding): no split needed
     return [
       { ...token, required: false },
-      { fragments: [], width: 0, wsWidth: 0, required: token.required }
+      { fragments: [], width: 0, wsWidth: 0, required: token.required, start: token.end, end: token.end }
     ];
   }
 
@@ -308,11 +348,283 @@ export class TextLayout {
     ctx._markDirty();
     return this;
   }
+
+  // ---- caret positioning / hit testing ----------------------------------
+  //
+  // Both methods speak logical **code-point** indices (what you get from
+  // `Array.from(text)` / caret arithmetic on code points), converted
+  // internally to the code-unit ranges the shaped runs carry.
+  //
+  // Conventions (v1):
+  // - Direction boundaries: a single caret, placed at the trailing edge of
+  //   the character logically before the index (the run containing the
+  //   previous character wins). At a line start the leading edge of the
+  //   run containing the index is used. Indices on both sides of a
+  //   direction boundary may therefore map to the same visual x.
+  // - Ligature/cluster interior indices interpolate proportionally (by
+  //   code-point count) across the cluster's advance.
+  // - An index just after a hard break belongs to the next line; the index
+  //   of the break character itself sits at the end of its line. An index
+  //   at a soft wrap boundary belongs to the start of the wrapped line.
+  // - Trailing whitespace stripped from a line end still advances the
+  //   caret, extending past the line edge on the paragraph-direction side.
+
+  /** lazy code-point index -> code-unit offset table (n + 1 entries) */
+  _offsets() {
+    if (!this._cpOffsets) {
+      const offs = [];
+      let cu = 0;
+      for (const ch of this._text) {
+        offs.push(cu);
+        cu += ch.length;
+      }
+      offs.push(cu);
+      this._cpOffsets = offs;
+    }
+    return this._cpOffsets;
+  }
+
+  /** code-unit offset -> code-point index (binary search) */
+  _cpOf(cu) {
+    const offs = this._offsets();
+    let lo = 0;
+    let hi = offs.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (offs[mid] <= cu) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo;
+  }
+
+  /**
+   * Visual caret geometry for a logical code-point index in
+   * `[0, codePointCount]` (out-of-range indices clamp).
+   *
+   * @returns {{ x, y, height, line }} `x` is the caret's visual x within
+   *   the layout box (alignment included), `y` the top of the line box,
+   *   `height` = ascent + descent, `line` the line index.
+   */
+  caretPosition(index) {
+    const offs = this._offsets();
+    const n = offs.length - 1;
+    const i = Math.max(0, Math.min(Math.floor(index), n));
+    const cu = offs[i];
+    let li = 0;
+    for (let l = this.lines.length - 1; l >= 0; l--) {
+      if (cu >= this.lines[l].start) {
+        li = l;
+        break;
+      }
+    }
+    const line = this.lines[li];
+    return {
+      x: this._caretXInLine(line, cu),
+      y: line.y,
+      height: line.ascent + line.descent,
+      line: li
+    };
+  }
+
+  /**
+   * Hit test: the logical code-point index of the caret boundary closest
+   * to layout-box coordinates (x, y). Picks the line by y (clamping above
+   * the first / below the last line), then the nearest boundary by x in
+   * visual order — a click past the midpoint of a cluster snaps to its far
+   * edge. Inverse of `caretPosition` up to bidi boundary ambiguity.
+   */
+  indexAt(x, y) {
+    const lines = this.lines;
+    if (lines.length === 0) return 0;
+    let li = lines.length - 1;
+    for (let l = 0; l < lines.length; l++) {
+      const bottom = l + 1 < lines.length ? lines[l + 1].y : Infinity;
+      if (y < bottom) {
+        li = l;
+        break;
+      }
+    }
+    const line = lines[li];
+    const lx = x - line.x;
+    const t = line._trailing;
+    const rightSide = !(this.baseLevel & 1);
+    if (t && (rightSide ? lx > line.width : lx < 0)) {
+      // in the stripped trailing-whitespace zone past the line edge
+      const dist = rightSide ? lx - line.width : -lx;
+      let pos = t.start;
+      let edge = 0;
+      for (const g of t.glyphs) {
+        if (dist < edge + g.ax / 2) return this._cpOf(pos);
+        edge += g.ax;
+        pos += g.len;
+      }
+      return this._cpOf(pos);
+    }
+    if (line.runs.length === 0) return this._cpOf(line.start);
+    const cx = Math.max(0, Math.min(lx, line.width));
+    let target = line.runs[line.runs.length - 1];
+    for (const r of line.runs) {
+      if (cx <= r.x + r.width) {
+        target = r;
+        break;
+      }
+    }
+    return this._cpOf(this._runIndexAt(target, cx));
+  }
+
+  /** caret x (layout-box coords) for an absolute code-unit offset on `line` */
+  _caretXInLine(line, cu) {
+    const t = line._trailing;
+    if (t && cu > t.start) {
+      // inside (or past) the stripped trailing whitespace: extend beyond
+      // the visual line edge on the paragraph-direction side
+      let adv = 0;
+      let pos = t.start;
+      for (const g of t.glyphs) {
+        if (cu >= pos + g.len) {
+          adv += g.ax;
+          pos += g.len;
+        } else {
+          if (cu > pos) adv += (g.ax * (cu - pos)) / g.len;
+          break;
+        }
+      }
+      return this.baseLevel & 1 ? line.x - adv : line.x + line.width + adv;
+    }
+    if (line.runs.length === 0) return line.x;
+    const cc = Math.min(cu, line._contentEnd);
+    // previous-character rule: the run containing the char before the index
+    let target = null;
+    if (cc > line.start) {
+      for (const r of line.runs) {
+        if (r.start < cc && cc <= r.end) {
+          target = r;
+          break;
+        }
+      }
+    }
+    if (!target) {
+      for (const r of line.runs) {
+        if (r.start <= cc && cc < r.end) {
+          target = r;
+          break;
+        }
+      }
+    }
+    if (!target) target = line.runs[this.baseLevel & 1 ? line.runs.length - 1 : 0];
+    return line.x + this._boundaryX(target, cc);
+  }
+
+  /** x of logical boundary `cu` within a positioned line run (run-local + run.x) */
+  _boundaryX(lineRun, cu) {
+    const { run, start, end } = lineRun;
+    let x = lineRun.x;
+    if (run.direction === 'rtl') {
+      // glyphs stored in visual order; leftmost glyph is logically last
+      let pos = end;
+      for (const g of run.glyphs) {
+        const len = cuLength(g.codePoints);
+        if (len === 0) {
+          x += g.ax;
+          continue;
+        }
+        if (cu >= pos) return x;
+        if (cu > pos - len) {
+          // fraction of the cluster left of the caret = code points after cu
+          const cps = g.codePoints;
+          let k = 0;
+          let c = pos;
+          for (let j = cps.length - 1; j >= 0; j--) {
+            const l = cps[j] > 0xffff ? 2 : 1;
+            if (c - l < cu) break;
+            c -= l;
+            k++;
+          }
+          return x + (g.ax * k) / cps.length;
+        }
+        pos -= len;
+        x += g.ax;
+      }
+      return x;
+    }
+    let pos = start;
+    for (const g of run.glyphs) {
+      const len = cuLength(g.codePoints);
+      if (len === 0) {
+        x += g.ax;
+        continue;
+      }
+      if (cu <= pos) return x;
+      if (cu < pos + len) {
+        const cps = g.codePoints;
+        let k = 0;
+        let c = pos;
+        for (const cp of cps) {
+          const l = cp > 0xffff ? 2 : 1;
+          if (c + l > cu) break;
+          c += l;
+          k++;
+        }
+        return x + (g.ax * k) / cps.length;
+      }
+      pos += len;
+      x += g.ax;
+    }
+    return x;
+  }
+
+  /** nearest caret boundary (code units) to line-local x within a line run */
+  _runIndexAt(lineRun, lx) {
+    const { run, start, end } = lineRun;
+    const rtl = run.direction === 'rtl';
+    let pos = rtl ? end : start;
+    let gx = lineRun.x;
+    for (const g of run.glyphs) {
+      const len = cuLength(g.codePoints);
+      if (len === 0 || g.ax <= 0) {
+        gx += g.ax;
+        if (g.ax <= 0) pos += rtl ? -len : len;
+        continue;
+      }
+      if (lx <= gx + g.ax) {
+        const cps = g.codePoints;
+        let k = Math.round(((lx - gx) / g.ax) * cps.length);
+        k = Math.max(0, Math.min(k, cps.length));
+        // move k code points into the cluster from its left edge
+        let c = pos;
+        if (rtl) {
+          for (let j = cps.length - 1; j >= cps.length - k; j--) {
+            c -= cps[j] > 0xffff ? 2 : 1;
+          }
+        } else {
+          for (let j = 0; j < k; j++) c += cps[j] > 0xffff ? 2 : 1;
+        }
+        return c;
+      }
+      pos += rtl ? -len : len;
+      gx += g.ax;
+    }
+    return pos;
+  }
+}
+
+// UTF-16 length of a glyph cluster's codePoints array
+function cuLength(codePoints) {
+  let len = 0;
+  for (const cp of codePoints) len += cp > 0xffff ? 2 : 1;
+  return len;
 }
 
 // Drop trailing whitespace glyphs from the logical end of a line.
 // Shaped runs are shared via the shaping cache — clone instead of mutating.
+// Returns what was stripped — `{ start, glyphs: [{ ax, len }] }` in logical
+// order (absolute code-unit start, per-glyph advance and code-unit length) —
+// so caret positioning can still walk through trailing spaces, or null when
+// nothing was stripped. Adjusts the surviving entries' logical `end`.
 function stripTrailingWhitespace(entries) {
+  const stripped = [];
+  let strippedStart = null;
+  const result = () => (stripped.length ? { start: strippedStart, glyphs: stripped } : null);
   for (let i = entries.length - 1; i >= 0; i--) {
     const run = entries[i].run;
     // rtl runs store glyphs in visual order: their logical end is index 0
@@ -325,21 +637,35 @@ function stripTrailingWhitespace(entries) {
       count++;
       wsWidth += g.ax;
     }
-    if (count === 0) return;
+    if (count === 0) return result();
+    // stripped glyphs in logical order (rtl glyph storage is reversed)
+    const tail = fromFront
+      ? run.glyphs.slice(0, count).reverse()
+      : run.glyphs.slice(run.glyphs.length - count);
+    let cuStripped = 0;
+    const info = tail.map((g) => {
+      const len = cuLength(g.codePoints);
+      cuStripped += len;
+      return { ax: g.ax, len };
+    });
+    stripped.unshift(...info);
+    strippedStart = entries[i].end - cuStripped;
     if (count === run.glyphs.length) {
       entries.splice(i, 1);
       continue;
     }
     entries[i] = {
       ...entries[i],
+      end: entries[i].end - cuStripped,
       run: {
         ...run,
         glyphs: fromFront ? run.glyphs.slice(count) : run.glyphs.slice(0, -count),
         width: run.width - wsWidth
       }
     };
-    return;
+    return result();
   }
+  return result();
 }
 
 // compact levels key for the shaping cache: single char when uniform

package/lib/widgets/htmlview.js

@@ -65,6 +65,9 @@ const VOID_SKIP = new Set(['script', 'style', 'head', 'title', 'meta', 'link', '
  * Standalone (windowless) use mirrors MarkdownView:
  *   const view = new HtmlView(null, { fonts });
  *   view.setHtml(html); view.layout(width); view.draw(ctx, x, y);
+ * Content that arrives asynchronously (images) invalidates the layout —
+ * pass `onInvalidate` to re-layout/redraw when that happens (window mode
+ * repaints automatically).
  */
 export default class HtmlView {
   constructor(window, opts = {}) {
@@ -74,6 +77,10 @@ export default class HtmlView {
 
     /** called with (href, event, element) when a link is activated */
     this.onLink = opts.onLink ?? null;
+    /** called when async content (an image) invalidates the layout;
+     *  standalone hosts re-layout/redraw here — window mode also repaints
+     *  on its own */
+    this.onInvalidate = opts.onInvalidate ?? null;
     /** extra author stylesheet(s) applied after document <style>s */
     this._userSheets = [].concat(opts.stylesheet ?? []);
     /**
@@ -407,13 +414,11 @@ export default class HtmlView {
               if (res instanceof SvgView) entry.svg = res;
               else entry.image = res;
               if (!res) entry.failed = true;
-              this._layoutWidth = -1;
-              if (this.window && this.window._mapped) this.render();
+              this._invalidate();
             },
             () => {
               entry.failed = true;
-              this._layoutWidth = -1;
-              if (this.window && this.window._mapped) this.render();
+              this._invalidate();
             }
           );
         }
@@ -422,6 +427,13 @@ export default class HtmlView {
     for (const child of box.children) this._collectImages(child);
   }
 
+  /** async content arrived: drop the cached layout, repaint and/or notify */
+  _invalidate() {
+    this._layoutWidth = -1;
+    if (this.window && this.window._mapped) this.render();
+    if (this.onInvalidate) this.onInvalidate();
+  }
+
   // decoded bytes -> Image (PNG/JPEG) or SvgView (sniffed SVG markup)
   _decodeResource(buf) {
     const head = buf.subarray(0, 1024).toString('utf8');

package/lib/widgets/markdownview.js

@@ -51,7 +51,10 @@ const DEFAULT_THEME = {
  *   wnd.map();
  *
  * Standalone use (no window attach): `view.layout(width)` then
- * `view.draw(ctx, x, y)`; `view.contentHeight` after layout.
+ * `view.draw(ctx, x, y)`; `view.contentHeight` after layout. Content that
+ * arrives asynchronously (mermaid models) invalidates the layout — pass
+ * `onInvalidate` to re-layout/redraw when that happens (window mode
+ * repaints automatically).
  */
 export default class MarkdownView {
   constructor(window, opts = {}) {
@@ -70,6 +73,10 @@ export default class MarkdownView {
     /** called with (href, event) when a rendered link is clicked (window
      *  mode wires mousedown automatically; standalone callers use linkAt) */
     this.onLink = opts.onLink ?? null;
+    /** called when async content (a mermaid model) invalidates the layout;
+     *  standalone hosts re-layout/redraw here — window mode also repaints
+     *  on its own */
+    this.onInvalidate = opts.onInvalidate ?? null;
 
     if (this.window) {
       this._ctx = this.window.getContext('2d');
@@ -116,8 +123,7 @@ export default class MarkdownView {
       parseMermaid(text).then(
         (model) => {
           entry.model = model;
-          this._layoutWidth = -1;
-          if (this.window && this.window._mapped) this.render();
+          this._invalidate();
         },
         () => {
           entry.failed = true; // unsupported/invalid: stays a code block
@@ -127,6 +133,13 @@ export default class MarkdownView {
     return entry;
   }
 
+  /** async content arrived: drop the cached layout, repaint and/or notify */
+  _invalidate() {
+    this._layoutWidth = -1;
+    if (this.window && this.window._mapped) this.render();
+    if (this.onInvalidate) this.onInvalidate();
+  }
+
   /** lay content out for a container width; returns total content height */
   layout(width) {
     const fonts = this._fonts();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",