Skip to content

Write HTML. Render video. Built for agents.

51.6 KB
Raw Blame
import type { BrowserInstallFacts } from "../browser/installFacts.js";
import type { OutputResolutionIssueKind } from "@hyperframes/core";
import { redactTelemetryString } from "@hyperframes/core/telemetry-redaction";
import type { SubTimelineWaitOutcome } from "@hyperframes/engine";
import { FEEDBACK_RATING_SCALE } from "../utils/feedbackRating.js";
import type { CatalogUsage } from "../utils/catalogUsage.js";
import { flush, shouldTrack, trackEvent } from "./client.js";
import { readConfig } from "./config.js";
import { getPowerState } from "./system.js";
import type { RenderCpuTelemetryPayload } from "./renderCpu.js";
import { CliRuntimeError } from "../utils/commandResult.js";

// Power state is volatile (a laptop docks/undocks mid-session), so it is
// sampled per render event rather than cached with SystemMeta. Attached to
// render_complete AND render_error: the DE fleet is macOS laptops whose
// power management shifts render perf ~1.8x with no other telemetry signal,
// and perf/soak analysis needs to segment by it (see getPowerState).
//
// shouldTrack() is checked HERE, not just inside trackEvent: this helper is
// spread into the properties object at the CALL SITE, so it runs before
// trackEvent's own `if (!shouldTrack()) return` guard. Without this an
// opted-out install would still pay two blocking `pmset` subprocess spawns
// per render for an event that is then discarded (review finding).
// shouldTrack() memoizes, so this costs nothing on the tracked path.
function powerStateFields(): { on_battery?: boolean; low_power_mode?: boolean } {
  if (!shouldTrack()) return {};
  const power = getPowerState();
  return {
    on_battery: power.on_battery ?? undefined,
    low_power_mode: power.low_power_mode ?? undefined,
  };
}

// run_id is attached only when the orchestrator set HYPERFRAMES_RUN_ID — an
// absent property, never null/"" (PostHog treats those as real values).
function runIdField(runId: string | undefined): { run_id?: string } {
  return runId !== undefined ? { run_id: runId } : {};
}

export interface RenderObservabilityTelemetryPayload {
  /** Worst sub-composition timeline wait outcome across sessions. */
  subTimelineWait?: SubTimelineWaitOutcome;
  observabilityRenderJobId?: string;
  observabilityCompositionHash?: string;
  observabilityEventCount?: number;
  observabilityLastPhase?: string;
  observabilityLastStatus?: string;
  observabilityFailedPhase?: string;
  browserDiagnosticCount?: number;
  browserDiagnosticErrors?: number;
  browserDiagnosticPageErrors?: number;
  browserDiagnosticRequestFailed?: number;
  browserDiagnosticHttpErrors?: number;
  browserDiagnosticNavigationStarts?: number;
  browserDiagnosticNavigationFailures?: number;
  browserDiagnosticConsoleErrors?: number;
  browserDiagnosticConsoleWarnings?: number;
  captureMode?: string;
  captureForceScreenshot?: boolean;
  captureWorkerCount?: number;
  captureUseStreamingEncode?: boolean;
  captureUseLayeredComposite?: boolean;
  captureUsePageSideCompositing?: boolean;
  captureHasHdrContent?: boolean;
  captureBrowserGpuMode?: string;
  captureProtocolTimeoutMs?: number;
  capturePageNavigationTimeoutMs?: number;
  capturePlayerReadyTimeoutMs?: number;
  captureTransientRetries?: number;
  captureMemoryExhaustionDetected?: boolean;
  // Mirror of the DE inversion/router state on `RenderCaptureObservability` —
  // sourced from the live-mutated capture object rather than `perfSummary`,
  // so a hard failure (crash, OOM, timeout) that never reaches perfSummary
  // construction still reports which DE experiment cohort it was in. Mapped
  // to the SAME `de_*` event keys `trackRenderComplete` sets explicitly from
  // `perfSummary.drawElement`; the caller must spread this payload FIRST so
  // the more authoritative perfSummary value wins when both are present.
  captureDeWorkerInversion?: string;
  captureDePreInversionWorkers?: number;
  captureCompositionElementCount?: number;
  captureCompositionElementCountSource?: string;
  captureCompositionElementTags?: Readonly<Record<string, number>>;
  captureArollVideoCount?: number;
  captureHeygenVideoCount?: number;
  captureAdaptersUsed?: readonly string[];
  captureAudioCount?: number;
  captureImageCount?: number;
  captureSubCompositionCount?: number;
  captureAudioGroupCount?: number;
  captureColorGradingCount?: number;
  captureHasLut?: boolean;
  captureRootBodyMismatch?: boolean;
  captureRootBodyDeltaPxBucket?: string;
  captureDeShortBand?: string;
  captureDeParallelRouter?: string;
  captureDeGpuRenderer?: string;
  captureDePreRouterWorkers?: number;
  captureDeSelfVerifyFallback?: boolean;
  captureDeFallbackReason?: string;
  captureDeFallbackFailedDb?: number;
  captureDeFallbackFrameIndex?: number;
  captureDeFallbackThresholdDb?: number;
  /** Non-DE parallel-streaming router outcome ("screenshot" | "beginframe" —
   * routed; "eligible_off" — would route but the kill switch is off). */
  captureParallelStream?: string;
  /** Chrome memory from the engine sampler (Phase −1, long-form render plan). */
  captureChromeBrowserRssPeakMb?: number;
  captureChromeRendererRssPeakMb?: number;
  captureChromeRssLastMb?: number;
  captureChromeGpuProcessSeenLastSample?: boolean;
  captureChromeMemorySamples?: number;
  captureCapturePath?: string;
  captureSegmentIndex?: number;
  captureSegmentRetries?: number;
  observabilityExtractVideoCount?: number;
  observabilityExtractedVideoCount?: number;
  observabilityExtractTotalFrames?: number;
  observabilityExtractMaxFramesPerVideo?: number;
  observabilityExtractAvgFramesPerVideo?: number;
  observabilityExtractVfrProbeMs?: number;
  observabilityExtractVfrPreflightMs?: number;
  observabilityExtractVfrPreflightCount?: number;
  observabilityExtractCacheHits?: number;
  observabilityExtractCacheMisses?: number;
  observabilityInitDurationMs?: number;
  observabilityInitTweenCount?: number;
  observabilityInitElementCount?: number;
}

