scenescript 0.3.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 (236) hide show
  1. {scenescript-0.3.0 → scenescript-0.4.0}/PKG-INFO +27 -6
  2. {scenescript-0.3.0 → scenescript-0.4.0}/README.md +26 -5
  3. {scenescript-0.3.0 → scenescript-0.4.0}/pyproject.toml +1 -1
  4. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/__init__.py +1 -1
  5. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/cli.py +47 -1
  6. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/mcp_server.py +72 -7
  7. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/renderer.py +26 -0
  8. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/timeline.py +12 -0
  9. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_cli.py +70 -2
  10. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_mcp_server.py +74 -2
  11. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_render.py +32 -1
  12. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_timeline.py +27 -0
  13. {scenescript-0.3.0 → scenescript-0.4.0}/uv.lock +1 -1
  14. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/agents/copy-writer.md +0 -0
  15. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/agents/product-owner.md +0 -0
  16. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/agents/qa-tester.md +0 -0
  17. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/agents/software-architect.md +0 -0
  18. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/agents/software-engineer.md +0 -0
  19. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/agents/ui-ux-specialist.md +0 -0
  20. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/README.md +0 -0
  21. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/accessibility-standard.md +0 -0
  22. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/adr-index.md +0 -0
  23. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/ci-pipeline.md +0 -0
  24. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/competitor-positioning.md +0 -0
  25. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/design-tokens.md +0 -0
  26. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/device-matrix.md +0 -0
  27. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/domain-glossary.md +0 -0
  28. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/environment-map.md +0 -0
  29. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/grounding-rules.md +0 -0
  30. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/known-debt.md +0 -0
  31. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/known-issues.md +0 -0
  32. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/local-dev-setup.md +0 -0
  33. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/nfr-targets.md +0 -0
  34. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/observability-map.md +0 -0
  35. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/personas.md +0 -0
  36. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/research-repository.md +0 -0
  37. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/severity-ladder.md +0 -0
  38. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/system-map.md +0 -0
  39. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/tech-radar.md +0 -0
  40. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/test-data-catalog.md +0 -0
  41. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/ui-string-catalog.md +0 -0
  42. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/context/voice-guide.md +0 -0
  43. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/analyzing-trade-offs/SKILL.md +0 -0
  44. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/analyzing-trade-offs/references/worked-example.md +0 -0
  45. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/applying-design-system-conventions/SKILL.md +0 -0
  46. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/applying-design-system-conventions/references/drift-catalogue.md +0 -0
  47. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/applying-design-system-conventions/references/worked-resolution.md +0 -0
  48. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/auditing-accessibility/SKILL.md +0 -0
  49. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/auditing-accessibility/references/audit-checklist.md +0 -0
  50. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/auditing-accessibility/references/finding-template.md +0 -0
  51. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/auditing-accessibility/references/state-audit.md +0 -0
  52. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/automating-tests/SKILL.md +0 -0
  53. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/automating-tests/references/adversarial-cases.md +0 -0
  54. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/automating-tests/references/flake-cures.md +0 -0
  55. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/automating-tests/references/test-note.md +0 -0
  56. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/critiquing-with-heuristics/SKILL.md +0 -0
  57. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/critiquing-with-heuristics/references/heuristics.md +0 -0
  58. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/critiquing-with-heuristics/references/worked-example.md +0 -0
  59. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/debugging-and-incidents/SKILL.md +0 -0
  60. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/debugging-and-incidents/references/records.md +0 -0
  61. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/defining-voice-and-style/SKILL.md +0 -0
  62. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/defining-voice-and-style/references/worked-guide.md +0 -0
  63. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/designing-tests-from-acceptance-criteria/SKILL.md +0 -0
  64. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/designing-tests-from-acceptance-criteria/references/adversarial-catalogue.md +0 -0
  65. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/designing-tests-from-acceptance-criteria/references/worked-example.md +0 -0
  66. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/documenting-flows-and-ia/SKILL.md +0 -0
  67. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/documenting-flows-and-ia/references/branch-checklist.md +0 -0
  68. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/documenting-flows-and-ia/references/worked-flow.md +0 -0
  69. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/documenting-systems/SKILL.md +0 -0
  70. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/documenting-systems/references/evidence-ladder.md +0 -0
  71. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/documenting-systems/references/worked-diagram.md +0 -0
  72. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/drafting-from-a-brief/SKILL.md +0 -0
  73. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/drafting-from-a-brief/references/worked-brief.md +0 -0
  74. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/editing-copy/SKILL.md +0 -0
  75. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/editing-copy/references/deliverables.md +0 -0
  76. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/enforcing-terminology/SKILL.md +0 -0
  77. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/enforcing-terminology/references/deliverable.md +0 -0
  78. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/enforcing-terminology/references/sweep-recipe.md +0 -0
  79. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/enumerating-ui-states/SKILL.md +0 -0
  80. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/enumerating-ui-states/references/inventory-template.md +0 -0
  81. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/enumerating-ui-states/references/state-axes.md +0 -0
  82. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/managing-test-data/SKILL.md +0 -0
  83. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/managing-test-data/references/hostile-fixtures.md +0 -0
  84. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/managing-test-data/references/provisioning-routes.md +0 -0
  85. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/planning-implementation/SKILL.md +0 -0
  86. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/planning-implementation/references/worked-plan.md +0 -0
  87. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/planning-migrations/SKILL.md +0 -0
  88. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/planning-migrations/references/expand-contract.md +0 -0
  89. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/planning-migrations/references/worked-plan.md +0 -0
  90. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/planning-usability-tests/SKILL.md +0 -0
  91. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/planning-usability-tests/references/plan-template.md +0 -0
  92. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/planning-usability-tests/references/task-wording.md +0 -0
  93. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/prioritizing-work/SKILL.md +0 -0
  94. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/prioritizing-work/references/cost-of-delay.md +0 -0
  95. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/prioritizing-work/references/frameworks.md +0 -0
  96. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/prioritizing-work/references/worked-example.md +0 -0
  97. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/probing-non-functional-behavior/SKILL.md +0 -0
  98. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/probing-non-functional-behavior/references/adversarial-probes.md +0 -0
  99. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/probing-non-functional-behavior/references/probe-types.md +0 -0
  100. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/probing-non-functional-behavior/references/worked-probe.md +0 -0
  101. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/refactoring/SKILL.md +0 -0
  102. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/refactoring/references/characterization-tests.md +0 -0
  103. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/refactoring/references/mechanical-moves.md +0 -0
  104. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/refining-the-backlog/SKILL.md +0 -0
  105. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/refining-the-backlog/references/split-axes.md +0 -0
  106. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/removing-ai-tells/SKILL.md +0 -0
  107. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/removing-ai-tells/references/catalogue.md +0 -0
  108. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reporting-defects/SKILL.md +0 -0
  109. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reporting-defects/references/report-template.md +0 -0
  110. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reporting-defects/references/worked-examples.md +0 -0
  111. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-code/SKILL.md +0 -0
  112. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-code/references/correctness-probes.md +0 -0
  113. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-code/references/worked-review.md +0 -0
  114. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-design-against-nfrs/SKILL.md +0 -0
  115. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-design-against-nfrs/references/quality-checklist.md +0 -0
  116. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-design-against-nfrs/references/worked-review.md +0 -0
  117. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-for-acceptance/SKILL.md +0 -0
  118. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-for-acceptance/references/acceptance-record.md +0 -0
  119. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-tests/SKILL.md +0 -0
  120. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-tests/references/mutation-catalogue.md +0 -0
  121. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-tests/references/tests-that-cannot-fail.md +0 -0
  122. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/reviewing-tests/references/worked-review.md +0 -0
  123. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/running-design-qa/SKILL.md +0 -0
  124. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/running-design-qa/references/check-matrix.md +0 -0
  125. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/running-design-qa/references/output-template.md +0 -0
  126. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/running-spikes/SKILL.md +0 -0
  127. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/running-spikes/references/spike-note.md +0 -0
  128. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/scoping-regression-tests/SKILL.md +0 -0
  129. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/scoping-regression-tests/references/reach-checklist.md +0 -0
  130. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/scoping-regression-tests/references/scope-note.md +0 -0
  131. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/specifying-interactions/SKILL.md +0 -0
  132. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/specifying-interactions/references/adversarial-read.md +0 -0
  133. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/specifying-interactions/references/spec-template.md +0 -0
  134. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/synthesizing-research/SKILL.md +0 -0
  135. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/synthesizing-research/references/no-research-yet.md +0 -0
  136. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/synthesizing-research/references/worked-synthesis.md +0 -0
  137. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/tdd-workflow/SKILL.md +0 -0
  138. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/tdd-workflow/references/reading-red.md +0 -0
  139. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/tdd-workflow/references/worked-cycle.md +0 -0
  140. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/SKILL.md +0 -0
  141. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/references/adversarial-conditions.md +0 -0
  142. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/references/finding-template.md +0 -0
  143. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/references/keyboard-pass.md +0 -0
  144. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/testing-accessibility/references/screen-reader-pass.md +0 -0
  145. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/testing-apis-and-contracts/SKILL.md +0 -0
  146. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/testing-apis-and-contracts/references/adversarial-catalogue.md +0 -0
  147. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/testing-apis-and-contracts/references/compatibility-matrix.md +0 -0
  148. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/triaging-bugs/SKILL.md +0 -0
  149. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/triaging-bugs/references/severity-and-priority.md +0 -0
  150. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/triaging-requests/SKILL.md +0 -0
  151. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/triaging-requests/references/triage-note.md +0 -0
  152. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/upgrading-dependencies/SKILL.md +0 -0
  153. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/upgrading-dependencies/references/silent-changes.md +0 -0
  154. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/upgrading-dependencies/references/upgrade-note.md +0 -0
  155. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/verifying-done/SKILL.md +0 -0
  156. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/verifying-done/references/completion-report.md +0 -0
  157. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/verifying-done/references/rationalizations.md +0 -0
  158. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/verifying-done/references/scaling-the-check.md +0 -0
  159. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-adrs/SKILL.md +0 -0
  160. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-adrs/references/adr-template.md +0 -0
  161. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-adrs/references/worked-adr.md +0 -0
  162. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-documentation/SKILL.md +0 -0
  163. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-documentation/references/page-shapes.md +0 -0
  164. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-documentation/references/worked-example.md +0 -0
  165. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-exploratory-charters/SKILL.md +0 -0
  166. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-exploratory-charters/references/lens-catalogue.md +0 -0
  167. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-exploratory-charters/references/session-record.md +0 -0
  168. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-marketing-copy/SKILL.md +0 -0
  169. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-marketing-copy/references/awareness-and-formats.md +0 -0
  170. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-marketing-copy/references/worked-examples.md +0 -0
  171. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-microcopy-in-context/SKILL.md +0 -0
  172. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-microcopy-in-context/references/content-set.md +0 -0
  173. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-microcopy-in-context/references/worked-review.md +0 -0
  174. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-plain-language/SKILL.md +0 -0
  175. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-plain-language/references/text-accessibility-checks.md +0 -0
  176. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-plain-language/references/worked-example.md +0 -0
  177. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-seo-metadata/SKILL.md +0 -0
  178. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-seo-metadata/references/surfaces.md +0 -0
  179. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-ui-copy/SKILL.md +0 -0
  180. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-ui-copy/references/constraints-and-variables.md +0 -0
  181. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-ui-copy/references/string-types.md +0 -0
  182. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-user-stories/SKILL.md +0 -0
  183. {scenescript-0.3.0 → scenescript-0.4.0}/.claude/skills/writing-user-stories/references/worked-example.md +0 -0
  184. {scenescript-0.3.0 → scenescript-0.4.0}/.gitignore +0 -0
  185. {scenescript-0.3.0 → scenescript-0.4.0}/LICENSE +0 -0
  186. {scenescript-0.3.0 → scenescript-0.4.0}/docs/adr/0001-pillow-numpy-composition-ffmpeg-at-boundaries.md +0 -0
  187. {scenescript-0.3.0 → scenescript-0.4.0}/docs/adr/0002-transition-timeline-model.md +0 -0
  188. {scenescript-0.3.0 → scenescript-0.4.0}/docs/adr/0003-single-ffmpeg-process-for-encode-and-audio.md +0 -0
  189. {scenescript-0.3.0 → scenescript-0.4.0}/docs/adr/0004-hand-written-validation.md +0 -0
  190. {scenescript-0.3.0 → scenescript-0.4.0}/docs/adr/0005-pillow-embedded-default-font.md +0 -0
  191. {scenescript-0.3.0 → scenescript-0.4.0}/docs/adr/0006-mcp-server-as-optional-extra.md +0 -0
  192. {scenescript-0.3.0 → scenescript-0.4.0}/docs/adr/0007-reusable-elements-expand-at-parse-time.md +0 -0
  193. {scenescript-0.3.0 → scenescript-0.4.0}/docs/adr/0008-declared-def-params-with-defaults.md +0 -0
  194. {scenescript-0.3.0 → scenescript-0.4.0}/docs/fake-ide-feature-notes.md +0 -0
  195. {scenescript-0.3.0 → scenescript-0.4.0}/examples/fake-ide/README.md +0 -0
  196. {scenescript-0.3.0 → scenescript-0.4.0}/examples/fake-ide/ide.defs.json +0 -0
  197. {scenescript-0.3.0 → scenescript-0.4.0}/examples/fake-ide/tutorial.json +0 -0
  198. {scenescript-0.3.0 → scenescript-0.4.0}/examples/fake-ide/tutorial.mp4 +0 -0
  199. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/animation.py +0 -0
  200. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/audio.py +0 -0
  201. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/backgrounds.py +0 -0
  202. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/codeblocks.py +0 -0
  203. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/codethemes.py +0 -0
  204. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/colors.py +0 -0
  205. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/easing.py +0 -0
  206. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/encoder.py +0 -0
  207. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/errors.py +0 -0
  208. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/geometry.py +0 -0
  209. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/probe.py +0 -0
  210. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/progress.py +0 -0
  211. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/scenes.py +0 -0
  212. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/spec.py +0 -0
  213. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/sprites.py +0 -0
  214. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/transitions.py +0 -0
  215. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/validation.py +0 -0
  216. {scenescript-0.3.0 → scenescript-0.4.0}/src/scenescript/videoreader.py +0 -0
  217. {scenescript-0.3.0 → scenescript-0.4.0}/tests/__init__.py +0 -0
  218. {scenescript-0.3.0 → scenescript-0.4.0}/tests/conftest.py +0 -0
  219. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_animation.py +0 -0
  220. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_audio.py +0 -0
  221. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_backgrounds.py +0 -0
  222. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_code.py +0 -0
  223. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_colors.py +0 -0
  224. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_defs.py +0 -0
  225. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_easing.py +0 -0
  226. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_geometry.py +0 -0
  227. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_groups.py +0 -0
  228. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_includes.py +0 -0
  229. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_probe.py +0 -0
  230. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_scenes.py +0 -0
  231. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_spec.py +0 -0
  232. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_spec_features.py +0 -0
  233. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_sprites.py +0 -0
  234. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_transitions.py +0 -0
  235. {scenescript-0.3.0 → scenescript-0.4.0}/tests/test_validation.py +0 -0
  236. {scenescript-0.3.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.3.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>
@@ -70,10 +70,11 @@ pip install "scenescript[code]"
70
70
  pip install --upgrade scenescript
71
71
  ```
72
72
 
73
- 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:
74
75
 
75
76
  ```bash
76
- pip install --upgrade "scenescript[mcp]"
77
+ pip install --upgrade "scenescript[mcp,code]"
77
78
  ```
78
79
 
79
80
  ### Installing from source
@@ -83,7 +84,7 @@ To work on SceneScript itself, install editable from a clone — the executables
83
84
  ```bash
84
85
  git clone https://github.com/CtrlAltDeplete/scenescript
85
86
  cd scenescript
86
- pip install -e ".[mcp]"
87
+ pip install -e ".[mcp,code]"
87
88
  ```
88
89
 
89
90
  ## Quick Start
@@ -940,6 +941,22 @@ scenescript render <input.json> -o <output>
940
941
  | `--overwrite` | Replace the output file if it already exists. |
941
942
  | `-q, --quiet` | Suppress the progress display. |
942
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
+
943
960
  ### `scenescript validate`
944
961
 
945
962
  Check a JSON file without rendering: schema correctness, asset paths, timing sanity (elements within scene bounds, transitions not longer than their scenes).
@@ -955,10 +972,13 @@ Exits non-zero with a list of problems, or prints a summary of the video (scene
955
972
  SceneScript ships an optional [MCP](https://modelcontextprotocol.io) server so AI agents can author and render videos through tool calls.
956
973
 
957
974
  ```bash
958
- pip install "scenescript[mcp]"
975
+ pip install "scenescript[mcp,code]"
959
976
  scenescript-mcp
960
977
  ```
961
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
+
962
982
  The server speaks stdio. To register it with Claude Code:
963
983
 
964
984
  ```bash
@@ -967,13 +987,14 @@ claude mcp add scenescript -- scenescript-mcp
967
987
 
968
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.
969
989
 
970
- Three tools:
990
+ Four tools:
971
991
 
972
992
  | Tool | What it does |
973
993
  |---|---|
974
994
  | `get_format_reference` | Returns this document, so an agent can learn the JSON format before authoring a spec. |
975
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). |
976
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. |
977
998
 
