feat(planner): prompt caching + multi-theme awareness + per-scene theme override

[cuio]

Summary

Three changes that together let the AI use multiple themes per video without blowing up API costs.

1. Prompt caching — ~80% input-cost reduction on iterative work

Anthropic client extended to accept system as a SystemSegment[] with per-segment cache_control. The planner now builds 4 cache breakpoints, ordered most-stable to most-volatile:

Block	Content	Stability
1	RETENTION_PLAYBOOK (~3-5k tokens)	every video reuses
2	Active theme DESIGN_SYSTEM.md + preferences (~1-2k)	same theme reuses
3	DESIGN.md + DESIGN-ART.md + RESEARCH.md (~1-2k)	same project reuses
4	Fidelity rule (per call)	never cached

Schema-correction retry and no-scenes retry now append to the user message instead of the system, so the cached prefix stays valid and retries hit cache too.

Net effect: re-plans / retries / hook-critic calls inside the 5-minute cache TTL pay ~10% of input cost on the cached prefix. Iterative work goes from ~$0.15/video to ~$0.03/video after the first plan.

2. Multi-theme awareness — mix concepts without bloat

Studio API passes a CONDENSED list of every other installed theme to the planner: id + 1-line description + their preference arrays only (~50 tokens per theme). Stays inside the active-theme cache breakpoint so adding a new theme doesn't invalidate the cache for projects that don't use it.

The planner gets a new "Other themes available for cross-pollination" section in its system prompt explaining the two ways to borrow concepts.

3. Per-scene theme override

Planner tool schema gains scene.themeOverride (validated against availableThemes + the active theme). Materializer threads it through as scene.props.theme. The assembler's render loop honours it: when set, that one scene gets the named theme's tokens (palette + fonts) for its template render + atmosphere injection. Other scenes keep the active theme.

Use case: a Dreamspace hook in a HackerNoon-themed video. One prop, no global config change. The planner can also borrow individual atmospheres / transitions from a peer theme without switching the whole palette.

Documentation

docs/design-systems/README.md gets three new sections:

• Mixing themes per scene — the two mechanisms above with examples.
• Themes from Claude design (Remotion + Babel) — JSX is reference, DESIGN_SYSTEM.md is the spec the planner reads, HTML+GSAP is production. Per-theme template overrides are coming in a follow-up PR.
• Cost notes — explains the 4 cache breakpoints and the ~80% iterative-work savings.

Test plan

• GET /api/themes?project=my-first-video returns 3 themes; payload size unchanged
• Studio's SSR cache-watcher (PR fix(studio): use file watcher for SSR module cache invalidation #11) picked up source edits without restart
• Lint, format, typecheck pass across both packages
• End-to-end live API verification — requires an Anthropic key. Re-plan with the studio's "Re-plan with AI" button; check the response's usage field for cache_creation_input_tokens (first call) and cache_read_input_tokens (subsequent calls). Hook critic should hit cache too.

What's deferred

Theme-shipped templates (per-theme template overrides via <theme>/templates/<id>.html with {{prop}} substitution + GSAP) is a meaningful new subsystem — design + implementation + tests warrant a focused PR. For now, themes restyle existing templates via tokens + preferences. The planner can already mix per-scene themes for a different aesthetic; templates-per-theme adds the ability to ship pixel-exact custom layouts (T2 prompt-to-app, T5 manifesto, etc.).

How the AI uses this

When the user re-plans with the sample script:

1. Planner sees the active theme's full DESIGN_SYSTEM.md + preferences (block 2).
2. Planner sees the condensed peer theme list (in block 2).
3. Planner can set scene.themeOverride on any scene to switch palette + fonts for that scene.
4. Planner can pull atmospheres / transitions from peer themes' preferences while keeping the active theme's tokens (lighter intervention).
5. The schema-correction retry uses the same cached prefix → minimal extra cost.
6. The hook critic reuses the playbook + theme cache → minimal cost.