entangled-worlds-orbiters-shared 1.4.0 → 1.5.0

package/dist/clock/meter.d.ts

@@ -0,0 +1,50 @@
+import type { TrackDataLike } from './track-metadata.js';
+export interface MeterPreset {
+    id: string;
+    numerator: number;
+    denominator: number;
+}
+/** Quick-pick reference meters. `id` is the persisted/display value, not a closed enum. */
+export declare const METER_PRESETS: MeterPreset[];
+export declare const DEFAULT_METER_ID = "4/4";
+export declare const MIN_METER_NUMERATOR = 1;
+export declare const MAX_METER_NUMERATOR = 64;
+export declare const VALID_METER_DENOMINATORS: readonly number[];
+interface MeterFraction {
+    numerator: number;
+    denominator: number;
+}
+export interface ParsedMeter {
+    id: string;
+    numerator: number;
+    denominator: number;
+    beatsPerBar: number;
+    beatUnit: number;
+    sharedBeatsPerBar: number;
+    quarterBeatsPerBar: number;
+    clickIntervalQuarterBeats: number;
+    clicksPerBar: number;
+}
+export declare function formatMeterId(value?: Partial<MeterFraction>): string;
+/** True when `value` is a valid arbitrary meter string or `{ numerator, denominator }`. */
+export declare function isValidMeterId(value: unknown): boolean;
+/** Normalize an arbitrary value to a persisted meter id (`n/d`), falling back to the default. */
+export declare function normalizeMeterId(value: unknown): string;
+/**
+ * Resolve a meter id to its numbers, including `sharedBeatsPerBar` — the count of shared (quarter-note)
+ * beats in one bar, which is what the engine uses for the downbeat accent and the launch bar.
+ */
+export declare function parseMeter(value: unknown): ParsedMeter;
+/** Shared (quarter-note) beats per bar for a meter id — the engine's bar length. */
+export declare function sharedBeatsPerBar(id: unknown): number;
+/**
+ * Resolve the per-track meter from assembled track data — the LOAD side, walking the SAME precedence
+ * as the shared tempo resolver (`resolveTrackBpmFromTrackData`): owner CANONICAL first, then the
+ * per-user override, then auto-detected analysis, then the default. First valid wins:
+ *   1) owner canonical  — `metadata.meter` → `metadata.effectiveSettings.sync.meter`
+ *   2) per-user         — `trackUserSettings.sync.meter`
+ *   3) auto-detected    — `metadata.audioAnalysis.analysis` time signature
+ *   4) default (4/4)
+ */
+export declare function resolveTrackMeterFromTrackData(trackData?: TrackDataLike | null): string;
+export {};

package/dist/clock/meter.js

