react-x11 2.31.0 → 2.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.31.0",
+  "version": "2.32.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

package/src/ntk.d.ts

@@ -91,6 +91,32 @@ export interface Surface {
   [Symbol.dispose](): void;
 }
 export const Surface: new (app: unknown, options: SurfaceOptions) => Surface;
+/** What `decodeImageBytes` answers: an ntk `Image` of straight RGBA. */
+export interface DecodedImage {
+  readonly width: number;
+  readonly height: number;
+  /** `width × height × 4` bytes, straight (not premultiplied) RGBA. */
+  readonly data: Uint8Array;
+}
+
+/**
+ * Encoded image bytes → an ntk `Image`, through the decoder `<image>` uses:
+ * the runtime's own where there is one (`Bun.Image`, off the JavaScript
+ * thread, every format it reads), and JavaScript elsewhere — PNG and JPEG
+ * synchronously, WebP through a decoder imported the first time a WebP
+ * arrives. The format comes from the bytes.
+ *
+ * An `Image`, or a promise of one wherever the decode is not synchronous;
+ * it throws, or rejects, on bytes this runtime cannot decode, saying what to
+ * convert them to. The bytes are read after it returns where the answer is
+ * a promise, so they must not change until it settles. See
+ * [elements.md](../docs/elements.md#formats-and-what-decodes-them) for which
+ * runtime decodes what.
+ */
+export function decodeImageBytes(
+  bytes: Uint8Array,
+): DecodedImage | Promise<DecodedImage>;
+
 /** `code` values on a failed GL setup — see `<glarea onError>`. */
 export const GLXError: {
   NO_EXTENSION: 'GLX_NO_EXTENSION';

package/src/ntk.js

@@ -28,6 +28,16 @@
 // without knowing which backend it was mounted on. This subpath is where a
 // drawing-adjacent name gets its backend-neutral answer; the X-only names
 // (`createClient`, `Pixmap`, `Picture`, `XEmbedSocket`) stay X-only.
+//
+// One name is not ntk's at all. `decodeImageBytes` (src/imagedecode.js) is
+// the decoder ladder behind `<image>`'s bytes and files — the runtime's own
+// decoder where there is one, WebP where ntk reads only PNG and JPEG — and
+// an element that draws images of its own (`<Html>`'s `<img>`, a CSS
+// background) decodes through it so that an image shows there exactly when
+// it would show in an `<image>`. It is a name of its own rather than ntk's
+// `decodeImage` answered differently, because that one is synchronous and a
+// caller may read the size off what it returns; this one answers a promise
+// wherever the decode is not.
 import * as ntk from 'ntk';
 
 import { adoptNtk } from './ntkroot.js';
@@ -35,6 +45,7 @@ import { adoptNtk } from './ntkroot.js';
 export * from 'ntk';
 export { default } from 'ntk';
 export { Surface } from './offscreen.js';
+export { decodeImageBytes } from './imagedecode.js';
 
 // what src/ntkroot.js would load, already loaded: handed over rather than
 // imported twice