978
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.
979
1000
 
@@ -48,10 +48,11 @@ pip install "scenescript[code]"
48
48
  pip install --upgrade scenescript
49
49
  ```
50
50
 
51
- If you use the MCP server, include the extra so its dependencies are upgraded too:
51
+ If you use extras (the MCP server, `code` highlighting), include them so
52
+ their dependencies are upgraded too:
52
53
 
53
54
  ```bash
54
- pip install --upgrade "scenescript[mcp]"
55
+ pip install --upgrade "scenescript[mcp,code]"
55
56
  ```
56
57
 
57
58
  ### Installing from source
@@ -61,7 +62,7 @@ To work on SceneScript itself, install editable from a clone — the executables
61
62
  ```bash
62
63
  git clone https://github.com/CtrlAltDeplete/scenescript
63
64
  cd scenescript
64
- pip install -e ".[mcp]"
65
+ pip install -e ".[mcp,code]"
65
66
  ```
66
67
 
67
68
  ## Quick Start
@@ -918,6 +919,22 @@ scenescript render <input.json> -o <output>
918
919
  | `--overwrite` | Replace the output file if it already exists. |
919
920
  | `-q, --quiet` | Suppress the progress display. |
920
921
 
922
+ ### `scenescript frames`
923
+
924
+ Render single frames to PNGs for spot-checking a spec without a full render.
925
+
926
+ ```bash
927
+ scenescript frames <input.json> -o <directory> --at 3.5 --frame 105
928
+ ```
929
+
930
+ | Option | Description |
931
+ |----------------|-------------|
932
+ | `-o, --output DIR` | Directory for the PNGs (created if missing; existing frames are replaced). |
933
+ | `--at SECONDS` | Render the frame at this time. Repeatable. |
934
+ | `--frame N` | Render this frame number. Repeatable. |
935
+
936
+ Frames are written as `frame_<number>.png` (zero-padded) and each path is printed. Transition frames blend exactly as a full render would.
937
+
921
938
  ### `scenescript validate`
922
939
 
923
940
  Check a JSON file without rendering: schema correctness, asset paths, timing sanity (elements within scene bounds, transitions not longer than their scenes).
@@ -933,10 +950,13 @@ Exits non-zero with a list of problems, or prints a summary of the video (scene
933
950
  SceneScript ships an optional [MCP](https://modelcontextprotocol.io) server so AI agents can author and render videos through tool calls.
934
951
 
935
952
  ```bash
