Skip to content

Commit 7f19f23

Browse files
jrusso1020claude
andauthored
feat(studio): load GSAP from the CLI's bundled copy by default (#6256)
* feat(studio): load GSAP from the CLI's bundled copy by default Studio preview now loads the GSAP, CustomEase and MotionPathPlugin scripts it adds from files the CLI ships and serves same-origin at /api/vendor/npm, instead of jsDelivr. HYPERFRAMES_GSAP_BASE_URL still wins when set, and a composition on another GSAP version gets its plugin from jsDelivr. Renders now honor HYPERFRAMES_GSAP_BASE_URL when they replace a missing local GSAP script, and the setting accepts plain http only for loopback hosts. Closes #6205 Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * refactor(studio): keep comment share flat for the GSAP local root Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): find the installed gsap with node resolution when run from source The Windows CI lane installs with the hoisted linker, so gsap is not under packages/core/node_modules there. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(producer): load a nested composition's missing GSAP from the mirror A sub-composition's missing local gsap/dist script was hoisted into the render unchanged, so HYPERFRAMES_GSAP_BASE_URL (and the jsDelivr fallback) only reached the entry document. Run the same rewrite on every sub-composition before it is compiled, resolving its path the way the inliner will hoist it. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent eed6ab3 commit 7f19f23

13 files changed