function renderObservabilityEventProperties(props: RenderObservabilityTelemetryPayload) {
  return {
    sub_timeline_wait: props.subTimelineWait,
    observability_render_job_id: props.observabilityRenderJobId,
    observability_composition_hash: props.observabilityCompositionHash,
    observability_event_count: props.observabilityEventCount,
    observability_last_phase: props.observabilityLastPhase,
    observability_last_status: props.observabilityLastStatus,
    observability_failed_phase: props.observabilityFailedPhase,
    browser_diagnostic_count: props.browserDiagnosticCount,
    browser_diagnostic_errors: props.browserDiagnosticErrors,
    browser_diagnostic_page_errors: props.browserDiagnosticPageErrors,
    browser_diagnostic_request_failed: props.browserDiagnosticRequestFailed,
    browser_diagnostic_http_errors: props.browserDiagnosticHttpErrors,
    browser_diagnostic_navigation_starts: props.browserDiagnosticNavigationStarts,
    browser_diagnostic_navigation_failures: props.browserDiagnosticNavigationFailures,
    browser_diagnostic_console_errors: props.browserDiagnosticConsoleErrors,
    browser_diagnostic_console_warnings: props.browserDiagnosticConsoleWarnings,
    capture_mode: props.captureMode,
    capture_force_screenshot: props.captureForceScreenshot,
    capture_worker_count: props.captureWorkerCount,
    capture_use_streaming_encode: props.captureUseStreamingEncode,
    capture_use_layered_composite: props.captureUseLayeredComposite,
    capture_use_page_side_compositing: props.captureUsePageSideCompositing,
    capture_has_hdr_content: props.captureHasHdrContent,
    capture_browser_gpu_mode: props.captureBrowserGpuMode,
    capture_protocol_timeout_ms: props.captureProtocolTimeoutMs,
    capture_page_navigation_timeout_ms: props.capturePageNavigationTimeoutMs,
    capture_player_ready_timeout_ms: props.capturePlayerReadyTimeoutMs,
    capture_transient_retries: props.captureTransientRetries,
    capture_memory_exhaustion_detected: props.captureMemoryExhaustionDetected,
    de_worker_inversion: props.captureDeWorkerInversion,
    de_pre_inversion_workers: props.captureDePreInversionWorkers,
    composition_element_count: props.captureCompositionElementCount,
    composition_element_count_source: props.captureCompositionElementCountSource,
    composition_element_tags: props.captureCompositionElementTags,
    aroll_video_count: props.captureArollVideoCount,
    heygen_video_count: props.captureHeygenVideoCount,
    adapters_used: props.captureAdaptersUsed,
    audio_count: props.captureAudioCount,
    image_count: props.captureImageCount,
    sub_composition_count: props.captureSubCompositionCount,
    audio_group_count: props.captureAudioGroupCount,
    color_grading_count: props.captureColorGradingCount,
    has_lut: props.captureHasLut,
    root_body_mismatch: props.captureRootBodyMismatch,
    root_body_delta_px_bucket: props.captureRootBodyDeltaPxBucket,
    de_short_band: props.captureDeShortBand,
    de_parallel_router: props.captureDeParallelRouter,
    gpu_renderer: props.captureDeGpuRenderer,
    de_pre_router_workers: props.captureDePreRouterWorkers,
    de_self_verify_fallback: props.captureDeSelfVerifyFallback,
    de_fallback_reason: props.captureDeFallbackReason,
    de_fallback_failed_db: props.captureDeFallbackFailedDb,
    de_fallback_frame_index: props.captureDeFallbackFrameIndex,
    de_fallback_threshold_db: props.captureDeFallbackThresholdDb,
    capture_parallel_stream: props.captureParallelStream,
    chrome_browser_rss_peak_mb: props.captureChromeBrowserRssPeakMb,
    chrome_renderer_rss_peak_mb: props.captureChromeRendererRssPeakMb,
    chrome_rss_last_mb: props.captureChromeRssLastMb,
    gpu_process_seen_last_sample: props.captureChromeGpuProcessSeenLastSample,
    chrome_memory_samples: props.captureChromeMemorySamples,
    capture_path: props.captureCapturePath,
    segment_index: props.captureSegmentIndex,
    segment_retries: props.captureSegmentRetries,
    observability_extract_video_count: props.observabilityExtractVideoCount,
    observability_extracted_video_count: props.observabilityExtractedVideoCount,
    observability_extract_total_frames: props.observabilityExtractTotalFrames,
    observability_extract_max_frames_per_video: props.observabilityExtractMaxFramesPerVideo,
    observability_extract_avg_frames_per_video: props.observabilityExtractAvgFramesPerVideo,
    observability_extract_vfr_probe_ms: props.observabilityExtractVfrProbeMs,
    observability_extract_vfr_preflight_ms: props.observabilityExtractVfrPreflightMs,
    observability_extract_vfr_preflight_count: props.observabilityExtractVfrPreflightCount,
    observability_extract_cache_hits: props.observabilityExtractCacheHits,
    observability_extract_cache_misses: props.observabilityExtractCacheMisses,
    observability_init_duration_ms: props.observabilityInitDurationMs,
    observability_init_tween_count: props.observabilityInitTweenCount,
    observability_init_element_count: props.observabilityInitElementCount,
  };
}

/** The direct drawElement-sourced value when render.ts's own path resolved one, else the
 * observability-capture fallback studioRenderTelemetry.ts's path resolves instead. */
function directOrCapture<T>(direct: T | undefined, capture: T | undefined): T | undefined {
  return direct ?? capture;
}

/** Output-shape request facts, resolved before the pipeline starts, shared by render_complete/render_error. */
export interface RenderOutputShapeTelemetryPayload {
  /** Named canvas preset from `--resolution`; undefined when rendering at the composition's native dimensions. */
  outputResolutionPreset?: string;
  /** Container/output format: mp4 | webm | mov | gif | png-sequence. */
  outputFormat?: string;
  /** Requested HDR mode (the CLI flag value, not the resolved per-render outcome): auto | force-hdr | force-sdr. */
  hdrMode?: string;
  /** Intermediate frame format used when extracting source video frames: auto | jpg | png. */
  videoFrameFormat?: string;
  /** True when a requested --fps > 30 was clamped to 30 for --format gif (createRenderPlan's gifFpsCapped). */
  gifFpsCapped?: boolean;
}

function renderOutputShapeEventProperties(props: RenderOutputShapeTelemetryPayload) {
  return {
    output_resolution_preset: props.outputResolutionPreset,
    output_format: props.outputFormat,
    hdr_mode: props.hdrMode,
    video_frame_format: props.videoFrameFormat,
    gif_fps_capped: props.gifFpsCapped,
  };
}

/** Local-preflight toolchain majors, shared by render_complete/render_error; absent on Docker renders. */
export interface RenderEnvironmentTelemetryPayload {
  ffmpegVersionMajor?: number;
  browserVersionMajor?: number;
  browserInstall?: BrowserInstallFacts;
}

