ntk 8.0.0 → 8.1.1

package/lib/shadow.js

@@ -0,0 +1,199 @@
+// Drop shadows for the 2d context (issue #272): the blur, the surfaces it
+// runs on, and the cache that keeps a redrawn shadow from being rebuilt.
+//
+// The drawing itself lives in renderingcontext_2d.js — everything here is
+// the part with no X connection in it (the kernel maths) or the part every
+// shadowed operation shares (the coverage surfaces and their budget).
+//
+// ## How a shadow is drawn
+//
+// A shadow is the drawing's *coverage*, blurred, offset, and painted in one
+// colour. Coverage is what an `a8` Surface holds and what XRender composites
+// a solid through, so the whole thing is three server-side steps:
+//
+//   1. draw the shape into a padded a8 surface — white on transparent, so
+//      every pixel is its own alpha
+//   2. blur it: two convolution passes, horizontal then vertical
+//   3. composite the result as a mask, with `shadowColor` as the source
+//
+// The padding in (1) is not optional. A convolution samples outside the
+// picture, where RepeatNone reads transparent, so a shape drawn flush to the
+// surface edge ends in a straight line where the kernel ran out of pixels.
+// `reach` is how far coverage can spread, and every surface carries it on
+// all four sides.
+//
+// ## Why two passes
+//
+// A gaussian is separable, and that is the difference between a shadow you
+// can animate and one you cannot: a k-wide 2d kernel costs k² multiplies per
+// pixel where two 1d passes cost 2k. At `shadowBlur: 30` that is 8281 against
+// 182. RENDER has no separable-convolution filter, but it does not need one —
+// two `convolution` filters and two composites are the same thing, and the
+// second pass leaves a surface with the blur already in its pixels, so the
+// cached copy composites as a plain mask rather than re-running a kernel on
+// every frame.
+import { Surface } from './surface.js';
+
+/**
+ * Shadow policy — the cost ceilings, per app via `app.shadowPolicy`
+ * (partial objects are merged over the defaults). See docs/context-2d.md.
+ *
+ * - `cacheBytes` — LRU budget for retained shadow coverage per connection.
+ *   Keyed by (text, font, blur) for text; least-recently-drawn surfaces are
+ *   destroyed server-side once the total goes over.
+ * - `maxSigma` — the widest gaussian actually run. The kernel is 6σ+1 wide,
+ *   the request carries every tap, and the server multiplies each of them
+ *   per pixel per pass, so an unbounded `shadowBlur` is an unbounded
+ *   request and an unbounded stall. Past this the blur stops widening.
+ * - `maxPixels` — the largest coverage surface built for one shadow. Beyond
+ *   it the shadow is dropped rather than turning one drawing into a
+ *   multi-megabyte allocation; the drawing itself is unaffected.
+ */
+export const DEFAULT_SHADOW_POLICY = {
+  cacheBytes: 4 << 20,
+  maxSigma: 32,
+  maxPixels: 8 << 20
+};
+
+/** the policy for one app, merged over the defaults */
+export function shadowPolicyOf(app) {
+  return app?.shadowPolicy
+    ? { ...DEFAULT_SHADOW_POLICY, ...app.shadowPolicy }
+    : DEFAULT_SHADOW_POLICY;
+}
+
+/**
+ * The gaussian a `shadowBlur` asks for.
+ *
+ * `shadowBlur` is a **diameter**, not a radius: the canvas spec says a
+ * shadow is blurred by a gaussian whose standard deviation is half of it.
+ * Getting this wrong is invisible until someone compares against a browser,
+ * so it is one line with a test on it — `shadowBlur: 8` must be σ = 4 here
+ * exactly as it is in Chrome and Firefox.
+ *
+ * Clamped to the policy's `maxSigma`, which is the only place a shadow
+ * silently stops matching a browser; the cap is chosen so that no shadow a
+ * UI actually draws reaches it.
+ */
+export function shadowSigma(blur, policy = DEFAULT_SHADOW_POLICY) {
+  const sigma = blur / 2;
+  return sigma > policy.maxSigma ? policy.maxSigma : sigma;
+}
+
+/**
+ * How far the blur spreads coverage, in pixels — the kernel's half-width,
+ * and therefore the padding every coverage surface needs on each side.
+ *
+ * Truncating a gaussian at 3σ leaves 0.3% of its weight outside, which is
+ * below one step of the 8-bit coverage it is convolving.
+ */
+export function shadowReach(sigma) {
+  return sigma > 0 ? Math.ceil(sigma * 3) : 0;
+}
+
+/**
+ * A normalized 1d gaussian, `2 * reach + 1` taps wide.
+ *
+ * Normalizing the *truncated* kernel rather than the ideal one is what keeps
+ * a flat interior at full coverage: a shadow under an opaque box must stay
+ * opaque in the middle, and a kernel summing to 0.997 would leave it at 254.
+ */
+export function gaussianKernel1d(sigma, reach = shadowReach(sigma)) {
+  const values = new Array(reach * 2 + 1);
+  let sum = 0;
+  for (let i = -reach; i <= reach; i++) {
+    const v = Math.exp(-(i * i) / (2 * sigma * sigma));
+    values[i + reach] = v;
+    sum += v;
+  }
+  for (let i = 0; i < values.length; i++) values[i] /= sum;
+  return values;
+}
+
+/**
+ * Blur an a8 coverage surface, returning a new one holding the result.
+ *
+ * The input is destroyed: a caller has no use for the sharp copy afterwards,
+ * and leaving it alive would double what the cache is holding. The output
+ * carries no filter of its own, so compositing it is an ordinary masked
+ * composite no matter how wide the blur was.
+ */
+export function blurCoverage(shape, sigma) {
+  const app = shape.app;
+  const R = app.display.Render;
+  const { width, height } = shape;
+  const kernel = gaussianKernel1d(sigma);
+  const scratch = new Surface(app, { width, height, format: 'a8' });
+  const out = new Surface(app, { width, height, format: 'a8' });
+
+  const pass = (src, dst, params) => {
+    src.picture().setFilter('convolution', params);
+    // Src, not Over: each pass replaces the destination, which was cleared
+    // to transparent on creation. Over would accumulate the sharp copy's
+    // coverage under the blurred one and give the shadow a hard core.
+    R.Composite(R.PictOp.Src, src.picture().id, 0, dst.picture().id, 0, 0, 0, 0, 0, 0, width, height);
+  };
+  pass(shape, scratch, [kernel.length, 1, ...kernel]);
+  pass(scratch, out, [1, kernel.length, ...kernel]);
+
+  shape.destroy();
+  scratch.destroy();
+  return out;
+}
+
+/**
+ * A shadow's coverage, from the cache when it has been seen before.
+ *
+ * `build()` returns the finished (blurred) surface, or null when there is
+ * nothing to draw. A null `key` means "not cacheable" — the geometry has no
+ * short name, as a path's does not — and the caller owns the surface it gets
+ * back. With a key, the cache owns it and the caller must not destroy it.
+ *
+ * Cached on the app rather than the context because contexts are short-lived
+ * (`Surface.render` builds one per call) while a shadow is a property of the
+ * drawing, which outlives them — the same reason `solidPicture` and the
+ * glyph pages live there.
+ */
+export function cachedShadow(app, key, build) {
+  if (key === null) return build();
+  const cache = (app._shadowSurfaces ??= new Map());
+  const hit = cache.get(key);
+  if (hit) {
+    // Map iteration order is insertion order — re-insert to mark recent
+    cache.delete(key);
+    cache.set(key, hit);
+    return hit;
+  }
+  const surface = build();
+  if (!surface) return null;
+  cache.set(key, surface);
+  trimShadowSurfaces(app, shadowPolicyOf(app), surface);
+  return surface;
+}
+
+/**
+ * Evict least-recently-drawn shadow coverage until the cache fits its
+ * budget. `keep` is never evicted: it is the surface the caller is about to
+ * composite, and a budget smaller than one shadow must not free it mid-draw.
+ */
+export function trimShadowSurfaces(app, policy = shadowPolicyOf(app), keep = null) {
+  const cache = app._shadowSurfaces;
+  if (!cache) return;
+  let total = 0;
+  for (const surface of cache.values()) total += surface.bytes;
+  for (const [key, surface] of cache) {
+    if (total <= policy.cacheBytes) break;
+    if (surface === keep) continue;
+    cache.delete(key);
+    total -= surface.bytes;
+    surface.destroy();
+  }
+}
+
+/** free every cached shadow surface — connection teardown */
+export function dropShadowSurfaces(app) {
+  const cache = app._shadowSurfaces;
+  if (!cache) return;
+  for (const surface of cache.values()) surface.destroy();
+  cache.clear();
+}

