mirror of https://github.com/hanzoai/frames.git synced 2026-09-24 00:08:03 +00:00

Files

T

zooqueen 75094e0d60 frames: publish the toolchain as @hanzo/frames

@hanzo/frame is taken by the hero video primitive — one full-bleed video
element — which has held that name on npm since it shipped. This repo is the
video toolchain: a CLI, a renderer, a studio, a player. Plural is what it is,
so the CLI publishes as @hanzo/frames and the workspace packages follow it
(@hanzo/frames-core, @hanzo/frames-engine, and the rest).

The binary stays `frames`, and now actually ships. The manifest mapped it to
bin/frames.mjs while the file on disk was bin/hyperframes.mjs, so a global
install produced no working command.

The paths that name a package to fetch were pointing elsewhere. The update
check read registry.npmjs.org/frames, a different author's package, and the
npm, bun and pnpm installers would have pulled it over the CLI; the render
image installed the upstream hyperframes; scaffolded projects and the docs
pinned the unscoped name. All of them now name @hanzo/frames.

2026-08-13 18:10:14 -07:00

2.8 KiB

Raw Permalink Blame History

@hanzo/frames-core

Types, parsers, generators, compiler, linter, runtime, and frame adapters for the Hyperframes video framework.

Install

npm install @hanzo/frames-core

Most users don't need to install core directly — the CLI, producer, and studio packages depend on it internally.

What's inside

Module	Description
Types	`TimelineElement`, `CompositionSpec`, `Asset`, canvas dimensions, defaults
Parsers	`parseHtml` — extract timeline elements from HTML; `parseGsapScript` — parse GSAP animations
Generators	`generateHyperframesHtml` — produce valid Hyperframes HTML from a composition spec
Compiler	`compileTimingAttrs` — resolve `data-start` / `data-duration` into absolute times
Linter	`lintHyperframeHtml` — validate Hyperframes HTML (missing attributes, overlapping tracks, etc.)
Runtime	IIFE script injected into the browser — manages seek, media playback, and the `window.__hf` protocol
Frame Adapters	Pluggable animation drivers (GSAP, Lottie, CSS, or custom)

Frame Adapters

A frame adapter tells the engine how to seek your animation to a specific frame:

import { createGSAPFrameAdapter } from "@hanzo/frames-core";

const adapter = createGSAPFrameAdapter({
  getTimeline: () => gsap.timeline(),
  compositionId: "my-video",
});

Implement FrameAdapter for custom animation runtimes:

import type { FrameAdapter } from "@hanzo/frames-core";

const myAdapter: FrameAdapter = {
  id: "my-adapter",
  getDurationFrames: () => 300,
  seekFrame: (frame) => {
    /* seek your animation */
  },
};

Parsing and generating HTML

import { parseHtml, generateHyperframesHtml } from "@hanzo/frames-core";

const { elements, metadata } = parseHtml(htmlString);
const html = generateHyperframesHtml(spec);

Linting

import { lintHyperframeHtml } from "@hanzo/frames-core/lint";

const result = lintHyperframeHtml(htmlString);
// result.findings: { severity, message, elementId }[]

Documentation

Full documentation: frames.hanzo.ai/packages/core

@hanzo/frames-engine — rendering engine that drives the browser
@hanzo/frames-producer — full render pipeline (capture + encode)
frames — CLI

2.8 KiB Raw Permalink Blame History