@msb235/blits 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0
+
+First release. A mix folds concurrent effects into one value per subject per frame: each effect runs
+on its own clock with its own state and weight, and the rules for combining them belong to the
+channel being written rather than to the effect writing it.
+
+What is here: the stock channels (`sum`, `mul`, `max`, `last`, `vec`, `hex`), both authoring forms
+for a patch (a function of phase, or a list of keyframes), voices with rates, loops, stagger, fade
+envelopes and loci, the five signals (`peak`, `slew`, `lag`, `level`, `gate`) with their state
+kept per voice and subject, per-subject state that catches up by its own gap or, under `stepMs`, at a
+fixed interval so it plays the same at any frame rate, events a patch sends for the host to `drain`,
+`handle.weightOf` for reading a voice's weight per subject, the checks that let one package's
+patches mix into another's (`Channel.kind`, `Patch.kit` and `Patch.reads` checked at `cue`, and
+`tags` to drain one package's events), and the `Engine` seam behind `mix`.
+
+[klieg](https://github.com/orochi235/klieg) composes its motion, its effects and its lighting on
+this, which is where the arithmetic was proven: that port changed no number and moved no baseline.
+
+Zero runtime dependencies. ESM only. The design is `docs/schema.html`, shipped alongside.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Baker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# blits
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Concurrent effects, mixed. Each effect runs on its own clock with its own state and weight, and a
+mix folds them into one value per subject per frame by rules that belong to the channel, not the
+effect.
+
+It is the thing klieg does three times over — motion, effects, lighting — and wod does once for
+transitions, extracted so those repos, sherpa and magicsmoke can share one vocabulary and one
+engine.
+
+```ts
+import { hex, kit, max, mix, mul, patch, sum, vec } from '@msb235/blits';
+
+// What a part of a sign can move on. The arithmetic lives here and nowhere else.
+const PART = kit<PartPose>({
+  gain: mul(),
+  dark: max(),
+  position: vec(3, sum()),
+  color: hex(),
+});
+
+const flicker = patch<Part, PartPose>(
+  180,
+  (phase, part) => ({ gain: 0.2 + 0.8 * Math.abs(Math.sin(phase * Math.PI + part.seed)) }),
+  { writes: ['gain'] },
+);
+
+const m = mix<Part, PartPose>(PART);
+const handle = m.cue({ patch: flicker, fade: { in: 300, out: 300 } });
+
+// Once a frame: tell the mix what time it is, then ask for the parts you are about to draw.
+function frame(timestamp: number) {
+  m.sync(timestamp);
+  for (const part of visible) apply(part, m.probe(part, scratch));
+  if (m.live) requestAnimationFrame(frame);
+}
+
+// A hidden tab gets no frames; say the time away should not count, or every fade finishes at once.
+document.addEventListener('visibilitychange', () => document.hidden || m.rebase());
+
+handle.fade({ over: 500 }); // the voice ramps out and leaves
+```
+
+## The words
+
+Ten of them carry the rest: **delta** (a partial record of channel values), **channel** (one field
+with its own arithmetic), **kit** (the channel set for one kind of delta), **subject** (what is
+driven), **patch** (a pure function of phase and a subject), **voice** (a patch with its own clock
+and weight), **mix** (the live voices over one kit), **signal** (a 0..1 scalar from outside the
+clock), **handle** (the live controls on one voice), **engine** (the implementation behind a mix).
+
+The design — the full vocabulary, the channel table, the time model, blending, the engine seam, and
+what is still open — is `docs/schema.html`, which ships in the package: open it from
+`node_modules/@msb235/blits/`. The naming work behind it is
+`docs/vocabulary.json`, which semanticore serves as a page.
+That repo is private; the JSON stands on its own.
+
+## The site
+
+`site/` is a docs site with a live explainer for each word and the API reference, generated from the
+doc comments in `src/`. It runs the working tree, not a build:
+
+```
+npm run site         # dev server on port 4880
+npm run site:smoke   # build, then load every page headless and fail on any error
+```
+
+`.github/workflows/site.yml` deploys it to GitHub Pages. It runs only by hand until Pages is enabled
+on the repo.
+
+## Status
+
+v0.1.0, and one real consumer: [klieg](https://github.com/orochi235/klieg) composes all three of
+its systems — letter motion, part effects, and the environment a sign is lit by — on a mix each.
+That port was an extraction rather than a rewrite, so it is also the evidence that the arithmetic
+here is the arithmetic a working renderer already had: klieg's suite of 1974 cases and its
+screenshot baselines came through it unchanged.
+
+One thing the port sent back. klieg's three motion phases layer, so they cue as separate voices; a
+`locus` folds its members through each channel's `lerp` instead, which is what a crossfade between
+alternatives wants and is not the same number on a multiplicative channel. Reach for a locus when
+one voice should replace another, not when both should be heard.
+
+Zero runtime dependencies, ESM only, types included.
+
+```
+npm install
+npm run check   # lint, typecheck, test
+```
+
+MIT.

package/dist/channels.d.ts

@@ -0,0 +1,54 @@
+import type { Channel, Kit } from './types.js';
+/**
+ * Position axes, rotation, crawl, yaw, pitch, offset.
+ *
+ * @category channel
+ */
+export declare function sum(): Channel<number>;
+/**
+ * Gain, scale, opacity, hold.
+ *
+ * @category channel
+ */
+export declare function mul(): Channel<number>;
+/**
+ * Dark, aperture.
+ *
+ * @category channel
+ */
+export declare function max(): 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
+ * consumer with a real interpolation passes its own, as `hex` does.
+ *
+ * @category channel
+ */
+export declare function last<V>(opts?: {
+    lerp?: (a: V, b: V, u: number) => V;
+}): Channel<V>;
+/**
+ * Vec3 position, premultiplied light: one channel's arithmetic applied down an axis list.
+ *
+ * @category channel
+ */
+export declare function vec(n: number, of: Channel<number>): Channel<number[]>;
+/**
+ * sRGB, which is what klieg's light channel already assumes, so the port's arithmetic is
+ * unchanged. OKLCH reads better across hues and is the open question, not a second function.
+ *
+ * @category channel
+ */
+export declare function mixHex(a: number, b: number, u: number): number;
+/**
+ * Color, as 0xrrggbb.
+ *
+ * @category channel
+ */
+export declare function hex(): Channel<number>;
+/**
+ * A kit is plain data; this only fixes the type.
+ *
+ * @category channel
+ */
+export declare function kit<O>(channels: Kit<O>): Kit<O>;

package/dist/channels.js

@@ -0,0 +1,131 @@
+const mix = (a, b, u) => a + (b - a) * u;
+/**
+ * Position axes, rotation, crawl, yaw, pitch, offset.
+ *
+ * @category channel
+ */
+export function sum() {
+    return {
+        kind: 'sum',
+        rest: 0,
+        merge: (a, b) => a + b,
+        scale: (v, w) => v * w,
+        lerp: mix,
+    };
+}
+/**
+ * Gain, scale, opacity, hold.
+ *
+ * @category channel
+ */
+export function mul() {
+    return {
+        kind: 'mul',
+        rest: 1,
+        merge: (a, b) => a * b,
+        scale: (v, w) => 1 + (v - 1) * w,
+        lerp: mix,
+    };
+}
+/**
+ * Dark, aperture.
+ *
+ * @category channel
+ */
+export function max() {
+    return {
+        kind: 'max',
+        rest: 0,
+        merge: (a, b) => (a > b ? a : b),
+        scale: (v, w) => v * w,
+        lerp: mix,
+    };
+}
+/**
+ * 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
+ * consumer with a real interpolation passes its own, as `hex` does.
+ *
+ * @category channel
+ */
+export function last(opts) {
+    return {
+        // A lerp of its own is arithmetic the name cannot vouch for.
+        kind: opts?.lerp ? undefined : 'last',
+        merge: (_a, b) => b,
+        lerp: opts?.lerp ?? ((a, b, u) => (u < 0.5 ? a : b)),
+    };
+}
+/**
+ * Vec3 position, premultiplied light: one channel's arithmetic applied down an axis list.
+ *
+ * @category channel
+ */
+export function vec(n, of) {
+    const rest = of.rest === undefined ? undefined : new Array(n).fill(of.rest);
+    const scale = of.scale;
+    const fill = of.rest ?? 0;
+    return {
+        kind: of.kind === undefined ? undefined : `vec(${n}, ${of.kind})`,
+        rest,
+        merge: (a, b) => {
+            const out = new Array(n);
+            for (let i = 0; i < n; i++)
+                out[i] = of.merge(a[i] ?? fill, b[i] ?? fill);
+            return out;
+        },
+        scale: scale === undefined
+            ? undefined
+            : (v, w) => {
+                const out = new Array(n);
+                for (let i = 0; i < n; i++)
+                    out[i] = scale(v[i] ?? fill, w);
+                return out;
+            },
+        fold: scale === undefined
+            ? undefined
+            : (into, v, w) => {
+                for (let i = 0; i < n; i++)
+                    into[i] = of.merge(into[i] ?? fill, scale(v[i] ?? fill, w));
+                return into;
+            },
+        lerp: (a, b, u) => {
+            const out = new Array(n);
+            for (let i = 0; i < n; i++)
+                out[i] = of.lerp(a[i] ?? fill, b[i] ?? fill, u);
+            return out;
+        },
+    };
+}
+const clamp255 = (v) => (v < 0 ? 0 : v > 255 ? 255 : Math.round(v));
+/**
+ * sRGB, which is what klieg's light channel already assumes, so the port's arithmetic is
+ * unchanged. OKLCH reads better across hues and is the open question, not a second function.
+ *
+ * @category channel
+ */
+export function mixHex(a, b, u) {
+    const ar = (a >> 16) & 0xff;
+    const ag = (a >> 8) & 0xff;
+    const ab = a & 0xff;
+    const br = (b >> 16) & 0xff;
+    const bg = (b >> 8) & 0xff;
+    const bb = b & 0xff;
+    return ((clamp255(mix(ar, br, u)) << 16) | (clamp255(mix(ag, bg, u)) << 8) | clamp255(mix(ab, bb, u)));
+}
+/**
+ * Color, as 0xrrggbb.
+ *
+ * @category channel
+ */
+export function hex() {
+    return { ...last({ lerp: mixHex }), kind: 'hex' };
+}
+/**
+ * A kit is plain data; this only fixes the type.
+ *
+ * @category channel
+ */
+export function kit(channels) {
+    return channels;
+}

package/dist/easing.d.ts

@@ -0,0 +1,4 @@
+import type { Easing } from './types.js';
+export type Curve = (u: number) => number;
+/** The function an easing names. Resolved once where a patch or voice is built, not per frame. */
+export declare function curve(easing: Easing): Curve;

package/dist/easing.js

@@ -0,0 +1,75 @@
+const linear = (u) => u;
+/** A CSS `cubic-bezier`: solves x(t) = u for t, then reads y(t). */
+function bezier(x1, y1, x2, y2) {
+    const cx = 3 * x1;
+    const bx = 3 * (x2 - x1) - cx;
+    const ax = 1 - cx - bx;
+    const cy = 3 * y1;
+    const by = 3 * (y2 - y1) - cy;
+    const ay = 1 - cy - by;
+    const x = (t) => ((ax * t + bx) * t + cx) * t;
+    const dx = (t) => (3 * ax * t + 2 * bx) * t + cx;
+    const y = (t) => ((ay * t + by) * t + cy) * t;
+    return (u) => {
+        if (u <= 0)
+            return 0;
+        if (u >= 1)
+            return 1;
+        let t = u;
+        for (let i = 0; i < 8; i++) {
+            const err = x(t) - u;
+            if (Math.abs(err) < 1e-7)
+                return y(t);
+            const d = dx(t);
+            if (Math.abs(d) < 1e-6)
+                break;
+            t -= err / d;
+        }
+        let lo = 0;
+        let hi = 1;
+        t = u;
+        while (hi - lo > 1e-7) {
+            if (x(t) < u)
+                lo = t;
+            else
+                hi = t;
+            t = (lo + hi) / 2;
+        }
+        return y(t);
+    };
+}
+const named = {
+    linear,
+    ease: bezier(0.25, 0.1, 0.25, 1),
+    'ease-in': bezier(0.42, 0, 1, 1),
+    'ease-out': bezier(0, 0, 0.58, 1),
+    'ease-in-out': bezier(0.42, 0, 0.58, 1),
+};
+const built = new WeakMap();
+/** The function an easing names. Resolved once where a patch or voice is built, not per frame. */
+export function curve(easing) {
+    if (typeof easing === 'function')
+        return easing;
+    if (typeof easing === 'string') {
+        const found = named[easing];
+        if (!found)
+            throw new Error(`blits: no easing named ${easing}`);
+        return found;
+    }
+    const held = built.get(easing);
+    if (held)
+        return held;
+    let made;
+    if ('bezier' in easing)
+        made = bezier(...easing.bezier);
+    else {
+        const n = easing.steps;
+        const start = easing.jump === 'start';
+        made = (u) => {
+            const c = u <= 0 ? 0 : u >= 1 ? 1 : u;
+            return (start ? Math.ceil(c * n) : Math.floor(c * n)) / n;
+        };
+    }
+    built.set(easing, made);
+    return made;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { hex, kit, last, max, mixHex, mul, sum, vec } from './channels.js';
+export { mix, mixer } from './mixer.js';
+export type { KeysOptions, PatchOptions } from './patch.js';
+export { keys, patch } from './patch.js';
+export { gate, lag, level, peak, slew } from './signals.js';
+export type { Channel, Easing, Engine, FadeOptions, FadeSpec, Handle, Keyframe, Kit, Mix, MixOptions, Patch, Sent, Setting, Signal, VoiceSpec, } from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { hex, kit, last, max, mixHex, mul, sum, vec } from './channels.js';
+export { mix, mixer } from './mixer.js';
+export { keys, patch } from './patch.js';
+export { gate, lag, level, peak, slew } from './signals.js';

package/dist/mixer.d.ts

@@ -0,0 +1,13 @@
+import type { Engine, Kit, Mix, MixOptions } from './types.js';
+/**
+ * The one that ships: both forms on the CPU, probed per subject on demand.
+ *
+ * @category engine
+ */
+export declare const mixer: Engine;
+/**
+ * Makes a mix over a kit, on the engine the options name or the stock one.
+ *
+ * @category mix
+ */
+export declare function mix<I, O>(kit: Kit<O>, opts?: MixOptions): Mix<I, O>;