scenescript 0.2.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (239) hide show
  1. {scenescript-0.2.0 → scenescript-0.4.0}/PKG-INFO +251 -21
  2. {scenescript-0.2.0 → scenescript-0.4.0}/README.md +248 -20
  3. scenescript-0.4.0/docs/adr/0008-declared-def-params-with-defaults.md +34 -0
  4. scenescript-0.4.0/docs/fake-ide-feature-notes.md +42 -0
  5. scenescript-0.4.0/examples/fake-ide/README.md +37 -0
  6. scenescript-0.4.0/examples/fake-ide/ide.defs.json +59 -0
  7. scenescript-0.4.0/examples/fake-ide/tutorial.json +176 -0
  8. scenescript-0.4.0/examples/fake-ide/tutorial.mp4 +0 -0
  9. {scenescript-0.2.0 → scenescript-0.4.0}/pyproject.toml +5 -1
  10. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/__init__.py +1 -1
  11. scenescript-0.4.0/src/scenescript/animation.py +66 -0
  12. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/cli.py +47 -1
  13. scenescript-0.4.0/src/scenescript/codeblocks.py +238 -0
  14. scenescript-0.4.0/src/scenescript/codethemes.py +91 -0
  15. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/easing.py +6 -0
  16. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/geometry.py +16 -0
  17. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/mcp_server.py +72 -7
  18. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/renderer.py +26 -0
  19. scenescript-0.4.0/src/scenescript/scenes.py +210 -0
  20. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/spec.py +387 -32
  21. scenescript-0.4.0/src/scenescript/sprites.py +182 -0
  22. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/timeline.py +12 -0
  23. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/validation.py +45 -16
  24. {scenescript-0.2.0 → scenescript-0.4.0}/tests/conftest.py +15 -0
  25. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_animation.py +23 -0
  26. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_cli.py +70 -2
  27. scenescript-0.4.0/tests/test_code.py +182 -0
  28. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_easing.py +6 -0
  29. scenescript-0.4.0/tests/test_groups.py +120 -0
  30. scenescript-0.4.0/tests/test_includes.py +179 -0
  31. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_mcp_server.py +74 -2
  32. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_render.py +32 -1
  33. scenescript-0.4.0/tests/test_spec_features.py +174 -0
  34. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_sprites.py +46 -6
  35. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_timeline.py +27 -0
  36. {scenescript-0.2.0 → scenescript-0.4.0}/uv.lock +8 -2
  37. scenescript-0.2.0/src/scenescript/animation.py +0 -43
  38. scenescript-0.2.0/src/scenescript/scenes.py +0 -142
  39. scenescript-0.2.0/src/scenescript/sprites.py +0 -109
  40. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/agents/copy-writer.md +0 -0
  41. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/agents/product-owner.md +0 -0
  42. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/agents/qa-tester.md +0 -0
  43. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/agents/software-architect.md +0 -0
  44. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/agents/software-engineer.md +0 -0
  45. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/agents/ui-ux-specialist.md +0 -0
  46. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/README.md +0 -0
  47. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/accessibility-standard.md +0 -0
  48. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/adr-index.md +0 -0
  49. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/ci-pipeline.md +0 -0
  50. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/competitor-positioning.md +0 -0
  51. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/design-tokens.md +0 -0
  52. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/device-matrix.md +0 -0
  53. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/domain-glossary.md +0 -0
  54. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/environment-map.md +0 -0
  55. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/grounding-rules.md +0 -0
  56. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/known-debt.md +0 -0
  57. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/known-issues.md +0 -0
  58. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/local-dev-setup.md +0 -0
  59. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/nfr-targets.md +0 -0
  60. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/observability-map.md +0 -0
  61. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/personas.md +0 -0
  62. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/research-repository.md +0 -0
  63. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/severity-ladder.md +0 -0
  64. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/system-map.md +0 -0
  65. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/tech-radar.md +0 -0
  66. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/test-data-catalog.md +0 -0
  67. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/ui-string-catalog.md +0 -0
  68. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/context/voice-guide.md +0 -0
  69. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/analyzing-trade-offs/SKILL.md +0 -0
  70. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/analyzing-trade-offs/references/worked-example.md +0 -0
  71. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/applying-design-system-conventions/SKILL.md +0 -0
  72. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/applying-design-system-conventions/references/drift-catalogue.md +0 -0
  73. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/applying-design-system-conventions/references/worked-resolution.md +0 -0
  74. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/auditing-accessibility/SKILL.md +0 -0
  75. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/auditing-accessibility/references/audit-checklist.md +0 -0
  76. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/auditing-accessibility/references/finding-template.md +0 -0
  77. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/auditing-accessibility/references/state-audit.md +0 -0
  78. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/automating-tests/SKILL.md +0 -0
  79. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/automating-tests/references/adversarial-cases.md +0 -0
  80. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/automating-tests/references/flake-cures.md +0 -0
  81. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/automating-tests/references/test-note.md +0 -0
  82. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/critiquing-with-heuristics/SKILL.md +0 -0
  83. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/critiquing-with-heuristics/references/heuristics.md +0 -0
  84. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/critiquing-with-heuristics/references/worked-example.md +0 -0
  85. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/debugging-and-incidents/SKILL.md +0 -0
  86. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/debugging-and-incidents/references/records.md +0 -0
  87. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/defining-voice-and-style/SKILL.md +0 -0
  88. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/defining-voice-and-style/references/worked-guide.md +0 -0
  89. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/designing-tests-from-acceptance-criteria/SKILL.md +0 -0
  90. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/designing-tests-from-acceptance-criteria/references/adversarial-catalogue.md +0 -0
  91. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/designing-tests-from-acceptance-criteria/references/worked-example.md +0 -0
  92. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/documenting-flows-and-ia/SKILL.md +0 -0
  93. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/documenting-flows-and-ia/references/branch-checklist.md +0 -0
  94. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/documenting-flows-and-ia/references/worked-flow.md +0 -0
  95. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/documenting-systems/SKILL.md +0 -0
  96. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/documenting-systems/references/evidence-ladder.md +0 -0
  97. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/documenting-systems/references/worked-diagram.md +0 -0
  98. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/drafting-from-a-brief/SKILL.md +0 -0
  99. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/drafting-from-a-brief/references/worked-brief.md +0 -0
  100. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/editing-copy/SKILL.md +0 -0
  101. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/editing-copy/references/deliverables.md +0 -0
  102. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/enforcing-terminology/SKILL.md +0 -0
  103. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/enforcing-terminology/references/deliverable.md +0 -0
  104. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/enforcing-terminology/references/sweep-recipe.md +0 -0
  105. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/enumerating-ui-states/SKILL.md +0 -0
  106. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/enumerating-ui-states/references/inventory-template.md +0 -0
  107. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/enumerating-ui-states/references/state-axes.md +0 -0
  108. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/managing-test-data/SKILL.md +0 -0
  109. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/managing-test-data/references/hostile-fixtures.md +0 -0
  110. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/managing-test-data/references/provisioning-routes.md +0 -0
  111. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/planning-implementation/SKILL.md +0 -0
  112. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/planning-implementation/references/worked-plan.md +0 -0
  113. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/planning-migrations/SKILL.md +0 -0
  114. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/planning-migrations/references/expand-contract.md +0 -0
  115. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/planning-migrations/references/worked-plan.md +0 -0
  116. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/planning-usability-tests/SKILL.md +0 -0
  117. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/planning-usability-tests/references/plan-template.md +0 -0
  118. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/planning-usability-tests/references/task-wording.md +0 -0
  119. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/prioritizing-work/SKILL.md +0 -0
  120. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/prioritizing-work/references/cost-of-delay.md +0 -0
  121. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/prioritizing-work/references/frameworks.md +0 -0
  122. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/prioritizing-work/references/worked-example.md +0 -0
  123. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/probing-non-functional-behavior/SKILL.md +0 -0
  124. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/probing-non-functional-behavior/references/adversarial-probes.md +0 -0
  125. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/probing-non-functional-behavior/references/probe-types.md +0 -0
  126. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/probing-non-functional-behavior/references/worked-probe.md +0 -0
  127. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/refactoring/SKILL.md +0 -0
  128. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/refactoring/references/characterization-tests.md +0 -0
  129. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/refactoring/references/mechanical-moves.md +0 -0
  130. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/refining-the-backlog/SKILL.md +0 -0
  131. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/refining-the-backlog/references/split-axes.md +0 -0
  132. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/removing-ai-tells/SKILL.md +0 -0
  133. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/removing-ai-tells/references/catalogue.md +0 -0
  134. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reporting-defects/SKILL.md +0 -0
  135. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reporting-defects/references/report-template.md +0 -0
  136. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reporting-defects/references/worked-examples.md +0 -0
  137. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-code/SKILL.md +0 -0
  138. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-code/references/correctness-probes.md +0 -0
  139. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-code/references/worked-review.md +0 -0
  140. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-design-against-nfrs/SKILL.md +0 -0
  141. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-design-against-nfrs/references/quality-checklist.md +0 -0
  142. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-design-against-nfrs/references/worked-review.md +0 -0
  143. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-for-acceptance/SKILL.md +0 -0
  144. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-for-acceptance/references/acceptance-record.md +0 -0
  145. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-tests/SKILL.md +0 -0
  146. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-tests/references/mutation-catalogue.md +0 -0
  147. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-tests/references/tests-that-cannot-fail.md +0 -0
  148. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/reviewing-tests/references/worked-review.md +0 -0
  149. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/running-design-qa/SKILL.md +0 -0
  150. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/running-design-qa/references/check-matrix.md +0 -0
  151. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/running-design-qa/references/output-template.md +0 -0
  152. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/running-spikes/SKILL.md +0 -0
  153. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/running-spikes/references/spike-note.md +0 -0
  154. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/scoping-regression-tests/SKILL.md +0 -0
  155. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/scoping-regression-tests/references/reach-checklist.md +0 -0
  156. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/scoping-regression-tests/references/scope-note.md +0 -0
  157. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/specifying-interactions/SKILL.md +0 -0
  158. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/specifying-interactions/references/adversarial-read.md +0 -0
  159. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/specifying-interactions/references/spec-template.md +0 -0
  160. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/synthesizing-research/SKILL.md +0 -0
  161. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/synthesizing-research/references/no-research-yet.md +0 -0
  162. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/synthesizing-research/references/worked-synthesis.md +0 -0
  163. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/tdd-workflow/SKILL.md +0 -0
  164. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/tdd-workflow/references/reading-red.md +0 -0
  165. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/tdd-workflow/references/worked-cycle.md +0 -0
  166. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/SKILL.md +0 -0
  167. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/references/adversarial-conditions.md +0 -0
  168. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/references/finding-template.md +0 -0
  169. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/references/keyboard-pass.md +0 -0
  170. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/references/screen-reader-pass.md +0 -0
  171. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/testing-apis-and-contracts/SKILL.md +0 -0
  172. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/testing-apis-and-contracts/references/adversarial-catalogue.md +0 -0
  173. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/testing-apis-and-contracts/references/compatibility-matrix.md +0 -0
  174. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/triaging-bugs/SKILL.md +0 -0
  175. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/triaging-bugs/references/severity-and-priority.md +0 -0
  176. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/triaging-requests/SKILL.md +0 -0
  177. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/triaging-requests/references/triage-note.md +0 -0
  178. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/upgrading-dependencies/SKILL.md +0 -0
  179. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/upgrading-dependencies/references/silent-changes.md +0 -0
  180. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/upgrading-dependencies/references/upgrade-note.md +0 -0
  181. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/verifying-done/SKILL.md +0 -0
  182. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/verifying-done/references/completion-report.md +0 -0
  183. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/verifying-done/references/rationalizations.md +0 -0
  184. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/verifying-done/references/scaling-the-check.md +0 -0
  185. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-adrs/SKILL.md +0 -0
  186. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-adrs/references/adr-template.md +0 -0
  187. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-adrs/references/worked-adr.md +0 -0
  188. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-documentation/SKILL.md +0 -0
  189. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-documentation/references/page-shapes.md +0 -0
  190. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-documentation/references/worked-example.md +0 -0
  191. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-exploratory-charters/SKILL.md +0 -0
  192. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-exploratory-charters/references/lens-catalogue.md +0 -0
  193. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-exploratory-charters/references/session-record.md +0 -0
  194. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-marketing-copy/SKILL.md +0 -0
  195. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-marketing-copy/references/awareness-and-formats.md +0 -0
  196. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-marketing-copy/references/worked-examples.md +0 -0
  197. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-microcopy-in-context/SKILL.md +0 -0
  198. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-microcopy-in-context/references/content-set.md +0 -0
  199. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-microcopy-in-context/references/worked-review.md +0 -0
  200. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-plain-language/SKILL.md +0 -0
  201. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-plain-language/references/text-accessibility-checks.md +0 -0
  202. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-plain-language/references/worked-example.md +0 -0
  203. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-seo-metadata/SKILL.md +0 -0
  204. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-seo-metadata/references/surfaces.md +0 -0
  205. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-ui-copy/SKILL.md +0 -0
  206. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-ui-copy/references/constraints-and-variables.md +0 -0
  207. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-ui-copy/references/string-types.md +0 -0
  208. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-user-stories/SKILL.md +0 -0
  209. {scenescript-0.2.0 → scenescript-0.4.0}/.claude/skills/writing-user-stories/references/worked-example.md +0 -0
  210. {scenescript-0.2.0 → scenescript-0.4.0}/.gitignore +0 -0
  211. {scenescript-0.2.0 → scenescript-0.4.0}/LICENSE +0 -0
  212. {scenescript-0.2.0 → scenescript-0.4.0}/docs/adr/0001-pillow-numpy-composition-ffmpeg-at-boundaries.md +0 -0
  213. {scenescript-0.2.0 → scenescript-0.4.0}/docs/adr/0002-transition-timeline-model.md +0 -0
  214. {scenescript-0.2.0 → scenescript-0.4.0}/docs/adr/0003-single-ffmpeg-process-for-encode-and-audio.md +0 -0
  215. {scenescript-0.2.0 → scenescript-0.4.0}/docs/adr/0004-hand-written-validation.md +0 -0
  216. {scenescript-0.2.0 → scenescript-0.4.0}/docs/adr/0005-pillow-embedded-default-font.md +0 -0
  217. {scenescript-0.2.0 → scenescript-0.4.0}/docs/adr/0006-mcp-server-as-optional-extra.md +0 -0
  218. {scenescript-0.2.0 → scenescript-0.4.0}/docs/adr/0007-reusable-elements-expand-at-parse-time.md +0 -0
  219. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/audio.py +0 -0
  220. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/backgrounds.py +0 -0
  221. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/colors.py +0 -0
  222. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/encoder.py +0 -0
  223. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/errors.py +0 -0
  224. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/probe.py +0 -0
  225. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/progress.py +0 -0
  226. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/transitions.py +0 -0
  227. {scenescript-0.2.0 → scenescript-0.4.0}/src/scenescript/videoreader.py +0 -0
  228. {scenescript-0.2.0 → scenescript-0.4.0}/tests/__init__.py +0 -0
  229. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_audio.py +0 -0
  230. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_backgrounds.py +0 -0
  231. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_colors.py +0 -0
  232. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_defs.py +0 -0
  233. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_geometry.py +0 -0
  234. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_probe.py +0 -0
  235. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_scenes.py +0 -0
  236. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_spec.py +0 -0
  237. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_transitions.py +0 -0
  238. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_validation.py +0 -0
  239. {scenescript-0.2.0 → scenescript-0.4.0}/tests/test_videoreader.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scenescript
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: Render complete videos from declarative JSON files
5
5
  Project-URL: Homepage, https://github.com/CtrlAltDeplete/scenescript
