@hyperframes/core 0.8.63 → 0.8.65

package/dist/vfx/refs/fractalNoise.js

@@ -0,0 +1,94 @@
+/**
+ * CPU reference for the `fractal-noise` kernel — a pure function of the same
+ * inputs the GLSL gets, built from the same `HASH_CONSTANTS`. The determinism
+ * contract's cross-backend bar (PSNR ≥ 32 dB, K = 4 sample frames) is measured
+ * against this, so it must stay a line-for-line mirror of the shader rather
+ * than an independent idea of what the effect should look like.
+ *
+ * Coordinates are **device pixels with y measured from the bottom** — the
+ * shader's `v_uv * u_size`, and the order `gl.readPixels` returns rows in. The
+ * shader samples fragment centres, so a caller comparing against pixel
+ * `(i, j)` should pass `(i + 0.5, j + 0.5)`.
+ */
+import { normalizeVfxParams } from "../../vfx.js";
+import { HASH_CONSTANTS } from "../fractalNoise.frag.js";
+const { mulX, mulY, mulMix, offset, shift1, shift2, divisor } = HASH_CONSTANTS;
+/**
+ * The shader's `hfHashUnit`. `Math.imul` + `>>> 0` reproduce GLSL's 32-bit
+ * `uint` wrap-around exactly; without them JS would carry the products into
+ * doubles and drift from the GPU immediately.
+ */
+export function fractalNoiseHashUnit(ix, iy, seed) {
+    let h = ((Math.imul(ix, mulX) ^ Math.imul(iy, mulY) ^ Math.imul(seed, mulMix)) >>> 0) + offset;
+    h = h >>> 0;
+    h = (h ^ (h >>> shift1)) >>> 0;
+    h = Math.imul(h, mulMix) >>> 0;
+    h = (h ^ (h >>> shift2)) >>> 0;
+    return h / divisor;
+}
+/** Noise Type picks the interpolation curve: Block, Linear, Soft Linear, Spline. */
+function fade(f, noiseType) {
+    if (noiseType < 1.5)
+        return 0;
+    if (noiseType < 2.5)
+        return f;
+    if (noiseType < 3.5)
+        return f * f * (3 - 2 * f);
+    return f * f * f * (f * (f * 6 - 15) + 10);
+}
+function mix(a, b, w) {
+    return a + (b - a) * w;
+}
+function valueNoise(px, py, seed, noiseType) {
+    const cx = Math.floor(px);
+    const cy = Math.floor(py);
+    const sx = fade(px - cx, noiseType);
+    const sy = fade(py - cy, noiseType);
+    const bottom = mix(fractalNoiseHashUnit(cx, cy, seed), fractalNoiseHashUnit(cx + 1, cy, seed), sx);
+    const top = mix(fractalNoiseHashUnit(cx, cy + 1, seed), fractalNoiseHashUnit(cx + 1, cy + 1, seed), sx);
+    return mix(bottom, top, sy);
+}
+function fbm(px, py, s) {
+    const lacunarity = 100 / Math.max(s.subScaling, 1);
+    const gain = s.subInfluence / 100;
+    let amp = 1;
+    let freq = 1;
+    let sum = 0;
+    let norm = 0;
+    for (let i = 0; i < s.complexity; i++) {
+        sum += amp * valueNoise(px * freq, py * freq, s.randomSeed + i, s.noiseType);
+        norm += amp;
+        amp *= gain;
+        freq *= lacunarity;
+    }
+    return norm > 0 ? sum / norm : 0;
+}
+/**
+ * The grey level the kernel writes at `(x, y)`, in [0, 1]. The shader then
+ * premultiplies it by `opacity/100` and writes that as alpha; this returns the
+ * unpremultiplied value so a caller can check either.
+ *
+ * `t` is part of the call shape every kernel reference shares. Fractal Noise
+ * is time-invariant — its animation arrives as a tweened `evolution` — so it
+ * is deliberately unread here.
+ */
+export function fractalNoiseRef(p, t, params) {
+    void t;
+    const n = normalizeVfxParams("fractal-noise", params);
+    const scale = Math.max(n["scale"], 1);
+    const evolution = n["evolution"];
+    const px = p.x / scale + evolution;
+    const py = p.y / scale + evolution * 0.5;
+    let v = fbm(px, py, {
+        complexity: n["complexity"],
+        subInfluence: n["subInfluence"],
+        subScaling: n["subScaling"],
+        randomSeed: Math.trunc(n["randomSeed"]),
+        noiseType: n["noiseType"],
+    });
+    v = (v - 0.5) * (n["contrast"] / 100) + 0.5 + n["brightness"] / 100;
+    if (n["invert"] === true)
+        v = 1 - v;
+    return Math.min(1, Math.max(0, v));
+}
+//# sourceMappingURL=fractalNoise.js.map

