From 8426b6df8ee3b81ccf479541260effa1824c6fad Mon Sep 17 00:00:00 2001 From: Corhelix Date: Thu, 23 Apr 2026 13:53:26 +1000 Subject: [PATCH] docs: relocate hyperframes setup report from Agent-and-Config-Files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This file was misrouted into Corhelix/Agent-and-Config-Files/projects/general/ because every slash command hardcoded a relative `projects//tasks/` path. It belongs here in the hyperframes repo. Coverage: - docs/reports/2026-04-21-setup/DRAFT-REPORT-v0.1-2026-04-21.html Cause fixed in separate Agent-and-Config-Files commit: slash commands now resolve entity → repo via protocols/entity-repo-map.md and write to absolute paths. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../DRAFT-REPORT-v0.1-2026-04-21.html | 319 ++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 docs/reports/2026-04-21-setup/DRAFT-REPORT-v0.1-2026-04-21.html diff --git a/docs/reports/2026-04-21-setup/DRAFT-REPORT-v0.1-2026-04-21.html b/docs/reports/2026-04-21-setup/DRAFT-REPORT-v0.1-2026-04-21.html new file mode 100644 index 000000000..1e54c3051 --- /dev/null +++ b/docs/reports/2026-04-21-setup/DRAFT-REPORT-v0.1-2026-04-21.html @@ -0,0 +1,319 @@ + + + + + +Session Report — Hyperframes Setup + + + + + + + + + +
+
+
+

Session Report — 21 April 2026

+

Hyperframes Setup.

+
+
+

Fork, install, configure, and verify the HeyGen Hyperframes open-source video rendering framework for local use with API-based rendering and Claude Code agent skills.

+
+
+ + +
+
+
+

Section 01

+

Task

+
+
+

Objective: Analyse, fork, install, and operationally verify the heygen-com/hyperframes open-source video rendering framework — establishing a local authoring environment with HTTP API-based rendering and agent skill integration for Claude Code.

+
+
+
+ + +
+
+
+

Section 02

+

What Was Done

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ActionOutcome
Repo analysisFull architectural breakdown of heygen-com/hyperframes: 7-package TypeScript monorepo (cli, core, engine, player, producer, shader-transitions, studio). Apache 2.0. 8k+ stars.
Fork to CorhelixCreated github.com/Corhelix/hyperframes via gh repo fork. Upstream tracking configured.
Bun installedv1.3.13 installed to ~/.bun/bin/bun. Added to $PATH in ~/.zshrc.
git-lfs installedInstalled via Homebrew. Hook conflict with graphify post-checkout hook — resolved via GIT_LFS_SKIP_SMUDGE=1 on clone.
Local clone/Users/burns/Documents/hyperframes/ — 1,160 packages installed via bun install.
Agent skills installed5 skills via npx skills add heygen-com/hyperframes --yes: hyperframes, hyperframes-cli, hyperframes-registry, gsap, website-to-hyperframes. Symlinked into Claude Code.
Producer server builtbun run build:producer — fonts generated (42 faces, 718KB), runtime compiled, server bundled to dist/public-server.js.
Producer server verifiedRunning at http://localhost:9847. Health check confirmed. Test render: 2s 640×360 composition → 15KB MP4 in 4 seconds. Full pipeline operational.
Knowledge memory savedreference_hyperframes_setup.md created and indexed in MEMORY.md for future session continuity.
+
+
+ + +
+
+
+

Section 03

+

Decisions Made

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
DecisionRationaleImpact
Fork to Corhelix user accountCorhelix is a GitHub user account, not an organisation. gh repo fork --org fails for user accounts.Fork lives at Corhelix/hyperframes. Can sync upstream via gh repo sync.
API rendering via producer server, not local CLIUser preference: avoid persistent RAM drain from Chrome + FFmpeg. Producer server runs only when needed.Rendering via POST /render to localhost:9847. Future: Docker/Azure for fully decoupled rendering.
LFS skip smudge on clonegraphify post-checkout hook conflicts with git-lfs hooks. git lfs update --force would overwrite graphify hook.LFS-tracked files (large assets) not downloaded. Pull selectively with git lfs pull if needed. No impact on authoring or rendering.
Local producer for now, Docker/Azure deferredUser wants to explore the tool before investing in infrastructure. Azure account available for future deployment.Rendering currently uses local Chrome + FFmpeg when producer is running. RAM impact is temporary (only while server is active).
+
+
+ + +
+
+
+

