Moving sharp and onnxruntime-node to optionalDependencies (in the earlier
capture/native-module hardening) regressed `remove-background` from ~7% to
~97% failure starting at 0.6.101: the command genuinely *requires* both native
modules, but as optional deps they're skipped on most installs, so it hits the
guarded "module not available" error and fails for nearly everyone.
The capture crash that motivated the optional move is already fixed by the
lazy, guarded `await import()` in contentExtractor / inference — that holds
regardless of dependency classification. Making the modules optional was the
over-correction; the lazy import alone was sufficient. sharp ships its own
platform binaries as optional sub-deps, so it installs cleanly as a hard dep
without failing installs on unsupported platforms (it was a hard dep at 0.6.99
with remove-background at a healthy ~7%).
- Move sharp + onnxruntime-node back to `dependencies` (so they install for
everyone again). `@google/genai` stays optional — genuinely optional, lazy,
and not part of the regression.
- Keep the lazy guarded imports — they remain the crash-safety for capture.
- Add trackCommandFailure to remove-background's catch: it self-exits, so the
dispatch wrapper never saw it (the reason stream was blind). Now its failures
carry a reason, closing that command from the wrapper-blind follow-up.
remove-background tests + background-removal suite pass; tsc clean; build green.
Aimed at `npx hyperframes` users (standalone and inside monorepos), where the
native modules `sharp` and `onnxruntime-node` can't install or load.
## Native modules are now optional, and never abort the CLI
`sharp` and `onnxruntime-node` are native modules: their platform binaries ship
as optional sub-dependencies that can fail to land on end-user installs
(--omit=optional, musl/glibc, monorepo hoisting, cross-platform lockfiles,
broken npx cache). Both powered only optional commands, yet both were wired as
hard `dependencies`, so on any platform where a binary can't install the whole
CLI failed to install. Moved both to `optionalDependencies` (alongside
@google/genai) so the core CLI always installs; the native-accelerated paths
light up only when present.
Runtime handling so a missing/unloadable binary degrades instead of crashing:
- `capture` (`contentExtractor.ts`): sharp was a static top-level
`import sharp from "sharp"`, so a load failure threw on module import —
before the inner try/catch — aborting the whole command. Now a guarded lazy
`await import("sharp")` that skips SVG captioning with an actionable warning.
Marked `external` in tsup so esbuild never bundles the native module.
- `remove-background` (`inference.ts`): both `onnxruntime-node` and `sharp`
are loaded here and genuinely required. The dynamic imports are now guarded
to throw an actionable "install / reinstall with optional deps" error
(surfaced cleanly by the command's existing try/catch) instead of a raw
"Cannot find module". New tests assert createSession rejects with that
guidance — before touching the model download — when either module is
unavailable.
`contactSheet.ts` also uses sharp but is already behind a dynamic-import
boundary wrapped in try/catch, so it was never a hard-fatal path.
## inspect: content-overlap as a warning, not a blocking error
The `content_overlap` layout-audit check shipped as `severity: "error"`, and
the audit exits non-zero when `errorCount > 0`, so `inspect` failed for
compositions that intentionally layer text. Downgraded to `severity: "warning"`
so it still reports (and prints the `data-layout-allow-overlap` opt-out hint)
without breaking exit codes. Reversible.
* feat(studio,cli): music beat detection with timeline guides + headless beats CLI
Beat detection for music tracks: the Studio draws beat guides on the active
track, beats are user-editable and persist to a project file, and a new
`hyperframes beats` CLI generates that file headlessly before the Studio opens.
Detection lives in @hyperframes/core/beats (shared by Studio + CLI): an energy
onset detector cross-validated with bpm-detective, regularized to an octave-
aligned grid, silence-gated, with per-beat loudness. Music-only — an
<audio data-timeline-role="music"> is analyzed; voiceover is excluded.
Studio: green beat lines + draggable dots on the selected track; add at playhead,
drag to move, double-click to delete (audio scrubs); edits persist to
beats/<audio>.json and are undoable (interleaved with file history).
CLI: `hyperframes beats [dir]` runs the same detection in headless Chrome
(prebuilt browser bundle in dist) and writes the beat file.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
* feat(studio): timeline beat-grid + zoom UX refinements
- Center-anchored magnify: zooming via the toolbar/slider keeps the time
at the viewport center fixed instead of anchoring at the left. Pinch
still anchors at the cursor.
- Move-snap to beats: dragging a clip snaps whichever edge (start or end)
is nearest a beat, matching the existing resize-edge snapping.
- Beat lines on track backgrounds: faint full-height beat lines now paint
behind the clips on every track lane (brightness scales with loudness);
the green dots stay on the active track's top bar.
- Waveform follows zoom: bars fill the full clip width and resample the
windowed peaks, so the waveform stretches with zoom instead of stopping
partway across a widened clip.
- Beat dots centered in the top bar: align the dot band to the clip top
(CLIP_Y) so the dots sit centered in the dark bar instead of being
bisected by the clip's top border.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
* fix(studio): preserve media sourceDuration across element re-derivation
Moving a non-music clip re-derived the timeline elements into fresh
objects whose sourceDuration the DOM scan hadn't loaded yet. The async
probe skips srcs already in its cache, so the value was silently
dropped — trimFractions then returned no window and the trimmed music
waveform reset to the full source pinned at the track start.
Re-apply the cached probe duration synchronously on every derivation
(applyCachedSourceDurations) and extract the async probe loop into
probeMissingSourceDurations to keep useTimelinePlayer within the file
size limit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
* feat(studio): skip beat-snap on the music track, highlight move-snap target
The music track defines the beats, so moving or trimming it no longer
snaps to its own beats (isMusicTrack guard on both the move and resize
snap paths).
Moving another clip snapped only on drop with no cue. snapMoveStartToBeat
now also returns the beat it will snap to; BeatBackgroundLines draws that
beat's line as a bright neon-green glow while the clip's edge is within
the snap region, so the target is visible before drop.
Also drops .commitmsg.tmp, accidentally committed via git add -A.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
* feat(studio): hide playhead while dragging a beat; default beat dots to music track
- Dragging a beat dot now hides the playhead guideline (new beatDragging
store flag set on beat pointer down/up) so its line doesn't track the
scrub and clutter the beat being moved.
- Beat dots render on the selected track, falling back to the music track
when nothing is selected.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
* fix(core): remove polynomial-ReDoS regex from audioRelPathForSrc
CodeQL js/polynomial-redos: the lazy `.+?` followed by an optional
trailing `[?#].*$` backtracks polynomially on crafted `/preview/...`
inputs. Parse the preview-relative path with indexOf/slice instead, and
strip the query/hash with a single linear char-class search. Behavior is
unchanged for all preview/absolute/blob/data/bare inputs.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
* fix(studio,core,cli): review hardening for beat detection + timeline UX
- playerStore.reset() now clears beat state (analysis, edits, undo/redo,
persist) so a project switch can't apply the previous project's beats,
undo stack, or file-writer to the new one.
- removeUserBeat returns the same reference on a no-op, and delete/move beat
actions skip committing when nothing changed — no more phantom undo
entries / debounced writes for no-op edits.
- regularizeBeats bails to raw onsets when the (octave-misread) tempo would
produce a sub-125ms grid, avoiding a tens-of-thousands-of-beats freeze.
- parseBeats clamps strength to [0,1] and rejects non-finite time/strength,
so a hand-edited file can't feed NaN into the gamma curve (Math.pow on a
negative base) and blank out beat markers.
- Start-edge beat-snap now also requires duration >= minDuration, matching
the end-edge guard, so a rightward snap can't collapse the clip.
- Center-anchor zoom effect always consumes its skip flag, so a pinch that
produced no pps change can't leave it stranded and skip the next zoom.
- Headless beats analyzer projects to {beatTimes,beatStrengths,bpm,confidence}
before returning, so page.evaluate no longer serializes the full decoded
PCM (channelData) across the CDP boundary.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
* fix(core): gate parseBeats on schema version
parseBeats accepted any object with a beats array, so a future v2 beat file
(with changed semantics) would be parsed silently as v1. Reject anything whose
version is not 1, treating an unknown version like an absent/invalid file.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
---------
Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
Miguel Ángel