Opacity Keyframes

import {
  useTimelineEngine,
  useTimelineKeyframes,
  useTimelineKeyframeGeometry,
  useTimelineTrack,
  type TimelineKeyframe,
  type TimelineEditPreview,
  type TimelineKeyframeClipboard,
  type TimelineKeyframeEditCommand,
  type TimelineKeyframeSide,
  type TimelineReadonly,
  addRational,
  formatRationalTimecode,
  fromSeconds,
  parseTimecodeToRationalTime,
  toSeconds,
} from '@techsquidtv/canvas-timeline';
import { useEffect, useRef, useState } from 'react';
import { opacityClipId } from './timeline-demo-data';
import {
  createCurvePresetCommand,
  getCurvePresetId,
  keyframeCurvePresets,
} from './keyframe-opacity-utils';

/** App-owned inspector composed from public headless APIs. */
export function KeyframeInspector() {
  const engine = useTimelineEngine();
  const state = useTimelineKeyframes({ clipId: opacityClipId, property: 'opacity' });
  const curveTrack = useTimelineTrack('opacity-video-track');
  const live = useTimelineKeyframeGeometry({ clipId: opacityClipId, property: 'opacity' });
  const selected = live.keyframeRects.find((entry) => entry.keyframe.selected)?.keyframe;
  const keys = state.keyframes;
  const index = keys.findIndex((key) => key.id === selected?.id);
  const [message, setMessage] = useState('');
  const expanded = curveTrack.height > 64;
  const clipboard = useRef<TimelineKeyframeClipboard | null>(null);
  const valueEdit = useRef<{
    keyframeId: string | undefined;
    time: TimelineKeyframe['time'];
    preview: TimelineEditPreview | null;
  } | null>(null);
  const [sliderValue, setSliderValue] = useState<number | null>(null);
  const value =
    sliderValue ??
    selected?.value ??
    engine.keyframes.getClipPropertyValueAtTime(opacityClipId, 'opacity') ??
    1;
  useEffect(
    () => () => {
      if (valueEdit.current?.preview && valueEdit.current.preview === engine.getEditPreview()) {
        engine.cancelEdit();
      }
    },
    [engine]
  );

  const commit = (command: TimelineKeyframeEditCommand) => {
    const result = engine.commitEdit(command);
    setMessage(
      result.committed ? '' : (result.preview.message ?? 'This edit could not be applied.')
    );
    return result;
  };
  const select = (key: TimelineReadonly<TimelineKeyframe> | undefined) => {
    if (!key) {
      return;
    }
    engine.keyframes.selectKeyframes([{ clipId: opacityClipId, keyframeId: key.id }]);
    engine.updatePlayhead(key.time);
  };
  const finishValue = (cancelled = false) => {
    if (!valueEdit.current) {
      return;
    }
    const preview = valueEdit.current.preview;
    if (preview && preview === engine.getEditPreview()) {
      if (!cancelled && preview.valid && preview.command.type === 'keyframes') {
        commit(preview.command);
      }
      engine.cancelEdit();
    }
    valueEdit.current = null;
    setSliderValue(null);
  };
  const editValue = (next: number, preview = false) => {
    if (!Number.isFinite(next)) {
      setMessage('Enter a finite opacity value.');
      return;
    }
    if (valueEdit.current && valueEdit.current.preview !== engine.getEditPreview()) {
      setSliderValue(null);
      setMessage('The value gesture was replaced by another edit.');
      return;
    }
    const target = valueEdit.current ?? {
      keyframeId: selected?.id,
      time: selected?.time ?? engine.getState().playheadTime,
      preview: null,
    };
    const command: TimelineKeyframeEditCommand = {
      type: 'keyframes',
      edits: [
        target.keyframeId
          ? { type: 'update', clipId: opacityClipId, keyframeId: target.keyframeId, value: next }
          : {
              type: 'set',
              clipId: opacityClipId,
              property: 'opacity',
              time: target.time,
              value: next,
              selected: true,
            },
      ],
    };
    if (preview) {
      valueEdit.current = target;
      setSliderValue(next);
      target.preview = engine.previewEdit(command);
    } else {
      commit(command);
    }
  };
  const deleteSelection = () =>
    commit({
      type: 'keyframes',
      edits: state.selectedKeyframes.map((ref) => ({ type: 'remove', ...ref })),
    });
  const paste = (duplicate: boolean) => {
    const copied = duplicate ? engine.keyframes.copyKeyframes() : clipboard.current;
    if (!copied?.entries.length) {
      setMessage('Select and copy some keyframes first.');
      return;
    }
    const time = duplicate
      ? addRational(
          keys.find((key) => key.selected)?.time ?? engine.getState().playheadTime,
          fromSeconds(1 / 30)
        )
      : engine.getState().playheadTime;
    commit(engine.keyframes.createPasteCommand(copied, time));
  };
  const renderCurve = (side: TimelineKeyframeSide) => {
    const left = keys[side === 'incoming' ? index - 1 : index];
    const right = keys[side === 'incoming' ? index : index + 1];
    const preset = left && right ? getCurvePresetId(left, right) : 'none';
    return (
      <label className="keyframe-editor-field">
        {side === 'incoming' ? 'Incoming curve' : 'Outgoing curve'}
        <select
          aria-label={`${side} curve`}
          disabled={!left || !right}
          value={preset}
          onChange={(event) => {
            if (left && right) {
              commit(
                createCurvePresetCommand(opacityClipId, left, right, event.currentTarget.value)
              );
            }
          }}
        >
          <option value="none" disabled>
            No segment
          </option>
          <option value="custom" disabled>
            Custom
          </option>
          {keyframeCurvePresets.map((item) => (
            <option key={item.id} value={item.id}>
              {item.label}
            </option>
          ))}
        </select>
      </label>
    );
  };
  return (
    <section className="media-sync-panel keyframe-opacity-panel" aria-label="Keyframe inspector">
      <h3>Opacity</h3>
      <p className="media-sync-status">
        {state.selectedKeyframes.length
          ? `${state.selectedKeyframes.length} selected`
          : 'Select a key or set one at the playhead'}
      </p>
      <div className="keyframe-editor-fields">
        <label className="keyframe-editor-field">
          Timecode
          <input
            aria-label="Keyframe timecode"
            key={`${selected?.id}:${selected?.time.v}`}
            disabled={!selected}
            defaultValue={selected ? formatRationalTimecode(selected.time, { frameRate: 30 }) : ''}
            onBlur={(event) => {
              if (!selected) {
                return;
              }
              const time = parseTimecodeToRationalTime(event.currentTarget.value, {
                frameRate: 30,
              });
              if (!time) {
                setMessage('Enter a valid timecode.');
                return;
              }
              if (toSeconds(time) !== toSeconds(selected.time)) {
                commit({
                  type: 'keyframes',
                  edits: [{ type: 'update', clipId: opacityClipId, keyframeId: selected.id, time }],
                });
              }
            }}
            onKeyDown={(event) => {
              if (event.key === 'Enter') {
                event.currentTarget.blur();
              }
            }}
          />
        </label>
        <label className="keyframe-editor-field">
          Value (%)
          <input
            aria-label="Keyframe opacity percent"
            type="number"
            min={0}
            max={100}
            step={0.1}
            key={`${selected?.id}:${selected?.value}`}
            defaultValue={Math.round(value * 10000) / 100}
            onBlur={(event) => {
              const next = Number(event.currentTarget.value) / 100;
              if (next !== value) {
                editValue(next);
              }
            }}
            onKeyDown={(event) => {
              if (event.key === 'Enter') {
                event.currentTarget.blur();
              }
            }}
          />
        </label>
      </div>
      <input
        aria-label="Opacity"
        type="range"
        min={0}
        max={1}
        step={0.001}
        value={value}
        onChange={(event) => editValue(Number(event.currentTarget.value), true)}
        onPointerUp={() => finishValue()}
        onPointerCancel={() => finishValue(true)}
        onBlur={() => finishValue()}
        onKeyUp={(event) => {
          if (event.key.startsWith('Arrow')) {
            finishValue();
          }
        }}
        onKeyDown={(event) => {
          if (event.key === 'Escape') {
            event.preventDefault();
            finishValue(true);
          }
        }}
      />
      <div className="media-sync-controls">
        <button
          className="media-sync-button"
          disabled={index <= 0}
          onClick={() => select(keys[index - 1])}
        >
          Previous
        </button>
        <button
          className="media-sync-button"
          disabled={index < 0 || index >= keys.length - 1}
          onClick={() => select(keys[index + 1])}
        >
          Next
        </button>
        <button
          className="media-sync-button"
          onClick={() => {
            const time = engine.getState().playheadTime;
            const result = commit({
              type: 'keyframes',
              edits: [
                {
                  type: 'set',
                  clipId: opacityClipId,
                  property: 'opacity',
                  time,
                  value:
                    engine.keyframes.getClipPropertyValueAtTime(opacityClipId, 'opacity', time) ??
                    1,
                  selected: true,
                },
              ],
            });
            if (result.committed) {
              select(
                engine.keyframes
                  .getClipKeyframes(opacityClipId, 'opacity')
                  .find((key) => toSeconds(key.time) === toSeconds(time))
              );
            }
          }}
        >
          Set key
        </button>
        <button
          className="media-sync-button"
          disabled={!state.selectedKeyframes.length}
          onClick={deleteSelection}
        >
          Delete
        </button>
      </div>
      <div className="keyframe-editor-fields">
        {renderCurve('incoming')}
        {renderCurve('outgoing')}
      </div>
      <div className="media-sync-controls">
        <button
          className="media-sync-button"
          disabled={!selected}
          aria-pressed={selected?.tangentMode === 'linked'}
          onClick={() => {
            if (selected) {
              commit({
                type: 'keyframes',
                edits: [
                  {
                    type: 'update',
                    clipId: opacityClipId,
                    keyframeId: selected.id,
                    tangentMode: selected.tangentMode === 'linked' ? 'broken' : 'linked',
                  },
                ],
              });
            }
          }}
        >
          {selected?.tangentMode === 'linked' ? 'Linked tangents' : 'Broken tangents'}
        </button>
        <button
          className="media-sync-button"
          disabled={!selected}
          onClick={() => {
            if (selected) {
              commit({
                type: 'keyframes',
                edits: [
                  {
                    type: 'sides',
                    clipId: opacityClipId,
                    keyframeId: selected.id,
                    incoming: { handle: null },
                    outgoing: { handle: null },
                  },
                ],
              });
            }
          }}
        >
          Reset tangents
        </button>
      </div>
      <div className="media-sync-controls">
        <button
          className="media-sync-button"
          disabled={!state.selectedKeyframes.length}
          onClick={() => {
            clipboard.current = engine.keyframes.copyKeyframes();
            setMessage('Keyframes copied. Paste places them at the playhead.');
          }}
        >
          Copy
        </button>
        <button className="media-sync-button" onClick={() => paste(false)}>
          Paste
        </button>
        <button
          className="media-sync-button"
          disabled={!state.selectedKeyframes.length}
          onClick={() => paste(true)}
        >
          Duplicate
        </button>
        <button className="media-sync-button" onClick={() => engine.undo()}>
          Undo
        </button>
        <button className="media-sync-button" onClick={() => engine.redo()}>
          Redo
        </button>
      </div>
      <button
        className="media-sync-button"
        aria-expanded={expanded}
        onClick={() => {
          curveTrack.setTrackHeight(expanded ? 64 : 240);
        }}
      >
        {expanded ? 'Collapse curve lane' : 'Expand curve lane'}
      </button>
      <p className="media-sync-status">
        Shift-drag empty space to select. Shift locks a drag axis; Alt makes fine adjustments;
        Ctrl/⌘ bypasses snapping. Escape cancels. Arrow keys nudge; [ and ] visit keys.
      </p>
      <p className="media-sync-status" role="status">
        {message}
      </p>
    </section>
  );
}