function renderEnvironmentEventProperties(props: RenderEnvironmentTelemetryPayload) {
  return {
    ffmpeg_version_major: props.ffmpegVersionMajor,
    browser_version_major: props.browserVersionMajor,
    browser_build: props.browserInstall?.build,
    browser_path_ascii: props.browserInstall?.pathAscii,
    browser_path_length: props.browserInstall?.pathLength,
    browser_path_drive: props.browserInstall?.drive,
  };
}

function renderCpuEventProperties(props: RenderCpuTelemetryPayload) {
  return {
    cpu_busy_avg_pct: props.cpuBusyAvgPct,
    cpu_busy_peak_pct: props.cpuBusyPeakPct,
    cpu_cores_busy_peak: props.cpuCoresBusyPeak,
    load_avg_start: props.loadAvgStart,
    load_avg_end: props.loadAvgEnd,
  };
}

function redactTelemetryMessage(value: string): string {
  return redactTelemetryString(value);
}

export function trackCommand(command: string, runId?: string): void {
  trackEvent("cli_command", {
    command,
    ...runIdField(runId),
  });
}

/**
 * Cap on item names in one event. Registry names are low-cardinality slugs, but
 * a project with a hundred blocks should not push a hundred-name string into
 * every render. The cap belongs at the boundary that builds the string, and
 * deliberately NOT on the counts: a count is one integer with no cardinality
 * risk, and a saturated one loses the real number with no way downstream to
 * tell 40 installs from 400.
 */
const MAX_REPORTED_ITEM_NAMES = 40;

/**
 * Catalog half of `render_complete`.
 *
 * Counts are emitted even when zero: the no-catalog cohort is exactly what the
 * with-catalog cohort gets compared against, and a property that is simply
 * absent is indistinguishable from an older CLI that never sent one. Names ride
 * as a comma-joined string because event property values are scalars only (same
 * shape as `recent_render_ids` on `cli_render_feedback`).
 *
 * The used names are narrowed to the reported installed names, so
 * `registry_blocks_used` stays a subset of `registry_items` even when the cap
 * bites. Sliced independently, the two lists can come out disjoint, breaking
 * the one relationship a drop-off query relies on. When the cap does bite,
 * `registry_items_truncated` says so: the counts still carry the truth, but the
 * names are a window, and a query that joins on names must not read the
 * difference as abandonment.
 *
 * An unreadable manifest reports itself and omits the counts rather than
 * sending zeros, so a failed read cannot pose as a project that never used the
 * catalog. Undefined usage means the caller built render options by hand rather
 * than through the render plan, so it makes no catalog claim at all.
 */
function catalogEventProperties(
  usage: CatalogUsage | undefined,
): Record<string, string | number | boolean> {
  if (!usage) return {};
  if (usage.manifestUnreadable) return { registry_manifest_unreadable: true };
  const names = usage.installed.slice(0, MAX_REPORTED_ITEM_NAMES);
  const reportedNames = new Set(names);
  const used = usage.usedBlocks.filter((name) => reportedNames.has(name));
  const truncated = names.length < usage.installed.length;
  return {
    registry_item_count: usage.installed.length,
    registry_blocks_used_count: usage.usedBlocks.length,
    // Say when the name lists are a window rather than the whole set. Without
    // it a name-joining drop-off query silently reads a truncated project as
    // all-abandoned: the used blocks can all sit past the cap, leaving an empty
    // `registry_blocks_used` against a non-zero count.
    ...(truncated ? { registry_items_truncated: true } : {}),
    ...(names.length > 0 ? { registry_items: names.join(",") } : {}),
    ...(used.length > 0 ? { registry_blocks_used: used.join(",") } : {}),
  };
}