Lines changed: 585 additions & 47 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -879,10 +879,12 @@ The server picks one of three modes by itself: **embedded** (the default for
879879
**monorepo** (the studio dev server, when you run from the source repo).
880880
`--background` works with the embedded server only.
881881

882-
To load the GSAP dependencies Studio adds from a local or private mirror, set
883-
`HYPERFRAMES_GSAP_BASE_URL` before starting the server. See
884-
[Serve GSAP from your own mirror](/packages/studio-server#serve-gsap-from-your-own-mirror)
885-
for the directory layout, restart requirements, and authored-resource scope.
882+
The CLI ships GSAP, CustomEase, and MotionPathPlugin, so the GSAP scripts
883+
Studio adds to previews load from the preview server itself, not from jsDelivr.
884+
To use your own mirror instead, set `HYPERFRAMES_GSAP_BASE_URL` before starting
885+
the server. See
886+
[Where Studio loads GSAP from](/packages/studio-server#where-studio-loads-gsap-from)
887+
for the lookup order, the mirror layout, and what the setting does not cover.
886888

887889
<Note>
888890
Preview plays in real time, so paint-heavy compositions can stutter on your

‎docs/packages/studio-server.mdx‎

Lines changed: 51 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -66,47 +66,81 @@ the bundler inlines can be served with ids that a later save does not mint.
6666
bundle: (dir, options) => bundleToSingleHtml(dir, { runtime: "inline", ...options }),
6767
```
6868

69-
## Serve GSAP from your own mirror
69+
## Where Studio loads GSAP from
7070

71-
Studio can load the GSAP dependencies it adds from a local or private mirror
72-
when jsDelivr is unavailable. Set `HYPERFRAMES_GSAP_BASE_URL` before starting
73-
the preview server or creating the Studio API:
71+
Studio adds GSAP scripts to previews when a composition needs them: the GSAP
72+
core and CustomEase for motion you edit in Studio, and MotionPathPlugin for
73+
motion paths. It picks the source in this order:
74+
75+
1. `HYPERFRAMES_GSAP_BASE_URL`, when set. Studio uses only that mirror and
76+
never retries through jsDelivr.
77+
2. The host's bundled copy, when the host passes `gsapLocalRoot`. The
78+
HyperFrames CLI ships GSAP `3.15.0` and serves it from
79+
`/api/vendor/npm`, so `npx hyperframes preview` makes no jsDelivr request for
80+
these scripts. The bundled copy holds one version: a composition that loads
81+
another GSAP version, such as `[email protected]`, still gets the matching plugin
82+
from jsDelivr.
83+
3. jsDelivr (`https://cdn.jsdelivr.net/npm`), for hosts without a bundled copy.
84+
85+
A host embedding this package opts in by serving the files and naming the
86+
root:
87+
88+
```ts
89+
gsapLocalRoot: "/api/vendor/npm", // serves /api/vendor/npm/[email protected]/dist/gsap.min.js
90+
```
91+
92+
`gsapLocalRoot` must be a path on the preview's own origin, such as
93+
`/api/vendor/npm`, with no query or fragment.
94+
95+
### Use your own mirror
96+
97+
Set `HYPERFRAMES_GSAP_BASE_URL` before starting the preview server or creating
98+
the Studio API:
7499

75100
```bash
76101
HYPERFRAMES_GSAP_BASE_URL=http://127.0.0.1:8080/vendor/npm \
77102
npx hyperframes preview ./my-video
78103
```
79104

80-
Serve the GSAP distribution files under that URL with this layout, using the
81-
versions your compositions need:
105+
The mirror is an HTTP server, not a folder: a file path is refused. Serve the
106+
GSAP distribution files under that URL with this layout, using the versions
107+
your compositions need:
82108

83109
```text
84110
<mirror-root>/[email protected]/dist/gsap.min.js
85111
<mirror-root>/[email protected]/dist/CustomEase.min.js
86112
<mirror-root>/[email protected]/dist/MotionPathPlugin.min.js
87113
```
88114

89-
Studio uses the mirror for the GSAP, CustomEase, and MotionPathPlugin scripts
90-
it adds to previews, including dependencies loaded when you edit motion.
91115
Keep `gsap@<version>` in authored GSAP URLs so the server can infer which
92116
plugin version to add. When it cannot infer a version, it uses the framework's
93117
default, currently `3.15.0`.
94118

95-
The base must be an absolute HTTP(S) URL without credentials, a query string,
96-
or a fragment. Surrounding whitespace and trailing slashes are removed.
97-
An unset or empty value uses `https://cdn.jsdelivr.net/npm`; an invalid
98-
nonempty value stops API startup with a configuration error.
119+
The base must be an absolute URL without credentials, a query string, or a
120+
fragment. Use HTTPS. Plain `http://` is accepted only for this machine:
121+
`localhost`, `127.0.0.0/8`, and `::1`. Surrounding whitespace and trailing
122+
slashes are removed. An invalid nonempty value stops API startup with a
123+
configuration error.
99124

100125
The server reads this setting once at startup. Restart it after changing the
101126
value. For a managed CLI preview, run `npx hyperframes preview ./my-video --stop`
102127
before starting it again with the new setting. Cached preview HTML is keyed
103-
by the normalized mirror URL, so a different mirror takes effect after restart
128+
by the GSAP source, so a different mirror takes effect after restart
104129
without deleting the preview cache.
105130

106-
This setting changes only dependencies Studio adds. Your composition's own
107-
script, font, image, and media URLs stay as authored; serve those locally too
108-
for an offline project. If the selected mirror is unavailable or lacks a
109-
requested file, Studio does not retry that dependency through jsDelivr.
131+
Renders read the same setting. When a composition points at a local
132+
`gsap/dist/` script that does not exist, the render compiler loads that file
133+
from the mirror instead of jsDelivr and inlines it, as it does for other
134+
remote scripts. An invalid value fails that render with the same
135+
configuration error. Renders do not use the CLI's bundled copy.
136+
137+
This setting changes only GSAP scripts HyperFrames adds. Your composition's
138+
own script, font, image, and media URLs stay as authored, including a GSAP
139+
`<script>` that points at jsDelivr; serve those locally too for an offline
140+
project. When Studio writes GSAP into a composition file, for example when you
141+
add the first animation to a file without one, it writes the jsDelivr URL so
142+
the file still renders outside Studio. If the selected mirror is unavailable or lacks a requested file,
143+
Studio does not retry that dependency through jsDelivr.
110144

111145
## Other entry points
112146

‎packages/cli/scripts/build-copy.mjs‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,17 @@
11
// Cross-platform replacement for the previous `mkdir -p … && cp -r …` shell
22
// chain, which failed on Windows because `cp` doesn't accept `-r` there.
33

4-
import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
4+
import {
5+
chmodSync,
6+
copyFileSync,
7+
cpSync,
8+
existsSync,
9+
mkdirSync,
10+
readFileSync,
11+
readdirSync,
12+
rmSync,
13+
} from "node:fs";
14+
import { createRequire } from "node:module";
515
import { dirname, join, resolve } from "node:path";
616
import { fileURLToPath } from "node:url";
717
import { setTimeout as sleep } from "node:timers/promises";
@@ -57,6 +67,36 @@ function copyMdFiles(srcDir, destDir) {
5767
}
5868
}
5969

70+
// Studio preview loads these from the CLI's own server instead of jsDelivr
71+
// (studioServer.ts serves dist/vendor/npm). They come from the workspace's
72+
// installed gsap, which must match the version core asks for, or Studio would
73+
// quietly fall back to the CDN for every preview.
74+
const GSAP_VENDOR_FILES = ["gsap.min.js", "CustomEase.min.js", "MotionPathPlugin.min.js"];
75+
76+
function copyGsapVendorFiles() {
77+
const coreRequire = createRequire(join(REPO_ROOT, "packages", "core", "package.json"));
78+
const gsapRoot = dirname(coreRequire.resolve("gsap/package.json"));
79+
const { version } = JSON.parse(readFileSync(join(gsapRoot, "package.json"), "utf-8"));
80+
const coreSource = readFileSync(
81+
join(REPO_ROOT, "packages", "core", "src", "gsapCdn.ts"),
82+
"utf-8",
83+
);
84+
const expected = coreSource.match(/GSAP_CDN_VERSION = "([^"]+)"/)?.[1];
85+
if (version !== expected) {
86+
throw new Error(
87+
`[build-copy] installed gsap ${version} does not match GSAP_CDN_VERSION ${expected}`,
88+
);
89+
}
90+
const vendorDir = join(DIST, "vendor", "npm");
91+
rmSync(vendorDir, { recursive: true, force: true });
92+
const dest = join(vendorDir, `gsap@${version}`, "dist");
93+
mkdirSync(dest, { recursive: true });
94+
for (const file of GSAP_VENDOR_FILES) {
95+
copyFileSync(join(gsapRoot, "dist", file), join(dest, file));
96+
chmodSync(join(dest, file), 0o644);
97+
}
98+
}
99+
60100
// fallow-ignore-next-line complexity
61101
async function main() {
62102
for (const sub of ["studio", "docs", "templates", "skills", "docker"]) {
@@ -155,6 +195,8 @@ async function main() {
155195
}
156196
}
157197

198+
copyGsapVendorFiles();
199+
158200
copyMdFiles(join(CLI_ROOT, "src", "docs"), join(DIST, "docs"));
159201

160202
console.log("[build-copy] done");

‎packages/cli/src/server/studioServer.previewAssets.test.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,61 @@ describe("studio preview document", () => {
8383
expect(response.headers.get("ETag")).toBeNull();
8484
});
8585
});
86+
87+
describe("bundled GSAP", () => {
88+
const plugin = "/api/vendor/npm/[email protected]/dist/MotionPathPlugin.min.js";
89+
90+
function writeMotionPathComposition(): void {
91+
fs.writeFileSync(
92+
path.join(projectDir, "index.html"),
93+
`<!doctype html>
94+
<html><head><script src="vendor/gsap.min.js"></script></head>
95+
<body><div id="root" data-composition-id="main" data-width="320" data-height="180">
96+
<div id="card"></div>
97+
<script>gsap.to("#card", { motionPath: { path: [{ x: 10, y: 10 }] } });</script>
98+
</div></body></html>`,
99+
);
100+
}
101+
102+
it("serves Studio's GSAP dependencies same-origin instead of from jsDelivr", async () => {
103+
writeMotionPathComposition();
104+
expect(server.adapter.gsapLocalRoot).toBe("/api/vendor/npm");
105+
const html = await (await server.app.request("/api/projects/film/preview")).text();
106+
expect(html).toContain(`src="${plugin}"`);
107+
expect(html).toContain('<meta name="hyperframes-gsap-base-url" content="/api/vendor/npm">');
108+
expect(html).not.toContain("jsdelivr");
109+
110+
for (const file of ["gsap.min.js", "CustomEase.min.js", "MotionPathPlugin.min.js"]) {
111+
const response = await server.app.request(`/api/vendor/npm/[email protected]/dist/${file}`);
112+
expect(response.status).toBe(200);
113+
expect(response.headers.get("Content-Type")).toContain("javascript");
114+
expect(await response.text()).toMatch(/^\/\*!\n \* \w+ 3\.15\.0/);
115+
}
116+
});
117+
118+
it.each([
119+
"/api/vendor/npm/[email protected]/dist/gsap.min.js",
120+
"/api/vendor/npm/[email protected]/dist/package.json",
121+
"/api/vendor/npm/[email protected]/dist/..%2Fpackage.json",
122+
"/api/vendor/npm/[email protected]/dist/gsap.min.js",
123+
])("serves only the bundled GSAP files: %s", async (url) => {
124+
expect((await server.app.request(url)).status).toBe(404);
125+
});
126+
127+
it("uses HYPERFRAMES_GSAP_BASE_URL over the bundled copy", async () => {
128+
writeMotionPathComposition();
129+
const mirror = "https://mirror.example/npm";
130+
const previous = process.env.HYPERFRAMES_GSAP_BASE_URL;
131+
process.env.HYPERFRAMES_GSAP_BASE_URL = mirror;
132+
try {
133+
server.watcher.close();
134+
server = createStudioServer({ projectDir, projectName: "film" });
135+
const html = await (await server.app.request("/api/projects/film/preview")).text();
136+
expect(html).toContain(`src="${mirror}/[email protected]/dist/MotionPathPlugin.min.js"`);
137+
expect(html).not.toContain("/api/vendor/npm");
138+
} finally {
139+
if (previous === undefined) delete process.env.HYPERFRAMES_GSAP_BASE_URL;
140+
else process.env.HYPERFRAMES_GSAP_BASE_URL = previous;
141+
}
142+
});
143+
});

