@msb235/blits 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ This package follows [semver](https://semver.org). Below 1.0.0, a breaking chang
 version and everything else the patch. Each release lists its changes as **Breaking**, **Added** and
 **Fixed**, and the release workflow refuses a tag with no section here.
 
+## 0.2.1
+
+### Added
+
+- Channel `bounds`: `sum`, `mul` and `max` take `{ bounds: [min, max] }`, and `vec` inherits its
+  axis channel's. The mix clamps the folded value to the range, so stacked voices and a retarget
+  that carries speed stop flat at the bound. Bounds are part of the channel's kind.
+
 ## 0.2.0
 
 ### Breaking

package/dist/channels.d.ts

@@ -1,22 +1,27 @@
 import type { Channel, Kit } from './types.js';
+/** What a stock numeric channel takes. */
+export interface NumberOptions {
+    /** The range the value means anything in; the mix clamps to it. */
+    bounds?: readonly [min: number, max: number];
+}
 /**
  * Position axes, rotation, crawl, yaw, pitch, offset.
  *
  * @category channel
  */
-export declare function sum(): Channel<number>;
+export declare function sum(opts?: NumberOptions): Channel<number>;
 /**
  * Gain, scale, opacity, hold.
  *
  * @category channel
  */
-export declare function mul(): Channel<number>;
+export declare function mul(opts?: NumberOptions): Channel<number>;
 /**
  * Dark, aperture.
  *
  * @category channel
  */
-export declare function max(): Channel<number>;
+export declare function max(opts?: NumberOptions): Channel<number>;
 /**
  * A channel with no rest: the last influence to pass wins, and a weight can only gate it. The
  * default `lerp` steps at the midpoint, which is all a value with no arithmetic can promise; a

package/dist/channels.js

@@ -1,12 +1,15 @@
 const mix = (a, b, u) => a + (b - a) * u;
+/** Bounds change how a value folds at its edges, so they are part of the kind. */
+const kindOf = (name, bounds) => bounds === undefined ? name : `${name}[${bounds[0]}, ${bounds[1]}]`;
 /**
  * Position axes, rotation, crawl, yaw, pitch, offset.
  *
  * @category channel
  */
-export function sum() {
+export function sum(opts) {
     return {
-        kind: 'sum',
+        kind: kindOf('sum', opts?.bounds),
+        bounds: opts?.bounds,
         rest: 0,
         merge: (a, b) => a + b,
         scale: (v, w) => v * w,
@@ -18,9 +21,10 @@ export function sum() {
  *
  * @category channel
  */
-export function mul() {
+export function mul(opts) {
     return {
-        kind: 'mul',
+        kind: kindOf('mul', opts?.bounds),
+        bounds: opts?.bounds,
         rest: 1,
         merge: (a, b) => a * b,
         scale: (v, w) => 1 + (v - 1) * w,
@@ -32,9 +36,10 @@ export function mul() {
  *
  * @category channel
  */
-export function max() {
+export function max(opts) {
     return {
-        kind: 'max',
+        kind: kindOf('max', opts?.bounds),
+        bounds: opts?.bounds,
         rest: 0,
         merge: (a, b) => (a > b ? a : b),
         scale: (v, w) => v * w,
@@ -67,6 +72,7 @@ export function vec(n, of) {
     const fill = of.rest ?? 0;
     return {
         kind: of.kind === undefined ? undefined : `vec(${n}, ${of.kind})`,
+        bounds: of.bounds,
         rest,
         merge: (a, b) => {
             const out = new Array(n);

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export type { NumberOptions } from './channels.js';
 export { hex, kit, last, max, mixHex, mul, sum, vec } from './channels.js';
 export { mix, mixer } from './mixer.js';
 export type { Motion, Moving, PerSubject, Value } from './motion.js';

package/dist/mixer.js

@@ -162,12 +162,15 @@ class Mixer {
     h = null;
     names;
     channels;
+    /** Slots of the channels that declare bounds, clamped after every fold. */
+    bounded;
     slotOf = new Map();
     constructor(kit, opts) {
         this.kit = kit;
         this.opts = opts;
         this.names = Object.keys(kit);
         this.channels = this.names.map((k) => kit[k]);
+        this.bounded = this.channels.flatMap((c, i) => (c.bounds ? [i] : []));
         this.names.forEach((k, i) => {
             this.slotOf.set(k, i);
         });
@@ -737,7 +740,27 @@ class Mixer {
                 pose[key] = pose[key] === undefined ? copy(value) : channel.merge(pose[key], value);
         }
     }
+    /** Clamps every bounded channel of a folded pose into its range, in place. */
+    clamp(pose) {
+        for (const slot of this.bounded) {
+            const [lo, hi] = this.channels[slot].bounds;
+            const key = this.names[slot];
+            const v = pose[key];
+            if (typeof v === 'number')
+                pose[key] = v < lo ? lo : v > hi ? hi : v;
+            else if (Array.isArray(v))
+                for (let i = 0; i < v.length; i++) {
+                    const x = v[i];
+                    v[i] = x < lo ? lo : x > hi ? hi : x;
+                }
+        }
+        return pose;
+    }
     fold(subject, out, dry = false, except) {
+        const pose = this.folded(subject, out, dry, except);
+        return (this.bounded.length === 0 ? pose : this.clamp(pose));
+    }
+    folded(subject, out, dry = false, except) {
         const now = this.now;
         const pose = (out ?? {});
         for (let i = 0; i < this.names.length; i++) {

package/dist/types.d.ts

@@ -10,6 +10,12 @@ export interface Channel<V> {
      * as `'sum'` or `'vec(3, sum)'`. Absent, a channel matches only itself.
      */
     kind?: string;
+    /**
+     * The range a numeric value means anything in, such as 0..1 for an opacity. The mix clamps the
+     * folded value to it, axis by axis for an array, so neither stacked voices nor a retarget that
+     * carries speed can push it out; overshoot stops flat at the bound.
+     */
+    bounds?: readonly [min: number, max: number];
     /** Identity. Absent means the channel has none: it replaces rather than contributes. */
     rest?: V;
     /** Fold two influences into one. */

package/docs/schema.html

@@ -248,6 +248,9 @@
   <span class="cm">/** Names the arithmetic: 'sum', 'vec(3, sum)'. Two channels of one kind fold identically. Absent, a channel
      matches only itself. */</span>
   kind?: string;
+  <span class="cm">/** The range a numeric value means anything in. The mix clamps the folded value to it, so stacked voices and a
+     retarget that carries speed stop flat at the bound. Part of the kind: mul({ bounds: [0, 1] }) is 'mul[0, 1]'. */</span>
+  bounds?: readonly [min: number, max: number];
   <span class="cm">/** Identity. Absent means the channel has none: `color` replaces rather than contributes. */</span>
   rest?: V;
   <span class="cm">/** Fold two influences into one. */</span>
@@ -569,7 +572,7 @@ export const mixer: Engine;   <span class="cm">// the one that ships</span></cod
   <tr><td>klieg motion</td><td><code>LetterInfo</code></td><td>position vec3 sum · rotation vec3 sum · scale mul · opacity mul</td><td>Three voices in locus <code>phase</code>, fades of <code>blendMs</code>.</td></tr>
   <tr><td>klieg effects</td><td><code>PartInfo</code></td><td>gain mul · scale mul · dark max · crawl sum · position vec3 sum · rotation vec3 sum · light vec3 sum · color last</td><td>Light is premultiplied by amount before it reaches the channel, as <code>mergeOffsets</code> does.</td></tr>
   <tr><td>klieg lighting</td><td>unit</td><td>yaw sum · pitch sum</td><td>One subject, the frame. A mix with no subject dimension is a mix over one subject.</td></tr>
-  <tr><td>wod transitions</td><td>wedge <code>Segment</code></td><td>hold mul · opacity mul · scale mul · offset sum · rotate sum · aperture max · offsetAngle last</td><td>Every voice is <code>keys</code> with <code>from: 'current'</code>; the voices map goes away.</td></tr>
+  <tr><td>wod transitions</td><td>wedge <code>Segment</code></td><td>hold mul[0, 1] · opacity mul[0, 1] · scale mul · offset sum · rotate sum · aperture max[0, 1] · offsetAngle last</td><td>Every voice is <code>keys</code> with <code>from: 'current'</code>; the voices map goes away.</td></tr>
   <tr><td>sherpa seams</td><td>page</td><td>opacity mul · transform (host's) · clip max</td><td>Exit and enter as two voices; overlap is whether both are live at once.</td></tr>
   <tr><td>magicsmoke faults</td><td>fault</td><td>none: the patch writes no channels</td><td>One voice per fault, on a mix per fault that magicsmoke keeps to itself. Its weight is the intensity, a number or any signal. Its state is the seeded discharge process, stepped under <code>stepMs: 5</code>, easing exponentially toward <code>setting.weight</code> and sending each discharge as an event. Stopping is <code>handle.fade()</code>; <code>blow</code> writes into the fault's own state through magicsmoke's handle, not as a second voice. The mix never sets <code>reduce</code>, which would step off the grid, and <code>cue</code> passes the last synced timestamp as <code>start</code>, the old process's clock origin. Jolt, whine and hum stay off blits: the browser already composites jolt, and whine and hum fade on the audio clock. magicsmoke imports <code>Signal</code>, <code>Handle</code>, <code>Setting</code>, <code>slew</code> and <code>level</code>, so those are surface to keep stable.</td></tr>
 </table></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msb235/blits",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Concurrent effects: each on its own clock with its own state and weight, folded into one value per subject per frame",
   "keywords": [
     "animation",