export function trackRenderComplete(
  props: {
    durationMs: number;
    fps: number;
    quality: string;
    /** Authoring skill that drove this render (e.g. "hyperframes"). */
    authoringSkill?: string;
    /** Which step resolved authoringSkill: an explicit --skill flag, or the project's own config. */
    authoringSkillSource?: string;
    /** Raw --skill value when it failed skill-slug normalization (an unrecognized skill name). */
    authoringSkillInvalid?: string;
    /** Names of HF_-/HYPERFRAMES_-prefixed env vars present at plan time (never values), capped at 20. */
    hfEnvOverrides?: readonly string[];
    /**
     * Catalog items installed in this project, and those the rendered
     * composition reaches. The pair is what joins `registry_item_added` to a
     * finished video: an installed item missing from the used set was tried
     * and dropped, which no add-time event can express.
     */
    catalogUsage?: CatalogUsage;
    workers?: number;
    // Worker auto-sizing provenance (RenderPerfSummary.workerSizing). Answers
    // "why N workers?" fleet-wide, and reports the per-worker heap budget
    // that caps auto sizing (field OOM: 6 auto workers on a 24GB/4GB-heap
    // machine — see computeWorkerSizing in @hyperframes/engine).
    workersBoundBy?: string;
    workersCpuBased?: number;
    workersMemoryBased?: number;
    workersHeapBased?: number;
    workersFrameBased?: number;
    workersHeapLimitMb?: number;
    workersExceedHeapAdvisory?: boolean;
    docker: boolean;
    gpu: boolean;
    // Static-frame dedup outcome (opt-out HF_STATIC_DEDUP=false). Undefined on
    // render paths with no capture session.
    staticDedupEnabled?: boolean;
    staticDedupArmed?: boolean;
    staticDedupSkipReason?: string;
    staticDedupPredictedFrames?: number;
    staticDedupReusedFrames?: number;
    // BeginFrame no-damage reuse outcome (Linux/Docker lastFrameCache — the BF
    // counterpart of static dedup). Undefined outside beginframe capture mode.
    beginFrameNoDamageFrames?: number;
    beginFrameHasDamageFrames?: number;
    // drawElement fast-capture outcome (default-on release visibility).
    // Undefined on render paths with no capture session.
    deCaptureMode?: string;
    deCompileGate?: string;
    deClampReason?: string;
    deWorkerInversion?: string;
    dePreInversionWorkers?: number;
    compositionElementCount?: number;
    compositionElementCountSource?: string;
    compositionElementTags?: Readonly<Record<string, number>>;
    arollVideoCount?: number;
    heygenVideoCount?: number;
    adaptersUsed?: readonly string[];
    audioCount?: number;
    imageCount?: number;
    subCompositionCount?: number;
    audioGroupCount?: number;
    colorGradingCount?: number;
    hasLut?: boolean;
    rootBodyMismatch?: boolean;
    rootBodyDeltaPxBucket?: string;
    // `data-vfx-chain` facts from the same static scan (Task 1.5's kernel-cost
    // measurement's producer-side counterpart). Undefined on render paths
    // with no capture session, same as the composition-element fields above.
    /** Host count — one per `data-vfx-chain` attribute occurrence, regardless of its chain's node count. */
    vfxHostCount?: number;
    /** Strongest enabled node's capture across every host ("none" | "self" | "backdrop", max). */
    vfxCapture?: string;
    /** Sorted unique def ids across every enabled node in every chain, comma-joined. */
    vfxTypes?: string;
    deShortBand?: string;
    deParallelRouter?: string;
    dePreRouterWorkers?: number;
    deGateReason?: string;
    /** Low-cardinality GPU bucket from DE session init (`<backend>/<vendor>`, e.g. `d3d11/nvidia`). */
    gpuRenderer?: string;
    deWorkerEncode?: boolean;
    deVerifyArmed?: number;
    deVerifyChecked?: number;
    deVerifyMinDb?: number;
    deVerifyInitMs?: number;
    deSelfVerifyFallback?: boolean;
    deFallbackReason?: string;
    deFallbackFailedDb?: number;
    deFallbackFrameIndex?: number;
    deFallbackThresholdDb?: number;
    deBlankSuspects?: number;
    deBlankDeterministicAccepts?: number;
    deBlankRecaptures?: number;
    deBoundaryFrames?: number;
    deNcprFallbacks?: number;
    deFrameTimeouts?: number;
    // "cli" when triggered by `hyperframes render` (default), "studio" when
    // triggered by a studio preview-server render (POST /api/projects/:id/render).
    source?: "cli" | "studio";
    // Composition metadata
    compositionDurationMs?: number;
    compositionWidth?: number;
    compositionHeight?: number;
    totalFrames?: number;
    // Processing efficiency
    speedRatio?: number;
    captureAvgMs?: number;
    /** Warmup-robust per-frame capture median (basis for speedup estimates). */
    captureP50Ms?: number;
    /** <video> element count (speedup segmentation: injection comps read lower). */
    videoCount?: number;
    capturePeakMs?: number;
    // Resource usage
    peakMemoryMb?: number;
    // Aggregate Chrome memory (RenderPerfSummary.chromeMemory); overrides the
    // live observability values when both are present, because the live ones
    // are only the last session's and the aggregate covers every worker.
    chromeBrowserRssPeakMb?: number;
    chromeRendererRssPeakMb?: number;
    chromeRssLastMb?: number;
    chromeGpuProcessSeenLastSample?: boolean;
    chromeMemorySamples?: number;
    memoryFreeMb?: number;
    tmpPeakBytes?: number;
    // Per-stage timings (subset of RenderPerfSummary.stages)
    stageCompileMs?: number;
    stageVideoExtractMs?: number;
    stageAudioProcessMs?: number;
    stageCaptureMs?: number;
    stageCaptureSetupMs?: number;
    stageCaptureFrameMs?: number;
    stageEncodeMs?: number;
    stageAssembleMs?: number;
    // Video-extraction breakdown (from RenderPerfSummary.videoExtractBreakdown)
    extractResolveMs?: number;
    extractHdrProbeMs?: number;
    extractHdrPreflightMs?: number;
    extractHdrPreflightCount?: number;
    extractVfrProbeMs?: number;
    extractVfrPreflightMs?: number;
    extractVfrPreflightCount?: number;
    extractPhase3Ms?: number;
    extractCacheHits?: number;
    extractCacheMisses?: number;
    // Attribute this event to a specific user (e.g. the browser user who
    // triggered a studio render); defaults to the install anonymousId.
    distinctId?: string;
  } & RenderObservabilityTelemetryPayload &
    RenderOutputShapeTelemetryPayload &
    RenderEnvironmentTelemetryPayload &
    RenderCpuTelemetryPayload,
): void {
  trackEvent(
    "render_complete",
    {
      // Spread first: fields below wrapped in directOrCapture() prefer
      // perfSummary.drawElement, present only on the CLI's own render.ts path.
      // studioRenderTelemetry.ts never populates drawElement, so without the
      // fallback the explicit key still wins the spread with an undefined.
      ...renderObservabilityEventProperties(props),
      chrome_browser_rss_peak_mb:
        props.chromeBrowserRssPeakMb ?? props.captureChromeBrowserRssPeakMb,
      chrome_renderer_rss_peak_mb:
        props.chromeRendererRssPeakMb ?? props.captureChromeRendererRssPeakMb,
      chrome_rss_last_mb: props.chromeRssLastMb ?? props.captureChromeRssLastMb,
      gpu_process_seen_last_sample:
        props.chromeGpuProcessSeenLastSample ?? props.captureChromeGpuProcessSeenLastSample,
      chrome_memory_samples: props.chromeMemorySamples ?? props.captureChromeMemorySamples,
      duration_ms: props.durationMs,
      fps: props.fps,
      quality: props.quality,
      authoring_skill: props.authoringSkill,
      authoring_skill_source: props.authoringSkillSource,
      authoring_skill_invalid: props.authoringSkillInvalid,
      hf_env_overrides: props.hfEnvOverrides ?? [],
      ...catalogEventProperties(props.catalogUsage),
      workers: props.workers,
      workers_bound_by: props.workersBoundBy,
      workers_cpu_based: props.workersCpuBased,
      workers_memory_based: props.workersMemoryBased,
      workers_heap_based: props.workersHeapBased,
      workers_frame_based: props.workersFrameBased,
      workers_heap_limit_mb: props.workersHeapLimitMb,
      workers_exceed_heap_advisory: props.workersExceedHeapAdvisory,
      docker: props.docker,
      gpu: props.gpu,
      static_dedup_enabled: props.staticDedupEnabled,
      static_dedup_armed: props.staticDedupArmed,
      static_dedup_skip_reason: props.staticDedupSkipReason,
      static_dedup_predicted_frames: props.staticDedupPredictedFrames,
      static_dedup_reused_frames: props.staticDedupReusedFrames,
      begin_frame_no_damage_frames: props.beginFrameNoDamageFrames,
      begin_frame_has_damage_frames: props.beginFrameHasDamageFrames,
      de_capture_mode: props.deCaptureMode,
      vfx_host_count: props.vfxHostCount,
      vfx_capture: props.vfxCapture,
      vfx_types: props.vfxTypes,
      de_compile_gate: props.deCompileGate,
      de_clamp_reason: props.deClampReason,
      de_worker_inversion: directOrCapture(props.deWorkerInversion, props.captureDeWorkerInversion),
      de_pre_inversion_workers: directOrCapture(
        props.dePreInversionWorkers,
        props.captureDePreInversionWorkers,
      ),
      composition_element_count: directOrCapture(
        props.compositionElementCount,
        props.captureCompositionElementCount,
      ),
      composition_element_count_source: directOrCapture(
        props.compositionElementCountSource,
        props.captureCompositionElementCountSource,
      ),
      composition_element_tags: directOrCapture(
        props.compositionElementTags,
        props.captureCompositionElementTags,
      ),
      aroll_video_count: directOrCapture(props.arollVideoCount, props.captureArollVideoCount),
      heygen_video_count: directOrCapture(props.heygenVideoCount, props.captureHeygenVideoCount),
      adapters_used: directOrCapture(props.adaptersUsed, props.captureAdaptersUsed),
      audio_count: directOrCapture(props.audioCount, props.captureAudioCount),
      image_count: directOrCapture(props.imageCount, props.captureImageCount),
      sub_composition_count: directOrCapture(
        props.subCompositionCount,
        props.captureSubCompositionCount,
      ),
      audio_group_count: directOrCapture(props.audioGroupCount, props.captureAudioGroupCount),
      color_grading_count: directOrCapture(props.colorGradingCount, props.captureColorGradingCount),
      has_lut: directOrCapture(props.hasLut, props.captureHasLut),
      root_body_mismatch: directOrCapture(props.rootBodyMismatch, props.captureRootBodyMismatch),
      root_body_delta_px_bucket: directOrCapture(
        props.rootBodyDeltaPxBucket,
        props.captureRootBodyDeltaPxBucket,
      ),
      de_short_band: directOrCapture(props.deShortBand, props.captureDeShortBand),
      de_parallel_router: directOrCapture(props.deParallelRouter, props.captureDeParallelRouter),
      de_pre_router_workers: directOrCapture(
        props.dePreRouterWorkers,
        props.captureDePreRouterWorkers,
      ),
      de_gate_reason: props.deGateReason,
      gpu_renderer: directOrCapture(props.gpuRenderer, props.captureDeGpuRenderer),
      de_worker_encode: props.deWorkerEncode,
      de_verify_armed: props.deVerifyArmed,
      de_verify_checked: props.deVerifyChecked,
      de_verify_min_db: props.deVerifyMinDb,
      de_verify_init_ms: props.deVerifyInitMs,
      de_self_verify_fallback: directOrCapture(
        props.deSelfVerifyFallback,
        props.captureDeSelfVerifyFallback,
      ),
      de_fallback_reason: directOrCapture(props.deFallbackReason, props.captureDeFallbackReason),
      de_fallback_failed_db: directOrCapture(
        props.deFallbackFailedDb,
        props.captureDeFallbackFailedDb,
      ),
      de_fallback_frame_index: directOrCapture(
        props.deFallbackFrameIndex,
        props.captureDeFallbackFrameIndex,
      ),
      de_fallback_threshold_db: directOrCapture(
        props.deFallbackThresholdDb,
        props.captureDeFallbackThresholdDb,
      ),
      de_blank_suspects: props.deBlankSuspects,
      de_blank_deterministic_accepts: props.deBlankDeterministicAccepts,
      de_blank_recaptures: props.deBlankRecaptures,
      de_boundary_frames: props.deBoundaryFrames,
      de_ncpr_fallbacks: props.deNcprFallbacks,
      de_frame_timeouts: props.deFrameTimeouts,
      ...powerStateFields(),
      source: props.source ?? "cli",
      ...renderOutputShapeEventProperties(props),
      ...renderEnvironmentEventProperties(props),
      ...renderCpuEventProperties(props),
      composition_duration_ms: props.compositionDurationMs,
      composition_width: props.compositionWidth,
      composition_height: props.compositionHeight,
      total_frames: props.totalFrames,
      speed_ratio: props.speedRatio,
      capture_avg_ms: props.captureAvgMs,
      capture_p50_ms: props.captureP50Ms,
      video_count: props.videoCount,
      capture_peak_ms: props.capturePeakMs,
      peak_memory_mb: props.peakMemoryMb,
      memory_free_mb: props.memoryFreeMb,
      tmp_peak_bytes: props.tmpPeakBytes,
      stage_compile_ms: props.stageCompileMs,
      stage_video_extract_ms: props.stageVideoExtractMs,
      stage_audio_process_ms: props.stageAudioProcessMs,
      stage_capture_ms: props.stageCaptureMs,
      stage_capture_setup_ms: props.stageCaptureSetupMs,
      stage_capture_frame_ms: props.stageCaptureFrameMs,
      stage_encode_ms: props.stageEncodeMs,
      stage_assemble_ms: props.stageAssembleMs,
      extract_resolve_ms: props.extractResolveMs,
      extract_hdr_probe_ms: props.extractHdrProbeMs,
      extract_hdr_preflight_ms: props.extractHdrPreflightMs,
      extract_hdr_preflight_count: props.extractHdrPreflightCount,
      extract_vfr_probe_ms: props.extractVfrProbeMs,
      extract_vfr_preflight_ms: props.extractVfrPreflightMs,
      extract_vfr_preflight_count: props.extractVfrPreflightCount,
      extract_phase3_ms: props.extractPhase3Ms,
      extract_cache_hits: props.extractCacheHits,
      extract_cache_misses: props.extractCacheMisses,
    },
    props.distinctId,
  );
  // Send immediately instead of waiting for the exit-time flush. The render
  // command's normal teardown (agent-pipe EPIPE → process.exit(0), or an
  // explicit process.exit) kills the lazy beforeExit flush mid-flight, which
  // is why only ~10-15% of successful renders ever produced a render_complete
  // — and the survivors skewed toward users with low RTT to PostHog. The
  // process is alive and idle here; if it still dies mid-request, the queue
  // keeps the event for the exit-time flushSync() fallback.
  void flush();
}

