@hyperframes/core 0.8.212 → 0.8.214

package/dist/audioAnalysis.d.ts

@@ -99,6 +99,7 @@ export interface KindFeatures {
     syllables: number;
     /** Share of 50 ms frames within 20 dB of the loud end (95th percentile), 0–1: high for beds and speech, low for hits. */
     sustain: number;
+    voiced?: number;
 }
 export declare const signalDuration: (signal: AudioSignal) => number;
 /** Per-sample energy. Channels are squared first, so a reversed channel stays audible. */
@@ -112,10 +113,11 @@ export declare function silence(signal: AudioSignal, options?: SilenceOptions):
 export declare function kindFeatures(signal: AudioSignal): KindFeatures;
 /**
  * A first guess at what the audio is. Length decides most of it: beds run long, effects short. Long audio is voice
- * when its envelope moves at syllable rate without a beat; short audio is voice when it also holds its level.
+ * when its envelope moves at syllable rate without a beat; short audio also holds its level. Both need a voice pitch.
  */
 export declare function classify(signal: AudioSignal): KindGuess;
 export * from "./audioAnalysisLadder.js";
+export * from "./audioPitch.js";
 export * from "./audioRhythm.js";
 export * from "./audioSections.js";
 export * from "./audioSnap.js";

package/dist/audioAnalysis.js

@@ -4,6 +4,7 @@
  */
 import { finish } from "./audioSteps.js";
 import { fft } from "./fft.js";
+import { voicedShare } from "./audioPitch.js";
 import { rhythm } from "./audioRhythm.js";
 import { sections } from "./audioSections.js";
 const DB_FLOOR = -120;
@@ -416,26 +417,33 @@ export function kindFeatures(signal) {
         sustain: round(sustainShare(signal)),
     };
 }
+const VOICED_SPEECH = 0.15;
+const VOICED_STEADY_SPEECH = 0.25;
 /**
  * A first guess at what the audio is. Length decides most of it: beds run long, effects short. Long audio is voice
- * when its envelope moves at syllable rate without a beat; short audio is voice when it also holds its level.
+ * when its envelope moves at syllable rate without a beat; short audio also holds its level. Both need a voice pitch.
  */
 export function classify(signal) {
     const features = kindFeatures(signal);
     const { duration, regularity, syllables, sustain } = features;
     const speechLike = syllables >= 0.35 && regularity < 0.35;
+    const voiced = () => (features.voiced ??= round(voicedShare(signal.channels, signal.sampleRate)));
+    const pitched = () => voiced() >= VOICED_SPEECH;
     if (duration >= 8) {
         if (sustain < 0.4)
             return { value: "sfx", confidence: 0.6, features };
-        if (speechLike)
+        if (speechLike && pitched())
             return { value: "voice", confidence: round(Math.min(0.9, 0.4 + syllables)), features };
+        if (regularity < 0.2 && syllables >= 0.17 && voiced() >= VOICED_STEADY_SPEECH)
+            return { value: "voice", confidence: 0.6, features };
         return { value: "music", confidence: round(Math.min(0.9, 0.5 + regularity)), features };
     }
-    if (duration >= 1.5 && syllables >= 0.17 && regularity < 0.3 && sustain >= 0.7)
+    if (duration >= 1.5 && syllables >= 0.17 && regularity < 0.3 && sustain >= 0.7 && pitched())
         return { value: "voice", confidence: speechLike ? 0.8 : 0.6, features };
     return { value: "sfx", confidence: duration <= 2 ? 0.85 : 0.65, features };
 }
 export * from "./audioAnalysisLadder.js";
+export * from "./audioPitch.js";
 export * from "./audioRhythm.js";
 export * from "./audioSections.js";
 export * from "./audioSnap.js";

package/dist/audioPitch.d.ts

@@ -0,0 +1,12 @@
+/** The rate pitch is tracked at: 8 kHz keeps the 70–500 Hz search cheap. */
+export declare const PITCH_RATE = 8000;
+export interface PitchPoint {
+    t: number;
+    hz: number;
+}
+/** The fundamental of each voiced 40 ms frame of 8 kHz mono, by YIN's cumulative mean normalized difference. */
+export declare function pitchTrack(pcm: Float32Array): PitchPoint[];
+/** Mono at {@link PITCH_RATE}: channels averaged, a box filter as wide as the step against aliasing, then sampled. */
+export declare function atPitchRate(channels: readonly Float32Array[], sampleRate: number): Float32Array;
+/** The share of 40 ms frames with a fundamental in the voice range; hits, whooshes and noise have none. */
+export declare function voicedShare(channels: readonly Float32Array[], sampleRate: number): number;