const demoClipColors = [
  'oklch(0.62 0.16 250)',
  'oklch(0.68 0.14 145)',
  'oklch(0.72 0.16 70)',
  'oklch(0.65 0.17 25)',
  'oklch(0.58 0.18 305)',
  'oklch(0.64 0.12 195)',
] as const;

export function getDemoClipColor(index: number) {
  return demoClipColors[index % demoClipColors.length];
}

import { createTimelineScalarKeyframeProperty } from '@techsquidtv/canvas-timeline';

export const opacityKeyframeProperty = createTimelineScalarKeyframeProperty({
  id: 'opacity',
  label: 'Opacity',
  min: 0,
  max: 1,
  defaultValue: 1,
  formatValue: (value) => `${Math.round(value * 100)}%`,
  getBaseValue: (clip) => clip.opacity ?? 1,
});

import type {
  MediaMetricEvent,
  TimelineMetricContext,
  TimelineMetricOperation,
  WorkerRenderMetric,
} from './metrics-common';

export interface DemoMetrics {
  onTimelineFpsSample?: (context: TimelineMetricContext, fps: number) => void;
  onTimelineFrameTimes?: (
    context: TimelineMetricContext,
    frameTimes: readonly number[],
    operation: TimelineMetricOperation
  ) => void;
  onTimelineInteractionLatencies?: (
    context: TimelineMetricContext,
    operation: TimelineMetricOperation,
    latencies: readonly number[]
  ) => void;
  onTimelineWorkerRenderStats?: (
    context: TimelineMetricContext,
    renderStats: readonly WorkerRenderMetric[]
  ) => void;
  onMediaLoadFailed?: (event: MediaMetricEvent) => void;
  onMediaDecodeTime?: (event: MediaMetricEvent, durationMs: number) => void;
}

