@react-x11/components 0.8.0 → 0.10.0

package/src/html/resources.ts

@@ -13,35 +13,62 @@
 // these requests", which an application cannot audit and a user did not ask
 // for. The host already knows its proxy, its cache, its offline policy and
 // whether this document is trusted; this does not.
-import ntk, { Image } from 'react-x11/ntk';
+import * as ntk from 'react-x11/ntk';
+import { decodeStylesheet } from './css/decode.js';
+import type { DecodedStylesheet } from './css/decode.js';
+import { svgFromBytes } from './svg.js';
+import type { IntrinsicSize } from './svg.js';
+import { decodeGif } from './gif.js';
+import type { UrlResolver } from './url.js';
 import type { Element } from 'domhandler';
 
 /** What the host is asked for. */
 export interface ResourceRequest {
-  /** The URL exactly as the document wrote it — not resolved against a base,
-   *  because this has no base and the host does. */
+  /**
+   * The URL. As the document wrote it, where the document has no base — no
+   * `baseUrl` prop and no `<base href>` — because then this has none and
+   * the host does. Absolute where it has one: resolved against the
+   * document's base, or, for a `url()` in a stylesheet that came from
+   * somewhere, against the stylesheet's own URL, as CSS resolves it.
+   */
   url: string;
-  kind: 'image' | 'stylesheet';
-  /** The element that referred to it, for a host that wants the context. */
+  /** An `<img>`, an `<object>`, a background or a list marker; a
+   *  `<link rel=stylesheet>` or an `@import`; an `@font-face` source. */
+  kind: 'image' | 'stylesheet' | 'font';
+  /** The element that referred to it, for a host that wants the context:
+   *  for a font, the `<style>` or `<link>` whose sheet declared it. */
   element: Element;
 }
 
 /**
- * What the host hands back. A stylesheet is text; an image is bytes, which
- * this decodes, or an already-decoded ntk `Image` for a host with its own
- * cache.
+ * What the host hands back. A stylesheet is text, or bytes this decodes as
+ * CSS says to — with `charset`, the encoding the protocol named, if it named
+ * one (`css/decode.ts`) — and may say the URL it finally came from, after
+ * redirects, which is what the relative URLs in it resolve against. An image
+ * is bytes, which this decodes — PNG, JPEG, GIF or SVG — or an
+ * already-decoded ntk `Image` for a host with its own cache. A font is the
+ * file's bytes: TrueType, OpenType, WOFF or WOFF2 (see `fonts.ts`).
  */
 export type ResourceResult =
-  | { kind: 'stylesheet'; text: string }
+  | { kind: 'stylesheet'; text: string; url?: string }
+  | { kind: 'stylesheet'; bytes: Uint8Array; charset?: string; url?: string }
   | { kind: 'image'; bytes: Uint8Array }
-  | { kind: 'image'; image: unknown; width: number; height: number };
+  | { kind: 'image'; image: unknown; width: number; height: number }
+  | { kind: 'font'; bytes: Uint8Array };
 
 interface Entry {
   state: 'pending' | 'ready' | 'failed';
+  /** A stylesheet's own URL, after redirects, as the host said it. */
+  url?: string;
   text?: string;
+  /** A stylesheet handed over as bytes, decoded when it is first read: what
+   *  it falls back to is the referrer's, known only then. */
+  bytes?: Uint8Array;
+  charset?: string;
+  decoded?: { fallbacks: string; sheet: DecodedStylesheet };
+  /** An ntk `Image`, or an `SvgDrawing`. */
   image?: unknown;
-  width?: number;
-  height?: number;
+  size?: IntrinsicSize;
 }
 
 /** The ntk `Image` slice this uses. Structural, as everywhere else here. */
@@ -56,32 +83,54 @@ interface ImageConstructor {
   new (...args: unknown[]): ImageLike;
 }
 
