From 3d67fb9d10a864201db9de3214f8cd67fb6fec46 Mon Sep 17 00:00:00 2001 From: Ular Kimsanov Date: Thu, 22 Oct 2026 19:04:48 +0000 Subject: [PATCH] chore: help agents find hyperframes on npm and context7 (#5937) * feat(cli): open scaffolded agent instructions with what hyperframes is Agents asked to make a video choose from what is on disk. The AGENTS.md and CLAUDE.md that init writes now open with a plain statement of what the project is and that `hyperframes render` replaces a hand-built headless-browser and ffmpeg pipeline, and list `snapshot` beside preview, check, render and docs. A test pins that init writes both files from the template, and the CLI docs now say init creates them. Co-Authored-By: Claude Opus 5.5 * chore: describe the npm packages in plain words npm search ranks on description and keywords. The hyperframes package now says what it does ("Make videos with code and AI agents: write HTML, render MP4. Open source.") and lists the words people and agents search for. Core and studio had empty descriptions; producer and player gain keywords too. Co-Authored-By: Claude Opus 5.5 * docs(readme): give coding agents a one-line start The opening paragraph said what HyperFrames is but not how an agent starts. Add one line: install the skills, then ask the agent for a video. Co-Authored-By: Claude Opus 5.5 * fix(cli): keep the scaffolded agent intro to what the folder is Inside a scaffolded project the agent already uses the CLI, so telling it not to build its own capture pipeline there adds nothing. The intro now only says what the folder is. Co-Authored-By: Claude Opus 5.5 * chore: keep npm metadata to the CLI package Internal packages are not searched on npm, and the init test only re-checked the template's own text. Co-Authored-By: Claude Opus 5.5 * chore: context7.json so agents get the docs and the composition rules Indexes docs, skills, registry and examples only (no test fixtures), and hands agents five rules from AGENTS.md. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- README.md | 2 ++ context7.json | 13 +++++++++++++ docs/packages/cli.mdx | 6 ++++-- packages/cli/package.json | 18 +++++++++++++++++- packages/cli/src/templates/_shared/AGENTS.md | 5 +++++ packages/cli/src/templates/_shared/CLAUDE.md | 5 +++++ 6 files changed, 46 insertions(+), 3 deletions(-) create mode 100644 context7.json diff --git a/README.md b/README.md index 8cfc65cc13..1842f2ff48 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,8 @@ HyperFrames is an open-source framework for turning HTML, CSS, media, and seekable animations into deterministic MP4 videos. Use it locally with the CLI, from AI coding agents with skills, or as the rendering core behind hosted authoring workflows. +Using Claude Code, Codex, Cursor, or another coding agent? Run `npx hyperframes skills update` once, then ask your agent to make a video. + ## Quick Start ### With an AI coding agent diff --git a/context7.json b/context7.json new file mode 100644 index 0000000000..26574f7a6d --- /dev/null +++ b/context7.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://context7.com/schema/context7.json", + "folders": ["docs", "skills", "registry", "examples"], + "excludeFolders": ["docs/public", "**/tests", "**/test", "**/fixtures", "**/node_modules"], + "excludeFiles": ["weekly-updates.mdx"], + "rules": [ + "Install the HyperFrames agent skills before writing a composition: `npx skills add heygen-com/hyperframes`, or in Claude Code `claude plugin marketplace add heygen-com/hyperframes` then `claude plugin install hyperframes@hyperframes`.", + "A composition is an HTML file whose root element has data-composition-id, data-width, data-height and data-duration. Timed elements use class=\"clip\" with data-start and data-duration.", + "Register one paused GSAP root timeline per composition on window.__timelines[\"\"]. The runtime seeks it frame by frame, so never play it yourself.", + "Rendering is deterministic: no Date.now(), no unseeded Math.random(), no network fetches at render time.", + "Check before rendering: `npx hyperframes lint`, `npx hyperframes check`, and `npx hyperframes snapshot --at 1,3,5` for frames. Make the MP4 with `npx hyperframes render --output video.mp4`." + ] +} diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index cb4439310d..aa1282bcf7 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -127,8 +127,10 @@ of v3 `tailwind.config.js` patterns. The browser runtime is meant for scaffolded projects and quick iteration — for offline or locked-down production renders, compile Tailwind to CSS and link the stylesheet. -After scaffolding, `init` checks and installs the core AI skills from the -current GitHub source. See [`skills`](#skills). +Every new project gets an `AGENTS.md` and an identical `CLAUDE.md`: they tell a +coding agent what HyperFrames is and which commands preview, check, snapshot and +render the video. After scaffolding, `init` checks and installs the core AI +skills from the current GitHub source. See [`skills`](#skills). ### `add` diff --git a/packages/cli/package.json b/packages/cli/package.json index a7dae7c75e..4b370fb75b 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,7 +1,23 @@ { "name": "@hyperframes/cli", "version": "0.8.186", - "description": "HyperFrames CLI — create, preview, and render HTML video compositions", + "description": "Make videos with code and AI agents: write HTML, render MP4. Open source.", + "keywords": [ + "ai-agents", + "animation", + "claude-code", + "codex", + "cursor", + "gsap", + "html-to-video", + "hyperframes", + "motion-graphics", + "mp4", + "remotion-alternative", + "render", + "video", + "video-editor" + ], "license": "Apache-2.0", "repository": { "type": "git", diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md index ef5066102f..31e19f380f 100644 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -1,5 +1,9 @@ # HyperFrames Composition Project +This folder is a [HyperFrames](https://hyperframes.heygen.com) video: HTML, CSS and seekable +animations (GSAP by default) that the `hyperframes` CLI previews in the browser and renders to +MP4. + ## Skills — read these first **Invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that generic web docs don't cover, so compositions written without them break. @@ -35,6 +39,7 @@ npx hyperframes preview --background # agent-safe persistent Studio preview npx hyperframes preview --status # verify the persistent preview is listening npx hyperframes preview --stop # stop it when review is finished npm run check # lint + runtime + layout + motion + contrast (one command) +npx hyperframes snapshot --at 1,3,5 # PNG frames at those seconds, to look at before rendering npm run render # render to MP4 npm run publish # publish and get a shareable link npx hyperframes lint --verbose # include info-level findings diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md index ef5066102f..31e19f380f 100644 --- a/packages/cli/src/templates/_shared/CLAUDE.md +++ b/packages/cli/src/templates/_shared/CLAUDE.md @@ -1,5 +1,9 @@ # HyperFrames Composition Project +This folder is a [HyperFrames](https://hyperframes.heygen.com) video: HTML, CSS and seekable +animations (GSAP by default) that the `hyperframes` CLI previews in the browser and renders to +MP4. + ## Skills — read these first **Invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that generic web docs don't cover, so compositions written without them break. @@ -35,6 +39,7 @@ npx hyperframes preview --background # agent-safe persistent Studio preview npx hyperframes preview --status # verify the persistent preview is listening npx hyperframes preview --stop # stop it when review is finished npm run check # lint + runtime + layout + motion + contrast (one command) +npx hyperframes snapshot --at 1,3,5 # PNG frames at those seconds, to look at before rendering npm run render # render to MP4 npm run publish # publish and get a shareable link npx hyperframes lint --verbose # include info-level findings