@@ -0,0 +1,145 @@
+// ./clock/meter — time signature / meter model. A per-track musical property (how many beats make a
+// bar), resolved with the SAME owner → per-user → auto-detected → default precedence as the tempo
+// resolver in `./clock/track-metadata`. Promoted out of the orbiters app so EW reuses it verbatim.
+// Framework-free: no three, no react.
+//
+// Units: `sharedBeatsPerBar` is quarter-note beats per bar = numerator * 4 / denominator — the same
+// beat unit `MusicalProjection` (./clock/musical) counts, so a resolved meter feeds its `signatureMap`
+// directly: `{ startBar: 0, numerator, denominator }`.
+/** Quick-pick reference meters. `id` is the persisted/display value, not a closed enum. */
+export const METER_PRESETS = [
+    { id: '4/4', numerator: 4, denominator: 4 },
+    { id: '3/4', numerator: 3, denominator: 4 },
+    { id: '6/8', numerator: 6, denominator: 8 },
+];
+export const DEFAULT_METER_ID = '4/4';
+export const MIN_METER_NUMERATOR = 1;
+export const MAX_METER_NUMERATOR = 64;
+export const VALID_METER_DENOMINATORS = [1, 2, 4, 8, 16, 32];
+const BY_ID = new Map(METER_PRESETS.map((m) => [m.id, m]));
+const DENOMINATORS = new Set(VALID_METER_DENOMINATORS);
+function isValidNumerator(n) {
+    return Number.isInteger(n) && n >= MIN_METER_NUMERATOR;
+}
+function isValidDenominator(n) {
+    return Number.isInteger(n) && DENOMINATORS.has(n);
+}
+function parseMeterString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = value.trim().match(/^(\d+)\s*\/\s*(\d+)$/);
+    if (!match)
+        return null;
+    const numerator = Number(match[1]);
+    const denominator = Number(match[2]);
+    if (!isValidNumerator(numerator) || !isValidDenominator(denominator))
+        return null;
+    return { numerator, denominator };
+}
+function parseMeterObject(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const numerator = Number(value.numerator);
+    const denominator = Number(value.denominator);
+    if (!isValidNumerator(numerator) || !isValidDenominator(denominator))
+        return null;
+    return { numerator, denominator };
+}
+export function formatMeterId(value = {}) {
+    const n = Number(value.numerator);
+    const d = Number(value.denominator);
+    return isValidNumerator(n) && isValidDenominator(d) ? `${n}/${d}` : DEFAULT_METER_ID;
+}
+/** True when `value` is a valid arbitrary meter string or `{ numerator, denominator }`. */
+export function isValidMeterId(value) {
+    return parseMeterString(value) !== null || parseMeterObject(value) !== null;
+}
+/** Normalize an arbitrary value to a persisted meter id (`n/d`), falling back to the default. */
+export function normalizeMeterId(value) {
+    const parsed = parseMeterString(value) ?? parseMeterObject(value);
+    return parsed ? formatMeterId(parsed) : DEFAULT_METER_ID;
+}
+/**
+ * Resolve a meter id to its numbers, including `sharedBeatsPerBar` — the count of shared (quarter-note)
+ * beats in one bar, which is what the engine uses for the downbeat accent and the launch bar.
+ */
+export function parseMeter(value) {
+    const id = normalizeMeterId(value);
+    const preset = BY_ID.get(id);
+    const parsed = preset ?? parseMeterString(id) ?? parseMeterString(DEFAULT_METER_ID);
+    const numerator = parsed.numerator;
+    const denominator = parsed.denominator;
+    const sharedBeatsPerBar = (numerator * 4) / denominator;
+    const clickIntervalQuarterBeats = 4 / denominator;
+    return {
+        id,
+        numerator,
+        denominator,
+        beatsPerBar: numerator,
+        beatUnit: denominator,
+        sharedBeatsPerBar,
+        quarterBeatsPerBar: sharedBeatsPerBar,
+        clickIntervalQuarterBeats,
+        clicksPerBar: numerator,
+    };
+}
+function resolveAnalysisMeter(analysis) {
+    if (!analysis || typeof analysis !== 'object')
+        return null;
+    const a = analysis;
+    const candidates = [
+        a.time_signature,
+        a.timeSignature,
+        a.meter,
+        a.time_signature?.meter,
+        a.timeSignature?.meter,
+        a.time_signature?.value,
+        a.timeSignature?.value,
+    ];
+    for (const candidate of candidates) {
+        if (isValidMeterId(candidate)) {
+            return normalizeMeterId(candidate);
+        }
+    }
+    return null;
+}
+/** Shared (quarter-note) beats per bar for a meter id — the engine's bar length. */
+export function sharedBeatsPerBar(id) {
+    return parseMeter(id).sharedBeatsPerBar;
+}
+/**
+ * Resolve the per-track meter from assembled track data — the LOAD side, walking the SAME precedence
+ * as the shared tempo resolver (`resolveTrackBpmFromTrackData`): owner CANONICAL first, then the
+ * per-user override, then auto-detected analysis, then the default. First valid wins:
+ *   1) owner canonical  — `metadata.meter` → `metadata.effectiveSettings.sync.meter`
+ *   2) per-user         — `trackUserSettings.sync.meter`
+ *   3) auto-detected    — `metadata.audioAnalysis.analysis` time signature
+ *   4) default (4/4)
+ */
+export function resolveTrackMeterFromTrackData(trackData = null) {
+    const td = trackData;
+    const candidates = [
+        // 1) owner canonical — top-level metadata (mirrors tempo's `metadata.trackBpm`)
+        td?.track?.metadata?.meter,
+        td?.release?.metadata?.meter,
+        td?.metadata?.meter,
+        // 1) owner canonical — effectiveSettings (mirrors tempo's `effectiveSettings.sync.trackBpm`)
+        td?.track?.metadata?.effectiveSettings?.sync?.meter,
+        td?.release?.metadata?.effectiveSettings?.sync?.meter,
+        td?.metadata?.effectiveSettings?.sync?.meter,
+        td?.track?.effectiveSettings?.sync?.meter,
+        td?.release?.effectiveSettings?.sync?.meter,
+        td?.effectiveSettings?.sync?.meter,
+        // 2) per-user override (mirrors tempo's `trackUserSettings.sync.trackBpm`)
+        td?.trackUserSettings?.sync?.meter,
+        // 3) auto-detected analysis (mirrors tempo's `audioAnalysis.analysis.tempo_bpm`)
+        resolveAnalysisMeter(td?.track?.metadata?.audioAnalysis?.analysis),
+        resolveAnalysisMeter(td?.release?.metadata?.audioAnalysis?.analysis),
+        resolveAnalysisMeter(td?.metadata?.audioAnalysis?.analysis),
+    ];
+    for (const c of candidates) {
+        if (isValidMeterId(c))
+            return normalizeMeterId(c);
+    }
+    return DEFAULT_METER_ID;
+}

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

