heygen-com--hyperframes/packages/sdk-playground/README.md

@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

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