From 5e8abd7574a78e159ac51761e62fa25179e151a5 Mon Sep 17 00:00:00 2001 From: Krish Sharma <99371181+krishs0404@users.noreply.github.com> Date: Sun, 8 Nov 2026 23:16:17 +0000 Subject: [PATCH] feat(cli): add 1440p resolution presets to --resolution (#7418) * feat(cli): add 1440p resolution presets to --resolution Adds landscape-1440p (2560x1440), portrait-1440p (1440x2560) and square-1440p (1440x1440) next to the existing 4K, 720p and 480p tiers, with the aliases 1440p, 2k and qhd plus 1440p-portrait and 1440p-square. 1440p joins the aspect-agnostic aliases, like 720p and 480p. Every validator derives from CANVAS_DIMENSIONS, so no logic changes: a 4K composition renders down to 1440p through the existing smaller-preset path, and a 1280x720 composition supersamples to 1440p at an exact 2x. A 1920x1080 composition is still refused by the non-integer-scale check (4/3); fractional scale factors are not part of this change. Refs #6309 Co-Authored-By: Claude Sonnet 5.5 * fix(cli): clarify 1440p aliases and repair skill validation --------- Co-authored-by: Claude Sonnet 5.5 Co-authored-by: James --- docs/packages/cli.mdx | 4 +- packages/cli/src/commands/init.test.ts | 19 +++++++++ packages/cli/src/commands/init.ts | 7 ++-- packages/cli/src/commands/render.test.ts | 15 +++++++ packages/cli/src/commands/render.ts | 2 +- packages/cli/src/commands/render/plan.ts | 5 ++- packages/core/src/index.test.ts | 16 ++++++++ .../src/outputResolutionCompatibility.test.ts | 40 +++++++++++++++++++ packages/parsers/src/types.ts | 9 +++++ skills-manifest.json | 2 +- .../references/init-and-scaffold.md | 4 +- .../references/preview-render.md | 2 + 12 files changed, 114 insertions(+), 11 deletions(-) diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index ce2d845bea..6e63a2266e 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -178,7 +178,7 @@ npx hyperframes init my-video --tailwind | Flag | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--example, -e` | Example to scaffold. Default is the centered blank. See [Examples](/examples) for the full list. | -| `--resolution` | Canvas preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` (2160×3840), `square` (1080×1080), `square-4k` (2160×2160). Aliases: `1080p`, `4k`, `uhd`, `1080p-square`, `square-1080p`, `4k-square`. Default: keep template dimensions. | +| `--resolution` | Canvas preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` (2160×3840), `square` (1080×1080), `square-4k` (2160×2160), `landscape-1440p` (2560×1440), `portrait-1440p` (1440×2560), `square-1440p` (1440×1440). Aliases: `1080p`, `4k`, `uhd`, `1440p`, `qhd`, `1080p-square`, `square-1080p`, `4k-square`, `1440p-portrait`, `1440p-square`. 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 the scaffolded HTML | @@ -1822,7 +1822,7 @@ The flags that come up most: | `--format` | `mp4` | `mp4`, `webm`, `mov`, `gif`, `png-sequence`, or `hls`. WebM and MOV carry transparency; `png-sequence` writes RGBA frames to a directory; `hls` writes a VOD playlist directory. | | `--fps, -f` | root `data-fps`, otherwise 30 | 1–240, or an ffmpeg rational like `30000/1001` for 29.97 | | `--quality, -q` | `looks` | `draft`, `looks` (CRF 16, default), `delivery` (= `high`), `standard`, or `high`. MOV always uses the fixed alpha-preserving ProRes 4444 profile. | -| `--resolution` | the composition's size | Supersample to a preset via Chrome's `deviceScaleFactor`. Aspect ratio must match and the scale must be a whole multiple. Not with `--hdr`. See [4K rendering](/guides/4k-rendering). | +| `--resolution` | the composition's size | Render to a preset via Chrome's `deviceScaleFactor`, including `landscape-1440p`, `portrait-1440p`, `square-1440p` (aliases `1440p`, `qhd`). Aspect ratio must match; upscaling requires an integer multiple. 720p→1440p and 4K→1440p work; 1080p→1440p is refused. Not with `--hdr`. See [4K rendering](/guides/4k-rendering). | | `--docker` | off | Render inside Docker for [deterministic output](/concepts/determinism) | | `--variables` | — | JSON object merged over the composition's `data-composition-variables` defaults | | `--variables-file` | — | Read those overrides from a JSON file instead | diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts index f84e07d452..2a8e60c906 100644 --- a/packages/cli/src/commands/init.test.ts +++ b/packages/cli/src/commands/init.test.ts @@ -625,6 +625,25 @@ describe("applyResolutionPreset", () => { }); }); + it("rewrites every dimension fingerprint for landscape-1440p", () => { + withFixture((dir) => { + const file = join(dir, "index.html"); + writeFileSync(file, sampleHtml, "utf-8"); + + applyResolutionPreset(dir, "landscape-1440p"); + const out = readFileSync(file, "utf-8"); + + expect(out).toContain('data-resolution="landscape-1440p"'); + expect(out).toContain('data-width="2560"'); + expect(out).toContain('data-height="1440"'); + expect(out).toContain("width: 2560px"); + expect(out).toContain("height: 1440px"); + expect(out).toContain('content="width=2560, height=1440"'); + 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"); diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index c4cc09e752..2cd0952447 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -842,7 +842,7 @@ export default defineCommand({ resolution: { type: "string", description: - "Canvas resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160). Aliases: 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square. Default: a --video clip's own shape as it plays, 1080 on the short side (4:3 -> 1440x1080), else the template's dimensions (typically 1920x1080).", + "Canvas resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160), landscape-1440p (2560x1440), portrait-1440p (1440x2560), square-1440p (1440x1440). Aliases: 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square. Default: a --video clip's own shape as it plays, 1080 on the short side (4:3 -> 1440x1080), else the template's dimensions (typically 1920x1080).", }, skill: { type: "string", @@ -894,8 +894,9 @@ export default defineCommand({ console.error( c.error( `Invalid --resolution: "${args.resolution}". ` + - `Use one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k ` + - `(or aliases 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square).`, + `Use one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k, ` + + `landscape-1440p, portrait-1440p, square-1440p ` + + `(or aliases 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`, ), ); failUsage(); diff --git a/packages/cli/src/commands/render.test.ts b/packages/cli/src/commands/render.test.ts index dc1e606a44..f852c3b87b 100644 --- a/packages/cli/src/commands/render.test.ts +++ b/packages/cli/src/commands/render.test.ts @@ -2089,6 +2089,21 @@ describe("checkRenderResolutionPreflight", () => { ).toBeUndefined(); }); + it("clears a landscape-1440p preset on a portrait 720p composition (an exact 2×)", async () => { + expect( + await checkRenderResolutionPreflight(comp(720, 1280), "landscape-1440p", agnostic), + ).toBeUndefined(); + }); + + it("refuses `--resolution 1440p` on a 1920×1080 composition: 4/3 is not an integer scale", async () => { + const result = await checkRenderResolutionPreflight( + landscapeHtml, + "landscape-1440p", + agnostic, + ); + expect(result?.kind).toBe("non-integer-scale"); + }); + it("clears a landscape preset on a square composition", async () => { // aspect > 1 → landscape, aspect = 1 → square. Both self-heal. expect( diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index 9e7381afae..3f8d7fa44b 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -384,7 +384,7 @@ export default defineCommand({ resolution: { type: "string", description: - "Output resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160). Aliases: 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square. The composition is unchanged — Chrome renders at higher DPR (deviceScaleFactor) so the captured screenshot lands at the requested dimensions. Aspect ratio must match the composition; the scale must be an integer multiple. Not yet supported with --hdr.", + "Output resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160), landscape-1440p (2560x1440), portrait-1440p (1440x2560), square-1440p (1440x1440). Aliases: 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square. The composition is unchanged — Chrome renders at higher DPR (deviceScaleFactor) so the captured screenshot lands at the requested dimensions. Aspect ratio must match the composition; upscaling requires an integer multiple. Not yet supported with --hdr.", }, "page-side-compositing": { type: "boolean", diff --git a/packages/cli/src/commands/render/plan.ts b/packages/cli/src/commands/render/plan.ts index 04402e6069..2b0a68e900 100644 --- a/packages/cli/src/commands/render/plan.ts +++ b/packages/cli/src/commands/render/plan.ts @@ -386,8 +386,9 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren if (!outputResolution) { errorBox( "Invalid resolution", - `Got "${args.resolution}". Must be one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k ` + - `(or aliases 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square).`, + `Got "${args.resolution}". Must be one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k, ` + + `landscape-1440p, portrait-1440p, square-1440p ` + + `(or aliases 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square).`, ); failUsage(); } diff --git a/packages/core/src/index.test.ts b/packages/core/src/index.test.ts index 730c14d7bf..c7c4f86346 100644 --- a/packages/core/src/index.test.ts +++ b/packages/core/src/index.test.ts @@ -12,6 +12,9 @@ describe("@hyperframes/core public API exports", () => { expect(core.CANVAS_DIMENSIONS["portrait-4k"]).toEqual({ width: 2160, height: 3840 }); expect(core.CANVAS_DIMENSIONS.square).toEqual({ width: 1080, height: 1080 }); expect(core.CANVAS_DIMENSIONS["square-4k"]).toEqual({ width: 2160, height: 2160 }); + expect(core.CANVAS_DIMENSIONS["landscape-1440p"]).toEqual({ width: 2560, height: 1440 }); + expect(core.CANVAS_DIMENSIONS["portrait-1440p"]).toEqual({ width: 1440, height: 2560 }); + expect(core.CANVAS_DIMENSIONS["square-1440p"]).toEqual({ width: 1440, height: 1440 }); }); it("exports VALID_CANVAS_RESOLUTIONS derived from CANVAS_DIMENSIONS", () => { @@ -22,6 +25,9 @@ describe("@hyperframes/core public API exports", () => { "portrait-4k", "square", "square-4k", + "landscape-1440p", + "portrait-1440p", + "square-1440p", "landscape-720p", "portrait-720p", "square-720p", @@ -41,6 +47,12 @@ describe("@hyperframes/core public API exports", () => { expect(core.normalizeResolutionFlag("square-4k")).toBe("square-4k"); expect(core.normalizeResolutionFlag("1080p-square")).toBe("square"); expect(core.normalizeResolutionFlag("4k-square")).toBe("square-4k"); + expect(core.normalizeResolutionFlag("1440p")).toBe("landscape-1440p"); + expect(core.normalizeResolutionFlag("2k")).toBeUndefined(); + expect(core.normalizeResolutionFlag("QHD")).toBe("landscape-1440p"); + expect(core.normalizeResolutionFlag("1440p-portrait")).toBe("portrait-1440p"); + expect(core.normalizeResolutionFlag("1440p-square")).toBe("square-1440p"); + expect(core.normalizeResolutionFlag("portrait-1440p")).toBe("portrait-1440p"); expect(core.normalizeResolutionFlag("8k")).toBeUndefined(); expect(core.normalizeResolutionFlag(undefined)).toBeUndefined(); }); @@ -51,6 +63,9 @@ describe("@hyperframes/core public API exports", () => { expect(core.isAspectAgnosticResolutionAlias("hd")).toBe(true); expect(core.isAspectAgnosticResolutionAlias("4k")).toBe(true); expect(core.isAspectAgnosticResolutionAlias("uhd")).toBe(true); + expect(core.isAspectAgnosticResolutionAlias("1440p")).toBe(true); + expect(core.isAspectAgnosticResolutionAlias("2k")).toBe(false); + expect(core.isAspectAgnosticResolutionAlias("qhd")).toBe(true); // Case-insensitive. expect(core.isAspectAgnosticResolutionAlias("1080P")).toBe(true); expect(core.isAspectAgnosticResolutionAlias("UHD")).toBe(true); @@ -59,6 +74,7 @@ describe("@hyperframes/core public API exports", () => { expect(core.isAspectAgnosticResolutionAlias("portrait-1080p")).toBe(false); expect(core.isAspectAgnosticResolutionAlias("4k-square")).toBe(false); expect(core.isAspectAgnosticResolutionAlias("1080p-square")).toBe(false); + expect(core.isAspectAgnosticResolutionAlias("1440p-portrait")).toBe(false); // Canonical presets → false. expect(core.isAspectAgnosticResolutionAlias("landscape")).toBe(false); expect(core.isAspectAgnosticResolutionAlias("portrait")).toBe(false); diff --git a/packages/parsers/src/outputResolutionCompatibility.test.ts b/packages/parsers/src/outputResolutionCompatibility.test.ts index 7c34794281..ef8a2f44a7 100644 --- a/packages/parsers/src/outputResolutionCompatibility.test.ts +++ b/packages/parsers/src/outputResolutionCompatibility.test.ts @@ -145,6 +145,46 @@ describe("checkOutputResolutionCompatibility", () => { }, ); + it.each([ + [1280, 720, "landscape-1440p"], + [720, 1280, "portrait-1440p"], + [720, 720, "square-1440p"], + [2560, 1440, "landscape-1440p"], + [3840, 2160, "landscape-1440p"], + [2160, 3840, "portrait-1440p"], + [2160, 2160, "square-1440p"], + ] as const)( + "allows %i×%i to %s (an exact multiple or a smaller preset)", + (compositionWidth, compositionHeight, outputResolution) => { + expect( + checkOutputResolutionCompatibility({ + compositionWidth, + compositionHeight, + outputResolution, + }), + ).toEqual({ ok: true }); + }, + ); + + it("refuses 1920×1080 to landscape-1440p: 4/3 is not an integer scale factor", () => { + const result = checkOutputResolutionCompatibility({ + compositionWidth: 1920, + compositionHeight: 1080, + outputResolution: "landscape-1440p", + }); + expect(result.kind).toBe("non-integer-scale"); + }); + + it("keeps the 1440p tier when suggesting a swap for the wrong orientation", () => { + const result = checkOutputResolutionCompatibility({ + compositionWidth: 2560, + compositionHeight: 1440, + outputResolution: "portrait-1440p", + }); + expect(result.kind).toBe("aspect-mismatch"); + expect(result.suggestedResolution).toBe("landscape-1440p"); + }); + it("keeps the 480p tier when suggesting a swap for the wrong orientation", () => { const result = checkOutputResolutionCompatibility({ compositionWidth: 1920, diff --git a/packages/parsers/src/types.ts b/packages/parsers/src/types.ts index 354fc7bb6a..1a8b26ff21 100644 --- a/packages/parsers/src/types.ts +++ b/packages/parsers/src/types.ts @@ -23,6 +23,9 @@ export const CANVAS_DIMENSIONS = { "portrait-4k": { width: 2160, height: 3840 }, square: { width: 1080, height: 1080 }, "square-4k": { width: 2160, height: 2160 }, + "landscape-1440p": { width: 2560, height: 1440 }, + "portrait-1440p": { width: 1440, height: 2560 }, + "square-1440p": { width: 1440, height: 1440 }, "landscape-720p": { width: 1280, height: 720 }, "portrait-720p": { width: 720, height: 1280 }, "square-720p": { width: 720, height: 720 }, @@ -56,6 +59,10 @@ const RESOLUTION_ALIASES: Record = { "1080p-square": "square", "square-1080p": "square", "4k-square": "square-4k", + "1440p": "landscape-1440p", + qhd: "landscape-1440p", + "1440p-portrait": "portrait-1440p", + "1440p-square": "square-1440p", "720p": "landscape-720p", "720p-portrait": "portrait-720p", "720p-square": "square-720p", @@ -83,6 +90,8 @@ const ASPECT_AGNOSTIC_RESOLUTION_ALIASES: ReadonlySet = new Set([ "hd", "4k", "uhd", + "1440p", + "qhd", "720p", "480p", ]); diff --git a/skills-manifest.json b/skills-manifest.json index 622eed2495..2f0321391d 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -10,7 +10,7 @@ "files": 78 }, "hyperframes-cli": { - "hash": "adcd30f21c700eba", + "hash": "53ea8e568639d20a", "files": 13 }, "hyperframes-registry": { diff --git a/skills/hyperframes-cli/references/init-and-scaffold.md b/skills/hyperframes-cli/references/init-and-scaffold.md index bc14e6964f..e47db20d60 100644 --- a/skills/hyperframes-cli/references/init-and-scaffold.md +++ b/skills/hyperframes-cli/references/init-and-scaffold.md @@ -1,6 +1,6 @@ # init, capture, skills - + Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, and run transcription. @@ -22,7 +22,7 @@ Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decisi Other useful flags: -- `--resolution` — preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k`, `portrait-4k`, `square` (1080×1080), `square-4k`. Aliases: `1080p`, `4k`, `uhd`, `1080p-square`, `4k-square`. +- `--resolution` — preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k`, `portrait-4k`, `square` (1080×1080), `square-4k`, `landscape-1440p` (2560×1440), `portrait-1440p`, `square-1440p`. Aliases: `1080p`, `4k`, `uhd`, `1440p`, `qhd`, `1080p-square`, `4k-square`. - `--skill=` — record the owning skill (e.g. `hyperframes`) in `hyperframes.json`, so every later render of this project — re-renders, `npm run render`, `--batch` — is attributed to it on usage telemetry without re-passing the flag. You rarely pass it by hand. - `--skip-skills` — leave AI coding skills alone: `init` does not install the core set. `HYPERFRAMES_SKIP_SKILLS=1` does the same. Always pass it: without it `init` installs any missing core skill, and installing skills is the person's step. When a core skill is missing, tell the person they can install it with `npx hyperframes skills update`. - `--skip-transcribe` — don't auto-transcribe `--audio` / `--video` with Whisper. diff --git a/skills/hyperframes-cli/references/preview-render.md b/skills/hyperframes-cli/references/preview-render.md index 19de7a6770..3978353d62 100644 --- a/skills/hyperframes-cli/references/preview-render.md +++ b/skills/hyperframes-cli/references/preview-render.md @@ -147,6 +147,8 @@ npx hyperframes render --docker # byte-identical **Quality guidance:** `draft` while iterating, `looks` (the default) for the first real encode, `delivery` for final delivery. `standard` and `high` still work. +The 1440p presets are `landscape-1440p` (2560×1440), `portrait-1440p` (1440×2560), and `square-1440p` (1440×1440). Aliases `1440p` and `qhd` follow the composition’s orientation. A 720p composition can upscale to 1440p at 2×, and a 4K composition can downscale to 1440p. A 1920×1080 composition cannot upscale to 1440p because 4/3 is not an integer scale; author at 1440p or render at 4K and downscale separately. + **Read the summary's second line.** After the output path and size, `render` prints the capture path, GPU mode, and per-stage timings, e.g. `beginframe capture · software gpu · compile 0.7s · setup 1.1s · capture 8.1s · encode 5.8s`. `capture` is the frame loop and `setup` is calibration plus session init; the capture path reads `a|b` when parallel workers diverged, and `encode (during capture)` means the streaming encoder overlapped the loop, so do not add it to the wall time. Local GPU `auto` (the default) requests BeginFrame. If the line still says `screenshot capture` with `software gpu` on Linux, a hint under it says BeginFrame did not run (needs chrome-headless-shell, no `--resolution` upscale). It only appears when the GPU was auto-probed, never under `--docker` or `--no-browser-gpu`, where software GL is the point. Heavy compositions can stall on software GL. Do not reach for `--debug` just to learn which path ran. **Parametrized renders:** the composition declares its variables on the `` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI `--variables '{"title":"Q4 Report"}'` is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. Sub-comp hosts can also override per-instance with `data-variable-values`. See `../../hyperframes/references/format.md` for the full pattern.