@camstack/ui-library 1.1.16 → 1.1.17

package/dist/lib/index.d.ts

@@ -10,3 +10,7 @@ export { PHASE_CONFIG, getPhaseVisual } from './phase-config';
 export type { PhaseVisual } from './phase-config';
 export { createSharedContext } from './shared-context';
 export { ensureMfHostInit } from './mf-runtime-init';
+export { serializeRecordedCommand, parseRecordedServerMessage, RECORDED_PLAYBACK_MODES, } from './recorded-control-protocol';
+export type { RecordedControlCommand, RecordedPlaybackMode, RecordedServerMessage, } from './recorded-control-protocol';
+export { scrubReducer, initialScrubState, shouldEmit, shouldCommit, cursorFractionFor, makeScrubBridge, useScrubController, COMMIT_DEDUPE_TOLERANCE_MS, COMMIT_DEDUPE_WINDOW_MS, } from './scrub-controller';
+export type { ScrubSource, ScrubState, ScrubAction, ScrubController, PlaybackControlSink, LastCommit, } from './scrub-controller';

package/dist/lib/recorded-control-protocol.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Client-side wire codec for the `camstack-control` RTCDataChannel (R9).
+ *
+ * Mirrors the broker's `control-protocol.ts`
+ * (packages/addon-pipeline/src/stream-broker/recorded/control-protocol.ts):
+ * client→server commands drive the per-viewer `TimelineSession` /
+ * `RecordedFeeder` (frame-push recorded playback on the SAME WebRTC session
+ * as live video); server→client messages report playback state + a ~1 Hz
+ * position. Shapes are re-declared here (not imported) because ui-library
+ * cannot depend on an addon package — the embed SPA does the same.
+ *
+ * Parsing is defensive: a malformed frame returns `null`, never throws, so a
+ * bad datachannel message can't take down the player.
+ */
+export type RecordedControlCommand = {
+    readonly t: 'playRecorded';
+    readonly deviceId: number;
+    readonly epoch: number;
+    readonly profile: string;
+} | {
+    readonly t: 'seek';
+    readonly epoch: number;
+} | {
+    readonly t: 'scrubCommit';
+    readonly epoch: number;
+} | {
+    readonly t: 'setRate';
+    readonly rate: 0 | 1;
+} | {
+    readonly t: 'goLive';
+} | {
+    readonly t: 'setProfile';
+    readonly profile: string;
+};
+/** Serialize a command for `RTCDataChannel.send` (matches the server schema). */
+export declare function serializeRecordedCommand(cmd: RecordedControlCommand): string;
+/**
+ * Playback mode reported by the server session. `live` = the shared live feed
+ * owns the track; every other value describes the recorded feeder.
+ */
+export declare const RECORDED_PLAYBACK_MODES: readonly ["live", "loading", "playing", "paused", "gap", "ended", "error"];
+export type RecordedPlaybackMode = (typeof RECORDED_PLAYBACK_MODES)[number];
+export type RecordedServerMessage = {
+    readonly kind: 'state';
+    readonly state: RecordedPlaybackMode;
+} | {
+    readonly kind: 'position';
+    readonly epochMs: number;
+};
+/**
+ * Parse a raw server→client control frame. Returns `null` on any malformed
+ * payload (bad JSON, unknown discriminator, wrong field types).
+ */
+export declare function parseRecordedServerMessage(raw: string): RecordedServerMessage | null;

package/dist/lib/scrub-controller.d.ts