package/dist/vfx/refs/fractalNoise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fractalNoise.js","sourceRoot":"","sources":["../../../src/vfx/refs/fractalNoise.ts"],"names":[],"mappings":"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"}

package/dist/vfx/refs/waveWarp.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CPU reference for the `wave-warp` kernel. It returns the *source coordinate*
+ * the kernel samples rather than a colour: the displacement is the whole of
+ * what the kernel decides, and a caller with the source image can look the
+ * colour up itself.
+ *
+ * Coordinates are device pixels with y measured from the bottom — the shader's
+ * `v_uv * u_size`, and the order `gl.readPixels` returns rows in.
+ */
+import { type HfVfxParamValues } from "../../vfx";
+/** Where the kernel reads from to paint `(x, y)`, in the same pixel space. */
+export declare function waveWarpSampleRef(p: {
+    x: number;
+    y: number;
+}, t: number, params: HfVfxParamValues): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=waveWarp.d.ts.map

package/dist/vfx/refs/waveWarp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waveWarp.d.ts","sourceRoot":"","sources":["../../../src/vfx/refs/waveWarp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAKtE,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3B,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,gBAAgB,GACvB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAU1B"}

package/dist/vfx/refs/waveWarp.js

@@ -0,0 +1,25 @@
+/**
+ * CPU reference for the `wave-warp` kernel. It returns the *source coordinate*
+ * the kernel samples rather than a colour: the displacement is the whole of
+ * what the kernel decides, and a caller with the source image can look the
+ * colour up itself.
+ *
+ * Coordinates are device pixels with y measured from the bottom — the shader's
+ * `v_uv * u_size`, and the order `gl.readPixels` returns rows in.
+ */
+import { normalizeVfxParams } from "../../vfx.js";
+import { WAVE_WARP_CONSTANTS } from "../waveWarp.frag.js";
+const { tau, degreesPerTurn } = WAVE_WARP_CONSTANTS;
+/** Where the kernel reads from to paint `(x, y)`, in the same pixel space. */
+export function waveWarpSampleRef(p, t, params) {
+    const n = normalizeVfxParams("wave-warp", params);
+    const dir = (n["direction"] * Math.PI) / 180;
+    const travelX = Math.sin(dir);
+    const travelY = -Math.cos(dir);
+    const proj = (p.x + 1) * travelX + p.y * travelY;
+    const turns = proj / Math.max(n["width"], 1) + n["phase"] / degreesPerTurn + n["speed"] * t;
+    const disp = n["height"] * Math.sin(tau * turns);
+    // The displacement swings perpendicular to the direction of travel.
+    return { x: p.x - travelY * disp, y: p.y + travelX * disp };
+}
+//# sourceMappingURL=waveWarp.js.map

package/dist/vfx/refs/waveWarp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waveWarp.js","sourceRoot":"","sources":["../../../src/vfx/refs/waveWarp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAyB,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,mBAAmB,CAAC;AAEpD,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAC/B,CAA2B,EAC3B,CAAS,EACT,MAAwB;IAExB,MAAM,CAAC,GAAG,kBAAkB,CAAC,WAAW,EAAE,MAAM,CAA2B,CAAC;IAC5E,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,WAAW,CAAE,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IACjD,MAAM,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAE,GAAG,cAAc,GAAG,CAAC,CAAC,OAAO,CAAE,GAAG,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC;IAClD,oEAAoE;IACpE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC;AAC9D,CAAC"}

