@hyperframes/studio-server 0.8.35 → 0.8.36

package/dist/{mediaProxyPreview-CGJ7f9JA.d.ts → mediaProxyPreview-BzPAj--m.d.ts}

@@ -259,12 +259,15 @@ declare function proxyEtagSalt(raw: string | undefined): string;
 /**
  * Injects `window.__HF_MEDIA_CODEC_MAP__` (the U1 codec-facts scan) into
  * served composition HTML, and fire-and-forget pre-warms `resolveProxy` for
- * every browser-hostile entry so an element's proactive swap usually hits a
- * warm cache (KTD: protects the per-origin connection budget under held
- * responses). No second concurrency limiter here — the transcoder's own
- * global bound throttles both pre-warm and element-triggered calls.
- * Pre-warm failures are swallowed; an actual `?hf-proxy=` request surfaces
- * them as a 502. Alpha-bearing entries pre-warm their VP8/WebM variant.
+ * every entry whose codec no browser decodes, so an element's proactive swap
+ * usually hits a warm cache (KTD: protects the per-origin connection budget
+ * under held responses). Conditionally hostile codecs are injected but NOT
+ * pre-warmed: the requesting browser usually plays them, and the transcode
+ * runs concurrently with its first layout. No second concurrency limiter here
+ * — the transcoder's own global bound throttles both pre-warm and
+ * element-triggered calls. Pre-warm failures are swallowed; an actual
+ * `?hf-proxy=` request surfaces them as a 502 and transcodes lazily.
+ * Alpha-bearing entries pre-warm their VP8/WebM variant.
  *
  * The single shared implementation for every auto-proxy surface — the studio
  * preview route (via `injectMediaCodecMap` below) and the CLI's composition /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio-server",
-  "version": "0.8.35",
+  "version": "0.8.36",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
@@ -64,8 +64,8 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "postcss-selector-parser": "^7.1.2",
-    "@hyperframes/parsers": "0.8.35",
-    "@hyperframes/core": "0.8.35"
+    "@hyperframes/core": "0.8.36",
+    "@hyperframes/parsers": "0.8.36"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",

package/dist/chunk-C6CSSUAY.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/helpers/mediaProxyPreview.ts"],"sourcesContent":["import { resolve } from \"node:path\";\nimport type { StudioApiAdapter } from \"../types.js\";\nimport {\n  createMediaCodecProbeCache,\n  proxyVariantFor,\n  scanProjectMediaCodecMap,\n  type HtmlSourceLike,\n  type MediaCodecMap,\n  type MediaCodecProbeCache,\n} from \"./mediaCodecMap.js\";\nimport { resolveProxy, PROXY_PARAMS_VERSION } from \"./proxyTranscoder.js\";\n\n/**\n * Transparent-media-proxy wiring shared by `routes/preview.ts`\n * (docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md, unit U3).\n * Split out of the route module to keep it under the repo's 600-line file cap.\n */\n\n/**\n * Preview-route-local adapter surface for the auto-proxy feature. Both\n * fields are optional so any existing `StudioApiAdapter` value remains\n * structurally assignable without editing the shared interface:\n * `autoProxy` defaults to true (on) when omitted — a later unit wires the\n * CLI `--no-proxy` flag / `hyperframes.json` setting through it;\n * `mediaCodecProbeCache` lets a host share one probe cache across\n * preview/play/static-server surfaces instead of each constructing its own.\n */\nexport type PreviewApiAdapter = StudioApiAdapter & {\n  autoProxy?: boolean;\n  mediaCodecProbeCache?: MediaCodecProbeCache;\n};\n\nexport function isAutoProxyEnabled(adapter: PreviewApiAdapter): boolean {\n  return adapter.autoProxy !== false;\n}\n\n/** One probe cache per server instance — construct once in `registerPreviewRoutes`\n * and reuse across every request so the mtime-cache benefit in\n * `scanProjectMediaCodecMap` actually applies. A host that wants to share the\n * cache across other surfaces (play, static project server) can pass its own\n * via `adapter.mediaCodecProbeCache`. */\nexport function resolvePreviewMediaCodecProbeCache(\n  adapter: PreviewApiAdapter,\n): MediaCodecProbeCache {\n  return adapter.mediaCodecProbeCache ?? createMediaCodecProbeCache();\n}\n\n/**\n * ETag salt for `?hf-proxy=` asset requests, mirroring `variablesEtagSalt` in\n * preview.ts: salted by the raw param value plus the transcoder's params\n * version, so a future proxy-recipe change (which bumps `PROXY_PARAMS_VERSION`)\n * or a different proxy variant invalidates cached 304s without needing to\n * touch the proxy file itself.\n */\nexport function proxyEtagSalt(raw: string | undefined): string {\n  if (raw === undefined) return \"\";\n  return `:proxy:${raw}:${PROXY_PARAMS_VERSION}`;\n}\n\n// Mirrors `injectScriptTagIntoHead` in routes/preview.ts (kept local rather\n// than imported to avoid a helpers → routes dependency edge for one\n// two-line utility).\nfunction injectScriptTagIntoHead(html: string, scriptTag: string): string {\n  if (html.includes(\"</head>\")) return html.replace(\"</head>\", `${scriptTag}\\n</head>`);\n  return `${scriptTag}\\n${html}`;\n}\n\n/**\n * Injects `window.__HF_MEDIA_CODEC_MAP__` (the U1 codec-facts scan) into\n * served composition HTML, and fire-and-forget pre-warms `resolveProxy` for\n * every browser-hostile entry so an element's proactive swap usually hits a\n * warm cache (KTD: protects the per-origin connection budget under held\n * responses). No second concurrency limiter here — the transcoder's own\n * global bound throttles both pre-warm and element-triggered calls.\n * Pre-warm failures are swallowed; an actual `?hf-proxy=` request surfaces\n * them as a 502. Alpha-bearing entries pre-warm their VP8/WebM variant.\n *\n * The single shared implementation for every auto-proxy surface — the studio\n * preview route (via `injectMediaCodecMap` below) and the CLI's composition /\n * static project servers (via the `./media-proxy-preview` subpath export).\n * Empty maps leave HTML untouched, preserving the normal no-hostile-media\n * preview path. On-demand proxy requests enforce the same eligibility gate.\n */\nexport async function injectMediaCodecMapIntoHtml(\n  html: string,\n  projectDir: string,\n  htmlSources: HtmlSourceLike[],\n  probeCache?: MediaCodecProbeCache,\n): Promise<string> {\n  let map: MediaCodecMap;\n  try {\n    map = await scanProjectMediaCodecMap(\n      projectDir,\n      htmlSources,\n      probeCache ? { cache: probeCache } : {},\n    );\n  } catch {\n    // Best-effort: a scan failure must never block serving the page.\n    return html;\n  }\n  if (Object.keys(map).length === 0) return html;\n  for (const [rootRelativePathname, facts] of Object.entries(map)) {\n    if (!facts.browserHostile) continue;\n    resolveProxy(\n      projectDir,\n      resolve(projectDir, rootRelativePathname.replace(/^\\/+/, \"\")),\n      proxyVariantFor(facts),\n    ).catch(() => {\n      // Swallowed: the pre-warm is best-effort. A real `?hf-proxy=` request\n      // for this asset re-attempts the transcode and reports failure (502).\n    });\n  }\n  // <-escape prevents a src path containing \"</script>\" from breaking out of\n  // the injected tag, mirroring injectPreviewVariables in helpers/previewVariables.ts.\n  const json = JSON.stringify(map)\n    .replace(/</g, \"\\\\u003c\")\n    .replace(/\\u2028/g, \"\\\\u2028\")\n    .replace(/\\u2029/g, \"\\\\u2029\");\n  const tag = `<script data-hf-media-codec-map>window.__HF_MEDIA_CODEC_MAP__=${json};</script>`;\n  return injectScriptTagIntoHead(html, tag);\n}\n\n/**\n * Adapter-aware wrapper used by the studio preview routes: skipped entirely\n * (no scan, no injection) when auto-proxy is off for this adapter.\n */\nexport async function injectMediaCodecMap(\n  html: string,\n  adapter: PreviewApiAdapter,\n  projectDir: string,\n  compSrcPath: string,\n  probeCache: MediaCodecProbeCache,\n): Promise<string> {\n  if (!isAutoProxyEnabled(adapter)) return html;\n  return injectMediaCodecMapIntoHtml(html, projectDir, [{ html, compSrcPath }], probeCache);\n}\n"],"mappings":";;;;;;;;;;;AAAA,SAAS,eAAe;AAgCjB,SAAS,mBAAmB,SAAqC;AACtE,SAAO,QAAQ,cAAc;AAC/B;AAOO,SAAS,mCACd,SACsB;AACtB,SAAO,QAAQ,wBAAwB,2BAA2B;AACpE;AASO,SAAS,cAAc,KAAiC;AAC7D,MAAI,QAAQ,OAAW,QAAO;AAC9B,SAAO,UAAU,GAAG,IAAI,oBAAoB;AAC9C;AAKA,SAAS,wBAAwB,MAAc,WAA2B;AACxE,MAAI,KAAK,SAAS,SAAS,EAAG,QAAO,KAAK,QAAQ,WAAW,GAAG,SAAS;AAAA,QAAW;AACpF,SAAO,GAAG,SAAS;AAAA,EAAK,IAAI;AAC9B;AAkBA,eAAsB,4BACpB,MACA,YACA,aACA,YACiB;AACjB,MAAI;AACJ,MAAI;AACF,UAAM,MAAM;AAAA,MACV;AAAA,MACA;AAAA,MACA,aAAa,EAAE,OAAO,WAAW,IAAI,CAAC;AAAA,IACxC;AAAA,EACF,QAAQ;AAEN,WAAO;AAAA,EACT;AACA,MAAI,OAAO,KAAK,GAAG,EAAE,WAAW,EAAG,QAAO;AAC1C,aAAW,CAAC,sBAAsB,KAAK,KAAK,OAAO,QAAQ,GAAG,GAAG;AAC/D,QAAI,CAAC,MAAM,eAAgB;AAC3B;AAAA,MACE;AAAA,MACA,QAAQ,YAAY,qBAAqB,QAAQ,QAAQ,EAAE,CAAC;AAAA,MAC5D,gBAAgB,KAAK;AAAA,IACvB,EAAE,MAAM,MAAM;AAAA,IAGd,CAAC;AAAA,EACH;AAGA,QAAM,OAAO,KAAK,UAAU,GAAG,EAC5B,QAAQ,MAAM,SAAS,EACvB,QAAQ,WAAW,SAAS,EAC5B,QAAQ,WAAW,SAAS;AAC/B,QAAM,MAAM,iEAAiE,IAAI;AACjF,SAAO,wBAAwB,MAAM,GAAG;AAC1C;AAMA,eAAsB,oBACpB,MACA,SACA,YACA,aACA,YACiB;AACjB,MAAI,CAAC,mBAAmB,OAAO,EAAG,QAAO;AACzC,SAAO,4BAA4B,MAAM,YAAY,CAAC,EAAE,MAAM,YAAY,CAAC,GAAG,UAAU;AAC1F;","names":[]}

