Refactor Recipe: rename symbol across repo in R (Astro static site)

You are a senior staff engineer with extensive technical knowledge in refactoring. You write clear, precise, and implementation-ready content.

Apply the **rename symbol across repo** refactor in a R Astro static site, safely, with the test suite staying green at every step.

**Recipe:** rename symbol across repo
**Language:** R
**Project:** Astro static site
**Test framework:** Mocha + Chai
**Convention:** public functions require JSDoc with @example

## When to reach for this recipe
Describe in 3-5 lines the code smell that signals "rename symbol across repo" is the right tool. Include:
- The shape of the problem (what the code looks like today)
- Symptoms in practice (hard to test, duplicated, hard to read, slow)
- When NOT to apply this (premature, across a module boundary, without tests)

## Prerequisites
- The area under refactor has at least characterization tests passing
- You can run the full suite locally in < 60s
- You are on a clean branch with nothing uncommitted
- Respect public functions require JSDoc with @example

## The safe procedure
A sequence of micro-steps. After EACH step, run the test suite. If it goes red, revert that step and rethink.

1. **Freeze the interface.** Identify the public signature that external callers depend on. Do not change it during this refactor. If you need to change it, do that as a separate follow-up refactor.
2. **Add characterization tests.** If coverage on the target is below ~80%, add tests that pin down current behavior (including bugs-as-spec). Commit: `test: characterize <target> before refactor`.
3. **Introduce the new shape side-by-side.** Create the new function/class/module next to the old one. No callers yet. Commit: `refactor: introduce <new shape>`.
4. **Migrate one caller.** Swap a single caller from old to new. Run tests. Commit: `refactor: migrate <caller> to <new shape>`.
5. **Migrate remaining callers** one at a time, committing per caller. Tests green at every commit.
6. **Delete the old shape** once no callers remain. Commit: `refactor: remove old <shape>`.
7. **Polish.** Rename symbols, align with conventions, remove dead params. Commit: `refactor: polish post-migration`.

## Micro-moves specific to "rename symbol across repo"
Enumerate 8-12 precise sub-moves that this specific recipe requires in R. For each:
- The exact before -> after shape (describe, do not paste long code)
- The IDE or AI-assistant command to perform it safely (e.g. "LSP rename", "Extract Function from selection")
- The test signal that confirms the move didn't break anything
- The common failure mode and its fix

## Anti-patterns during this refactor
- Refactor + feature change in the same PR (split them)
- Silent behavior changes (those are bugs, not refactors)
- Bulk search-and-replace without tests (breaks imports, shadows, escaped chars)
- Renaming through reflection strings (e.g. `getAttr(obj, "oldName")`) without searching them

## Rollback
- Because every step is a green commit, `git revert <sha>` unwinds cleanly
- Keep the branch under 20 commits; otherwise split the refactor

## Done means
- All callers on the new shape
- Old shape deleted
- No change in observable behavior (same public tests pass, no new tests needed beyond characterization)
- Coverage equal or better than before
- public functions require JSDoc with @example satisfied

Present as numbered steps. Each step should have: a clear action title, detailed instructions, expected outcome, and common pitfalls to avoid.