package/dist/vfx/waveWarp.frag.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `wave-warp` kernel — GLSL ES 3.00, capture `self`.
+ *
+ * **Scope (v1, recorded rather than implied):** After Effects builds a
+ * 2048-entry displacement table per Wave Type on the CPU and reads it as
+ * `disp = table[round(proj/65536 + phase) & 2047]`, where
+ * `proj = (x + 1)·dirX + y·dirY`. The corpus needs **Wave Type 1 (Sine)** only
+ * (Direction 0, Speed 1, Pinning 1, Phase 0, Height/Width animated), and Sine
+ * ports analytically:
+ *
+ *     disp = height · sin(2π · (proj/width + phase/360 + speed·t))
+ *
+ * applied perpendicular to the direction of travel, sampling `u_src` at the
+ * displaced coordinate with **clamp-to-transparent** edges. The other wave
+ * types are not defs in v1 — the exporter marks them cosmetic — and a
+ * 2048-wide strip probe is the upgrade path if the gate fails on Sine.
+ *
+ * **Pinning is not implemented (v1 = 1, "none").** The def's `pinning` option
+ * list carries only that value, so `normalizeVfxParams` folds anything else
+ * back to it, matching how `fractal-noise` handles Fractal Type.
+ *
+ * **Open question for the corpus gate:** `direction` is treated here as the
+ * direction of *travel*, with the displacement perpendicular to it — the
+ * reading the deep dive's `proj` formula supports. If After Effects' UI angle
+ * instead names the *displacement* axis, every direction is 90° out and the
+ * exporter's handler gains that offset. Corpus retro-wave uses Direction 0, so
+ * the two readings differ only by which axis moves.
+ */
+/**
+ * Angles arrive in degrees (AE's unit) and `phase` is degrees of one wave;
+ * both meet `2π` here, so the constant is shared rather than spelled twice.
+ */
+export declare const WAVE_WARP_CONSTANTS: {
+    readonly tau: 6.283185307179586;
+    readonly degreesPerTurn: 360;
+};
+export declare const WAVE_WARP_FRAG: string;
+//# sourceMappingURL=waveWarp.frag.d.ts.map

package/dist/vfx/waveWarp.frag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waveWarp.frag.d.ts","sourceRoot":"","sources":["../../src/vfx/waveWarp.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC;AAIX,eAAO,MAAM,cAAc,QAmC1B,CAAC"}

package/dist/vfx/waveWarp.frag.js

