name: theatrejs-optimizer description: Audit and optimize Theatre.js usage (@theatre/core + @theatre/studio + @theatre/r3f) — Studio left un-gated in production bundles (the classic mistake; studio bloat + exposed edit UI), getProject without exported project state JSON, sequence.play called before sheet.project.ready, SheetProvider/Sheet wiring in R3F, editable-object theatreKey drift between Studio and code, infinite autoplay sequences (iterationCount: Infinity) without a reduced-motion gate, and project JSON size/linting. Report with evidence and a plan approved before edits. Use when the user mentions Theatre.js, @theatre/core, @theatre/studio, @theatre/r3f, sequence, sheet, or theatreKey -- even if they don't say "optimize".

Theatre.js (@theatre/core) Optimizer

Audit how a codebase uses Theatre.js, report what ships broken or wasteful, agree a plan, then fix. Theatre.js has a sharp dev/prod split: Studio (@theatre/studio) is an authoring GUI that must be dev-only (bundlers tree-shake it out of if (import.meta.env.DEV) / NODE_ENV === 'development' gates), production plays back from an exported project-state JSON passed to getProject, and playback code must await sheet.project.ready. Most audits find Studio in prod bundles, missing or stale state JSON, and autoplaying sequences without reduced-motion gates. Report first, plan approved, then edit.

Workflow

1. Scope (quick)

• Project root (package.json — @theatre/core, @theatre/studio, @theatre/r3f versions; note R3F/three presence since @theatre/r3f extends R3F).
• Run python <skill-dir>/scripts/audit.py <project-root> [--json] — inventories studio gating, project-state wiring (getProject + { state }), project.ready ordering, SheetProvider setup, theatreKey usage, sequence.play call sites, autoplay loops, reduced-motion coverage.

2. Audit

Read what the script flagged. Load references as fit:

Runtime checks you do by hand: run a prod build — does the Studio UI appear (it must not)? Does the scene play from the exported JSON (not just localStorage)? Reduce-motion emulation on autoplay.

Mark findings Confirmed or Suspected.

3. Report

Fill in assets/report-template.md, save as THEATREJS_REPORT.md in the project root. Group: studio gating, project state, sequence wiring, a11y.

4. Plan — stop for approval

1. Quick wins — gate studio.initialize()/studio.extend() behind env checks; await sheet.project.ready before sequence.play; re-export a current state JSON if the stored one lags the scene; add a reduced-motion guard before autoplay (iterationCount: Infinity).
2. Structural — split Studio init into a dev entry module; thread project state through getProject(name, { state }) consistently; consolidate sheet names between Studio and code.
3. Optional — trimming project JSON (unused objects props/columns dead keys), moving state fetch to runtime loading when JSON is large. Per step: files, expected effect, verification, rollback. Let the user drop or reorder.

5. Fix

Approved items only. Theatre.js changes are visible: verify each group by playing the scene in a dev build (Studio still available), then in a prod build (Studio absent, playback from JSON states).

6. Verify and wrap up

• Bundle deltas (Studio out of the prod bundle is usually the largest single win).
• Prod-build playback walkthrough; state JSON re-export round-trip; reduced-motion emulation.
• Deferred items + next step.

Principles

• Studio never ships. It is the authoring GUI; prod builds play back state JSON and stay clean of Studio code — relying on tree-shaking via an env gate, verified by a prod build.
• State JSON is the source of truth. Studio edits persist to localStorage; a prod site must receive an exported project state or nothing plays.
• ready before play. Projects load asynchronously; sequencing without awaiting sheet.project.ready races.
• One project, stable sheets. getProject(name) is a registry — mismatched names/sheets between Studio sessions and code silently no-op.
• Autoplay is an a11y decision. iterationCount: Infinity loops forever; gate behind prefers-reduced-motion.
• Docs over memory. Theatre.js moves version to version; fetch current docs (theatrejs.com) before quoting APIs in a plan.