936
- pip install "scenescript[mcp]"
953
+ pip install "scenescript[mcp,code]"
937
954
  scenescript-mcp
938
955
  ```
939
956
 
957
+ (The `code` extra is optional but recommended: it lets agents use
958
+ syntax-highlighted [`code` elements](#code) without a follow-up install.)
959
+
940
960
  The server speaks stdio. To register it with Claude Code:
941
961
 
942
962
  ```bash
@@ -945,13 +965,14 @@ claude mcp add scenescript -- scenescript-mcp
945
965
 
946
966
  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.
947
967
 
948
- Three tools:
968
+ Four tools:
949
969
 
950
970
  | Tool | What it does |
951
971
  |---|---|
952
972
  | `get_format_reference` | Returns this document, so an agent can learn the JSON format before authoring a spec. |
953
973
  | `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). |
954
974
  | `render_video` | Renders a spec to `output_path`. The extension picks the container; an existing file is only replaced when `overwrite` is true. |
975
+ | `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. |
955
976
 
956
977
  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.
957
978
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "scenescript"
3
- version = "0.3.0"
3
+ version = "0.4.0"
4
4
  description = "Render complete videos from declarative JSON files"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,3 +1,3 @@
1
1
  """SceneScript: render complete videos from declarative JSON files."""
