> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @hyperframes/studio

> React components and hooks used to build the HyperFrames Studio editing interface.

`@hyperframes/studio` contains the React application, editor components, player,
timeline, and hooks that power HyperFrames Studio.

Most people should not install this package directly. To open a project in the
complete Studio application, run:

```bash theme={null}
npx hyperframes preview
```

Install the package only when you are extending Studio or building an editor that
uses its lower-level parts:

```bash theme={null}
npm install @hyperframes/studio react react-dom zustand
```

<Warning>
  The exported components are building blocks, not a drop-in embedded editor.
  Components such as `EditorShell`, `NLEPreview`, `Timeline`, `PropertyPanel`, and
  `FileTree` require project state, callbacks, or Studio contexts. Use `StudioApp`
  when you need the complete application, or inspect the component types before
  composing a custom host.
</Warning>

When you run Studio from the monorepo, its dev server listens on `http://localhost:5190`.

## Entry points

| Import                                | Contains                                                   |
| ------------------------------------- | ---------------------------------------------------------- |
| `@hyperframes/studio`                 | React components, hooks, utilities, and their public types |
| `@hyperframes/studio/tailwind-preset` | Tailwind preset used by Studio                             |

Peer dependencies are React 19, React DOM 19, and Zustand 4 or 5.

## Main exports

### Complete application

| Export      | Use                             |
| ----------- | ------------------------------- |
| `StudioApp` | The complete Studio application |

### Editor structure

| Export                  | Use                                      |
| ----------------------- | ---------------------------------------- |
| `EditorShell`           | Preview, side panels, and timeline shell |
| `NLEPreview`            | Composition preview surface              |
| `CompositionBreadcrumb` | Navigation through nested compositions   |
| `SourceEditor`          | Source editor                            |
| `PropertyPanel`         | Inspector for the selected element       |
| `FileTree`              | Project file browser                     |

### Playback and timeline

| Export                 | Use                                    |
| ---------------------- | -------------------------------------- |
| `Player`               | Composition iframe and playback bridge |
| `PlayerControls`       | Playback, seeking, and frame controls  |
| `Timeline`             | Timeline editing surface               |
| `VideoThumbnail`       | Video clip thumbnail                   |
| `CompositionThumbnail` | Nested-composition thumbnail           |

### Hooks and utilities

| Export                                                      | Use                                                   |
| ----------------------------------------------------------- | ----------------------------------------------------- |
| `useTimelinePlayer`                                         | Read and control the shared player state              |
| `usePlayerStore`                                            | Access the Zustand player store                       |
| `useElementPicker`                                          | Select and edit an element through the preview iframe |
| `resolveSourceFile`, `applyPatch`                           | Locate and patch source                               |
| `parseStyleString`, `mergeStyleIntoTag`, `findElementBlock` | Work with inline source styles and elements           |

The package also exports `CompositionLevel`, `TimelineElement`, `PickedElement`,
and `PatchOperation`.

## How Studio stays connected to a project

1. Studio loads the composition in an iframe with the HyperFrames runtime.
2. Player controls communicate with that runtime to play, pause, and seek.
3. The editor and timeline send changes through the Studio API.
4. The Studio server writes those changes back to the project files.
5. External file changes refresh the preview while keeping the current position
   when possible.

Preview and render use the same seekable composition contract. Preview still
depends on the browser playing in real time, while render captures frames one at a
time. A heavy project can therefore stutter during preview and still render every
frame.

## Tailwind preset

```typescript theme={null}
import studioPreset from "@hyperframes/studio/tailwind-preset";

export default {
  presets: [studioPreset],
};
```

## Related pages

<CardGroup cols={2}>
  <Card title="Use Studio" icon="pen-to-square" href="/studio">
    Learn the complete editing workflow.
  </Card>

  <Card title="Studio server" icon="server" href="/packages/studio-server">
    Connect project files, media, linting, and render jobs.
  </Card>

  <Card title="Player" icon="circle-play" href="/packages/player">
    Embed playback without the editing interface.
  </Card>

  <Card title="SDK" icon="code" href="/sdk/overview">
    Query and edit compositions without Studio.
  </Card>
</CardGroup>