fix(lab): enforce canonical replay runtime

2026-08-29 22:42:30 +03:00
parent 525ab74168
commit bd2892140f
17 changed files with 1765 additions and 507 deletions
@@ -781,6 +781,8 @@ export function RecordedFmp4Player({
  onAdmissionChange,
  onPlaybackChange,
  onPlayingRejected,
+  playbackAuthority = "media",
+  playbackTransport = "segmented",
 }: {
  source: ObservationSourceDescriptor;
  playback?: RecordedObservationPlayback | null;
@@ -793,6 +795,8 @@ export function RecordedFmp4Player({
  onAdmissionChange?: (state: RecordedCameraAdmissionState) => void;
  onPlaybackChange?: (playback: RecordedObservationPlayback) => void;
  onPlayingRejected?: () => void;
+  playbackAuthority?: "media" | "host";
+  playbackTransport?: "segmented" | "epoch-stream";
 }) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const onAdmissionChangeRef = useRef(onAdmissionChange);
@@ -888,7 +892,8 @@ export function RecordedFmp4Player({
    && effectiveSegmentSequence !== requestedSegmentSequence,
  );
  const segmented = Boolean(
-    requestedSegmentSequence !== null
+    playbackTransport === "segmented"
+    && requestedSegmentSequence !== null
    && Number.isInteger(requestedSegmentSequence)
    && requestedSegmentSequence >= 1
    &&
@@ -1201,6 +1206,11 @@ export function RecordedFmp4Player({
          || segmentedRuntimeRef.current !== runtime
          || runtime.target?.revision !== revision
        ) return;
+        // Canonical recorded LABs run one host-owned clock for camera and
+        // spatial evidence. A transient MSE play() rejection (commonly a
+        // pause/reset race while the next fragment is admitted) must stay a
+        // decoder concern: the rolling target will retry and catch up.
+        if (playbackAuthority === "host") return;
        onPlayingRejectedRef.current?.();
        setReadyGeneration(null);
        setErrorMessage("Запуск записанной камеры отклонён браузером.");
@@ -1311,7 +1321,13 @@ export function RecordedFmp4Player({
      if (targetReadyAbortRef.current === targetReadyAbort) targetReadyAbortRef.current = null;
      if (runtime.onTargetBuffered === markBuffered) runtime.onTargetBuffered = null;
    };
-  }, [archive?.byteLength, effectiveSegmentSequence, segmented, segmentedRuntimeGeneration]);
+  }, [
+    archive?.byteLength,
+    effectiveSegmentSequence,
+    playbackAuthority,
+    segmented,
+    segmentedRuntimeGeneration,
+  ]);

  useEffect(() => {
    const video = videoRef.current;
@@ -1407,6 +1423,7 @@ export function RecordedFmp4Player({
    if (playback?.playing && !holdingForSegmentRecovery) {
      void video.play().catch(() => {
        if (playAttemptRevisionRef.current !== playAttemptRevision) return;
+        if (playbackAuthority === "host") return;
        onPlayingRejectedRef.current?.();
        setReadyGeneration(null);
        setErrorMessage("Запуск записанной камеры отклонён браузером.");
@@ -1427,6 +1444,7 @@ export function RecordedFmp4Player({
    epoch,
    holdingForSegmentRecovery,
    playback?.playing,
+    playbackAuthority,
    playbackRate,
    segmented,
    visualState,
@@ -1454,6 +1472,7 @@ export function RecordedFmp4Player({
      video.playbackRate = playbackRateRef.current;
      void video.play().catch(() => {
        if (cancelled || playAttemptRevisionRef.current !== playAttemptRevision) return;
+        if (playbackAuthority === "host") return;
        onPlayingRejectedRef.current?.();
      });
    };
@@ -1465,7 +1484,7 @@ export function RecordedFmp4Player({
      cancelled = true;
      for (const event of events) video.removeEventListener(event, queueResume);
    };
-  }, [bufferRevision, playback?.playing, segmented, visualState]);
+  }, [bufferRevision, playback?.playing, playbackAuthority, segmented, visualState]);

  useEffect(() => {
    const video = videoRef.current;
@@ -0,0 +1,245 @@
+import { useCallback, useEffect, useState, type ReactNode } from "react";
+import { SegmentedControl, SplitPane, type SplitPaneOrientation } from "@nodedc/ui-react";
+
+import { LaboratoryEvidenceViewer } from "./LaboratoryEvidenceViewer";
+
+export const CANONICAL_RECORDED_LAB_REPLAY_CONTRACT =
+  "missioncore.canonical-recorded-lab-replay/v1";
+
+export interface CanonicalRecordedLabMode<T extends string> {
+  value: T;
+  label: string;
+}
+
+/**
+ * The interaction contract from the accepted recorded-LAB instrument.
+ *
+ * Keeping pane selection, collapse semantics, responsive split orientation,
+ * expansion and splitter state here prevents individual experiments from
+ * quietly growing their own replay behaviour.  Experiments provide evidence
+ * layers; they do not reimplement the laboratory shell.
+ */
+export function useCanonicalRecordedLabReplayState<
+  TMedia extends string,
+  TSpatial extends string,
+>({
+  initialMediaMode,
+  initialSpatialMode,
+}: {
+  initialMediaMode: TMedia;
+  initialSpatialMode: TSpatial | null;
+}) {
+  const [mediaMode, setMediaMode] = useState<TMedia | null>(initialMediaMode);
+  const [spatialMode, setSpatialMode] = useState<TSpatial | null>(initialSpatialMode);
+  const [splitPrimarySize, setSplitPrimarySize] = useState(50);
+  const [splitOrientation, setSplitOrientation] = useState<SplitPaneOrientation>(() => (
+    typeof window !== "undefined" && window.matchMedia("(max-width: 900px)").matches
+      ? "horizontal"
+      : "vertical"
+  ));
+  const [expanded, setExpanded] = useState(false);
+
+  useEffect(() => {
+    const query = window.matchMedia("(max-width: 900px)");
+    const update = () => setSplitOrientation(query.matches ? "horizontal" : "vertical");
+    update();
+    query.addEventListener("change", update);
+    return () => query.removeEventListener("change", update);
+  }, []);
+
+  const onMediaModeChange = useCallback((next: TMedia | "none") => {
+    if (next === "none") return;
+    setMediaMode((current) => current === next ? null : next);
+  }, []);
+  const onSpatialModeChange = useCallback((next: TSpatial | "none") => {
+    if (next === "none") return;
+    setSpatialMode((current) => current === next ? null : next);
+  }, []);
+
+  return {
+    mediaMode,
+    spatialMode,
+    splitView: mediaMode !== null && spatialMode !== null,
+    splitPrimarySize,
+    splitOrientation,
+    expanded,
+    onMediaModeChange,
+    onSpatialModeChange,
+    onSplitPrimarySizeChange: setSplitPrimarySize,
+    onExpandedChange: setExpanded,
+  };
+}
+
+export function CanonicalRecordedLabReplay<
+  TMedia extends string,
+  TSpatial extends string,
+>({
+  label,
+  mediaMode,
+  mediaModes,
+  spatialMode,
+  spatialModes,
+  expanded,
+  splitPrimarySize,
+  splitOrientation,
+  mediaAriaLabel,
+  spatialAriaLabel,
+  mediaLayerControls,
+  spatialLayerControls,
+  spatialLeadingControl,
+  mediaMultiLayer = false,
+  mediaContent,
+  spatialContent,
+  emptyMessage,
+  deckOverlays,
+  actions,
+  overlay,
+  transport,
+  trailingActions,
+  onMediaModeChange,
+  onSpatialModeChange,
+  onExpandedChange,
+  onSplitPrimarySizeChange,
+}: {
+  label: string;
+  mediaMode: TMedia;
+  mediaModes: readonly CanonicalRecordedLabMode<TMedia>[];
+  spatialMode: TSpatial;
+  spatialModes: readonly CanonicalRecordedLabMode<TSpatial>[];
+  expanded: boolean;
+  splitPrimarySize: number;
+  splitOrientation: SplitPaneOrientation;
+  mediaAriaLabel: string;
+  spatialAriaLabel: string;
+  mediaLayerControls?: ReactNode;
+  spatialLayerControls?: ReactNode;
+  spatialLeadingControl?: ReactNode;
+  mediaMultiLayer?: boolean;
+  mediaContent: ReactNode;
+  spatialContent: ReactNode;
+  emptyMessage: string;
+  deckOverlays?: ReactNode;
+  actions?: ReactNode;
+  overlay?: ReactNode;
+  transport?: ReactNode;
+  trailingActions?: ReactNode;
+  onMediaModeChange: (mode: TMedia) => void;
+  onSpatialModeChange: (mode: TSpatial) => void;
+  onExpandedChange: (expanded: boolean) => void;
+  onSplitPrimarySizeChange: (size: number) => void;
+}) {
+  const splitView = mediaMode !== "none" && spatialMode !== "none";
+  const mediaModeControls = (
+    <div className="m4-replay-threat-visual__pane-mode-controls" data-pane-mode="media">
+      <SegmentedControl
+        value={mediaMode}
+        items={[...mediaModes]}
+        label="Видео и камера"
+        onChange={onMediaModeChange}
+      />
+    </div>
+  );
+  const spatialModeControls = (
+    <div className="m4-replay-threat-visual__pane-mode-controls" data-pane-mode="spatial">
+      <SegmentedControl
+        value={spatialMode}
+        items={[...spatialModes]}
+        label="3D и план"
+        onChange={onSpatialModeChange}
+      />
+    </div>
+  );
+  const mediaPane = (
+    <section
+      className="m4-replay-threat-visual__pane"
+      data-pane="media"
+      aria-label={mediaAriaLabel}
+      hidden={mediaMode === "none"}
+    >
+      {splitView ? (
+        <div
+          className="m4-replay-threat-visual__pane-toolbar"
+          data-pane-toolbar="media"
+          data-multi-semantic={mediaMultiLayer ? "true" : undefined}
+        >
+          {mediaLayerControls}
+          {mediaModeControls}
+        </div>
+      ) : null}
+      {mediaContent}
+    </section>
+  );
+  const spatialPane = spatialMode !== "none" ? (
+    <section
+      className="m4-replay-threat-visual__pane"
+      data-pane="spatial"
+      aria-label={spatialAriaLabel}
+    >
+      {splitView ? (
+        <div
+          className="m4-replay-threat-visual__pane-toolbar"
+          data-pane-toolbar="spatial"
+        >
+          {spatialLeadingControl}
+          <div className="m4-replay-threat-visual__spatial-toolbar-end">
+            {spatialLayerControls}
+            {spatialModeControls}
+          </div>
+        </div>
+      ) : null}
+      {spatialContent}
+    </section>
+  ) : null;
+
+  return (
+    <div
+      className="l3-visual-audit m4-replay-threat-visual"
+      data-contract={CANONICAL_RECORDED_LAB_REPLAY_CONTRACT}
+    >
+      <LaboratoryEvidenceViewer
+        label={label}
+        className="m4-replay-threat-evidence-viewer"
+        mode={mediaMode}
+        modes={[...mediaModes]}
+        secondaryMode={{
+          value: spatialMode,
+          modes: [...spatialModes],
+          label: "3D и план",
+          onChange: onSpatialModeChange,
+        }}
+        expanded={expanded}
+        onModeChange={onMediaModeChange}
+        onExpandedChange={onExpandedChange}
+        modeControlsVisible={!splitView}
+        actions={actions}
+        overlay={overlay}
+        transport={transport}
+        trailingActions={trailingActions}
+      >
+        <div
+          className="m4-replay-threat-visual__deck"
+          data-split={splitView ? "true" : undefined}
+          data-empty={mediaMode === "none" && spatialMode === "none" ? "true" : undefined}
+        >
+          <SplitPane
+            primary={mediaPane}
+            secondary={spatialPane ?? <div />}
+            primarySize={splitView ? splitPrimarySize : mediaMode !== "none" ? 100 : 0}
+            onPrimarySizeChange={onSplitPrimarySizeChange}
+            orientation={splitOrientation}
+            minPrimarySize={splitView ? 24 : 0}
+            minSecondarySize={splitView ? 24 : 0}
+            resizable={splitView}
+            separatorLabel="Изменить размер VIDEO/CAMERA и 3D/PLAN"
+          />
+          {mediaMode === "none" && spatialMode === "none" ? (
+            <div className="l3-visual-audit__state" role="status">
+              {emptyMessage}
+            </div>
+          ) : null}
+          {deckOverlays}
+        </div>
+      </LaboratoryEvidenceViewer>
+    </div>
+  );
+}
@@ -81,9 +81,7 @@ export function LaboratoryRecordedClipPlayer({
  sourceCount,
  cameraRef,
  cameraOverlay,
-  cameraControls,
  alternativeScene,
-  spatialControls,
  onSequenceChange,
  onPlayingChange,
  onPlaybackRateChange,
@@ -99,9 +97,7 @@ export function LaboratoryRecordedClipPlayer({
  sourceCount: number;
  cameraRef?: RefObject<HTMLDivElement | null>;
  cameraOverlay?: ReactNode;
-  cameraControls?: ReactNode;
  alternativeScene?: ReactNode;
-  spatialControls?: ReactNode;
  onSequenceChange: (sequence: number) => void;
  onPlayingChange: (playing: boolean) => void;
  onPlaybackRateChange: (rate: number) => void;
@@ -177,14 +173,6 @@ export function LaboratoryRecordedClipPlayer({
      aria-hidden={cameraPresentation === "primary"}
    >
      {alternativeScene}
-      {spatialControls ? (
-        <div
-          className="laboratory-recorded-clip-player__pane-controls"
-          data-pane="spatial"
-        >
-          {spatialControls}
-        </div>
-      ) : null}
    </div>
  );
  const cameraPane = (
@@ -207,14 +195,6 @@ export function LaboratoryRecordedClipPlayer({
        />
      ) : null}
      {cameraPresentation !== "hidden" ? cameraOverlay : null}
-      {cameraPresentation !== "hidden" && cameraControls ? (
-        <div
-          className="laboratory-recorded-clip-player__pane-controls"
-          data-pane="camera"
-        >
-          {cameraControls}
-        </div>
-      ) : null}
    </div>
  );
  return (
@@ -33,6 +33,8 @@ export function RecordedEvidenceVideoScene({
  segmentCount,
  onPlaybackChange,
  onPlayingRejected,
+  playbackAuthority = "media",
+  playbackTransport = "segmented",
 }: {
  source: ObservationSourceDescriptor;
  playback: RecordedObservationPlayback;
@@ -47,6 +49,8 @@ export function RecordedEvidenceVideoScene({
  segmentCount?: number;
  onPlaybackChange?: (playback: RecordedObservationPlayback) => void;
  onPlayingRejected?: () => void;
+  playbackAuthority?: "media" | "host";
+  playbackTransport?: "segmented" | "epoch-stream";
 }) {
  return (
    <div className="recorded-evidence-video-scene">
@@ -59,6 +63,8 @@ export function RecordedEvidenceVideoScene({
        segmentCount={segmentCount}
        onPlaybackChange={onPlaybackChange}
        onPlayingRejected={onPlayingRejected}
+        playbackAuthority={playbackAuthority}
+        playbackTransport={playbackTransport}
      />
      {semanticOverlay ? (
        <RecordedEvidenceSemanticMaskOverlay
@@ -130,8 +130,12 @@ export function useRecordedEvidencePlayback(

  const synchronize = useCallback((next: RecordedObservationPlayback) => {
    if (!validRange(range) || !Number.isFinite(next.currentSeconds)) return;
+    // The canonical LAB host clock is authoritative. Native media callbacks
+    // are observational only in this mode: a stalled decoder must never stop
+    // the common timeline or let an independently playing spatial view drift.
+    if (clock === "animation") return;
    setPlayback((current) => synchronizeRecordedEvidencePlayback(current, next, range));
-  }, [range]);
+  }, [clock, range]);

  return useMemo(() => ({
    playback,