export function trackRenderError(
  props: {
    fps: number;
    quality: string;
    /** Authoring skill that drove this render (e.g. "hyperframes"). */
    authoringSkill?: string;
    /** Which step resolved authoringSkill: an explicit --skill flag, or the project's own config. */
    authoringSkillSource?: string;
    /** Raw --skill value when it failed skill-slug normalization (an unrecognized skill name). */
    authoringSkillInvalid?: string;
    /** Names of HF_-/HYPERFRAMES_-prefixed env vars present at plan time (never values), capped at 20. */
    hfEnvOverrides?: readonly string[];
    docker: boolean;
    workers?: number;
    gpu?: boolean;
    source?: "cli" | "studio";
    failedStage?: string;
    /** One of ~20 typed producer error classes (CaptureFailure, DrawElementCaptureError, …), or "unknown" for a non-Error throw. */
    errorName?: string;
    /** failedStage normalized to a stable snake_case code. */
    failedStageCode?: string;
    errorMessage?: string;
    elapsedMs?: number;
    peakMemoryMb?: number;
    memoryFreeMb?: number;
    // Attribute this event to a specific user (e.g. the browser user who
    // triggered a studio render); defaults to the install anonymousId.
    distinctId?: string;
  } & RenderObservabilityTelemetryPayload &
    RenderOutputShapeTelemetryPayload &
    RenderEnvironmentTelemetryPayload &
    RenderCpuTelemetryPayload,
): void {
  trackEvent(
    "render_error",
    {
      fps: props.fps,
      quality: props.quality,
      authoring_skill: props.authoringSkill,
      authoring_skill_source: props.authoringSkillSource,
      authoring_skill_invalid: props.authoringSkillInvalid,
      hf_env_overrides: props.hfEnvOverrides ?? [],
      docker: props.docker,
      workers: props.workers,
      gpu: props.gpu,
      source: props.source ?? "cli",
      failed_stage: props.failedStage,
      error_name: props.errorName,
      failed_stage_code: props.failedStageCode,
      error_message: props.errorMessage ? redactTelemetryMessage(props.errorMessage) : undefined,
      elapsed_ms: props.elapsedMs,
      ...renderOutputShapeEventProperties(props),
      ...renderEnvironmentEventProperties(props),
      ...renderCpuEventProperties(props),
      peak_memory_mb: props.peakMemoryMb,
      memory_free_mb: props.memoryFreeMb,
      ...powerStateFields(),
      // gpu_renderer arrives via renderObservabilityEventProperties below:
      // on the failure path perfSummary is never built, so live capture
      // observability is the only source. Backend attribution matters MOST
      // here — a win32 D3D11 crash is what the rollout is watching for.
      ...renderObservabilityEventProperties(props),
    },
    props.distinctId,
  );
  // Same rationale as trackRenderComplete: error paths process.exit(1) before
  // the lazy flush can win its race — send now, exit-time fallback covers the rest.
  void flush();
}