@@ -0,0 +1,115 @@
+export type ScrubSource = 'timeline' | 'heatmap';
+export interface ScrubState {
+    readonly scrubbing: boolean;
+    readonly scrubEpoch: number | null;
+    readonly playheadEpoch: number | null;
+    readonly lastSource: ScrubSource | null;
+}
+export declare const initialScrubState: ScrubState;
+export type ScrubAction = {
+    readonly type: 'begin';
+    readonly source: ScrubSource;
+} | {
+    readonly type: 'update';
+    readonly epoch: number;
+    readonly source: ScrubSource;
+} | {
+    readonly type: 'end';
+    readonly epoch: number;
+    readonly source: ScrubSource;
+} | {
+    readonly type: 'seek';
+    readonly epoch: number;
+    readonly source: ScrubSource;
+} | {
+    readonly type: 'playhead';
+    readonly epoch: number;
+} | {
+    readonly type: 'reset';
+};
+export declare function scrubReducer(state: ScrubState, action: ScrubAction): ScrubState;
+/**
+ * Throttle decision for continuous `update` emits (default ~70 ms).
+ * Returns true when enough time has elapsed since the last emit.
+ */
+export declare function shouldEmit(lastEmitMs: number, now: number, throttleMs?: number): boolean;
+/** The last committed target (epoch + wall-clock of the commit). */
+export interface LastCommit {
+    readonly epoch: number;
+    readonly at: number;
+}
+/** Epochs within this many ms of the last commit count as the SAME target. */
+export declare const COMMIT_DEDUPE_TOLERANCE_MS = 750;
+/** Only dedupe against a commit made within this recent window. */
+export declare const COMMIT_DEDUPE_WINDOW_MS = 2000;
+/**
+ * Decide whether a `seek`/`scrubCommit` should actually hit the playback sink.
+ * Each commit reloads the server feeder (loading→playing) and visibly stutters
+ * playback; firing the same (or a near-identical) target twice in quick
+ * succession produces a redundant reload. Drop a commit only when it targets
+ * essentially the SAME epoch as the last commit AND that commit was recent — a
+ * genuinely different target, or a re-seek to the same spot after the window,
+ * always commits.
+ */
+export declare function shouldCommit(last: LastCommit | null, epoch: number, now: number, toleranceMs?: number, windowMs?: number): boolean;
+/**
+ * The active cursor position (scrub target while scrubbing, else playhead)
+ * expressed as a 0..1 fraction across the day window.
+ * Returns null when no position is known or the day window is degenerate.
+ */
+export declare function cursorFractionFor(state: ScrubState, day: {
+    readonly from: number;
+    readonly to: number;
+}): number | null;
+/**
+ * Generic, always-active playback control surface the scrub controller
+ * drives. `scrubStart`/`scrubTo` are CLIENT-SIDE hooks (the wire protocol has
+ * no per-move scrub message — a future WebCodecs preview consumes them);
+ * `scrubCommit`/`seek` reach the server feeder.
+ */
+export interface PlaybackControlSink {
+    scrubStart(): void;
+    scrubTo(epochMs: number): void;
+    scrubCommit(epochMs: number): void;
+    seek(epochMs: number): void;
+}
+/** A mutable holder, structurally compatible with React's `MutableRefObject`. */
+export interface MutableRef<T> {
+    current: T;
+}
+/** The gesture callbacks the hook exposes (everything except `state`). */
+type ScrubBridge = Omit<ScrubController, 'state'>;
+/**
+ * Builds the always-active bridge callbacks from a sink, a dispatch, and the
+ * throttle ref. Pure (no React) so it can be unit-tested directly: the hook
+ * just wraps the result in `useMemo`.
+ *
+ * Every gesture drives the sink immediately — there is no VOD-active gate.
+ */
+export declare function makeScrubBridge(sink: PlaybackControlSink, dispatch: (action: ScrubAction) => void, lastEmitRef: MutableRef<number>, lastCommitRef?: MutableRef<LastCommit | null>, 
+/** Reports whether the PLAYER is currently on the live edge (not in recorded
+ *  mode). Used to bypass commit-dedupe on the live→recorded transition. */
+isPlayerLive?: () => boolean): ScrubBridge;
+export interface ScrubController {
+    readonly state: ScrubState;
+    readonly beginScrub: (source: ScrubSource) => void;
+    readonly updateScrub: (epoch: number, source: ScrubSource) => void;
+    readonly endScrub: (epoch: number, source: ScrubSource) => void;
+    readonly seek: (epoch: number, source: ScrubSource) => void;
+    readonly setPlayhead: (epoch: number) => void;
+    readonly reset: () => void;
+}
+/**
+ * Owns the shared scrub position and bridges it to a playback control sink.
+ *
+ * The bridge is always active: any gesture (drag or tap) drives the sink
+ * immediately. There is no VOD-active gate — the timeline always drives
+ * playback while frame-push mode is on.
+ *
+ * @param sink Always-active playback control surface (e.g. the datachannel)
+ * @param isPlayerLive Synchronous getter for "is the player on the live
+ *   edge?" — lets a live→recorded commit bypass dedupe so the seek always
+ *   reaches the server.
+ */
+export declare function useScrubController(sink: PlaybackControlSink, isPlayerLive?: () => boolean): ScrubController;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/ui-library",
-  "version": "1.1.16",
+  "version": "1.1.17",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",