@solidrt/flux-types 0.0.64 → 0.0.65

package/gui/gpu.d.ts

@@ -228,10 +228,41 @@ declare module "flux:gpu" {
    * (integer textures never filter), and a float sampler over it (or a
    * `usampler2D` over any other format) throws at bind.
    *
-   * Reserved future value of this same vocabulary: "etc2-rgba8" (compressed
-   * uploads).
+   * "etc2-rgba8", "etc2-rgba8-srgb", "bc7-rgba8" and "bc7-rgba8-srgb" are
+   * the block-compressed formats: 4x4 texel blocks of 16 bytes (1 byte per
+   * texel, a quarter of rgba8) that the sampler decodes for free, so a
+   * texture-heavy scene holds a quarter of the GPU memory. The payload is
+   * the raw blocks as a Uint8Array: ceil(width/4) * ceil(height/4) * 16
+   * bytes per level, and with `mipmap: true` the FULL chain concatenated
+   * level-major down to 1x1 (a compressed chain is uploaded, never
+   * generated - the runtime cannot build mips on compressed storage). The
+   * "-srgb" twins decode to linear light on sample exactly like
+   * "rgba8-srgb". Filterable like the byte formats (linear, mipmap,
+   * anisotropy all apply), and create-once and sample-only: createMutableTexture,
+   * uploadTexture, resizeTexture, readTexture, copyTexture and cube maps
+   * throw for them, and `<texture src>` display is out of contract.
+   * Availability differs by device, which is the point of the two codecs:
+   * the "etc2-*" formats are GLES 3.0 core and every device takes them
+   * (a desktop driver without the hardware format expands them to RGBA8,
+   * losing the memory cut but not correctness), so ETC2 is the only
+   * compressed format that is portable to SHIP raw; the "bc7-*" formats
+   * exist where `limits.bc7Textures` is true (every desktop: ANGLE over
+   * D3D11 and Metal, Mesa) and throw elsewhere, so BC7 is a load-time
+   * target - what `transcodeTexture` in flux:image picks on a desktop from
+   * one shipped KTX2 payload - not a format an app ships raw.
    */
-  export type TextureFormat = "rgba8" | "rgba8-srgb" | "r8" | "r32f" | "rgba32f" | "rgba16f" | "rgba32ui"
+  export type TextureFormat =
+    | "rgba8"
+    | "rgba8-srgb"
+    | "r8"
+    | "r32f"
+    | "rgba32f"
+    | "rgba16f"
+    | "rgba32ui"
+    | "etc2-rgba8"
+    | "etc2-rgba8-srgb"
+    | "bc7-rgba8"
+    | "bc7-rgba8-srgb"
   export type TextureFormatOption = { format?: TextureFormat }
   /**
    * This device's hard ceilings, queried once at startup: process constants.
@@ -277,13 +308,25 @@ declare module "flux:gpu" {
      * "rgba16f" texture throws where this is false.
      */
     halfFloatRenderable: boolean
+    /**
+     * Whether the "bc7-rgba8" and "bc7-rgba8-srgb" formats upload on this
+     * device (the EXT_texture_compression_bptc extension: every desktop,
+     * no mobile GPU). The "etc2-*" formats are GLES 3.0 core and need no
+     * flag. A loader with one shipped payload picks BC7 where this is
+     * true and ETC2 otherwise; `transcodeTexture` in flux:image applies
+     * that rule when given no target.
+     */
+    bc7Textures: boolean
   }
   /**
    * Create an immutable texture from a pixel buffer holding exactly one
    * frame at the declared format's size. The view type must match the
    * format: byte formats ("rgba8", "rgba8-srgb", "r8") take a Uint8Array,
-   * float formats ("r32f", "rgba32f", "rgba16f") a Float32Array. Returns
-   * the texture id.
+   * float formats ("r32f", "rgba32f", "rgba16f") a Float32Array. A
+   * compressed format ("etc2-*", "bc7-*") takes its raw blocks as a
+   * Uint8Array, the full mip chain when `mipmap: true` (see
+   * {@link TextureFormat}); the byte count in the error names what is
+   * expected. Returns the texture id.
    */
   export function createTexture(data: Uint8Array | Float32Array | Uint32Array, width: number, height: number, opts?: SamplerOptions & TextureFormatOption & LabelOption): TextureId
   /**

package/gui/test.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The node verbs of a gui test: finding and reading the nodes of the render
+ * tree. A GUI build of Flux with the test module has them, which is the
+ * SolidRT dev client; an app test reaches them through
+ * `@solidrt/test`, whose locators are built on this module.
+ *
+ * A node reads as the control API's `/tree` reports it: records cross as
+ * JSON text, shaped in one place for both readers.
+ */
+declare module "flux:test/gui" {
+  /**
+   * One field of a query: a string matches exactly (case-sensitive), `true`
+   * matches every node that has the field (for a pattern the caller checks
+   * itself), absent is no constraint.
+   */
+  export type FieldQuery = string | true
+
+  export interface NodeQuery {
+    /** The element kind's name: "view", "text", ... */
+    kind?: string
+    /** The text a text or span node shows. */
+    text?: FieldQuery
+    /** The node's `label` prop. */
+    label?: FieldQuery
+  }
+
+  /**
+   * The nodes under `root` (the tree root when null, `root` included) that
+   * the query matches, depth first, at most `limit`: a JSON array of node
+   * records without children, each with `path`, the ids from the search
+   * root down to it. A node whose text matches under an ancestor showing
+   * the very same text is left out. Null when `root` is no current node.
+   */
+  export function find(root: number | null, query: NodeQuery, limit: number): string | null
+
+  /**
+   * The record of node `id` with `depth` levels of children (0: the node
+   * alone), as JSON; null when `id` is no current node.
+   */
+  export function node(id: number, depth: number): string | null
+
+  /**
+   * The subtree of node `id` as an outline: one node per line indented by
+   * depth, with its kind, label, text and painted box (`view [save] 20,50
+   * 120x40`), and with `props` the off-default props as JSON after it. No
+   * ids, so two runs print the same text. A span that is all of its
+   * parent's text is folded into the parent's line, as `find` sees it.
+   * Null when `id` is no current node.
+   */
+  export function outline(id: number, props: boolean): string | null
+
+  /**
+   * Whether the node is painted where a user could see it: mounted and not
+   * exiting, its painted box still has area once every clipping ancestor
+   * and the window have cut it, and the opacity multiplied up its ancestor
+   * chain is above 0. It says nothing of what is painted over it; `hit`
+   * answers that.
+   */
+  export function visible(id: number): boolean
+
+  /** The ids from the tree root down to `id`; null when `id` is no current node. */
+  export function path(id: number): number[] | null
+
+  /**
+   * The ids of the nodes a pointer at the window point reaches, root first,
+   * the node it lands on last; empty when nothing is hit.
+   */
+  export function hit(x: number, y: number): number[]
+
+  /**
+   * The GPU resource inventory as JSON, the record the control API's `/gpu`
+   * answers with: textures, buffers, pipelines, programs and each draw
+   * target's entries. `label` keeps the resources created with exactly
+   * that label; `draw` is the draw entry id whose params are reported in
+   * full (matrix-valued ones are elided elsewhere).
+   */
+  export function gpu(label: string | null, draw: number | null): string
+}

