import type { CapturePerfSummary } from "@hyperframes/engine";
import type { RenderObservabilityRecorder } from "./observability.js";
/**
 * Opt-in per-frame timing summary emitted through the observability channel
 * whenever a render's capture ran on the FAST-CAPTURE FALLBACK path
 * (drawElement gated off → screenshot capture engaged).
 *
 * ── Why this exists ────────────────────────────────────────────────────────
 * Field-signal baseline from `#hyperframes-cli-feedback` cron sweeps: on
 * darwin/arm64 alone we see ≥2 fast-capture fallbacks/hr triggered by
 * `filter:blur` / `filter:drop-shadow`. That is documented and correct
 * behavior — drawElement can't reproduce those CSS effects and bails to
 * screenshot per `packages/engine/docs/fast-capture-limitations.md` — but the
 * fallback path's per-frame perf is currently *untimed* end-to-end. Session
 * state carries `capturePerf.frameMs` and `getCapturePerfSummary()` emits a
 * `p50TotalMs`, but no tail (p95/p99) and no per-render summary keyed on the
 * specific trigger reaches downstream telemetry. Without that we can't
 * characterize whether the fallback is a 10% tax or a 10× cliff — every
 * future perf discussion is guesswork.
 *
 * ── What this emits ────────────────────────────────────────────────────────
 * A single `capture_fallback_profile` checkpoint per render, per session that
 * hit the fallback, containing:
 *  • `stagePhase: "fallback-capture"` — string tag consumers can match on;
 *  • `frameCount` — captured frames on this session's fallback path;
 *  • `captureTimeP50Ms` / `captureTimeP95Ms` / `captureTimeP99Ms` — nearest-rank
 *    per-frame capture-time percentiles (from `capturePerf.frameMs`);
 *  • `captureTimeTotalMs` — cumulative session capture time
 *    (session.capturePerf.totalMs);
 *  • `message` — human-readable diagnostic prefix incorporating the trigger.
 *
 * Uses the SAME `RenderObservabilityRecorder.checkpoint()` primitive that
 * `observeRenderStage` heartbeats and `stageStart`/`stageEnd` use (introduced
 * in PR #2510). No new telemetry channel, no new sink.
 *
 * ── Why opt-in ────────────────────────────────────────────────────────────
 * The percentile computation itself is trivially cheap (one sort per
 * session), but *emitting* structured records into the observability stream
 * is a downstream-consumer decision — enterprises that don't route
 * `capture_fallback_profile` events shouldn't see unfamiliar phase names in
 * their trace pipeline. `HF_PROFILE_FALLBACK_CAPTURE=true` lets operators
 * opt into the diagnostic surface. Default off preserves current-shape
 * telemetry for every caller that hasn't asked for the new signal.
 *
 * ── What this ISN'T ────────────────────────────────────────────────────────
 * A perf fix. A behavior change on healthy paths. A new metric pipeline. It
 * is *diagnostic groundwork*: once operators can collect real-world
 * p50/p95/p99 keyed on the exact CSS trigger, we can decide whether the
 * fallback-path perf is a design-decision-to-revisit or an acceptable
 * trade-off. That decision is out of scope here.
 */
/** Env var operators set to opt into the diagnostic emission. */
export declare const FALLBACK_PROFILE_ENV_VAR = "HF_PROFILE_FALLBACK_CAPTURE";
/**
 * Emit a `capture_fallback_profile` checkpoint per fallback-engaged capture
 * summary. No-op when the env var is not `"true"` (default) or when the
 * summary set has no fallback-engaged entries.
 *
 * Multi-composition batches produce multiple {@link CapturePerfSummary} in
 * `perfSummaries` (one per worker session). Each fallback-engaged summary
 * gets its own checkpoint — the emitter is *per-session*, not *per-render*
 * — so cross-session divergence (e.g. one worker gated by `filter:blur`,
 * another by `at_risk_timeline`) is visible individually. Downstream
 * consumers can aggregate as needed.
 *
 * @param recorder Observability recorder for the current render.
 * @param perfSummaries `CapturePerfSummary` collected from capture-stage sessions.
 * @param env Env-var view (defaults to `process.env`) — injected for tests.
 * @returns Count of checkpoints emitted (0 when opt-in is off or no fallback fired).
 */
export declare function emitFallbackCaptureProfile(recorder: RenderObservabilityRecorder, perfSummaries: readonly CapturePerfSummary[], env?: Readonly<Record<string, string | undefined>>): number;
//# sourceMappingURL=fallbackCaptureProfile.d.ts.map