export function trackRenderObservation(props: {
  source?: "cli" | "studio";
  renderJobId?: string;
  phase?: string;
  status?: string;
  compositionHash?: string;
  elapsedMs?: number;
  durationMs?: number;
  message?: string;
  workerCount?: number;
  forceScreenshot?: boolean;
  useStreamingEncode?: boolean;
  useLayeredComposite?: boolean;
  usePageSideCompositing?: boolean;
  hasHdrContent?: boolean;
  captureMode?: string;
  captureOperation?: string;
  framesCompleted?: number;
  totalFrames?: number;
  heartbeatIndex?: number;
  stageElapsedMs?: number;
  videoCount?: number;
  extractedVideoCount?: number;
  totalFramesExtracted?: number;
  maxFramesPerVideo?: number;
  avgFramesPerExtractedVideo?: number;
  vfrPreflightCount?: number;
  vfrPreflightMs?: number;
  cacheHits?: number;
  cacheMisses?: number;
}): void {
  trackEvent("render_observation", {
    source: props.source ?? "cli",
    render_job_id: props.renderJobId,
    phase: props.phase,
    status: props.status,
    composition_hash: props.compositionHash,
    elapsed_ms: props.elapsedMs,
    duration_ms: props.durationMs,
    message: props.message ? redactTelemetryMessage(props.message) : undefined,
    worker_count: props.workerCount,
    force_screenshot: props.forceScreenshot,
    use_streaming_encode: props.useStreamingEncode,
    use_layered_composite: props.useLayeredComposite,
    use_page_side_compositing: props.usePageSideCompositing,
    has_hdr_content: props.hasHdrContent,
    capture_mode: props.captureMode,
    capture_operation: props.captureOperation,
    frames_completed: props.framesCompleted,
    total_frames: props.totalFrames,
    heartbeat_index: props.heartbeatIndex,
    stage_elapsed_ms: props.stageElapsedMs,
    video_count: props.videoCount,
    extracted_video_count: props.extractedVideoCount,
    total_frames_extracted: props.totalFramesExtracted,
    max_frames_per_video: props.maxFramesPerVideo,
    avg_frames_per_extracted_video: props.avgFramesPerExtractedVideo,
    vfr_preflight_count: props.vfrPreflightCount,
    vfr_preflight_ms: props.vfrPreflightMs,
    extract_cache_hits: props.cacheHits,
    extract_cache_misses: props.cacheMisses,
  });
}

export function trackInitTemplate(templateId: string, props?: { tailwind?: boolean }): void {
  trackEvent("init_template", { template: templateId, tailwind: props?.tailwind });
}

/**
 * One event per registry item written into a project.
 *
 * `cli_command` records that `add` ran, never what it installed, so the
 * catalog cannot be ranked by what people actually pull — and the registry is
 * served from raw.githubusercontent.com, which gives us no per-item counter
 * either. `add` is the only place an item lands in a project, so this is the
 * one signal that answers "which block is worth building more of".
 *
 * `requested` separates the item the user named from the transitive
 * `registryDependencies` dragged in behind it. A dependency installed
 * alongside something else is not a vote for itself, and collapsing the two
 * would rank a popular dependency above everything that depends on it.
 *
 * Item names are public registry identifiers, never user content or project
 * data. This routes through `trackEvent`, so an install that opted out
 * (`hyperframes telemetry disable`, `HYPERFRAMES_NO_TELEMETRY`, `DO_NOT_TRACK`)
 * emits nothing.
 */
export function trackRegistryItemAdded(props: {
  item: string;
  itemType: string;
  requested: boolean;
  source: "cli" | "studio";
}): void {
  trackEvent("registry_item_added", {
    item: props.item,
    item_type: props.itemType,
    requested: props.requested,
    source: props.source,
  });
}

export function trackBrowserInstall(): void {
  trackEvent("browser_install", {});
}

// Sign-in lifecycle. The CLI tracks command and render lifecycles but never
// authentication, so `auth login` outcomes are invisible on the observability
// dashboards — a completed sign-in, a browser flow the user abandoned, and a
// rejected key all look identical (i.e. absent). These three events close that
// gap so the sign-in funnel is measurable like the render funnel already is.
// `method` is "oauth" (the default browser PKCE flow), "device" (attended
// RFC 8628 flow), or "api_key". No token,
// key, identity, email, or free text is ever attached — only the method and a
// low-cardinality outcome/reason.
//
// The three trackers accept an optional `distinctId`, forwarded to trackEvent
// exactly like trackRenderComplete/trackRenderError already do. It is unused
// today (events attribute to the install's anonymousId), but pre-plumbing it
// makes attributing a completed sign-in to a resolved identity later a one-line
// change at the callsite rather than a signature sweep.
export type AuthLoginMethod = "oauth" | "device" | "api_key";
export type AuthLoginFailureReason =
  | "flow_error" // OAuth authorization/exchange threw a real error
  | "flow_timeout" // OAuth callback wait elapsed (user closed the tab / walked away)
  | "rejected" // backend rejected the supplied API key (401)
  | "invalid_input" // key was empty, header-unsafe, or too short
  | "aborted"; // prompt cancelled, or no key arrived on stdin before timeout

export function trackAuthLoginStarted(method: AuthLoginMethod, distinctId?: string): void {
  trackEvent("auth_login_started", { method }, distinctId);
}

