@solidrt/flux-types 0.0.71 → 0.0.73

package/gui/camera.d.ts

@@ -57,7 +57,9 @@ declare module "flux:camera" {
   /**
    * List the available camera devices. The first call also starts the camera
    * subsystem, which comes up asynchronously: expect an empty list until the
-   * initial cameraDeviceChange events arrive.
+   * initial cameraDeviceChange events arrive. Under a test that installed an
+   * image as the camera (`app.camera` of `@solidrt/test`) the list is that
+   * one camera, id 0, and every open shows the image.
    */
   export function listCameras(): CameraDevice[]
   /**

package/gui/spatial.d.ts

@@ -47,13 +47,14 @@ declare module "flux:spatial" {
    * The node's lifecycle state, for probing: whether it is leaving, its
    * effective visibility as of the last flush, and the motion in force
    * per component - one entry per running track or held write, `to` the
-   * target lanes, `heldUntil` the animation-clock ms a held write applies
-   * at (null for a running track).
+   * target lanes, `heldFor` the ms of a held write's hold still left on
+   * the node's own time as of the last advance (null for a running
+   * track).
    */
   export function describeNode(node: NodeId): {
     leaving: boolean
     shown: boolean
-    motion: { component: NodeComponent; to: number[]; heldUntil: number | null }[]
+    motion: { component: NodeComponent; to: number[]; heldFor: number | null }[]
   }
   /** Re-parent (null = make a root). Throws on a cycle. */
   export function setParent(node: NodeId, parent: NodeId | null): void
@@ -154,12 +155,40 @@ declare module "flux:spatial" {
    * setTransform. A component matching its running track's target is
    * left alone, so rewriting the whole array to move one component never
    * restarts the others (a held write's target counts, so re-sending it
-   * does not restart its delay). Each settled component fires one
-   * "spatialTransitionEnd" engine event (sol:events), payload
-   * `{ node, component: NodeComponent }` - on a live node; a leaving
-   * node's settles feed its free instead (exitNode).
+   * does not restart its delay). The core steps every track before the
+   * frame's JS (beside the clip players), so a read in the frame sees
+   * this frame's pose and a raw setTransform made in the frame wins the
+   * frame. Each settled component fires one "spatialTransitionEnd"
+   * engine event (sol:events), payload `{ node, component:
+   * NodeComponent }`, ahead of the frame's JS - on a live node; a
+   * leaving node's settles feed its free instead (exitNode).
    */
   export function writeTransform(node: NodeId, transform: Float32Array): void
+  /**
+   * Declare (null clears) the rate the native motion in the node's
+   * subtree runs at: node transitions with their delays, enters, exits
+   * and stagger slots, weights tracks, and the clip players clocked on a
+   * node under it (createPlayer's `clock`). 0 freezes, 1 is app time,
+   * other values are slow or fast motion. The nearest declaring ancestor
+   * wins, never a product through nesting (Godot's process_mode shape): a
+   * scene root at 0 freezes the world and a node inside it declaring 1
+   * keeps running - a preview spinning on a pause screen. A frozen track
+   * is not frame demand (a paused scene lets the loop idle; this write
+   * requests the frame that resumes it). Writes while frozen behave as
+   * always: undeclared components snap, declared ones retarget and wait;
+   * a node let go of (exitNode) stays a ghost until its exit can play,
+   * and a node created frozen sits at its `from`. What it does NOT
+   * cover: the app's own frame handlers, timers, video and audio stay on
+   * app time - app code gates itself, with `timeRate` as its reading.
+   * Negative and non-finite values throw (reverse playback is a player's
+   * `speed`). The dev clock (`/clock?scale=`) scales app time underneath
+   * all of this.
+   */
+  export function setTimeScale(node: NodeId, scale: number | null): void
+  /** The rate the node's motion runs at (setTimeScale): its own scale,
+   * else the nearest declaring ancestor's, else 1. What JS-driven motion
+   * inside a scaled subtree multiplies its own frame step by. */
+  export function timeRate(node: NodeId): number
   export function setVisible(node: NodeId, visible: boolean): void
   /** What a draw sink writes and where it sorts (bindDraw). */
   export type BindDrawOptions = {
@@ -241,6 +270,13 @@ declare module "flux:spatial" {
   /** Recompute every changed subtree and write the sinks; requests a frame
    * when anything was written. */
   export function flush(): void
+  /** The frame's start pass, core's to call after the frame callbacks and
+   * their reactive flush: start the lifecycle motion they declared (the
+   * enter of a node created in the frame from its `from`, the exit of one
+   * let go of), so a read in the late pass of onBeforeRender sees the pose
+   * the frame draws. Running motion steps before the callbacks instead.
+   * Idempotent within a frame; requests a frame for what it started. */
+  export function startTransitions(): void
 
   export type ShapeId = number & { readonly __spatialShape: unique symbol }
 
@@ -634,22 +670,27 @@ declare module "flux:spatial" {
   export function destroyClip(clip: ClipId): void
   /**
    * Start playing `clip`: `targets[slot]` is the node each channel
-   * animates - every target must be a live scene node (throws
-   * otherwise). Players advance on the frame clock BEFORE each frame's
-   * JS, sample and weight-blend every active player per (node, path) -
-   * two players on one node crossfade - and write the blended TRS into
-   * the arena, so frame handlers read and may overwrite freshly posed
-   * nodes (last write wins) and the frame's flush publishes the result.
-   * `speed` scales clip time (1 = as authored); `loop` wraps, else the
-   * player holds its final pose and reports once; `weight`/`fade` start
-   * the crossfade state (weight 0..1, fade = weight change per second -
-   * positive fades in, negative out; past 0 the player is removed).
-   * When a player finishes or is removed without finishing (faded out,
-   * clip or target destroyed), the "spatialClipEnd" engine event
-   * (sol:events) fires with payload { player, reason: "finished" |
-   * "dropped" }, before the same frame's handlers.
+   * animates, `clock` the node whose rate (setTimeScale) the player's
+   * time, fades and root motion run at - a player has one time over many
+   * targets, so the node it is attached to names the clock: the model's
+   * root for a mixer. Every target and the clock must be a live scene
+   * node (throws otherwise). Players advance on the frame clock BEFORE
+   * each frame's JS, sample and weight-blend every active player per
+   * (node, path) - two players on one node crossfade - and write the
+   * blended TRS into the arena, so frame handlers read and may overwrite
+   * freshly posed nodes (last write wins) and the frame's flush
+   * publishes the result. `opts` (the setPlayer field names): `speed`
+   * scales clip time (1 = as authored, the default); `loop` wraps (the
+   * default), else the player holds its final pose and reports once;
+   * `weight`/`fade` start the crossfade state (weight 0..1, default 1;
+   * fade = weight change per second, default 0 - positive fades in,
+   * negative out; past 0 the player is removed). When a player finishes
+   * or is removed without finishing (faded out, clip, clock or target
+   * destroyed), the "spatialClipEnd" engine event (sol:events) fires with
+   * payload { player, reason: "finished" | "dropped" }, before the same
+   * frame's handlers.
    */
-  export function createPlayer(clip: ClipId, targets: NodeId[], speed: number, loop: boolean, weight: number, fade: number): PlayerId
+  export function createPlayer(clip: ClipId, targets: NodeId[], clock: NodeId, opts?: { speed?: number; loop?: boolean; weight?: number; fade?: number }): PlayerId
   /** Write the given fields of a player - the O(changes) crossfade
    * channel. Setting `time` (seconds) also re-arms a finished player's
    * end report. Throws on an id that already dropped. */

package/modules/test.d.ts

@@ -130,6 +130,21 @@ declare module "flux:test" {
     /** Exactly `null`; `undefined` is not. */
     toBeNull(): void
 
+    /** Anything but `undefined`; `null` counts as defined. */
+    toBeDefined(): void
+
+    /** Exactly `undefined`; `null` is not. */
+    toBeUndefined(): void
+
+    /**
+     * A string, array, typed array or anything else with a numeric `length`
+     * whose length is `length`; a failure prints the length it found.
+     */
+    toHaveLength(length: number): void
+
+    /** An instance of the class (or constructor) `expected`, as `instanceof` sees it. */
+    toBeInstanceOf(expected: abstract new (...args: any[]) => unknown): void
+
     /**
      * A string that contains the part `item`, or an array (or any other
      * iterable) with an entry that is `item` by `===`.

package/package.json

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