package/index.d.ts

@@ -13,6 +13,7 @@
 /// <reference path="./modules/wasm.d.ts" />
 /// <reference path="./modules/ffi.d.ts" />
 /// <reference path="./modules/isolate.d.ts" />
+/// <reference path="./modules/test.d.ts" />
 
 // Web-standard globals. The runtime is QuickJS, not a browser or Node, so it
 // ships no lib.dom / @types/bun: these declarations are the sole source for
@@ -40,6 +41,7 @@
 /// <reference path="./gui/spatial.d.ts" />
 /// <reference path="./gui/video.d.ts" />
 /// <reference path="./gui/raf.d.ts" />
+/// <reference path="./gui/test.d.ts" />
 
 declare let Flux: {
   /** The flux runtime version. */

package/modules/fs.d.ts

@@ -120,4 +120,26 @@ declare module "flux:fs" {
    * @param to    Path it should have afterwards.
    */
   export function rename(from: string, to: string): Promise<void>
+  /**
+   * The files whose path matches the glob `pattern`, sorted: Node's
+   * `fs.glob`, as a promise of the whole list. The pattern language is
+   * `matchesGlob`'s (flux:path), and the two agree: a file is listed
+   * exactly when its path matches. Files only; a directory is walked and
+   * never listed, so an empty list means no file matches.
+   *
+   * Each path is given as seen from `cwd`. Without `cwd` the pattern stands
+   * against the process cwd like any relative path, and in a SolidRT app
+   * running an installed version a pattern that starts in `assets/` lists
+   * that version's assets. With `cwd` it is that directory as the OS has
+   * it.
+   *
+   * Throws on a malformed pattern. Rejects when a directory on the way
+   * cannot be read.
+   *
+   * @param pattern  The glob pattern, written with "/".
+   *
+   * @example
+   * let textures = await glob("assets/textures/*.png")
+   */
+  export function glob(pattern: string, options?: { cwd?: string }): Promise<string[]>
 }

package/modules/image.d.ts

@@ -44,4 +44,100 @@ declare module "flux:image" {
     img: DecodedImage,
     options?: { format?: "png" | "jpeg"; quality?: number; alpha?: AlphaMode },
   ): Uint8Array
+
+  /**
+   * A transcoded compressed texture, shaped as the arguments of
+   * `createTexture` in flux:gpu: `createTexture(t.data, t.width, t.height,
+   * { format: t.format, mipmap: t.mipmap })`. `data` holds every level of
+   * the file, level 0 first; `mipmap` says it is the full chain down to
+   * 1x1 rather than the base level alone. `format` is the target with the
+   * "-srgb" qualifier when the file's texels are sRGB-encoded (the file
+   * says, not the caller).
+   */
+  export type TranscodedTexture = {
+    data: Uint8Array
+    width: number
+    height: number
+    format: "etc2-rgba8" | "etc2-rgba8-srgb" | "bc7-rgba8" | "bc7-rgba8-srgb" | "rgba8" | "rgba8-srgb"
+    mipmap: boolean
+  }
+
+  /**
+   * The Basis Universal codec inside a KTX2 file. "etc1s" is the small one:
+   * lossy at JPEG-class quality, around 1 bit per texel, for color maps
+   * (base color, emissive). "uastc" is the high quality one, for normal
+   * maps and data maps, where ETC1S artifacts show: 8 bits per texel
+   * before the file's zstd compression, which takes it to 2 to 6 on a
+   * real map at the default quality.
+   */
+  export type TextureCodec = "etc1s" | "uastc"
+
+  /**
+   * Transcodes a KTX2 file of Basis Universal texel data (ETC1S or UASTC, a
+   * 2D texture with one level or its full mip chain - what `encodeTexture`
+   * writes and what glTF's KHR_texture_basisu carries) into the block
+   * format a GPU samples. This is the load-time half of compressed
+   * textures: an app ships ONE file for every platform and each device
+   * turns it into its own native format, a quarter of the GPU memory of
+   * the same image as "rgba8".
+   *
+   * Without `target` the runtime picks this device's format: "bc7-rgba8"
+   * where the GPU reports it (`limits.bc7Textures` in flux:gpu, every
+   * desktop), "etc2-rgba8" everywhere else (GLES 3.0 core, every mobile
+   * GPU). A runtime with no GPU cannot pick and throws; name the target
+   * there. "rgba8" is the uncompressed form, for inspection and comparison;
+   * no device needs it as a fallback.
+   *
+   * The texels come through as the file holds them: a file baked here is
+   * premultiplied like every texture, a file from elsewhere (glTF stores
+   * straight alpha) samples as straight alpha.
+   *
+   * Asynchronous: the work runs off the JS thread, and a scene's worth of
+   * textures is seconds of it on a slow device. Start as many as there are
+   * textures: the runtime transcodes four at a time and queues the rest, so
+   * a `Promise.all` over a scene neither floods the device's cores nor
+   * multiplies the memory in flight. Rejects when the bytes are
+   * not such a file (another codec, a cube map, an array, a partial mip
+   * chain). Throws on a runtime built without compressed textures
+   * (`Flux.capabilities` lacks "ktx2").
+   */
+  export function transcodeTexture(
+    ktx2: Uint8Array,
+    options?: { target?: "etc2-rgba8" | "bc7-rgba8" | "rgba8" },
+  ): Promise<TranscodedTexture>
+
+  /**
+   * Encodes RGBA8 pixels into a KTX2 file of Basis Universal texel data,
+   * the bake-time half of compressed textures. The file is device
+   * independent - the same bytes whatever machine encodes it and whatever
+   * device loads it - and `transcodeTexture` turns it into each device's
+   * format at load.
+   *
+   * `img` holds the pixels as the GPU will sample them, which means
+   * premultiplied: pass a `decodeImage` result as it is (blocks cannot be
+   * premultiplied after the fact, and mips only filter correctly on
+   * premultiplied color). `codec` is required. `srgb` (default false) says
+   * the pixels are sRGB-encoded color: set it for base color and emissive
+   * maps, never for normal or data maps; it flags the file, makes the
+   * error metric perceptual and filters the mips in linear light. `mipmap`
+   * (default false) generates and stores the full mip chain, filtered
+   * across the edges as `wrap` says ("clamp" default, or "repeat" for a
+   * texture sampled tiled). `quality` is 0..1 (default 0.5), higher is
+   * larger and closer to the source. For "uastc", 1 is the encoder's best
+   * blocks and anything below it trades block error for a file that
+   * compresses better.
+   *
+   * Asynchronous and slow by design (seconds for a large image):
+   * bake-time work, never something to do at load. The runtime encodes
+   * four at a time and queues the rest, so starting many neither floods
+   * the machine's cores nor multiplies the encoder's memory; the pixels of
+   * an encode that waits are held meanwhile, so with many images decode
+   * and start a few at a time. Rejects when `data.length` does not match
+   * `width * height * 4`. Throws on a runtime built without compressed
+   * textures.
+   */
+  export function encodeTexture(
+    img: DecodedImage,
+    options: { codec: TextureCodec; srgb?: boolean; mipmap?: boolean; wrap?: "clamp" | "repeat"; quality?: number },
+  ): Promise<Uint8Array>
 }

