mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
docs: add missing package pages (#1660)
* docs: add sdk package page * docs: add remaining package pages
This commit is contained in:
Miguel Ángel
@@ -89,10 +89,16 @@ bun run --filter '*' test
|
||||
| Package | Path | Description |
|
||||
|---------|------|-------------|
|
||||
| [`@hyperframes/core`](/packages/core) | `packages/core` | Types, HTML generation, runtime, linter |
|
||||
| [`@hyperframes/sdk`](/packages/sdk) | `packages/sdk` | Headless composition editing engine |
|
||||
| [`@hyperframes/engine`](/packages/engine) | `packages/engine` | Seekable page-to-video capture engine |
|
||||
| [`@hyperframes/player`](/packages/player) | `packages/player` | Embeddable composition player |
|
||||
| [`@hyperframes/producer`](/packages/producer) | `packages/producer` | Full rendering pipeline (capture + encode) |
|
||||
| [`@hyperframes/shader-transitions`](/packages/shader-transitions) | `packages/shader-transitions` | WebGL shader transition engine |
|
||||
| [`@hyperframes/aws-lambda`](/packages/aws-lambda) | `packages/aws-lambda` | AWS Lambda distributed rendering adapter |
|
||||
| [`@hyperframes/gcp-cloud-run`](/packages/gcp-cloud-run) | `packages/gcp-cloud-run` | GCP Cloud Run distributed rendering adapter |
|
||||
| [`@hyperframes/studio`](/packages/studio) | `packages/studio` | Composition editor UI |
|
||||
| [`hyperframes`](/packages/cli) | `packages/cli` | CLI for creating, previewing, and rendering |
|
||||
| `@hyperframes/sdk-playground` (private) | `packages/sdk-playground` | Local SDK playground app |
|
||||
|
||||
## What to Work On
|
||||
|
||||
|
||||
@@ -302,9 +302,13 @@
|
||||
"group": "Packages",
|
||||
"pages": [
|
||||
"packages/core",
|
||||
"packages/sdk",
|
||||
"packages/engine",
|
||||
"packages/player",
|
||||
"packages/producer",
|
||||
"packages/shader-transitions",
|
||||
"packages/aws-lambda",
|
||||
"packages/gcp-cloud-run",
|
||||
"packages/studio",
|
||||
"packages/cli"
|
||||
]
|
||||
|
||||
@@ -79,12 +79,27 @@ Run `npx hyperframes render --output demo.mp4` and this produces an MP4 with det
|
||||
<Card title="@hyperframes/core" icon="cube" href="/packages/core">
|
||||
Types, HTML parsing, runtime, and composition linter — the foundation everything else builds on.
|
||||
</Card>
|
||||
<Card title="@hyperframes/sdk" icon="code" href="/packages/sdk">
|
||||
Headless composition editing engine for agents, custom editors, patch events, and persistence.
|
||||
</Card>
|
||||
<Card title="@hyperframes/engine" icon="gear" href="/packages/engine">
|
||||
Seekable page-to-video capture engine. Loads HTML in headless Chrome and captures frame-by-frame.
|
||||
</Card>
|
||||
<Card title="@hyperframes/player" icon="play" href="/packages/player">
|
||||
Embeddable web component for playing HyperFrames compositions in any web page.
|
||||
</Card>
|
||||
<Card title="@hyperframes/producer" icon="video" href="/packages/producer">
|
||||
Full rendering pipeline combining capture and FFmpeg encoding into a single API call.
|
||||
</Card>
|
||||
<Card title="@hyperframes/shader-transitions" icon="sparkles" href="/packages/shader-transitions">
|
||||
WebGL shader transitions for scene-to-scene motion and render-time compositing.
|
||||
</Card>
|
||||
<Card title="@hyperframes/aws-lambda" icon="cloud" href="/packages/aws-lambda">
|
||||
AWS Lambda and Step Functions adapter for distributed rendering.
|
||||
</Card>
|
||||
<Card title="@hyperframes/gcp-cloud-run" icon="cloud" href="/packages/gcp-cloud-run">
|
||||
Google Cloud Run and Workflows adapter for distributed rendering.
|
||||
</Card>
|
||||
<Card title="@hyperframes/studio" icon="palette" href="/packages/studio">
|
||||
Visual composition editor UI for building and previewing timelines interactively.
|
||||
</Card>
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
---
|
||||
title: "@hyperframes/aws-lambda"
|
||||
description: "AWS Lambda and Step Functions adapter for distributed HyperFrames rendering."
|
||||
---
|
||||
|
||||
The AWS Lambda package runs HyperFrames' distributed render primitives on AWS. It ships the Lambda handler, a Node client SDK, and an optional CDK construct for provisioning the render stack inside an adopter's AWS account.
|
||||
|
||||
```bash
|
||||
npm install @hyperframes/aws-lambda
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use `@hyperframes/aws-lambda` when you need to:**
|
||||
- Render large compositions on AWS Lambda instead of one local machine
|
||||
- Fan out `plan`, `renderChunk`, and `assemble` through Step Functions
|
||||
- Store render inputs, intermediate chunks, and outputs in S3
|
||||
- Drive renders from CI, a backend service, or a custom CLI
|
||||
- Provision the render topology from a CDK app
|
||||
|
||||
**Use a different package if you want to:**
|
||||
- Render locally or inside your own Node process - use the [CLI](/packages/cli) or [producer](/packages/producer)
|
||||
- Run the same distributed model on Google Cloud - use [gcp-cloud-run](/packages/gcp-cloud-run)
|
||||
- Build or edit composition HTML - use [studio](/packages/studio), [sdk](/packages/sdk), or [core](/packages/core)
|
||||
|
||||
<Warning>
|
||||
This package is deployment glue for AWS infrastructure. It assumes you control an AWS account, S3 bucket, Step Functions state machine, and Lambda runtime configuration.
|
||||
</Warning>
|
||||
|
||||
## Package Exports
|
||||
|
||||
| Import | Description |
|
||||
|--------|-------------|
|
||||
| `@hyperframes/aws-lambda` | Handler types, runtime helpers, S3 transport, and client SDK exports |
|
||||
| `@hyperframes/aws-lambda/handler` | Lambda handler entry point for Step Functions dispatch |
|
||||
| `@hyperframes/aws-lambda/sdk` | Lightweight Node SDK for deploying sites, starting renders, polling progress, and estimating cost |
|
||||
| `@hyperframes/aws-lambda/cdk` | Optional CDK construct for provisioning the render bucket, Lambda, and Step Functions stack |
|
||||
|
||||
`aws-cdk-lib` and `constructs` are optional peer dependencies. SDK-only consumers do not need them unless they import from `@hyperframes/aws-lambda/cdk`.
|
||||
|
||||
## Architecture
|
||||
|
||||
The Lambda adapter wraps the distributed producer primitives behind one dispatch boundary:
|
||||
|
||||
<Steps>
|
||||
<Step title="Plan">
|
||||
Downloads the project archive from S3, runs the producer planner, and uploads the plan directory.
|
||||
</Step>
|
||||
<Step title="Render chunks">
|
||||
Step Functions fans out chunk jobs. Each Lambda invocation downloads the plan assets, renders one chunk, and uploads the result.
|
||||
</Step>
|
||||
<Step title="Assemble">
|
||||
Downloads all rendered chunks plus audio assets, assembles the final output, and writes the finished file to S3.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
The handler uses `@sparticuz/chromium` by default, with a build-time fallback for bundling `chrome-headless-shell` directly when needed.
|
||||
|
||||
## Using the SDK
|
||||
|
||||
After deploying the AWS resources, use the SDK from Node:
|
||||
|
||||
```typescript
|
||||
import { deploySite, getRenderProgress, renderToLambda } from "@hyperframes/aws-lambda/sdk";
|
||||
|
||||
const site = await deploySite({
|
||||
projectDir: "./my-composition",
|
||||
bucketName: "hyperframes-render-bucket",
|
||||
});
|
||||
|
||||
const handle = await renderToLambda({
|
||||
siteHandle: site,
|
||||
bucketName: site.bucketName,
|
||||
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hyperframes-render",
|
||||
config: {
|
||||
fps: 30,
|
||||
width: 1920,
|
||||
height: 1080,
|
||||
format: "mp4",
|
||||
chunkSize: 240,
|
||||
maxParallelChunks: 16,
|
||||
runtimeCap: "lambda",
|
||||
},
|
||||
});
|
||||
|
||||
const progress = await getRenderProgress({ executionArn: handle.executionArn });
|
||||
console.log(progress.status, progress.overallProgress, progress.costs.displayCost);
|
||||
```
|
||||
|
||||
`renderToLambda()` validates the distributed render config before starting the Step Functions execution, so invalid dimensions, formats, chunk sizes, or payload sizes fail synchronously.
|
||||
|
||||
## Using the CDK Construct
|
||||
|
||||
```typescript
|
||||
import { App, Stack } from "aws-cdk-lib";
|
||||
import { HyperframesRenderStack } from "@hyperframes/aws-lambda/cdk";
|
||||
|
||||
const app = new App();
|
||||
const stack = new Stack(app, "VideoRender");
|
||||
|
||||
const render = new HyperframesRenderStack(stack, "HyperframesRender", {
|
||||
// reservedConcurrency: 8,
|
||||
// lambdaMemoryMb: 10240,
|
||||
// chromeSource: "sparticuz",
|
||||
});
|
||||
|
||||
console.log(render.bucket.bucketName, render.stateMachine.stateMachineArn);
|
||||
```
|
||||
|
||||
## Building the Handler ZIP
|
||||
|
||||
From the monorepo:
|
||||
|
||||
```bash
|
||||
bun install
|
||||
bun run --cwd packages/aws-lambda build:zip
|
||||
bun run --cwd packages/aws-lambda verify:zip-size
|
||||
```
|
||||
|
||||
The build stages Chromium, Puppeteer, FFmpeg, and the handler bundle into `packages/aws-lambda/dist/handler.zip`. The size verifier keeps the unzipped artifact below Lambda's deployment limit.
|
||||
|
||||
## Related Guides
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="AWS Lambda Deployment" icon="cloud" href="/deploy/aws-lambda">
|
||||
End-to-end deployment details and operational notes.
|
||||
</Card>
|
||||
<Card title="@hyperframes/producer" icon="video" href="/packages/producer">
|
||||
The distributed primitives that the Lambda handler executes.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: "@hyperframes/gcp-cloud-run"
|
||||
description: "Google Cloud Run and Workflows adapter for distributed HyperFrames rendering."
|
||||
---
|
||||
|
||||
The GCP Cloud Run package runs HyperFrames' distributed render primitives on Google Cloud. It ships a Cloud Run HTTP service, a Node client SDK, and a Terraform module for provisioning the bucket, service, workflow, and service accounts.
|
||||
|
||||
```bash
|
||||
npm install @hyperframes/gcp-cloud-run
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use `@hyperframes/gcp-cloud-run` when you need to:**
|
||||
- Render large compositions on Google Cloud infrastructure
|
||||
- Orchestrate `plan`, `renderChunk`, and `assemble` through Cloud Workflows
|
||||
- Store project archives, chunk outputs, and final videos in GCS
|
||||
- Deploy the renderer as a Cloud Run service with a pinned Chrome runtime
|
||||
- Drive renders from CI, a backend service, or custom internal tooling
|
||||
|
||||
**Use a different package if you want to:**
|
||||
- Render locally or inside a single Node process - use the [CLI](/packages/cli) or [producer](/packages/producer)
|
||||
- Run the same distributed model on AWS - use [aws-lambda](/packages/aws-lambda)
|
||||
- Build or edit composition HTML - use [studio](/packages/studio), [sdk](/packages/sdk), or [core](/packages/core)
|
||||
|
||||
<Tip>
|
||||
Cloud Run uses a container image, so it avoids Lambda ZIP-size pressure and can install the same pinned `chrome-headless-shell` runtime used by the standard renderer.
|
||||
</Tip>
|
||||
|
||||
## Package Exports
|
||||
|
||||
| Import | Description |
|
||||
|--------|-------------|
|
||||
| `@hyperframes/gcp-cloud-run` | Server handler, event types, GCS transport, and client SDK exports |
|
||||
| `@hyperframes/gcp-cloud-run/server` | Cloud Run HTTP service entry point |
|
||||
| `@hyperframes/gcp-cloud-run/sdk` | Lightweight Node SDK for deploying sites, starting renders, polling progress, and estimating cost |
|
||||
|
||||
The published package also includes `terraform/` and a `Dockerfile` for deployment.
|
||||
|
||||
## Architecture
|
||||
|
||||
Cloud Workflows invokes one Cloud Run service with different `Action` values:
|
||||
|
||||
<Steps>
|
||||
<Step title="Plan">
|
||||
Downloads the project archive from GCS, runs the producer planner, and uploads the plan directory.
|
||||
</Step>
|
||||
<Step title="Render chunks">
|
||||
Cloud Workflows runs parallel `renderChunk` calls against the Cloud Run service. Each request renders one chunk and uploads it to GCS.
|
||||
</Step>
|
||||
<Step title="Assemble">
|
||||
Downloads all chunks and audio assets, assembles the deliverable, and uploads the final file.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
The service is intentionally close to the AWS Lambda adapter: thin cloud transport around the same `@hyperframes/producer/distributed` primitives.
|
||||
|
||||
## Deploying
|
||||
|
||||
Build and push the container, then apply the Terraform module:
|
||||
|
||||
```bash
|
||||
gcloud builds submit . \
|
||||
--tag REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
|
||||
|
||||
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform init
|
||||
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
|
||||
-var project_id=PROJECT \
|
||||
-var region=us-central1 \
|
||||
-var image=REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
|
||||
```
|
||||
|
||||
Terraform outputs the bucket name, service URL, workflow name, and region needed by the SDK.
|
||||
|
||||
## Using the SDK
|
||||
|
||||
```typescript
|
||||
import { getRenderProgress, renderToCloudRun } from "@hyperframes/gcp-cloud-run/sdk";
|
||||
|
||||
const handle = await renderToCloudRun({
|
||||
projectDir: "./my-composition",
|
||||
config: { fps: 30, width: 1920, height: 1080, format: "mp4" },
|
||||
bucketName: "hyperframes-render-my-project",
|
||||
projectId: "my-project",
|
||||
location: "us-central1",
|
||||
workflowId: "hyperframes-render",
|
||||
serviceUrl: "https://hyperframes-render-abc.us-central1.run.app",
|
||||
});
|
||||
|
||||
let progress = await getRenderProgress({ executionName: handle.executionName });
|
||||
while (progress.status === "running") {
|
||||
await new Promise((resolve) => setTimeout(resolve, 5000));
|
||||
progress = await getRenderProgress({ executionName: handle.executionName });
|
||||
}
|
||||
|
||||
console.log(progress.status, progress.outputFile, progress.costs.displayCost);
|
||||
```
|
||||
|
||||
Pass `projectDir` for one-shot uploads, or call `deploySite()` separately and reuse the returned site handle across many renders.
|
||||
|
||||
## Related Guides
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="GCP Cloud Run Deployment" icon="cloud" href="/deploy/gcp-cloud-run">
|
||||
End-to-end deployment details and smoke-test notes.
|
||||
</Card>
|
||||
<Card title="@hyperframes/producer" icon="video" href="/packages/producer">
|
||||
The distributed primitives that the Cloud Run service executes.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,223 @@
|
||||
---
|
||||
title: "@hyperframes/sdk"
|
||||
description: "Headless, framework-neutral composition editing engine for agents and custom editors."
|
||||
---
|
||||
|
||||
The SDK package provides a programmatic editing layer for HyperFrames compositions. It opens composition HTML, exposes query and mutation APIs, emits JSON patches, supports undo/redo, and can persist changes through pluggable adapters without requiring React, Studio, or a browser UI.
|
||||
|
||||
```bash
|
||||
npm install @hyperframes/sdk
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use `@hyperframes/sdk` when you need to:**
|
||||
- Build a custom composition editor in your own application
|
||||
- Let an agent inspect and edit composition HTML without driving a browser UI
|
||||
- Apply batch text, style, timing, asset, variable, or animation edits from code
|
||||
- Track undo/redo and patch events for host application history
|
||||
- Persist edited HTML through memory, filesystem, or custom storage adapters
|
||||
- Layer sparse overrides on top of a reusable base composition template
|
||||
|
||||
**Use a different package if you want to:**
|
||||
- Render compositions to MP4 or WebM - use the [CLI](/packages/cli) or [producer](/packages/producer)
|
||||
- Preview and edit visually out of the box - use the [CLI](/packages/cli) (`npx hyperframes preview`) or [studio](/packages/studio)
|
||||
- Parse, lint, or generate low-level composition HTML - use [core](/packages/core)
|
||||
- Capture frames from a headless browser - use [engine](/packages/engine)
|
||||
|
||||
<Tip>
|
||||
The SDK is the right layer for product integrations and agents that need structured edits. The CLI and Studio are user-facing tools built around the same composition format; the SDK is the editing engine you embed behind your own UI or automation.
|
||||
</Tip>
|
||||
|
||||
## Package Exports
|
||||
|
||||
| Import | Description |
|
||||
|--------|-------------|
|
||||
| `@hyperframes/sdk` | Main editing API, types, memory/headless adapters, iframe preview adapter |
|
||||
| `@hyperframes/sdk/adapters/memory` | In-memory persistence adapter for tests, demos, and ephemeral sessions |
|
||||
| `@hyperframes/sdk/adapters/fs` | Node.js filesystem persistence adapter with version history |
|
||||
| `@hyperframes/sdk/adapters/headless` | No-op preview adapter for agents, CI, and server-side editing |
|
||||
|
||||
## Quick Start
|
||||
|
||||
Open HTML, edit explicit element IDs, then serialize the updated composition:
|
||||
|
||||
```typescript
|
||||
import { openComposition } from "@hyperframes/sdk";
|
||||
|
||||
const comp = await openComposition(html);
|
||||
|
||||
const [headlineId] = comp.find({ text: "Old headline" });
|
||||
if (headlineId) {
|
||||
comp.setText(headlineId, "New headline");
|
||||
comp.setStyle(headlineId, {
|
||||
color: "#FFD60A",
|
||||
fontSize: "96px",
|
||||
});
|
||||
}
|
||||
|
||||
const updatedHtml = comp.serialize();
|
||||
comp.dispose();
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Explicit Element IDs
|
||||
|
||||
All edits target stable HyperFrames element IDs. This makes the SDK safe for headless agents and backend jobs because mutations do not depend on mouse state or a current UI selection.
|
||||
|
||||
```typescript
|
||||
const allElements = comp.getElements();
|
||||
const imageIds = allElements
|
||||
.filter((element) => element.tag === "img")
|
||||
.map((element) => element.id);
|
||||
|
||||
for (const id of imageIds) {
|
||||
comp.setAttribute(id, "loading", "eager");
|
||||
}
|
||||
```
|
||||
|
||||
### Typed Methods
|
||||
|
||||
The common editing operations have typed convenience methods:
|
||||
|
||||
```typescript
|
||||
comp.setText("hf-title", "Launch day");
|
||||
comp.setStyle("hf-title", { color: "#ffffff", transform: "translateY(24px)" });
|
||||
comp.setAttribute("hf-logo", "src", "/assets/logo.png");
|
||||
comp.setTiming("hf-title", { start: 0.5, duration: 2.5 });
|
||||
comp.setVariableValue("brandColor", "#6C5CE7");
|
||||
comp.removeElement("hf-old-caption");
|
||||
```
|
||||
|
||||
Use `batch()` when several mutations should become one undo entry, one persist write, and one change notification:
|
||||
|
||||
```typescript
|
||||
comp.batch(() => {
|
||||
comp.setText("hf-title", "Version 2");
|
||||
comp.setStyle("hf-title", { color: "#22C55E" });
|
||||
comp.setTiming("hf-title", { start: 1, duration: 3 });
|
||||
});
|
||||
```
|
||||
|
||||
### Advanced Dispatch API
|
||||
|
||||
Agents and automation can emit data-shaped operations through `dispatch()`:
|
||||
|
||||
```typescript
|
||||
comp.dispatch({
|
||||
type: "setStyle",
|
||||
target: "hf-card",
|
||||
styles: { borderRadius: "24px" },
|
||||
});
|
||||
```
|
||||
|
||||
Before showing a UI control or applying an optional operation, call `can()`:
|
||||
|
||||
```typescript
|
||||
const result = comp.can({
|
||||
type: "setGsapTween",
|
||||
animationId: "anim-1",
|
||||
properties: { ease: "power3.out" },
|
||||
});
|
||||
|
||||
if (result.ok) {
|
||||
comp.setGsapTween("anim-1", { ease: "power3.out" });
|
||||
}
|
||||
```
|
||||
|
||||
## Persistence
|
||||
|
||||
Pass a persistence adapter to autosave edits. The SDK ships memory and filesystem adapters, and host applications can implement the same `PersistAdapter` interface for S3, HTTP, IndexedDB, or app-specific storage.
|
||||
|
||||
```typescript
|
||||
import { openComposition } from "@hyperframes/sdk";
|
||||
import { createFsAdapter } from "@hyperframes/sdk/adapters/fs";
|
||||
|
||||
const comp = await openComposition(html, {
|
||||
persist: createFsAdapter({ root: "./project" }),
|
||||
persistPath: "index.html",
|
||||
});
|
||||
|
||||
comp.setText("hf-title", "Saved title");
|
||||
await comp.flush();
|
||||
```
|
||||
|
||||
Persistence failures are emitted as events instead of crashing the session:
|
||||
|
||||
```typescript
|
||||
comp.on("persist:error", ({ error }) => {
|
||||
console.error("Autosave failed:", error.message);
|
||||
});
|
||||
```
|
||||
|
||||
## Undo, Redo, and Patch Events
|
||||
|
||||
Standalone sessions include undo/redo by default:
|
||||
|
||||
```typescript
|
||||
comp.setText("hf-title", "Draft");
|
||||
comp.undo();
|
||||
comp.redo();
|
||||
```
|
||||
|
||||
Patch events let a host application mirror SDK edits into its own state, collaboration layer, or audit log:
|
||||
|
||||
```typescript
|
||||
const unsubscribe = comp.on("patch", ({ patches, inversePatches, origin }) => {
|
||||
saveToHostHistory({ patches, inversePatches, origin });
|
||||
});
|
||||
|
||||
unsubscribe();
|
||||
```
|
||||
|
||||
## Embedded Override Mode
|
||||
|
||||
For template-driven products, open a composition with an `overrides` object. The SDK applies the sparse override set on top of the base HTML, accumulates additional edits into that override set, and lets the host store only the delta.
|
||||
|
||||
```typescript
|
||||
const comp = await openComposition(templateHtml, {
|
||||
overrides: {
|
||||
"hf-title.text": "Customer-specific title",
|
||||
"hf-logo.attr.src": "/customers/acme/logo.png",
|
||||
},
|
||||
history: false,
|
||||
});
|
||||
|
||||
comp.setStyle("hf-title", { color: "#0EA5E9" });
|
||||
|
||||
const nextOverrides = comp.getOverrides();
|
||||
```
|
||||
|
||||
Use `applyPatches()` when the host owns undo/redo and needs to replay inverse patches into the SDK without creating loops.
|
||||
|
||||
## Preview Adapters
|
||||
|
||||
The SDK can run headlessly, or it can connect to a preview surface:
|
||||
|
||||
```typescript
|
||||
import { openComposition, createHeadlessAdapter } from "@hyperframes/sdk";
|
||||
|
||||
const comp = await openComposition(html, {
|
||||
preview: createHeadlessAdapter(),
|
||||
});
|
||||
```
|
||||
|
||||
For browser integrations, `createIframePreviewAdapter()` bridges the SDK to a same-origin composition iframe so hit-testing, selection, and draft preview updates can stay outside the model mutation path.
|
||||
|
||||
## Related Packages
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="@hyperframes/core" icon="cube" href="/packages/core">
|
||||
Low-level types, HTML utilities, runtime helpers, and linter APIs.
|
||||
</Card>
|
||||
<Card title="@hyperframes/studio" icon="palette" href="/packages/studio">
|
||||
Ready-made visual editor UI that can embed SDK-driven editing flows.
|
||||
</Card>
|
||||
<Card title="@hyperframes/producer" icon="video" href="/packages/producer">
|
||||
Programmatic rendering pipeline for turning edited HTML into video.
|
||||
</Card>
|
||||
<Card title="CLI" icon="terminal" href="/packages/cli">
|
||||
Command-line create, preview, lint, and render workflows.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
title: "@hyperframes/shader-transitions"
|
||||
description: "WebGL shader transitions for HyperFrames scenes and compositions."
|
||||
---
|
||||
|
||||
The shader transitions package adds GPU-accelerated scene-to-scene transitions to HyperFrames compositions. It captures scene samples, uploads them as WebGL textures, and drives fragment-shader compositing from a GSAP timeline.
|
||||
|
||||
```bash
|
||||
npm install @hyperframes/shader-transitions
|
||||
```
|
||||
|
||||
You can also load the browser global build directly:
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/@hyperframes/shader-transitions/dist/index.global.js"></script>
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use `@hyperframes/shader-transitions` when you need to:**
|
||||
- Add shader-based scene transitions such as domain warp, whip pan, glitch, iris, light leak, or thermal distortion
|
||||
- Attach GPU transitions to an existing GSAP timeline
|
||||
- Build a transition picker or validation UI around the available shader registry
|
||||
- Feature-detect native HTML-in-canvas capture support
|
||||
- Use the producer's deterministic page-side compositor for render-mode captures
|
||||
|
||||
**Use a different package if you want to:**
|
||||
- Render the finished composition to video - use the [CLI](/packages/cli) or [producer](/packages/producer)
|
||||
- Edit composition structure programmatically - use [sdk](/packages/sdk)
|
||||
- Build a visual editor surface - use [studio](/packages/studio)
|
||||
|
||||
## Package Exports
|
||||
|
||||
| Import | Description |
|
||||
|--------|-------------|
|
||||
| `init()` | Creates or augments a GSAP timeline with shader transitions |
|
||||
| `SHADER_NAMES` | Array of supported shader names for validation and UI pickers |
|
||||
| `isHtmlInCanvasCaptureSupported()` | Feature-detects Chrome's native HTML-in-canvas capture path |
|
||||
| `installPageSideCompositor()` | Installs the render-mode compositor used by the producer path |
|
||||
| `isPageSideCompositingSupported()` | Checks whether page-side shader compositing is available |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
import { init } from "@hyperframes/shader-transitions";
|
||||
|
||||
const timeline = init({
|
||||
bgColor: "#0a0a0a",
|
||||
accentColor: "#ff6b2b",
|
||||
scenes: ["scene-1", "scene-2", "scene-3"],
|
||||
transitions: [
|
||||
{ time: 3, shader: "domain-warp", duration: 0.8 },
|
||||
{ time: 8, shader: "light-leak", duration: 0.7 },
|
||||
],
|
||||
});
|
||||
|
||||
window.__timelines ??= {};
|
||||
window.__timelines.hero = timeline;
|
||||
```
|
||||
|
||||
Pass an existing GSAP timeline when the composition already owns the animation sequence:
|
||||
|
||||
```typescript
|
||||
const timeline = gsap.timeline({ paused: true });
|
||||
timeline.from("#headline", { opacity: 0, y: 40, duration: 0.6 });
|
||||
|
||||
init({
|
||||
bgColor: "#000000",
|
||||
scenes: ["intro", "demo", "outro"],
|
||||
transitions: [
|
||||
{ time: 5, shader: "cinematic-zoom" },
|
||||
{ time: 12, shader: "glitch", duration: 0.5 },
|
||||
],
|
||||
timeline,
|
||||
});
|
||||
```
|
||||
|
||||
If WebGL is unavailable, the package falls back to normal timeline playback without shader compositing.
|
||||
|
||||
## Available Shaders
|
||||
|
||||
| Shader | Description |
|
||||
|--------|-------------|
|
||||
| `domain-warp` | Organic noise-based warp with a glowing edge |
|
||||
| `ridged-burn` | Ridged noise burn with sparks and heat glow |
|
||||
| `whip-pan` | Horizontal motion blur simulating a fast camera pan |
|
||||
| `sdf-iris` | Circular iris wipe with a glowing ring edge |
|
||||
| `ripple-waves` | Concentric ripple distortion radiating from center |
|
||||
| `gravitational-lens` | Warping gravity well with chromatic aberration |
|
||||
| `cinematic-zoom` | Radial zoom blur with chromatic fringing |
|
||||
| `chromatic-split` | RGB channel separation expanding from center |
|
||||
| `glitch` | Digital glitch with block displacement and scanlines |
|
||||
| `swirl-vortex` | Spiral rotation with noise-based warping |
|
||||
| `thermal-distortion` | Heat shimmer rising from the bottom |
|
||||
| `flash-through-white` | Flash to white, then reveal the next scene |
|
||||
| `cross-warp-morph` | Noise-driven morph blending both scenes |
|
||||
| `light-leak` | Warm cinematic light leak with lens flare |
|
||||
|
||||
Use `SHADER_NAMES` when you need a typed list:
|
||||
|
||||
```typescript
|
||||
import { SHADER_NAMES } from "@hyperframes/shader-transitions";
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
```typescript
|
||||
type TransitionConfig = {
|
||||
time: number;
|
||||
shader?: string;
|
||||
duration?: number;
|
||||
ease?: string;
|
||||
};
|
||||
|
||||
type HyperShaderConfig = {
|
||||
bgColor: string;
|
||||
accentColor?: string;
|
||||
scenes: string[];
|
||||
transitions: TransitionConfig[];
|
||||
timeline?: gsap.core.Timeline;
|
||||
compositionId?: string;
|
||||
previewCaptureFps?: number;
|
||||
};
|
||||
```
|
||||
|
||||
`shader` is optional. Omit it to use a CSS fallback transition at that point in the timeline.
|
||||
|
||||
## Preview and Render Behavior
|
||||
|
||||
Browser previews pre-capture transition samples and cache matching snapshots in IndexedDB. Cache keys include the composition ID, scene DOM/style signatures, timing, capture FPS, scale, and dimensions, so normal page refreshes can reuse samples while runtime edits invalidate only adjacent transition caches.
|
||||
|
||||
During producer renders, shader transitions use a deterministic page-side compositor instead of preview-time snapshot caching. That keeps frame capture seek-driven and avoids depending on wall-clock playback.
|
||||
|
||||
## Related Packages
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="@hyperframes/producer" icon="video" href="/packages/producer">
|
||||
Renders compositions that include shader transitions.
|
||||
</Card>
|
||||
<Card title="Transition Catalog" icon="sparkles" href="/catalog/blocks/transitions-distortion">
|
||||
Browse installable transition blocks built on the shader system.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
Reference in New Issue
Block a user