2
2
 
3
- __version__ = "0.2.0"
3
+ __version__ = "0.4.0"
@@ -13,8 +13,9 @@ from pathlib import Path
13
13
 
14
14
  from .errors import RenderError, SpecError
15
15
  from .progress import ProgressPrinter
16
- from .renderer import render_video
16
+ from .renderer import render_frames, render_video
17
17
  from .spec import FORMATS, load_spec
18
+ from .timeline import Timeline
18
19
  from .validation import ValidationResult, validate_spec
19
20
 
20
21
 
@@ -98,6 +99,39 @@ def _cmd_render(args: argparse.Namespace) -> int:
98
99
  return 0
99
100
 
100
101
 
102
+ def _cmd_frames(args: argparse.Namespace) -> int:
103
+ if shutil.which("ffmpeg") is None or shutil.which("ffprobe") is None:
104
+ _error("ffmpeg and ffprobe must be on PATH (see README.md Requirements)")
105
+ return 1
106
+ if not args.at and not args.frame:
107
+ _error("nothing to render: pass --at SECONDS and/or --frame N")
108
+ return 1
109
+
110
+ spec, result = _load_and_validate(args.input)
111
+ if spec is None:
112
+ return 1
113
+
114
+ timeline = Timeline(spec.scenes, spec.output.fps)
115
+ try:
116
+ frames = [timeline.frame_for_time(t) for t in args.at] + list(args.frame)
117
+ except ValueError as e:
118
+ _error(str(e))
119
+ return 1
120
+
121
+ outdir = Path(args.output)
122
+ outdir.mkdir(parents=True, exist_ok=True)
123
+ width = len(str(timeline.total_frames - 1))
124
+ try:
125
+ for f, image in render_frames(spec, result.media, frames):
126
+ path = outdir / f"frame_{f:0{width}d}.png"
127
+ image.save(path)
128
+ print(path)
129
+ except RenderError as e:
130
+ _error(str(e))
131
+ return 1
132
+ return 0
133
+
134
+
101
135
  def build_parser() -> argparse.ArgumentParser:
102
136
  parser = argparse.ArgumentParser(
103
137
  prog="scenescript",
@@ -115,6 +149,18 @@ def build_parser() -> argparse.ArgumentParser:
115
149
  help="suppress the progress display")
116
150
  render.set_defaults(func=_cmd_render)
117
151
 
152
+ frames = sub.add_parser(
153
+ "frames", help="render single frames to PNGs for spot-checking"
154
+ )
155
+ frames.add_argument("input", help="path to the video JSON file")
156
+ frames.add_argument("-o", "--output", required=True,
157
+ help="directory for the PNGs (created if missing)")
158
+ frames.add_argument("--at", metavar="SECONDS", type=float, action="append",
159
+ default=[], help="render the frame at this time (repeatable)")
160
+ frames.add_argument("--frame", metavar="N", type=int, action="append",
161
+ default=[], help="render this frame number (repeatable)")
162
+ frames.set_defaults(func=_cmd_frames)
163
+
118
164
  validate = sub.add_parser(
119
165
  "validate", help="check a JSON file without rendering"
120
166
  )
@@ -1,9 +1,10 @@
1
1
  """MCP server exposing SceneScript to AI agents (stdio transport).
2
2
 
3
- Three tools: get_format_reference (the JSON spec documentation),
4
- validate_video, and render_video. Validation problems come back as data so an
5
- agent can fix its spec and retry; unrecoverable conditions (invalid render
6
- input, existing output, missing ffmpeg) raise ToolError with the reason.
3
+ Four tools: get_format_reference (the JSON spec documentation),
4
+ validate_video, render_video, and render_frames (single-frame PNGs for spot
5
+ checks). Validation problems come back as data so an agent can fix its spec
6
+ and retry; unrecoverable conditions (invalid render input, existing output,
7
+ missing ffmpeg) raise ToolError with the reason.
7
8
 
8
9
  Requires the ``mcp`` extra: ``pip install "scenescript[mcp]"``. Run with
9
10
  ``scenescript-mcp``.
@@ -15,7 +16,11 @@ import shutil
15
16
  import sys
16
17
  from importlib import resources
17
18
  from pathlib import Path
18
- from typing import Any, TypedDict
19
+ from typing import Any
20
+
21
+ # pydantic (via the mcp extra) needs typing_extensions' TypedDict to build
22
+ # result schemas on Python 3.11
23
+ from typing_extensions import TypedDict
19
24
 
20
25
  try:
21
26
  from mcp.server.mcpserver import MCPServer
@@ -25,9 +30,11 @@ except ModuleNotFoundError as e: # pragma: no cover - exercised only sans extra
25
30
  "the MCP server needs the 'mcp' package; install scenescript[mcp]"
26
31
  ) from e
27
32
 
28
- from .errors import SpecError
33
+ from .errors import RenderError, SpecError
34
+ from .renderer import render_frames as _render_frames
29
35
  from .renderer import render_video as _render
30
36
  from .spec import FORMATS, VideoSpec, load_spec, parse_spec
37
+ from .timeline import Timeline
31
38
  from .validation import ValidationResult, validate_spec
32
39
 
33
40
  _INSTRUCTIONS = """\
@@ -36,7 +43,8 @@ Workflow: call get_format_reference once to learn the JSON format, author a
36
43
  spec, check it with validate_video (problems come back as data - fix and
37
44
  retry), then render_video. Asset paths in a spec are relative to assets_dir