‎packages/cli/src/server/studioServer.ts‎

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,10 @@ import { existsSync, readFileSync, statSync, writeFileSync, unlinkSync } from "n
1212
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
1313
import { createHash } from "node:crypto";
1414
import { fileURLToPath } from "node:url";
15-
import { resolve, join, basename, relative, sep } from "node:path";
15+
import { resolve, join, basename, dirname, relative, sep } from "node:path";
16+
import { createRequire } from "node:module";
1617
import { readBundleFile } from "./readBundleFile.js";
18+
import { GSAP_CDN_VERSION } from "@hyperframes/core/gsap-cdn";
1719
import {
1820
createProjectWatcher,
1921
shouldWatchProjectFile,
@@ -171,6 +173,39 @@ function resolveRuntimePath(): string {
171173
return builtPath;
172174
}
173175

176+
// Same-origin root for the GSAP files the CLI ships (build-copy.mjs), laid out
177+
// like an npm mirror so preview can ask for `<root>/gsap@<version>/dist/<file>`.
178+
const GSAP_LOCAL_ROOT = "/api/vendor/npm";
179+
const GSAP_VENDOR_FILES = new Set(["gsap.min.js", "CustomEase.min.js", "MotionPathPlugin.min.js"]);
180+
181+
function installedGsapDist(): string | null {
182+
try {
183+
const coreRequire = createRequire(resolve(__dirname, "..", "..", "..", "core", "package.json"));
184+
return join(dirname(coreRequire.resolve("gsap/package.json")), "dist");
185+
} catch {
186+
return null;
187+
}
188+
}
189+
190+
/** The bundled GSAP dist dir, or null so preview keeps loading GSAP from jsDelivr. */
191+
function resolveGsapVendorDir(): string | null {
192+
const vendored = join("vendor", "npm", `gsap@${GSAP_CDN_VERSION}`, "dist");
193+
const candidates = [
194+
resolve(__dirname, vendored),
195+
// Running from source: the built CLI next door, then core's installed gsap.
196+
resolve(__dirname, "..", "..", "dist", vendored),
197+
installedGsapDist(),
198+
];
199+
for (const dir of candidates) {
200+
if (!dir) continue;
201+
if (!existsSync(join(dir, "gsap.min.js"))) continue;
202+
const manifest = readBundleFile(join(dir, "..", "package.json"));
203+
if (manifest && JSON.parse(manifest.toString("utf-8")).version !== GSAP_CDN_VERSION) continue;
204+
return dir;
205+
}
206+
return null;
207+
}
208+
174209
function readStudioManualEditManifestContent(projectDir: string): string {
175210
const manifestPath = join(projectDir, STUDIO_MANUAL_EDITS_PATH);
176211
if (!existsSync(manifestPath)) return "";
@@ -434,6 +469,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
434469
const browserGpuMode = options.browserGpuMode ?? resolveLocalBrowserGpuMode();
435470
const studioDir = resolveDistDir();
436471
const runtimePath = resolveRuntimePath();
472+
const gsapVendorDir = resolveGsapVendorDir();
437473
stampProjectHfIds(projectDir);
438474
const watcher = createProjectWatcher(projectDir);
439475

@@ -572,6 +608,7 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
572608
),
573609

574610
runtimeUrl: "/api/runtime.js",
611+
gsapLocalRoot: gsapVendorDir ? GSAP_LOCAL_ROOT : undefined,
575612

576613
rendersDir: () => join(projectDir, "renders"),
577614

@@ -897,6 +934,22 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
897934
return serve();
898935
});
899936

937+
// Bundled GSAP for preview, so opening Studio makes no jsDelivr request.
938+
app.get(`${GSAP_LOCAL_ROOT}/:pkg/dist/:file`, (c) => {
939+
const file = c.req.param("file");
940+
const body =
941+
gsapVendorDir &&
942+
c.req.param("pkg") === `gsap@${GSAP_CDN_VERSION}` &&
943+
GSAP_VENDOR_FILES.has(file)
944+
? readBundleFile(join(gsapVendorDir, file))
945+
: null;
946+
if (!body) return c.text("not found", 404);
947+
return c.body(body, 200, {
948+
"Content-Type": getMimeType(file),
949+
"Cache-Control": "public, max-age=31536000, immutable",
950+
});
951+
});
952+
900953
// CLI → Studio telemetry identity endpoint (Layer 1). Studio reads the
901954
// injected `window.__HF_CLI_DISTINCT_ID` first; this GET is a fallback for
902955
// clients that can't rely on the injected global. Returns the CLI's anonymous

0 commit comments

Comments
 (0)