Skip to main content
The studio-server package is the HTTP backend that powers studio preview and editing — project routes, file serving, preview bundling, thumbnails, and source-mutation helpers. It was extracted from @hyperframes/core/studio-api into a dedicated package so an embedder can mount the studio backend without depending on core’s full surface, and so core no longer ships a web server it doesn’t need at render time. 
npm install @hyperframes/studio-server

​
When to Use

Most users do not need this package directly. The CLI (npx hyperframes preview) and studio wire it up for you. Reach for it when you’re embedding the studio backend into your own server.
Use @hyperframes/studio-server when you need to:
  • Mount the studio preview/editing API into an existing Node/Hono server
  • Serve project files and bundled preview HTML to a custom frontend
  • Drive source mutations (manual edits, draft markers) from your own tooling
@hyperframes/core/studio-api still resolves (via a back-compat re-export stub), so existing imports keep working. New code should import from @hyperframes/studio-server directly.

​
Package Exports

ImportDescription
@hyperframes/studio-servercreateStudioApi, helpers, types
@hyperframes/studio-server/screenshot-clipElement screenshot-clip geometry
@hyperframes/studio-server/manual-edits-render-scriptManual-edits render body script
@hyperframes/studio-server/studio-motion-render-scriptStudio motion render body script
@hyperframes/studio-server/draft-markersDraft gesture-marker attributes
@hyperframes/studio-server/finite-mutationFinite-mutation safety checks

​
Mounting the API

createStudioApi returns a Hono app you can mount into any server. You supply a StudioApiAdapter that tells the API how to resolve projects, bundle preview HTML, and lint: 
import { createStudioApi } from '@hyperframes/studio-server';
import type { StudioApiAdapter, ResolvedProject } from '@hyperframes/studio-server';

const adapter: StudioApiAdapter = {
  listProjects: () => projects,
  resolveProject: (id) => projectsById.get(id) ?? null,
  bundle: async (projectDir) => bundleToSingleHtml(projectDir),
  lint: (html, opts) => lintHyperframeHtml(html, opts),
  runtimeUrl: '/hyperframe-runtime.js',
};

const api = createStudioApi(adapter); // → Hono app

// Mount under /api in your own Hono server
app.route('/api', api);
The adapter is the seam between the framework-agnostic route logic and your storage / bundling / lint implementation — the CLI supplies a filesystem-backed adapter, but you can back it with anything.

​
Helpers

import {
  createProjectSignature,   // cache key for a project's files
  isSafePath,               // path-traversal guard
  walkDir,
  getMimeType,
  buildSubCompositionHtml,
  getElementScreenshotClip,
} from '@hyperframes/studio-server';
import type {
  ResolvedProject,
  RenderJobState,
  LintResult,
  ScreenshotClip,
} from '@hyperframes/studio-server';

Studio

The browser editor UI this server backs.

@hyperframes/parsers

The HTML + GSAP parsing layer it builds on.

@hyperframes/core

Types and runtime; re-exports the studio API for back-compat.

CLI

npx hyperframes preview wires this server up for you.