scenescript 0.2.0__tar.gz → 0.3.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.3.0}/PKG-INFO +225 -16
  2. {scenescript-0.2.0 → scenescript-0.3.0}/README.md +222 -15
  3. scenescript-0.3.0/docs/adr/0008-declared-def-params-with-defaults.md +34 -0
  4. scenescript-0.3.0/docs/fake-ide-feature-notes.md +42 -0
  5. scenescript-0.3.0/examples/fake-ide/README.md +37 -0
  6. scenescript-0.3.0/examples/fake-ide/ide.defs.json +59 -0
  7. scenescript-0.3.0/examples/fake-ide/tutorial.json +176 -0
  8. scenescript-0.3.0/examples/fake-ide/tutorial.mp4 +0 -0
  9. {scenescript-0.2.0 → scenescript-0.3.0}/pyproject.toml +5 -1
  10. scenescript-0.3.0/src/scenescript/animation.py +66 -0
  11. scenescript-0.3.0/src/scenescript/codeblocks.py +238 -0
  12. scenescript-0.3.0/src/scenescript/codethemes.py +91 -0
  13. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/easing.py +6 -0
  14. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/geometry.py +16 -0
  15. scenescript-0.3.0/src/scenescript/scenes.py +210 -0
  16. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/spec.py +387 -32
  17. scenescript-0.3.0/src/scenescript/sprites.py +182 -0
  18. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/validation.py +45 -16
  19. {scenescript-0.2.0 → scenescript-0.3.0}/tests/conftest.py +15 -0
  20. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_animation.py +23 -0
  21. scenescript-0.3.0/tests/test_code.py +182 -0
  22. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_easing.py +6 -0
  23. scenescript-0.3.0/tests/test_groups.py +120 -0
  24. scenescript-0.3.0/tests/test_includes.py +179 -0
  25. scenescript-0.3.0/tests/test_spec_features.py +174 -0
  26. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_sprites.py +46 -6
  27. {scenescript-0.2.0 → scenescript-0.3.0}/uv.lock +8 -2
  28. scenescript-0.2.0/src/scenescript/animation.py +0 -43
  29. scenescript-0.2.0/src/scenescript/scenes.py +0 -142
  30. scenescript-0.2.0/src/scenescript/sprites.py +0 -109
  31. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/agents/copy-writer.md +0 -0
  32. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/agents/product-owner.md +0 -0
  33. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/agents/qa-tester.md +0 -0
  34. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/agents/software-architect.md +0 -0
  35. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/agents/software-engineer.md +0 -0
  36. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/agents/ui-ux-specialist.md +0 -0
  37. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/README.md +0 -0
  38. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/accessibility-standard.md +0 -0
  39. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/adr-index.md +0 -0
  40. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/ci-pipeline.md +0 -0
  41. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/competitor-positioning.md +0 -0
  42. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/design-tokens.md +0 -0
  43. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/device-matrix.md +0 -0
  44. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/domain-glossary.md +0 -0
  45. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/environment-map.md +0 -0
  46. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/grounding-rules.md +0 -0
  47. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/known-debt.md +0 -0
  48. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/known-issues.md +0 -0
  49. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/local-dev-setup.md +0 -0
  50. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/nfr-targets.md +0 -0
  51. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/observability-map.md +0 -0
  52. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/personas.md +0 -0
  53. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/research-repository.md +0 -0
  54. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/severity-ladder.md +0 -0
  55. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/system-map.md +0 -0
  56. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/tech-radar.md +0 -0
  57. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/test-data-catalog.md +0 -0
  58. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/ui-string-catalog.md +0 -0
  59. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/context/voice-guide.md +0 -0
  60. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/analyzing-trade-offs/SKILL.md +0 -0
  61. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/analyzing-trade-offs/references/worked-example.md +0 -0
  62. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/applying-design-system-conventions/SKILL.md +0 -0
  63. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/applying-design-system-conventions/references/drift-catalogue.md +0 -0
  64. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/applying-design-system-conventions/references/worked-resolution.md +0 -0
  65. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/auditing-accessibility/SKILL.md +0 -0
  66. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/auditing-accessibility/references/audit-checklist.md +0 -0
  67. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/auditing-accessibility/references/finding-template.md +0 -0
  68. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/auditing-accessibility/references/state-audit.md +0 -0
  69. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/automating-tests/SKILL.md +0 -0
  70. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/automating-tests/references/adversarial-cases.md +0 -0
  71. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/automating-tests/references/flake-cures.md +0 -0
  72. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/automating-tests/references/test-note.md +0 -0
  73. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/critiquing-with-heuristics/SKILL.md +0 -0
  74. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/critiquing-with-heuristics/references/heuristics.md +0 -0
  75. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/critiquing-with-heuristics/references/worked-example.md +0 -0
  76. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/debugging-and-incidents/SKILL.md +0 -0
  77. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/debugging-and-incidents/references/records.md +0 -0
  78. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/defining-voice-and-style/SKILL.md +0 -0
  79. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/defining-voice-and-style/references/worked-guide.md +0 -0
  80. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/designing-tests-from-acceptance-criteria/SKILL.md +0 -0
  81. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/designing-tests-from-acceptance-criteria/references/adversarial-catalogue.md +0 -0
  82. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/designing-tests-from-acceptance-criteria/references/worked-example.md +0 -0
  83. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/documenting-flows-and-ia/SKILL.md +0 -0
  84. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/documenting-flows-and-ia/references/branch-checklist.md +0 -0
  85. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/documenting-flows-and-ia/references/worked-flow.md +0 -0
  86. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/documenting-systems/SKILL.md +0 -0
  87. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/documenting-systems/references/evidence-ladder.md +0 -0
  88. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/documenting-systems/references/worked-diagram.md +0 -0
  89. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/drafting-from-a-brief/SKILL.md +0 -0
  90. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/drafting-from-a-brief/references/worked-brief.md +0 -0
  91. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/editing-copy/SKILL.md +0 -0
  92. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/editing-copy/references/deliverables.md +0 -0
  93. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/enforcing-terminology/SKILL.md +0 -0
  94. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/enforcing-terminology/references/deliverable.md +0 -0
  95. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/enforcing-terminology/references/sweep-recipe.md +0 -0
  96. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/enumerating-ui-states/SKILL.md +0 -0
  97. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/enumerating-ui-states/references/inventory-template.md +0 -0
  98. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/enumerating-ui-states/references/state-axes.md +0 -0
  99. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/managing-test-data/SKILL.md +0 -0
  100. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/managing-test-data/references/hostile-fixtures.md +0 -0
  101. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/managing-test-data/references/provisioning-routes.md +0 -0
  102. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/planning-implementation/SKILL.md +0 -0
  103. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/planning-implementation/references/worked-plan.md +0 -0
  104. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/planning-migrations/SKILL.md +0 -0
  105. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/planning-migrations/references/expand-contract.md +0 -0
  106. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/planning-migrations/references/worked-plan.md +0 -0
  107. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/planning-usability-tests/SKILL.md +0 -0
  108. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/planning-usability-tests/references/plan-template.md +0 -0
  109. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/planning-usability-tests/references/task-wording.md +0 -0
  110. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/prioritizing-work/SKILL.md +0 -0
  111. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/prioritizing-work/references/cost-of-delay.md +0 -0
  112. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/prioritizing-work/references/frameworks.md +0 -0
  113. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/prioritizing-work/references/worked-example.md +0 -0
  114. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/probing-non-functional-behavior/SKILL.md +0 -0
  115. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/probing-non-functional-behavior/references/adversarial-probes.md +0 -0
  116. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/probing-non-functional-behavior/references/probe-types.md +0 -0
  117. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/probing-non-functional-behavior/references/worked-probe.md +0 -0
  118. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/refactoring/SKILL.md +0 -0
  119. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/refactoring/references/characterization-tests.md +0 -0
  120. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/refactoring/references/mechanical-moves.md +0 -0
  121. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/refining-the-backlog/SKILL.md +0 -0
  122. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/refining-the-backlog/references/split-axes.md +0 -0
  123. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/removing-ai-tells/SKILL.md +0 -0
  124. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/removing-ai-tells/references/catalogue.md +0 -0
  125. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reporting-defects/SKILL.md +0 -0
  126. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reporting-defects/references/report-template.md +0 -0
  127. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reporting-defects/references/worked-examples.md +0 -0
  128. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-code/SKILL.md +0 -0
  129. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-code/references/correctness-probes.md +0 -0
  130. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-code/references/worked-review.md +0 -0
  131. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-design-against-nfrs/SKILL.md +0 -0
  132. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-design-against-nfrs/references/quality-checklist.md +0 -0
  133. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-design-against-nfrs/references/worked-review.md +0 -0
  134. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-for-acceptance/SKILL.md +0 -0
  135. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-for-acceptance/references/acceptance-record.md +0 -0
  136. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-tests/SKILL.md +0 -0
  137. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-tests/references/mutation-catalogue.md +0 -0
  138. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-tests/references/tests-that-cannot-fail.md +0 -0
  139. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/reviewing-tests/references/worked-review.md +0 -0
  140. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/running-design-qa/SKILL.md +0 -0
  141. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/running-design-qa/references/check-matrix.md +0 -0
  142. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/running-design-qa/references/output-template.md +0 -0
  143. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/running-spikes/SKILL.md +0 -0
  144. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/running-spikes/references/spike-note.md +0 -0
  145. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/scoping-regression-tests/SKILL.md +0 -0
  146. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/scoping-regression-tests/references/reach-checklist.md +0 -0
  147. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/scoping-regression-tests/references/scope-note.md +0 -0
  148. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/specifying-interactions/SKILL.md +0 -0
  149. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/specifying-interactions/references/adversarial-read.md +0 -0
  150. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/specifying-interactions/references/spec-template.md +0 -0
  151. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/synthesizing-research/SKILL.md +0 -0
  152. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/synthesizing-research/references/no-research-yet.md +0 -0
  153. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/synthesizing-research/references/worked-synthesis.md +0 -0
  154. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/tdd-workflow/SKILL.md +0 -0
  155. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/tdd-workflow/references/reading-red.md +0 -0
  156. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/tdd-workflow/references/worked-cycle.md +0 -0
  157. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/testing-accessibility/SKILL.md +0 -0
  158. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/testing-accessibility/references/adversarial-conditions.md +0 -0
  159. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/testing-accessibility/references/finding-template.md +0 -0
  160. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/testing-accessibility/references/keyboard-pass.md +0 -0
  161. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/testing-accessibility/references/screen-reader-pass.md +0 -0
  162. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/testing-apis-and-contracts/SKILL.md +0 -0
  163. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/testing-apis-and-contracts/references/adversarial-catalogue.md +0 -0
  164. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/testing-apis-and-contracts/references/compatibility-matrix.md +0 -0
  165. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/triaging-bugs/SKILL.md +0 -0
  166. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/triaging-bugs/references/severity-and-priority.md +0 -0
  167. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/triaging-requests/SKILL.md +0 -0
  168. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/triaging-requests/references/triage-note.md +0 -0
  169. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/upgrading-dependencies/SKILL.md +0 -0
  170. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/upgrading-dependencies/references/silent-changes.md +0 -0
  171. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/upgrading-dependencies/references/upgrade-note.md +0 -0
  172. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/verifying-done/SKILL.md +0 -0
  173. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/verifying-done/references/completion-report.md +0 -0
  174. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/verifying-done/references/rationalizations.md +0 -0
  175. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/verifying-done/references/scaling-the-check.md +0 -0
  176. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-adrs/SKILL.md +0 -0
  177. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-adrs/references/adr-template.md +0 -0
  178. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-adrs/references/worked-adr.md +0 -0
  179. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-documentation/SKILL.md +0 -0
  180. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-documentation/references/page-shapes.md +0 -0
  181. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-documentation/references/worked-example.md +0 -0
  182. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-exploratory-charters/SKILL.md +0 -0
  183. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-exploratory-charters/references/lens-catalogue.md +0 -0
  184. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-exploratory-charters/references/session-record.md +0 -0
  185. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-marketing-copy/SKILL.md +0 -0
  186. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-marketing-copy/references/awareness-and-formats.md +0 -0
  187. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-marketing-copy/references/worked-examples.md +0 -0
  188. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-microcopy-in-context/SKILL.md +0 -0
  189. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-microcopy-in-context/references/content-set.md +0 -0
  190. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-microcopy-in-context/references/worked-review.md +0 -0
  191. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-plain-language/SKILL.md +0 -0
  192. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-plain-language/references/text-accessibility-checks.md +0 -0
  193. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-plain-language/references/worked-example.md +0 -0
  194. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-seo-metadata/SKILL.md +0 -0
  195. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-seo-metadata/references/surfaces.md +0 -0
  196. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-ui-copy/SKILL.md +0 -0
  197. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-ui-copy/references/constraints-and-variables.md +0 -0
  198. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-ui-copy/references/string-types.md +0 -0
  199. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-user-stories/SKILL.md +0 -0
  200. {scenescript-0.2.0 → scenescript-0.3.0}/.claude/skills/writing-user-stories/references/worked-example.md +0 -0
  201. {scenescript-0.2.0 → scenescript-0.3.0}/.gitignore +0 -0
  202. {scenescript-0.2.0 → scenescript-0.3.0}/LICENSE +0 -0
  203. {scenescript-0.2.0 → scenescript-0.3.0}/docs/adr/0001-pillow-numpy-composition-ffmpeg-at-boundaries.md +0 -0
  204. {scenescript-0.2.0 → scenescript-0.3.0}/docs/adr/0002-transition-timeline-model.md +0 -0
  205. {scenescript-0.2.0 → scenescript-0.3.0}/docs/adr/0003-single-ffmpeg-process-for-encode-and-audio.md +0 -0
  206. {scenescript-0.2.0 → scenescript-0.3.0}/docs/adr/0004-hand-written-validation.md +0 -0
  207. {scenescript-0.2.0 → scenescript-0.3.0}/docs/adr/0005-pillow-embedded-default-font.md +0 -0
  208. {scenescript-0.2.0 → scenescript-0.3.0}/docs/adr/0006-mcp-server-as-optional-extra.md +0 -0
  209. {scenescript-0.2.0 → scenescript-0.3.0}/docs/adr/0007-reusable-elements-expand-at-parse-time.md +0 -0
  210. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/__init__.py +0 -0
  211. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/audio.py +0 -0
  212. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/backgrounds.py +0 -0
  213. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/cli.py +0 -0
  214. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/colors.py +0 -0
  215. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/encoder.py +0 -0
  216. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/errors.py +0 -0
  217. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/mcp_server.py +0 -0
  218. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/probe.py +0 -0
  219. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/progress.py +0 -0
  220. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/renderer.py +0 -0
  221. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/timeline.py +0 -0
  222. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/transitions.py +0 -0
  223. {scenescript-0.2.0 → scenescript-0.3.0}/src/scenescript/videoreader.py +0 -0
  224. {scenescript-0.2.0 → scenescript-0.3.0}/tests/__init__.py +0 -0
  225. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_audio.py +0 -0
  226. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_backgrounds.py +0 -0
  227. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_cli.py +0 -0
  228. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_colors.py +0 -0
  229. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_defs.py +0 -0
  230. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_geometry.py +0 -0
  231. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_mcp_server.py +0 -0
  232. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_probe.py +0 -0
  233. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_render.py +0 -0
  234. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_scenes.py +0 -0
  235. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_spec.py +0 -0
  236. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_timeline.py +0 -0
  237. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_transitions.py +0 -0
  238. {scenescript-0.2.0 → scenescript-0.3.0}/tests/test_validation.py +0 -0
  239. {scenescript-0.2.0 → scenescript-0.3.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.3.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,6 +57,13 @@ 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
@@ -124,12 +133,13 @@ scenescript render video.json -o output.mp4
124
133
 
125
134
  ### Top Level
126
135
 
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. |
136
+ | Key | Type | Required | Description |
137
+ |-----------|--------|----------|-------------|
138
+ | `output` | object | no | Output settings. Defaults: `1920×1080`, `30` fps, `mp4`. |
139
+ | `scenes` | array | yes | Ordered list of scenes, played back to back. |
140
+ | `defs` | object | no | Named, reusable element groups (see [Reusable Elements](#reusable-elements)). |
141
+ | `include` | array | no | Paths of JSON files whose `defs` are merged in (see [Shared def libraries](#shared-def-libraries)). |
142
+ | `audio` | array | no | Global audio tracks spanning the whole video. |
133
143
 
134
144
  #### `output`
135
145
 
@@ -190,13 +200,50 @@ All element types share these keys:
190
200
 
191
201
  | Key | Type | Default | Description |
192
202
  |--------------|---------------|----------------|-------------|
193
- | `type` | string | — | `text`, `video`, `image`, `shape`, or `ref` (see [Reusable Elements](#reusable-elements)). |
203
+ | `type` | string | — | `text`, `video`, `image`, `shape`, `code`, `group`, or `ref` (see [Reusable Elements](#reusable-elements)). |
194
204
  | `start` | number | `0` | Seconds into the scene when the element appears. |
195
205
  | `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. |
206
+ | `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. |
207
+ | `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
208
  | `opacity` | number | `1.0` | `0.0`–`1.0`. |
209
+ | `shadow` | object | none | Drop shadow (see [Shadows](#shadows)). Not on `video` elements. |
198
210
  | `animations` | array | `[]` | Keyframed property animations (see [Animations](#animations)). |
199
211
 
212
+ Pixel dimensions (`width`, `height`, `size`, `radius`, `max_width`) accept any
213
+ number; fractional values are rounded, so computed layouts can pass floats.
214
+
215
+ #### Anchors
216
+
217
+ By default an explicit `{x, y}` position locates the element's **center**.
218
+ `anchor` changes which point it locates instead: `top-left`, `top`,
219
+ `top-right`, `left`, `right`, `bottom-left`, `bottom`, `bottom-right`, or
220
+ `center`. Named string positions (`"top-left"` etc.) already place the whole
221
+ box against the frame and ignore `anchor`.
222
+
223
+ For `text` elements, anchors are **font-metric based** so that different
224
+ strings line up consistently: `left`/`right` anchor the pen origin and
225
+ advance width (not the inked pixels), `top` anchors the ascender line, and
226
+ the additional `baseline-left`, `baseline`, and `baseline-right` anchors sit
227
+ on the first line's baseline. Anchoring text `top-left` or `baseline-left`
228
+ is the reliable way to build precise layouts (columns of text, labels that
229
+ change content) without measuring fonts yourself.
230
+
231
+ #### Shadows
232
+
233
+ `text`, `image`, `shape`, `code`, and `group` elements take an optional
234
+ drop shadow:
235
+
236
+ ```json
237
+ { "shadow": { "blur": 24, "color": "#000000", "opacity": 0.6, "offset": { "x": 0, "y": 8 } } }
238
+ ```
239
+
240
+ | Key | Type | Default | Description |
241
+ |-----------|--------|-------------|-------------|
242
+ | `blur` | number | `8` | Gaussian blur radius in pixels. |
243
+ | `color` | string | `"#000000"` | Shadow color. |
244
+ | `opacity` | number | `0.5` | Shadow strength, `0.0`–`1.0`. |
245
+ | `offset` | object | `{0, 0}` | Shadow displacement in pixels. |
246
+
200
247
  #### `text`
201
248
 
202
249
  ```json
@@ -218,10 +265,15 @@ All element types share these keys:
218
265
  |-------------|--------|----------------|-------------|
219
266
  | `content` | string | — | The text to display. Supports `\n` for manual line breaks. |
220
267
  | `font` | string | bundled default | Path to a `.ttf`/`.otf` file. |
221
- | `size` | int | `48` | Font size in pixels. |
268
+ | `size` | number | `48` | Font size in pixels. |
222
269
  | `color` | string | `"#ffffff"` | Hex color. |
223
270
  | `align` | string | `"center"` | `left`, `center`, or `right` (for multi-line text). |
224
- | `max_width` | int | frame width | Wrap text to fit this pixel width. |
271
+ | `max_width` | number | frame width | Wrap text to fit this pixel width. |
272
+ | `wrap` | bool | `true` | Set `false` to disable wrapping entirely (`\n` still breaks lines). |
273
+
274
+ Wrapping breaks lines between words and preserves indentation and interior
275
+ runs of spaces. Text content can also change over time via a `content`
276
+ animation (see [Animations](#animations)).
225
277
 
226
278
  #### `video`
227
279
 
@@ -280,11 +332,98 @@ If the trimmed clip is shorter than its element window, it holds its last frame;
280
332
  | Key | Type | Default | Description |
281
333
  |----------------|--------|---------|-------------|
282
334
  | `shape` | string | — | `rect`, `ellipse`, or `line`. |
283
- | `width`/`height` | int | — | Dimensions in pixels (`line` uses `x2`/`y2` endpoints instead). |
335
+ | `width`/`height` | number | — | Dimensions in pixels (`line` uses `x2`/`y2` endpoints instead). |
284
336
  | `fill` | string | none | Fill color. |
285
337
  | `stroke` | string | none | Stroke color. |
286
338
  | `stroke_width` | int | `1` | Stroke thickness in pixels. |
287
- | `radius` | int | `0` | Corner radius for `rect`. |
339
+ | `radius` | number | `0` | Corner radius for `rect`. |
340
+
341
+ #### `code`
342
+
343
+ A block of syntax-highlighted code, laid out on a fixed line grid with
344
+ optional line numbers — and optionally revealed over time, typed character
345
+ by character with a cursor, as if someone were writing it live. Built for
346
+ coding-tutorial videos: put a `code` element over a mock editor window (see
347
+ [Reusable Elements](#reusable-elements)) and the code types itself in.
348
+
349
+ ```json
350
+ {
351
+ "type": "code",
352
+ "content": "def greet(name: str) -> str:\n return f\"Hi, {name}\"\n",
353
+ "language": "python",
354
+ "theme": "dark-plus",
355
+ "font": "assets/fonts/JetBrainsMono-Regular.ttf",
356
+ "size": 28,
357
+ "line_numbers": true,
358
+ "position": { "x": 200, "y": 170 },
359
+ "reveal": { "mode": "typing", "cps": 28, "line_pause": 0.3 }
360
+ }
361
+ ```
362
+
363
+ | Key | Type | Default | Description |
364
+ |----------------|--------|---------------|-------------|
365
+ | `content` | string | — | The code. Tabs expand to `tab_width` spaces; indentation is preserved exactly. |
366
+ | `language` | string | `"python"` | Any [pygments lexer name](https://pygments.org/languages/), or `"none"` for monochrome text (no pygments needed). |
367
+ | `theme` | string | `"dark-plus"` | `dark-plus`, `monokai`, or `github-light`. |
368
+ | `font` | string | — | Path to a monospace `.ttf`/`.otf`. Required. |
369
+ | `size` | number | `28` | Font size in pixels. |
370
+ | `line_height` | number | `size × 1.5` | Vertical distance between line tops. |
371
+ | `line_numbers` | bool | `false` | Draw a right-aligned line-number gutter. |
372
+ | `tab_width` | int | `4` | Spaces per tab. |
373
+ | `reveal` | object | none | Animate the code in (below). Omit for a static block. |
374
+
375
+ The block's `anchor` defaults to `top-left`, so `position` is the top-left
376
+ corner of the first line — matching how you think about an editor's text
377
+ area. Highlighting needs the `code` extra (`pip install "scenescript[code]"`).
378
+
379
+ ##### `reveal`
380
+
381
+ | Key | Type | Default | Description |
382
+ |--------------|--------|-----------|-------------|
383
+ | `mode` | string | `"typing"`| `typing` (character by character) or `lines` (line by line). |
384
+ | `cps` | number | `30` | Typing speed, characters per second (`typing`). |
385
+ | `line_pause` | number | `0.3` | Extra pause after each line break (`typing`). |
386
+ | `interval` | number | `0.5` | Seconds between lines (`lines`). |
387
+ | `delay` | number | `0` | Seconds after the element starts before the reveal begins. |
388
+ | `cursor` | bool | mode is `typing` | Draw an insertion-point cursor at the reveal position. |
389
+ | `blink` | bool | `true` | Blink the cursor once the reveal finishes. |
390
+
391
+ Times are on the element's own clock (they start at `start`). Validation
392
+ fails if the reveal takes longer than the element's window, so a too-short
393
+ scene is caught before rendering.
394
+
395
+ #### `group`
396
+
397
+ A container that renders its child elements onto its own canvas, then
398
+ places, animates, and fades that canvas as a single element. Children use
399
+ the group's coordinate space (positions relative to the group's top-left,
400
+ named positions relative to the group's box), run on the group's clock
401
+ (`start`/`end` relative to the group's `start`), and are **clipped** to the
402
+ group's `width` × `height`.
403
+
404
+ ```json
405
+ {
406
+ "type": "group",
407
+ "width": 800,
408
+ "height": 400,
409
+ "position": { "x": 960, "y": 540 },
410
+ "elements": [
411
+ { "type": "shape", "shape": "rect", "width": 800, "height": 400, "fill": "#1e1e1e", "position": { "x": 400, "y": 200 } },
412
+ { "type": "text", "content": "inside the panel", "position": { "x": 400, "y": 200 } }
413
+ ]
414
+ }
415
+ ```
416
+
417
+ | Key | Type | Default | Description |
418
+ |------------------|--------|----------|-------------|
419
+ | `width`/`height` | number | — | The group's canvas size in pixels. Children are clipped to it. |
420
+ | `scale` | number | `1.0` | Uniform scale applied to the rendered canvas. |
421
+ | `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). |
422
+ | `elements` | array | `[]` | Child elements, drawn in document order. Refs work here too. |
423
+
424
+ Groups make composites move as one: scale a whole mock window down,
425
+ slide a panel in, fade an entire overlay — and their clipping is what makes
426
+ scrolling viewports possible (animate `content_offset`).
288
427
 
289
428
  ### Reusable Elements
290
429
 
@@ -315,12 +454,65 @@ Define a group of elements once under the top-level `defs` key, then insert it a
315
454
  |----------|--------|----------|-------------|
316
455
  | `name` | string | yes | The def to insert. |
317
456
  | `offset` | object | no | `{ "x": dx, "y": dy }` added to every inserted element's position (after named anchors resolve). Defaults to no shift. |
457
+ | `params` | object | no | Values for a parameterized def's placeholders (below). |
318
458
 
319
459
  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
460
 
461
+ #### Parameterized defs
462
+
463
+ A def can declare parameters with default values by using the object form —
464
+ `{ "params": { defaults }, "elements": [ ... ] }` — and referencing them as
465
+ `{name}` placeholders in any string:
466
+
467
+ ```json
468
+ {
469
+ "defs": {
470
+ "editor_tab": {
471
+ "params": { "filename": "untitled", "width": 200 },
472
+ "elements": [
473
+ { "type": "shape", "shape": "rect", "width": "{width}", "height": 40, "fill": "#1e1e1e", "position": { "x": 100, "y": 20 } },
474
+ { "type": "text", "content": "{filename}", "size": 22, "position": { "x": 100, "y": 20 } }
475
+ ]
476
+ }
477
+ },
478
+ "scenes": [
479
+ {
480
+ "duration": 4,
481
+ "elements": [
482
+ { "type": "ref", "name": "editor_tab", "params": { "filename": "app.py" } }
483
+ ]
484
+ }
485
+ ]
486
+ }
487
+ ```
488
+
489
+ A string that is exactly one placeholder (`"{width}"`) takes the parameter's
490
+ own type, so numbers can parameterize dimensions and positions. Placeholders
491
+ are spliced into longer strings as text. Only declared parameters substitute
492
+ — other braces (dict literals in code content, say) pass through untouched —
493
+ and passing an undeclared parameter is a validation error, so typos are
494
+ caught. A ref that omits `params` uses the declared defaults.
495
+
496
+ #### Shared def libraries
497
+
498
+ The top-level `include` key merges `defs` from other JSON files, so one IDE
499
+ mock, lower third, or brand kit can serve many videos:
500
+
501
+ ```json
502
+ { "include": ["../shared/ide.defs.json"], "scenes": [ ... ] }
503
+ ```
504
+
505
+ An included file is a JSON object with a single `defs` object. Asset paths
506
+ inside it resolve against **that file's** directory (a def library carries
507
+ its own fonts and images no matter who includes it). Names must be unique
508
+ across the document and everything it includes — a collision is a validation
509
+ error, not a silent override. Included files cannot themselves include.
510
+ Problems inside an included def are reported with the file prefixed:
511
+ `ide.defs.json:defs.ide[2].size: ...`.
512
+
321
513
  ### Animations
322
514
 
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.
515
+ 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
516
 
325
517
  ```json
326
518
  {
@@ -349,12 +541,29 @@ Any element can animate `position`, `opacity`, `scale`, `scale_x`, or `scale_y`
349
541
 
350
542
  | Key | Type | Description |
351
543
  |------------|--------|-------------|
352
- | `property` | string | `position`, `opacity`, `scale`, `scale_x`, or `scale_y`. |
544
+ | `property` | string | `position`, `opacity`, `scale`, `scale_x`, `scale_y`, `content` (text only), or `content_offset` (groups only). |
353
545
  | `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`. |
546
+ | `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). |
547
+ | `repeat` | int | Play the keyframe cycle this many times before the final value holds. Default `1`. |
548
+ | `loop` | bool | Repeat the cycle for as long as the element is visible. Mutually exclusive with `repeat`. |
355
549
 
356
550
  `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
551
 
552
+ `step` easing plus `loop` covers everything that used to need long hand-built
553
+ keyframe lists — a blinking cursor is three keyframes:
554
+
555
+ ```json
556
+ {
557
+ "property": "opacity",
558
+ "loop": true,
559
+ "keyframes": [
560
+ { "time": 0.0, "value": 1.0, "easing": "step" },
561
+ { "time": 0.53, "value": 0.0, "easing": "step" },
562
+ { "time": 1.06, "value": 1.0 }
563
+ ]
564
+ }
565
+ ```
566
+
358
567
  A slow position/scale drift on an image gives you the Ken Burns effect:
359
568
 
360
569
  ```json
@@ -35,6 +35,13 @@ For the [MCP server](#mcp-server), include the extra:
35
35
  pip install "scenescript[mcp]"
36
36
  ```
37
37
 
38
+ For syntax-highlighted [`code` elements](#code), include the `code` extra
39
+ (it pulls in [pygments](https://pygments.org)):
40
+
41
+ ```bash
42
+ pip install "scenescript[code]"
43
+ ```
44
+
38
45
  ### Upgrading
39
46
 
40
47
  ```bash
@@ -104,12 +111,13 @@ scenescript render video.json -o output.mp4
104
111
 
105
112
  ### Top Level
106
113
 
107
- | Key | Type | Required | Description |
108
- |----------|--------|----------|-------------|
109
- | `output` | object | no | Output settings. Defaults: `1920×1080`, `30` fps, `mp4`. |
110
- | `scenes` | array | yes | Ordered list of scenes, played back to back. |
111
- | `defs` | object | no | Named, reusable element groups (see [Reusable Elements](#reusable-elements)). |
112
- | `audio` | array | no | Global audio tracks spanning the whole video. |
114
+ | Key | Type | Required | Description |
115
+ |-----------|--------|----------|-------------|
116
+ | `output` | object | no | Output settings. Defaults: `1920×1080`, `30` fps, `mp4`. |
117
+ | `scenes` | array | yes | Ordered list of scenes, played back to back. |
118
+ | `defs` | object | no | Named, reusable element groups (see [Reusable Elements](#reusable-elements)). |
119
+ | `include` | array | no | Paths of JSON files whose `defs` are merged in (see [Shared def libraries](#shared-def-libraries)). |
120
+ | `audio` | array | no | Global audio tracks spanning the whole video. |
113
121
 
114
122
  #### `output`
115
123
 
@@ -170,13 +178,50 @@ All element types share these keys:
170
178
 
171
179
  | Key | Type | Default | Description |
172
180
  |--------------|---------------|----------------|-------------|
173
- | `type` | string | — | `text`, `video`, `image`, `shape`, or `ref` (see [Reusable Elements](#reusable-elements)). |
181
+ | `type` | string | — | `text`, `video`, `image`, `shape`, `code`, `group`, or `ref` (see [Reusable Elements](#reusable-elements)). |
174
182
  | `start` | number | `0` | Seconds into the scene when the element appears. |
175
183
  | `end` | number | scene duration | Seconds into the scene when the element disappears. |
176
- | `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. |
184
+ | `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. |
185
+ | `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. |
177
186
  | `opacity` | number | `1.0` | `0.0`–`1.0`. |
187
+ | `shadow` | object | none | Drop shadow (see [Shadows](#shadows)). Not on `video` elements. |
178
188
  | `animations` | array | `[]` | Keyframed property animations (see [Animations](#animations)). |
179
189
 
190
+ Pixel dimensions (`width`, `height`, `size`, `radius`, `max_width`) accept any
191
+ number; fractional values are rounded, so computed layouts can pass floats.
192
+
193
+ #### Anchors
194
+
195
+ By default an explicit `{x, y}` position locates the element's **center**.
196
+ `anchor` changes which point it locates instead: `top-left`, `top`,
197
+ `top-right`, `left`, `right`, `bottom-left`, `bottom`, `bottom-right`, or
198
+ `center`. Named string positions (`"top-left"` etc.) already place the whole
199
+ box against the frame and ignore `anchor`.
200
+
201
+ For `text` elements, anchors are **font-metric based** so that different
202
+ strings line up consistently: `left`/`right` anchor the pen origin and
203
+ advance width (not the inked pixels), `top` anchors the ascender line, and
204
+ the additional `baseline-left`, `baseline`, and `baseline-right` anchors sit
205
+ on the first line's baseline. Anchoring text `top-left` or `baseline-left`
206
+ is the reliable way to build precise layouts (columns of text, labels that
207
+ change content) without measuring fonts yourself.
208
+
209
+ #### Shadows
210
+
211
+ `text`, `image`, `shape`, `code`, and `group` elements take an optional
212
+ drop shadow:
213
+
214
+ ```json
215
+ { "shadow": { "blur": 24, "color": "#000000", "opacity": 0.6, "offset": { "x": 0, "y": 8 } } }
216
+ ```
217
+
218
+ | Key | Type | Default | Description |
219
+ |-----------|--------|-------------|-------------|
220
+ | `blur` | number | `8` | Gaussian blur radius in pixels. |
221
+ | `color` | string | `"#000000"` | Shadow color. |
222
+ | `opacity` | number | `0.5` | Shadow strength, `0.0`–`1.0`. |
223
+ | `offset` | object | `{0, 0}` | Shadow displacement in pixels. |
224
+
180
225
  #### `text`
181
226
 
182
227
  ```json
@@ -198,10 +243,15 @@ All element types share these keys:
198
243
  |-------------|--------|----------------|-------------|
199
244
  | `content` | string | — | The text to display. Supports `\n` for manual line breaks. |
200
245
  | `font` | string | bundled default | Path to a `.ttf`/`.otf` file. |
201
- | `size` | int | `48` | Font size in pixels. |
246
+ | `size` | number | `48` | Font size in pixels. |
202
247
  | `color` | string | `"#ffffff"` | Hex color. |
203
248
  | `align` | string | `"center"` | `left`, `center`, or `right` (for multi-line text). |
204
- | `max_width` | int | frame width | Wrap text to fit this pixel width. |
249
+ | `max_width` | number | frame width | Wrap text to fit this pixel width. |
250
+ | `wrap` | bool | `true` | Set `false` to disable wrapping entirely (`\n` still breaks lines). |
251
+
252
+ Wrapping breaks lines between words and preserves indentation and interior
253
+ runs of spaces. Text content can also change over time via a `content`
254
+ animation (see [Animations](#animations)).
205
255
 
206
256
  #### `video`
207
257
 
@@ -260,11 +310,98 @@ If the trimmed clip is shorter than its element window, it holds its last frame;
260
310
  | Key | Type | Default | Description |
261
311
  |----------------|--------|---------|-------------|
262
312
  | `shape` | string | — | `rect`, `ellipse`, or `line`. |
263
- | `width`/`height` | int | — | Dimensions in pixels (`line` uses `x2`/`y2` endpoints instead). |
313
+ | `width`/`height` | number | — | Dimensions in pixels (`line` uses `x2`/`y2` endpoints instead). |
264
314
  | `fill` | string | none | Fill color. |
265
315
  | `stroke` | string | none | Stroke color. |
266
316
  | `stroke_width` | int | `1` | Stroke thickness in pixels. |
267
- | `radius` | int | `0` | Corner radius for `rect`. |
317
+ | `radius` | number | `0` | Corner radius for `rect`. |
318
+
319
+ #### `code`
320
+
321
+ A block of syntax-highlighted code, laid out on a fixed line grid with
322
+ optional line numbers — and optionally revealed over time, typed character
323
+ by character with a cursor, as if someone were writing it live. Built for
324
+ coding-tutorial videos: put a `code` element over a mock editor window (see
325
+ [Reusable Elements](#reusable-elements)) and the code types itself in.
326
+
327
+ ```json
328
+ {
329
+ "type": "code",
330
+ "content": "def greet(name: str) -> str:\n return f\"Hi, {name}\"\n",
331
+ "language": "python",
332
+ "theme": "dark-plus",
333
+ "font": "assets/fonts/JetBrainsMono-Regular.ttf",
334
+ "size": 28,
335
+ "line_numbers": true,
336
+ "position": { "x": 200, "y": 170 },
337
+ "reveal": { "mode": "typing", "cps": 28, "line_pause": 0.3 }
338
+ }
339
+ ```
340
+
341
+ | Key | Type | Default | Description |
342
+ |----------------|--------|---------------|-------------|
343
+ | `content` | string | — | The code. Tabs expand to `tab_width` spaces; indentation is preserved exactly. |
344
+ | `language` | string | `"python"` | Any [pygments lexer name](https://pygments.org/languages/), or `"none"` for monochrome text (no pygments needed). |
345
+ | `theme` | string | `"dark-plus"` | `dark-plus`, `monokai`, or `github-light`. |
346
+ | `font` | string | — | Path to a monospace `.ttf`/`.otf`. Required. |
347
+ | `size` | number | `28` | Font size in pixels. |
348
+ | `line_height` | number | `size × 1.5` | Vertical distance between line tops. |
349
+ | `line_numbers` | bool | `false` | Draw a right-aligned line-number gutter. |
350
+ | `tab_width` | int | `4` | Spaces per tab. |
351
+ | `reveal` | object | none | Animate the code in (below). Omit for a static block. |
352
+
353
+ The block's `anchor` defaults to `top-left`, so `position` is the top-left
354
+ corner of the first line — matching how you think about an editor's text
355
+ area. Highlighting needs the `code` extra (`pip install "scenescript[code]"`).
356
+
357
+ ##### `reveal`
358
+
359
+ | Key | Type | Default | Description |
360
+ |--------------|--------|-----------|-------------|
361
+ | `mode` | string | `"typing"`| `typing` (character by character) or `lines` (line by line). |
362
+ | `cps` | number | `30` | Typing speed, characters per second (`typing`). |
363
+ | `line_pause` | number | `0.3` | Extra pause after each line break (`typing`). |
364
+ | `interval` | number | `0.5` | Seconds between lines (`lines`). |
365
+ | `delay` | number | `0` | Seconds after the element starts before the reveal begins. |
366
+ | `cursor` | bool | mode is `typing` | Draw an insertion-point cursor at the reveal position. |
367
+ | `blink` | bool | `true` | Blink the cursor once the reveal finishes. |
368
+
369
+ Times are on the element's own clock (they start at `start`). Validation
370
+ fails if the reveal takes longer than the element's window, so a too-short
371
+ scene is caught before rendering.
372
+
373
+ #### `group`
374
+
375
+ A container that renders its child elements onto its own canvas, then
376
+ places, animates, and fades that canvas as a single element. Children use
377
+ the group's coordinate space (positions relative to the group's top-left,
378
+ named positions relative to the group's box), run on the group's clock
379
+ (`start`/`end` relative to the group's `start`), and are **clipped** to the
380
+ group's `width` × `height`.
381
+
382
+ ```json
383
+ {
384
+ "type": "group",
385
+ "width": 800,
386
+ "height": 400,
387
+ "position": { "x": 960, "y": 540 },
388
+ "elements": [
389
+ { "type": "shape", "shape": "rect", "width": 800, "height": 400, "fill": "#1e1e1e", "position": { "x": 400, "y": 200 } },
390
+ { "type": "text", "content": "inside the panel", "position": { "x": 400, "y": 200 } }
391
+ ]
392
+ }
393
+ ```
394
+
395
+ | Key | Type | Default | Description |
396
+ |------------------|--------|----------|-------------|
397
+ | `width`/`height` | number | — | The group's canvas size in pixels. Children are clipped to it. |
398
+ | `scale` | number | `1.0` | Uniform scale applied to the rendered canvas. |
399
+ | `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). |
400
+ | `elements` | array | `[]` | Child elements, drawn in document order. Refs work here too. |
401
+
402
+ Groups make composites move as one: scale a whole mock window down,
403
+ slide a panel in, fade an entire overlay — and their clipping is what makes
404
+ scrolling viewports possible (animate `content_offset`).
268
405
 
269
406
  ### Reusable Elements
270
407
 
@@ -295,12 +432,65 @@ Define a group of elements once under the top-level `defs` key, then insert it a
295
432
  |----------|--------|----------|-------------|
296
433
  | `name` | string | yes | The def to insert. |
297
434
  | `offset` | object | no | `{ "x": dx, "y": dy }` added to every inserted element's position (after named anchors resolve). Defaults to no shift. |
435
+ | `params` | object | no | Values for a parameterized def's placeholders (below). |
298
436
 
299
437
  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.
300
438
 
439
+ #### Parameterized defs
440
+
441
+ A def can declare parameters with default values by using the object form —
442
+ `{ "params": { defaults }, "elements": [ ... ] }` — and referencing them as
443
+ `{name}` placeholders in any string:
444
+
445
+ ```json
446
+ {
447
+ "defs": {
448
+ "editor_tab": {
449
+ "params": { "filename": "untitled", "width": 200 },
450
+ "elements": [
451
+ { "type": "shape", "shape": "rect", "width": "{width}", "height": 40, "fill": "#1e1e1e", "position": { "x": 100, "y": 20 } },
452
+ { "type": "text", "content": "{filename}", "size": 22, "position": { "x": 100, "y": 20 } }
453
+ ]
454
+ }
455
+ },
456
+ "scenes": [
457
+ {
458
+ "duration": 4,
459
+ "elements": [
460
+ { "type": "ref", "name": "editor_tab", "params": { "filename": "app.py" } }
461
+ ]
462
+ }
463
+ ]
464
+ }
465
+ ```
466
+
467
+ A string that is exactly one placeholder (`"{width}"`) takes the parameter's
468
+ own type, so numbers can parameterize dimensions and positions. Placeholders
469
+ are spliced into longer strings as text. Only declared parameters substitute
470
+ — other braces (dict literals in code content, say) pass through untouched —
471
+ and passing an undeclared parameter is a validation error, so typos are
472
+ caught. A ref that omits `params` uses the declared defaults.
473
+
474
+ #### Shared def libraries
475
+
476
+ The top-level `include` key merges `defs` from other JSON files, so one IDE
477
+ mock, lower third, or brand kit can serve many videos:
478
+
479
+ ```json
480
+ { "include": ["../shared/ide.defs.json"], "scenes": [ ... ] }
481
+ ```
482
+
483
+ An included file is a JSON object with a single `defs` object. Asset paths
484
+ inside it resolve against **that file's** directory (a def library carries
485
+ its own fonts and images no matter who includes it). Names must be unique
486
+ across the document and everything it includes — a collision is a validation
487
+ error, not a silent override. Included files cannot themselves include.
488
+ Problems inside an included def are reported with the file prefixed:
489
+ `ide.defs.json:defs.ide[2].size: ...`.
490
+
301
491
  ### Animations
302
492
 
303
- 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.
493
+ 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.
304
494
 
305
495
  ```json
306
496
  {
@@ -329,12 +519,29 @@ Any element can animate `position`, `opacity`, `scale`, `scale_x`, or `scale_y`
329
519
 
330
520
  | Key | Type | Description |
331
521
  |------------|--------|-------------|
332
- | `property` | string | `position`, `opacity`, `scale`, `scale_x`, or `scale_y`. |
522
+ | `property` | string | `position`, `opacity`, `scale`, `scale_x`, `scale_y`, `content` (text only), or `content_offset` (groups only). |
333
523
  | `keyframes`| array | Two or more `{ time, value, easing }` points. |
334
- | `easing` | string | Interpolation *out of* this keyframe: `linear` (default), `ease_in`, `ease_out`, `ease_in_out`. |
524
+ | `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). |
525
+ | `repeat` | int | Play the keyframe cycle this many times before the final value holds. Default `1`. |
526
+ | `loop` | bool | Repeat the cycle for as long as the element is visible. Mutually exclusive with `repeat`. |
335
527
 
336
528
  `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.
337
529
 
530
+ `step` easing plus `loop` covers everything that used to need long hand-built
531
+ keyframe lists — a blinking cursor is three keyframes:
532
+
533
+ ```json
534
+ {
535
+ "property": "opacity",
536
+ "loop": true,
537
+ "keyframes": [
538
+ { "time": 0.0, "value": 1.0, "easing": "step" },
539
+ { "time": 0.53, "value": 0.0, "easing": "step" },
540
+ { "time": 1.06, "value": 1.0 }
541
+ ]
542
+ }
543
+ ```
544
+
338
545
  A slow position/scale drift on an image gives you the Ken Burns effect:
339
546
 
340
547
  ```json
@@ -0,0 +1,34 @@
1
+ # 0008 — Parameterized defs declare their params, with default values
2
+
3
+ Status: accepted — 2026-08-26
4
+
5
+ ## Context
6
+
7
+ Defs gained `{name}` placeholder substitution so one composite (a mock IDE
8
+ window, a lower third) can be reused with different content. The first design
9
+ let any ref pass arbitrary `params` against a plain element array. That
10
+ collided with an existing guarantee from ADR-0007: every def is resolved and
11
+ validated up front, used or not. A placeholder sitting in a non-string slot
12
+ (`"width": "{w}"`) cannot parse without a value, so an unused parameterized
13
+ def would fail validation — and silently accepting unknown placeholder names
14
+ would let typos through at ref sites.
15
+
16
+ ## Decision
17
+
18
+ A parameterized def uses an object form and declares defaults:
19
+ `{ "params": { "w": 250 }, "elements": [ ... ] }`. Up-front resolution
20
+ substitutes the defaults, so the def validates whether or not it is used and
21
+ plain refs get the defaults. A ref's `params` may override any declared
22
+ subset; passing an undeclared name is a validation error naming what the def
23
+ declares. A string that is exactly one placeholder takes the parameter's own
24
+ JSON type; otherwise placeholders splice into strings as text, and undeclared
25
+ braces (dict literals in code content) pass through untouched. Parameterized
26
+ refs re-parse the def's raw JSON, so their problems point at the ref site.
27
+
28
+ ## Consequences
29
+
30
+ - "Unused defs are still validated" survives; defaults double as
31
+ documentation of what a def expects.
32
+ - Typos in param names fail validation instead of rendering "{fielname}".
33
+ - Each parameterized ref re-parses its def (plain refs still deep-copy the
34
+ cached parse); defs are small, so the cost is negligible.