+/**
+ * The resources a document asked for, by URL — resolved against the
+ * document's base (`url.ts`) on the way in and on every lookup, so a caller
+ * names a resource by what the document wrote and the host is asked for,
+ * and caches by, what it resolves to.
+ */
 export class ResourceStore {
   private _entries = new Map<string, Entry>();
   private _ask: (
     request: ResourceRequest,
   ) => Promise<ResourceResult | null> | ResourceResult | null;
-  private _changed: () => void;
+  private _changed: (what: 'stylesheet' | 'image') => void;
+  private _urls: UrlResolver | null;
   private _destroyed = false;
 
+  /**
+   * `changed` is told when a resource arrives after the request that asked
+   * for it returned, and which kind: a stylesheet changes the cascade and an
+   * image the boxes, and a host answering over a network answers every one
+   * of them later.
+   */
   constructor(
     ask: (
       request: ResourceRequest,
     ) => Promise<ResourceResult | null> | ResourceResult | null,
-    changed: () => void,
+    changed: (what: 'stylesheet' | 'image') => void,
+    urls: UrlResolver | null = null,
   ) {
     this._ask = ask;
     this._changed = changed;
+    this._urls = urls;
+  }
+
+  /** A URL as the document wrote it, as the store keys it. */
+  private _key(url: string): string {
+    return this._urls ? this._urls.resolve(url) : url;
   }
 
   /** Ask for a resource, once per URL. */
   request(request: ResourceRequest): void {
-    if (this._destroyed || this._entries.has(request.url)) return;
+    if (this._destroyed || !request.url) return;
+    const url = this._key(request.url);
+    if (this._entries.has(url)) return;
     const entry: Entry = { state: 'pending' };
-    this._entries.set(request.url, entry);
+    this._entries.set(url, entry);
     let answer: Promise<ResourceResult | null> | ResourceResult | null;
     try {
-      answer = this._ask(request);
+      answer = this._ask(url === request.url ? request : { ...request, url });
     } catch {
       entry.state = 'failed';
       return;
@@ -92,14 +141,14 @@ export class ResourceStore {
     }
     if (isPromise(answer)) {
       answer.then(
-        (result) => this._settle(request.url, entry, result),
+        (result) => this._settle(url, entry, result),
         () => {
           entry.state = 'failed';
         },
       );
       return;
     }
-    this._settle(request.url, entry, answer, true);
+    this._settle(url, entry, answer, true);
   }
 
   private _settle(
@@ -109,23 +158,36 @@ export class ResourceStore {
     synchronous = false,
   ): void {
     if (this._destroyed) return;
-    void url;
-    if (!result) {
+    // a font is `fonts.ts`'s to ask for, and never comes through here
+    if (!result || result.kind === 'font') {
       entry.state = 'failed';
       return;
     }
     if (result.kind === 'stylesheet') {
-      entry.text = result.text;
+      entry.url = result.url || url;
+      if ('bytes' in result) {
+        entry.bytes = result.bytes;
+        entry.charset = result.charset;
+      } else {
+        entry.text = result.text;
+      }
       entry.state = 'ready';
-      if (!synchronous) this._changed();
+      if (!synchronous) this._changed('stylesheet');
       return;
     }
     if ('image' in result) {
       entry.image = result.image;
-      entry.width = result.width;
-      entry.height = result.height;
+      entry.size = rasterSize(result.width, result.height);
       entry.state = 'ready';
-      if (!synchronous) this._changed();
+      if (!synchronous) this._changed('image');
+      return;
+    }
+    const svg = svgFromBytes(result.bytes);
+    if (svg) {
+      entry.image = svg;
+      entry.size = svg.intrinsics;
+      entry.state = 'ready';
+      if (!synchronous) this._changed('image');
       return;
     }
     const decoded = decodeImage(result.bytes);
@@ -134,10 +196,9 @@ export class ResourceStore {
         (image) => {
           if (this._destroyed) return;
           entry.image = image;
-          entry.width = image.width;
-          entry.height = image.height;
+          entry.size = rasterSize(image.width, image.height);
           entry.state = 'ready';
-          this._changed();
+          this._changed('image');
         },
         () => {
           entry.state = 'failed';
@@ -150,29 +211,61 @@ export class ResourceStore {
       return;
     }
     entry.image = decoded;
-    entry.width = decoded.width;
-    entry.height = decoded.height;
+    entry.size = rasterSize(decoded.width, decoded.height);
     entry.state = 'ready';
-    if (!synchronous) this._changed();
+    if (!synchronous) this._changed('image');
   }
 
-  /** A loaded stylesheet's text, or null while it has not arrived. */
-  stylesheetText(url: string): string | null {
-    const entry = this._entries.get(url);
-    return entry?.state === 'ready' ? (entry.text ?? null) : null;
+  /** A loaded stylesheet, as text, or null while it has not arrived.
+   *  `fallbacks` are the encodings the referrer says, most specific first,
+   *  for bytes that name none of their own. */
+  stylesheet(
+    url: string,
+    fallbacks: readonly (string | undefined)[] = [],
+  ): DecodedStylesheet | null {
+    const entry = this._entries.get(this._key(url));
+    if (entry?.state !== 'ready') return null;
+    if (!entry.bytes) {
+      if (entry.text === undefined) return null;
+      // decoded by the host, from an encoding it did not say: what it
+      // imports falls back to the referrer's
+      return { text: entry.text, encoding: fallbacks.find(Boolean) ?? 'utf-8' };
+    }
+    const key = fallbacks.join('\u0001');
+    if (entry.decoded?.fallbacks !== key) {
+      entry.decoded = {
+        fallbacks: key,
+        sheet: decodeStylesheet(entry.bytes, entry.charset, fallbacks),
+      };
+    }
+    return entry.decoded.sheet;
+  }
+
+  /**
+   * The URL a loaded stylesheet's own relative URLs resolve against: where
+   * the host said it came from, or where it was asked for. Null while it
+   * has not arrived, or where that is not an absolute URL — a sheet asked
+   * for by a relative one, from a document with no base, whose URLs are
+   * left as they are written.
+   */
+  sheetBase(url: string): string | null {
+    const entry = this._entries.get(this._key(url));
+    const base = entry?.state === 'ready' ? entry.url : undefined;
+    return base && /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(base) ? base : null;
   }
 
   /** A loaded image, for the paint pass. */
   image(url: string): unknown | null {
-    const entry = this._entries.get(url);
+    if (!url) return null;
+    const entry = this._entries.get(this._key(url));
     return entry?.state === 'ready' ? (entry.image ?? null) : null;
   }
 
   /** A loaded image's intrinsic size, for the box builder. */
-  imageSize(url: string): { width: number; height: number } | null {
-    const entry = this._entries.get(url);
-    if (entry?.state !== 'ready' || entry.width === undefined) return null;
-    return { width: entry.width, height: entry.height ?? 0 };
+  imageSize(url: string): IntrinsicSize | null {
+    if (!url) return null;
+    const entry = this._entries.get(this._key(url));
+    return entry?.state === 'ready' ? (entry.size ?? null) : null;
   }
 
   destroy(): void {
@@ -181,29 +274,47 @@ export class ResourceStore {
   }
 }
 
+/** A raster image's size: both dimensions, and their ratio. */
+function rasterSize(width: number, height: number): IntrinsicSize {
+  return {
+    width,
+    height,
+    ratio: width > 0 && height > 0 ? width / height : 0,
+  };
+}
+
 function isPromise<T>(value: unknown): value is Promise<T> {
   return typeof (value as Promise<T> | null)?.then === 'function';
 }
 
 /**
- * Decode image bytes through ntk.
+ * Decode image bytes through ntk — PNG and JPEG — or, for a GIF, here: its
+ * first frame (`gif.ts`), handed to ntk's `Image` as the RGBA it takes.
  *
- * `decodeImage` is ntk's own front door — the one its `HtmlView` used — but
- * it is not on `react-x11/ntk`'s *typed* list, so it is reached through the
- * default export and probed at run time; a version that dropped it falls
- * back to the `Image` constructor shapes. A host that would rather decode
- * images itself hands back `{ image, width, height }` and never reaches
- * this.
+ * `decodeImage` is ntk's own front door — the one its `HtmlView` used. It is
+ * a **named** export of `react-x11/ntk`, which re-exports ntk with
+ * `export *`, and it is not in that subpath's declarations, so it is read off
+ * the module namespace and probed at run time; a version that dropped it
+ * falls back to the `Image` constructor shapes. It is not a property of the
+ * default export: this read it there, found nothing, and every image a host
+ * handed over as bytes drew as an empty frame. A host that would rather
+ * decode images itself hands back `{ image, width, height }` and never
+ * reaches this.
  */
 function decodeImage(bytes: Uint8Array): ImageLike | Promise<ImageLike> | null {
   try {
-    const decode = (ntk as Record<string, unknown>).decodeImage;
+    const gif = decodeGif(bytes);
+    if (gif) {
+      const ctor = ntk.Image as unknown as ImageConstructor | undefined;
+      return ctor ? new ctor(gif) : null;
+    }
+    const decode = (ntk as unknown as Record<string, unknown>).decodeImage;
     if (typeof decode === 'function') {
       return (decode as (b: Uint8Array) => ImageLike | Promise<ImageLike>)(
         bytes,
       );
     }
-    const ctor = Image as unknown as ImageConstructor | undefined;
+    const ctor = ntk.Image as unknown as ImageConstructor | undefined;
     if (!ctor) return null;
     if (typeof ctor.fromBuffer === 'function') return ctor.fromBuffer(bytes);
     if (typeof ctor.decode === 'function') return ctor.decode(bytes);

package/src/html/surfaces.ts

@@ -0,0 +1,81 @@
+// Drawings kept on offscreen surfaces of their own, made once for a key and
+// composited after: how a blurred shadow is drawn a second time without its
+// blur. ntk bakes a shadow's blur on every fill of a path — a path has no
+// short name to cache it by — which put 500ms on each repaint of a grid of
+// thirty cards; the name is the shadow's geometry and colour, which only
+// the painter knows, so the cache is here.
+
+import { Surface } from 'react-x11/ntk';
+
+/** ntk's `Surface`, as this uses it. */
+interface SurfaceLike {
+  getContext(kind: '2d'): unknown;
+  destroy?(): void;
+}
+
+interface Kept {
+  surface: SurfaceLike;
+  pixels: number;
+}
+
+/**
+ * Surfaces by key, the least recently drawn given up first once they hold
+ * more than `budget` pixels. One too large for a quarter of the budget is
+ * not made, and the caller draws the thing itself; so does one on a backend
+ * with no offscreen surface — the headless mock — after the first attempt.
+ */
+export class SurfaceCache {
+  private readonly kept = new Map<string, Kept>();
+  private pixels = 0;
+  private unavailable = false;
+
+  constructor(
+    private readonly app: unknown,
+    private readonly budget = 8 * 1024 * 1024,
+  ) {}
+
+  get(
+    key: string,
+    width: number,
+    height: number,
+    draw: (ctx: unknown) => void,
+  ): SurfaceLike | null {
+    const hit = this.kept.get(key);
+    if (hit) {
+      // re-inserted: a Map iterates in insertion order, oldest first
+      this.kept.delete(key);
+      this.kept.set(key, hit);
+      return hit.surface;
+    }
+    const pixels = width * height;
+    if (this.unavailable || !(width > 0 && height > 0)) return null;
+    if (pixels > this.budget / 4) return null;
+    let surface: SurfaceLike;
+    try {
+      surface = new Surface(this.app as never, {
+        width,
+        height,
+      }) as unknown as SurfaceLike;
+    } catch {
+      this.unavailable = true;
+      return null;
+    }
+    // a new surface is transparent: ntk clears its pixmap as it makes it
+    draw(surface.getContext('2d'));
+    this.kept.set(key, { surface, pixels });
+    this.pixels += pixels;
+    for (const [oldest, entry] of this.kept) {
+      if (this.pixels <= this.budget || entry.surface === surface) break;
+      this.kept.delete(oldest);
+      this.pixels -= entry.pixels;
+      entry.surface.destroy?.();
+    }
+    return surface;
+  }
+
+  destroy(): void {
+    for (const entry of this.kept.values()) entry.surface.destroy?.();
+    this.kept.clear();
+    this.pixels = 0;
+  }
+}