Plotbeat Data Videos

Build a composition

1. Acquire the requested data or inspect the supplied file, then identify its columns, date grain, missing values, number of series, source, and desired unit.

2. Obtain the visual style and pacing before scaffolding. If the user supplies JSON copied from the Plotbeat style builder, treat that as an explicit custom visual direction: validate its documented fields, choose the nearest preset only as the scaffold base, then apply the supplied tokens and composition choices in the copied project. Do not replace the supplied JSON with the base preset. If style or pacing is otherwise missing, ask one short grouped question: “Should the visual direction be dark or light, which preset character fits the story, and should it feel quick (~18s), standard (~30s), deliberate (~45s), or use an exact duration?” Offer the installed presets from --list-styles; map the answer to its --style <id> flag and pacing to --pace quick, --pace standard, --pace deliberate, or --duration <seconds>. When a user asks the agent to decide, choose from the data context using the style reference and state the choice.

3. Normalize dates and numbers. Ask only when another choice changes the story materially; otherwise choose safe column defaults and state them.

4. Scaffold a template:

   node {skill-dir}/scripts/scaffold.mjs \
     --template single-line-story \
     --input /absolute/path/to/data.csv \
     --output /absolute/path/to/composition \
     --date date --value value \
     --title "What if Revenue kept compounding?" \
     --accent-text "Revenue" --unit "USD" \
     --style paper-cut --pace quick

   For long-form multi-series data, add --series series and select multi-line-rank. For wide data such as date,North,South, pass --series-columns North,South instead.

   Select bar-race for ranking changes or stacked-area-story for contribution-to-total stories. Add --bar-mode leader-index to normalize the current leader to 100, or --stack-mode percent for a 100% stacked composition. Scatter, map, KPI, and milestone inputs use the documented contracts and the --scatter-mode, --map-mode, --kpi-mode, and --timeline-mode variant flags.

5. Edit the copied index.html, frame.md, and metadata in the output project. Preserve local script paths and HyperFrames timing attributes.

6. Run the compiler again after changing column mappings, story copy, or pacing:

   node scripts/prepare-data.mjs \
     --template single-line-story \
     --input data/input.csv \
     --output generated/data.js \
     --composition index.html \
     --date date --value value \
     --title "What if Conversion kept compounding?" \
     --accent-text "Conversion" --unit "%" \
     --style studio-blueprint --pace standard --duration 24 --path-style linear

   --duration overrides only the pace preset's length; the selected pace still supplies suitable opening, finale, and closing proportions unless explicit timing flags override them. Recompiling with a different --style changes the design system and default chart palette without changing the data, template, or timing.

7. Validate from the composition directory:

   npm test
   npx hyperframes check --snapshots --samples 12
   npx hyperframes preview

8. Inspect the closed first frame, multiple opening-transition frames, early growth, middle, rank-crossing/extreme, pre-finale, staggered finale, finale hold, and closed last frame. Confirm that each line grows continuously from the left without snapping to the right edge, the live date chip follows the endpoint, axes expand from zero for positive datasets, endpoint values match the compiled rows, rank rows glide rather than jump, the finale begins only after the full chart is visible, neither transition produces a one-frame flash, and the music fades cleanly at both ends without overpowering the chart. Obtain preview approval before npx hyperframes render.

Extend the template set

When the existing templates do not fit, add a new native HyperFrames template rather than branching into a new generator. Define its manifest, data shape, deterministic state model, example data, preview frames, and quality checks. Reuse assets/runtime/plotbeat-data.js for interpolation and formatting where practical.

Keep template-specific visual decisions in the composition and generic math in the runtime. A template is ready only when arbitrary forward and backward seeks produce the same frame and HyperFrames checks pass without unexplained suppressions.

Resources

• scripts/scaffold.mjs: copies a complete template and compiles the selected dataset.
• scripts/prepare-data.mjs: compiles CSV/JSON to frozen local JavaScript.
• assets/templates/: native HyperFrames composition starters.
• assets/catalog/templates.json: machine-readable catalog used for template discovery.
• assets/runtime/: shared deterministic chart-state helpers and visual-style tokens.
• assets/samples/: generic sample datasets for smoke tests.