export function trackAuthLoginCompleted(method: AuthLoginMethod, distinctId?: string): void {
  trackEvent("auth_login_completed", { method }, distinctId);
}

export function trackAuthLoginFailed(
  method: AuthLoginMethod,
  reason: AuthLoginFailureReason,
  distinctId?: string,
): void {
  trackEvent("auth_login_failed", { method, reason }, distinctId);
}

// Associate this install with the signed-in HeyGen account after a completed
// sign-in. Emits a PostHog `$identify` alias whose `$anon_distinct_id` is the
// install's anonymousId, so events recorded before sign-in stitch to the same
// person instead of stranding as a separate anonymous profile. Routed through
// trackEvent so it shares the opt-out gate and flush path — a no-op when
// telemetry is disabled. `distinctId` is the account email (else username);
// see the privacy notice in showTelemetryNotice and docs/packages/cli.mdx.
export function identifyUser(distinctId: string): void {
  if (!distinctId) return;
  trackEvent("$identify", { $anon_distinct_id: readConfig().anonymousId }, distinctId);
}

// A render was rejected by the output-resolution/HDR pre-flight (P1-3)
// before any browser/ffmpeg work. Counts the "caught early" saves on dashboard
// 1783183, distinct from deep render failures. `kind` is the low-cardinality
// `OutputResolutionIssueKind` (aspect-mismatch / hdr-incompatible / etc.),
// typed to the union so the metric can never carry free text.
export function trackRenderPreflightRejected(props: { kind: OutputResolutionIssueKind }): void {
  trackEvent("render_preflight_rejected", { kind: props.kind });
}

export function trackCliError(props: {
  error_name: string;
  error_message: string;
  stack_trace?: string;
  command?: string;
  kind: "uncaught_exception" | "unhandled_rejection" | "command_error";
  /** Low-cardinality figma REST call label (e.g. "images", "files_nodes") —
   *  which endpoint failed, for FigmaClientError-backed failures only. */
  endpoint?: string;
}): void {
  trackEvent("cli_error", {
    error_name: props.error_name,
    // Redact before truncating — CLI messages and stack traces carry absolute
    // install paths (/Users/...), cache dirs, and user-supplied args. Same
    // redaction the render_* events already apply.
    error_message: redactTelemetryMessage(props.error_message).slice(0, 1000),
    stack_trace: props.stack_trace
      ? redactTelemetryMessage(props.stack_trace).slice(0, 2000)
      : undefined,
    command: props.command,
    kind: props.kind,
    endpoint: props.endpoint,
  });
}

/**
 * One figma import outcome (asset/tokens/component). Carries capability mix,
 * dedup effectiveness, and fidelity-degradation counts — never fileKeys,
 * node ids, names, or descriptions.
 */
export function trackFigmaImport(props: {
  phase: "asset" | "tokens" | "component";
  durationMs: number;
  reused?: boolean;
  tokensMode?: "variables" | "styles";
  entryCount?: number;
  unresolvedBindings?: number;
  rasterizedNodes?: number;
  rasterizeFailures?: number;
}): void {
  trackEvent("figma_import", {
    phase: props.phase,
    duration_ms: props.durationMs,
    ...(props.reused !== undefined ? { reused: props.reused } : {}),
    ...(props.tokensMode !== undefined ? { tokens_mode: props.tokensMode } : {}),
    ...(props.entryCount !== undefined ? { entry_count: props.entryCount } : {}),
    ...(props.unresolvedBindings !== undefined
      ? { unresolved_bindings: props.unresolvedBindings }
      : {}),
    ...(props.rasterizedNodes !== undefined ? { rasterized_nodes: props.rasterizedNodes } : {}),
    ...(props.rasterizeFailures !== undefined
      ? { rasterize_failures: props.rasterizeFailures }
      : {}),
  });
}

const reportedFailures = new WeakSet<object>();

// Report why a command failed: cli_command_result records the failure, not the reason. Every
// command-failure report goes through here. Enqueues synchronously; the `exit` handler flushes it.
export function trackCommandFailure(
  command: string,
  err: unknown,
  overrides: { error_name?: string; endpoint?: string } = {},
): void {
  // A CliRuntimeError wraps the failure it presented; report that failure, and only once.
  let failure = err;
  while (failure instanceof CliRuntimeError && failure.cause !== undefined) failure = failure.cause;
  if (typeof failure === "object" && failure !== null) {
    if (reportedFailures.has(failure)) return;
    reportedFailures.add(failure);
  }
  const error = failure instanceof Error ? failure : new Error(String(failure));
  trackCliError({
    error_name: overrides.error_name ?? error.name,
    error_message: error.message,
    stack_trace: error.stack,
    command,
    kind: "command_error",
    endpoint: overrides.endpoint,
  });
}

// Whisper being absent/uninstallable is an environment prerequisite gap, not a
// command crash — track it on its own low-severity metric instead of cli_error
// so the command-failure budget reflects real bugs. `optional` records whether
// the caller (init / skill pipeline) treated captions as skippable.
export function trackTranscribeUnavailable(props: { optional: boolean }): void {
  trackEvent("transcribe_unavailable", { optional: props.optional });
}

// grade-compare / compare stand up headless Chrome and render up to 16 cells.
// Cell count, truncation-cap hits, and whether the render-ready timeout fired
// are the signals needed before safely lifting the cap. Low-cardinality only.
export function trackCompareSheet(props: {
  command: "grade-compare" | "compare";
  cells: number;
  truncated: boolean;
  total: number;
  renderReadyTimedOut: boolean;
}): void {
  trackEvent("media_use_compare", {
    command: props.command,
    cells: props.cells,
    truncated: props.truncated,
    total: props.total,
    render_ready_timed_out: props.renderReadyTimedOut,
  });
}

export function trackHistoryAction(props: { action: string; via: "preview" | "direct" }): void {
  trackEvent("cli_history", props);
}

// A skills install was skipped because a required prerequisite binary is
// absent from PATH (e.g. git on a fresh Windows box). Best-effort callers
// (init) skip cleanly rather than crash, so the skip is otherwise invisible;
// this surfaces the rare environments that hit it. `reason` is a low-cardinality
// binary tag (e.g. "git_missing"), never a path or free text.
export function trackSkillsInstallSkipped(props: { reason: string }): void {
  trackEvent("cli skill install skipped", { reason: props.reason });
}

export function trackFeedbackComment(props: {
  comment: string;
  doctorSummary?: string;
  feedbackId?: string;
  recentRenderIds?: string[];
}): void {
  trackEvent("cli_feedback_comment", {
    comment: props.comment,
    ...(props.doctorSummary ? { doctor_summary: props.doctorSummary } : {}),
    ...(props.feedbackId ? { feedback_id: props.feedbackId } : {}),
    ...(props.recentRenderIds?.length
      ? { recent_render_ids: props.recentRenderIds.join(",") }
      : {}),
  });
}

