feat: publish viewer animation cadence

Author: lfagundes

…ublished-viewer-animation/.openspec.yaml …ublished-viewer-animation/.openspec.yamlopenspec/changes/published-viewer-animation/.openspec.yaml renamed to openspec/changes/archive/2026-07-20-published-viewer-animation/.openspec.yaml openspec/changes/published-viewer-animation/.openspec.yaml renamed to openspec/changes/archive/2026-07-20-published-viewer-animation/.openspec.yaml

@@ -1,11 +1,11 @@
 ## 1. Published snapshot contract
 
-- [ ] 1.1 Add red-first builder coverage for the published animation cadence
+- [x] 1.1 Add red-first builder coverage for the published animation cadence
   and its retention after a failed later build.
-- [ ] 1.2 Serialize the established `fps` and `frames` cadence into staging
+- [x] 1.2 Serialize the established `fps` and `frames` cadence into staging
   `viewer.json` before atomic publication.
 
 ## 2. Verification
 
-- [ ] 2.1 Run the focused build, CLI, and snapshot-backed-viewer suites and
+- [x] 2.1 Run the focused build, CLI, and snapshot-backed-viewer suites and
   validate the originating Floor/V8 consumer against the completed build.

…ges/published-viewer-animation/design.md …-20-published-viewer-animation/design.mdopenspec/changes/published-viewer-animation/design.md renamed to openspec/changes/archive/2026-07-20-published-viewer-animation/design.md openspec/changes/published-viewer-animation/design.md renamed to openspec/changes/archive/2026-07-20-published-viewer-animation/design.md

@@ -7,12 +7,16 @@ Complete normal-build viewer state for private local framework consumers.
 ## Requirements
 
 ### Requirement: Complete builds publish a viewer snapshot
-The builder SHALL publish a versioned viewer snapshot in the normal build directory only after the current project model has assembled and every required STL artifact is current. The snapshot SHALL contain the recursive viewer state for the root model: node identity, type, colour, serialized operations, child relationships, and build-root-relative rigid-model paths.
+The builder SHALL publish a versioned viewer snapshot in the normal build directory only after the current project model has assembled and every required STL artifact is current. The snapshot SHALL contain the recursive viewer state for the root model: node identity, type, colour, serialized operations, child relationships, and build-root-relative rigid-model paths. It SHALL also contain an `animation` object with numeric `fps` and `frames` values representing the animation cadence used to evaluate raw `$t` operations. The snapshot and all referenced model files SHALL become visible together through the normal atomic build publication.
 
 #### Scenario: A complete model is built once
 - **WHEN** `solid build <project>` completes successfully
 - **THEN** its `_build` directory contains a complete viewer snapshot whose rigid model paths resolve within that same published directory
 
+#### Scenario: A completed animated model is published
+- **WHEN** `solid build <project>` completes a model with a `$t` operation
+- **THEN** its `viewer.json` contains numeric `animation.fps` and `animation.frames` values alongside the root tree
+
 ### Requirement: The framework viewer can read a published snapshot
 The framework SHALL provide its existing private viewer implementation a snapshot-backed mode that serves the same recursive node state and model files from a published build directory without importing the project model.
 

…s/published-viewer-animation/proposal.md …0-published-viewer-animation/proposal.mdopenspec/changes/published-viewer-animation/proposal.md renamed to openspec/changes/archive/2026-07-20-published-viewer-animation/proposal.md openspec/changes/published-viewer-animation/proposal.md renamed to openspec/changes/archive/2026-07-20-published-viewer-animation/proposal.md

@@ -273,6 +273,7 @@ def _write_viewer_snapshot(self):
         os.makedirs(self.build_dir, exist_ok=True)
         with open(os.path.join(self.build_dir, 'viewer.json'), 'w') as snapshot:
             json.dump({'version': 1,
+                       'animation': {'fps': 30, 'frames': 360},
                        'root': _viewer_state(self.node, self.build_dir)}, snapshot)
 
     def _notify_callback(self):

…ion/specs/build-viewer-artifacts/spec.md …ion/specs/build-viewer-artifacts/spec.mdopenspec/changes/published-viewer-animation/specs/build-viewer-artifacts/spec.md renamed to openspec/changes/archive/2026-07-20-published-viewer-animation/specs/build-viewer-artifacts/spec.md openspec/changes/published-viewer-animation/specs/build-viewer-artifacts/spec.md renamed to openspec/changes/archive/2026-07-20-published-viewer-animation/specs/build-viewer-artifacts/spec.md

@@ -125,6 +125,7 @@ def test_complete_build_writes_viewer_snapshot_before_publishing(self):
             data = json.load(snapshot)
         self.assertEqual(data['root']['name'], 'part')
         self.assertEqual(data['root']['model'], 'part.stl')
+        self.assertEqual(data['animation'], {'fps': 30, 'frames': 360})
 
     def test_failed_build_does_not_notify_callback(self):
         builder = Builder('model.py', build_dir='/tmp/candidate',