From a4eea984d9ae7e3eb1dd7fe6974ab7a8f675655b Mon Sep 17 00:00:00 2001 From: James Date: Thu, 7 May 2026 02:38:27 +0000 Subject: [PATCH 1/2] feat(cli): add --resolution flag to hyperframes init for 4k scaffolding --- docs/packages/cli.mdx | 1 + packages/cli/src/commands/init.test.ts | 112 +++++++++++++++++++++- packages/cli/src/commands/init.ts | 126 ++++++++++++++++++++++++- 3 files changed, 236 insertions(+), 3 deletions(-) diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index bf492833f..ca7df21e6 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -162,6 +162,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_ | Flag | Description | |------|-------------| | `--example, -e` | Example to scaffold (required in default mode, interactive in `--human-friendly`) | + | `--resolution` | Canvas preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` (2160×3840). Aliases: `1080p`, `4k`, `uhd`. Default: keep template dimensions. | | `--video, -V` | Path to a video file (MP4, WebM, MOV) | | `--audio, -a` | Path to an audio file (MP3, WAV, M4A) | | `--tailwind` | Add Tailwind CSS browser-runtime support to scaffolded HTML | diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts index 1e905509b..ef7dbf561 100644 --- a/packages/cli/src/commands/init.test.ts +++ b/packages/cli/src/commands/init.test.ts @@ -1,10 +1,10 @@ import { describe, expect, it } from "vitest"; import { spawnSync } from "node:child_process"; -import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; -import { injectTailwindBrowserScript } from "./init.js"; +import { applyResolutionPreset, injectTailwindBrowserScript } from "./init.js"; const cliEntry = resolve(fileURLToPath(import.meta.url), "..", "..", "cli.ts"); const tailwindScript = @@ -146,3 +146,111 @@ describe("hyperframes init flag rename", () => { } }); }); + +describe("applyResolutionPreset", () => { + function withFixture(fn: (dir: string) => void): void { + const dir = mkdtempSync(join(tmpdir(), "hf-resolution-test-")); + try { + mkdirSync(dir, { recursive: true }); + fn(dir); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + } + + const sampleHtml = [ + "", + '', + " ", + ' ', + " ", + " ", + " ", + '
', + "
", + " ", + "", + ].join("\n"); + + it("rewrites every dimension fingerprint for landscape-4k", () => { + withFixture((dir) => { + const file = join(dir, "index.html"); + writeFileSync(file, sampleHtml, "utf-8"); + + applyResolutionPreset(dir, "landscape-4k"); + const out = readFileSync(file, "utf-8"); + + expect(out).toContain('data-resolution="landscape-4k"'); + expect(out).toContain('data-width="3840"'); + expect(out).toContain('data-height="2160"'); + expect(out).toContain("width: 3840px"); + expect(out).toContain("height: 2160px"); + expect(out).toContain('content="width=3840, height=2160"'); + expect(out).not.toContain("1920"); + expect(out).not.toContain("1080"); + }); + }); + + it("swaps to portrait dimensions for portrait-4k", () => { + withFixture((dir) => { + const file = join(dir, "index.html"); + writeFileSync(file, sampleHtml, "utf-8"); + + applyResolutionPreset(dir, "portrait-4k"); + const out = readFileSync(file, "utf-8"); + + expect(out).toContain('data-width="2160"'); + expect(out).toContain('data-height="3840"'); + expect(out).toContain('data-resolution="portrait-4k"'); + }); + }); + + it("scaffolds a 4k project end-to-end via --resolution 4k", () => { + const dir = mkdtempSync(join(tmpdir(), "hf-init-test-")); + const target = join(dir, "proj"); + try { + const res = runInit([ + target, + "--example", + "blank", + "--resolution", + "4k", + "--non-interactive", + "--skip-skills", + ]); + expect(res.status).toBe(0); + + const html = readFileSync(join(target, "index.html"), "utf-8"); + expect(html).toContain('data-width="3840"'); + expect(html).toContain('data-height="2160"'); + expect(html).toContain('data-resolution="landscape-4k"'); + expect(html).toContain("width: 3840px"); + expect(html).toContain("height: 2160px"); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); + + it("rejects an unknown --resolution value", () => { + const dir = mkdtempSync(join(tmpdir(), "hf-init-test-")); + const target = join(dir, "proj"); + try { + const res = runInit([ + target, + "--example", + "blank", + "--resolution", + "8k", + "--non-interactive", + "--skip-skills", + ]); + expect(res.status).toBe(1); + expect(res.stderr).toContain("Invalid --resolution"); + expect(existsSync(target)).toBe(false); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); +}); diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 798d20763..4f20a1544 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -4,6 +4,8 @@ import type { Example } from "./_examples.js"; export const examples: Example[] = [ ["Create a project with the interactive wizard", "hyperframes init my-video"], ["Pick a starter example", "hyperframes init my-video --example warm-grain"], + ["Scaffold a 4K project", "hyperframes init my-video --resolution 4k"], + ["Scaffold a portrait video", "hyperframes init my-video --resolution portrait"], ["Start from an existing video file", "hyperframes init my-video --video clip.mp4"], ["Start from an audio file", "hyperframes init my-video --audio track.mp3"], ["Scaffold with Tailwind CSS", "hyperframes init my-video --example blank --tailwind"], @@ -34,6 +36,34 @@ import { fetchRemoteTemplate } from "../templates/remote.js"; import { trackInitTemplate } from "../telemetry/events.js"; import { hasFFmpeg } from "../whisper/manager.js"; import { VERSION } from "../version.js"; +import { CANVAS_DIMENSIONS, type CanvasResolution } from "@hyperframes/core"; + +const VALID_RESOLUTIONS: readonly CanvasResolution[] = [ + "landscape", + "portrait", + "landscape-4k", + "portrait-4k", +] as const; + +const RESOLUTION_ALIASES: Record = { + "1080p": "landscape", + hd: "landscape", + "1080p-portrait": "portrait", + "portrait-1080p": "portrait", + "4k": "landscape-4k", + uhd: "landscape-4k", + "4k-portrait": "portrait-4k", + "portrait-4k": "portrait-4k", +}; + +function normalizeResolutionFlag(input: string | undefined): CanvasResolution | undefined { + if (!input) return undefined; + const lowered = input.toLowerCase(); + if ((VALID_RESOLUTIONS as readonly string[]).includes(lowered)) { + return lowered as CanvasResolution; + } + return RESOLUTION_ALIASES[lowered]; +} interface VideoMeta { durationSeconds: number; @@ -416,6 +446,70 @@ async function handleVideoFile( return { meta, localVideoName }; } +// --------------------------------------------------------------------------- +// applyResolutionPreset — rewrite stage dimensions in scaffolded HTML +// --------------------------------------------------------------------------- + +/** + * Templates ship with 1920×1080 dimensions baked into multiple places. + * When the user picks a non-default resolution we walk every HTML file in + * the scaffold and rewrite the dimension fingerprint: + * - `data-width` / `data-height` on the root composition + * - `data-resolution` on the element (added when missing) + * - the `width`/`height` declared in the inline `html, body { ... }` CSS + * - the `` tag's `width=`/`height=` parts + * We rewrite by regex rather than DOM-parsing because templates have + * decorative comments and indentation we want to preserve byte-for-byte. + */ +export function applyResolutionPreset(destDir: string, resolution: CanvasResolution): void { + const { width, height } = CANVAS_DIMENSIONS[resolution]; + for (const file of listHtmlFiles(destDir)) { + let html = readFileSync(file, "utf-8"); + let changed = false; + + const dataWidthRe = /(data-width=)["'](\d+)["']/g; + if (dataWidthRe.test(html)) { + html = html.replace(dataWidthRe, `$1"${width}"`); + changed = true; + } + const dataHeightRe = /(data-height=)["'](\d+)["']/g; + if (dataHeightRe.test(html)) { + html = html.replace(dataHeightRe, `$1"${height}"`); + changed = true; + } + + const htmlOpenRe = /]*)>/i; + const htmlOpen = html.match(htmlOpenRe); + if (htmlOpen) { + const attrs = htmlOpen[1] ?? ""; + let next: string; + if (/data-resolution=/.test(attrs)) { + next = attrs.replace(/data-resolution=["'][^"']*["']/, `data-resolution="${resolution}"`); + } else { + next = `${attrs.replace(/\s+$/, "")} data-resolution="${resolution}"`; + } + if (next !== attrs) { + html = html.replace(htmlOpenRe, ``); + changed = true; + } + } + + const bodyCssRe = /(html\s*,\s*body\s*\{[^}]*?width:\s*)\d+px([^}]*?height:\s*)\d+px/i; + if (bodyCssRe.test(html)) { + html = html.replace(bodyCssRe, `$1${width}px$2${height}px`); + changed = true; + } + + const viewportRe = /(]*name=["']viewport["'][^>]*content=["'])width=\d+,\s*height=\d+/i; + if (viewportRe.test(html)) { + html = html.replace(viewportRe, `$1width=${width}, height=${height}`); + changed = true; + } + + if (changed) writeFileSync(file, html, "utf-8"); + } +} + // --------------------------------------------------------------------------- // scaffoldProject — copy template, patch video refs, write meta.json // --------------------------------------------------------------------------- @@ -427,6 +521,7 @@ async function scaffoldProject( localVideoName: string | undefined, durationSeconds?: number, tailwind = false, + resolution?: CanvasResolution, ): Promise { mkdirSync(destDir, { recursive: true }); @@ -439,6 +534,7 @@ async function scaffoldProject( } patchVideoSrc(destDir, localVideoName, durationSeconds); if (tailwind) writeTailwindSupport(destDir); + if (resolution) applyResolutionPreset(destDir, resolution); writeFileSync( resolve(destDir, "meta.json"), @@ -540,6 +636,11 @@ export default defineCommand({ type: "boolean", description: "Add Tailwind CSS browser-runtime support", }, + resolution: { + type: "string", + description: + "Canvas resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840). Aliases: 1080p, 4k, uhd. Default: keep template dimensions (typically 1920x1080).", + }, }, async run({ args }) { if (args.template !== undefined) { @@ -563,6 +664,20 @@ export default defineCommand({ const languageFlag = args.language; const interactive = !nonInteractive && process.stdout.isTTY === true; + let resolutionPreset: CanvasResolution | undefined; + if (args.resolution !== undefined) { + resolutionPreset = normalizeResolutionFlag(args.resolution); + if (!resolutionPreset) { + console.error( + c.error( + `Invalid --resolution: "${args.resolution}". ` + + `Use one of: landscape, portrait, landscape-4k, portrait-4k (or aliases 1080p, 4k, uhd).`, + ), + ); + process.exit(1); + } + } + // ----------------------------------------------------------------------- // Non-interactive mode — all inputs from flags, defaults where missing // ----------------------------------------------------------------------- @@ -645,6 +760,7 @@ export default defineCommand({ localVideoName, videoDuration, tailwind, + resolutionPreset, ); } catch (err) { console.error( @@ -840,7 +956,15 @@ export default defineCommand({ spin.start(`Downloading example ${c.accent(templateId)}...`); } try { - await scaffoldProject(destDir, name, templateId, localVideoName, videoDuration, tailwind); + await scaffoldProject( + destDir, + name, + templateId, + localVideoName, + videoDuration, + tailwind, + resolutionPreset, + ); if (!isBundled) { spin.stop(c.success(`Downloaded ${templateId}`)); } From 9f0074e44a80c851f5771f6012ade59d3828842c Mon Sep 17 00:00:00 2001 From: James Date: Thu, 7 May 2026 05:33:22 +0000 Subject: [PATCH 2/2] fix(cli): handle reverse-order CSS in applyResolutionPreset and document scope --- packages/cli/src/commands/init.test.ts | 57 ++++++++++++++++++++++++++ packages/cli/src/commands/init.ts | 26 ++++++++---- 2 files changed, 74 insertions(+), 9 deletions(-) diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts index ef7dbf561..59cfa7ca4 100644 --- a/packages/cli/src/commands/init.test.ts +++ b/packages/cli/src/commands/init.test.ts @@ -253,4 +253,61 @@ describe("applyResolutionPreset", () => { rmSync(dir, { recursive: true, force: true }); } }); + + it("rewrites height-before-width inline CSS", () => { + withFixture((dir) => { + const file = join(dir, "index.html"); + // Reversed property order — same as the parser's stageMatchReverse path. + const reversedOrderHtml = sampleHtml.replace( + "html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; }", + "html, body { margin: 0; height: 1080px; width: 1920px; overflow: hidden; }", + ); + writeFileSync(file, reversedOrderHtml, "utf-8"); + + applyResolutionPreset(dir, "landscape-4k"); + const out = readFileSync(file, "utf-8"); + + expect(out).toContain("height: 2160px"); + expect(out).toContain("width: 3840px"); + expect(out).not.toContain("1080px"); + expect(out).not.toContain("1920px"); + }); + }); + + it("is a no-op on a file with no dimension fingerprint (does not error)", () => { + withFixture((dir) => { + const file = join(dir, "fragment.html"); + // No data-width/height, no html/body block, no viewport — just markup. + const minimal = "

hi

"; + writeFileSync(file, minimal, "utf-8"); + + expect(() => applyResolutionPreset(dir, "landscape-4k")).not.toThrow(); + const out = readFileSync(file, "utf-8"); + // The htmlOpenRe path adds `data-resolution="landscape-4k"` because + // the tag is present. That's correct: an explicit signal of + // intended resolution survives even when no dim fields exist. + expect(out).toContain('data-resolution="landscape-4k"'); + }); + }); + + it("accepts uppercase --resolution value (4K)", () => { + const dir = mkdtempSync(join(tmpdir(), "hf-init-test-")); + const target = join(dir, "proj"); + try { + const res = runInit([ + target, + "--example", + "blank", + "--resolution", + "4K", + "--non-interactive", + "--skip-skills", + ]); + expect(res.status).toBe(0); + const html = readFileSync(join(target, "index.html"), "utf-8"); + expect(html).toContain('data-width="3840"'); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); }); diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index 4f20a1544..d31cad686 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -451,15 +451,16 @@ async function handleVideoFile( // --------------------------------------------------------------------------- /** - * Templates ship with 1920×1080 dimensions baked into multiple places. - * When the user picks a non-default resolution we walk every HTML file in - * the scaffold and rewrite the dimension fingerprint: - * - `data-width` / `data-height` on the root composition - * - `data-resolution` on the element (added when missing) - * - the `width`/`height` declared in the inline `html, body { ... }` CSS - * - the `` tag's `width=`/`height=` parts - * We rewrite by regex rather than DOM-parsing because templates have - * decorative comments and indentation we want to preserve byte-for-byte. + * Rewrite the canvas dimensions in every scaffolded HTML file to match a + * preset. We rewrite by regex rather than DOM-parsing so template comments + * and indentation survive byte-for-byte — these are review-target files, + * not transient build artifacts. + * + * Scope: HTML files only. Templates whose `#stage` dimensions live in an + * external `.css` stylesheet are not patched — the bundled `blank` template + * inlines its CSS, and that's the convention for new templates. If you + * author a template with external CSS, replicate the dimension swap there + * by hand or move the dimensions inline. */ export function applyResolutionPreset(destDir: string, resolution: CanvasResolution): void { const { width, height } = CANVAS_DIMENSIONS[resolution]; @@ -494,11 +495,18 @@ export function applyResolutionPreset(destDir: string, resolution: CanvasResolut } } + // Inline `html, body { ... }` CSS: handle width-before-height and + // height-before-width orderings. Hand-authored templates can use either. const bodyCssRe = /(html\s*,\s*body\s*\{[^}]*?width:\s*)\d+px([^}]*?height:\s*)\d+px/i; if (bodyCssRe.test(html)) { html = html.replace(bodyCssRe, `$1${width}px$2${height}px`); changed = true; } + const bodyCssReverseRe = /(html\s*,\s*body\s*\{[^}]*?height:\s*)\d+px([^}]*?width:\s*)\d+px/i; + if (bodyCssReverseRe.test(html)) { + html = html.replace(bodyCssReverseRe, `$1${height}px$2${width}px`); + changed = true; + } const viewportRe = /(]*name=["']viewport["'][^>]*content=["'])width=\d+,\s*height=\d+/i; if (viewportRe.test(html)) {