Files
hyperframes/packages/engine/src/index.ts
T
Miguel Ángel 1b8f8a43d4 fix(cli): stopping the preview server no longer leaves a Chrome running (#4183)
* fix(cli): stop the preview server's browser when the server exits

Cancel in-flight renders and thumbnail launches before draining the
browser pool on shutdown, instead of only closing whatever browser was
already registered. A render whose Chrome died from the shutdown signal
itself was being misclassified as a transient failure and retried with a
fresh, untracked browser that outlived the process. Reject new render and
thumbnail requests once shutdown has begun, and await an in-flight
thumbnail launch before closing it.

* fix(cli): close preview browsers before a hung render, keep SIGINT armed

shutdown() awaited renders before closing browsers, so a render slower
than preview.ts 3s exit watchdog left Chrome running when it fired.
Close the thumbnail browser and drain the pool concurrently with, not
after, the render wait, and bound the wait under that watchdog.

A second Ctrl+C/SIGTERM during shutdown removed the one-shot signal
handlers, so it hit the OS default and killed the process before
cleanup ran. Use persistent handlers guarded by the existing
shuttingDown flag instead.

Also: getThumbnailBrowser could still hand a live lease to a request
that lands after shuttingDown flips true; trim a comment over budget;
replace a fixed-sleep test race with a drain-signal barrier.

* fix(engine): make browser pool shutdown terminal, not just draining

drain() resets its drainPromise to null once it settles, so acquire()
only waits for an in-flight drain -- a render still unwinding after
shutdown could relaunch Chrome the instant that drain resolved
(probeStage.ts:449-465 has exactly this gap between an abort check
and a later acquireBrowser call). No non-shutdown caller reuses the
pool after draining it (checked every drainBrowserPool()/drain()
call site), but added a separate terminal close() rather than
changing drain()'s own semantics, so a future reuse caller stays
safe by default.

BrowserLeasePool.close() sets a permanent closed flag before
draining, and acquire() checks it both before and after its one
await point, so a request already mid-await when close() lands still
sees it once that await resolves. studioServer's shutdown() now
calls the new closeBrowserPool() instead of drainBrowserPool().

Also bounds drain()'s own wait: a close() that hangs past 1s now
gets escalated to a force-close instead of blocking the caller
indefinitely, keeping total shutdown time under preview.ts's 3s exit
watchdog alongside the existing render-wait bound.

* fix(engine): trim closeBrowserPool JSDoc to house comment length
2026-09-22 22:49:44 -04:00

449 lines
14 KiB
TypeScript

/**
* @hyperframes/engine
*
* Seekable web page to video rendering engine.
* Framework-agnostic: works with GSAP, Lottie, Three.js, CSS animations,
* or any web content that implements the window.__hf seek protocol.
*
* ## Error Convention
*
* Engine services use three error strategies depending on the operation type:
*
* - **Orchestration services throw on failure.** Browser launch, session init,
* frame capture, and CDP operations propagate errors as thrown exceptions.
* Callers are expected to catch and handle (e.g. frameCapture, browserManager,
* screenshotService, videoFrameExtractor.extractVideoFramesRange).
*
* - **FFmpeg process wrappers return `{ success, error? }` result objects.**
* Encoding, muxing, audio mixing, and streaming encode operations never reject.
* They resolve with a result that includes `success: boolean` and an optional
* `error` string (e.g. chunkEncoder, audioMixer, streamingEncoder).
*
* - **Cleanup and teardown functions never throw.** Browser close, session close,
* temp directory removal, and resource release swallow errors via `.catch(() => {})`
* to avoid masking the original failure (e.g. releaseBrowser, closeCaptureSession,
* FrameLookupTable.cleanup).
*
* - **Optional lookups return `T | undefined` or `T | null`.**
* Functions that may legitimately find nothing (resolveHeadlessShellPath,
* getFrameAtTime, detectGpuEncoder) return a nullable value instead of throwing.
*
*/
// ── Protocol types ─────────────────────────────────────────────────────────────
export type {
HfProtocol,
HfMediaElement,
HfTransitionMeta,
CaptureOptions,
CaptureVideoMetadataHint,
CaptureResult,
CaptureBufferResult,
CapturePerfSummary,
CaptureWarning,
CaptureWarningCode,
SubTimelineWaitOutcome,
} from "./types.js";
// ── Configuration ──────────────────────────────────────────────────────────────
export {
resolveConfig,
validateEngineConfigSnapshot,
DEFAULT_CONFIG,
scaleProtocolTimeoutForComposition,
shouldClampToScreenshotForConcreteGpu,
applyConcreteGpuScreenshotClamp,
explainDrawElementDisabled,
resolveExtractCacheDir,
defaultExtractCacheDir,
EXTRACT_CACHE_DIR_DISABLED_ALIASES,
type EngineConfig,
type ExtractCacheDirResolution,
} from "./config.js";
export {
DEFAULT_VP9_CPU_USED,
MAX_VP9_CPU_USED,
MIN_VP9_CPU_USED,
normalizeVp9CpuUsed,
} from "./services/vp9Options.js";
export {
getCgroupMemoryLimitMb,
getSystemTotalMb,
isLowMemorySystem,
LOW_MEMORY_TOTAL_MB_THRESHOLD,
} from "./services/systemMemory.js";
// ── Browser management ─────────────────────────────────────────────────────────
export { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
export {
acquireBrowser,
releaseBrowser,
drainBrowserPool,
closeBrowserPool,
resolveHeadlessShellPath,
resolveBrowserGpuMode,
buildChromeArgs,
compositionRequiresWebGpu,
assertWebGpuAdapterAvailable,
WebGpuUnavailableError,
ENABLE_BROWSER_POOL,
BrowserLeasePool,
type BuildChromeArgsOptions,
type BrowserLaunchFingerprint,
type BrowserLease,
type BrowserPoolState,
type CaptureMode,
type AcquiredBrowser,
} from "./services/browserManager.js";
export {
augmentProtocolTimeoutError,
isProtocolTimeoutError,
} from "./services/protocolTimeoutErrorHint.js";
export {
augmentPageNavigationTimeoutError,
isPageNavigationTimeoutError,
type NavigationTimeoutHintContext,
} from "./services/pageNavigationTimeoutErrorHint.js";
// ── Frame capture pipeline ──────────────────────────────────────────────────────
export {
createCaptureSession,
initializeSession,
closeCaptureSession,
captureFrame,
captureFrameToBuffer,
captureFrameToBufferPipelined,
captureFramesBatchPipelined,
DrawElementVerificationError,
isDrawElementVerificationError,
getDrawElementVerificationDetails,
type DrawElementVerificationDetails,
recaptureDrawElementFrameForVerify,
completeDeferredDrawElementInit,
writeCapturedFrame,
discardWarmupCapture,
getCompositionDuration,
getCapturePerfSummary,
percentileOf,
prepareCaptureSessionForReuse,
deriveBeginFrameProbeTimeTicks,
type CaptureSession,
isTransientBrowserError,
isMemoryExhaustionError,
type BeforeCaptureHook,
type DiscardWarmupInnerCapture,
type StaticVerificationOutcome,
} from "./services/frameCapture.js";
export {
CaptureFailure,
classifyCaptureFailure,
isFatalCaptureFailure,
type CaptureFailureKind,
type CaptureWorkerDiagnostic,
} from "./services/captureFailure.js";
export {
createChromeMemorySampler,
type ChromeMemoryStats,
} from "./services/chromeMemorySampler.js";
// ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
export {
beginFrameCapture,
pageScreenshotCapture,
getCdpSession,
injectVideoFramesBatch,
syncVideoFrameVisibility,
cdpSessionCache,
probeBeginFrameLiveness,
initTransparentBackground,
captureAlphaPng,
applyDomLayerMask,
removeDomLayerMask,
DOM_LAYER_MASK_STYLE_ID,
type BeginFrameResult,
} from "./services/screenshotService.js";
// ── Encoding ───────────────────────────────────────────────────────────────────
export {
buildEncoderArgs,
encodeFramesFromDir,
buildConcatArgs,
concatVideoFiles,
encodeFramesChunkedConcat,
muxVideoWithAudio,
applyFaststart,
packageHls,
detectGpuEncoder,
ENCODER_PRESETS,
getEncoderPreset,
HLS_MASTER_PLAYLIST,
HLS_VIDEO_PLAYLIST,
HLS_AUDIO_PLAYLIST,
type GpuEncoder,
type PackageHlsOptions,
} from "./services/chunkEncoder.js";
export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
export {
spawnStreamingEncoder,
createFrameReorderBuffer,
type StreamingEncoder,
type StreamingEncoderOptions,
type StreamingEncoderResult,
type FrameReorderBuffer,
} from "./services/streamingEncoder.js";
// ── Media processing ───────────────────────────────────────────────────────────
export {
parseVideoElements,
parseImageElements,
extractVideoFramesRange,
extractAllVideoFrames,
resolveTimelineExtractionWindow,
resolveVideoExtractionWindow,
resolveFinalFrameExtractionWindow,
resolveVideoExtractionDuration,
resolvePlayableVideoDuration,
extractionFrameCountForDuration,
resolveProjectRelativeSrc,
getFrameAtTime,
createFrameLookupTable,
FrameLookupTable,
analyzeClipMediaFit,
classifyVideoExtractionError,
isVideoSourceExtractionError,
runVideoExtractionWithRetry,
safeVideoExtractionSourceIdentity,
VideoSourceExtractionError,
type VideoElement,
type ImageElement,
type ExtractedFrames,
type ExtractionOptions,
type ExtractionResult,
type ExtractionPhaseBreakdown,
type TimelineExtractionWindow,
type VideoExtractionFailure,
type VideoExtractionFailureKind,
type VideoExtractionFailureGroupDetails,
type VideoExtractionFailureRetry,
type VideoExtractionFailureStatusClass,
type SafeVideoExtractionSourceIdentity,
type VideoFrameFormat,
VIDEO_FRAME_FORMATS,
isVideoFrameFormat,
} from "./services/videoFrameExtractor.js";
export {
resolveReferencedStart,
resolveReferencedDuration,
type RefResolverEl,
type RefResolverDoc,
} from "./services/referenceResolver.js";
export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
export {
MIXED_AUDIO_FILENAME,
parseAudioElements,
processCompositionAudio,
} from "./services/audioMixer.js";
export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
export type {
AudioElement,
AudioFailureReason,
AudioFailureStage,
AudioProcessingFailure,
AudioTrack,
AudioVolumeKeyframe,
MixResult,
} from "./services/audioMixer.types.js";
// ── Parallel rendering ─────────────────────────────────────────────────────────
export {
calculateOptimalWorkers,
computeWorkerSizing,
selectVerifySampleIndicesForTask,
verifyDiskDrawElementSamples,
distributeFrames,
distributeFramesInterleaved,
executeParallelCapture,
mergeWorkerFrames,
getSystemResources,
type WorkerTask,
type WorkerResult,
type WorkerSizing,
type WorkerSizingBound,
type ParallelProgress,
} from "./services/parallelCoordinator.js";
// ── File server ────────────────────────────────────────────────────────────────
export {
createFileServer,
type FileServerOptions,
type FileServerHandle,
} from "./services/fileServer.js";
// ── Utilities ──────────────────────────────────────────────────────────────────
export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
export { frameFileExtension } from "./services/frameCapture.js";
export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js";
export {
assertSwiftShader,
readWebGlVendorInfo,
SwiftShaderAssertionError,
BROWSER_GPU_NOT_SOFTWARE,
} from "./utils/assertSwiftShader.js";
export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
export {
extractMediaMetadata,
extractVideoMetadata,
extractFinalVideoFrameTimestamp,
extractAudioMetadata,
probeMediaProfile,
analyzeKeyframeIntervals,
type VideoMetadata,
type AudioMetadata,
type MediaProbeProfile,
type KeyframeAnalysis,
} from "./utils/ffprobe.js";
export {
NOT_MEDIA_PAYLOAD,
NotMediaPayloadError,
assertMediaPayload,
fingerprintElementId,
isNotMediaPayload,
} from "./utils/notMediaPayload.js";
export {
assertPublicHttpsUrl,
isBlockedNetworkHost,
downloadToTemp,
fetchPublicHttpsText,
isHttpUrl,
safeDownloadUrlIdentity,
writeUrlDownloadTelemetry,
type SafeDownloadUrlIdentity,
type UrlDownloadOptions,
type UrlDownloadTelemetry,
type PublicHttpsTextOptions,
} from "./utils/urlDownloader.js";
export {
runFfmpeg,
formatFfmpegError,
isExternalFfmpegInterruption,
type RunFfmpegOptions,
type RunFfmpegResult,
} from "./utils/runFfmpeg.js";
export {
ManagedChildProcess,
type ManagedChildProcessOptions,
type ManagedChildProcessOutcome,
type ManagedProcessTerminationReason,
} from "./utils/managedChildProcess.js";
export {
assertConfiguredFfmpegBinariesExist,
getFfmpegBinary,
getFfprobeBinary,
FFMPEG_PATH_ENV,
FFPROBE_PATH_ENV,
} from "./utils/ffmpegBinaries.js";
export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
// drawElement self-verify comparison — shared by the streaming drain
// (producer) and the parallel disk-path verify (parallelCoordinator).
export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";
export {
decodePng,
decodePngToRgb48le,
blitRgba8OverRgb48le,
blitRgb48leRegion,
blitRgb48leAffine,
parseTransformMatrix,
roundedRectAlpha,
resampleRgb48leObjectFit,
normalizeObjectFit,
type ObjectFit,
} from "./utils/alphaBlit.js";
export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.js";
export {
diffGpuParityFrames,
diffGpuParityPngs,
verifyGpuParity,
type RgbaFrame,
type GpuParityDiffOptions,
type GpuParityDiffResult,
type BlackOnlyInARegion,
type VerifyGpuParityResult,
} from "./utils/gpuParityDiff.js";
// ── Shader transitions ────────────────────────────────────────────────────────
export {
type TransitionFn,
TRANSITIONS,
crossfade,
sampleRgb48le,
hdrToLinear,
linearToHdr,
convertTransfer,
} from "./utils/shaderTransitions.js";
export {
initHdrReadback,
uploadAndReadbackHdrFrame,
float16ToPqRgb,
buildHdrChromeArgs,
launchHdrBrowser,
} from "./services/hdrCapture.js";
export { captureScreenshotWithAlpha } from "./services/screenshotService.js";
export {
hideVideoElements,
showVideoElements,
queryVideoElementBounds,
queryElementStacking,
type VideoElementBounds,
type ElementStackingInfo,
} from "./services/videoFrameInjector.js";
export {
isHdrColorSpace,
detectTransfer,
getHdrEncoderColorParams,
analyzeCompositionHdr,
findHdrAutoPromotion,
formatHdrAutoPromotionWarning,
sanitizeHdrAutoPromotionAsset,
DEFAULT_HDR10_MASTERING,
HDR_AUTO_PROMOTION_PIPELINE,
type HdrTransfer,
type HdrEncoderColorParams,
type HdrAutoPromotion,
type CompositionHdrInfo,
type HdrMasteringMetadata,
} from "./utils/hdr.js";
export type { VideoColorSpace } from "./utils/ffprobe.js";
export {
renderProvenanceArgs,
appendRenderProvenanceArgs,
readRenderProvenance,
PROVENANCE_RENDERER_TAG,
PROVENANCE_VERSION_TAG,
PROVENANCE_RENDERER_NAME,
PROVENANCE_VERSION,
type RenderProvenance,
} from "./utils/renderProvenance.js";
export {
DrawElementCaptureError,
isDrawElementCaptureError,
} from "./services/drawElementCaptureError.js";