38
45
  (or to the spec file's directory when spec_path is used). Rendering runs at
39
- roughly realtime speed for 1080p30."""
46
+ roughly realtime speed for 1080p30. To spot-check a spec without a full
47
+ render, render_frames writes single frames as PNGs you can read back."""
40
48
 
41
49
 
42
50
  class ValidateResult(TypedDict):
@@ -47,6 +55,16 @@ class ValidateResult(TypedDict):
47
55
  assets: list[str]
48
56
 
49
57
 
58
+ class FrameResult(TypedDict):
59
+ frame: int
60
+ time_seconds: float
61
+ path: str
62
+
63
+
64
+ class FramesResult(TypedDict):
65
+ frames: list[FrameResult]
66
+
67
+
50
68
  class RenderResult(TypedDict):
51
69
  output_path: str
52
70
  duration_seconds: float
@@ -162,6 +180,53 @@ def build_server() -> MCPServer:
162
180
  format=extension,
163
181
  )
164
182
 
183
+ @server.tool()
184
+ def render_frames(
185
+ output_dir: str,
186
+ spec: dict[str, Any] | None = None,
187
+ spec_path: str | None = None,
188
+ assets_dir: str | None = None,
189
+ times: list[float] | None = None,
190
+ frame_numbers: list[int] | None = None,
191
+ ) -> FramesResult:
192
+ """Render single frames as PNGs to spot-check a spec without a full
193
+ render. Pick frames by 'times' (seconds) and/or 'frame_numbers';
194
+ duplicates collapse. PNGs land in output_dir (created if missing,
195
+ existing frames replaced) and each result entry names the frame, its
196
+ timestamp, and the file to read back."""
197
+ if shutil.which("ffmpeg") is None or shutil.which("ffprobe") is None:
198
+ raise ToolError("ffmpeg and ffprobe must be on PATH to render")
199
+ if not times and not frame_numbers:
200
+ raise ToolError("pass 'times' (seconds) and/or 'frame_numbers'")
201
+
202
+ parsed, problems, result = _load(spec, spec_path, assets_dir)
203
+ if problems or parsed is None or result is None:
204
+ raise ToolError("the spec is invalid:\n" + "\n".join(problems))
205
+
206
+ timeline = Timeline(parsed.scenes, parsed.output.fps)
207
+ try:
208
+ wanted = [timeline.frame_for_time(t) for t in times or []]
209
+ except ValueError as e:
210
+ raise ToolError(str(e)) from e
211
+ wanted += frame_numbers or []
212
+
213
+ out = Path(output_dir)
214
+ out.mkdir(parents=True, exist_ok=True)
215
+ width = len(str(timeline.total_frames - 1))
216
+ entries: list[FrameResult] = []
217
+ try:
218
+ for f, image in _render_frames(parsed, result.media, wanted):
219
+ path = out / f"frame_{f:0{width}d}.png"
220
+ image.save(path)
221
+ entries.append(FrameResult(
222
+ frame=f,
223
+ time_seconds=(f + 0.5) / parsed.output.fps,
224
+ path=str(path),
225
+ ))
226
+ except RenderError as e:
227
+ raise ToolError(str(e)) from e
228
+ return FramesResult(frames=entries)
229
+
165
230
  return server
166
231
 
167
232
 
@@ -14,6 +14,7 @@ from PIL import Image
14
14
 
15
15
  from .audio import build_audio_args, collect_audio_sources
16
16
  from .encoder import Encoder
17
+ from .errors import RenderError
17
18
  from .probe import MediaInfo
18
19
  from .scenes import SceneRenderer
19
20
  from .spec import VideoSpec
