fix(cli): preview uses the bundled Studio unless local Studio mode is opted in (#7551)

Local Studio mode runs Vite in the resolved @hyperframes/studio folder, so the
project folder decided which config and binary ran. Use it only when the
project resolves to the same Studio the CLI itself resolves (a source checkout
running its own build) or when HYPERFRAMES_LOCAL_STUDIO=1 is set; otherwise
serve the embedded Studio.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-11-11 10:55:59 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 84799bdc59
commit 668983e1a6
3 changed files with 128 additions and 23 deletions
+5 -2
View File
@@ -1065,8 +1065,11 @@ sub-compositions refresh live. Preview and render share the same runtime.
The server picks one of three modes by itself: **embedded** (the default for
`npx` — Studio bundled in the CLI, no extra dependencies), **local studio**
(Vite with full HMR, when `@hyperframes/studio` is in your `node_modules`), or
**monorepo** (the studio dev server, when you run from the source repo).
(Vite with full HMR, from a `@hyperframes/studio` source checkout), or
**monorepo** (the studio dev server, when you run from the source repo). Local
studio mode runs only when the project resolves to the same Studio checkout as
the CLI itself, or when you set `HYPERFRAMES_LOCAL_STUDIO=1`; a Studio in the
project's own `node_modules` is not used otherwise.
`--background` works with the embedded server only.
The CLI ships GSAP, CustomEase, and MotionPathPlugin, so the GSAP scripts
+77 -1
View File
@@ -1,4 +1,12 @@
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
realpathSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
@@ -15,6 +23,7 @@ import {
prebuildPreview,
handlePreviewKillAll,
handlePreviewList,
localStudioDir,
previewHostAppError,
previewLaunchMode,
previewLaunchModeError,
@@ -407,6 +416,59 @@ describe("previewLaunchMode", () => {
});
});
/** A project folder that carries its own @hyperframes/studio with a Vite config and binary. */
function projectWithOwnStudio(): { project: string; studio: string; marker: string } {
const root = mkdtempSync(join(tmpdir(), "hf-preview-own-studio-"));
tempDirs.push(root);
const project = join(root, "project");
const studio = join(project, "node_modules", "@hyperframes", "studio");
const bin = join(project, "node_modules", ".bin");
const marker = join(root, "ran");
mkdirSync(studio, { recursive: true });
mkdirSync(bin, { recursive: true });
writeFileSync(join(project, "package.json"), '{"name":"project"}');
writeFileSync(join(studio, "package.json"), '{"name":"@hyperframes/studio","version":"0.0.0"}');
writeFileSync(
join(studio, "vite.config.ts"),
`require("node:fs").writeFileSync(${JSON.stringify(marker)}, "config");\nexport default {};\n`,
);
writeFileSync(join(bin, "vite"), `#!/bin/sh\necho bin > ${JSON.stringify(marker)}\n`);
chmodSync(join(bin, "vite"), 0o755);
return { project, studio: realpathSync(studio), marker };
}
describe("localStudioDir", () => {
const interactive = { background: false, foreground: false, interactive: true, devMode: false };
it("serves the bundled Studio when the project brings its own", () => {
const { project } = projectWithOwnStudio();
const dir = localStudioDir(project, {});
expect(dir).toBeNull();
expect(previewLaunchMode({ ...interactive, localStudio: dir !== null })).toBe("embedded");
});
it("ignores a Studio in a parent folder's node_modules", () => {
const { project } = projectWithOwnStudio();
const nested = join(project, "nested");
mkdirSync(nested);
writeFileSync(join(nested, "package.json"), '{"name":"nested"}');
expect(localStudioDir(nested, {})).toBeNull();
});
it("uses the project's Studio when the user opts in", () => {
const { project, studio } = projectWithOwnStudio();
const dir = localStudioDir(project, { HYPERFRAMES_LOCAL_STUDIO: "1" });
expect(dir).toBe(studio);
expect(previewLaunchMode({ ...interactive, localStudio: dir !== null })).toBe("local");
});
it("uses the project's Studio when it is the CLI's own", () => {
const { project, studio } = projectWithOwnStudio();
expect(localStudioDir(project, {}, studio)).toBe(studio);
expect(localStudioDir(project, {}, join(studio, "elsewhere"))).toBeNull();
});
});
describe("preview lifecycle JSON failures", () => {
it.each([
[
@@ -743,6 +805,20 @@ describe("studio dev-server spawns", () => {
expect(spawn).toHaveBeenCalledOnce();
expect(spawn.mock.calls[0]?.[2]).toMatchObject({ windowsHide: true });
});
it("runLocalStudioMode spawns nothing from a Studio the project brings", async () => {
const spawn = mockStudioSpawn();
vi.stubEnv("HYPERFRAMES_LOCAL_STUDIO", "");
const { project, marker } = projectWithOwnStudio();
try {
const { runLocalStudioMode } = await import("./preview.js");
await runLocalStudioMode(project, { json: true });
expect(spawn).not.toHaveBeenCalled();
expect(existsSync(marker)).toBe(false);
} finally {
vi.unstubAllEnvs();
}
});
});
describe("preview inside a host app's agent run", () => {
+46 -20
View File
@@ -33,7 +33,15 @@ export const examples: Example[] = [
"hyperframes preview --lint-verbose",
],
];
import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
import {
existsSync,
lstatSync,
mkdirSync,
readlinkSync,
realpathSync,
symlinkSync,
unlinkSync,
} from "node:fs";
import { resolve, dirname, basename, join } from "node:path";
import { fileURLToPath } from "node:url";
import { createRequire } from "node:module";
@@ -492,7 +500,7 @@ export default defineCommand({
foreground: Boolean(args.foreground),
interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
devMode: isDevMode(),
localStudio: hasLocalStudio(dir),
localStudio: localStudioDir(dir) !== null,
});
const hostAppError = previewHostAppError(launchMode);
@@ -1517,27 +1525,37 @@ export async function runDevMode(dir: string, options?: StudioLaunchOptions): Pr
return waitForStudioChildClose(child);
}
/**
* Whether the project's local @hyperframes/studio can actually be SERVED.
*
* Local mode runs `vite` with the studio package as its cwd, so it needs that
* package's own `vite.config.ts` — which the published tarball does not carry
* (`files: ["src", "dist"]`). Resolving the package alone therefore is not
* enough: an npm-installed studio would send `preview` down a path that can
* never come up, and since `--background` re-execs this same CLI, it would time
* out after ten seconds instead of falling back. Fall back to embedded mode,
* which serves the same studio and does work from a published install.
*/
function hasLocalStudio(dir: string): boolean {
/** Set to 1 to let `preview` serve the project's own @hyperframes/studio with Vite. */
export const LOCAL_STUDIO_ENV = "HYPERFRAMES_LOCAL_STUDIO";
function studioPackageDir(from: string): string | null {
try {
const req = createRequire(join(dir, "package.json"));
const studioPkgPath = dirname(req.resolve("@hyperframes/studio/package.json"));
return existsSync(join(studioPkgPath, "vite.config.ts"));
const req = createRequire(from);
return realpathSync(dirname(req.resolve("@hyperframes/studio/package.json")));
} catch {
return false;
return null;
}
}
/**
* The @hyperframes/studio folder local mode may serve with Vite, or null for embedded mode.
* It needs the package's own `vite.config.ts`, which the published tarball lacks, so an
* npm-installed studio falls back to embedded instead of a launch that never comes up.
* Vite runs that config and the `vite` beside it as code, and a project folder (or a
* parent's node_modules) must not choose that code: the project's Studio is used only when
* it is the one the CLI itself resolves (a source checkout) or HYPERFRAMES_LOCAL_STUDIO=1.
*/
export function localStudioDir(
dir: string,
env: NodeJS.ProcessEnv = process.env,
cliStudioDir: string | null = studioPackageDir(fileURLToPath(import.meta.url)),
): string | null {
const studioDir = studioPackageDir(join(dir, "package.json"));
if (!studioDir || !existsSync(join(studioDir, "vite.config.ts"))) return null;
if (env[LOCAL_STUDIO_ENV] === "1") return studioDir;
return studioDir === cliStudioDir ? studioDir : null;
}
/**
* Local studio mode: spawn Vite using a locally installed @hyperframes/studio.
* Provides full Vite HMR and the complete studio experience.
@@ -1546,8 +1564,16 @@ export async function runLocalStudioMode(
dir: string,
options?: StudioLaunchOptions,
): Promise<void> {
const req = createRequire(join(dir, "package.json"));
const studioPkgPath = dirname(req.resolve("@hyperframes/studio/package.json"));
const studioPkgPath = localStudioDir(dir);
if (!studioPkgPath) {
reportPreviewFailure(
Boolean(options?.json),
"start",
"preview-start-failed",
`No local Studio to run for this project; set ${LOCAL_STUDIO_ENV}=1 to use the project's own @hyperframes/studio.`,
);
return;
}
const pName = options?.projectName ?? basename(dir);
// Symlink project into studio's data directory