type MetricAttributeValue = string | number | boolean;
export type MetricAttributes = Record<string, MetricAttributeValue>;

type RendererType = 'canvas' | 'dom';
export type TimelineMetricOperation =
  | 'scrub'
  | 'zoom'
  | 'pan'
  | 'drag'
  | 'trim'
  | 'drag-rejected'
  | 'commit'
  | 'undo';

export interface NormalizedRouteMetric {
  route: string;
  section: string;
}

export interface TimelineMetricContext {
  demoId: string;
  renderer: RendererType;
  trackCount: number;
  clipCount: number;
  keyframeCount?: number;
  benchmarkScope?: 'engine' | 'interactive';
}

export interface WorkerRenderMetric {
  reason: string;
  durationMs: number;
}

export interface MediaMetricEvent {
  demoId: string;
  adapter: 'html-media' | 'mediabunny';
  mediaType: 'video' | 'audio' | 'video_audio';
}

export function normalizeMetricRoute(pathname: string): NormalizedRouteMetric {
  const segments = pathname.split('/').filter(Boolean);
  const [section] = segments;

  if (!section) {
    return { route: '/', section: 'home' };
  }

  if (section === 'packages') {
    if (segments[1] === 'react' && segments[2] === 'registry') {
      return {
        route: segments.length > 3 ? '/packages/react/registry/:slug' : '/packages/react/registry',
        section: 'registry',
      };
    }

    if (segments[2] === 'api') {
      return {
        route: segments.length > 3 ? '/packages/:package/api/:symbol' : '/packages/:package/api',
        section: 'packages-api',
      };
    }

    return {
      route: segments.length > 1 ? '/packages/:package' : '/packages',
      section: 'packages',
    };
  }

  if (section === 'docs') {
    return {
      route: segments.length > 1 ? '/docs/:slug' : '/docs',
      section: 'docs',
    };
  }

  if (section === 'demos') {
    return {
      route: segments.length > 1 ? '/demos/:slug' : '/demos',
      section: 'demos',
    };
  }

  if (section === 'blog') {
    return {
      route: segments.length > 1 ? '/blog/:slug' : '/blog',
      section: 'blog',
    };
  }

  return {
    route: `/${section}`,
    section,
  };
}