Section 04

+

Files Created / Modified

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FileActionPurpose
/Users/burns/Documents/hyperframes/Created (clone)Local Hyperframes repo — full monorepo with all 7 packages
~/Documents/hyperframes/.agents/skills/Created (skills install)5 agent skills symlinked into Claude Code
~/.bun/bin/bunCreated (install)Bun v1.3.13 package manager — required for Hyperframes dev tooling
~/.claude/.../memory/reference_hyperframes_setup.mdCreatedKnowledge memory: full setup reference for future sessions
~/.claude/.../memory/MEMORY.mdModifiedAdded Hyperframes entry to Tools & Integrations index
+
+
+ + +
+
+
+

Section 05

+

Findings

+
+ +
+ Architecture. Hyperframes is a mature, well-structured monorepo. The producer package exposes a clean HTTP API (POST /render, POST /render/stream with SSE, POST /lint, GET /health). Rendering is deterministic — same HTML composition always produces the same video output. No external API dependencies; entirely self-contained. +
+ +
+ git-lfs hook conflict. The graphify post-checkout hook and git-lfs post-checkout hook cannot coexist without manual merging. Current workaround (GIT_LFS_SKIP_SMUDGE=1) is functional but means LFS-tracked assets are not automatically fetched. If large video assets are needed for compositions, run git lfs pull explicitly. +
+ +
+ Bun not in subshell PATH. After install, bun is added to ~/.zshrc but not available in non-login subshells. Commands must use PATH="$HOME/.bun/bin:$PATH" bun ... or ~/.bun/bin/bun directly until a new terminal session is opened. +
+ +
+ Full pipeline verified. Test render completed successfully: 2-second 640×360 composition → valid MP4 (15KB) in 4 seconds. Health endpoint responding. All 5 agent skills installed and security-assessed (0 Socket alerts, low-to-medium Snyk risk). +
+ +
+ +

System Inventory

+
+
+
+

Prerequisites

+

Node.js v22.19.0

+

FFmpeg v8.0.1

+

Bun v1.3.13

+

Chromium v146 (Puppeteer cache)

+
+
+

Producer API Endpoints

+

POST /render — blocking

+

POST /render/stream — SSE

+

GET /render/queue — status

+

POST /lint — validate

+

GET /health — check

+

GET /outputs/:token — download

+
+
+

Agent Skills

+

hyperframes — authoring

+

hyperframes-cli — CLI

+

hyperframes-registry — components

+

gsap — animations

+

website-to-hyperframes — conversion

+
+
+
+
+ + +
+
+
+

Section 06

+

Next Steps

+
+ +
+
+

Completed

+
    +
  • Fork to Corhelix GitHub
    • +
  • Clone locally with dependencies
    • +
  • Install Bun, git-lfs, agent skills
    • +
  • Build producer server
    • +
  • Verify full render pipeline (test composition → MP4)
    • +
  • Save knowledge memory for future sessions
    • +
+
+
+

Open

+
    +
  • Dockerise producer server for Azure deployment (decoupled rendering)
    • +
  • Build first real composition using the component registry
    • +
  • Explore the studio visual editor (bun run dev)
    • +
  • Test the website-to-hyperframes skill on an existing HTML page
    • +
  • Resolve git-lfs / graphify hook conflict properly (manual merge)
    • +
+
+
+ +
+ +
+

Quick Reference — Starting Hyperframes

+ 
# Start the producer server
+cd /Users/burns/Documents/hyperframes
+node packages/producer/dist/public-server.js
+# Server at http://localhost:9847
+
+# Render a composition
+curl -X POST http://localhost:9847/render \
+  -H "Content-Type: application/json" \
+  -d '{"html": "<div id=\"stage\" ...>...</div>"}'
+
+# Open the studio editor
+PATH="$HOME/.bun/bin:$PATH" bun run dev
+
+# Rebuild producer (after upstream sync)
+PATH="$HOME/.bun/bin:$PATH" bun run build:producer
+
+
+
+ + + + + +