entangled-worlds-orbiters-shared 2.7.0 → 2.8.0

package/dist/clock/track-metadata.d.ts

@@ -14,6 +14,16 @@ export interface SyncSettingsLike {
         sourceTimeSec?: unknown;
     } | null | undefined> | null;
     gridStartTimeSec?: unknown;
+    /** Whether this track time-stretches onto the grid. A BOOLEAN, so `false` is an answer rather than
+     *  an absence — see `resolveWarpEnabledFromTrackData`. */
+    warpEnabled?: unknown;
+    /** Whether this track plays looped. Same boolean rule as `warpEnabled`, and the same three states:
+     *  on, off, and nobody-said — see `resolveLoopEnabledFromTrackData`. */
+    loopEnabled?: unknown;
+    /** The loop region in SECONDS (storage's time unit; the audio engine works in ms and converts at
+     *  its edge). Only ever meaningful as a pair — see `resolveLoopRangeSecFromTrackData`. */
+    loopStartSec?: unknown;
+    loopEndSec?: unknown;
 }
 export interface TrackMetadataLike {
     trackBpm?: unknown;
@@ -71,3 +81,33 @@ export declare function resolveTrackBpmFromTrackData(trackData?: TrackDataLike |
  * Returns null when nothing resolves (consumers default to 0).
  */
 export declare function resolvePrimaryGridMarkerTimeSecFromTrackData(trackData?: TrackDataLike | null): number | null;
+/**
+ * Resolve whether this track should warp (time-stretch onto the grid) for the viewer.
+ *
+ * Returns null when nothing anywhere expressed a preference. Null means "no opinion", NOT "off" —
+ * the caller supplies its own default, because only the caller knows its runtime constraints (in
+ * orbiters, a deck with no tempo cannot warp at all, whatever was saved).
+ */
+export declare function resolveWarpEnabledFromTrackData(trackData?: TrackDataLike | null): boolean | null;
+/**
+ * Resolve whether this track should play looped for the viewer.
+ *
+ * Same three states as warp — on, off, nobody-said — but no smart default anywhere behind it: the
+ * server stops at the owner's setting, so null here is genuinely common and simply means the caller
+ * keeps whatever looping default it already had.
+ */
+export declare function resolveLoopEnabledFromTrackData(trackData?: TrackDataLike | null): boolean | null;
+/**
+ * Resolve the saved loop region, in seconds, or null when no layer holds a complete one.
+ *
+ * Resolved as a PAIR, never edge by edge: a start borrowed from one layer and an end from another
+ * describes a loop nobody set, and can invert. `start` of 0 is a real value, so the guard is a
+ * finiteness test rather than a truthiness one.
+ *
+ * The caller must still clamp this against the audio's real duration before using it — a region
+ * saved against an earlier version of the track can outlive the audio it was drawn on.
+ */
+export declare function resolveLoopRangeSecFromTrackData(trackData?: TrackDataLike | null): {
+    startSec: number;
+    endSec: number;
+} | null;

package/dist/clock/track-metadata.js

@@ -20,6 +20,22 @@ function firstResolvedValue(candidates, parser) {
     }
     return null;
 }
+/**
+ * The first candidate that is an actual boolean, or null when none of them is.
+ *
+ * Deliberately separate from `firstResolvedValue`: that one folds "absent" and "invalid" together
+ * and returns a number, which is exactly the wrong shape here. A warp preference has THREE states —
+ * on, off, and nobody-said — and `false` is the middle one, not the last. Any `||`, any truthiness
+ * test, any `?? ` against a default collapses off into nobody-said and loses the user's choice.
+ */
+function firstBoolean(candidates) {
+    for (const candidate of candidates) {
+        if (typeof candidate === 'boolean') {
+            return candidate;
+        }
+    }
+    return null;
+}
 /**
  * Resolve the effective track BPM. Precedence (first finite, > 0 wins):
  * owner `trackBpm` → owner `effectiveSettings.sync.trackBpm` → per-user `trackUserSettings.sync.trackBpm`
@@ -64,3 +80,71 @@ export function resolvePrimaryGridMarkerTimeSecFromTrackData(trackData = null) {
         trackData?.metadata?.wrap?.gridStartTimeSec,
     ], toNonNegativeNumber);
 }
+/**
+ * The shared walk behind the boolean preferences below.
+ *
+ * The server already applied the real precedence — the viewer's own saved setting, then the owner's,
+ * then (for warp) a smart default — and publishes the answer at `effectiveSettings.sync`. So that is
+ * read FIRST: it is the resolved value, not a competing opinion. The per-user path below it covers
+ * the shapes where the server has not resolved anything (a raw `trackUserSettings` fetch that has not
+ * been merged into a track payload yet).
+ *
+ * One walk, not one per field: warp and loop differ in what they MEAN, never in where they are found,
+ * and two hand-maintained copies of this list would drift the moment a payload shape changed.
+ */
+function resolveSyncFlagFromTrackData(trackData, field) {
+    return firstBoolean([
+        trackData?.track?.metadata?.effectiveSettings?.sync?.[field],
+        trackData?.release?.metadata?.effectiveSettings?.sync?.[field],
+        trackData?.metadata?.effectiveSettings?.sync?.[field],
+        trackData?.effectiveSettings?.sync?.[field],
+        trackData?.trackUserSettings?.sync?.[field],
+    ]);
+}
+/**
+ * Resolve whether this track should warp (time-stretch onto the grid) for the viewer.
+ *
+ * Returns null when nothing anywhere expressed a preference. Null means "no opinion", NOT "off" —
+ * the caller supplies its own default, because only the caller knows its runtime constraints (in
+ * orbiters, a deck with no tempo cannot warp at all, whatever was saved).
+ */
+export function resolveWarpEnabledFromTrackData(trackData = null) {
+    return resolveSyncFlagFromTrackData(trackData, 'warpEnabled');
+}
+/**
+ * Resolve whether this track should play looped for the viewer.
+ *
+ * Same three states as warp — on, off, nobody-said — but no smart default anywhere behind it: the
+ * server stops at the owner's setting, so null here is genuinely common and simply means the caller
+ * keeps whatever looping default it already had.
+ */
+export function resolveLoopEnabledFromTrackData(trackData = null) {
+    return resolveSyncFlagFromTrackData(trackData, 'loopEnabled');
+}
+/**
+ * Resolve the saved loop region, in seconds, or null when no layer holds a complete one.
+ *
+ * Resolved as a PAIR, never edge by edge: a start borrowed from one layer and an end from another
+ * describes a loop nobody set, and can invert. `start` of 0 is a real value, so the guard is a
+ * finiteness test rather than a truthiness one.
+ *
+ * The caller must still clamp this against the audio's real duration before using it — a region
+ * saved against an earlier version of the track can outlive the audio it was drawn on.
+ */
+export function resolveLoopRangeSecFromTrackData(trackData = null) {
+    const candidates = [
+        trackData?.track?.metadata?.effectiveSettings?.sync,
+        trackData?.release?.metadata?.effectiveSettings?.sync,
+        trackData?.metadata?.effectiveSettings?.sync,
+        trackData?.effectiveSettings?.sync,
+        trackData?.trackUserSettings?.sync,
+    ];
+    for (const candidate of candidates) {
+        const startSec = toNonNegativeNumber(candidate?.loopStartSec);
+        const endSec = toNonNegativeNumber(candidate?.loopEndSec);
+        if (startSec !== null && endSec !== null && endSec > startSec) {
+            return { startSec, endSec };
+        }
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",

package/src/clock/track-metadata.ts

@@ -18,6 +18,16 @@ export interface SyncSettingsLike {
   primaryGridMarkerTimeSec?: unknown;
   gridMarkers?: ReadonlyArray<{ sourceTimeSec?: unknown } | null | undefined> | null;
   gridStartTimeSec?: unknown;
+  /** Whether this track time-stretches onto the grid. A BOOLEAN, so `false` is an answer rather than
+   *  an absence — see `resolveWarpEnabledFromTrackData`. */
+  warpEnabled?: unknown;
+  /** Whether this track plays looped. Same boolean rule as `warpEnabled`, and the same three states:
+   *  on, off, and nobody-said — see `resolveLoopEnabledFromTrackData`. */
+  loopEnabled?: unknown;
+  /** The loop region in SECONDS (storage's time unit; the audio engine works in ms and converts at
+   *  its edge). Only ever meaningful as a pair — see `resolveLoopRangeSecFromTrackData`. */
+  loopStartSec?: unknown;
+  loopEndSec?: unknown;
 }
 
 export interface TrackMetadataLike {
@@ -72,6 +82,23 @@ function firstResolvedValue(
   return null;
 }
 
+/**
+ * The first candidate that is an actual boolean, or null when none of them is.
+ *
+ * Deliberately separate from `firstResolvedValue`: that one folds "absent" and "invalid" together
+ * and returns a number, which is exactly the wrong shape here. A warp preference has THREE states —
+ * on, off, and nobody-said — and `false` is the middle one, not the last. Any `||`, any truthiness
+ * test, any `?? ` against a default collapses off into nobody-said and loses the user's choice.
+ */
+function firstBoolean(candidates: ReadonlyArray<unknown>): boolean | null {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'boolean') {
+      return candidate;
+    }
+  }
+  return null;
+}
+
 /**
  * Resolve the effective track BPM. Precedence (first finite, > 0 wins):
  * owner `trackBpm` → owner `effectiveSettings.sync.trackBpm` → per-user `trackUserSettings.sync.trackBpm`
@@ -125,3 +152,85 @@ export function resolvePrimaryGridMarkerTimeSecFromTrackData(
     toNonNegativeNumber,
   );
 }
+
+/**
+ * The shared walk behind the boolean preferences below.
+ *
+ * The server already applied the real precedence — the viewer's own saved setting, then the owner's,
+ * then (for warp) a smart default — and publishes the answer at `effectiveSettings.sync`. So that is
+ * read FIRST: it is the resolved value, not a competing opinion. The per-user path below it covers
+ * the shapes where the server has not resolved anything (a raw `trackUserSettings` fetch that has not
+ * been merged into a track payload yet).
+ *
+ * One walk, not one per field: warp and loop differ in what they MEAN, never in where they are found,
+ * and two hand-maintained copies of this list would drift the moment a payload shape changed.
+ */
+function resolveSyncFlagFromTrackData(
+  trackData: TrackDataLike | null,
+  field: 'warpEnabled' | 'loopEnabled',
+): boolean | null {
+  return firstBoolean([
+    trackData?.track?.metadata?.effectiveSettings?.sync?.[field],
+    trackData?.release?.metadata?.effectiveSettings?.sync?.[field],
+    trackData?.metadata?.effectiveSettings?.sync?.[field],
+    trackData?.effectiveSettings?.sync?.[field],
+    trackData?.trackUserSettings?.sync?.[field],
+  ]);
+}
+
+/**
+ * Resolve whether this track should warp (time-stretch onto the grid) for the viewer.
+ *
+ * Returns null when nothing anywhere expressed a preference. Null means "no opinion", NOT "off" —
+ * the caller supplies its own default, because only the caller knows its runtime constraints (in
+ * orbiters, a deck with no tempo cannot warp at all, whatever was saved).
+ */
+export function resolveWarpEnabledFromTrackData(
+  trackData: TrackDataLike | null = null,
+): boolean | null {
+  return resolveSyncFlagFromTrackData(trackData, 'warpEnabled');
+}
+
+/**
+ * Resolve whether this track should play looped for the viewer.
+ *
+ * Same three states as warp — on, off, nobody-said — but no smart default anywhere behind it: the
+ * server stops at the owner's setting, so null here is genuinely common and simply means the caller
+ * keeps whatever looping default it already had.
+ */
+export function resolveLoopEnabledFromTrackData(
+  trackData: TrackDataLike | null = null,
+): boolean | null {
+  return resolveSyncFlagFromTrackData(trackData, 'loopEnabled');
+}
+
+/**
+ * Resolve the saved loop region, in seconds, or null when no layer holds a complete one.
+ *
+ * Resolved as a PAIR, never edge by edge: a start borrowed from one layer and an end from another
+ * describes a loop nobody set, and can invert. `start` of 0 is a real value, so the guard is a
+ * finiteness test rather than a truthiness one.
+ *
+ * The caller must still clamp this against the audio's real duration before using it — a region
+ * saved against an earlier version of the track can outlive the audio it was drawn on.
+ */
+export function resolveLoopRangeSecFromTrackData(
+  trackData: TrackDataLike | null = null,
+): { startSec: number; endSec: number } | null {
+  const candidates: Array<SyncSettingsLike | null | undefined> = [
+    trackData?.track?.metadata?.effectiveSettings?.sync,
+    trackData?.release?.metadata?.effectiveSettings?.sync,
+    trackData?.metadata?.effectiveSettings?.sync,
+    trackData?.effectiveSettings?.sync,
+    trackData?.trackUserSettings?.sync,
+  ];
+
+  for (const candidate of candidates) {
+    const startSec = toNonNegativeNumber(candidate?.loopStartSec);
+    const endSec = toNonNegativeNumber(candidate?.loopEndSec);
+    if (startSec !== null && endSec !== null && endSec > startSec) {
+      return { startSec, endSec };
+    }
+  }
+  return null;
+}