package/lib/text/fontsource.js

@@ -9,11 +9,22 @@
 //     Full match list for a pattern, best first — the fallback chain.
 //     `family` may be a CSS-style comma-separated list. Must return at
 //     least one candidate or throw. A candidate is openable:
-//       { key?, path?, data?, font?, postscriptName? }
+//       { key?, path?, data?, font?, postscriptName?, family?, families? }
 //     - `font`: an already-open Font instance (preferred when available)
 //     - `data`: font file bytes (Uint8Array/Buffer) for fontkit
 //     - `path`: font file path (node only)
 //     - `key`: stable cache key (defaults to `${path}#${postscriptName}`)
+//     - `family`: the face's family name, for showing a match list without
+//       opening every file in it; `families` its aliases, first one first
+//       (both optional, but both sources here fill them in)
+//
+//   matchSortedAsync({ family, weight, style }) -> Promise<candidate[]>
+//     The same answer, awaited. Text layout is synchronous and always calls
+//     matchSorted; this is for an app asking a source directly — a font
+//     picker matching as the user types — where the fontconfig source's
+//     ~100ms spawn has no business blocking the event loop. A source with
+//     nothing to await implements it by resolving immediately, so a caller
+//     can be written once against either.
 //
 //   covers(candidate, codepoint) -> boolean   [optional]
 //     Cheap coverage pre-filter used during per-codepoint fallback, ideally
