mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-01 19:42:03 +00:00

Files

T

Miguel Ángel 1149602bc9 fix(studio): support web-component refs in useTimelinePlayer (#245 )

* fix(studio): support web-component refs in useTimelinePlayer

The studio's `useTimelinePlayer` hook returns an `iframeRef` that
consumers attach to an `<iframe>` element. When consumers wrap the
iframe in a custom element (e.g. `<hyperframes-player>`) that puts
the iframe inside its shadow DOM, every `iframeRef.current.contentWindow`
access returned `null` and `getAdapter()` silently failed — meaning
timeline seek, play, pause, and `refreshPlayer` all became no-ops.

Changes:
- Add `resolveIframe(el)` helper that returns the underlying iframe
  whether the host is the iframe itself, a custom element with a
  shadow-DOM iframe, or a wrapper with a descendant iframe.
- Export `resolveIframe` from the studio so consumers can pre-resolve
  the iframe before assigning it to `iframeRef`.
- Internal `useTimelinePlayer` keeps the strict `HTMLIFrameElement`
  ref type, so existing consumers attaching directly to an `<iframe>`
  are unaffected.

Also adds:
- JSDoc on the player's `iframeElement` getter.
- "Advanced: iframe access" docs section in `packages/player/README.md`
  and `docs/packages/player.mdx`.
- Type-safety lint rules in `.oxlintrc.json` and a "Type-safety
  conventions" section in `CONTRIBUTING.md`.

Backward compatible — App.tsx and NLELayout.tsx continue to work
unchanged.

* chore(lint): defer no-explicit-any rule; it broke existing codebase

The new rules added 37 errors across 32 existing files — mostly
legitimate `window as any` casts at browser-global and test-mock
boundaries. Enabling them without fixing all violations breaks CI.

Revert the `.oxlintrc.json` additions and soften the CONTRIBUTING.md
wording to describe the convention without claiming lint enforcement
(that enforcement will come in a follow-up PR that fixes all sites).

2026-04-13 17:53:01 +02:00

6.1 KiB

Raw Permalink Blame History

Contributing to Hyperframes

Thanks for your interest in contributing to Hyperframes! This guide will help you get started.

Getting Started

Fork the repository
Clone your fork: git clone https://github.com/YOUR_USERNAME/hyperframes.git
Install dependencies: bun install
Create a branch: git checkout -b my-feature

Development

bun install        # Install all dependencies
bun run dev        # Run the studio (composition editor)
bun run build      # Build all packages
bun run --filter '*' typecheck   # Type-check all packages
bun run lint       # Lint all packages
bun run format:check   # Check formatting

Running Tests

bun run --filter @hyperframes/core test          # Core unit tests (vitest)
bun run --filter @hyperframes/engine test        # Engine unit tests (vitest)
bun run --filter @hyperframes/core test:hyperframe-runtime-ci  # Runtime contract tests

Linting & Formatting

bun run lint            # Run oxlint
bun run lint:fix        # Run oxlint with auto-fix
bun run format          # Format all files with oxfmt
bun run format:check    # Check formatting without writing

Git hooks (via lefthook) run automatically after bun install and enforce linting + formatting on staged files before each commit.

Type-safety conventions

We aim for honest types — code that lies to the compiler eventually lies to users. The underlying convention is:

Avoid any. Use unknown and narrow it where possible.
Avoid as T type assertions. They suppress type-checker warnings without telling the compiler anything new. Prefer:
- Type guards (function isFoo(x): x is Foo)
- instanceof / typeof narrowing
- Centralized narrowing helpers (e.g. resolveIframe)
- Properly-typed interfaces at the source
Acceptable as use, with a comment explaining why:
- as const — literal narrowing; always safe
- as unknown as T — explicit double-cast at hard type-system boundaries (e.g. parsing untrusted JSON, FFI/postMessage). Pair with a one-line justification.
Avoid ! non-null assertions outside of post-if-checked code paths. Use ?? defaults or guard clauses instead.

If you must add a cast, add a comment:

// `postMessage` data is `unknown`; the runtime guarantees this shape.
const event = data as unknown as RuntimeEvent;

Pull Requests

Use conventional commit format for all commits (e.g., feat: add timeline export, fix: resolve seek overflow). Enforced by a git hook.
CI must pass before merge (build, typecheck, tests, semantic PR title)
PRs require at least 1 approval

Packages

Package	Description
`@hyperframes/core`	Types, HTML generation, runtime, linter
`@hyperframes/engine`	Seekable page-to-video capture engine
`@hyperframes/producer`	Full rendering pipeline (capture + encode)
`@hyperframes/studio`	Composition editor UI
`hyperframes`	CLI for creating, previewing, and rendering

Releasing (Maintainers)

All packages use fixed versioning — every release bumps all packages to the same version.

Stable releases

bun run set-version 0.2.0            # bumps all packages, commits, and creates git tag
git push origin main --tags           # triggers the publish workflow

The set-version script automatically creates a chore: release v<version> commit and a v<version> git tag. Pushing the tag triggers CI to publish all packages to npm and create a GitHub Release.

Pre-releases (alpha / beta / rc)

Use a pre-release suffix to publish to a named npm dist-tag instead of latest:

bun run set-version 0.2.0-alpha.1    # first alpha
git push origin v0.2.0-alpha.1       # publishes to npm with --tag alpha

bun run set-version 0.2.0-alpha.2    # iterate
bun run set-version 0.2.0-beta.1     # promote to beta (--tag beta)
bun run set-version 0.2.0-rc.1       # release candidate (--tag rc)
bun run set-version 0.2.0            # final stable release (--tag latest)

Consumers install pre-releases with npm install @hyperframes/core@alpha (or @beta, @rc). The latest tag is never touched by pre-releases, so npm install @hyperframes/core always gets the last stable version.

Pre-releases also create GitHub Releases marked as pre-release.

Options

If you need to bump versions without committing (e.g., for a release PR), pass --no-tag:

bun run set-version 0.2.0 --no-tag   # updates package.json files only

Reporting Issues

Use GitHub Issues for bug reports and feature requests
Search existing issues before creating a new one
Include reproduction steps for bugs

AI-Assisted Contributions

We welcome contributions that use AI tools (GitHub Copilot, Claude, ChatGPT, etc.). If you used AI to help write a PR, there is no need to disclose it — we review all code on its merits. However:

You are responsible for the correctness of any code you submit, regardless of how it was generated.
AI-generated tests must actually test meaningful behavior, not just assert truthy values.
Do not submit AI-generated code you don't understand. If you can't explain what a change does during review, it will be rejected.

Governance

Hyperframes uses a BDFL (Benevolent Dictator for Life) governance model. The core maintainers at HeyGen have final say on the project's direction, API design, and what gets merged. This keeps the project focused and moving fast.

Community input is valued and encouraged — open issues, propose RFCs, and discuss in PRs. But final decisions rest with the maintainers.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

License

By contributing, you agree that your contributions will be licensed under the project's license. See LICENSE for details.

6.1 KiB Raw Permalink Blame History