From 1f9be6858eb7aeaf59962ee6e07a986e2199255f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Mon, 30 Mar 2026 18:40:16 +0200 Subject: [PATCH 1/4] docs: add guide for testing local CLI changes outside the monorepo Covers pnpm link, node alias, and npm pack workflows with a table of test scenarios for each bug fix category. --- docs/docs.json | 3 +- docs/guides/testing-local-changes.mdx | 128 ++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 docs/guides/testing-local-changes.mdx diff --git a/docs/docs.json b/docs/docs.json index 6deb4074f..361a6fed0 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -54,7 +54,8 @@ "guides/templates", "guides/rendering", "guides/common-mistakes", - "guides/troubleshooting" + "guides/troubleshooting", + "guides/testing-local-changes" ] } ] diff --git a/docs/guides/testing-local-changes.mdx b/docs/guides/testing-local-changes.mdx new file mode 100644 index 000000000..f8cfec389 --- /dev/null +++ b/docs/guides/testing-local-changes.mdx @@ -0,0 +1,128 @@ +--- +title: Testing Local CLI Changes +description: How to test unreleased CLI changes outside the monorepo using your local build. +--- + +When you modify the CLI or any package it bundles (core, engine, producer, studio), you need to test those changes against real projects _outside_ the monorepo — the same way an end user would run `hyperframes dev`. + +## Prerequisites + +Build the monorepo first. Every time you change source files, rebuild before testing. + +```bash +# From the monorepo root +pnpm build +``` + +## Option 1: pnpm link (recommended) + +`pnpm link --global` makes the `hyperframes` binary in your `$PATH` point at your local build. It survives across terminal sessions and auto-picks up new builds without re-linking. + +```bash +# One-time setup +cd packages/cli +pnpm link --global + +# Verify — should print your local version +hyperframes --version +``` + +Now use `hyperframes` normally in any directory: + +```bash +cd ~/my-video-project +hyperframes dev . +``` + +**After every `pnpm build`** the linked binary is already up to date — no re-linking needed. + +To restore the published release when you're done: + +```bash +pnpm unlink --global hyperframes +npm install -g hyperframes@latest +``` + +## Option 2: node alias (no PATH changes) + +If you don't want to touch your global `$PATH`, add a shell alias or call `node` directly: + +```bash +# Temporary alias for your current shell session +alias hyperframes="node /path/to/hyperframes-oss/packages/cli/dist/cli.js" + +# Or invoke directly +node /path/to/hyperframes-oss/packages/cli/dist/cli.js dev . +``` + +Replace `/path/to/hyperframes-oss` with your actual monorepo path. + +## Option 3: npm pack (test the exact published artifact) + +Use this when you want to verify what would actually ship in a release, including the bundled studio and templates. + +```bash +cd packages/cli +npm pack +# Creates: hyperframes-.tgz + +# Test it in an isolated directory +mkdir /tmp/pack-test && cd /tmp/pack-test +npx /path/to/hyperframes-oss/packages/cli/hyperframes-.tgz init my-video +cd my-video +npx /path/to/hyperframes-oss/packages/cli/hyperframes-.tgz dev . +``` + +## Testing the fix branches + +When validating a specific bug fix, extract one of the test project archives and run through the scenario: + +```bash +# Example: testing audio-after-seek fix +unzip golden-lyric-video.zip && cd golden-lyric-video +hyperframes dev . +# 1. Press Play — confirm audio plays +# 2. Drag the timeline scrubber to a different position +# 3. Press Play again — audio should resume from the seeked position +``` + +Common test scenarios: + +| Bug | Project | Steps | +|---|---|---| +| Audio silent after seek | `golden-lyric-video` | Play → seek → play again, verify audio | +| Render stuck at 0% | any | Renders tab → Export → watch progress bar | +| Download 404 after restart | any | Complete a render → `Ctrl+C` → restart → Download | +| Timeline stops early | `intro-vid` | Play → should reach `0:05`, not stop at `0:03` | +| Lottie missing | `hyperframe-build-up-demo` | Play → rocket visible during 0–2 s | +| Blank thumbnails | any | Compositions sidebar should show previews | + +## Troubleshooting + +**Changes not reflected after `pnpm build`** + +The CLI binary is a single bundled file at `packages/cli/dist/cli.js`. If your change is in `@hyperframes/core` or another workspace package, make sure `pnpm build` rebuilt _all_ packages — the CLI bundles its dependencies at build time. + +**`hyperframes` still shows the old version** + +Check which binary is active: + +```bash +which hyperframes +hyperframes --version +``` + +If it points to a global npm installation rather than your link, uninstall the npm version first: + +```bash +npm uninstall -g hyperframes +cd packages/cli && pnpm link --global +``` + +**Port already in use** + +`hyperframes dev` defaults to port 3002 and auto-increments if it's taken. Pass `--port` to use a specific port: + +```bash +hyperframes dev . --port 4000 +``` From 745c7690e2615aa8c736397e729407e729ccc730 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Mon, 30 Mar 2026 22:06:33 +0200 Subject: [PATCH 2/4] docs: move testing guide from Guides to Contributing section Addresses review feedback: move the local CLI testing guide out of the Guides nav group and into the Contributing section alongside contributing.mdx. --- docs/docs.json | 3 +- docs/guides/testing-local-changes.mdx | 128 -------------------------- 2 files changed, 1 insertion(+), 130 deletions(-) delete mode 100644 docs/guides/testing-local-changes.mdx diff --git a/docs/docs.json b/docs/docs.json index 361a6fed0..6deb4074f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -54,8 +54,7 @@ "guides/templates", "guides/rendering", "guides/common-mistakes", - "guides/troubleshooting", - "guides/testing-local-changes" + "guides/troubleshooting" ] } ] diff --git a/docs/guides/testing-local-changes.mdx b/docs/guides/testing-local-changes.mdx deleted file mode 100644 index f8cfec389..000000000 --- a/docs/guides/testing-local-changes.mdx +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Testing Local CLI Changes -description: How to test unreleased CLI changes outside the monorepo using your local build. ---- - -When you modify the CLI or any package it bundles (core, engine, producer, studio), you need to test those changes against real projects _outside_ the monorepo — the same way an end user would run `hyperframes dev`. - -## Prerequisites - -Build the monorepo first. Every time you change source files, rebuild before testing. - -```bash -# From the monorepo root -pnpm build -``` - -## Option 1: pnpm link (recommended) - -`pnpm link --global` makes the `hyperframes` binary in your `$PATH` point at your local build. It survives across terminal sessions and auto-picks up new builds without re-linking. - -```bash -# One-time setup -cd packages/cli -pnpm link --global - -# Verify — should print your local version -hyperframes --version -``` - -Now use `hyperframes` normally in any directory: - -```bash -cd ~/my-video-project -hyperframes dev . -``` - -**After every `pnpm build`** the linked binary is already up to date — no re-linking needed. - -To restore the published release when you're done: - -```bash -pnpm unlink --global hyperframes -npm install -g hyperframes@latest -``` - -## Option 2: node alias (no PATH changes) - -If you don't want to touch your global `$PATH`, add a shell alias or call `node` directly: - -```bash -# Temporary alias for your current shell session -alias hyperframes="node /path/to/hyperframes-oss/packages/cli/dist/cli.js" - -# Or invoke directly -node /path/to/hyperframes-oss/packages/cli/dist/cli.js dev . -``` - -Replace `/path/to/hyperframes-oss` with your actual monorepo path. - -## Option 3: npm pack (test the exact published artifact) - -Use this when you want to verify what would actually ship in a release, including the bundled studio and templates. - -```bash -cd packages/cli -npm pack -# Creates: hyperframes-.tgz - -# Test it in an isolated directory -mkdir /tmp/pack-test && cd /tmp/pack-test -npx /path/to/hyperframes-oss/packages/cli/hyperframes-.tgz init my-video -cd my-video -npx /path/to/hyperframes-oss/packages/cli/hyperframes-.tgz dev . -``` - -## Testing the fix branches - -When validating a specific bug fix, extract one of the test project archives and run through the scenario: - -```bash -# Example: testing audio-after-seek fix -unzip golden-lyric-video.zip && cd golden-lyric-video -hyperframes dev . -# 1. Press Play — confirm audio plays -# 2. Drag the timeline scrubber to a different position -# 3. Press Play again — audio should resume from the seeked position -``` - -Common test scenarios: - -| Bug | Project | Steps | -|---|---|---| -| Audio silent after seek | `golden-lyric-video` | Play → seek → play again, verify audio | -| Render stuck at 0% | any | Renders tab → Export → watch progress bar | -| Download 404 after restart | any | Complete a render → `Ctrl+C` → restart → Download | -| Timeline stops early | `intro-vid` | Play → should reach `0:05`, not stop at `0:03` | -| Lottie missing | `hyperframe-build-up-demo` | Play → rocket visible during 0–2 s | -| Blank thumbnails | any | Compositions sidebar should show previews | - -## Troubleshooting - -**Changes not reflected after `pnpm build`** - -The CLI binary is a single bundled file at `packages/cli/dist/cli.js`. If your change is in `@hyperframes/core` or another workspace package, make sure `pnpm build` rebuilt _all_ packages — the CLI bundles its dependencies at build time. - -**`hyperframes` still shows the old version** - -Check which binary is active: - -```bash -which hyperframes -hyperframes --version -``` - -If it points to a global npm installation rather than your link, uninstall the npm version first: - -```bash -npm uninstall -g hyperframes -cd packages/cli && pnpm link --global -``` - -**Port already in use** - -`hyperframes dev` defaults to port 3002 and auto-increments if it's taken. Pass `--port` to use a specific port: - -```bash -hyperframes dev . --port 4000 -``` From 61231cd1992d87c3295ab688a096a0725ff40c0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Mon, 30 Mar 2026 23:36:00 +0200 Subject: [PATCH 3/4] feat(studio): remove home page, auto-select first project on load Removes ProjectPicker, ProjectCard, and ExpandedPreviewIframe components. On mount, the studio now auto-fetches /api/projects and navigates directly to the first project instead of showing a selection screen. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- packages/studio/src/App.tsx | 302 +++--------------------------------- 1 file changed, 20 insertions(+), 282 deletions(-) diff --git a/packages/studio/src/App.tsx b/packages/studio/src/App.tsx index 63fd5db1f..8993f6f5c 100644 --- a/packages/studio/src/App.tsx +++ b/packages/studio/src/App.tsx @@ -16,12 +16,6 @@ interface EditingFile { content: string | null; } -interface ProjectEntry { - id: string; - title?: string; - sessionId?: string; -} - interface LintFinding { severity: "error" | "warning"; message: string; @@ -29,8 +23,6 @@ interface LintFinding { fixHint?: string; } -import { ExpandOnHover } from "./components/ui/ExpandOnHover"; - // ── Media file detection and preview ── const IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|svg|ico)$/i; @@ -122,246 +114,6 @@ function MediaPreview({ projectId, filePath }: { projectId: string; filePath: st ); } -// ── Project Card with hover-to-preview ── - -function ExpandedPreviewIframe({ src }: { src: string }) { - const containerRef = useRef(null); - const iframeRef = useRef(null); - const [dims, setDims] = useState({ w: 1920, h: 1080 }); - const [scale, setScale] = useState(1); - - // Recalculate scale when container resizes or dims change. - // Note: useEffect with [dims] dep — syncs with ResizeObserver (external system). - // eslint-disable-next-line no-restricted-syntax - useEffect(() => { - const el = containerRef.current; - if (!el) return; - const update = () => { - const cw = el.clientWidth; - const ch = el.clientHeight; - // Fit the composition inside the container (contain, not cover) - const s = Math.min(cw / dims.w, ch / dims.h); - setScale(s); - }; - update(); - const ro = new ResizeObserver(update); - ro.observe(el); - return () => ro.disconnect(); - }, [dims]); - - // After iframe loads: detect composition dimensions, seek, and play - const handleLoad = useCallback(() => { - const iframe = iframeRef.current; - if (!iframe) return; - let attempts = 0; - const interval = setInterval(() => { - try { - const doc = iframe.contentDocument; - if (doc) { - const comp = doc.querySelector("[data-composition-id]") as HTMLElement | null; - if (comp) { - const w = parseInt(comp.getAttribute("data-width") ?? "0", 10); - const h = parseInt(comp.getAttribute("data-height") ?? "0", 10); - if (w > 0 && h > 0) setDims({ w, h }); - } - } - const win = iframe.contentWindow as Window & { - __player?: { seek: (t: number) => void; play: () => void }; - }; - if (win?.__player) { - win.__player.seek(2); - win.__player.play(); - clearInterval(interval); - } - } catch { - /* cross-origin */ - } - if (++attempts > 25) clearInterval(interval); - }, 200); - }, []); - - // Center the scaled iframe - const offsetX = containerRef.current - ? (containerRef.current.clientWidth - dims.w * scale) / 2 - : 0; - const offsetY = containerRef.current - ? (containerRef.current.clientHeight - dims.h * scale) / 2 - : 0; - - return ( -
-