mirror of
https://github.com/hanzoai/frames.git
synced 2026-09-24 00:08:03 +00:00
zooqueen
75094e0d60
@hanzo/frame is taken by the hero video primitive — one full-bleed video element — which has held that name on npm since it shipped. This repo is the video toolchain: a CLI, a renderer, a studio, a player. Plural is what it is, so the CLI publishes as @hanzo/frames and the workspace packages follow it (@hanzo/frames-core, @hanzo/frames-engine, and the rest). The binary stays `frames`, and now actually ships. The manifest mapped it to bin/frames.mjs while the file on disk was bin/hyperframes.mjs, so a global install produced no working command. The paths that name a package to fetch were pointing elsewhere. The update check read registry.npmjs.org/frames, a different author's package, and the npm, bun and pnpm installers would have pulled it over the CLI; the render image installed the upstream hyperframes; scaffolded projects and the docs pinned the unscoped name. All of them now name @hanzo/frames.
100 lines
3.9 KiB
Plaintext
100 lines
3.9 KiB
Plaintext
---
|
|
title: "@frames/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 `@frames/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 @frames/studio-server
|
|
```
|
|
|
|
## When to Use
|
|
|
|
<Tip>
|
|
**Most users do not need this package directly.** The [CLI](/packages/cli) (`npx @hanzo/frames 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 `@frames/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>
|
|
`@frames/core/studio-api` still resolves (via a back-compat re-export stub), so existing imports keep working. New code should import from `@frames/studio-server` directly.
|
|
</Info>
|
|
|
|
## Package Exports
|
|
|
|
| Import | Description |
|
|
|--------|-------------|
|
|
| `@frames/studio-server` | `createStudioApi`, helpers, types |
|
|
| `@frames/studio-server/source-mutation` | Source mutation utilities |
|
|
| `@frames/studio-server/screenshot-clip` | Element screenshot-clip geometry |
|
|
| `@frames/studio-server/manual-edits-render-script` | Manual-edits render body script |
|
|
| `@frames/studio-server/studio-motion-render-script` | Studio motion render body script |
|
|
| `@frames/studio-server/draft-markers` | Draft gesture-marker attributes |
|
|
| `@frames/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 '@frames/studio-server';
|
|
import type { StudioApiAdapter, ResolvedProject } from '@frames/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 '@frames/studio-server';
|
|
import type {
|
|
ResolvedProject,
|
|
RenderJobState,
|
|
LintResult,
|
|
ScreenshotClip,
|
|
} from '@frames/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="@frames/parsers" icon="code" href="/packages/parsers">
|
|
The HTML + GSAP parsing layer it builds on.
|
|
</Card>
|
|
<Card title="@frames/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 @hanzo/frames preview` wires this server up for you.
|
|
</Card>
|
|
</CardGroup>
|