6
6
  Author-email: CtrlAltDeplete <gavyn@ctrlaltdeplete.com>
@@ -14,6 +14,8 @@ Classifier: Programming Language :: Python :: 3.13
14
14
  Requires-Python: >=3.11
15
15
  Requires-Dist: numpy>=1.26
16
16
  Requires-Dist: pillow>=10.1
17
+ Provides-Extra: code
18
+ Requires-Dist: pygments>=2.15; extra == 'code'
17
19
  Provides-Extra: mcp
18
20
  Requires-Dist: mcp>=2; extra == 'mcp'
19
21
  Description-Content-Type: text/markdown
@@ -55,16 +57,24 @@ For the [MCP server](#mcp-server), include the extra:
55
57
  pip install "scenescript[mcp]"
56
58
  ```
57
59
 
60
+ For syntax-highlighted [`code` elements](#code), include the `code` extra
61
+ (it pulls in [pygments](https://pygments.org)):
62
+
63
+ ```bash
64
+ pip install "scenescript[code]"
65
+ ```
66
+
58
67
  ### Upgrading
59
68
 
60
69
  ```bash
61
70
  pip install --upgrade scenescript
62
71
  ```
63
72
 
64
- If you use the MCP server, include the extra so its dependencies are upgraded too:
73
+ If you use extras (the MCP server, `code` highlighting), include them so
74
+ their dependencies are upgraded too:
65
75
 
66
76
  ```bash
67
- pip install --upgrade "scenescript[mcp]"
77
+ pip install --upgrade "scenescript[mcp,code]"
68
78
  ```
69
79
 
70
80
  ### Installing from source
@@ -74,7 +84,7 @@ To work on SceneScript itself, install editable from a clone — the executables
74
84
  ```bash
75
85
  git clone https://github.com/CtrlAltDeplete/scenescript
76
86
  cd scenescript
77
- pip install -e ".[mcp]"
87
+ pip install -e ".[mcp,code]"
78
88
  ```
79
89
 
80
90
  ## Quick Start
@@ -124,12 +134,13 @@ scenescript render video.json -o output.mp4
124
134
 
125
135
  ### Top Level
126
136
 
127
- | Key | Type | Required | Description |
128
- |----------|--------|----------|-------------|
129
- | `output` | object | no | Output settings. Defaults: `1920×1080`, `30` fps, `mp4`. |
130
- | `scenes` | array | yes | Ordered list of scenes, played back to back. |
131
- | `defs` | object | no | Named, reusable element groups (see [Reusable Elements](#reusable-elements)). |
132
- | `audio` | array | no | Global audio tracks spanning the whole video. |
137
+ | Key | Type | Required | Description |
138
+ |-----------|--------|----------|-------------|
139
+ | `output` | object | no | Output settings. Defaults: `1920×1080`, `30` fps, `mp4`. |
140
+ | `scenes` | array | yes | Ordered list of scenes, played back to back. |
141
+ | `defs` | object | no | Named, reusable element groups (see [Reusable Elements](#reusable-elements)). |
142
+ | `include` | array | no | Paths of JSON files whose `defs` are merged in (see [Shared def libraries](#shared-def-libraries)). |
143
+ | `audio` | array | no | Global audio tracks spanning the whole video. |
133
144
 
134
145
  #### `output`
135
146
 
@@ -190,13 +201,50 @@ All element types share these keys:
190
201
 
191
202
  | Key | Type | Default | Description |
192
203
  |--------------|---------------|----------------|-------------|
193
- | `type` | string | — | `text`, `video`, `image`, `shape`, or `ref` (see [Reusable Elements](#reusable-elements)). |
204
+ | `type` | string | — | `text`, `video`, `image`, `shape`, `code`, `group`, or `ref` (see [Reusable Elements](#reusable-elements)). |
194
205
  | `start` | number | `0` | Seconds into the scene when the element appears. |
195
206
  | `end` | number | scene duration | Seconds into the scene when the element disappears. |
196
- | `position` | string/object | `"center"` | Named anchor (`center`, `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`) or explicit `{ "x": 100, "y": 200 }` pixel coordinates of the element's center. |
207
+ | `position` | string/object | `"center"` | Named frame position (`center`, `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`) or explicit `{ "x": 100, "y": 200 }` pixel coordinates. |
208
+ | `anchor` | string | `"center"` (`"top-left"` for `code`) | Which point of the element an explicit `{x, y}` position places (see [Anchors](#anchors)). Not on `video` elements. |
197
209
  | `opacity` | number | `1.0` | `0.0`–`1.0`. |
210
+ | `shadow` | object | none | Drop shadow (see [Shadows](#shadows)). Not on `video` elements. |
198
211
  | `animations` | array | `[]` | Keyframed property animations (see [Animations](#animations)). |
199
212
 
213
+ Pixel dimensions (`width`, `height`, `size`, `radius`, `max_width`) accept any
214
+ number; fractional values are rounded, so computed layouts can pass floats.
215
+
216
+ #### Anchors
217
+
218
+ By default an explicit `{x, y}` position locates the element's **center**.
219
+ `anchor` changes which point it locates instead: `top-left`, `top`,
220
+ `top-right`, `left`, `right`, `bottom-left`, `bottom`, `bottom-right`, or
221
+ `center`. Named string positions (`"top-left"` etc.) already place the whole
222
+ box against the frame and ignore `anchor`.
223
+
224
+ For `text` elements, anchors are **font-metric based** so that different
225
+ strings line up consistently: `left`/`right` anchor the pen origin and
226
+ advance width (not the inked pixels), `top` anchors the ascender line, and
227
+ the additional `baseline-left`, `baseline`, and `baseline-right` anchors sit
228
+ on the first line's baseline. Anchoring text `top-left` or `baseline-left`
229
+ is the reliable way to build precise layouts (columns of text, labels that
230
+ change content) without measuring fonts yourself.
231
+
232
+ #### Shadows
233
+
234
+ `text`, `image`, `shape`, `code`, and `group` elements take an optional
235
+ drop shadow:
236
+
237
+ ```json
238
+ { "shadow": { "blur": 24, "color": "#000000", "opacity": 0.6, "offset": { "x": 0, "y": 8 } } }
239
+ ```
240
+
241
+ | Key | Type | Default | Description |
242
+ |-----------|--------|-------------|-------------|
243
+ | `blur` | number | `8` | Gaussian blur radius in pixels. |
244
+ | `color` | string | `"#000000"` | Shadow color. |
245
+ | `opacity` | number | `0.5` | Shadow strength, `0.0`–`1.0`. |
246
+ | `offset` | object | `{0, 0}` | Shadow displacement in pixels. |
247
+
200
248
  #### `text`
201
249
 
202
250
  ```json
@@ -218,10 +266,15 @@ All element types share these keys:
218
266
  |-------------|--------|----------------|-------------|
219
267
  | `content` | string | — | The text to display. Supports `\n` for manual line breaks. |
220
268
  | `font` | string | bundled default | Path to a `.ttf`/`.otf` file. |
221
- | `size` | int | `48` | Font size in pixels. |
269
+ | `size` | number | `48` | Font size in pixels. |
222
270
  | `color` | string | `"#ffffff"` | Hex color. |
223
271
  | `align` | string | `"center"` | `left`, `center`, or `right` (for multi-line text). |
224
- | `max_width` | int | frame width | Wrap text to fit this pixel width. |
272
+ | `max_width` | number | frame width | Wrap text to fit this pixel width. |
273
+ | `wrap` | bool | `true` | Set `false` to disable wrapping entirely (`\n` still breaks lines). |
274
+
275
+ Wrapping breaks lines between words and preserves indentation and interior
276
+ runs of spaces. Text content can also change over time via a `content`
277
+ animation (see [Animations](#animations)).
225
278
 
226
279
  #### `video`
227
280
 
@@ -280,11 +333,98 @@ If the trimmed clip is shorter than its element window, it holds its last frame;
280
333
  | Key | Type | Default | Description |
281
334
  |----------------|--------|---------|-------------|
282
335
  | `shape` | string | — | `rect`, `ellipse`, or `line`. |
283
- | `width`/`height` | int | — | Dimensions in pixels (`line` uses `x2`/`y2` endpoints instead). |
336
+ | `width`/`height` | number | — | Dimensions in pixels (`line` uses `x2`/`y2` endpoints instead). |
284
337
  | `fill` | string | none | Fill color. |
285
338
  | `stroke` | string | none | Stroke color. |
286
339
  | `stroke_width` | int | `1` | Stroke thickness in pixels. |
287
- | `radius` | int | `0` | Corner radius for `rect`. |
340
+ | `radius` | number | `0` | Corner radius for `rect`. |
341
+
342
+ #### `code`
343
+
344
+ A block of syntax-highlighted code, laid out on a fixed line grid with
345
+ optional line numbers — and optionally revealed over time, typed character
346
+ by character with a cursor, as if someone were writing it live. Built for
347
+ coding-tutorial videos: put a `code` element over a mock editor window (see
348
+ [Reusable Elements](#reusable-elements)) and the code types itself in.
349
+
350
+ ```json
351
+ {
352
+ "type": "code",
353
+ "content": "def greet(name: str) -> str:\n return f\"Hi, {name}\"\n",
354
+ "language": "python",
355
+ "theme": "dark-plus",
356
+ "font": "assets/fonts/JetBrainsMono-Regular.ttf",
357
+ "size": 28,
358
+ "line_numbers": true,
359
+ "position": { "x": 200, "y": 170 },
360
+ "reveal": { "mode": "typing", "cps": 28, "line_pause": 0.3 }
361
+ }
362
+ ```
363
+
364
+ | Key | Type | Default | Description |
365
+ |----------------|--------|---------------|-------------|
366
+ | `content` | string | — | The code. Tabs expand to `tab_width` spaces; indentation is preserved exactly. |
367
+ | `language` | string | `"python"` | Any [pygments lexer name](https://pygments.org/languages/), or `"none"` for monochrome text (no pygments needed). |
368
+ | `theme` | string | `"dark-plus"` | `dark-plus`, `monokai`, or `github-light`. |
369
+ | `font` | string | — | Path to a monospace `.ttf`/`.otf`. Required. |
370
+ | `size` | number | `28` | Font size in pixels. |
371
+ | `line_height` | number | `size × 1.5` | Vertical distance between line tops. |
372
+ | `line_numbers` | bool | `false` | Draw a right-aligned line-number gutter. |
373
+ | `tab_width` | int | `4` | Spaces per tab. |
374
+ | `reveal` | object | none | Animate the code in (below). Omit for a static block. |
375
+
376
+ The block's `anchor` defaults to `top-left`, so `position` is the top-left
377
+ corner of the first line — matching how you think about an editor's text
378
+ area. Highlighting needs the `code` extra (`pip install "scenescript[code]"`).
379
+
380
+ ##### `reveal`
381
+
382
+ | Key | Type | Default | Description |
383
+ |--------------|--------|-----------|-------------|
384
+ | `mode` | string | `"typing"`| `typing` (character by character) or `lines` (line by line). |
385
+ | `cps` | number | `30` | Typing speed, characters per second (`typing`). |
386
+ | `line_pause` | number | `0.3` | Extra pause after each line break (`typing`). |
387
+ | `interval` | number | `0.5` | Seconds between lines (`lines`). |
388
+ | `delay` | number | `0` | Seconds after the element starts before the reveal begins. |
389
+ | `cursor` | bool | mode is `typing` | Draw an insertion-point cursor at the reveal position. |
390
+ | `blink` | bool | `true` | Blink the cursor once the reveal finishes. |
391
+
392
+ Times are on the element's own clock (they start at `start`). Validation
393
+ fails if the reveal takes longer than the element's window, so a too-short
394
+ scene is caught before rendering.
395
+
396
+ #### `group`
397
+
398
+ A container that renders its child elements onto its own canvas, then
399
+ places, animates, and fades that canvas as a single element. Children use
400
+ the group's coordinate space (positions relative to the group's top-left,
401
+ named positions relative to the group's box), run on the group's clock
402
+ (`start`/`end` relative to the group's `start`), and are **clipped** to the
403
+ group's `width` × `height`.
404
+
405
+ ```json
406
+ {
407
+ "type": "group",
408
+ "width": 800,
409
+ "height": 400,
410
+ "position": { "x": 960, "y": 540 },
411
+ "elements": [
412
+ { "type": "shape", "shape": "rect", "width": 800, "height": 400, "fill": "#1e1e1e", "position": { "x": 400, "y": 200 } },
413
+ { "type": "text", "content": "inside the panel", "position": { "x": 400, "y": 200 } }
414
+ ]
415
+ }
416
+ ```
417
+
418
+ | Key | Type | Default | Description |
419
+ |------------------|--------|----------|-------------|
420
+ | `width`/`height` | number | — | The group's canvas size in pixels. Children are clipped to it. |
421
+ | `scale` | number | `1.0` | Uniform scale applied to the rendered canvas. |
422
+ | `content_offset` | object | `{0, 0}` | Shifts all children within the canvas — animate it to scroll (a long code listing inside an editor viewport, terminal output). |
423
+ | `elements` | array | `[]` | Child elements, drawn in document order. Refs work here too. |
424
+
425
+ Groups make composites move as one: scale a whole mock window down,
426
+ slide a panel in, fade an entire overlay — and their clipping is what makes
427
+ scrolling viewports possible (animate `content_offset`).
288
428
 
289
429
  ### Reusable Elements
290
430
 
@@ -315,12 +455,65 @@ Define a group of elements once under the top-level `defs` key, then insert it a
315
455
  |----------|--------|----------|-------------|
316
456
  | `name` | string | yes | The def to insert. |
317
457
  | `offset` | object | no | `{ "x": dx, "y": dy }` added to every inserted element's position (after named anchors resolve). Defaults to no shift. |
458
+ | `params` | object | no | Values for a parameterized def's placeholders (below). |
318
459
 
319
460
  A `ref` splices the def's elements in place, keeping layer order: the def's elements draw in their own order, and anything listed after the ref draws on top — so a def works naturally as a background composite under per-scene content. Defs may reference other defs (offsets accumulate); circular references are a validation error. A def element that omits `end` runs to the end of whichever scene uses it. Every def is validated once at its own path (problems read `defs.ide[2].size: ...`), whether or not it is used.
320
461
 
462
+ #### Parameterized defs
463
+
464
+ A def can declare parameters with default values by using the object form —
465
+ `{ "params": { defaults }, "elements": [ ... ] }` — and referencing them as
466
+ `{name}` placeholders in any string:
467
+
468
+ ```json
469
+ {
470
+ "defs": {
471
+ "editor_tab": {
472
+ "params": { "filename": "untitled", "width": 200 },
473
+ "elements": [
474
+ { "type": "shape", "shape": "rect", "width": "{width}", "height": 40, "fill": "#1e1e1e", "position": { "x": 100, "y": 20 } },
475
+ { "type": "text", "content": "{filename}", "size": 22, "position": { "x": 100, "y": 20 } }
476
+ ]
477
+ }
478
+ },
479
+ "scenes": [
480
+ {
481
+ "duration": 4,
482
+ "elements": [
483
+ { "type": "ref", "name": "editor_tab", "params": { "filename": "app.py" } }
484
+ ]
485
+ }
486
+ ]
487
+ }
488
+ ```
489
+
490
+ A string that is exactly one placeholder (`"{width}"`) takes the parameter's
491
+ own type, so numbers can parameterize dimensions and positions. Placeholders
492
+ are spliced into longer strings as text. Only declared parameters substitute
493
+ — other braces (dict literals in code content, say) pass through untouched —
494
+ and passing an undeclared parameter is a validation error, so typos are
495
+ caught. A ref that omits `params` uses the declared defaults.
496
+
497
+ #### Shared def libraries
498
+
499
+ The top-level `include` key merges `defs` from other JSON files, so one IDE
500
+ mock, lower third, or brand kit can serve many videos:
501
+
502
+ ```json
503
+ { "include": ["../shared/ide.defs.json"], "scenes": [ ... ] }
504
+ ```
505
+
506
+ An included file is a JSON object with a single `defs` object. Asset paths
507
+ inside it resolve against **that file's** directory (a def library carries
508
+ its own fonts and images no matter who includes it). Names must be unique
509
+ across the document and everything it includes — a collision is a validation
510
+ error, not a silent override. Included files cannot themselves include.
511
+ Problems inside an included def are reported with the file prefixed:
512
+ `ide.defs.json:defs.ide[2].size: ...`.
513
+
321
514
  ### Animations
322
515
 
323
- Any element can animate `position`, `opacity`, `scale`, `scale_x`, or `scale_y` with keyframes. Times are in seconds relative to the element's `start`. Values between keyframes are interpolated; before the first and after the last keyframe, the boundary value holds.
516
+ Any element can animate `position`, `opacity`, `scale`, `scale_x`, or `scale_y` with keyframes. Text elements can additionally animate `content` (the string itself — values switch at each keyframe, no interpolation), and groups can animate `content_offset` (scrolling their children). Times are in seconds relative to the element's `start`. Values between keyframes are interpolated; before the first and after the last keyframe, the boundary value holds.
324
517
 
325
518
  ```json
326
519
  {
@@ -349,12 +542,29 @@ Any element can animate `position`, `opacity`, `scale`, `scale_x`, or `scale_y`
349
542
 
350
543
  | Key | Type | Description |
351
544
  |------------|--------|-------------|
352
- | `property` | string | `position`, `opacity`, `scale`, `scale_x`, or `scale_y`. |
545
+ | `property` | string | `position`, `opacity`, `scale`, `scale_x`, `scale_y`, `content` (text only), or `content_offset` (groups only). |
353
546
  | `keyframes`| array | Two or more `{ time, value, easing }` points. |
354
- | `easing` | string | Interpolation *out of* this keyframe: `linear` (default), `ease_in`, `ease_out`, `ease_in_out`. |
547
+ | `easing` | string | Interpolation *out of* this keyframe: `linear` (default), `ease_in`, `ease_out`, `ease_in_out`, or `step` (hold this value, jump at the next keyframe). |
548
+ | `repeat` | int | Play the keyframe cycle this many times before the final value holds. Default `1`. |
549
+ | `loop` | bool | Repeat the cycle for as long as the element is visible. Mutually exclusive with `repeat`. |
355
550
 
356
551
  `scale` is uniform. `scale_x` and `scale_y` scale one axis only; when one is combined with `scale` on the same element, the values multiply.
357
552
 
553
+ `step` easing plus `loop` covers everything that used to need long hand-built
554
+ keyframe lists — a blinking cursor is three keyframes:
555
+
556
+ ```json
557
+ {
558
+ "property": "opacity",
559
+ "loop": true,
560
+ "keyframes": [
561
+ { "time": 0.0, "value": 1.0, "easing": "step" },
562
+ { "time": 0.53, "value": 0.0, "easing": "step" },
563
+ { "time": 1.06, "value": 1.0 }
564
+ ]
565
+ }
566
+ ```
567
+
358
568
  A slow position/scale drift on an image gives you the Ken Burns effect:
359
569
 
360
570
  ```json
@@ -731,6 +941,22 @@ scenescript render <input.json> -o <output>
731
941
  | `--overwrite` | Replace the output file if it already exists. |
732
942
  | `-q, --quiet` | Suppress the progress display. |
733
943
 
944
+ ### `scenescript frames`
945
+
946
+ Render single frames to PNGs for spot-checking a spec without a full render.
947
+
948
+ ```bash
949
+ scenescript frames <input.json> -o <directory> --at 3.5 --frame 105
950
+ ```
951
+
952
+ | Option | Description |
953
+ |----------------|-------------|
954
+ | `-o, --output DIR` | Directory for the PNGs (created if missing; existing frames are replaced). |
955
+ | `--at SECONDS` | Render the frame at this time. Repeatable. |
956
+ | `--frame N` | Render this frame number. Repeatable. |
957
+
958
+ Frames are written as `frame_<number>.png` (zero-padded) and each path is printed. Transition frames blend exactly as a full render would.
959
+
734
960
  ### `scenescript validate`
735
961
 
736
962
  Check a JSON file without rendering: schema correctness, asset paths, timing sanity (elements within scene bounds, transitions not longer than their scenes).
@@ -746,10 +972,13 @@ Exits non-zero with a list of problems, or prints a summary of the video (scene
746
972
  SceneScript ships an optional [MCP](https://modelcontextprotocol.io) server so AI agents can author and render videos through tool calls.
747
973
 
748
974
  ```bash
749
- pip install "scenescript[mcp]"
975
+ pip install "scenescript[mcp,code]"
750
976
  scenescript-mcp
751
977
  ```
752
978
 
979
+ (The `code` extra is optional but recommended: it lets agents use
980
+ syntax-highlighted [`code` elements](#code) without a follow-up install.)
981
+
753
982
  The server speaks stdio. To register it with Claude Code:
754
983
 
755
984
  ```bash
@@ -758,13 +987,14 @@ claude mcp add scenescript -- scenescript-mcp
758
987
 
759
988
  The registration stores the `scenescript-mcp` command, not a version, so after [upgrading](#upgrading) there is nothing to re-register. A client launches the server once per session, so a running session keeps the old one; start a new session (or reconnect via `/mcp` in Claude Code) to pick up the new version.
760
989
 
761
- Three tools:
990
+ Four tools:
762
991
 
763
992
  | Tool | What it does |
764
993
  |---|---|
765
994
  | `get_format_reference` | Returns this document, so an agent can learn the JSON format before authoring a spec. |
766
995
  | `validate_video` | Checks a spec without rendering. Pass the spec inline as `spec` (asset paths resolve against `assets_dir`) or as `spec_path` (a JSON file; asset paths resolve beside it). |
767
996
  | `render_video` | Renders a spec to `output_path`. The extension picks the container; an existing file is only replaced when `overwrite` is true. |
997
+ | `render_frames` | Renders single frames as PNGs into `output_dir` to spot-check a spec, picked by `times` (seconds) and/or `frame_numbers`. Returns each frame's number, timestamp, and file path. |
768
998
 
769
999
  Validation problems come back as data rather than tool errors, so an agent can fix its spec and call again. Rendering takes roughly the video's duration.
770
1000