function bucketCount(value: number): string {
  if (value <= 0) {
    return '0';
  }
  if (value <= 10) {
    return '1-10';
  }
  if (value <= 50) {
    return '11-50';
  }
  if (value <= 100) {
    return '51-100';
  }
  if (value <= 500) {
    return '101-500';
  }
  if (value <= 1000) {
    return '501-1000';
  }
  return '1001+';
}

export function sampleMetricValues(values: readonly number[], maxSamples = 60): number[] {
  if (values.length <= maxSamples) {
    return [...values];
  }

  const step = values.length / maxSamples;
  return Array.from({ length: maxSamples }, (_, index) => values[Math.floor(index * step)] ?? 0);
}

export function sampleMetricItems<T>(values: readonly T[], maxSamples = 60): T[] {
  if (values.length <= maxSamples) {
    return [...values];
  }

  const step = values.length / maxSamples;
  return Array.from({ length: maxSamples }, (_, index) => values[Math.floor(index * step)]).filter(
    (value): value is T => value !== undefined
  );
}

export function timelineMetricAttributes(context: TimelineMetricContext): MetricAttributes {
  return {
    demo_id: context.demoId,
    renderer: context.renderer,
    track_count_bucket: bucketCount(context.trackCount),
    clip_count_bucket: bucketCount(context.clipCount),
    ...(context.keyframeCount === undefined
      ? {}
      : { keyframe_count_bucket: bucketCount(context.keyframeCount) }),
    ...(context.benchmarkScope === undefined ? {} : { benchmark_scope: context.benchmarkScope }),
  };
}