package/dist/audioPitch.js

@@ -0,0 +1,91 @@
+/** The rate pitch is tracked at: 8 kHz keeps the 70–500 Hz search cheap. */
+export const PITCH_RATE = 8000;
+const FRAME = 320;
+const HOP = 320;
+const LOW_HZ = 70;
+const HIGH_HZ = 500;
+const VOICED_DB = -35;
+const PERIODIC = 0.15;
+const MIN_LAG = Math.floor(PITCH_RATE / HIGH_HZ);
+const MAX_LAG = Math.ceil(PITCH_RATE / LOW_HZ);
+function voiced(channels, start) {
+    let energy = 0;
+    for (const pcm of channels)
+        for (let i = 0; i < FRAME; i++)
+            energy += pcm[start + i] ** 2;
+    return 10 * Math.log10(energy / (FRAME * channels.length) + 1e-12) >= VOICED_DB;
+}
+function difference(channels, start, tau) {
+    let sum = 0;
+    for (const pcm of channels) {
+        for (let i = 0; i < FRAME; i++) {
+            const delta = pcm[start + i] - pcm[start + i + tau];
+            sum += delta * delta;
+        }
+    }
+    return sum;
+}
+/** The first lag whose normalized difference dips under the threshold, followed down to its minimum; -1 if none. */
+function periodOf(channels, start, d) {
+    let running = 0;
+    let lag = -1;
+    for (let tau = 1; tau <= MAX_LAG; tau++) {
+        const sum = difference(channels, start, tau);
+        running += sum;
+        d[tau] = running > 0 ? (sum * tau) / running : 1;
+        if (lag === -1) {
+            if (tau >= MIN_LAG && d[tau] < PERIODIC)
+                lag = tau;
+        }
+        else if (d[tau] > d[tau - 1])
+            break;
+        else if (d[tau] < d[lag])
+            lag = tau;
+    }
+    return lag;
+}
+/** The fundamental of each voiced 40 ms frame of 8 kHz mono, by YIN's cumulative mean normalized difference. */
+export function pitchTrack(pcm) {
+    return channelPitchTrack([pcm]);
+}
+function channelPitchTrack(channels) {
+    const length = channels[0]?.length ?? 0;
+    const out = [];
+    const d = new Float64Array(MAX_LAG + 1);
+    for (let start = 0; start + FRAME + MAX_LAG <= length; start += HOP) {
+        if (!voiced(channels, start))
+            continue;
+        const lag = periodOf(channels, start, d);
+        if (lag > 0)
+            out.push({ t: (start + FRAME / 2) / PITCH_RATE, hz: PITCH_RATE / lag });
+    }
+    return out;
+}
+/** Mono at {@link PITCH_RATE}: channels averaged, a box filter as wide as the step against aliasing, then sampled. */
+export function atPitchRate(channels, sampleRate) {
+    const length = channels[0]?.length ?? 0;
+    if (!length || !channels.length)
+        return new Float32Array(0);
+    const step = sampleRate / PITCH_RATE;
+    const width = Math.max(1, Math.round(step));
+    const sums = new Float64Array(length + 1);
+    for (let i = 0; i < length; i++) {
+        let mixed = 0;
+        for (const channel of channels)
+            mixed += channel[i];
+        sums[i + 1] = sums[i] + mixed / channels.length;
+    }
+    const out = new Float32Array(Math.floor(length / step));
+    for (let n = 0; n < out.length; n++) {
+        const from = Math.floor(n * step);
+        const to = Math.min(length, from + width);
+        out[n] = (sums[to] - sums[from]) / (to - from);
+    }
+    return out;
+}
+/** The share of 40 ms frames with a fundamental in the voice range; hits, whooshes and noise have none. */
+export function voicedShare(channels, sampleRate) {
+    const pitched = channels.map((channel) => atPitchRate([channel], sampleRate));
+    const frames = Math.floor((pitched[0]?.length ?? 0) / HOP);
+    return frames ? channelPitchTrack(pitched).length / frames : 0;
+}

package/dist/colorGradingBake.d.ts