@@ -69,6 +70,31 @@ def iter_frames(
69
70
  renderers.close()
70
71
 
71
72
 
73
+ def render_frames(
74
+ spec: VideoSpec, media: dict[Path, MediaInfo], frames: list[int]
75
+ ) -> Iterator[tuple[int, Image.Image]]:
76
+ """Render just the given frame indices, for spot-checking a spec.
77
+
78
+ Yields (frame_index, image) in ascending order with duplicates dropped,
79
+ blending transitions exactly as a full render would."""
80
+ timeline = Timeline(spec.scenes, spec.output.fps)
81
+ wanted = sorted(set(frames))
82
+ out_of_range = [f for f in wanted if not 0 <= f < timeline.total_frames]
83
+ if out_of_range:
84
+ raise RenderError(
85
+ f"frame {out_of_range[0]} is outside the video "
86
+ f"(valid range: 0 to {timeline.total_frames - 1})"
87
+ )
88
+ renderers = _SceneRenderers(spec, media)
89
+ try:
90
+ for f in wanted:
91
+ plan = timeline.plan(f)
92
+ renderers.retire_before(plan.scene)
93
+ yield f, _render_plan(plan, renderers)
94
+ finally:
95
+ renderers.close()
96
+
97
+
72
98
  def render_video(
73
99
  spec: VideoSpec,
74
100
  media: dict[Path, MediaInfo],
@@ -43,6 +43,18 @@ class Timeline:
43
43
  self.total_duration = acc
44
44
  self.total_frames = round(self.total_duration * fps)
45
45
 
46
+ def frame_for_time(self, t: float) -> int:
47
+ """The frame whose span [f/fps, (f+1)/fps) contains time ``t``.
48
+
49
+ The final instant clamps to the last frame rather than falling off
50
+ the end of the timeline."""
51
+ if not 0.0 <= t < self.total_duration:
52
+ raise ValueError(
53
+ f"time {t:g} s is outside the video "
54
+ f"(valid range: 0 to {self.total_duration:g} s)"
55
+ )
56
+ return min(int(t * self.fps), self.total_frames - 1)
57
+
46
58
  def _capped_transition(self, boundary_index: int) -> tuple[Transition, float]:
47
59
  """The transition after scene boundary_index, with its duration capped
48
60
  at the shorter of the two adjacent scenes [source: README.md]."""
@@ -115,9 +115,77 @@ class TestRender:
115
115
  assert capsys.readouterr().err == ""
116
116
 
117
117
 
118
- def test_help_names_both_subcommands(capsys):
118
+ class TestFrames:
119
+ def two_scene_path(self, tmp_path):
120
+ doc = tiny_doc(scenes=[
121
+ {
122
+ "duration": 1,
123
+ "background": {"type": "color", "color": "#1a1a2e"},
124
+ "transition": {"type": "crossfade", "duration": 0.5},
125
+ },
126
+ {"duration": 1, "background": {"type": "color", "color": "#e94560"}},
127
+ ])
128
+ return write_json(tmp_path / "v.json", doc)
129
+
130
+ def test_writes_pngs_and_prints_their_paths(self, tmp_path, capsys):
131
+ path = self.two_scene_path(tmp_path)
132
+ outdir = tmp_path / "shots"
133
+ assert main(["frames", str(path), "-o", str(outdir),
134
+ "--at", "0.05", "--frame", "19"]) == 0
135
+ out = capsys.readouterr().out
136
+ for name in ("frame_00.png", "frame_19.png"):
137
+ assert (outdir / name).exists()
138
+ assert str(outdir / name) in out
139
+ from PIL import Image
140
+ with Image.open(outdir / "frame_00.png") as image:
141
+ assert image.size == (64, 64)
142
+
143
+ def test_at_and_frame_address_the_same_frame_once(self, tmp_path, capsys):
144
+ path = self.two_scene_path(tmp_path)
145
+ outdir = tmp_path / "shots"
146
+ # fps=10: --at 1.05 is frame 10 (mid-crossfade), same as --frame 10
147
+ assert main(["frames", str(path), "-o", str(outdir),
148
+ "--at", "1.05", "--frame", "10"]) == 0
149
+ assert [p.name for p in sorted(outdir.iterdir())] == ["frame_10.png"]
150
+
151
+ def test_existing_png_is_replaced_silently(self, tmp_path):
152
+ path = self.two_scene_path(tmp_path)
153
+ outdir = tmp_path / "shots"
154
+ outdir.mkdir()
155
+ stale = outdir / "frame_00.png"
156
+ stale.write_bytes(b"stale")
157
+ assert main(["frames", str(path), "-o", str(outdir), "--frame", "0"]) == 0
158
+ assert stale.read_bytes() != b"stale"
159
+
160
+ def test_requires_at_least_one_frame_selector(self, tmp_path, capsys):
161
+ path = self.two_scene_path(tmp_path)
162
+ assert main(["frames", str(path), "-o", str(tmp_path / "shots")]) == 1
163
+ assert "--at" in capsys.readouterr().err
164
+
165
+ def test_out_of_range_time_reports_the_valid_range(self, tmp_path, capsys):
166
+ path = self.two_scene_path(tmp_path)
167
+ assert main(["frames", str(path), "-o", str(tmp_path / "shots"),
168
+ "--at", "2.5"]) == 1
169
+ err = capsys.readouterr().err
170
+ assert "error:" in err and "2" in err
171
+
172
+ def test_out_of_range_frame_reports_the_valid_range(self, tmp_path, capsys):
173
+ path = self.two_scene_path(tmp_path)
174
+ assert main(["frames", str(path), "-o", str(tmp_path / "shots"),
175
+ "--frame", "20"]) == 1
176
+ err = capsys.readouterr().err
177
+ assert "error:" in err and "19" in err
178
+
179
+ def test_invalid_spec_reports_problems(self, tmp_path, capsys):
180
+ path = write_json(tmp_path / "v.json", {"scenes": []})
181
+ assert main(["frames", str(path), "-o", str(tmp_path / "shots"),
182
+ "--frame", "0"]) == 1
183
+ assert "error:" in capsys.readouterr().err
184
+
185
+
186
+ def test_help_names_all_subcommands(capsys):
119
187
  with pytest.raises(SystemExit) as exc:
120
188
  main(["--help"])
121
189
  assert exc.value.code == 0
122
190
  out = capsys.readouterr().out
123
- assert "render" in out and "validate" in out
191
+ assert "render" in out and "validate" in out and "frames" in out
@@ -31,11 +31,12 @@ def tiny_spec():
31
31
 
32
32
 
33
33
  @pytest.mark.anyio
34
- async def test_server_exposes_the_three_tools():
34
+ async def test_server_exposes_the_four_tools():
35
35
  async with Client(build_server()) as client:
36
36
  tools = await client.list_tools()
37
37
  names = {t.name for t in tools.tools}
38
- assert names == {"get_format_reference", "validate_video", "render_video"}
38
+ assert names == {"get_format_reference", "validate_video", "render_video",
39
+ "render_frames"}
39
40
  for tool in tools.tools:
40
41
  assert tool.description
41
42
 
@@ -162,6 +163,77 @@ async def test_render_refuses_to_overwrite_without_flag(assets, tmp_path):
162
163
  assert probe_media(out).has_video
163
164
 
164
165
 
166
+ @pytest.mark.anyio
167
+ async def test_render_frames_writes_pngs_and_returns_their_paths(assets, tmp_path):
168
+ from PIL import Image
169
+
170
+ outdir = tmp_path / "shots"
171
+ async with Client(build_server()) as client:
172
+ result = await client.call_tool("render_frames", {
173
+ "spec": tiny_spec(),
174
+ "assets_dir": str(assets["root"]),
175
+ "output_dir": str(outdir),
176
+ "times": [0.35],
177
+ "frame_numbers": [9],
178
+ })
179
+ assert result.is_error is False
180
+ frames = result.structured_content["frames"]
181
+ assert [f["frame"] for f in frames] == [3, 9]
182
+ assert frames[0]["time_seconds"] == pytest.approx(0.35, abs=0.05)
183
+ for f in frames:
184
+ with Image.open(f["path"]) as image:
185
+ assert image.size == (64, 64)
186
+
187
+
188
+ @pytest.mark.anyio
189
+ async def test_render_frames_needs_at_least_one_selector(assets, tmp_path):
190
+ async with Client(build_server()) as client:
191
+ result = await client.call_tool("render_frames", {
192
+ "spec": tiny_spec(),
193
+ "assets_dir": str(assets["root"]),
194
+ "output_dir": str(tmp_path / "shots"),
195
+ })
196
+ assert result.is_error is True
197
+ assert "times" in result.content[0].text
198
+
199
+
200
+ @pytest.mark.anyio
201
+ async def test_render_frames_out_of_range_is_a_tool_error(assets, tmp_path):
202
+ async with Client(build_server()) as client:
203
+ bad_time = await client.call_tool("render_frames", {
204
+ "spec": tiny_spec(),
205
+ "assets_dir": str(assets["root"]),
206
+ "output_dir": str(tmp_path / "shots"),
207
+ "times": [5.0],
208
+ })
209
+ bad_frame = await client.call_tool("render_frames", {
210
+ "spec": tiny_spec(),
211
+ "assets_dir": str(assets["root"]),
212
+ "output_dir": str(tmp_path / "shots"),
213
+ "frame_numbers": [10],
214
+ })
215
+ assert bad_time.is_error is True
216
+ assert "valid range" in bad_time.content[0].text
217
+ assert bad_frame.is_error is True
218
+ assert "valid range" in bad_frame.content[0].text
219
+
220
+
221
+ @pytest.mark.anyio
222
+ async def test_render_frames_invalid_spec_is_a_tool_error(assets, tmp_path):
223
+ spec = tiny_spec()
224
+ spec["scenes"] = []
225
+ async with Client(build_server()) as client:
226
+ result = await client.call_tool("render_frames", {
227
+ "spec": spec,
228
+ "assets_dir": str(assets["root"]),
229
+ "output_dir": str(tmp_path / "shots"),
230
+ "frame_numbers": [0],
231
+ })
232
+ assert result.is_error is True
233
+ assert "scene" in result.content[0].text
234
+ assert not (tmp_path / "shots").exists()
235
+
236
+
165
237
  @pytest.mark.anyio
166
238
  async def test_render_extension_overrides_format(assets, tmp_path):
167
239
  out = tmp_path / "out.webm"
@@ -2,8 +2,9 @@ import hashlib
2
2
 
3
3
  import pytest
4
4
 
5
+ from scenescript.errors import RenderError
5
6
  from scenescript.probe import probe_media
6
- from scenescript.renderer import iter_frames, render_video
7
+ from scenescript.renderer import iter_frames, render_frames, render_video
7
8
  from scenescript.spec import parse_spec
8
9
  from scenescript.validation import validate_spec
9
10
 
@@ -128,6 +129,36 @@ def test_progress_reports_every_frame(assets, tmp_path):
128
129
  assert len(calls) == 20
129
130
 
130
131
 
132
+ class TestRenderFrames:
133
+ def test_frames_match_the_full_render(self, assets):
134
+ spec, media = prepare(two_scene_doc(), assets)
135
+ full = list(iter_frames(spec, media))
136
+ picked = dict(render_frames(spec, media, [0, 14, 19]))
137
+ assert set(picked) == {0, 14, 19}
138
+ for f, image in picked.items():
139
+ assert image.tobytes() == full[f].tobytes()
140
+
141
+ def test_a_transition_frame_blends_both_scenes(self, assets):
142
+ spec, media = prepare(two_scene_doc(), assets)
143
+ full = list(iter_frames(spec, media))
144
+ # fps=10, boundary at 1.0 s, crossfade 0.5 => frame 10 is mid-blend
145
+ [(f, image)] = list(render_frames(spec, media, [10]))
146
+ assert f == 10
147
+ assert image.tobytes() == full[10].tobytes()
148
+
149
+ def test_indices_come_back_sorted_and_deduplicated(self, assets):
150
+ spec, media = prepare(two_scene_doc(), assets)
151
+ indices = [f for f, _ in render_frames(spec, media, [19, 0, 19, 0])]
152
+ assert indices == [0, 19]
153
+
154
+ def test_out_of_range_index_raises_naming_the_range(self, assets):
155
+ spec, media = prepare(two_scene_doc(), assets)
156
+ with pytest.raises(RenderError, match=r"0.*19"):
157
+ list(render_frames(spec, media, [20]))
158
+ with pytest.raises(RenderError, match=r"0.*19"):
159
+ list(render_frames(spec, media, [-1]))
160
+
161
+
131
162
  def test_mkv_output(assets, tmp_path):
132
163
  doc = two_scene_doc(output={"width": 64, "height": 64, "fps": 10,
133
164
  "format": "mkv"})