Audit and triage of TODO/FIXME markers in hotspot source files

Nobody has claimed this yet.

## Background

As part of an academic project on software maintenance and evolution (repository mining course assignment), we ran a static audit of TODO/FIXME/XXX/HACK markers across the source tree. The audit focused on eight hotspot files identified by a churn × bug-fix-touches analysis over the 2024-01 to 2026-05 window. Two larger hotspot files (`mobject.py` and `vectorized_mobject.py`) were excluded because they are reported to be under active refactor.

The audit found **26 real markers** across the eight files. After a manual triage, we believe **18 of them** describe work that would benefit from being represented in the issue tracker.

This issue proposes filing those 18 issues, in batches grouped by source file, and asks for maintainer feedback on scope and process before we proceed.

## Scope of the audit

| File | Markers analysed | Issues proposed |
|------|-----------------:|----------------:|
| `manim/mobject/opengl/opengl_mobject.py` | 10 | 7 |
| `manim/scene/scene.py` | 8 | 5 |
| `manim/mobject/graphing/coordinate_systems.py` | 3 | 3 |
| `manim/mobject/geometry/arc.py` | 3 | 2 |
| `manim/_config/utils.py` | 2 | 1 |
| `manim/utils/color/core.py` | 1 | 1 |
| **Total** | **26** | **18 (after grouping)** |

The difference between markers and proposed issues is accounted for by:

- **2 markers grouped with another marker** in the same file (e.g. two `# TODO, get rid of this` markers on the same parameter, two markers describing the two ends of a single refactor).
- **4 markers classified as design questions** with no clear action attached, skipped to avoid adding low-signal work for maintainers.
- **2 markers already tracked** elsewhere (one references PR #620, one references issue #4176).

## Proposed issues, by file

Each row below corresponds to one issue we would open if this audit is approved. The category column indicates the kind of work, which we expect to map roughly to the labels `issue:bug`, `maintenance`, or `pr:deprecation`.

### `opengl_mobject.py`

| Line | Category | Proposed title |
|-----:|----------|----------------|
| 156, 185 | refactor | opengl: deprecate unused `dim` parameter on `OpenGLMobject` |
| 675 | refactor | opengl: align `apply_points_function` naming with `Mobject.apply_points_function_about_point` |
| 1447 | refactor | opengl: justify or eliminate shallow path in `OpenGLMobject.copy()` |
| 1460 | latent bug | opengl: verify whether uniforms can contain numpy arrays in `OpenGLMobject.copy()` |
| 2308 | bug | opengl: `add_background_rectangle` displays on top when target mobject has its own points |
| 2876 | latent bug | opengl: verify `replace_shader_code` propagates through `OpenGLVMobject` family |
| 2904 | enhancement | opengl: add point-data variant of `set_color_by_xyz_func` |

### `scene.py`

| Line | Category | Proposed title |
|-----:|----------|----------------|
| 220, 760 | refactor | scene: deprecate `foreground_mobjects` in favour of `z_index` ordering |
| 264 | bug | scene: `render()` can crash on rerun when using `CairoRenderer` |
| 1182 | refactor | scene: verify subcaption kwargs propagate through `SceneInteractRerun` queue |
| 1302 | refactor | scene: `compile_animation_data` should return `None`, not `Self` |
| 1381 | bug | scene: `play_internal()` can crash on `OpenGLRenderer` due to missing `static_image` attribute |

### Other files

| File | Line | Category | Proposed title |
|------|-----:|----------|----------------|
| `_config/utils.py` | 1193 | refactor | config: return `ManimColor` instance from `background_color` property |
| `utils/color/core.py` | 964 | refactor | color: implement `ManimColor.gradient()` instead of raising `NotImplementedError` |
| `geometry/arc.py` | 345 | refactor | geometry: unify `generate_points` and `init_points` in `Arc` |
| `geometry/arc.py` | 701 | refactor | geometry: introduce `Ellipse` class to support single-dimension stretching |
| `geometry/arc.py` | 704 | latent bug | geometry: investigate incorrect behaviour of `Circle.surround()` on `Line` objects |
| `graphing/coordinate_systems.py` | 159 | refactor | graphing: align `coords_to_point` return type in base class with subclass behaviour |
| `graphing/coordinate_systems.py` | 2874 | refactor | graphing: consolidate `x_lines` and `y_lines` into `background_lines` on `NumberPlane` |
| `graphing/coordinate_systems.py` | 3480 | refactor | graphing: align `get_coordinate_labels` with `add_coordinates` API |

## Cross-file patterns we noticed

Three observations emerged from the triage that may be more interesting than any individual marker:

1. **Cairo / OpenGL interface drift.** Three independent markers in different files (`scene.py:264`, `scene.py:1381`, `opengl_mobject.py:675`) describe the same underlying problem: methods, attributes, and names diverge between the Cairo `Mobject` hierarchy and the OpenGL `OpenGLMobject` hierarchy. Each is filed as its own issue, but the maintainer team might want to consider tracking the broader alignment as a separate theme.
2. **TODOs sitting above `# type: ignore` comments.** Four markers (`scene.py:264`, `scene.py:1381`, `opengl_mobject.py:2308`, `opengl_mobject.py:2908`) are paired with `# type: ignore` annotations on the next line. These are effectively author-confessed bugs: the original developer knew the type checker had a legitimate complaint and silenced it. We treated these as confirmed bugs rather than latent ones.
3. **Existing precedent for issue-linked TODOs.** One marker (`opengl_mobject.py:2908`) already follows a `# TODO: ... See ` pattern, referencing issue #4176. The practice exists in the project but is not uniform or documented. A small follow-up could be to standardise the comment format as `# TODO(#NNNN): ...` and document it in the contributing guide.

## Methodological note

The audit used `grep -nHE "TODO|FIXME|XXX|HACK"` on the eight files. This captures literal markers but misses comments that are functionally TODOs but use natural language (e.g. `# Any problems with this?`, `# Is this safe?`). At least one such case was discovered incidentally during the triage (`scene.py:1305`). A complete audit would need a second pass to catch these.

## What we are asking for

Before we file the 18 individual issues, we would like maintainer feedback on:

1. **Scope.** Are any of the files above ones we should exclude because they are scheduled for an imminent refactor?
2. **Process.** Is opening 18 issues over the next week (in small batches, one source file at a time) the right cadence, or would you prefer a different rhythm?
3. **Format.** We propose to follow up each issue with a small PR that updates the corresponding source comment to `# TODO(#NNNN): `. Is that the convention you would like, or would you prefer a different format (or no source-side update at all)?
4. **Themed work.** Would you like the Cairo/OpenGL interface drift pattern tracked as a separate themed issue, with the individual bugs linked as children, or left as independent issues?

We are not asking anyone on the maintainer team to do work. We will pause and wait for any of these questions to be answered before proceeding.

## Context

This work is part of an academic project on software maintenance and evolution. Triage methodology, raw spreadsheet, and per-marker analyses are available on request. The audit is a one-off study; no automated crawling of the issue tracker is being performed.

Review the audit table and the cited locations in manim/mobject/opengl/opengl_mobject.py, manim/scene/scene.py, and the listed geometry, graphing, config, and color files. Start by checking whether the proposed markers are still present and whether existing refactors or issues cover them; this issue is done when maintainers decide the scope, filing cadence, comment format, and treatment of the Cairo/OpenGL theme.

Written by the indexing model from the issue text.