@@ -35,7 +46,14 @@
 // — its whole purpose is running the text stack without a filesystem. See
 // builtin.js for how the lazy lookup stays version-tolerant.
 import { builtin } from '../builtin.js';
-import { charsetHas, matchSortedSync, noFontsError, prewarm, supported } from '../fontconfig.js';
+import {
+  charsetHas,
+  matchSorted,
+  matchSortedSync,
+  noFontsError,
+  prewarm,
+  supported
+} from '../fontconfig.js';
 import Font from './font.js';
 
 const WEIGHTS = { normal: 400, bold: 700 };
@@ -111,6 +129,16 @@ export class FontconfigFontSource {
     return matchSortedSync(pattern);
   }
 
+  /**
+   * Non-blocking sibling: the fc-match spawn runs off the event loop and
+   * seeds the same cache, so a later synchronous layout for the pattern is
+   * a cache hit. Rejects with the same ERR_NTK_NO_FONTS the sync path
+   * throws — the failure case must not be the one that blocks.
+   */
+  matchSortedAsync(pattern) {
+    return matchSorted(pattern);
+  }
+
   covers(candidate, codepoint) {
     return charsetHas(candidate, codepoint);
   }
@@ -237,12 +265,28 @@ export class StaticFontSource {
     scored.sort((a, b) => a.score - b.score);
     return scored.map(({ face }) => {
       if (!face.candidate) {
-        face.candidate = { key: face.font.key, font: face.font };
+        // the font's own family name, not the (lowercased, possibly aliased)
+        // one it is matched by — this field is the one to show a reader
+        const name = face.font.familyName || '';
+        face.candidate = {
+          key: face.font.key,
+          font: face.font,
+          family: name,
+          families: name ? [name] : []
+        };
       }
       return face.candidate;
     });
   }
 
+  /**
+   * Nothing here is off-process, so matching is already instant — this
+   * exists so an app can await either source without asking which it has.
+   */
+  async matchSortedAsync(pattern = {}) {
+    return this.matchSorted(pattern);
+  }
+
   covers(candidate, codepoint) {
     return candidate.font.hasGlyph(codepoint);
   }

package/lib/text/layout.js

@@ -468,9 +468,21 @@ export class TextLayout {
   }
 
   /**
-   * Draw onto a 2d context at (x, y) = top-left of the layout box.
+   * Draw onto a 2d context at (x, y) = top-left of the layout box, in the
+   * context's **user space**: the current transform applies to the origin,
+   * the same way it applies to `fillText`, `fillRect` and `drawImage`, so a
+   * paragraph drawn into a translated context lands where the rest of the
+   * drawing does (issue #280). The glyphs themselves are not rotated or
+   * scaled by it — set the span size instead.
+   *
    * Span `color`s override the context fillStyle; consecutive same-color
    * runs are batched into single CompositeGlyphs requests.
+   *
+   * `caretPosition`/`indexAt` and the line/run geometry speak the same
+   * layout-relative coordinates as the (x, y) here, so hit testing stays
+   * `layout.indexAt(px - x, py - y)` — with (px, py) in user space too,
+   * which for a pointer event under a transformed context means undoing
+   * `ctx.getTransform()` first.
    */
   draw(ctx, x = 0, y = 0) {
     const app = ctx.window.app;
@@ -484,8 +496,9 @@ export class TextLayout {
     const flush = () => {
       if (batch.length === 0) return;
       const src = batchColor ? ctx._stylePicture(batchColor) : ctx._backgroundPicture;
-      // via the context so the clip is applied (drawGlyphRuns composites
-      // straight onto the picture and cannot see it)
+      // via the context so the clip and the transform are applied
+      // (drawGlyphRuns composites straight onto the picture and can see
+      // neither)
       if (typeof ctx.drawGlyphs === 'function') {
         ctx.drawGlyphs(Render.PictOp.Over, src, batch);
       } else {

package/lib/widgets/svgview.js

@@ -22,7 +22,7 @@
 import { textContent } from 'domutils';
 import { parseDocument } from 'htmlparser2';
 
-import { Path2D, flattenPath, matApply } from '../path.js';
+import { Path2D, flattenPath } from '../path.js';
 
 const INHERITED = {
   fill: '#000',
@@ -486,16 +486,15 @@ export default class SvgView {
       if (!bbox) return v;
       return axis === 'x' ? bbox.x + v * bbox.w : bbox.y + v * bbox.h;
     };
-    // ntk gradients live in device space: map user-space endpoints through
-    // the current transform
-    const m = ctx.getTransform();
-    const mat = [m.a, m.b, m.c, m.d, m.e, m.f];
-    const dev = (px, py) => matApply(mat, px, py);
-
+    // gradient coordinates are user space, like the path's own — the
+    // context resolves them against the transform in force when it paints,
+    // which is this one (issue #271)
     let gradient;
     if (tag(node) === 'lineargradient') {
-      const [x1, y1] = dev(coord(a.x1, 0, 'x'), coord(a.y1, 0, 'y'));
-      const [x2, y2] = dev(coord(a.x2, 1, 'x'), coord(a.y2, 0, 'y'));
+      const x1 = coord(a.x1, 0, 'x');
+      const y1 = coord(a.y1, 0, 'y');
+      const x2 = coord(a.x2, 1, 'x');
+      const y2 = coord(a.y2, 0, 'y');
       gradient = ctx.createLinearGradient(x1, y1, x2, y2);
     } else {
       const cx = coord(a.cx, 0.5, 'x');
@@ -503,9 +502,7 @@ export default class SvgView {
       let r = a.r === undefined ? 0.5 : parseFloat(a.r);
       if (String(a.r ?? '').endsWith('%')) r /= 100;
       if (bbox) r *= (bbox.w + bbox.h) / 2;
-      const [dcx, dcy] = dev(cx, cy);
-      const scale = Math.sqrt(Math.abs(mat[0] * mat[3] - mat[1] * mat[2])) || 1;
-      gradient = ctx.createRadialGradient(dcx, dcy, 0, dcx, dcy, r * scale);
+      gradient = ctx.createRadialGradient(cx, cy, 0, cx, cy, r);
     }
 
     for (const stop of node.children || []) {

package/package.json

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