@@ -0,0 +1,74 @@
+/**
+ * `wave-warp` kernel — GLSL ES 3.00, capture `self`.
+ *
+ * **Scope (v1, recorded rather than implied):** After Effects builds a
+ * 2048-entry displacement table per Wave Type on the CPU and reads it as
+ * `disp = table[round(proj/65536 + phase) & 2047]`, where
+ * `proj = (x + 1)·dirX + y·dirY`. The corpus needs **Wave Type 1 (Sine)** only
+ * (Direction 0, Speed 1, Pinning 1, Phase 0, Height/Width animated), and Sine
+ * ports analytically:
+ *
+ *     disp = height · sin(2π · (proj/width + phase/360 + speed·t))
+ *
+ * applied perpendicular to the direction of travel, sampling `u_src` at the
+ * displaced coordinate with **clamp-to-transparent** edges. The other wave
+ * types are not defs in v1 — the exporter marks them cosmetic — and a
+ * 2048-wide strip probe is the upgrade path if the gate fails on Sine.
+ *
+ * **Pinning is not implemented (v1 = 1, "none").** The def's `pinning` option
+ * list carries only that value, so `normalizeVfxParams` folds anything else
+ * back to it, matching how `fractal-noise` handles Fractal Type.
+ *
+ * **Open question for the corpus gate:** `direction` is treated here as the
+ * direction of *travel*, with the displacement perpendicular to it — the
+ * reading the deep dive's `proj` formula supports. If After Effects' UI angle
+ * instead names the *displacement* axis, every direction is 90° out and the
+ * exporter's handler gains that offset. Corpus retro-wave uses Direction 0, so
+ * the two readings differ only by which axis moves.
+ */
+/**
+ * Angles arrive in degrees (AE's unit) and `phase` is degrees of one wave;
+ * both meet `2π` here, so the constant is shared rather than spelled twice.
+ */
+export const WAVE_WARP_CONSTANTS = {
+    tau: 6.283185307179586,
+    degreesPerTurn: 360,
+};
+const { tau, degreesPerTurn } = WAVE_WARP_CONSTANTS;
+export const WAVE_WARP_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 v_uv;
+out vec4 fragColor;
+
+uniform vec2 u_size;
+uniform float u_t;
+uniform float u_fps;
+uniform sampler2D u_src;
+uniform float u_waveType;
+uniform float u_height;
+uniform float u_width;
+uniform float u_direction;
+uniform float u_speed;
+uniform float u_pinning;
+uniform float u_phase;
+
+// Outside the layer's own box there is nothing to warp in from, so the wave
+// carries transparency rather than a smeared edge pixel.
+vec4 hfSampleSrc(vec2 uv) {
+  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return vec4(0.0);
+  return texture(u_src, uv);
+}
+
+void main() {
+  vec2 px = v_uv * u_size;
+  float dir = radians(u_direction);
+  vec2 travel = vec2(sin(dir), -cos(dir));
+  vec2 swing = vec2(-travel.y, travel.x);
+  float proj = (px.x + 1.0) * travel.x + px.y * travel.y;
+  float turns = proj / max(u_width, 1.0) + u_phase / ${degreesPerTurn}.0 + u_speed * u_t;
+  float disp = u_height * sin(${tau} * turns);
+  fragColor = hfSampleSrc((px + swing * disp) / u_size);
+}
+`;
+//# sourceMappingURL=waveWarp.frag.js.map

package/dist/vfx/waveWarp.frag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waveWarp.frag.js","sourceRoot":"","sources":["../../src/vfx/waveWarp.frag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,GAAG,EAAE,iBAAiB;IACtB,cAAc,EAAE,GAAG;CACX,CAAC;AAEX,MAAM,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,mBAAmB,CAAC;AAEpD,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uDA+ByB,cAAc;gCACrC,GAAG;;;CAGlC,CAAC"}

package/dist/vfx.d.ts

@@ -0,0 +1,121 @@
+/**
+ * VFX chain: the one description of every per-pixel effect that can be
+ * applied to a layer's own pixels through the WebGL2 runtime.
+ *
+ * Mirrors `audioFx.ts` (`data-fx-chain`) in shape: a versioned JSON chain
+ * attribute, a def registry with typed params, and parse/serialize/normalize
+ * helpers so the exporter and the runtime agree on one description of each
+ * effect.
+ */
+export declare const HF_VFX_ATTR = "data-vfx-chain";
+/**
+ * Chain files are versioned; a reader must refuse a version it doesn't know.
+ * Exported for the exporter (hyperframes-ae-mcp), which stamps the version it
+ * emits; inside this repo only parse/serialize below read it.
+ */
+export declare const HF_VFX_CHAIN_VERSION = 1;
+/**
+ * What a def's kernel must read besides `(x, y, t, params)`:
+ * - `none` — the kernel is a generator/replacement; no captured texture.
+ * - `self` — the kernel reads the host's own pixels through a `layoutsubtree`
+ *   capture canvas.
+ * - `backdrop` — the kernel reads everything below the host (adjustment-layer
+ *   style effects).
+ */
+export type HfVfxCapture = "none" | "self" | "backdrop";
+export interface HfVfxNumberParam {
+    kind: "number";
+    key: string;
+    label: string;
+    unit: string;
+    min: number;
+    max: number;
+    step: number;
+    default: number;
+    /** May be driven by a `--vfx-<nodeId>-<key>` CSS var instead of `params`. */
+    animatable?: boolean;
+    hint?: string;
+}
+export interface HfVfxEnumParam {
+    kind: "enum";
+    key: string;
+    label: string;
+    options: readonly {
+        value: number;
+        label: string;
+    }[];
+    default: number;
+    hint?: string;
+}
+export interface HfVfxBoolParam {
+    kind: "bool";
+    key: string;
+    label: string;
+    default: boolean;
+}
+/** A second-source param (v1.1): its value is the id of another element. */
+export interface HfVfxRefParam {
+    kind: "ref";
+    key: string;
+    label: string;
+}
+export type HfVfxParam = HfVfxNumberParam | HfVfxEnumParam | HfVfxBoolParam | HfVfxRefParam;
+/** `string` values only occur for `ref` params (element ids). */
+export type HfVfxParamValues = Record<string, number | boolean | string>;
+export interface HfVfxDef {
+    id: string;
+    label: string;
+    /** What the kernel must read besides (x, y, t, params). */
+    capture: HfVfxCapture;
+    params: readonly HfVfxParam[];
+    /** GLSL ES 3.00 fragment source; uniforms are u_size/u_t/u_fps/u_src(2)/u_<key>. */
+    frag: string;
+    /** AE match name this def ports, for docs — e.g. "ADBE Fractal Noise". */
+    ae?: string;
+}
+/**
+ * The def registry. Params come from the AE deep dives and retro-wave's
+ * observed values; each kernel's own `frag` module states the v1 scope
+ * decision — which of the effect's modes it actually implements and why.
+ *
+ * Exported as the whole registry for the exporter and Studio's effect picker;
+ * inside the runtime, defs are reached through `getVfxDef`.
+ */
+export declare const HF_VFX: readonly HfVfxDef[];
+export declare function getVfxDef(id: string): HfVfxDef | undefined;
+/**
+ * Clamp and fill a parameter set so it is always renderable: unknown keys are
+ * dropped, missing keys take their default, numbers are clamped into their
+ * declared range, an unrecognised enum value falls back to its default, and a
+ * non-boolean bool value falls back to its default. Mirrors
+ * `normalizeAudioFxParams`.
+ */
+export declare function normalizeVfxParams(id: string, values: Readonly<HfVfxParamValues> | undefined): HfVfxParamValues;
+export interface HfVfxNode {
+    type: string;
+    id: string;
+    enabled?: boolean;
+    params: HfVfxParamValues;
+}
+export interface HfVfxChain {
+    version: 1;
+    nodes: HfVfxNode[];
+}
+export declare class VfxChainError extends Error {
+    constructor(message: string);
+}
+/** The nodes that should paint, in order. */
+export declare function enabledVfxNodes(chain: HfVfxChain): HfVfxNode[];
+/** A chain's capture requirement is the strongest of its enabled nodes'. */
+export declare function chainCapture(chain: HfVfxChain): HfVfxCapture;
+/**
+ * Parse a chain file. Unknown effect ids are rejected rather than skipped: a
+ * chain that silently loses a node would render differently from the
+ * composition the author saved, which is worse than refusing to render at
+ * all. Params are kept as given (not normalized) so a chain round-trips
+ * exactly; call `normalizeVfxParams` at paint time.
+ */
+export declare function parseVfxChain(json: string): HfVfxChain;
+/** Serialise a chain for the `data-vfx-chain` attribute. */
+export declare function serializeVfxChain(chain: HfVfxChain): string;
+//# sourceMappingURL=vfx.d.ts.map

package/dist/vfx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfx.d.ts","sourceRoot":"","sources":["../src/vfx.ts"],"names":[],"mappings":"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"}