mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
577a689860
* feat(sdk): file-backed fs adapter + setTiming GSAP-script sync; add sdk-playground * fix(sdk): address PR #1423 review — oxfmt, PersistVersionEntry contract, race, comments - bunx oxfmt packages/sdk-playground/index.html (unblocks CI) - PersistVersionEntry.content is now optional; HTTP adapter omits it for lazy-load - fs adapter: monotonic key (Date.now-NNNN) + per-path write serialization via promise chain - mutate.ts: fix wrong comment on GSAP sync reason; add caveat to "pre-parse once" note Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com> * fix(core): oxfmt gsapSerialize.ts — unblocks Preflight across stack Pre-existing format issue on the base; fixing here to unblock CI. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com> * chore: update bun.lock for sdk-playground workspace Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
85 lines
4.8 KiB
Markdown
85 lines
4.8 KiB
Markdown
# @hyperframes/sdk-playground
|
|
|
|
Interactive browser playground for the `@hyperframes/sdk` API. Open a composition, edit it through the full SDK op surface, watch the preview update live.
|
|
|
|
## Running
|
|
|
|
```bash
|
|
bun run --cwd packages/sdk-playground dev
|
|
```
|
|
|
|
Serves at `http://localhost:5173`. On first load it reads `packages/sdk-playground/composition.html` from disk (if present) or falls back to a built-in demo composition.
|
|
|
|
## Features
|
|
|
|
### File persistence
|
|
|
|
Composition state is persisted to `packages/sdk-playground/composition.html` via a Vite dev-server plugin backed by `@hyperframes/sdk/adapters/fs`. Every save writes a timestamped snapshot to `.hf-versions/composition.html/` (capped at 20). Reload the page and your last state is restored.
|
|
|
|
### Preview iframe
|
|
|
|
Full composition rendered in a sandboxed `<iframe>`. Supports:
|
|
|
|
- **Play / Pause / Seek** via the transport bar
|
|
- **Click-to-select** elements (highlights in the tree and properties panel)
|
|
- **Drag-to-reposition** — drag any element to a new position; on drop the playground calls `comp.setStyle(id, { left, top })`
|
|
|
|
### Element tree
|
|
|
|
Lists all non-root elements. Click any row to select it.
|
|
|
|
### Properties panel
|
|
|
|
Editable per-element properties for the selected element:
|
|
|
|
| Section | SDK op |
|
|
| ---------- | --------------------------------------------------------------------------- |
|
|
| Content | `comp.setText(id, value)` |
|
|
| Typography | `comp.setStyle(id, { fontSize, fontWeight, color, fontFamily })` |
|
|
| Box | `comp.setStyle(id, { top, left, width, height })` |
|
|
| Attributes | `comp.element(id).setAttribute(name, value)` — shows all non-internal attrs |
|
|
| Danger | `comp.element(id).removeElement()` |
|
|
| Animations | `comp.setTiming(id, { start, duration })` — inline form per GSAP tween |
|
|
|
|
### Timeline
|
|
|
|
DAW-style per-element tween blocks. Drag handles to trim start/end; drag body to move. All edits go through `comp.setTiming(id, { start, duration })` which keeps the GSAP script and DOM attributes in sync.
|
|
|
|
### Ops panel
|
|
|
|
Full op surface, grouped by feature:
|
|
|
|
| Section | SDK op |
|
|
| ---------------------------- | --------------------------------------------------------------------------------- |
|
|
| PreviewAdapter.select() | `preview.select([id])` |
|
|
| setStyle | `comp.setStyle(id, styles)` |
|
|
| setText | `comp.setText(id, value)` |
|
|
| addGsapTween | `comp.addGsapTween(target, spec)` |
|
|
| setTiming | `comp.setTiming(id, { start, duration })` |
|
|
| setGsapTween | `comp.setGsapTween(animId, updates)` |
|
|
| moveElement | `comp.moveElement(id, { parent, index })` |
|
|
| setClassStyle | `comp.dispatch({ type: "setClassStyle", selector, styles })` |
|
|
| setAttribute / removeElement | `comp.element(id).setAttribute()` / `.removeElement()` |
|
|
| setVariableValue | `comp.setVariableValue(id, value)` |
|
|
| find(query) | `comp.find({ tag, text, name, track })` |
|
|
| selection() proxy | `comp.selection().setStyle()` / `.removeElement()` |
|
|
| listVersions / loadFrom | `adapter.listVersions()` / `adapter.loadFrom()` |
|
|
| History / inspect | `comp.undo()`, `comp.redo()`, `comp.can()`, `comp.getOverrides()`, `comp.flush()` |
|
|
|
|
### Editor modal
|
|
|
|
Click "Open editor" to view and directly edit the raw composition HTML. Saving re-opens the composition through the SDK.
|
|
|
|
---
|
|
|
|
## Planned / not yet wired
|
|
|
|
- `comp.setTrackVariable(trackId, variableId)` — variable binding per track
|
|
- `comp.addElement(spec)` — create new elements from the UI
|
|
- `comp.duplicateElement(id)` — duplicate with offset
|
|
- Selection multi-select (current: single-select only)
|
|
- Timeline zoom and horizontal scroll for long compositions
|
|
- Version history browser — list/preview/restore past versions inline (API is implemented; UI shows only list + load-oldest)
|
|
- `comp.on('change', cb)` live event log fed from SDK event stream
|
|
- Render to video via `@hyperframes/producer` integration
|