export function trackRenderFeedback(props: {
  rating: number;
  renderDurationMs?: number;
  comment?: string;
  doctorSummary?: string;
  /**
   * Join key shared with the forwarded feedback report (Slack/backend): the
   * same uuid rides in the report's env string as `fid=…`, so a wild report
   * resolves to exactly one PostHog `cli_render_feedback` or
   * `cli_feedback_comment` event and vice versa.
   */
  feedbackId?: string;
  /** render_job_id values of this install's recent renders (newest last). */
  recentRenderIds?: string[];
}): void {
  // Plain product event, not a PostHog survey response: nothing here is served
  // by the surveys product (no survey definition, no targeting, no popover).
  trackEvent("cli_render_feedback", {
    rating: props.rating,
    rating_scale: FEEDBACK_RATING_SCALE,
    ...(props.comment ? { comment: props.comment } : {}),
    ...(props.renderDurationMs !== undefined ? { render_duration_ms: props.renderDurationMs } : {}),
    ...(props.doctorSummary ? { doctor_summary: props.doctorSummary } : {}),
    ...(props.feedbackId ? { feedback_id: props.feedbackId } : {}),
    // Comma-joined: EventProperties values are scalars only.
    ...(props.recentRenderIds?.length
      ? { recent_render_ids: props.recentRenderIds.join(",") }
      : {}),
  });
}

/**
 * A catalog search that found nothing worth installing.
 *
 * This is the only path that ever sends a query anywhere, and it is a separate
 * deliberate command rather than something `catalog --query` does on its own:
 * plain search stays entirely local, which is what the CLI promises. The query
 * is the point of the report — it names a move the catalog does not have yet,
 * so the gaps can be read directly rather than guessed from install counts.
 */
export function trackCatalogSearchMiss(props: {
  query: string;
  wanted?: string;
  tier?: string;
}): void {
  trackEvent("cli_catalog_search_miss", {
    query: props.query,
    ...(props.wanted ? { wanted: props.wanted } : {}),
    ...(props.tier ? { tier: props.tier } : {}),
  });
}

export function trackCommandResult(props: {
  command: string;
  success: boolean;
  exitCode: number;
  durationMs: number;
  runId?: string;
}): void {
  trackEvent("cli_command_result", {
    command: props.command,
    success: props.success,
    exit_code: props.exitCode,
    duration_ms: props.durationMs,
    ...runIdField(props.runId),
  });
}

export function trackCheckReport(props: {
  contrastGate: boolean;
  motionGate: boolean;
  captionZoneGate: boolean;
  frameCheckGate: boolean;
  snapshotsGate: boolean;
  lintErrors: number;
  lintWarnings: number;
  runtimeErrors: number;
  runtimeWarnings: number;
  layoutErrors: number;
  layoutWarnings: number;
  motionErrors: number;
  motionWarnings: number;
  contrastErrors: number;
  contrastWarnings: number;
  craftWarnings: number;
  launchSettleMs: number;
  seekLoopMs: number;
  contrastMs: number;
  gridPoints: number;
  contrastPoints: number;
  ok: boolean;
  exitCode: number;
  runId?: string;
}): void {
  trackEvent("check_report", {
    gate_contrast: props.contrastGate,
    gate_motion: props.motionGate,
    gate_caption_zone: props.captionZoneGate,
    gate_frame_check: props.frameCheckGate,
    gate_snapshots: props.snapshotsGate,
    lint_errors: props.lintErrors,
    lint_warnings: props.lintWarnings,
    runtime_errors: props.runtimeErrors,
    runtime_warnings: props.runtimeWarnings,
    layout_errors: props.layoutErrors,
    layout_warnings: props.layoutWarnings,
    motion_errors: props.motionErrors,
    motion_warnings: props.motionWarnings,
    contrast_errors: props.contrastErrors,
    contrast_warnings: props.contrastWarnings,
    craft_warnings: props.craftWarnings,
    launch_settle_ms: props.launchSettleMs,
    seek_loop_ms: props.seekLoopMs,
    contrast_ms: props.contrastMs,
    grid_points: props.gridPoints,
    contrast_points: props.contrastPoints,
    ok: props.ok,
    exit_code: props.exitCode,
    ...runIdField(props.runId),
  });
}

/**
 * One lint pass over a project. `code_counts` is what makes "which rules
 * actually fire" answerable; `rule_group_ms` and `slowest_rule` are what make
 * "which rules are expensive" answerable. Only lint rule codes and timings are
 * sent — never file paths, project names, or composition source.
 */
export function trackLintReport(props: {
  /** The command that ran the lint: "lint" or "check". */
  command: string;
  durationMs: number;
  filesScanned: number;
  errorCount: number;
  warningCount: number;
  infoCount: number;
  /** Finding count keyed by lint rule code. */
  codeCounts: Record<string, number>;
  /** Milliseconds spent per rule-source module, summed across files. */
  ruleGroupMs: Record<string, number>;
  /** Slowest single rule as `<group>#<index>`, across every file in the run. */
  slowestRule: string;
  slowestRuleMs: number;
  /** How many rules this build ran, so a ruleset change is visible in the data. */
  ruleCount: number;
  /**
   * Rule count per group. `slowest_rule` is positional, so a group that changed
   * size between two builds has indices that no longer mean the same thing.
   */
  ruleGroupCounts: Record<string, number>;
  runId?: string;
}): void {
  trackEvent("lint_report", {
    command: props.command,
    duration_ms: Math.round(props.durationMs),
    files_scanned: props.filesScanned,
    error_count: props.errorCount,
    warning_count: props.warningCount,
    info_count: props.infoCount,
    codes: Object.keys(props.codeCounts).sort(),
    code_counts: props.codeCounts,
    rule_group_ms: props.ruleGroupMs,
    slowest_rule: props.slowestRule,
    slowest_rule_ms: Math.round(props.slowestRuleMs),
    rule_count: props.ruleCount,
    rule_group_counts: props.ruleGroupCounts,
    ...runIdField(props.runId),
  });
}

/**
 * A finding that survived one or more edits to the file it was reported on.
 *
 * `cleared: false` with a high `edits` is the signal that matters most: a rule
 * an agent kept trying and failing to satisfy. `cleared: true` gives the
 * distribution to compare it against — how many edits a normal finding costs.
 */
export function trackLintRuleStreak(props: {
  code: string;
  severity: string;
  edits: number;
  cleared: boolean;
  command: string;
  runId?: string;
}): void {
  trackEvent("lint_rule_streak", {
    code: props.code,
    severity: props.severity,
    edits: props.edits,
    cleared: props.cleared,
    command: props.command,
    ...runIdField(props.runId),
  });
}