package/dist/chunk-NJISQQTN.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/helpers/mediaCodecMap.ts","../src/helpers/mediaMetadata.ts"],"sourcesContent":["import { existsSync, statSync } from \"node:fs\";\nimport { relative, resolve, sep } from \"node:path\";\nimport { rewriteAssetPath } from \"@hyperframes/parsers/asset-paths\";\nimport {\n  cleanAssetUrl,\n  isRemoteOrInlineUrl,\n  isUnresolvedAssetPlaceholder,\n  maskNonScannableRanges,\n  resolveLocalAssetCandidates,\n} from \"@hyperframes/parsers/asset-resolution\";\nimport { pixelFormatHasAlpha, probeMediaMetadata, type FfprobeRunner } from \"./mediaMetadata.js\";\n\n/**\n * One reusable answer to \"what codec is this asset, and is it browser-hostile?\",\n * built on top of `mediaMetadata.ts`'s ffprobe-backed prober so studio-server\n * probes each asset once instead of running a second prober.\n */\n\nexport interface AssetCodecFacts {\n  codecName: string;\n  browserHostile: boolean;\n  /** Coarse `canPlayType()` input; `null` when not applicable (safe codec) or\n   * when no representative mime exists (ProRes: browsers never decode it, so\n   * the runtime always proxies rather than probing `canPlayType`). */\n  representativeMime: string | null;\n  /** Source carries an alpha channel (ffprobe pix_fmt). Alpha sources use a\n   * VP8/WebM proxy so their transparency is preserved across Chromium builds. */\n  hasAlpha: boolean;\n}\n\n/** Server-root-relative URL pathname -> that asset's codec facts. */\nexport type MediaCodecMap = Record<string, AssetCodecFacts>;\n\n/**\n * Browser-hostile codec table v1. One exported constant so extending it is a\n * one-line change. `ffprobe` cannot emit exact RFC 6381 codec strings, so\n * these `representativeMime` values are deliberately coarse (a false\n * positive costs one proxy transcode, never correctness; a false negative is\n * rescued by the runtime's reactive zero-videoWidth swap).\n */\nexport const BROWSER_HOSTILE_CODECS: Record<string, string | null> = {\n  hevc: 'video/mp4; codecs=\"hvc1.1.6.L120.B0\"',\n  prores: null,\n  av1: 'video/mp4; codecs=\"av01.0.08M.08\"',\n  // VP9 is browser-dependent: Chrome generally decodes it while Safari\n  // support varies. Treat it as conditional so canPlayType keeps the\n  // original where supported and transparently proxies it where unsupported.\n  vp9: 'video/webm; codecs=\"vp09.00.10.08\"',\n};\n\nexport type ProxyVariant = \"h264\" | \"vp8\";\nexport type ProxyVariantRequest = ProxyVariant | \"auto\";\n\nexport const PROXY_VARIANT_CONFIG: Record<\n  ProxyVariant,\n  { extension: \".mp4\" | \".webm\"; contentType: \"video/mp4\" | \"video/webm\" }\n> = {\n  h264: { extension: \".mp4\", contentType: \"video/mp4\" },\n  vp8: { extension: \".webm\", contentType: \"video/webm\" },\n};\n\nexport function isProxyVariant(value: string): value is ProxyVariant {\n  return Object.hasOwn(PROXY_VARIANT_CONFIG, value);\n}\n\nexport function isProxyVariantRequest(value: string): value is ProxyVariantRequest {\n  return value === \"auto\" || isProxyVariant(value);\n}\n\nexport function proxyVariantFor(facts: AssetCodecFacts): ProxyVariant {\n  return facts.hasAlpha ? \"vp8\" : \"h264\";\n}\n\nexport function resolveProxyVariantRequest(\n  request: ProxyVariantRequest,\n  facts: AssetCodecFacts,\n): ProxyVariant | null {\n  const expected = proxyVariantFor(facts);\n  return request === \"auto\" || request === expected ? expected : null;\n}\n\nexport type MediaProxyIneligibilityReason = \"browser_safe_codec\" | \"unknown_codec\";\n\nexport type MediaProxyEligibility =\n  | { eligible: true }\n  | { eligible: false; reason: MediaProxyIneligibilityReason };\n\n/** Single policy gate shared by proactive scans and on-demand proxy routes. */\nexport function decideMediaProxyEligibility(facts: AssetCodecFacts | null): MediaProxyEligibility {\n  if (!facts) return { eligible: false, reason: \"unknown_codec\" };\n  if (!facts.browserHostile) return { eligible: false, reason: \"browser_safe_codec\" };\n  return { eligible: true };\n}\n\nfunction codecFactsFor(codecName: string, hasAlpha: boolean): AssetCodecFacts {\n  const isHostile = Object.hasOwn(BROWSER_HOSTILE_CODECS, codecName);\n  return {\n    codecName,\n    browserHostile: isHostile,\n    representativeMime: isHostile ? (BROWSER_HOSTILE_CODECS[codecName] ?? null) : null,\n    hasAlpha,\n  };\n}\n\n/**\n * Probe a single video asset. Best-effort: ffprobe missing, erroring, or\n * finding no video stream resolves to `null` (asset omitted by the caller),\n * never a throw. Async so a pool of probes runs concurrently (the default\n * runner is `execFile`-based).\n */\nexport async function probeAssetCodec(\n  filePath: string,\n  runner?: FfprobeRunner,\n): Promise<AssetCodecFacts | null> {\n  const metadata = runner\n    ? await probeMediaMetadata(filePath, runner)\n    : await probeMediaMetadata(filePath);\n  if (metadata.kind !== \"video\" || metadata.probeError) return null;\n  const codecName = metadata.color.codecName;\n  if (!codecName) return null;\n  return codecFactsFor(codecName, pixelFormatHasAlpha(metadata.color.pixelFormat));\n}\n\ninterface CachedAssetProbe {\n  mtimeMs: number;\n  size: number;\n  facts: AssetCodecFacts | null;\n}\n\n/** Per (path, mtime) probe cache. Construct one per project/server lifetime\n * and reuse it across scans; a fresh instance defeats the caching benefit. */\nexport type MediaCodecProbeCache = Map<string, CachedAssetProbe>;\n\nexport function createMediaCodecProbeCache(): MediaCodecProbeCache {\n  return new Map();\n}\n\n// Used when a caller doesn't pass its own cache — still correct (probes every\n// time a fresh Map would), but callers that want the mtime-cache benefit\n// across repeated scans (the studio preview route, etc.) should construct\n// and hold their own cache via `createMediaCodecProbeCache`.\nconst defaultProbeCache: MediaCodecProbeCache = new Map();\nconst MAX_PROBE_CACHE_ENTRIES = 512;\n\nfunction rememberProbeResult(\n  cache: MediaCodecProbeCache,\n  filePath: string,\n  result: CachedAssetProbe,\n): void {\n  if (!cache.has(filePath) && cache.size >= MAX_PROBE_CACHE_ENTRIES) {\n    const oldest = cache.keys().next().value;\n    if (oldest) cache.delete(oldest);\n  }\n  // Refresh insertion order so frequently used assets remain resident.\n  cache.delete(filePath);\n  cache.set(filePath, result);\n}\n\nasync function probeAssetCodecCached(\n  filePath: string,\n  cache: MediaCodecProbeCache,\n  runner?: FfprobeRunner,\n): Promise<AssetCodecFacts | null> {\n  let stat: ReturnType<typeof statSync>;\n  try {\n    stat = statSync(filePath);\n  } catch {\n    return null;\n  }\n  const cached = cache.get(filePath);\n  if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {\n    rememberProbeResult(cache, filePath, cached);\n    return cached.facts;\n  }\n  const facts = await probeAssetCodec(filePath, runner);\n  rememberProbeResult(cache, filePath, { mtimeMs: stat.mtimeMs, size: stat.size, facts });\n  return facts;\n}\n\n/** Structurally compatible with `packages/lint/src/hevcPreviewLint.ts`'s\n * (unexported) `HtmlSourceLike`. */\nexport interface HtmlSourceLike {\n  html: string;\n  compSrcPath?: string;\n}\n\n// --- <video src> collection: shared primitives live in\n// @hyperframes/parsers/asset-resolution; the <video>-specific regex and the\n// pinned key derivation stay here.\nconst VIDEO_SRC_RE = /<video\\b[^>]*\\bsrc\\s*=\\s*[\"']([^\"']+)[\"'][^>]*>/gi;\n\n/**\n * Resolve a `<video src>` reference to an existing local file.\n *\n * `rootRelativePathname` is the map key format PINNED by this plan's Key\n * Technical Decisions: project-root-relative URL pathname, percent-decoded,\n * query-string-stripped, forward-slash separated, leading-slash prefixed\n * (e.g. \"/assets/videos/clip.mp4\"). This must match what the runtime derives\n * via `new URL(el.currentSrc || el.src, document.baseURI).pathname`, because\n * server-side scanning resolves filesystem paths while the DOM sees served\n * URLs — a documented prior source of this exact class of bug.\n */\nfunction resolveExistingLocalAsset(\n  projectDir: string,\n  url: string,\n): { resolvedPath: string; rootRelativePathname: string } | null {\n  const projectRoot = resolve(projectDir);\n  const resolvedPath = resolveLocalAssetCandidates(projectRoot, url).find((candidate) =>\n    existsSync(candidate),\n  );\n  if (!resolvedPath) return null;\n  const rootRelative = relative(projectRoot, resolvedPath).split(sep).join(\"/\");\n  return { resolvedPath, rootRelativePathname: `/${rootRelative}` };\n}\n\n/**\n * Collects local `<video src>` references, resolved to their absolute path\n * and deduped by that path, keyed by the pinned root-relative URL pathname.\n */\n// fallow-ignore-next-line complexity\nfunction collectLocalVideoAssets(\n  projectDir: string,\n  htmlSources: HtmlSourceLike[],\n): Map<string, string> {\n  const candidates = new Map<string, string>();\n\n  for (const { html, compSrcPath } of htmlSources) {\n    const scannable = maskNonScannableRanges(html);\n    const re = new RegExp(VIDEO_SRC_RE.source, VIDEO_SRC_RE.flags);\n    let match: RegExpExecArray | null;\n    while ((match = re.exec(scannable)) !== null) {\n      const rawSrc = match[1] ?? \"\";\n      // Placeholder check runs on the RAW value: cleanAssetUrl() splits on ?/# and would chop inside a ${...} token.\n      if (isUnresolvedAssetPlaceholder(rawSrc)) continue;\n      const src = cleanAssetUrl(rawSrc);\n      if (!src || isRemoteOrInlineUrl(src)) continue;\n      const rootRelativeSrc = compSrcPath ? rewriteAssetPath(compSrcPath, src) : src;\n      const resolved = resolveExistingLocalAsset(projectDir, rootRelativeSrc);\n      if (!resolved) continue;\n      candidates.set(resolved.resolvedPath, resolved.rootRelativePathname);\n    }\n  }\n\n  return candidates;\n}\n\n// Bounds concurrent ffprobe child processes for projects referencing many\n// videos, mirroring `PROBE_CONCURRENCY` in `hevcPreviewLint.ts`.\nconst PROBE_CONCURRENCY = 8;\n\nexport interface ScanProjectMediaCodecMapOptions {\n  /** Persisted across calls by the caller for the mtime-cache benefit;\n   * defaults to a shared module-level cache when omitted. */\n  cache?: MediaCodecProbeCache;\n  runner?: FfprobeRunner;\n}\n\n/**\n * Scans a project's composition HTML for local `<video src>` references and\n * returns the injection map: root-relative URL pathname -> codec facts.\n * Best-effort throughout — a video whose codec can't be determined (missing\n * ffprobe, probe error, no video stream) is simply omitted, never thrown.\n */\nexport async function scanProjectMediaCodecMap(\n  projectDir: string,\n  htmlSources: HtmlSourceLike[],\n  options: ScanProjectMediaCodecMapOptions = {},\n): Promise<MediaCodecMap> {\n  const candidates = collectLocalVideoAssets(projectDir, htmlSources);\n  if (candidates.size === 0) return {};\n\n  const cache = options.cache ?? defaultProbeCache;\n  const entries = [...candidates.entries()]; // [resolvedPath, rootRelativePathname]\n  const facts = new Array<AssetCodecFacts | null>(entries.length).fill(null);\n  let nextIndex = 0;\n  const workerCount = Math.min(PROBE_CONCURRENCY, entries.length);\n  await Promise.all(\n    Array.from({ length: workerCount }, async () => {\n      while (nextIndex < entries.length) {\n        const index = nextIndex++;\n        const entry = entries[index];\n        if (!entry) break;\n        facts[index] = await probeAssetCodecCached(entry[0], cache, options.runner);\n      }\n    }),\n  );\n\n  const map: MediaCodecMap = {};\n  entries.forEach(([, pathname], index) => {\n    const entryFacts = facts[index];\n    if (entryFacts?.browserHostile) map[pathname] = entryFacts;\n  });\n  return map;\n}\n","import { execFile } from \"node:child_process\";\nimport { extname } from \"node:path\";\nimport { findFfBinary } from \"@hyperframes/parsers/ff-binaries\";\n\nexport interface FfprobeRunResult {\n  status: number | null;\n  stdout: string | Buffer;\n  stderr: string | Buffer;\n  /** Spawn-level failure (covers both `NodeJS.ErrnoException` and\n   * `ExecFileException`); only `code === \"ENOENT\"` is ever inspected. */\n  error?: { code?: string | number | null | undefined };\n}\n\n/** Injectable ffprobe runner. May be synchronous (tests) or async (the\n * default `execFile`-based runner below), so cold scans can run many probes\n * concurrently off the event loop. */\nexport type FfprobeRunner = (\n  command: string,\n  args: string[],\n  options?: { timeout?: number; maxBuffer?: number },\n) => FfprobeRunResult | Promise<FfprobeRunResult>;\n\n/** Default runner: genuinely async (`execFile`), unlike the previous\n * `spawnSync`-based one — a pool of concurrent probes actually parallelizes\n * (mirrors `execFileAsync` in packages/lint/src/hevcPreviewLint.ts). */\nconst execFileRunner: FfprobeRunner = (command, args, options) =>\n  new Promise<FfprobeRunResult>((resolvePromise) => {\n    execFile(\n      command,\n      args,\n      { timeout: options?.timeout, maxBuffer: options?.maxBuffer, windowsHide: true },\n      (error, stdout, stderr) => {\n        if (error && error.code === \"ENOENT\") {\n          resolvePromise({ status: null, stdout: \"\", stderr: \"\", error });\n          return;\n        }\n        if (error) {\n          // Nonzero exit / timeout / kill: report a nonzero status; callers\n          // only distinguish \"ok\" (0) from \"failed\" from \"ENOENT\".\n          const status = typeof error.code === \"number\" ? error.code : 1;\n          resolvePromise({ status, stdout: stdout ?? \"\", stderr: stderr ?? \"\" });\n          return;\n        }\n        resolvePromise({ status: 0, stdout: stdout ?? \"\", stderr: stderr ?? \"\" });\n      },\n    );\n  });\n\nexport type MediaDynamicRange = \"hdr\" | \"sdr\" | \"unknown\";\nexport type MediaHdrTransfer = \"pq\" | \"hlg\" | \"unknown\";\n\nexport interface MediaColorMetadata {\n  dynamicRange: MediaDynamicRange;\n  hdrTransfer: MediaHdrTransfer | null;\n  label: string;\n  isHdr: boolean;\n  codecName?: string;\n  profile?: string;\n  pixelFormat?: string;\n  colorSpace?: string;\n  colorTransfer?: string;\n  colorPrimaries?: string;\n  bitsPerRawSample?: string;\n}\n\nexport interface MediaMetadata {\n  kind: \"video\" | \"image\" | \"audio\" | \"unknown\";\n  color: MediaColorMetadata;\n  probeError?: string;\n}\n\ninterface FfprobeStream {\n  codec_type?: string;\n  codec_name?: string;\n  profile?: string;\n  pix_fmt?: string;\n  color_space?: string;\n  color_transfer?: string;\n  color_primaries?: string;\n  bits_per_raw_sample?: string;\n  disposition?: { attached_pic?: number };\n}\n\nconst VIDEO_EXT = new Set([\n  \".mp4\",\n  \".mov\",\n  \".webm\",\n  \".mkv\",\n  \".avi\",\n  \".m4v\",\n  \".mxf\",\n  \".mts\",\n  \".m2ts\",\n  \".ts\",\n]);\nconst IMAGE_EXT = new Set([\".jpg\", \".jpeg\", \".png\", \".webp\", \".avif\"]);\nconst AUDIO_EXT = new Set([\".mp3\", \".wav\", \".ogg\", \".m4a\", \".aac\"]);\n\nfunction lower(value: string | undefined): string {\n  return value?.toLowerCase() ?? \"\";\n}\n\nfunction inferKindFromPath(path: string): MediaMetadata[\"kind\"] {\n  const ext = extname(path).toLowerCase();\n  if (VIDEO_EXT.has(ext)) return \"video\";\n  if (IMAGE_EXT.has(ext)) return \"image\";\n  if (AUDIO_EXT.has(ext)) return \"audio\";\n  return \"unknown\";\n}\n\nfunction colorLabel(input: {\n  isHdr: boolean;\n  hdrTransfer: MediaHdrTransfer | null;\n  colorPrimaries: string;\n  colorSpace: string;\n  colorTransfer: string;\n}): string {\n  if (input.isHdr) {\n    if (input.hdrTransfer === \"pq\") return \"HDR PQ\";\n    if (input.hdrTransfer === \"hlg\") return \"HDR HLG\";\n    return \"HDR\";\n  }\n  if (\n    input.colorPrimaries.includes(\"bt709\") ||\n    input.colorSpace.includes(\"bt709\") ||\n    input.colorTransfer.includes(\"bt709\")\n  ) {\n    return \"SDR Rec.709\";\n  }\n  return \"SDR/unknown\";\n}\n\n// Conservative alpha-bearing pix_fmt list: yuva* (yuva420p, yuva444p10le...),\n// rgba/argb/bgra/abgr (packed RGB+alpha), gbrap* (planar GBR+alpha, ProRes\n// 4444 decodes to these), ya* (gray+alpha). Prefix match keeps bit-depth /\n// endianness suffixes covered.\nconst ALPHA_PIX_FMT_RE = /^(?:yuva|rgba|argb|bgra|abgr|gbrap|ya)/;\n\n/** True when an ffprobe `pix_fmt` carries an alpha component. */\nexport function pixelFormatHasAlpha(pixFmt: string | undefined): boolean {\n  return pixFmt !== undefined && ALPHA_PIX_FMT_RE.test(pixFmt.toLowerCase());\n}\n\nexport function classifyMediaColor(stream: FfprobeStream | null | undefined): MediaColorMetadata {\n  const colorPrimaries = lower(stream?.color_primaries);\n  const colorSpace = lower(stream?.color_space);\n  const colorTransfer = lower(stream?.color_transfer);\n  const isHdr =\n    colorPrimaries.includes(\"bt2020\") ||\n    colorSpace.includes(\"bt2020\") ||\n    colorTransfer === \"smpte2084\" ||\n    colorTransfer === \"arib-std-b67\";\n  const hdrTransfer: MediaHdrTransfer | null = isHdr\n    ? colorTransfer === \"smpte2084\"\n      ? \"pq\"\n      : colorTransfer === \"arib-std-b67\"\n        ? \"hlg\"\n        : \"unknown\"\n    : null;\n\n  return {\n    dynamicRange: stream ? (isHdr ? \"hdr\" : \"sdr\") : \"unknown\",\n    hdrTransfer,\n    label: stream\n      ? colorLabel({ isHdr, hdrTransfer, colorPrimaries, colorSpace, colorTransfer })\n      : \"Unknown\",\n    isHdr,\n    codecName: stream?.codec_name,\n    profile: stream?.profile,\n    pixelFormat: stream?.pix_fmt,\n    colorSpace: stream?.color_space,\n    colorTransfer: stream?.color_transfer,\n    colorPrimaries: stream?.color_primaries,\n    bitsPerRawSample: stream?.bits_per_raw_sample,\n  };\n}\n\nexport async function probeMediaMetadata(\n  filePath: string,\n  runner: FfprobeRunner = execFileRunner,\n): Promise<MediaMetadata> {\n  const kind = inferKindFromPath(filePath);\n  if (kind === \"audio\" || kind === \"unknown\") {\n    return { kind, color: classifyMediaColor(null) };\n  }\n\n  // The default runner degrades a missing ffprobe to \"unavailable\" without\n  // spawning; injected runners own execution and receive the normal command.\n  const ffprobePath =\n    findFfBinary(\"ffprobe\", { configuredMustExist: true }) ??\n    (runner === execFileRunner ? undefined : \"ffprobe\");\n  if (!ffprobePath) {\n    return { kind, color: classifyMediaColor(null), probeError: \"ffprobe unavailable\" };\n  }\n\n  const result = await runner(\n    ffprobePath,\n    [\n      \"-v\",\n      \"error\",\n      \"-show_entries\",\n      \"stream=codec_type,codec_name,profile,pix_fmt,color_space,color_transfer,color_primaries,bits_per_raw_sample:stream_disposition=attached_pic\",\n      \"-of\",\n      \"json\",\n      \"--\",\n      filePath,\n    ],\n    { timeout: 15_000, maxBuffer: 1024 * 1024 },\n  );\n\n  if (result.error?.code === \"ENOENT\") {\n    return { kind, color: classifyMediaColor(null), probeError: \"ffprobe unavailable\" };\n  }\n  if (result.status !== 0) {\n    return { kind, color: classifyMediaColor(null), probeError: \"ffprobe failed\" };\n  }\n\n  try {\n    const parsed = JSON.parse(String(result.stdout || \"{}\")) as { streams?: FfprobeStream[] };\n    const stream = parsed.streams?.find((item) => {\n      if (kind === \"image\") return item.codec_type === \"video\";\n      return item.codec_type === kind && item.disposition?.attached_pic !== 1;\n    });\n    return { kind, color: classifyMediaColor(stream) };\n  } catch {\n    return { kind, color: classifyMediaColor(null), probeError: \"ffprobe returned invalid json\" };\n  }\n}\n"],"mappings":"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","names":[]}