Skip to content

refactor: isolate caption render planning - #5

Open
anaschatz wants to merge 1 commit into
mainfrom
codex/maintainability-caption-render-planning
Open

refactor: isolate caption render planning#5
anaschatz wants to merge 1 commit into
mainfrom
codex/maintainability-caption-render-planning

Conversation

@anaschatz

Copy link
Copy Markdown
Owner

Problem

Per-frame caption cue selection, cue normalization, typography defaults, and Budget Friendly kinetic calculations were embedded in the 7.5k-line clipper.py, making these deterministic rules difficult to characterize independently.

Scope

  • Adds one standard-library-only leaf: caption_render_planning.py.
  • Extracts active cue selection, render-plan normalization, typography values, and kinetic-state calculation.
  • Keeps _CaptionRenderer, drawing, _editorial_kinetic_state, caption_index, _render_elapsed, and all existing patch points in clipper.py.
  • Adds characterization-first coverage and an engineering report.

Explicit non-goals: no cue grouping/timing changes; no font, layout, safe-box, coordinate, pixel, Pillow/OpenCV, FFmpeg, cache, provider, API, migration, infrastructure, or video-output changes.

Architecture

Before: frame loop -> embedded selection -> draw normalization -> kinetic math -> Pillow/OpenCV
After:  frame loop -> pure planner -> immutable results -> clipper facade -> Pillow/OpenCV

The new module imports only typing; it has no environment, filesystem, logging, subprocess, NumPy, OpenCV, Pillow, or clipper.py dependency.

Provenance and size

  • Base: 33338d72cfa5de94370c0f2609fadf35f8057ae8
  • Head: f300a78f30df6170b3d86505e5ffd6f1f26da72d
  • clipper.py: 7,590 -> 7,468 LOC (-122)
  • New planner: 218 LOC
  • Production Python: 30,098 -> 30,194 LOC (+96)

The small positive total provides explicit immutable result contracts and a separately testable pure boundary while shrinking the monolithic facade.

Characterization-first evidence

  • 9 behavioral tests passed against the original implementation before extraction.
  • Final characterization suite: 15/15.
  • Focused caption/profile/semantic/winner suite: 159/159.
  • Existing deterministic caption ROI/pixel-preservation assertions pass.
  • No full decoded-video comparison was added, so this PR does not claim independently proven pixel-identical complete videos.

Full regression results

  • npm run lint: pass
  • npm run build: pass
  • npm test: 1,683 pass / 7 skip / 0 fail
  • Python discovery: 539/539 pass (baseline 524/524)
  • Isolated Python modules: 54/54 pass (baseline 53/53)
  • HookGate quality: 96.2981, unchanged
  • Hard guardrails: pass
  • Fixture fingerprint: 37ef626b9901ad2eeb1056d47954d88cdf2ede6430cc80e449bd5f9c7a91f9c9, unchanged
  • Metric fingerprint: d62ce934e038d9026263ce2be7efa5f0c6e3ffac8a583d7b23b609540a5f4fe9, unchanged

Limitations

The full browser suite needs normal host browser permissions; sandboxed Chrome exited with EPERM, while the same locked suite passed with browser permissions. npm audit reports five moderate transitive findings and no high/critical issue; dependency upgrades are outside this refactor.

Next slice

Characterize and isolate caption cue grouping/timing planning only, without combining font resolution, drawing, or render behavior changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant