@motionstudies/core 0.1.0-alpha.20 → 0.1.0-alpha.22

package/README.md

@@ -255,3 +255,13 @@ Render support as opacity or reach, not as confidence in the underlying measurem
 `@motionstudies/core/domain/daylight` computes `solarPosition` (altitude and azimuth in degrees, azimuth clockwise from north) from the Astronomy Answers low-precision algorithm, matching SunCalc to a thousandth of a degree without a dependency. `daylightAt` adds a unit `direction` towards the sun in a scene frame with +x east, +y up and +z south, and smooth `twilight`, `warmth` and `daylight` envelopes from `DaylightEnvelopes` (defaults: twilight −18° to −1°, warmth rising −12° to −1° and falling 3° to 15°, daylight −1° to 12°). The envelopes are artistic responses to sun altitude and encode no weather or sky observation. Sample several longitudes to place a terminator across a national field.
 
 The lab's **Fields** specimen renders a synthetic archipelago of seven instruments with a mid-study gap and one vectorless instrument, an invented cover series as haze, integrated trails, and a terminator crossing with the study clock. Brightness is the estimate and opacity is support; clicking reads the estimate, cover and sun altitude at a place.
+
+## Recorded power days
+
+`@motionstudies/core/domain/power-day` exports `readPowerDay`, `powerPeriod`, `unitPower`, `plannedPower`, `sumPower` and `fuelMixAt`, plus their data types. A complete civil day declares its timezone, UTC bounds, half-hour intervals, MWh settlement quantities and MW plans/aggregates. Missing values remain null; signed quantities remain signed. Interval energy becomes average power only through the explicit interval duration. Declarations are interpolated only within one unambiguous segment; fuel samples expire after five minutes. Callers choose aggregate membership and receive a missing-contributor count. The reader validates source links, settlement run labels, identities, placement coordinates and safe evidence-artifact paths without fetching data. Source adapters, placement policy and the composition stay outside core. See [power ownership](../docs/POWER.md#ownership-and-handoff).
+
+## Activity timeline
+
+`@motionstudies/core/timeline` supplies validated interval geometry, lookup, time mapping and service-time formatting. `@motionstudies/web/components/StudyTimeline` renders a controlled activity chart and scrubber; import `@motionstudies/web/study-timeline.css`. Pass `bins: {start, end, value}[]`, the time window, current `time` and `onSeek`. A `null` value means missing evidence; zero is a measured zero. `variant="bars"` (default) or `"line"` shares the same time axis. `maximum` optionally fixes the scale for comparisons. Playback and loading remain consumer-owned. See [the full contract](https://github.com/emmettl/motionstudies/blob/main/docs/STUDY-TIMELINE.md) and the Timeline lab specimen.
+
+Canvas editions can import `PausedVehicleFrame` from `@motionstudies/core/render-frame` without loading Three.js. The existing Three.js entry point re-exports the same class. Record only a frame actually submitted; change its visibility revision (or replace the tracker) when data, projection, size or selection changes. Time changes invalidate even while paused.

package/domain/power-day.d.ts

@@ -0,0 +1,84 @@
+/** Dated electricity evidence. All times are elapsed UTC seconds from startUtc.
+ * Settlement is interval energy (MWh); plans and national aggregates are power (MW).
+ * Geography, population selection and placement policy belong to the consuming work.
+ */
+export interface PowerSource {
+    sha256: string;
+    url: string;
+    retrievedAt: string;
+    publisher: string;
+}
+export interface PowerPlacement {
+    method: 'site' | 'connection' | 'curated' | 'aggregate' | 'interconnector' | 'unplaced';
+    latitude?: number;
+    longitude?: number;
+    note?: string | null;
+    source?: string | null;
+    score?: number;
+    matched?: Record<string, unknown>;
+}
+export interface PowerUnit {
+    id: string;
+    name: string;
+    fuelType: string | null;
+    capacityMw: number | null;
+    settledMwh: (number | null)[];
+    runs: (string | null)[];
+    /** [start, end, start MW, end MW]; half-open intervals, no extrapolation. */
+    plan: [number, number, number, number][];
+    placement?: PowerPlacement;
+    evidence?: {
+        path: string;
+        sha256: string;
+        bytes: number;
+    };
+}
+export interface PowerDay {
+    kind: 'power-day';
+    schemaVersion: 1;
+    date: string;
+    timezone: string;
+    startUtc: string;
+    endUtc: string;
+    periodSeconds: 1800;
+    quantityUnit: 'MWh';
+    powerUnit: 'MW';
+    scope: string;
+    population: string;
+    units: PowerUnit[];
+    demandMw: (number | null)[];
+    fuelMix: {
+        time: number;
+        byFuel: Record<string, number | null>;
+    }[];
+    settlementSources: string[];
+    planSources: string[];
+    sources: PowerSource[];
+    attribution: {
+        statement: string;
+        licence: string;
+    }[];
+}
+/** Validate untrusted JSON at both publication and browser boundaries. Does not fetch. */
+export declare function readPowerDay(value: unknown): PowerDay;
+export declare function powerPeriod(day: PowerDay, seconds: number): number | null;
+/** Return null for a gap or ambiguous overlapping declarations, never infer a plan. */
+export declare function plannedPower(unit: PowerUnit, seconds: number): number | null;
+export declare function unitPower(day: PowerDay, unit: PowerUnit, seconds: number): {
+    period: number | null;
+    settledMwh: number | null;
+    averageMw: number | null;
+    plannedMw: number | null;
+    run: string | null;
+};
+/** Membership is supplied by the work; report missing contributors alongside partial sums. */
+export declare function sumPower(day: PowerDay, units: readonly PowerUnit[], seconds: number): {
+    averageMw: number | null;
+    available: number;
+    missing: number;
+};
+/** Last national sample, valid for at most five minutes and never outside this day. */
+export declare function fuelMixAt(day: PowerDay, seconds: number): {
+    time: number;
+    byFuel: Record<string, number | null>;
+} | null;

package/domain/power-day.js

@@ -0,0 +1,104 @@
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+const nullable = (v) => v === null || finite(v);
+const hash = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const nonempty = (v) => typeof v === 'string' && v.length > 0;
+const utc = (v) => typeof v === 'string' && /Z$/.test(v) && Number.isFinite(Date.parse(v));
+function requireValue(ok, message) { if (!ok)
+    throw new Error(`Invalid power day: ${message}`); }
+/** Validate untrusted JSON at both publication and browser boundaries. Does not fetch. */
+export function readPowerDay(value) {
+    requireValue(object(value), 'expected object');
+    const d = value;
+    requireValue(d.kind === 'power-day' && d.schemaVersion === 1, 'schema');
+    requireValue(nonempty(d.timezone) && typeof d.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(d.date), 'date/timezone');
+    requireValue(utc(d.startUtc) && utc(d.endUtc), 'UTC bounds');
+    const duration = (Date.parse(d.endUtc) - Date.parse(d.startUtc)) / 1000, periods = duration / 1800;
+    requireValue([46, 48, 50].includes(periods) && d.periodSeconds === 1800, 'civil-day intervals');
+    // A power day is a complete civil day, including both clock-change days.
+    const dateAt = (t) => new Intl.DateTimeFormat('en-CA', { timeZone: d.timezone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(t);
+    const midnight = (t) => new Intl.DateTimeFormat('en-GB', { timeZone: d.timezone, hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23' }).format(t) === '00:00:00';
+    requireValue(dateAt(Date.parse(d.startUtc)) === d.date && midnight(Date.parse(d.startUtc)) && midnight(Date.parse(d.endUtc)) && dateAt(Date.parse(d.endUtc) - 1) === d.date, 'civil date');
+    requireValue(d.quantityUnit === 'MWh' && d.powerUnit === 'MW', 'explicit units');
+    requireValue(nonempty(d.scope) && nonempty(d.population), 'scope/population');
+    requireValue(Array.isArray(d.sources) && d.sources.length > 0, 'sources');
+    const hashes = new Set();
+    for (const s of d.sources) {
+        requireValue(object(s) && hash(s.sha256) && nonempty(s.publisher) && utc(s.retrievedAt) && typeof s.url === 'string' && /^https:\/\//.test(s.url), 'source record');
+        requireValue(!hashes.has(s.sha256), 'duplicate source');
+        hashes.add(s.sha256);
+    }
+    for (const key of ['settlementSources', 'planSources'])
+        requireValue(Array.isArray(d[key]) && d[key].length === periods && d[key].every((h) => typeof h === 'string' && hashes.has(h)), `${key} linkage`);
+    requireValue(Array.isArray(d.attribution) && d.attribution.length > 0 && d.attribution.every(a => object(a) && nonempty(a.statement) && typeof a.licence === 'string' && /^https:\/\//.test(a.licence)), 'attribution');
+    requireValue(Array.isArray(d.demandMw) && d.demandMw.length === periods && d.demandMw.every(nullable), 'demand');
+    requireValue(Array.isArray(d.fuelMix), 'fuel mix');
+    let previous = -Infinity;
+    for (const f of d.fuelMix) {
+        requireValue(object(f) && finite(f.time) && f.time >= 0 && f.time < duration && f.time > previous && object(f.byFuel) && Object.values(f.byFuel).every(nullable), 'fuel mix samples');
+        previous = f.time;
+    }
+    requireValue(Array.isArray(d.units), 'units');
+    const ids = new Set();
+    for (const u of d.units) {
+        requireValue(object(u) && nonempty(u.id) && !ids.has(u.id) && nonempty(u.name), 'unit identity');
+        ids.add(u.id);
+        requireValue((u.fuelType === null || nonempty(u.fuelType)) && nullable(u.capacityMw), 'unit register');
+        requireValue(Array.isArray(u.settledMwh) && u.settledMwh.length === periods && u.settledMwh.every(nullable), 'settlement values');
+        const settledMwh = u.settledMwh;
+        requireValue(Array.isArray(u.runs) && u.runs.length === periods && u.runs.every((r, i) => settledMwh[i] === null ? r === null : ['II', 'SF', 'R1', 'R2', 'R3', 'RF', 'DF'].includes(r)), 'settlement runs');
+        requireValue(Array.isArray(u.plan) && u.plan.every(p => Array.isArray(p) && p.length === 4 && p.every(finite) && p[0] >= 0 && p[1] <= duration && p[1] > p[0]), 'declared segments');
+        if (u.placement !== undefined) {
+            const p = u.placement;
+            requireValue(object(p) && ['site', 'connection', 'curated', 'aggregate', 'interconnector', 'unplaced'].includes(String(p.method)), 'placement method');
+            const located = ['site', 'connection', 'curated'].includes(String(p.method));
+            requireValue(located ? finite(p.latitude) && Math.abs(p.latitude) <= 90 && finite(p.longitude) && Math.abs(p.longitude) <= 180 : p.latitude === undefined && p.longitude === undefined, 'placement coordinates');
+            if (p.method === 'curated')
+                requireValue(nonempty(p.source), 'curated citation');
+        }
+        if (u.evidence !== undefined) {
+            const e = u.evidence;
+            requireValue(object(e) && typeof e.path === 'string' && /^evidence\/[a-f0-9]{64}\.json$/.test(e.path) && hash(e.sha256) && Number.isSafeInteger(e.bytes) && Number(e.bytes) > 0, 'evidence artifact');
+        }
+    }
+    return value;
+}
+export function powerPeriod(day, seconds) {
+    return Number.isFinite(seconds) && seconds >= 0 && seconds < day.demandMw.length * day.periodSeconds ? Math.floor(seconds / day.periodSeconds) : null;
+}
+/** Return null for a gap or ambiguous overlapping declarations, never infer a plan. */
+export function plannedPower(unit, seconds) {
+    const segments = unit.plan.filter(p => seconds >= p[0] && seconds < p[1]);
+    if (segments.length !== 1)
+        return null;
+    const [start, end, a, b] = segments[0];
+    return a + (b - a) * (seconds - start) / (end - start);
+}
+export function unitPower(day, unit, seconds) {
+    const period = powerPeriod(day, seconds), mwh = period === null ? null : unit.settledMwh[period];
+    return { period, settledMwh: mwh, averageMw: mwh === null ? null : mwh * 3600 / day.periodSeconds, plannedMw: period === null ? null : plannedPower(unit, seconds), run: period === null ? null : unit.runs[period] };
+}
+/** Membership is supplied by the work; report missing contributors alongside partial sums. */
+export function sumPower(day, units, seconds) {
+    let averageMw = 0, available = 0;
+    for (const unit of units) {
+        const value = unitPower(day, unit, seconds).averageMw;
+        if (value !== null) {
+            averageMw += value;
+            available++;
+        }
+    }
+    return { averageMw: available ? averageMw : null, available, missing: units.length - available };
+}
+/** Last national sample, valid for at most five minutes and never outside this day. */
+export function fuelMixAt(day, seconds) {
+    if (powerPeriod(day, seconds) === null)
+        return null;
+    let sample;
+    for (let i = day.fuelMix.length - 1; i >= 0; i--)
+        if (day.fuelMix[i].time <= seconds) {
+            sample = day.fuelMix[i];
+            break;
+        }
+    return sample && seconds - sample.time < 300 ? sample : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -204,6 +204,21 @@
       "types": "./domain/daylight.d.ts",
       "import": "./domain/daylight.js",
       "default": "./domain/daylight.js"
+    },
+    "./domain/power-day": {
+      "types": "./domain/power-day.d.ts",
+      "import": "./domain/power-day.js",
+      "default": "./domain/power-day.js"
+    },
+    "./timeline": {
+      "types": "./timeline.d.ts",
+      "import": "./timeline.js",
+      "default": "./timeline.js"
+    },
+    "./render-frame": {
+      "types": "./render-frame.d.ts",
+      "import": "./render-frame.js",
+      "default": "./render-frame.js"
     }
   },
   "files": [

package/render-frame.d.ts

@@ -0,0 +1,8 @@
+/** Track the last submitted buffers, not the last animation callback. Create a
+ * fresh tracker when geometry, projection, data or selection inputs change. */
+export declare class PausedVehicleFrame {
+    private time;
+    private visibility;
+    needsUpdate(isPlaying: boolean, time: number, visibility: number): boolean;
+    record(time: number, visibility: number): void;
+}

package/render-frame.js

@@ -0,0 +1,13 @@
+/** Track the last submitted buffers, not the last animation callback. Create a
+ * fresh tracker when geometry, projection, data or selection inputs change. */
+export class PausedVehicleFrame {
+    time = NaN;
+    visibility = NaN;
+    needsUpdate(isPlaying, time, visibility) {
+        return isPlaying || this.time !== time || this.visibility !== visibility;
+    }
+    record(time, visibility) {
+        this.time = time;
+        this.visibility = visibility;
+    }
+}

package/timeline.d.ts

@@ -0,0 +1,31 @@
+/** A measured interval. Null means missing evidence; zero is a measured zero. */
+export interface TimelineBin {
+    start: number;
+    end: number;
+    value: number | null;
+}
+export interface TimelineWindow {
+    start: number;
+    end: number;
+}
+export interface TimelineBar extends TimelineBin {
+    x: number;
+    width: number;
+    height: number;
+}
+export interface TimelineModel {
+    window: TimelineWindow;
+    maximum: number;
+    bars: TimelineBar[];
+    lines: {
+        x: number;
+        y: number;
+    }[][];
+}
+export declare function timelinePosition(time: number, window: TimelineWindow): number;
+export declare function timelineTime(position: number, window: TimelineWindow, step?: number): number;
+/** Build chart geometry once per series, independently of playback and rendering. */
+export declare function createTimelineModel(bins: readonly TimelineBin[], window: TimelineWindow, maximum?: number): TimelineModel;
+export declare function timelineBinAt(model: TimelineModel, time: number): TimelineBar | undefined;
+/** Service time, including 24:00 and times beyond midnight; no timezone inference. */
+export declare function formatTimelineTime(seconds: number): string;

package/timeline.js

@@ -0,0 +1,68 @@
+function checkWindow(window) {
+    if (!Number.isFinite(window.start) || !Number.isFinite(window.end) || window.end <= window.start)
+        throw new Error('Timeline needs a finite, increasing window');
+}
+export function timelinePosition(time, window) {
+    checkWindow(window);
+    return Number.isFinite(time) ? Math.max(0, Math.min(1, (time - window.start) / (window.end - window.start))) : 0;
+}
+export function timelineTime(position, window, step = 1) {
+    checkWindow(window);
+    if (!Number.isFinite(step) || step <= 0)
+        throw new Error('Timeline step must be positive');
+    const fraction = Number.isFinite(position) ? Math.max(0, Math.min(1, position)) : 0;
+    return Math.min(window.end, window.start + Math.round(fraction * (window.end - window.start) / step) * step);
+}
+/** Build chart geometry once per series, independently of playback and rendering. */
+export function createTimelineModel(bins, window, maximum) {
+    checkWindow(window);
+    if (maximum !== undefined && (!Number.isFinite(maximum) || maximum < 0))
+        throw new Error('Timeline maximum must be non-negative');
+    const sorted = [...bins].sort((a, b) => a.start - b.start);
+    let previous = -Infinity;
+    for (const bin of sorted) {
+        if (!Number.isFinite(bin.start) || !Number.isFinite(bin.end) || bin.end <= bin.start || bin.start < previous)
+            throw new Error('Timeline bins must be finite, increasing and non-overlapping');
+        if (bin.value !== null && (!Number.isFinite(bin.value) || bin.value < 0))
+            throw new Error('Timeline values must be non-negative or null');
+        previous = bin.end;
+    }
+    const visible = sorted.filter(bin => bin.end > window.start && bin.start < window.end);
+    const peak = maximum ?? visible.reduce((value, bin) => Math.max(value, bin.value ?? 0), 0);
+    const bars = visible.map(bin => {
+        const start = Math.max(window.start, bin.start), end = Math.min(window.end, bin.end);
+        return { ...bin, start, end, x: timelinePosition(start, window), width: (end - start) / (window.end - window.start), height: peak > 0 && bin.value !== null ? Math.min(1, bin.value / peak) : 0 };
+    });
+    const lines = [];
+    let line = [], lastEnd = -Infinity;
+    for (const bar of bars) {
+        if (bar.value === null || bar.start !== lastEnd) {
+            if (line.length)
+                lines.push(line);
+            line = [];
+        }
+        if (bar.value !== null)
+            line.push({ x: bar.x + bar.width / 2, y: 1 - bar.height });
+        lastEnd = bar.end;
+    }
+    if (line.length)
+        lines.push(line);
+    return { window: { ...window }, maximum: peak, bars, lines };
+}
+export function timelineBinAt(model, time) {
+    let lo = 0, hi = model.bars.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (model.bars[mid].start <= time)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    const bin = model.bars[lo - 1];
+    return bin && time < bin.end ? bin : undefined;
+}
+/** Service time, including 24:00 and times beyond midnight; no timezone inference. */
+export function formatTimelineTime(seconds) {
+    const minutes = Math.floor(Math.max(0, Number.isFinite(seconds) ? seconds : 0) / 60);
+    return `${String(Math.floor(minutes / 60)).padStart(2, '0')}:${String(minutes % 60).padStart(2, '0')}`;
+}