[miguel-heygen]

What changed

• Every place the CLI and its packages keep downloaded or built files (the headless browser, whisper and Parakeet models, background-removal models, TTS, optional packages, fonts, cloud asset records, the Lambda handler, warm-check state, project history) now takes its folder from one helper, hyperframesCacheDir() in @hyperframes/core/cache-dir.
• Cache paths follow HYPERFRAMES_CACHE_DIR when it is set. The default is unchanged: ~/.cache/hyperframes, so existing caches and CI caches keyed on that path keep working.
• A host that runs the CLI (HyperFrames Desktop, for one) can keep its own cache apart from the one in the home folder.
• The CLI docs mention the variable.

How

• packages/core/src/cacheDir.ts: hyperframesCacheDir(...parts) reads the variable on each call and resolves a relative value.
• 20 call sites in cli, core, engine, inspector and studio-server now use it in place of join(homedir(), ".cache", "hyperframes", …).
• packages/core/src/cacheDir.test.ts checks the default and the override, and scans every package's sources so a new hand-built cache path fails the test.

What I measured

• Linux x64: tsc --noEmit exit 0 in core, engine, inspector and studio-server; cli reports no error in any file this changes (its remaining errors come from unbuilt workspace packages). oxlint, oxfmt --check and fallow audit are clean on the 21 changed files.
• packages/core/src/cacheDir.test.ts: 3 passed. fails without the fix: writing one site back by hand (tts/manager.ts) turns the scan red, naming that file.
• The existing tests of every changed file pass, among them whisper/* (49), tts/* (25), browser/manager, background-removal/*, cloud/offload, utils/optionalPackages, warmCheck*, the deterministicFonts-* and fontCompression suites (245), browserManager* (132) and projectHistory* (154).
• The commit hooks were run as above rather than locally.

What I did NOT exercise

• A real download or install into a moved cache folder; the call sites only change where the folder is.
• Windows. Warm-check state there still lives under LOCALAPPDATA, and on Linux under XDG_RUNTIME_DIR when set; only the fallback follows the variable.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 31, 2026, 8:35 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Edit accuracy: accurate 271 (base branch 271), smooth 109 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (1)

• seqplainkeys-none-px-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true

[heygengenesis]

Verdict: REQUEST CHANGES · 3 blocker · 0 important · 1 nit · head dabb0f5b

The helper and the 20 call sites look right, and the guard scan found no remaining hand-built paths. The blockers are all CI. Comments, Lint/Preflight, Build and Fallow fail because of this PR. Regression, preview, player-perf and Windows are red only because their preflight is. ↓ inline

• nit: a relative HYPERFRAMES_CACHE_DIR resolves against the cwd at import time for the module-level constants (CACHE_DIR, MODELS_DIR, …). The warm-check server imports them in its own cwd and only then calls process.chdir(request.cwd) (cli/src/warmCheck.ts:57). A warm run can therefore use a different folder than a cold one. Consider documenting that the variable should be absolute.

Scope

Read every changed file, grepped the tree at head for leftover .cache paths (only the torch and huggingface ones remain, which is correct), and checked child-process env propagation and the warm-check env digest. The fails without the fix: line names cacheDir.test.ts, which is acceptable. Studio: edit accuracy gate is also red; re-check it once the build passes.

— Genesis

[heygengenesis]

Verdict: REQUEST CHANGES — 3 resolved, 0 open, 1 new · dabb0f5b → 51a321f5

All three earlier blockers and the nit are fixed. Previously the Windows lanes stopped at preflight; now they run, and Tests on windows-latest: core fails on the new test. ↓ inline

— Genesis

[heygengenesis]

Verdict: APPROVE — 1 resolved, 0 open, 0 new · 51a321f5 → 411eb179. Only the test changed: it now uses an absolute temp folder. All CI is green, including Tests on windows-latest: core.

— Genesis

[heygengenesis]

Verdict: APPROVE — 0 resolved, 0 open, 0 new · 4cef924c → cd2cc26a. The new commit moves the OpenCV cache, which arrived in the main merge, onto hyperframesCacheDir. The scan now skips *.test-* helpers, so diff.test-helpers.ts can still copy from the default machine cache. No hand-built .cache/hyperframes path is left outside tests. CI is green on this head.

— Genesis

[heygengenesis]

Verdict: APPROVE — 0 resolved, 0 open, 0 new · cd2cc26a → 74776630. npm now runs inside the staging dir instead of getting --prefix <cache path>. The {} package.json written there keeps npm's local prefix on that dir, and sherpa passes cwd through to npm. The new test checks that no cache path appears in npm's arguments. CodeQL, CI, regression and Windows were still running when I approved.

— Genesis

[heygengenesis]

Verdict: APPROVE — 0 resolved, 0 open, 0 new · 74776630 → 316a5f27. whisper.cpp is now cloned into . with cwd: BUILD_DIR. If the clone fails it leaves an empty BUILD_DIR behind, but the existing stale-build guard (existsSync && !findBuiltBinary) removes it on the next try, so a retry still re-clones. The new test pins the clone's arguments and cwd. CodeQL, CI, regression and Windows were still running when I approved.

— Genesis

[heygengenesis]

Verdict: APPROVE — 0 resolved, 0 open, 0 new · 316a5f27 → cf830e49. Test-only change: the clone test's stub now treats where (Windows) like which, so a system whisper is not found on Windows either. CodeQL passed on 316a5f27. Its only red run was Windows render verification, which this commit fixes. The checks for this head were still running when I approved.

— Genesis

[jrusso1020]

Post-merge advisory review (this PR is already merged into main). Findings flagged for follow-up, not gating.

Reviewed at cf830e4980d9372b0825fecf90e379b732e4b7ed.

No new correctness finding. Genesis already covered the package-subpath descriptor, inspector's source import, and Windows test isolation; those changes are present at this head. The body names cacheDir.test.ts on its fails without the fix: line. I confirmed the source scan rejects a reverted hand-built TTS cache path (1 failed / 2 passed), with the production file restored afterward.

The new helper preserves the default and resolves overrides; the existing browser lock/staging/cache directories move together. npm's staging cwd reaches sherpa, and whisper's failed clone leaves a directory that the existing stale-build guard removes before retry. Relative environment values are import-time dependent for module constants; the CLI docs correctly require an absolute path. The existing font-specific/Lambda temp-root and platform warm-state precedence remains explicit.

Validation: core cache tests 3 passed; optional-package/whisper/sherpa/warm/browser CLI tests 160 passed; engine browser resolution 117 passed; font compression 12 passed. Independent controls exercised a real offline npm install from a local fixture under an apostrophe-and-space cache path, staging cleanup after failure, retry, and live absolute/relative/empty helper overrides. No network model/browser downloads, real whisper build, or Windows execution.

Audited: changed cache-root construction, package export descriptors, staged npm/sherpa install and whisper clone/retry consumers. Trusting: platform-specific downloads/builds and unrelated internals of the larger font/history modules. Project-history suite: 147 passed / 2 skipped / 1 idle-window timing failure; that test supplies an explicit temporary history root and does not use the changed default-root expression. The same test passed on an isolated same-head retry (1 passed).

Need: yes, hosts need a configurable shared cache root · Size: ok, one cross-package path contract · Reuse: one core helper replaces repeated home-cache construction · Simpler: already minimal · Structure: fine
Risk: medium — persistent cache/install paths span multiple packages and platforms.

Verdict: COMMENT (post-merge: Ready)
Reasoning: The shared cache-root contract and staged installation paths hold up in source and focused controls. Platform downloads and Windows remain outside this audit.

— hf-review