From fa318d9727b6c0f691939325445b5d003c762f92 Mon Sep 17 00:00:00 2001 From: Michael Wang Date: Wed, 4 Nov 2026 23:19:51 +0000 Subject: [PATCH] feat(cli,docs): links to our sites say where they came from (#7178) README links to hyperframes.studio, hyperframes.heygen.com and heygen.com carry utm_source=github&utm_medium=readme, the values the README's download links already use. Three README links went through docs redirects that drop the query string (/showcase, /guides/claude-design, /guides/open-design); they now point at the pages themselves. The docs navbar's Community and changelog links carry src=docs-navbar, and the export page's reinstall link src=docs-export, beside the existing docs-* tags. Links the CLI prints to our sites (init's docs links, the Lambda docs, the publish claim URL, the HeyGen API-key page) carry utm_source=cli. Discord invites stay untagged. Co-authored-by: Claude Opus 5.5 --- README.md | 100 +++++++++--------- docs/docs.json | 4 +- docs/studio-app/export.mdx | 2 +- .../cli/src/commands/auth/status-guidance.ts | 3 +- packages/cli/src/commands/init.ts | 7 +- .../commands/lambda/prebuiltHandler.test.ts | 4 +- .../src/commands/lambda/prebuiltHandler.ts | 3 +- packages/cli/src/commands/publish.ts | 3 +- packages/cli/src/utils/sourceTag.test.ts | 27 +++++ packages/cli/src/utils/sourceTag.ts | 10 ++ 10 files changed, 104 insertions(+), 59 deletions(-) create mode 100644 packages/cli/src/utils/sourceTag.test.ts create mode 100644 packages/cli/src/utils/sourceTag.ts diff --git a/README.md b/README.md index f84b4d4f64..e4fc97da5d 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,12 @@

Write HTML. Render video. Built for agents.

- Studio | - Quickstart | - Showcase | - Playground | - Catalog | - Docs | + Studio | + Quickstart | + Showcase | + Playground | + Catalog | + Docs | Discord

@@ -124,7 +124,7 @@ This writes `dist/hyperframes-plugin.zip` with a `hyperframes/` root folder and | `/reverse-any-video` | Rebuilding any video file as an editable HyperFrames project (motion graphics, talking heads, live action, AI-generated footage), checked frame by frame against the original. HyperFrames Pro. | | `/style-sampling` | Making a new episode on your topic in one of five proven styles: Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime. HyperFrames Pro. | -For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design) and [Open Design guide](https://hyperframes.heygen.com/guides/open-design). +For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/design-tools?utm_source=github&utm_medium=readme#start-from-claude-design-or-open-design) and [Open Design guide](https://hyperframes.heygen.com/guides/design-tools?utm_source=github&utm_medium=readme#start-from-claude-design-or-open-design). ### Manually with the CLI @@ -139,7 +139,7 @@ npx hyperframes render # render to MP4 ## What You Can Build -Need ideas? Browse the [Showcase](https://hyperframes.heygen.com/showcase) for finished videos you can watch, read, run, and remix. +Need ideas? Browse the [Showcase](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme) for finished videos you can watch, read, run, and remix. - Product launch videos and feature announcements - PR walkthroughs with animated code diffs, narration, and captions @@ -159,57 +159,57 @@ The output is a `DESIGN.md` superset your whole toolchain can read. Atoms stay s
- Biennale Yellow -
Biennale Yellow + Biennale Yellow +
Biennale Yellow
- BlockFrame -
BlockFrame + BlockFrame +
BlockFrame
- Blue Professional -
Blue Professional + Blue Professional +
Blue Professional
- Bold Poster -
Bold Poster + Bold Poster +
Bold Poster
- Broadside -
Broadside + Broadside +
Broadside
- Capsule -
Capsule + Capsule +
Capsule
- Cartesian -
Cartesian + Cartesian +
Cartesian
- Cobalt Grid -
Cobalt Grid + Cobalt Grid +
Cobalt Grid
- Coral -
Coral + Coral +
Coral
- Creative Mode -
Creative Mode + Creative Mode +
Creative Mode
-Browse and remix them all at [hyperframes.studio/design](https://hyperframes.studio/design). +Browse and remix them all at [hyperframes.studio/design](https://hyperframes.studio/design?utm_source=github&utm_medium=readme). ## How It Works @@ -253,16 +253,16 @@ Preview instantly in the browser. Render locally or in Docker. The renderer seek HyperFrames is the open-source rendering engine, plus a growing set of tools around HTML-native video creation. -| Piece | Status | What it does | -| ------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------- | -| CLI | Available | Scaffold, preview, lint, inspect, and render local video projects | -| Core / Engine / Producer | Available | Parse compositions, drive headless Chrome, encode video, and mix audio | -| Catalog | Available | Reusable blocks and components for transitions, overlays, captions, charts, maps, and effects | -| Agent skills | Available | Teach coding agents the video-production patterns that generic web docs miss | -| Studio | Available, evolving | Browser surface for previewing and editing compositions | -| AWS Lambda rendering | Available | Deploy a distributed render stack and drive renders from your laptop or CI | -| [hyperframes.studio](https://hyperframes.studio/) | Available | Community playground for previewing, iterating, sharing, and rendering HTML-native video projects | -| [frame.md](https://hyperframes.studio/design) | Available | Invert your design system for the camera — a DESIGN.md superset an agent can compose video from | +| Piece | Status | What it does | +| ------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------- | +| CLI | Available | Scaffold, preview, lint, inspect, and render local video projects | +| Core / Engine / Producer | Available | Parse compositions, drive headless Chrome, encode video, and mix audio | +| Catalog | Available | Reusable blocks and components for transitions, overlays, captions, charts, maps, and effects | +| Agent skills | Available | Teach coding agents the video-production patterns that generic web docs miss | +| Studio | Available, evolving | Browser surface for previewing and editing compositions | +| AWS Lambda rendering | Available | Deploy a distributed render stack and drive renders from your laptop or CI | +| [hyperframes.studio](https://hyperframes.studio/?utm_source=github&utm_medium=readme) | Available | Community playground for previewing, iterating, sharing, and rendering HTML-native video projects | +| [frame.md](https://hyperframes.studio/design?utm_source=github&utm_medium=readme) | Available | Invert your design system for the camera — a DESIGN.md superset an agent can compose video from | ## Catalog @@ -274,7 +274,7 @@ npx hyperframes add instagram-follow # social overlay npx hyperframes add data-chart # animated chart ``` -Browse the catalog at [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart). +Browse the catalog at [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart?utm_source=github&utm_medium=readme). ## Why HyperFrames? @@ -298,19 +298,19 @@ HyperFrames is inspired by [Remotion](https://www.remotion.dev). Both tools rend | Distributed rendering | Local and AWS Lambda render paths | Remotion Lambda, mature cloud renderer | | License | Apache 2.0 | Source-available Remotion License | -Read the full comparison in the [HyperFrames vs Remotion guide](https://hyperframes.heygen.com/guides/hyperframes-vs-remotion). +Read the full comparison in the [HyperFrames vs Remotion guide](https://hyperframes.heygen.com/guides/hyperframes-vs-remotion?utm_source=github&utm_medium=readme). ## Documentation -Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.heygen.com/introduction) +Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.heygen.com/introduction?utm_source=github&utm_medium=readme) -- [Quickstart](https://hyperframes.heygen.com/quickstart) -- [Showcase](https://hyperframes.heygen.com/showcase) -- [Guides](https://hyperframes.heygen.com/guides/gsap-animation) -- [API Reference](https://hyperframes.heygen.com/packages/core) -- [Catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart) -- [Examples](https://hyperframes.heygen.com/examples) -- [AWS Lambda rendering](https://hyperframes.heygen.com/deploy/aws-lambda) +- [Quickstart](https://hyperframes.heygen.com/quickstart?utm_source=github&utm_medium=readme) +- [Showcase](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme) +- [Guides](https://hyperframes.heygen.com/guides/gsap-animation?utm_source=github&utm_medium=readme) +- [API Reference](https://hyperframes.heygen.com/packages/core?utm_source=github&utm_medium=readme) +- [Catalog](https://hyperframes.heygen.com/catalog/blocks/data-chart?utm_source=github&utm_medium=readme) +- [Examples](https://hyperframes.heygen.com/examples?utm_source=github&utm_medium=readme) +- [AWS Lambda rendering](https://hyperframes.heygen.com/deploy/aws-lambda?utm_source=github&utm_medium=readme) ## Packages @@ -327,7 +327,7 @@ Full documentation: [hyperframes.heygen.com/introduction](https://hyperframes.he ## Community -HyperFrames is used in production at [HeyGen](https://www.heygen.com), with community examples from teams like [tldraw](https://tldraw.com), [TanStack](https://tanstack.com), and others in [ADOPTERS.md](ADOPTERS.md). Open a PR if your team is using HyperFrames. +HyperFrames is used in production at [HeyGen](https://www.heygen.com?utm_source=github&utm_medium=readme), with community examples from teams like [tldraw](https://tldraw.com), [TanStack](https://tanstack.com), and others in [ADOPTERS.md](ADOPTERS.md). Open a PR if your team is using HyperFrames. - Questions and ideas: [Discord](https://discord.gg/fzbdWyjphr) - Bugs and feature requests: [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) diff --git a/docs/docs.json b/docs/docs.json index b6aca7a5f8..1ad3c55479 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -326,13 +326,13 @@ "item": "Community", "icon": "users", "description": "Videos people made", - "href": "https://hyperframes.studio/?view=community" + "href": "https://hyperframes.studio/?view=community&src=docs-navbar" }, { "item": "App changelog", "icon": "sparkles", "description": "What's new in the app", - "href": "https://hyperframes.studio/changelog" + "href": "https://hyperframes.studio/changelog?src=docs-navbar" } ] }, diff --git a/docs/studio-app/export.mdx b/docs/studio-app/export.mdx index 3356362485..65b5c3a501 100644 --- a/docs/studio-app/export.mdx +++ b/docs/studio-app/export.mdx @@ -73,7 +73,7 @@ Watch the exported file once from start to end before you send it. - **The video was made but could not be saved to your Downloads folder**: free up space or check that the Downloads folder exists, then export again. - **HyperFrames could not start its built-in FFmpeg**: the app may be damaged. Reinstall it from - [hyperframes.studio/studio](https://hyperframes.studio/studio). + [hyperframes.studio/studio](https://hyperframes.studio/studio?src=docs-export). ## Related topics diff --git a/packages/cli/src/commands/auth/status-guidance.ts b/packages/cli/src/commands/auth/status-guidance.ts index 866dc17212..7f3dc8390d 100644 --- a/packages/cli/src/commands/auth/status-guidance.ts +++ b/packages/cli/src/commands/auth/status-guidance.ts @@ -8,6 +8,7 @@ */ import { c } from "../../ui/colors.js"; +import { cliSourced } from "../../utils/sourceTag.js"; export interface UnconfiguredContext { /** A human can act on guidance now — a TTY, or a coding agent driving the CLI. */ @@ -88,7 +89,7 @@ export function buildUnconfiguredLines( "Sign in or sign up (browser OAuth, writes ~/.hyperframes — no per-repo .env):", ` ${c.accent("npx hyperframes auth login")} ${c.dim("# browser sign-in / sign-up")}`, "", - "Or paste an existing HeyGen API key (get one at app.heygen.com/settings/api):", + `Or paste an existing HeyGen API key (get one at ${cliSourced("https://app.heygen.com/settings/api")}):`, ` ${c.accent("npx hyperframes auth login --api-key")} ${c.dim("# paste at the prompt")}`, "", ...offlineEngineLines(engines), diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts index f9d6c5acbc..eb901b7a4e 100644 --- a/packages/cli/src/commands/init.ts +++ b/packages/cli/src/commands/init.ts @@ -60,6 +60,7 @@ import { VIEWPORT_META_SIZE_RE, } from "@hyperframes/parsers"; import { decodableAudioStream } from "@hyperframes/parsers/media-streams"; +import { cliSourced } from "../utils/sourceTag.js"; function resolveScaffoldTemplateId(exampleFlag: string | undefined, hasMediaFile: boolean): string { const example = exampleFlag === "agent" ? "blank" : exampleFlag; @@ -997,7 +998,9 @@ export default defineCommand({ console.log( ` ${c.dim('"Using /hyperframes, create a 15-second intro about [your topic]"')}`, ); - console.log(` ${c.dim("More patterns: hyperframes.heygen.com/prompting/overview")}`); + console.log( + ` ${c.dim(`More patterns: ${cliSourced("https://hyperframes.heygen.com/prompting/overview")}`)}`, + ); console.log(); console.log(` ${c.accent("4.")} Preview in the browser:`); console.log(` ${c.accent(`cd ${name}`)} && ${c.accent("npm run dev")}`); @@ -1008,7 +1011,7 @@ export default defineCommand({ console.log(` ${c.accent("6.")} Render to MP4 when ready:`); console.log(` ${c.accent(`cd ${name}`)} && ${c.accent("npm run render")}`); console.log(); - console.log(` ${c.dim("Full docs: hyperframes.heygen.com")}`); + console.log(` ${c.dim(`Full docs: ${cliSourced("https://hyperframes.heygen.com")}`)}`); return; } diff --git a/packages/cli/src/commands/lambda/prebuiltHandler.test.ts b/packages/cli/src/commands/lambda/prebuiltHandler.test.ts index 9817463e6c..f07f1d67fa 100644 --- a/packages/cli/src/commands/lambda/prebuiltHandler.test.ts +++ b/packages/cli/src/commands/lambda/prebuiltHandler.test.ts @@ -109,7 +109,9 @@ describe("stagePrebuiltHandler with nothing to deploy", () => { const message = noHandlerMessage(false); expect(message).toMatch(/npm install -g @hyperframes\/aws-lambda@/); expect(message).toMatch(/HYPERFRAMES_REPO_ROOT/); - expect(message).toMatch(/^Docs: https:\/\/hyperframes\.heygen\.com\/deploy\/aws-lambda$/m); + expect(message).toMatch( + /^Docs: https:\/\/hyperframes\.heygen\.com\/deploy\/aws-lambda\?utm_source=cli$/m, + ); expect(downloads).toEqual([]); }); diff --git a/packages/cli/src/commands/lambda/prebuiltHandler.ts b/packages/cli/src/commands/lambda/prebuiltHandler.ts index 2a6df0fae6..481b6098d5 100644 --- a/packages/cli/src/commands/lambda/prebuiltHandler.ts +++ b/packages/cli/src/commands/lambda/prebuiltHandler.ts @@ -16,8 +16,9 @@ import { downloadFile } from "../../utils/download.js"; import { isMissingPackageError } from "../../utils/missingPackage.js"; import { VERSION } from "../../version.js"; import { hyperframesCacheDir } from "@hyperframes/core/cache-dir"; +import { cliSourced } from "../../utils/sourceTag.js"; -const DOCS_URL = "https://hyperframes.heygen.com/deploy/aws-lambda"; +const DOCS_URL = cliSourced("https://hyperframes.heygen.com/deploy/aws-lambda"); const HANDLER_CACHE_DIR = hyperframesCacheDir("lambda-handler"); type AdapterSdk = typeof import("@hyperframes/aws-lambda/sdk"); diff --git a/packages/cli/src/commands/publish.ts b/packages/cli/src/commands/publish.ts index f81c4d937e..2584165245 100644 --- a/packages/cli/src/commands/publish.ts +++ b/packages/cli/src/commands/publish.ts @@ -29,6 +29,7 @@ import { readTeamProject, writeTeamProject, } from "../utils/projectLink.js"; +import { cliSourced } from "../utils/sourceTag.js"; export const examples: Example[] = [ ["Publish the current project privately to a stable URL", "hyperframes publish"], @@ -313,7 +314,7 @@ export default defineCommand({ } else { const claimUrl = new URL(published.url); claimUrl.searchParams.set("claim_token", published.claimToken); - console.log(` ${c.dim("Claim URL")} ${c.accent(claimUrl.toString())}`); + console.log(` ${c.dim("Claim URL")} ${c.accent(cliSourced(claimUrl.toString()))}`); console.log(` ${c.dim("Access")} ${c.accent("Sign in required to claim")}`); console.log(); console.log( diff --git a/packages/cli/src/utils/sourceTag.test.ts b/packages/cli/src/utils/sourceTag.test.ts new file mode 100644 index 0000000000..09c5dc00b7 --- /dev/null +++ b/packages/cli/src/utils/sourceTag.test.ts @@ -0,0 +1,27 @@ +import { describe, expect, it } from "vitest"; +import { cliSourced } from "./sourceTag.js"; + +describe("cliSourced", () => { + it("tags our sites with utm_source=cli, keeping the query and fragment", () => { + expect(cliSourced("https://hyperframes.heygen.com/prompting/overview")).toBe( + "https://hyperframes.heygen.com/prompting/overview?utm_source=cli", + ); + expect(cliSourced("https://hyperframes.studio/p/abc?claim_token=t#top")).toBe( + "https://hyperframes.studio/p/abc?claim_token=t&utm_source=cli#top", + ); + expect(cliSourced("https://app.heygen.com/settings/api")).toBe( + "https://app.heygen.com/settings/api?utm_source=cli", + ); + }); + + it("leaves other hosts, look-alikes, an existing source and non-URLs alone", () => { + for (const url of [ + "https://github.com/heygen-com/hyperframes", + "https://hyperframes.app/", + "https://notheygen.com/", + "https://hyperframes.studio/?utm_source=github", + "not a url", + ]) + expect(cliSourced(url)).toBe(url); + }); +}); diff --git a/packages/cli/src/utils/sourceTag.ts b/packages/cli/src/utils/sourceTag.ts new file mode 100644 index 0000000000..496474cbc7 --- /dev/null +++ b/packages/cli/src/utils/sourceTag.ts @@ -0,0 +1,10 @@ +// A link the CLI prints to one of our sites says it came from the CLI; a link that already names a source keeps it. +const OUR_HOST = /(^|\.)(hyperframes\.studio|hyperframes\.heygen\.com|heygen\.com)$/; + +export function cliSourced(url: string): string { + if (!URL.canParse(url)) return url; + const parsed = new URL(url); + if (!OUR_HOST.test(parsed.hostname) || parsed.searchParams.has("utm_source")) return url; + parsed.searchParams.set("utm_source", "cli"); + return parsed.toString(); +}