package/modules/path.d.ts

@@ -23,4 +23,65 @@ declare module "flux:path" {
    * guarantee; use `resolveWithin` when a segment is untrusted.
    */
   export function join(...segments: string[]): string
-}
+
+  /**
+   * The last component of `path`, trailing separators ignored: Node's
+   * `path.basename`. Lexical. `basename("/a/model.gltf")` is "model.gltf",
+   * `basename("/a/b/")` is "b".
+   *
+   * @param ext  A suffix to cut off the result, as in
+   *             `basename("/a/model.gltf", ".gltf")`, which is "model". A
+   *             name that is nothing but the suffix keeps it.
+   */
+  export function basename(path: string, ext?: string): string
+
+  /**
+   * `path` without its last component: Node's `path.dirname`. Lexical.
+   * `dirname("/a/b.txt")` is "/a", and a bare name's is ".".
+   */
+  export function dirname(path: string): string
+
+  /**
+   * The extension of `path`'s last component, from its last dot on, or ""
+   * when it has none: Node's `path.extname`. `extname("a.tar.gz")` is ".gz";
+   * a leading dot names a hidden file, so `extname(".bashrc")` is "".
+   */
+  export function extname(path: string): string
+
+  /**
+   * The path that leads from `from` to `to`: Node's `path.relative`.
+   * Lexical. Each side stands against the process cwd when it is relative,
+   * so `relative(".", path)` is `path` as seen from the cwd.
+   * `relative("/a/b", "/a/c/d.txt")` is "../c/d.txt", and a place to itself
+   * is "". Two paths with nothing in common (another drive on Windows) give
+   * `to` as it resolved.
+   */
+  export function relative(from: string, to: string): string
+
+  /**
+   * Whether `path` matches the glob `pattern`, as a whole: Node's
+   * `path.matchesGlob`, with a smaller pattern language.
+   *
+   * - `*` is any run of characters inside one segment, none included
+   * - `**` as a whole segment is any number of segments, none included:
+   *   "a/(**)/b" without the parentheses matches "a/b" and "a/x/y/b", and
+   *   "assets/(**)" every path below "assets" (not "assets" itself)
+   * - `?` is one character of a segment
+   * - `[a-z]` is one character of the set, `[!a-z]` one outside it
+   *
+   * A character the language reads as syntax is written as a set of one:
+   * `[*]`, `[?]`, `[[]`. There are no `{a,b}` groups (test each pattern)
+   * and no escape character. Matching is on the text as given:
+   * case-sensitive, nothing normalized, a leading dot an ordinary
+   * character. On Windows "/" and "\\" match each other, so a pattern is
+   * written with "/" on every platform. Lexical: nothing is read from
+   * disk; `glob` in flux:fs lists the files a pattern matches.
+   *
+   * Throws on a malformed pattern (an unclosed set, a `**` that is not a
+   * whole segment), naming the character.
+   *
+   * @example
+   * matchesGlob("assets/textures/lion_head.png", "assets/textures/lion_*.png") // true
+   */
+  export function matchesGlob(path: string, pattern: string): boolean
+}

