Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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),
});
}