@kieransimkin/dancemoves 3.2.0 → 3.3.0

package/lib/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   createPlaybackPublisher: () => createPlaybackPublisher,
   createPlaybackReceiver: () => createPlaybackReceiver,
   fromWordPressMeta: () => fromWordPressMeta,
+  validateBeatAlignment: () => validateBeatAlignment,
   validatePageConfig: () => validatePageConfig
 });
 module.exports = __toCommonJS(index_exports);
@@ -135,6 +136,38 @@ function install(__dmScope) {
       return ticks;
     }
     var bpm = effectiveBpm(rawConfig.bpm);
+    var bpmSource = ["explicit", "analysis"].indexOf(rawConfig.bpmSource) >= 0 ? rawConfig.bpmSource : "fallback";
+    function beatAlignmentState(audio) {
+      var reading = rawConfig.beatAlignment;
+      if (!reading)
+        return { status: rawConfig.beatAlignmentStatus === "invalid" ? "invalid" : "unconfigured", applied: false };
+      var source = playbackAudio(audio);
+      var identity2 = source && (source.masterSourceUrl || source.masterId || source.currentSrc || source.src);
+      try {
+        if (!identity2 || new URL(String(identity2), document2.baseURI).href !== new URL(reading.source_url).href) {
+          return { status: "source-mismatch", applied: false };
+        }
+      } catch (error) {
+        return { status: "source-mismatch", applied: false };
+      }
+      return {
+        status: reading.phase_status,
+        applied: true,
+        firstBeatSeconds: reading.first_beat_seconds,
+        offsetPips: reading.offset_pips,
+        sourceSha256: reading.source_sha256,
+        bpmStatus: reading.bpm_status
+      };
+    }
+    function rhythmicTime(audio) {
+      var source = playbackAudio(audio);
+      var seconds = source && Number.isFinite(Number(source.currentTime)) ? Number(source.currentTime) : 0;
+      var state = beatAlignmentState(source);
+      return seconds - (state.applied ? state.firstBeatSeconds : 0);
+    }
+    function sourceTick(audio, bpmOverride) {
+      return rhythmicTime(audio) * effectiveBpm(bpmOverride || bpm) * TICKS_PER_BEAT / 60;
+    }
     function durationMilliseconds(ticks, bpmOverride) {
       return 3750 / effectiveBpm(bpmOverride || bpm) * quantizeTicks(ticks);
     }
