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

package/README.md

@@ -259,3 +259,9 @@ The lab's **Fields** specimen renders a synthetic archipelago of seven instrumen
 ## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.22",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -209,6 +209,16 @@
       "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')}`;
+}