@@ -1,11 +1,14 @@
 /**
- * The slice of a track's data these resolvers read. Every field is optional and untyped at the leaf
- * because the runtime objects come from different app layers (release metadata, effective owner
- * settings, per-user overrides, audio analysis). Resolvers coerce leaves with Number(...) and ignore
- * anything non-finite, so a permissive shape here is intentional — not every consumer fills every path.
+ * The slice of a track's data these resolvers read (tempo here; meter in `./clock/meter`). Every field
+ * is optional and untyped at the leaf because the runtime objects come from different app layers
+ * (release metadata, effective owner settings, per-user overrides, audio analysis). Resolvers coerce
+ * leaves with Number(...)/String(...) and ignore anything invalid, so a permissive shape here is
+ * intentional — not every consumer fills every path.
  */
 export interface SyncSettingsLike {
     trackBpm?: unknown;
+    /** Per-track time signature (e.g. `'4/4'` or `{ numerator, denominator }`) — see `./clock/meter`. */
+    meter?: unknown;
     primaryGridMarkerTimeSec?: unknown;
     gridMarkers?: ReadonlyArray<{
         sourceTimeSec?: unknown;
@@ -14,6 +17,8 @@ export interface SyncSettingsLike {
 }
 export interface TrackMetadataLike {
     trackBpm?: unknown;
+    /** Per-track time signature (owner canonical) — see `./clock/meter`. */
+    meter?: unknown;
     primaryGridMarkerTimeSec?: unknown;
     effectiveSettings?: {
         sync?: SyncSettingsLike | null;
@@ -21,6 +26,8 @@ export interface TrackMetadataLike {
     audioAnalysis?: {
         analysis?: {
             tempo_bpm?: unknown;
+            time_signature?: unknown;
+            timeSignature?: unknown;
         } | null;
     } | null;
     wrap?: {
@@ -33,11 +40,20 @@ export interface TrackMetadataLike {
 export interface TrackDataLike {
     track?: {
         metadata?: TrackMetadataLike | null;
+        effectiveSettings?: {
+            sync?: SyncSettingsLike | null;
+        } | null;
     } | null;
     release?: {
         metadata?: TrackMetadataLike | null;
+        effectiveSettings?: {
+            sync?: SyncSettingsLike | null;
+        } | null;
     } | null;
     metadata?: TrackMetadataLike | null;
+    effectiveSettings?: {
+        sync?: SyncSettingsLike | null;
+    } | null;
     trackUserSettings?: {
         sync?: SyncSettingsLike | null;
     } | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -25,6 +25,10 @@
       "types": "./dist/clock/track-metadata.d.ts",
       "import": "./dist/clock/track-metadata.js"
     },
+    "./clock/meter": {
+      "types": "./dist/clock/meter.d.ts",
+      "import": "./dist/clock/meter.js"
+    },
     "./clock/sync": {
       "types": "./dist/clock/sync.d.ts",
       "import": "./dist/clock/sync.js"

package/src/clock/meter.ts

@@ -0,0 +1,177 @@
+// ./clock/meter — time signature / meter model. A per-track musical property (how many beats make a
+// bar), resolved with the SAME owner → per-user → auto-detected → default precedence as the tempo
+// resolver in `./clock/track-metadata`. Promoted out of the orbiters app so EW reuses it verbatim.
+// Framework-free: no three, no react.
+//
+// Units: `sharedBeatsPerBar` is quarter-note beats per bar = numerator * 4 / denominator — the same
+// beat unit `MusicalProjection` (./clock/musical) counts, so a resolved meter feeds its `signatureMap`
+// directly: `{ startBar: 0, numerator, denominator }`.
+
+import type { TrackDataLike } from './track-metadata.js';
+
+export interface MeterPreset {
+  id: string;
+  numerator: number;
+  denominator: number;
+}
+
+/** Quick-pick reference meters. `id` is the persisted/display value, not a closed enum. */
+export const METER_PRESETS: MeterPreset[] = [
+  { id: '4/4', numerator: 4, denominator: 4 },
+  { id: '3/4', numerator: 3, denominator: 4 },
+  { id: '6/8', numerator: 6, denominator: 8 },
+];
+
+export const DEFAULT_METER_ID = '4/4';
+export const MIN_METER_NUMERATOR = 1;
+export const MAX_METER_NUMERATOR = 64;
+export const VALID_METER_DENOMINATORS: readonly number[] = [1, 2, 4, 8, 16, 32];
+
+const BY_ID = new Map(METER_PRESETS.map((m) => [m.id, m]));
+const DENOMINATORS = new Set(VALID_METER_DENOMINATORS);
+
+interface MeterFraction {
+  numerator: number;
+  denominator: number;
+}
+
+export interface ParsedMeter {
+  id: string;
+  numerator: number;
+  denominator: number;
+  beatsPerBar: number;
+  beatUnit: number;
+  sharedBeatsPerBar: number;
+  quarterBeatsPerBar: number;
+  clickIntervalQuarterBeats: number;
+  clicksPerBar: number;
+}
+
+function isValidNumerator(n: number): boolean {
+  return Number.isInteger(n) && n >= MIN_METER_NUMERATOR;
+}
+
+function isValidDenominator(n: number): boolean {
+  return Number.isInteger(n) && DENOMINATORS.has(n);
+}
+
+function parseMeterString(value: unknown): MeterFraction | null {
+  if (typeof value !== 'string') return null;
+  const match = value.trim().match(/^(\d+)\s*\/\s*(\d+)$/);
+  if (!match) return null;
+  const numerator = Number(match[1]);
+  const denominator = Number(match[2]);
+  if (!isValidNumerator(numerator) || !isValidDenominator(denominator)) return null;
+  return { numerator, denominator };
+}
+
+function parseMeterObject(value: unknown): MeterFraction | null {
+  if (!value || typeof value !== 'object') return null;
+  const numerator = Number((value as Record<string, unknown>).numerator);
+  const denominator = Number((value as Record<string, unknown>).denominator);
+  if (!isValidNumerator(numerator) || !isValidDenominator(denominator)) return null;
+  return { numerator, denominator };
+}
+
+export function formatMeterId(value: Partial<MeterFraction> = {}): string {
+  const n = Number(value.numerator);
+  const d = Number(value.denominator);
+  return isValidNumerator(n) && isValidDenominator(d) ? `${n}/${d}` : DEFAULT_METER_ID;
+}
+
+/** True when `value` is a valid arbitrary meter string or `{ numerator, denominator }`. */
+export function isValidMeterId(value: unknown): boolean {
+  return parseMeterString(value) !== null || parseMeterObject(value) !== null;
+}
+
+/** Normalize an arbitrary value to a persisted meter id (`n/d`), falling back to the default. */
+export function normalizeMeterId(value: unknown): string {
+  const parsed = parseMeterString(value) ?? parseMeterObject(value);
+  return parsed ? formatMeterId(parsed) : DEFAULT_METER_ID;
+}
+
+/**
+ * Resolve a meter id to its numbers, including `sharedBeatsPerBar` — the count of shared (quarter-note)
+ * beats in one bar, which is what the engine uses for the downbeat accent and the launch bar.
+ */
+export function parseMeter(value: unknown): ParsedMeter {
+  const id = normalizeMeterId(value);
+  const preset = BY_ID.get(id);
+  const parsed = preset ?? parseMeterString(id) ?? (parseMeterString(DEFAULT_METER_ID) as MeterFraction);
+  const numerator = parsed.numerator;
+  const denominator = parsed.denominator;
+  const sharedBeatsPerBar = (numerator * 4) / denominator;
+  const clickIntervalQuarterBeats = 4 / denominator;
+  return {
+    id,
+    numerator,
+    denominator,
+    beatsPerBar: numerator,
+    beatUnit: denominator,
+    sharedBeatsPerBar,
+    quarterBeatsPerBar: sharedBeatsPerBar,
+    clickIntervalQuarterBeats,
+    clicksPerBar: numerator,
+  };
+}
+
+function resolveAnalysisMeter(analysis: unknown): string | null {
+  if (!analysis || typeof analysis !== 'object') return null;
+  const a = analysis as Record<string, any>;
+  const candidates = [
+    a.time_signature,
+    a.timeSignature,
+    a.meter,
+    a.time_signature?.meter,
+    a.timeSignature?.meter,
+    a.time_signature?.value,
+    a.timeSignature?.value,
+  ];
+  for (const candidate of candidates) {
+    if (isValidMeterId(candidate)) {
+      return normalizeMeterId(candidate);
+    }
+  }
+  return null;
+}
+
+/** Shared (quarter-note) beats per bar for a meter id — the engine's bar length. */
+export function sharedBeatsPerBar(id: unknown): number {
+  return parseMeter(id).sharedBeatsPerBar;
+}
+
+/**
+ * Resolve the per-track meter from assembled track data — the LOAD side, walking the SAME precedence
+ * as the shared tempo resolver (`resolveTrackBpmFromTrackData`): owner CANONICAL first, then the
+ * per-user override, then auto-detected analysis, then the default. First valid wins:
+ *   1) owner canonical  — `metadata.meter` → `metadata.effectiveSettings.sync.meter`
+ *   2) per-user         — `trackUserSettings.sync.meter`
+ *   3) auto-detected    — `metadata.audioAnalysis.analysis` time signature
+ *   4) default (4/4)
+ */
+export function resolveTrackMeterFromTrackData(trackData: TrackDataLike | null = null): string {
+  const td = trackData;
+  const candidates = [
+    // 1) owner canonical — top-level metadata (mirrors tempo's `metadata.trackBpm`)
+    td?.track?.metadata?.meter,
+    td?.release?.metadata?.meter,
+    td?.metadata?.meter,
+    // 1) owner canonical — effectiveSettings (mirrors tempo's `effectiveSettings.sync.trackBpm`)
+    td?.track?.metadata?.effectiveSettings?.sync?.meter,
+    td?.release?.metadata?.effectiveSettings?.sync?.meter,
+    td?.metadata?.effectiveSettings?.sync?.meter,
+    td?.track?.effectiveSettings?.sync?.meter,
+    td?.release?.effectiveSettings?.sync?.meter,
+    td?.effectiveSettings?.sync?.meter,
+    // 2) per-user override (mirrors tempo's `trackUserSettings.sync.trackBpm`)
+    td?.trackUserSettings?.sync?.meter,
+    // 3) auto-detected analysis (mirrors tempo's `audioAnalysis.analysis.tempo_bpm`)
+    resolveAnalysisMeter(td?.track?.metadata?.audioAnalysis?.analysis),
+    resolveAnalysisMeter(td?.release?.metadata?.audioAnalysis?.analysis),
+    resolveAnalysisMeter(td?.metadata?.audioAnalysis?.analysis),
+  ];
+  for (const c of candidates) {
+    if (isValidMeterId(c)) return normalizeMeterId(c);
+  }
+  return DEFAULT_METER_ID;
+}

package/src/clock/track-metadata.ts

@@ -5,13 +5,16 @@
 // startSec: gridSec, bpm }] })`. Promoted out of the orbiters app (ORB-137) so EW reuses it verbatim.
 
 /**
- * The slice of a track's data these resolvers read. Every field is optional and untyped at the leaf
- * because the runtime objects come from different app layers (release metadata, effective owner
- * settings, per-user overrides, audio analysis). Resolvers coerce leaves with Number(...) and ignore
- * anything non-finite, so a permissive shape here is intentional — not every consumer fills every path.
+ * The slice of a track's data these resolvers read (tempo here; meter in `./clock/meter`). Every field
+ * is optional and untyped at the leaf because the runtime objects come from different app layers
+ * (release metadata, effective owner settings, per-user overrides, audio analysis). Resolvers coerce
+ * leaves with Number(...)/String(...) and ignore anything invalid, so a permissive shape here is
+ * intentional — not every consumer fills every path.
  */
 export interface SyncSettingsLike {
   trackBpm?: unknown;
+  /** Per-track time signature (e.g. `'4/4'` or `{ numerator, denominator }`) — see `./clock/meter`. */
+  meter?: unknown;
   primaryGridMarkerTimeSec?: unknown;
   gridMarkers?: ReadonlyArray<{ sourceTimeSec?: unknown } | null | undefined> | null;
   gridStartTimeSec?: unknown;
@@ -19,9 +22,13 @@ export interface SyncSettingsLike {
 
 export interface TrackMetadataLike {
   trackBpm?: unknown;
+  /** Per-track time signature (owner canonical) — see `./clock/meter`. */
+  meter?: unknown;
   primaryGridMarkerTimeSec?: unknown;
   effectiveSettings?: { sync?: SyncSettingsLike | null } | null;
-  audioAnalysis?: { analysis?: { tempo_bpm?: unknown } | null } | null;
+  audioAnalysis?: {
+    analysis?: { tempo_bpm?: unknown; time_signature?: unknown; timeSignature?: unknown } | null;
+  } | null;
   wrap?: {
     gridMarkers?: ReadonlyArray<{ sourceTimeSec?: unknown } | null | undefined> | null;
     gridStartTimeSec?: unknown;
@@ -29,9 +36,16 @@ export interface TrackMetadataLike {
 }
 
 export interface TrackDataLike {
-  track?: { metadata?: TrackMetadataLike | null } | null;
-  release?: { metadata?: TrackMetadataLike | null } | null;
+  track?: {
+    metadata?: TrackMetadataLike | null;
+    effectiveSettings?: { sync?: SyncSettingsLike | null } | null;
+  } | null;
+  release?: {
+    metadata?: TrackMetadataLike | null;
+    effectiveSettings?: { sync?: SyncSettingsLike | null } | null;
+  } | null;
   metadata?: TrackMetadataLike | null;
+  effectiveSettings?: { sync?: SyncSettingsLike | null } | null;
   trackUserSettings?: { sync?: SyncSettingsLike | null } | null;
 }