@@ -0,0 +1,14 @@
+import { type HfColorGrading, type ResolvedHfColorGrading } from "./colorGrading.js";
+import { type CubeLut3D } from "./colorLuts.js";
+export interface BakeHfColorGradingCubeOptions {
+    /** Points per axis. ffmpeg's lut3d reads 2 to 256. */
+    size?: number;
+    /** The parsed output LUT, required when the grading names one. */
+    lut?: CubeLut3D | null;
+}
+/**
+ * Bakes a colour grade into a `.cube` 3D LUT (red varying fastest) that matches the runtime's
+ * shader, for applying the grade outside a browser, e.g. with ffmpeg's lut3d. Throws for a grade
+ * with spatial stages (grain, vignette, blur, halftone and the other effects), which no LUT holds.
+ */
+export declare function bakeHfColorGradingCube(grading: HfColorGrading | ResolvedHfColorGrading, options?: BakeHfColorGradingCubeOptions): string;

package/dist/colorGradingBake.js

@@ -0,0 +1,299 @@
+import { calculateHfColorGradingSecondaryMask, hasHfColorGradingHueCurveValues, hasHfColorGradingRgbCurveValues, hasHfColorGradingSecondaryValues, HF_COLOR_GRADING_ACTIVE_EFFECT_KEYS, normalizeHfColorGrading, } from "./colorGrading.js";
+import { compileHfColorCurve, compileHfHueCurve, HF_COLOR_CURVE_LUT_SIZE, } from "./colorGradingCurves.js";
+import { packCubeLutToRgba8, unitFloatToByte } from "./colorLuts.js";
+const LUMA_WEIGHTS = [0.2126, 0.7152, 0.0722];
+const CURVE_MAX_INDEX = HF_COLOR_CURVE_LUT_SIZE - 1;
+const luma = (c) => c[0] * LUMA_WEIGHTS[0] + c[1] * LUMA_WEIGHTS[1] + c[2] * LUMA_WEIGHTS[2];
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const clampRgb = (c) => [clamp(c[0], 0, 1), clamp(c[1], 0, 1), clamp(c[2], 0, 1)];
+const fract = (value) => value - Math.floor(value);
+const mod = (value, divisor) => value - divisor * Math.floor(value / divisor);
+const mix = (a, b, t) => a + (b - a) * t;
+const mixRgb = (a, b, t) => [
+    mix(a[0], b[0], t),
+    mix(a[1], b[1], t),
+    mix(a[2], b[2], t),
+];
+const smoothstep = (edge0, edge1, value) => {
+    const t = clamp((value - edge0) / (edge1 - edge0), 0, 1);
+    return t * t * (3 - 2 * t);
+};
+const towardLuma = (c, base, amount) => [
+    mix(base, c[0], amount),
+    mix(base, c[1], amount),
+    mix(base, c[2], amount),
+];
+/**
+ * A value as the shader reads it back from an 8-bit texture channel. The runtime stages texture
+ * data in a Float32Array first, which moves rounding ties: 0.9 packs as 229, not 230.
+ */
+const texel = (value) => unitFloatToByte(Math.fround(value)) / 255;
+/** The runtime's encoding of a signed value into an 8-bit channel. */
+const signedUnit = (value, range) => Math.min(1, Math.max(1 / 255, (value * (127 / range) + 128) / 255));
+const decodeSigned = (value) => (value * 255 - 128) / 127;
+const signedTexel = (value, range) => decodeSigned(texel(signedUnit(value, range)));
+function rgbToHsv(c) {
+    const maximum = Math.max(c[0], c[1], c[2]);
+    const minimum = Math.min(c[0], c[1], c[2]);
+    const delta = maximum - minimum;
+    let hue = 0;
+    if (delta > 0.00001) {
+        if (maximum === c[0])
+            hue = mod((c[1] - c[2]) / delta, 6);
+        else if (maximum === c[1])
+            hue = (c[2] - c[0]) / delta + 2;
+        else
+            hue = (c[0] - c[1]) / delta + 4;
+        hue = fract(hue / 6);
+    }
+    return [hue, maximum > 0.00001 ? delta / maximum : 0, maximum];
+}
+function hsvToRgb([hue, saturation, value]) {
+    const channel = (offset) => {
+        const band = Math.abs(fract(hue + offset) * 6 - 3);
+        return value * mix(1, clamp(band - 1, 0, 1), saturation);
+    };
+    return [channel(0), channel(0.6666667), channel(0.3333333)];
+}
+function applyPrimaryGrade(input, adjust) {
+    const gain = 2 ** adjust.exposure;
+    let c = [input[0] * gain, input[1] * gain, input[2] * gain];
+    const y = luma(c);
+    const lift = adjust.shadows * 0.35 * (1 - smoothstep(0, 0.65, y)) +
+        adjust.highlights * 0.35 * smoothstep(0.35, 1, y);
+    const blackPoint = clamp(adjust.blacks * 0.18, -0.18, 0.18);
+    const whitePoint = clamp(1 - adjust.whites * 0.18, 0.82, 1.18);
+    const range = Math.max(whitePoint - blackPoint, 0.2);
+    c = c.map((value) => (value + lift - blackPoint) / range);
+    c[0] += adjust.temperature * 0.08 + adjust.tint * 0.04;
+    c[2] -= adjust.temperature * 0.08 - adjust.tint * 0.04;
+    c[1] -= adjust.tint * 0.08;
+    const contrast = Math.max(0, 1 + adjust.contrast);
+    c = c.map((value) => (value - 0.5) * contrast + 0.5);
+    const satLuma = luma(c);
+    const currentSat = clamp(Math.max(...c) - Math.min(...c), 0, 1);
+    const skinLike = smoothstep(0.02, 0.18, c[0] - c[1]) *
+        smoothstep(0, 0.16, c[1] - c[2]) *
+        smoothstep(0.18, 0.82, satLuma);
+    const vibranceWeight = (1 - currentSat * 0.72) * mix(1, 0.55, skinLike);
+    c = towardLuma(c, satLuma, Math.max(0, 1 + adjust.vibrance * vibranceWeight));
+    return towardLuma(c, satLuma, Math.max(0, 1 + adjust.saturation));
+}
+function wheelDirection(hue) {
+    const direction = hsvToRgb([fract(hue), 1, 1]);
+    const y = luma(direction);
+    const centred = direction.map((value) => value - y);
+    const scale = Math.max(Math.abs(centred[0]), Math.abs(centred[1]), Math.abs(centred[2]), 0.0001);
+    return centred.map((value) => value / scale);
+}
+function applyTonalWheels(color, wheels) {
+    const y = luma(color);
+    const shadows = 1 - smoothstep(0, 0.6, y);
+    const highlights = smoothstep(0.4, 1, y);
+    const midtones = Math.max(0, 1 - shadows - highlights);
+    const total = Math.max(shadows + midtones + highlights, 0.0001);
+    const c = [...color];
+    for (const [wheel, weight] of [
+        [wheels.shadows, shadows / total],
+        [wheels.midtones, midtones / total],
+        [wheels.highlights, highlights / total],
+    ]) {
+        const direction = wheelDirection(wheel.hue / 360);
+        for (let channel = 0; channel < 3; channel += 1) {
+            c[channel] =
+                (c[channel] ?? 0) +
+                    (direction[channel] ?? 0) * wheel.amount * weight * 0.18 +
+                    wheel.level * weight * 0.25;
+        }
+    }
+    return c;
+}
+function quantisedCurve(samples) {
+    return Float64Array.from(samples, texel);
+}
+function sampleCurve(samples, coordinate) {
+    const position = clamp(coordinate, 0, 1) * CURVE_MAX_INDEX;
+    const lower = Math.floor(position);
+    const upper = Math.min(lower + 1, CURVE_MAX_INDEX);
+    return mix(samples[lower] ?? 0, samples[upper] ?? 0, position - lower);
+}
+function applyRgbCurves(c, curves) {
+    return [
+        sampleCurve(curves.red, sampleCurve(curves.master, c[0])),
+        sampleCurve(curves.green, sampleCurve(curves.master, c[1])),
+        sampleCurve(curves.blue, sampleCurve(curves.master, c[2])),
+    ];
+}
+function signedHueCurve(points, outputMin, outputMax) {
+    const samples = points.length >= 3
+        ? compileHfHueCurve(points, outputMin, outputMax)
+        : new Float32Array(HF_COLOR_CURVE_LUT_SIZE);
+    return Float64Array.from(samples, (value) => signedTexel(value, outputMax));
+}
+function sampleHueCurve(samples, hue) {
+    const position = fract(hue) * HF_COLOR_CURVE_LUT_SIZE;
+    const lower = Math.floor(position);
+    const upper = (lower + 1) % HF_COLOR_CURVE_LUT_SIZE;
+    return mix(samples[lower] ?? 0, samples[upper] ?? 0, position - lower);
+}
+function applyHueCurves(c, curves) {
+    const hsv = rgbToHsv(clampRgb(c));
+    const originalLuma = luma(c);
+    const hueShift = sampleHueCurve(curves.hue, hsv[0]);
+    const saturation = sampleHueCurve(curves.saturation, hsv[0]);
+    const lumaShift = sampleHueCurve(curves.luma, hsv[0]);
+    const shifted = hsvToRgb([
+        fract(hsv[0] + hueShift * 0.5),
+        clamp(hsv[1] * Math.max(0, 1 + saturation), 0, 1),
+        hsv[2],
+    ]);
+    const offset = originalLuma - luma(shifted) + lumaShift;
+    return shifted.map((value) => value + offset);
+}
+function quantisedSecondary({ key, correction, }) {
+    const range = (soft) => ({
+        min: texel(soft.min),
+        max: texel(soft.max),
+        softness: texel(soft.softness / 0.5) * 0.5,
+    });
+    return {
+        key: {
+            hue: {
+                center: texel(key.hue.center / 360) * 360,
+                range: texel(key.hue.range / 180) * 180,
+                softness: texel(key.hue.softness / 180) * 180,
+            },
+            saturation: range(key.saturation),
+            luma: range(key.luma),
+        },
+        hueShift: signedTexel(correction.hueShift, 180),
+        saturation: signedTexel(correction.saturation, 1),
+        luma: signedTexel(correction.luma, 1),
+        temperature: signedTexel(correction.temperature, 1),
+        tint: signedTexel(correction.tint, 1),
+    };
+}
+function applySecondary(c, secondary) {
+    const hsv = rgbToHsv(clampRgb(c));
+    const mask = calculateHfColorGradingSecondaryMask(hsv[0] * 360, hsv[1], luma(c), secondary.key);
+    if (mask <= 0)
+        return c;
+    const rotated = hsvToRgb([fract(hsv[0] + secondary.hueShift * 0.5), hsv[1], hsv[2]]);
+    const corrected = towardLuma(rotated, luma(rotated), Math.max(0, 1 + secondary.saturation)).map((value) => value + secondary.luma);
+    corrected[0] += secondary.temperature * 0.08 + secondary.tint * 0.04;
+    corrected[2] -= secondary.temperature * 0.08 - secondary.tint * 0.04;
+    corrected[1] -= secondary.tint * 0.08;
+    return mixRgb(c, corrected, mask);
+}
+function sampleLut(lut, r, g, b) {
+    const index = (g * lut.width + b * lut.size + r) * 4;
+    return [
+        (lut.data[index] ?? 0) / 255,
+        (lut.data[index + 1] ?? 0) / 255,
+        (lut.data[index + 2] ?? 0) / 255,
+    ];
+}
+function applyLut(color, lut) {
+    const top = lut.size - 1;
+    const scaled = color.map((value, channel) => clamp((value - (lut.domainMin[channel] ?? 0)) / (lut.span[channel] ?? 1), 0, 1) * top);
+    const lo = scaled.map(Math.floor);
+    const hi = lo.map((value) => Math.min(value + 1, top));
+    const f = scaled.map((value, channel) => value - (lo[channel] ?? 0));
+    const c00 = mixRgb(sampleLut(lut, lo[0], lo[1], lo[2]), sampleLut(lut, hi[0], lo[1], lo[2]), f[0]);
+    const c10 = mixRgb(sampleLut(lut, lo[0], hi[1], lo[2]), sampleLut(lut, hi[0], hi[1], lo[2]), f[0]);
+    const c01 = mixRgb(sampleLut(lut, lo[0], lo[1], hi[2]), sampleLut(lut, hi[0], lo[1], hi[2]), f[0]);
+    const c11 = mixRgb(sampleLut(lut, lo[0], hi[1], hi[2]), sampleLut(lut, hi[0], hi[1], hi[2]), f[0]);
+    const lutColor = mixRgb(mixRgb(c00, c10, f[1]), mixRgb(c01, c11, f[1]), f[2]);
+    return mixRgb(color, lutColor, clamp(lut.intensity, 0, 1));
+}
+function spatialStages(grading) {
+    const details = ["vignette", "grain"]
+        .filter((key) => Math.abs(grading.details[key]) > 0.0001)
+        .map((key) => `details.${key}`);
+    const effects = HF_COLOR_GRADING_ACTIVE_EFFECT_KEYS.filter((key) => Math.abs(grading.effects[key]) > 0.0001).map((key) => `effects.${key}`);
+    return [...details, ...effects];
+}
+function compileLut(grading, lut) {
+    if (!grading.lut || grading.lut.intensity === 0)
+        return null;
+    if (!lut) {
+        throw new Error(`The grading applies the LUT ${grading.lut.src}; pass its parsed .cube as options.lut to bake it.`);
+    }
+    const packed = packCubeLutToRgba8(lut);
+    return {
+        size: Math.max(lut.size, 2),
+        width: packed.width,
+        data: packed.data,
+        domainMin: [...lut.domainMin],
+        span: lut.domainMax.map((max, channel) => Math.max(max - (lut.domainMin[channel] ?? 0), 0.00001)),
+        intensity: grading.lut.intensity ?? 0,
+    };
+}
+function compileGrade(grading, lut) {
+    const spatial = spatialStages(grading);
+    if (spatial.length > 0) {
+        throw new Error(`A 3D LUT holds only colour; this grading also has spatial stages: ${spatial.join(", ")}.`);
+    }
+    const { curves, hueCurves, secondaries } = grading;
+    return {
+        grading,
+        curves: hasHfColorGradingRgbCurveValues(curves)
+            ? {
+                red: quantisedCurve(compileHfColorCurve(curves.red)),
+                green: quantisedCurve(compileHfColorCurve(curves.green)),
+                blue: quantisedCurve(compileHfColorCurve(curves.blue)),
+                master: quantisedCurve(compileHfColorCurve(curves.master)),
+            }
+            : null,
+        hueCurves: hasHfColorGradingHueCurveValues(hueCurves)
+            ? {
+                hue: signedHueCurve(hueCurves.hueVsHue, -180, 180),
+                saturation: signedHueCurve(hueCurves.hueVsSaturation, -1, 1),
+                luma: signedHueCurve(hueCurves.hueVsLuma, -1, 1),
+            }
+            : null,
+        secondaries: hasHfColorGradingSecondaryValues(secondaries)
+            ? secondaries.filter((secondary) => secondary.enabled).map(quantisedSecondary)
+            : [],
+        lut: compileLut(grading, lut),
+    };
+}
+function gradeColor(input, grade) {
+    let c = applyPrimaryGrade(input, grade.grading.adjust);
+    c = applyTonalWheels(c, grade.grading.wheels);
+    if (grade.curves)
+        c = applyRgbCurves(c, grade.curves);
+    if (grade.hueCurves)
+        c = applyHueCurves(c, grade.hueCurves);
+    for (const secondary of grade.secondaries)
+        c = applySecondary(c, secondary);
+    c = clampRgb(c);
+    if (grade.lut)
+        c = clampRgb(applyLut(c, grade.lut));
+    return clampRgb(mixRgb(input, c, grade.grading.intensity));
+}
+/**
+ * Bakes a colour grade into a `.cube` 3D LUT (red varying fastest) that matches the runtime's
+ * shader, for applying the grade outside a browser, e.g. with ffmpeg's lut3d. Throws for a grade
+ * with spatial stages (grain, vignette, blur, halftone and the other effects), which no LUT holds.
+ */
+export function bakeHfColorGradingCube(grading, options = {}) {
+    const size = options.size ?? 33;
+    if (!Number.isInteger(size) || size < 2 || size > 256) {
+        throw new RangeError(`A .cube size must be a whole number from 2 to 256, not ${size}.`);
+    }
+    const resolved = normalizeHfColorGrading(grading);
+    const grade = resolved ? compileGrade(resolved, options.lut) : null;
+    const step = size - 1;
+    const lines = [`LUT_3D_SIZE ${size}`, "DOMAIN_MIN 0 0 0", "DOMAIN_MAX 1 1 1"];
+    for (let b = 0; b < size; b += 1) {
+        for (let g = 0; g < size; g += 1) {
+            for (let r = 0; r < size; r += 1) {
+                const input = [r / step, g / step, b / step];
+                const output = grade ? gradeColor(input, grade) : input;
+                lines.push(output.map((value) => value.toFixed(6)).join(" "));
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/colorGroups.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Grade groups: one colour grade for a whole lane. An inert `<hf-color-group>`
+ * holds the grade in `data-color-grading`; each `<video>`, `<img>` or `<canvas>`
+ * joins with `data-color-group` naming the group's id. Membership is held by the
+ * member, as with audio groups, so a camera cut into hundreds of clips is graded
+ * by editing one attribute.
+ */
+export declare const HF_COLOR_GROUP_TAG = "hf-color-group";
+export declare const HF_COLOR_GROUP_ATTR = "data-color-group";
+type GroupLookupRoot = Pick<Document, "getElementById"> | null | undefined;
+/**
+ * The group a gradable element belongs to, or null. `data-color-group=""` is no
+ * group. Tolerant of partial `Element` doubles, as `audioGroupOf` is.
+ */
+export declare function colorGroupOf(el: Element): string | null;
+/**
+ * The `<hf-color-group>` for an id, or null. Tag-checked so an unrelated
+ * element sharing the id is never read as a lane's grade.
+ */
+export declare function resolveColorGroupElement(root: GroupLookupRoot, groupId: string): Element | null;
+/**
+ * The grade that applies to `el`: its own `data-color-grading` when present,
+ * else its group element's, else null. A group id with no element is ungrouped.
+ */
+export declare function effectiveColorGrading(el: Element, root: GroupLookupRoot): string | null;
+/**
+ * Make `<hf-color-group>` inert, once per document: an unknown custom element
+ * still makes a box, and a grade must not shift authored layout. `contents`, so
+ * anything nested inside one still renders; `!important` because an author rule
+ * can outrank a bare type selector.
+ */
+export declare function ensureColorGroupInertStyle(doc: Document): void;
+export {};

package/dist/colorGroups.js

@@ -0,0 +1,59 @@
+/**
+ * Grade groups: one colour grade for a whole lane. An inert `<hf-color-group>`
+ * holds the grade in `data-color-grading`; each `<video>`, `<img>` or `<canvas>`
+ * joins with `data-color-group` naming the group's id. Membership is held by the
+ * member, as with audio groups, so a camera cut into hundreds of clips is graded
+ * by editing one attribute.
+ */
+import { COLOR_GROUP_ATTR, COLOR_GROUP_TAG } from "@hyperframes/parsers/color-grading-contract";
+import { HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_SOURCE_TAGS } from "./colorGrading.js";
+export const HF_COLOR_GROUP_TAG = COLOR_GROUP_TAG;
+export const HF_COLOR_GROUP_ATTR = COLOR_GROUP_ATTR;
+/**
+ * The group a gradable element belongs to, or null. `data-color-group=""` is no
+ * group. Tolerant of partial `Element` doubles, as `audioGroupOf` is.
+ */
+export function colorGroupOf(el) {
+    if (typeof el.tagName !== "string" || typeof el.getAttribute !== "function")
+        return null;
+    if (!HF_COLOR_GRADING_SOURCE_TAGS.includes(el.tagName.toLowerCase())) {
+        return null;
+    }
+    return el.getAttribute(HF_COLOR_GROUP_ATTR) || null;
+}
+/**
+ * The `<hf-color-group>` for an id, or null. Tag-checked so an unrelated
+ * element sharing the id is never read as a lane's grade.
+ */
+export function resolveColorGroupElement(root, groupId) {
+    const el = root?.getElementById(groupId) ?? null;
+    return el?.tagName.toLowerCase() === HF_COLOR_GROUP_TAG ? el : null;
+}
+/**
+ * The grade that applies to `el`: its own `data-color-grading` when present,
+ * else its group element's, else null. A group id with no element is ungrouped.
+ */
+export function effectiveColorGrading(el, root) {
+    const own = el.getAttribute(HF_COLOR_GRADING_ATTR);
+    if (own !== null)
+        return own;
+    const groupId = colorGroupOf(el);
+    if (!groupId)
+        return null;
+    return resolveColorGroupElement(root, groupId)?.getAttribute(HF_COLOR_GRADING_ATTR) ?? null;
+}
+/**
+ * Make `<hf-color-group>` inert, once per document: an unknown custom element
+ * still makes a box, and a grade must not shift authored layout. `contents`, so
+ * anything nested inside one still renders; `!important` because an author rule
+ * can outrank a bare type selector.
+ */
+export function ensureColorGroupInertStyle(doc) {
+    const styleId = "__hf-color-group-inert";
+    if (!doc?.head || doc.getElementById(styleId))
+        return;
+    const style = doc.createElement("style");
+    style.id = styleId;
+    style.textContent = `${HF_COLOR_GROUP_TAG}{display:contents!important}`;
+    doc.head.appendChild(style);
+}

package/dist/compiler/htmlBundler.js

@@ -888,7 +888,11 @@ async function bundleProject(projectDir, options) {
     const rawHtml = readSource(mountedShell ?? entryHtml);
     const compiled = await compileHtml(rawHtml, sourceDir, options?.probeMediaDuration);
     if (options?.staticGuard !== false && !mountedShell) {
-        const staticGuard = await validateHyperframeHtmlContract(compiled);
+        const entryRel = relative(projectDir, indexPath).replace(/\\/g, "/");
+        const staticGuard = await validateHyperframeHtmlContract(compiled, {
+            dir: projectDir,
+            ...(entryRel !== "index.html" && { compSrcPath: entryRel }),
+        });
         if (!staticGuard.isValid) {
             console.warn(`[StaticGuard] Invalid HyperFrame contract: ${staticGuard.missingKeys.join("; ")}`);
         }

package/dist/compiler/staticGuard.d.ts

@@ -4,4 +4,7 @@ export type HyperframeStaticGuardResult = {
     missingKeys: string[];
     failureReason: HyperframeStaticFailureReason | null;
 };
-export declare function validateHyperframeHtmlContract(html: string): Promise<HyperframeStaticGuardResult>;
+export declare function validateHyperframeHtmlContract(html: string, project?: {
+    dir: string;
+    compSrcPath?: string;
+}): Promise<HyperframeStaticGuardResult>;

package/dist/compiler/staticGuard.js

@@ -1,6 +1,8 @@
-import { lintHyperframeHtml } from "@hyperframes/lint";
-export async function validateHyperframeHtmlContract(html) {
-    const result = await lintHyperframeHtml(html);
+import { collectExternalStyles, lintHyperframeHtml } from "@hyperframes/lint";
+export async function validateHyperframeHtmlContract(html, project) {
+    const result = await lintHyperframeHtml(html, project && {
+        externalStyles: collectExternalStyles(project.dir, html, project.compSrcPath),
+    });
     const missingKeys = result.findings
         .filter((finding) => finding.severity === "error")
         .map((finding) => finding.message);

package/dist/fonts/deterministicFonts.d.ts

@@ -36,7 +36,7 @@ export declare function parseFontFamilyValue(value: string): string[];
  */
 export declare function normalizeSystemFontPrimaryFamilies(html: string, deterministicPrimary?: string): string;
 /** Surfaces font-family is declared on in served HTML. */
-export type FontFamilySurface = "font-family" | "data-font-family";
+export type FontFamilySurface = "font-family" | "font" | "data-font-family";
 export type FontFamilyDeclaration = {
     surface: FontFamilySurface;
     declaration: string;

package/dist/fonts/deterministicFonts.js

@@ -213,16 +213,30 @@ function collectCssCustomProperties(css, customProperties) {
         customProperties.set(decl.prop, decl.value);
     });
 }
+const FONT_SIZE_KEYWORD = /^(?:xx-small|x-small|small|medium|large|x-large|xx-large|xxx-large|smaller|larger)$/i;
+const FONT_SIZE_TOKEN = /^(?:\d*\.?\d+[a-z%]+|(?:calc|min|max|clamp|var)\(.*\))(?:\/\S+)?$/i;
+function fontShorthandFamilies(value) {
+    for (const token of value.matchAll(/(?:[^\s(]|\([^)]*\))+/g)) {
+        const size = token[0].split("/")[0] ?? "";
+        if (FONT_SIZE_KEYWORD.test(size) || FONT_SIZE_TOKEN.test(token[0])) {
+            return value.slice(token.index + token[0].length).trim();
+        }
+    }
+    return "";
+}
 function* iterateCssRootFontFamilyDeclarations(root) {
     const declarations = [];
     root.walkDecls((decl) => {
-        if (decl.prop.toLowerCase() !== "font-family")
+        const prop = decl.prop.toLowerCase();
+        if (prop !== "font-family" && prop !== "font")
             return;
         if (isFontFaceDeclaration(decl))
             return;
-        const declaration = decl.value;
+        const declaration = prop === "font" ? fontShorthandFamilies(decl.value) : decl.value;
+        if (!declaration)
+            return;
         declarations.push({
-            surface: "font-family",
+            surface: prop,
             declaration,
             families: parseFontFamilyValue(declaration),
         });
@@ -230,7 +244,7 @@ function* iterateCssRootFontFamilyDeclarations(root) {
     yield* declarations;
 }
 function* iterateCssFontFamilyDeclarations(css) {
-    if (!/font-family/i.test(css))
+    if (!/font(?:-family)?\s*:/i.test(css))
         return;
     const root = parseCssRoot(css);
     if (!root)