package/modules/process.d.ts

@@ -52,6 +52,20 @@ declare module "flux:process" {
    * plain object, not Node's live and writable `process.env`.
    */
   export let env: Record<string, string | undefined>
+  /**
+   * Ends the process with `code` as its exit status, Node's `process.exit`.
+   * For a command line tool that is done or has failed: the process ends
+   * inside the call, so nothing pending runs (timers, promises, requests in
+   * flight); what was printed is flushed first.
+   *
+   * For a script run by the flux binaries. It throws anywhere else: in a
+   * windowed app, which ends with `exit()` from `@solidrt/core` so its
+   * `onQuit` handlers run, and in an isolate, which is not the process.
+   *
+   * @param code  An integer in 0..255, 0 (success) when omitted. Anything
+   *              else throws.
+   */
+  export function exit(code?: number): never
   /**
    * Listen for an OS signal. The callback receives the signal name. Returns an
    * unsubscribe function. Unix only; a no-op elsewhere.

package/modules/test.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Tests for a flux program: `test` registers one and `expect` asserts
+ * inside it. A test file is run by a test host, `srt test <file>` (the
+ * `flux` binary's `--test` mode underneath); imported anywhere else the
+ * module throws, since nothing would run the tests.
+ *
+ * Every test runs in an engine of its own. The host evaluates the file
+ * once to list its tests and once more for each test, so a test starts
+ * from the file's freshly evaluated state: a variable, a listener or a
+ * timer of one test is not there for the next, a test's result does not
+ * depend on the tests before it, and an uncaught error (a throw in a timer
+ * callback, a rejection nobody handles) fails the test it happened in. The
+ * file's top level therefore runs once per test, plus once for the
+ * listing; keep it to registering tests and cheap setup.
+ *
+ * The names are the familiar ones and the semantics are simplified. Tests
+ * are flat: there is no `describe` and there are no hooks. The file is the
+ * group, the test name is a sentence that names its subject, and shared
+ * setup is a plain function a test calls.
+ *
+ * A test runs on real time: timers, `performance.now()` and `Date.now()`
+ * are the wall clock's, as they are for the program under test and for
+ * whatever is on the other side of its sockets. Logic with a timeout is
+ * tested by waiting for it, or takes its delay as a parameter.
+ *
+ * `Math.random()` is seeded in a test's engine, from before the file is
+ * evaluated: random inputs, and code under test that calls
+ * `Math.random()`, are the same on every run and do not depend on the
+ * tests that ran before. It is the engine's generator in kind and
+ * resolution, only its start is fixed. An isolate the test spawns is
+ * seeded too, with a seed derived from the test's. `srt test --seed <n>`
+ * runs the tests on another sequence.
+ *
+ * A test that does not finish within 5 seconds of real time fails as timed
+ * out, a synchronous loop included, and a test that waits on a promise
+ * nothing will settle fails at once. Either way its engine is dropped with
+ * whatever it left running. A safety cap, not a wait.
+ *
+ * Present on the `flux` binary only (capability `"test"`), not in a
+ * shipping runtime.
+ *
+ * @example
+ * import { test, expect } from "flux:test"
+ *
+ * test("matchPath: a param segment matches any value", () => {
+ *   expect(matchPath("/users/$id", "/users/7")).toEqual({ id: "7" })
+ * })
+ */
+declare module "flux:test" {
+  /**
+   * Registers a test. `fn` passes when it returns, or when the promise it
+   * returns fulfills, and fails when it throws or the promise rejects.
+   * Tests run one after another, in the order they were registered. The
+   * file has to register the same tests every time it is evaluated.
+   *
+   * Throws when the name is empty or already taken in this file, and when
+   * called while a test runs: register at the top level of the file.
+   */
+  export function test(name: string, fn: () => void | Promise<void>): void
+
+  /**
+   * Starts an assertion on `received`. Each matcher throws when it does not
+   * hold, which fails the test; the message names the matcher and prints
+   * the expected and the received value.
+   */
+  export function expect(received: unknown): Matchers
+
+  /**
+   * Fulfills once nothing the test started is still in flight: work that
+   * completes by itself (a fetch, a body or file read, a query, a connect,
+   * a call into an isolate) has landed, and what it woke has run and
+   * started nothing more. For work a test set off without holding its
+   * promise; awaiting the promise itself is the direct way when there is
+   * one.
+   *
+   * What stands is not waited for: a listening server, an open socket or a
+   * read waiting on its peer, a running child process, an event listener,
+   * a timer. A test that wants a timer to fire waits for it itself.
+   *
+   * @example
+   * save(record) // writes in the background
+   * await settle()
+   * expect(await file(path).text()).toBe(expected)
+   */
+  export function settle(): Promise<void>
+
+  export interface Matchers {
+    /** The same matchers, inverted: each throws when it does hold. */
+    not: Matchers
+
+    /** The same value, as `Object.is` sees it: `NaN` is `NaN`, `0` is not `-0`, and two equal objects are not the same. */
+    toBe(expected: unknown): void
+
+    /**
+     * Equal in value, recursively. Objects are compared by their own
+     * enumerable properties, and a property whose value is `undefined`
+     * counts as absent. Arrays and typed arrays are compared element by
+     * element, and a typed array equals neither a plain array nor a typed
+     * array of another kind. `ArrayBuffer`s are compared byte by byte,
+     * `Map`s and `Set`s by their entries, `Date`s by their time, errors by
+     * name and message. Leaves are compared as `toBe` does.
+     */
+    toEqual(expected: unknown): void
+
+    /**
+     * A number within half a unit of the last of `digits` decimal places
+     * (default 2): the difference is below `10 ** -digits / 2`. The way to
+     * compare floating point results.
+     */
+    toBeCloseTo(expected: number, digits?: number): void
+
+    /**
+     * For a function: calling it throws. With a string, the thrown error's
+     * message has to contain it; with a pattern, to match it; with an error
+     * class, the thrown value has to be an instance of it.
+     */
+    toThrow(expected?: string | RegExp | (new (...args: any[]) => unknown)): void
+
+    /** Exactly `null`; `undefined` is not. */
+    toBeNull(): void
+
+    /**
+     * A string that contains the part `item`, or an array (or any other
+     * iterable) with an entry that is `item` by `===`.
+     */
+    toContain(item: unknown): void
+
+    /**
+     * An object that carries everything `pattern` names: each property of
+     * the pattern has to be present and, for a nested plain object, match
+     * in turn; anything else has to be equal as `toEqual` sees it.
+     * Properties the pattern does not name are ignored. An array in the
+     * pattern is matched entry by entry, at the same length.
+     */
+    toMatchObject(pattern: object): void
+
+    toBeLessThan(expected: number | bigint): void
+    toBeLessThanOrEqual(expected: number | bigint): void
+    toBeGreaterThan(expected: number | bigint): void
+    toBeGreaterThanOrEqual(expected: number | bigint): void
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.64",
+  "version": "0.0.65",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",