Loading, tiers and TypeScript

This page covers the script tags that load Kinetic, the framework tiers each feature needs, the TypeScript declarations and the skill for Claude Code.

Loading it

Load three script tags, in this order.

<script defer src="https://cdn.jsdelivr.net/npm/wildflowerjs@^1.5.5/dist/wildflower.lite.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/@wildflowerjs/kinetic@0.1/dist/kinetic.wf.js"></script>
<script defer src="scenes.js"></script>

1. The framework tier comes first, because Kinetic installs itself into wildflower when it loads.
2. Kinetic comes second. kinetic.wf.js is the development build, which prints a warning with a KN code when a scene breaks a rule, and kinetic.wf.min.js is the same code with the checks left out, for the finished page.
3. The page's own scripts come last. Kinetic settles readiness after DOMContentLoaded, when every deferred and module script has registered its scenes.

wildflower.kinetic.version is the package's version.

Embedding

With embed in the page's URL, as in index.html?embed, the page shows the composition alone, with no preview bar: Kinetic hides every element beside the composition root and beside each of its ancestors up to the children of body, leaving script, style, link and template elements alone, zeroes the margin and padding of each ancestor and the root's own margin, and keeps the stage fitted to the window when fit is on. That is the form an <iframe> on another page shows, and the page that holds the iframe drives it with postMessage, from any origin, and hears its time back.

const frame = document.querySelector('iframe');   // src="video/index.html?embed"
frame.contentWindow.postMessage({ type: 'kinetic:seek', time: 2.5 }, '*');
frame.contentWindow.postMessage({ type: 'kinetic:play' }, '*');          // or { type: 'kinetic:play', from: 1, to: 4 }
frame.contentWindow.postMessage({ type: 'kinetic:pause' }, '*');
frame.contentWindow.postMessage({ type: 'kinetic:state' }, '*');         // asks for a kinetic:time message now

addEventListener('message', (e) => {
    if (e.source !== frame.contentWindow || !e.data || typeof e.data.type !== 'string') return;
    if (e.data.type === 'kinetic:ready') console.log(e.data.ready, e.data.duration, e.data.fps);   // once readiness has settled
    if (e.data.type === 'kinetic:time') console.log(e.data.time, e.data.frame, e.data.playing);   // after every seek, play and pause
});

• The frame posts to its parent with '*' and takes play, pause and seek from its parent only. Without embed in the URL, or at the top of a window, it posts and takes nothing.
• A kinetic:time message carries time, frame, playing, duration and fps. It comes after every seek, and whenever the frame pauses or plays, a click or a key inside the frame included. A kinetic:ready message carries ready, 'true' or 'failed', with duration, fps, width and height.
• A seek whose time is not a number, or a play the clock refuses, is answered with { type: 'kinetic:error', message } and changes nothing.

The HyperFrames runtime

A page that renders through HyperFrames carries one more script tag, the HyperFrames runtime, after Kinetic's. Rendering through HyperFrames has the tag, the command, what changes on the page while the runtime is present, and the frame-rate rule its player imposes.

Tiers

TypeScript

The package ships types.d.ts, which declares WildflowerKinetic and the type of every option and result. Inside a scene's computed properties and methods, this is typed as SceneContext plus the scene's own properties.

• Scenes and motion: SceneDefinition, SceneContext, Track, InterpolateOptions, SpringOptions, MatchPathsOptions.
• Transitions and effects: TransitionKind, TransitionStyles, EffectParams, Effect.
• Media: LottieAnimation, LottieOptions, AnimatedImage.
• Rendering: RenderOptions, RenderResult, CheckReport.
• Captions and audio: CaptionLine, LevelBand, LevelOptions.
• Interactive mode: StepDefinition, ScriptTrack, ScriptSettings, FollowEntry, StepEventDetail.

The built files add wildflower.kinetic rather than exporting, so a page that loads them by script tag has no import to carry the types. types.global.d.ts adds wildflower.kinetic to the framework's own surface.

/// <reference types="@wildflowerjs/kinetic/types.global" />

const report = await wildflower.kinetic.check({ samples: 30 });   // CheckReport
const v = wildflower.kinetic.interpolate(1, [0, 2], ['#000', '#fff']);   // string

The skill for Claude Code

The package ships skills/wildflower-kinetic/, a skill in the Claude Code layout. Copy the folder into a project's .claude/skills/, or into ~/.claude/skills/ for every project.

• SKILL.md holds the routing description and the procedure.
• references/start.md, which SKILL.md points to first, holds one complete video page and one complete interactive lesson page, with the rules that matter for each.
• references/rules.md, references/api.md and references/patterns.md hold the rules, the API, and the patterns with their code.
• scripts/check.cjs opens a composition in a headless browser, waits for readiness, runs check() and prints every KN line. It runs in the installed Chrome when there is one, and in Playwright's Chromium otherwise, and prints which.
• A run fails on a report that is not ok, on any KN line, on an uncaught error or unhandled rejection at any time, and on a console error the framework or an extension printed, such as [WF-238], even outside the seeks check() counts. An author's own console.error lines are printed and do not fail it.

check() cannot see a binding that shows nothing or a layer drawn in the wrong place, since those are the same on every seek, so the script also saves frames to look at.

node check.cjs index.html                      # readiness, check() and the KN lines
node check.cjs index.html --frames 0,2.5,5      # a PNG of the stage at each time, in frames/ beside the page
node check.cjs index.html --frames 12           # twelve frames, evenly spaced from the first to the last
node check.cjs index.html --lesson              # each step entered in turn, with a still at its hold
node check.cjs index.html --frames 6 --out shots   # the PNGs in another folder

• --frames seeks each time in video mode as check() does, waiting for the seek to settle, and saves the composition root without the preview bar.
• --lesson enters each step with go() in interactive mode and waits for its hold, then reports whether it held, the until path it waits on, and the console errors and KN lines during the step (Checking a lesson). It answers no question, and a step that never holds, a console error or a KN line fails the run.

The skill applies to any brief that asks for a video: a title, motion graphics, a chart or captions from data, a lesson, or many videos from one page. With an AI assistant has the track that uses it.