@@ -142,7 +175,7 @@ function install(__dmScope) {
       var settings = options || {};
       var audio = playbackAudio(settings.audio) || (settings.clock === "audio" ? activeAudio : null);
       if (audio && !audio.paused && !audio.ended && Number.isFinite(Number(audio.currentTime))) {
-        return Number(audio.currentTime) * effectiveBpm(settings.bpm || bpm) * TICKS_PER_BEAT / 60;
+        return sourceTick(audio, settings.bpm);
       }
       var now = window2.performance && typeof window2.performance.now === "function" ? window2.performance.now() : Date.now();
       return Math.max(0, now - pageClockStarted) * effectiveBpm(settings.bpm || bpm) * TICKS_PER_BEAT / 6e4;
@@ -441,7 +474,7 @@ function install(__dmScope) {
         __dmScope.dataset(document2.documentElement, "danceMovesSharedControls", null);
       }
       __dmScope.dataset(document2.documentElement, "danceMovesBpm", String(bpm));
-      __dmScope.dataset(document2.documentElement, "danceMovesBpmSource", rawConfig.bpmSource === "explicit" ? "explicit" : "fallback");
+      __dmScope.dataset(document2.documentElement, "danceMovesBpmSource", bpmSource);
       __dmScope.dataset(document2.documentElement, "danceMovesVersion", String(rawConfig.version || ""));
     }
     function registerAnimationScope(root, selectors) {
@@ -977,7 +1010,7 @@ function install(__dmScope) {
       var root = document2.querySelector(".ks-epk");
       if (root) {
         __dmScope.dataset(root, "danceMovesBpm", String(bpm));
-        __dmScope.dataset(root, "danceMovesBpmSource", rawConfig.bpmSource === "explicit" ? "explicit" : "fallback");
+        __dmScope.dataset(root, "danceMovesBpmSource", bpmSource);
         if (rawConfig.lyricTimingUrl)
           __dmScope.dataset(root, "danceMovesLyricTiming", String(rawConfig.lyricTimingUrl));
         if (rawConfig.cueTimingUrl)
@@ -1006,11 +1039,14 @@ function install(__dmScope) {
     var api = {
       version: String(rawConfig.version || ""),
       bpm,
-      bpmSource: rawConfig.bpmSource === "explicit" ? "explicit" : "fallback",
+      bpmSource,
       ticksPerBeat: TICKS_PER_BEAT,
       quantizeTicks,
       durationMilliseconds,
       currentTick,
+      sourceTick,
+      rhythmicTime,
+      beatAlignmentState,
       nextIntervalTick,
       scheduleAtInterval,
       deferStart,
@@ -1217,7 +1253,8 @@ function install2(__dmScope) {
       function sync() {
         var rate = Math.max(0.01, finite3(audio.playbackRate, 1));
         var duration = motion.durationMilliseconds(ticks) / 1e3 / rate;
-        var phase = -(finite3(audio.currentTime, 0) / rate % duration);
+        var rhythmicSeconds = motion.rhythmicTime ? motion.rhythmicTime(audio) : finite3(audio.currentTime, 0);
+        var phase = -((rhythmicSeconds / rate % duration + duration) % duration);
         __dmScope.setStyle(state.root.style, prefix + "-duration", duration.toFixed(6) + "s");
         __dmScope.setStyle(state.root.style, prefix + "-delay", phase.toFixed(6) + "s");
         __dmScope.dataset(state.root, "danceMovesPulse", state.reduced.matches || state.forced.matches ? "inactive" : audio.paused ? "paused" : "playing");
@@ -1509,7 +1546,8 @@ function install2(__dmScope) {
       function calculate(reason, staticFallback) {
         var cycleSeconds = Math.max(1e-3, finite3(motion.durationMilliseconds(cycleTicks), 1) / 1e3);
         var time = Math.max(0, finite3(audio.currentTime, 0));
-        var phase = ((time - phaseOffsetSeconds) % cycleSeconds + cycleSeconds) % cycleSeconds / cycleSeconds;
+        var rhythmicSeconds = motion.rhythmicTime ? motion.rhythmicTime(audio) : time;
+        var phase = ((rhythmicSeconds - phaseOffsetSeconds) % cycleSeconds + cycleSeconds) % cycleSeconds / cycleSeconds;
         var localFrame = staticFallback ? staticFrame : Math.min(frameCount - 1, Math.floor(phase * frameCount + 1e-9));
         var mapped = mappedFrame(localFrame);
         return {
@@ -4928,8 +4966,9 @@ function install9(__dmScope) {
           anchor = 0;
         lastClock = mode;
         const tempo = bpm();
-        const beats = useAudio ? Math.max(0, Number.isFinite(audio.currentTime) ? audio.currentTime : 0) * tempo / 60 : motion.currentTick({ clock: "page" }) / 16;
-        return { beats, mode, tempo };
+        const sourceBeats = useAudio ? Math.max(0, Number.isFinite(audio.currentTime) ? audio.currentTime : 0) * tempo / 60 : motion.currentTick({ clock: "page" }) / 16;
+        const beats = useAudio && motion.sourceTick ? motion.sourceTick(audio) / 16 : sourceBeats;
+        return { beats, sourceBeats, mode, tempo };
       }
       function blocked() {
         if (!enabled)
@@ -4967,7 +5006,8 @@ function install9(__dmScope) {
           audio: s.mode === "audio" ? audio : null,
           rudiment: row.name,
           clock: s.mode,
-          sourceBeats: s.beats,
+          sourceBeats: s.sourceBeats,
+          rhythmicBeats: s.beats,
           bpm: s.tempo,
           rate,
           pip: neutral ? null : pip,
@@ -5513,6 +5553,35 @@ function createScope(root, config, { legacyGlobals = false, nonce, orientation =
   return api;
 }
 
+// .build/modules/beat-alignment.mjs
+var hash = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+function rational(value, label) {
+  if (typeof value !== "string" || !/^-?\d{1,80}(?:\/[1-9]\d{0,79})?$/.test(value)) throw new TypeError(`Invalid exact ${label}`);
+  const [n, d = "1"] = value.split("/");
+  return [BigInt(n), BigInt(d)];
+}
+function numeric(value, label, min, max) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) throw new RangeError(`Invalid ${label}`);
+  return value;
+}
+function validateBeatAlignment(input) {
+  if (input === void 0 || input === null || input === "") return null;
+  if (!input || typeof input !== "object" || Array.isArray(input) || input.schema !== "stemlab.beat-alignment.v1" || input.pips_per_beat !== 64 || input.canonical_first_beat_pip !== 0 || !hash(input.source_sha256) || !hash(input.evidence_sha256) || !hash(input.report_sha256)) throw new TypeError("Invalid source-bound StemLab beat alignment");
+  const bpm = numeric(input.bpm, "alignment BPM", 20, 400);
+  const first = numeric(input.first_beat_seconds, "first beat", 0, 86400);
+  const offset = numeric(input.offset_pips, "pip offset", -36864e3, 0);
+  const [bn, bd] = rational(input.exact_bpm, "BPM"), [fn, fd] = rational(input.first_beat_exact_seconds, "first beat"), [pn, pd] = rational(input.exact_offset_pips, "pip offset");
+  if (fn * bn * 64n * pd + pn * fd * bd * 60n !== 0n || bn <= 0n || fn < 0n || Math.abs(Number(bn) / Number(bd) - bpm) > 1e-9 || Math.abs(Number(fn) / Number(fd) - first) > 1e-9 || Math.abs(Number(pn) / Number(pd) - offset) > 1e-7) throw new RangeError("Exact beat alignment and numeric clock disagree");
+  if (!["canonical", "estimated"].includes(input.bpm_status) || !["estimated", "confirmed", "synthetic"].includes(input.phase_status)) throw new TypeError("Alignment authority is required");
+  for (const key of ["analysis_id", "bpm_basis"]) if (typeof input[key] !== "string" || !/^[a-zA-Z0-9_.-]{1,128}$/.test(input[key])) throw new TypeError(`Invalid ${key}`);
+  if (input.source_audio_verified !== true || !input.source_audio || !Number.isSafeInteger(input.source_audio.num_frames) || input.source_audio.num_frames < 1 || !Number.isSafeInteger(input.source_audio.sample_rate) || input.source_audio.sample_rate < 1 || first >= input.source_audio.num_frames / input.source_audio.sample_rate) throw new TypeError("Verified source audio frame bounds are required");
+  const sourceUrl = input.source_url;
+  if (typeof sourceUrl !== "string" || sourceUrl.length > 4096 || /[\u0000-\u001f]/.test(sourceUrl)) throw new TypeError("An exact verified master URL is required");
+  const parsed = new URL(sourceUrl);
+  if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password || parsed.hash) throw new TypeError("Invalid verified master URL");
+  return Object.freeze({ ...input, bpm, first_beat_seconds: first, offset_pips: offset, source_audio: Object.freeze({ ...input.source_audio }) });
+}
+
 // .build/modules/config.mjs
 var PAGE_META_KEYS = Object.freeze({
   bpm: "_dance_moves_bpm",
@@ -5520,7 +5589,9 @@ var PAGE_META_KEYS = Object.freeze({
   cue: "_dance_moves_cue_timing_id",
   popups: "_dance_moves_lyric_popups_enabled",
   duration: "_dance_moves_master_duration_ms",
-  effect: "_dance_moves_effect"
+  effect: "_dance_moves_effect",
+  alignment: "_dance_moves_beat_alignment",
+  alignmentAudio: "_dance_moves_beat_alignment_audio_id"
 });
 var object = (value) => value && typeof value === "object" && !Array.isArray(value);
 function finite(value, name, min, max) {
@@ -5539,7 +5610,11 @@ function url(value, name) {
 function validatePageConfig(input = {}) {
   if (!object(input)) throw new TypeError("Page configuration must be an object");
   const explicit = input.bpm !== void 0 && input.bpm !== null && input.bpm !== "";
-  const bpm = explicit ? Math.round(finite(input.bpm, "bpm", 20, 400) * 1e3) / 1e3 : 120;
+  const beatAlignment = validateBeatAlignment(input.beatAlignment);
+  const canonicalExplicit = explicit && !["fallback", "analysis"].includes(input.bpmSource);
+  if (canonicalExplicit && beatAlignment && Math.abs(input.bpm - beatAlignment.bpm) > 500001e-9) throw new RangeError("Stored BPM and selected beat alignment disagree; select a matching BPM basis");
+  const bpm = beatAlignment ? beatAlignment.bpm : explicit ? Math.round(finite(input.bpm, "bpm", 20, 400) * 1e3) / 1e3 : 120;
+  if (explicit) finite(input.bpm, "bpm", 20, 400);
   const effect = input.effect ?? "";
   if (!["", "paper-planes"].includes(effect)) throw new RangeError("effect must be empty or paper-planes");
   if (input.lyricPopupsEnabled !== void 0 && typeof input.lyricPopupsEnabled !== "boolean") throw new TypeError("lyricPopupsEnabled must be boolean");
@@ -5551,8 +5626,9 @@ function validatePageConfig(input = {}) {
   return Object.freeze({
     pageId,
     bpm,
-    bpmSource: explicit && input.bpmSource !== "fallback" ? "explicit" : "fallback",
+    bpmSource: canonicalExplicit ? "explicit" : beatAlignment ? "analysis" : "fallback",
     fallbackBpm: 120,
+    beatAlignment,
     ticksPerBeat: 16,
     tickDefinition: "sixteenth-of-beat",
     longDurationQuantumTicks: 16,
@@ -5568,9 +5644,9 @@ function validatePageConfig(input = {}) {
 }
 async function fromWordPressMeta(meta, resolveAttachment) {
   if (!object(meta)) throw new TypeError("meta must be an object");
-  const numeric = (value) => value !== "" && value !== null && value !== void 0 && Number.isFinite(Number(value));
+  const numeric2 = (value) => value !== "" && value !== null && value !== void 0 && Number.isFinite(Number(value));
   const b = meta[PAGE_META_KEYS.bpm];
-  const bpm = numeric(b) && Number(b) >= 20 && Number(b) <= 400 ? Number(b) : void 0;
+  const bpm = numeric2(b) && Number(b) >= 20 && Number(b) <= 400 ? Number(b) : void 0;
   const resolve = async (key) => {
     const value = Number(meta[key] || 0);
     if (!Number.isSafeInteger(value)) throw new RangeError("Attachment ID must be a safe integer");
@@ -5580,8 +5656,15 @@ async function fromWordPressMeta(meta, resolveAttachment) {
     return await resolveAttachment(id) || "";
   };
   const duration = Number(meta[PAGE_META_KEYS.duration]);
+  let beatAlignment = meta[PAGE_META_KEYS.alignment] || null;
+  if (typeof beatAlignment === "string") {
+    if (beatAlignment.length > 16384) throw new RangeError("Beat alignment exceeds 16 KiB");
+    beatAlignment = JSON.parse(beatAlignment);
+  }
+  if (beatAlignment) beatAlignment = { ...beatAlignment, source_url: await resolve(PAGE_META_KEYS.alignmentAudio) };
   return validatePageConfig({
     bpm,
+    beatAlignment,
     lyricTimingUrl: await resolve(PAGE_META_KEYS.lyric),
     cueTimingUrl: await resolve(PAGE_META_KEYS.cue),
     lyricPopupsEnabled: meta[PAGE_META_KEYS.popups] === true || String(meta[PAGE_META_KEYS.popups]) === "1",
@@ -6122,7 +6205,8 @@ function installPlayback(scope, api, host = scope.document.defaultView) {
       error: { get: () => read().error || null },
       element: { value: isNative ? master : null },
       activePlayer: { get: () => delegate ? delegate.activePlayer : active.element },
-      masterId: { get: () => delegate ? delegate.masterId : master.currentSrc || master.src || master.id }
+      masterId: { get: () => delegate ? delegate.masterId : master.currentSrc || master.src || master.id },
+      masterSourceUrl: { get: () => delegate ? delegate.masterSourceUrl : reference?.sourceUrl || master.currentSrc || master.src || "" }
     });
     transport.matches = (selector) => target.matches(selector);
     transport.getAttribute = (name) => target.getAttribute(name);
@@ -7038,7 +7122,7 @@ function installChildPlayback(scope, api, host) {
 }
 
 // .build/modules/version.mjs
-var VERSION = "3.2.0";
+var VERSION = "3.3.0";
 
 // .build/modules/index.mjs
 var mounted = /* @__PURE__ */ new WeakMap();

package/lib/index.d.ts

@@ -2,7 +2,7 @@ export * from './rudiments';
 export type Remove = () => void;
 export type PlaybackMedia = HTMLMediaElement | PlaybackSource;
 export interface PlaybackMapping {offset?:number;duration?:number;playerStart?:number}
-export type MasterReference = HTMLMediaElement | Readonly<{id:string;duration:number;element?:HTMLMediaElement}>;
+export type MasterReference = HTMLMediaElement | Readonly<{id:string;duration:number;element?:HTMLMediaElement;sourceUrl?:string}>;
 export interface PlaybackSource extends EventTarget {
  readonly nodeType:1;readonly tagName:string;readonly element:HTMLMediaElement|null;readonly activePlayer:HTMLMediaElement|HTMLIFrameElement|null;
  currentTime:number;readonly duration:number;readonly paused:boolean;readonly ended:boolean;readonly seeking:boolean;readonly playbackRate:number;
@@ -26,8 +26,15 @@ export function createPlaybackPublisher(options:ChildPlaybackPublisherOptions):C
 export function createPlaybackReceiver(options:ChildPlaybackReceiverOptions):ChildPlaybackReceiver;
 export type Offset = Readonly<{x:number;y:number;z?:number}>;
 export type Metadata = string | {id?:string;handlerId?:string};
+export interface BeatAlignment {
+ schema:'stemlab.beat-alignment.v1';source_sha256:string;source_url:string;source_audio_verified:true;
+ source_audio:Readonly<{sample_rate:number;num_frames:number;num_channels?:number;duration_seconds?:number}>;
+ bpm:number;exact_bpm:string;bpm_basis:string;bpm_status:'canonical'|'estimated';phase_status:'estimated'|'confirmed'|'synthetic';
+ analysis_id:string;evidence_sha256:string;report_sha256:string;first_beat_seconds:number;first_beat_exact_seconds:string;
+ offset_pips:number;exact_offset_pips:string;pips_per_beat:64;canonical_first_beat_pip:0;
+}
 export interface PageConfig {
- pageId?:number;bpm?:number|null;bpmSource?:'explicit'|'fallback';lyricTimingUrl?:string;cueTimingUrl?:string;
+ pageId?:number;bpm?:number|null;bpmSource?:'explicit'|'fallback'|'analysis';beatAlignment?:BeatAlignment|null;lyricTimingUrl?:string;cueTimingUrl?:string;
  lyricPopupsEnabled?:boolean;masterDurationMilliseconds?:number;sharedControlTicks?:number;lyricDisclosureTicks?:number;
  effect?:''|'paper-planes';diagnostics?:boolean;
 }
@@ -77,6 +84,8 @@ export interface DanceMoves {
  readonly version:string;readonly bpm:number;readonly bpmSource:string;readonly ticksPerBeat:16;readonly root:HTMLElement;readonly config:Readonly<PageConfig>;
  readonly destroyed:boolean;ready:Promise<DanceMoves>;
  quantizeTicks(value:number):number;durationMilliseconds(ticks:number,bpmOverride?:number):number;currentTick(options?:Clock):number;
+ sourceTick(audio:PlaybackMedia,bpmOverride?:number):number;rhythmicTime(audio:PlaybackMedia):number;
+ beatAlignmentState(audio:PlaybackMedia):Readonly<{status:string;applied:boolean;firstBeatSeconds?:number;offsetPips?:number;sourceSha256?:string;bpmStatus?:string}>;
  nextIntervalTick(interval:number,fromTick:number,strictlyFuture?:boolean):number;
  scheduleAtInterval(interval:number,callback:(detail:IntervalDetail)=>void,options?:Clock):Remove;
  deferStart(target:HTMLElement,interval:number,options?:Clock & {start?:(detail:IntervalDetail)=>void}):Remove;
@@ -104,7 +113,8 @@ export interface DanceMoves {
 }
 export const VERSION:string;
 export const ORIENTATION_ADAPTERS:readonly OrientationAdapter[];
-export const PAGE_META_KEYS:Readonly<{bpm:string;lyric:string;cue:string;popups:string;duration:string;effect:string}>;
+export const PAGE_META_KEYS:Readonly<{bpm:string;lyric:string;cue:string;popups:string;duration:string;effect:string;alignment:string;alignmentAudio:string}>;
+export function validateBeatAlignment(input?:BeatAlignment|null):Readonly<BeatAlignment>|null;
 export function createDanceMoves(options:Options):DanceMoves;
 export function validatePageConfig(input?:PageConfig):Readonly<PageConfig>;
 export function fromWordPressMeta(meta:Record<string,unknown>,resolveAttachment?:(id:number)=>string|Promise<string>):Promise<Readonly<PageConfig>>;

package/lib/index.mjs

@@ -102,6 +102,38 @@ function install(__dmScope) {
       return ticks;
     }
     var bpm = effectiveBpm(rawConfig.bpm);
+    var bpmSource = ["explicit", "analysis"].indexOf(rawConfig.bpmSource) >= 0 ? rawConfig.bpmSource : "fallback";
+    function beatAlignmentState(audio) {
+      var reading = rawConfig.beatAlignment;
+      if (!reading)
+        return { status: rawConfig.beatAlignmentStatus === "invalid" ? "invalid" : "unconfigured", applied: false };
+      var source = playbackAudio(audio);
+      var identity2 = source && (source.masterSourceUrl || source.masterId || source.currentSrc || source.src);
+      try {
+        if (!identity2 || new URL(String(identity2), document2.baseURI).href !== new URL(reading.source_url).href) {
+          return { status: "source-mismatch", applied: false };
+        }
+      } catch (error) {
+        return { status: "source-mismatch", applied: false };
+      }
+      return {
+        status: reading.phase_status,
+        applied: true,
+        firstBeatSeconds: reading.first_beat_seconds,
+        offsetPips: reading.offset_pips,
+        sourceSha256: reading.source_sha256,
+        bpmStatus: reading.bpm_status
+      };
+    }
+    function rhythmicTime(audio) {
+      var source = playbackAudio(audio);
+      var seconds = source && Number.isFinite(Number(source.currentTime)) ? Number(source.currentTime) : 0;
+      var state = beatAlignmentState(source);
+      return seconds - (state.applied ? state.firstBeatSeconds : 0);
+    }
+    function sourceTick(audio, bpmOverride) {
+      return rhythmicTime(audio) * effectiveBpm(bpmOverride || bpm) * TICKS_PER_BEAT / 60;
+    }
     function durationMilliseconds(ticks, bpmOverride) {
       return 3750 / effectiveBpm(bpmOverride || bpm) * quantizeTicks(ticks);
     }
@@ -109,7 +141,7 @@ function install(__dmScope) {
       var settings = options || {};
       var audio = playbackAudio(settings.audio) || (settings.clock === "audio" ? activeAudio : null);
       if (audio && !audio.paused && !audio.ended && Number.isFinite(Number(audio.currentTime))) {
-        return Number(audio.currentTime) * effectiveBpm(settings.bpm || bpm) * TICKS_PER_BEAT / 60;
+        return sourceTick(audio, settings.bpm);
       }
       var now = window2.performance && typeof window2.performance.now === "function" ? window2.performance.now() : Date.now();
       return Math.max(0, now - pageClockStarted) * effectiveBpm(settings.bpm || bpm) * TICKS_PER_BEAT / 6e4;
@@ -408,7 +440,7 @@ function install(__dmScope) {
         __dmScope.dataset(document2.documentElement, "danceMovesSharedControls", null);
       }
       __dmScope.dataset(document2.documentElement, "danceMovesBpm", String(bpm));
-      __dmScope.dataset(document2.documentElement, "danceMovesBpmSource", rawConfig.bpmSource === "explicit" ? "explicit" : "fallback");
+      __dmScope.dataset(document2.documentElement, "danceMovesBpmSource", bpmSource);
       __dmScope.dataset(document2.documentElement, "danceMovesVersion", String(rawConfig.version || ""));
     }
     function registerAnimationScope(root, selectors) {
@@ -944,7 +976,7 @@ function install(__dmScope) {
       var root = document2.querySelector(".ks-epk");
       if (root) {
         __dmScope.dataset(root, "danceMovesBpm", String(bpm));
-        __dmScope.dataset(root, "danceMovesBpmSource", rawConfig.bpmSource === "explicit" ? "explicit" : "fallback");
+        __dmScope.dataset(root, "danceMovesBpmSource", bpmSource);
         if (rawConfig.lyricTimingUrl)
           __dmScope.dataset(root, "danceMovesLyricTiming", String(rawConfig.lyricTimingUrl));
         if (rawConfig.cueTimingUrl)
@@ -973,11 +1005,14 @@ function install(__dmScope) {
     var api = {
       version: String(rawConfig.version || ""),
       bpm,
-      bpmSource: rawConfig.bpmSource === "explicit" ? "explicit" : "fallback",
+      bpmSource,
       ticksPerBeat: TICKS_PER_BEAT,
       quantizeTicks,
       durationMilliseconds,
       currentTick,
+      sourceTick,
+      rhythmicTime,
+      beatAlignmentState,
       nextIntervalTick,
       scheduleAtInterval,
       deferStart,
@@ -1184,7 +1219,8 @@ function install2(__dmScope) {
       function sync() {
         var rate = Math.max(0.01, finite3(audio.playbackRate, 1));
         var duration = motion.durationMilliseconds(ticks) / 1e3 / rate;
-        var phase = -(finite3(audio.currentTime, 0) / rate % duration);
+        var rhythmicSeconds = motion.rhythmicTime ? motion.rhythmicTime(audio) : finite3(audio.currentTime, 0);
+        var phase = -((rhythmicSeconds / rate % duration + duration) % duration);
         __dmScope.setStyle(state.root.style, prefix + "-duration", duration.toFixed(6) + "s");
         __dmScope.setStyle(state.root.style, prefix + "-delay", phase.toFixed(6) + "s");
         __dmScope.dataset(state.root, "danceMovesPulse", state.reduced.matches || state.forced.matches ? "inactive" : audio.paused ? "paused" : "playing");
@@ -1476,7 +1512,8 @@ function install2(__dmScope) {
       function calculate(reason, staticFallback) {
         var cycleSeconds = Math.max(1e-3, finite3(motion.durationMilliseconds(cycleTicks), 1) / 1e3);
         var time = Math.max(0, finite3(audio.currentTime, 0));
-        var phase = ((time - phaseOffsetSeconds) % cycleSeconds + cycleSeconds) % cycleSeconds / cycleSeconds;
+        var rhythmicSeconds = motion.rhythmicTime ? motion.rhythmicTime(audio) : time;
+        var phase = ((rhythmicSeconds - phaseOffsetSeconds) % cycleSeconds + cycleSeconds) % cycleSeconds / cycleSeconds;
         var localFrame = staticFallback ? staticFrame : Math.min(frameCount - 1, Math.floor(phase * frameCount + 1e-9));
         var mapped = mappedFrame(localFrame);
         return {
@@ -4895,8 +4932,9 @@ function install9(__dmScope) {
           anchor = 0;
         lastClock = mode;
         const tempo = bpm();
-        const beats = useAudio ? Math.max(0, Number.isFinite(audio.currentTime) ? audio.currentTime : 0) * tempo / 60 : motion.currentTick({ clock: "page" }) / 16;
-        return { beats, mode, tempo };
+        const sourceBeats = useAudio ? Math.max(0, Number.isFinite(audio.currentTime) ? audio.currentTime : 0) * tempo / 60 : motion.currentTick({ clock: "page" }) / 16;
+        const beats = useAudio && motion.sourceTick ? motion.sourceTick(audio) / 16 : sourceBeats;
+        return { beats, sourceBeats, mode, tempo };
       }
       function blocked() {
         if (!enabled)
@@ -4934,7 +4972,8 @@ function install9(__dmScope) {
           audio: s.mode === "audio" ? audio : null,
           rudiment: row.name,
           clock: s.mode,
-          sourceBeats: s.beats,
+          sourceBeats: s.sourceBeats,
+          rhythmicBeats: s.beats,
           bpm: s.tempo,
           rate,
           pip: neutral ? null : pip,
@@ -5480,6 +5519,35 @@ function createScope(root, config, { legacyGlobals = false, nonce, orientation =
   return api;
 }
 
+// .build/modules/beat-alignment.mjs
+var hash = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+function rational(value, label) {
+  if (typeof value !== "string" || !/^-?\d{1,80}(?:\/[1-9]\d{0,79})?$/.test(value)) throw new TypeError(`Invalid exact ${label}`);
+  const [n, d = "1"] = value.split("/");
+  return [BigInt(n), BigInt(d)];
+}
+function numeric(value, label, min, max) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) throw new RangeError(`Invalid ${label}`);
+  return value;
+}
+function validateBeatAlignment(input) {
+  if (input === void 0 || input === null || input === "") return null;
+  if (!input || typeof input !== "object" || Array.isArray(input) || input.schema !== "stemlab.beat-alignment.v1" || input.pips_per_beat !== 64 || input.canonical_first_beat_pip !== 0 || !hash(input.source_sha256) || !hash(input.evidence_sha256) || !hash(input.report_sha256)) throw new TypeError("Invalid source-bound StemLab beat alignment");
+  const bpm = numeric(input.bpm, "alignment BPM", 20, 400);
+  const first = numeric(input.first_beat_seconds, "first beat", 0, 86400);
+  const offset = numeric(input.offset_pips, "pip offset", -36864e3, 0);
+  const [bn, bd] = rational(input.exact_bpm, "BPM"), [fn, fd] = rational(input.first_beat_exact_seconds, "first beat"), [pn, pd] = rational(input.exact_offset_pips, "pip offset");
+  if (fn * bn * 64n * pd + pn * fd * bd * 60n !== 0n || bn <= 0n || fn < 0n || Math.abs(Number(bn) / Number(bd) - bpm) > 1e-9 || Math.abs(Number(fn) / Number(fd) - first) > 1e-9 || Math.abs(Number(pn) / Number(pd) - offset) > 1e-7) throw new RangeError("Exact beat alignment and numeric clock disagree");
+  if (!["canonical", "estimated"].includes(input.bpm_status) || !["estimated", "confirmed", "synthetic"].includes(input.phase_status)) throw new TypeError("Alignment authority is required");
+  for (const key of ["analysis_id", "bpm_basis"]) if (typeof input[key] !== "string" || !/^[a-zA-Z0-9_.-]{1,128}$/.test(input[key])) throw new TypeError(`Invalid ${key}`);
+  if (input.source_audio_verified !== true || !input.source_audio || !Number.isSafeInteger(input.source_audio.num_frames) || input.source_audio.num_frames < 1 || !Number.isSafeInteger(input.source_audio.sample_rate) || input.source_audio.sample_rate < 1 || first >= input.source_audio.num_frames / input.source_audio.sample_rate) throw new TypeError("Verified source audio frame bounds are required");
+  const sourceUrl = input.source_url;
+  if (typeof sourceUrl !== "string" || sourceUrl.length > 4096 || /[\u0000-\u001f]/.test(sourceUrl)) throw new TypeError("An exact verified master URL is required");
+  const parsed = new URL(sourceUrl);
+  if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password || parsed.hash) throw new TypeError("Invalid verified master URL");
+  return Object.freeze({ ...input, bpm, first_beat_seconds: first, offset_pips: offset, source_audio: Object.freeze({ ...input.source_audio }) });
+}
+
 // .build/modules/config.mjs
 var PAGE_META_KEYS = Object.freeze({
   bpm: "_dance_moves_bpm",
@@ -5487,7 +5555,9 @@ var PAGE_META_KEYS = Object.freeze({
   cue: "_dance_moves_cue_timing_id",
   popups: "_dance_moves_lyric_popups_enabled",
   duration: "_dance_moves_master_duration_ms",
-  effect: "_dance_moves_effect"
+  effect: "_dance_moves_effect",
+  alignment: "_dance_moves_beat_alignment",
+  alignmentAudio: "_dance_moves_beat_alignment_audio_id"
 });
 var object = (value) => value && typeof value === "object" && !Array.isArray(value);
 function finite(value, name, min, max) {
@@ -5506,7 +5576,11 @@ function url(value, name) {
 function validatePageConfig(input = {}) {
   if (!object(input)) throw new TypeError("Page configuration must be an object");
   const explicit = input.bpm !== void 0 && input.bpm !== null && input.bpm !== "";
-  const bpm = explicit ? Math.round(finite(input.bpm, "bpm", 20, 400) * 1e3) / 1e3 : 120;
+  const beatAlignment = validateBeatAlignment(input.beatAlignment);
+  const canonicalExplicit = explicit && !["fallback", "analysis"].includes(input.bpmSource);
+  if (canonicalExplicit && beatAlignment && Math.abs(input.bpm - beatAlignment.bpm) > 500001e-9) throw new RangeError("Stored BPM and selected beat alignment disagree; select a matching BPM basis");
+  const bpm = beatAlignment ? beatAlignment.bpm : explicit ? Math.round(finite(input.bpm, "bpm", 20, 400) * 1e3) / 1e3 : 120;
+  if (explicit) finite(input.bpm, "bpm", 20, 400);
   const effect = input.effect ?? "";
   if (!["", "paper-planes"].includes(effect)) throw new RangeError("effect must be empty or paper-planes");
   if (input.lyricPopupsEnabled !== void 0 && typeof input.lyricPopupsEnabled !== "boolean") throw new TypeError("lyricPopupsEnabled must be boolean");
@@ -5518,8 +5592,9 @@ function validatePageConfig(input = {}) {
   return Object.freeze({
     pageId,
     bpm,
-    bpmSource: explicit && input.bpmSource !== "fallback" ? "explicit" : "fallback",
+    bpmSource: canonicalExplicit ? "explicit" : beatAlignment ? "analysis" : "fallback",
     fallbackBpm: 120,
+    beatAlignment,
     ticksPerBeat: 16,
     tickDefinition: "sixteenth-of-beat",
     longDurationQuantumTicks: 16,
@@ -5535,9 +5610,9 @@ function validatePageConfig(input = {}) {
 }
 async function fromWordPressMeta(meta, resolveAttachment) {
   if (!object(meta)) throw new TypeError("meta must be an object");
-  const numeric = (value) => value !== "" && value !== null && value !== void 0 && Number.isFinite(Number(value));
+  const numeric2 = (value) => value !== "" && value !== null && value !== void 0 && Number.isFinite(Number(value));
   const b = meta[PAGE_META_KEYS.bpm];
-  const bpm = numeric(b) && Number(b) >= 20 && Number(b) <= 400 ? Number(b) : void 0;
+  const bpm = numeric2(b) && Number(b) >= 20 && Number(b) <= 400 ? Number(b) : void 0;
   const resolve = async (key) => {
     const value = Number(meta[key] || 0);
     if (!Number.isSafeInteger(value)) throw new RangeError("Attachment ID must be a safe integer");
@@ -5547,8 +5622,15 @@ async function fromWordPressMeta(meta, resolveAttachment) {
     return await resolveAttachment(id) || "";
   };
   const duration = Number(meta[PAGE_META_KEYS.duration]);
+  let beatAlignment = meta[PAGE_META_KEYS.alignment] || null;
+  if (typeof beatAlignment === "string") {
+    if (beatAlignment.length > 16384) throw new RangeError("Beat alignment exceeds 16 KiB");
+    beatAlignment = JSON.parse(beatAlignment);
+  }
+  if (beatAlignment) beatAlignment = { ...beatAlignment, source_url: await resolve(PAGE_META_KEYS.alignmentAudio) };
   return validatePageConfig({
     bpm,
+    beatAlignment,
     lyricTimingUrl: await resolve(PAGE_META_KEYS.lyric),
     cueTimingUrl: await resolve(PAGE_META_KEYS.cue),
     lyricPopupsEnabled: meta[PAGE_META_KEYS.popups] === true || String(meta[PAGE_META_KEYS.popups]) === "1",
@@ -6089,7 +6171,8 @@ function installPlayback(scope, api, host = scope.document.defaultView) {
       error: { get: () => read().error || null },
       element: { value: isNative ? master : null },
       activePlayer: { get: () => delegate ? delegate.activePlayer : active.element },
-      masterId: { get: () => delegate ? delegate.masterId : master.currentSrc || master.src || master.id }
+      masterId: { get: () => delegate ? delegate.masterId : master.currentSrc || master.src || master.id },
+      masterSourceUrl: { get: () => delegate ? delegate.masterSourceUrl : reference?.sourceUrl || master.currentSrc || master.src || "" }
     });
     transport.matches = (selector) => target.matches(selector);
     transport.getAttribute = (name) => target.getAttribute(name);
@@ -7005,7 +7088,7 @@ function installChildPlayback(scope, api, host) {
 }
 
 // .build/modules/version.mjs
-var VERSION = "3.2.0";
+var VERSION = "3.3.0";
 
 // .build/modules/index.mjs
 var mounted = /* @__PURE__ */ new WeakMap();
@@ -7100,5 +7183,6 @@ export {
   createPlaybackPublisher,
   createPlaybackReceiver,
   fromWordPressMeta,
+  validateBeatAlignment,
   validatePageConfig
 };

package/lib/react.cjs

@@ -115,7 +115,11 @@ function Rudiment({ runtime, options, children, ...attributes }) {
 }
 function PageMetadataEditor({ value = EMPTY, onSave }) {
   const [draft, setDraft] = (0, import_react.useState)(() => ({ ...value })), [message, setMessage] = (0, import_react.useState)(""), [busy, setBusy] = (0, import_react.useState)(false);
-  (0, import_react.useEffect)(() => setDraft({ ...value }), [value]);
+  const [alignmentText, setAlignmentText] = (0, import_react.useState)(() => value.beatAlignment ? JSON.stringify(value.beatAlignment, null, 2) : "");
+  (0, import_react.useEffect)(() => {
+    setDraft({ ...value });
+    setAlignmentText(value.beatAlignment ? JSON.stringify(value.beatAlignment, null, 2) : "");
+  }, [value]);
   const input = (key, label, type = "text") => (0, import_react.createElement)("label", { key }, label, (0, import_react.createElement)("input", {
     type,
     value: draft[key] ?? "",
@@ -129,7 +133,7 @@ function PageMetadataEditor({ value = EMPTY, onSave }) {
       setBusy(true);
       setMessage("");
       try {
-        await onSave((0, import_index.validatePageConfig)(draft));
+        await onSave((0, import_index.validatePageConfig)({ ...draft, beatAlignment: alignmentText.trim() ? JSON.parse(alignmentText) : null }));
         setMessage("Saved");
       } catch (error) {
         setMessage(error.message);
@@ -140,6 +144,7 @@ function PageMetadataEditor({ value = EMPTY, onSave }) {
     input("bpm", "BPM", "number"),
     input("lyricTimingUrl", "Lyric timing URL"),
     input("cueTimingUrl", "Cue timing URL"),
+    (0, import_react.createElement)("label", null, "Beat alignment reading (JSON)", (0, import_react.createElement)("textarea", { rows: 7, value: alignmentText, onChange: (e) => setAlignmentText(e.target.value) })),
     input("masterDurationMilliseconds", "Master duration (milliseconds)", "number"),
     (0, import_react.createElement)("label", null, (0, import_react.createElement)("input", { type: "checkbox", checked: !!draft.lyricPopupsEnabled, onChange: (e) => setDraft({ ...draft, lyricPopupsEnabled: e.target.checked }) }), "Timed lyric pop-ups"),
     (0, import_react.createElement)("label", null, "Ambient effect", (0, import_react.createElement)(

package/lib/react.mjs

@@ -86,7 +86,11 @@ function Rudiment({ runtime, options, children, ...attributes }) {
 }
 function PageMetadataEditor({ value = EMPTY, onSave }) {
   const [draft, setDraft] = useState(() => ({ ...value })), [message, setMessage] = useState(""), [busy, setBusy] = useState(false);
-  useEffect(() => setDraft({ ...value }), [value]);
+  const [alignmentText, setAlignmentText] = useState(() => value.beatAlignment ? JSON.stringify(value.beatAlignment, null, 2) : "");
+  useEffect(() => {
+    setDraft({ ...value });
+    setAlignmentText(value.beatAlignment ? JSON.stringify(value.beatAlignment, null, 2) : "");
+  }, [value]);
   const input = (key, label, type = "text") => h("label", { key }, label, h("input", {
     type,
     value: draft[key] ?? "",
@@ -100,7 +104,7 @@ function PageMetadataEditor({ value = EMPTY, onSave }) {
       setBusy(true);
       setMessage("");
       try {
-        await onSave(validatePageConfig(draft));
+        await onSave(validatePageConfig({ ...draft, beatAlignment: alignmentText.trim() ? JSON.parse(alignmentText) : null }));
         setMessage("Saved");
       } catch (error) {
         setMessage(error.message);
@@ -111,6 +115,7 @@ function PageMetadataEditor({ value = EMPTY, onSave }) {
     input("bpm", "BPM", "number"),
     input("lyricTimingUrl", "Lyric timing URL"),
     input("cueTimingUrl", "Cue timing URL"),
+    h("label", null, "Beat alignment reading (JSON)", h("textarea", { rows: 7, value: alignmentText, onChange: (e) => setAlignmentText(e.target.value) })),
     input("masterDurationMilliseconds", "Master duration (milliseconds)", "number"),
     h("label", null, h("input", { type: "checkbox", checked: !!draft.lyricPopupsEnabled, onChange: (e) => setDraft({ ...draft, lyricPopupsEnabled: e.target.checked }) }), "Timed lyric pop-ups"),
     h("label", null, "Ambient effect", h(