mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
ukimsanov
52d586dd31
Exhaustive audit of every MDX file in docs/ against skill references and package source code. Every API signature, default value, flag, and technical claim verified against ground truth.
100 lines
4.0 KiB
Plaintext
100 lines
4.0 KiB
Plaintext
---
|
|
title: "@hyperframes/studio-server"
|
|
description: "The studio preview/editor backend — a mountable Hono API, extracted from core."
|
|
---
|
|
|
|
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.
|
|
|
|
```bash
|
|
npm install @hyperframes/studio-server
|
|
```
|
|
|
|
## When to Use
|
|
|
|
<Tip>
|
|
**Most users do not need this package directly.** The [CLI](/packages/cli) (`npx hyperframes preview`) and [studio](/packages/studio) wire it up for you. Reach for it when you're **embedding** the studio backend into your own server.
|
|
</Tip>
|
|
|
|
**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
|
|
|
|
<Info>
|
|
`@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.
|
|
</Info>
|
|
|
|
## Package Exports
|
|
|
|
| Import | Description |
|
|
|--------|-------------|
|
|
| `@hyperframes/studio-server` | `createStudioApi`, helpers, types |
|
|
| `@hyperframes/studio-server/source-mutation` | Source mutation utilities |
|
|
| `@hyperframes/studio-server/screenshot-clip` | Element screenshot-clip geometry |
|
|
| `@hyperframes/studio-server/manual-edits-render-script` | Manual-edits render body script |
|
|
| `@hyperframes/studio-server/studio-motion-render-script` | Studio motion render body script |
|
|
| `@hyperframes/studio-server/draft-markers` | Draft gesture-marker attributes |
|
|
| `@hyperframes/studio-server/finite-mutation` | Finite-mutation safety checks |
|
|
|
|
## Mounting the API
|
|
|
|
`createStudioApi` returns a [Hono](https://hono.dev) app you can mount into any server. You supply a `StudioApiAdapter` that tells the API how to resolve projects, bundle preview HTML, and lint:
|
|
|
|
```typescript
|
|
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',
|
|
rendersDir: (project) => join(project.dir, 'renders'),
|
|
startRender: async (opts) => startRenderJob(opts),
|
|
};
|
|
|
|
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](/packages/cli) supplies a filesystem-backed adapter, but you can back it with anything.
|
|
|
|
## Helpers
|
|
|
|
```typescript
|
|
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';
|
|
```
|
|
|
|
## Related Packages
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Studio" icon="palette" href="/packages/studio">
|
|
The browser editor UI this server backs.
|
|
</Card>
|
|
<Card title="@hyperframes/parsers" icon="code" href="/packages/parsers">
|
|
The HTML + GSAP parsing layer it builds on.
|
|
</Card>
|
|
<Card title="@hyperframes/core" icon="cube" href="/packages/core">
|
|
Types and runtime; re-exports the studio API for back-compat.
|
|
</Card>
|
|
<Card title="CLI" icon="terminal" href="/packages/cli">
|
|
`npx hyperframes preview` wires this server up for you.
|
|
</Card>
|
|
</CardGroup>
|