From eb199bd1595f7774a16fb7baea12510a8d8a02d6 Mon Sep 17 00:00:00 2001 From: ukimsanov Date: Tue, 4 Aug 2026 03:03:36 -0700 Subject: [PATCH] docs: make the two hardest-reading pages readable, and draw the two core concepts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Prompting.** These were the only two pages that stayed hard to read once the sentence counter was corrected for bullet lists. Capstone went from 46% of sentences over 28 words to 20%, and 53 semicolons to 42. Motion went from 37% to 15%, 26 semicolons to 4, and lost six table rows that were prose in a grid. Both keep every technique and every worked example — the length barely moved, the sentences did. **Concepts.** Compositions and Determinism explain how the whole thing works and showed the reader nothing. Each has one mermaid diagram now: how an HTML file with data-* timing becomes a numbered sequence of frames, and why frame 90 always comes out the same — what is locked before frame 0, and the three things that break it. Mermaid renders natively in Mintlify, so these cost no asset, no CDN upload and no regeneration. Verified in the browser rather than assumed; the pattern is the one proven on concepts/frame-adapters. --- docs/concepts/compositions.mdx | 266 +++++++++++++++++++++++++++------ docs/concepts/determinism.mdx | 127 +++++++++------- docs/prompting/capstone.mdx | 130 +++++++++------- docs/prompting/motion.mdx | 262 +++++++++++++++++--------------- 4 files changed, 513 insertions(+), 272 deletions(-) diff --git a/docs/concepts/compositions.mdx b/docs/concepts/compositions.mdx index cb56f5592..9fa943d52 100644 --- a/docs/concepts/compositions.mdx +++ b/docs/concepts/compositions.mdx @@ -1,76 +1,250 @@ --- -title: "Understand compositions" -sidebarTitle: "Compositions" -description: "See how a HyperFrames project divides a video into timed, reusable parts." +title: Compositions +description: "The fundamental building block of a Hyperframes video." --- -A composition is a piece of a HyperFrames project with its own size and timeline. The main composition is the finished sequence. Other compositions can be scenes, captions, title systems, or reusable visual parts inside it. +A composition is an HTML file that describes a video. You write elements, give +them `data-*` timing attributes, and the framework turns them into frames. -```text -Main video -├── Opening -├── Product demo -├── Customer quote -└── Closing +`index.html` is the top-level composition. It can hold other compositions +inside it. There is no special "root" type — any composition can be imported +into any other. + +## How an HTML file becomes frames + +Here is a whole video: a logo, then a video clip. + +```html index.html +
+ + +
``` -Each part is still HTML. Studio, the agent, and normal code tools all work on the same files. +Two rules make that work. The outer element needs `data-composition-id`, and +every timed element needs `class="clip"` so the runtime can hide it outside its +own window of time. -## What a composition controls +The clips add up to five seconds. At 30 frames per second — the default — that +is 150 frames, numbered 0 to 149: -A composition brings three things together: +```mermaid +flowchart TD + A["index.html
img: start 0, duration 2
video: start 2, duration 3"] + A --> B["One timeline, 5 seconds
30 fps = 150 frames"] + B --> C["frames 0-59
image on screen"] + B --> D["frames 60-149
video on screen, playing
from its own second 0"] +``` -- **content** — text, shapes, images, video, audio, or another composition; -- **time** — when each part starts and how long it remains; -- **motion** — seekable animation tied to the same playhead. +Nothing plays in real time during a render. The renderer asks for frame 0, then +frame 1, and each answer is a single still picture. That is what makes +[rendering deterministic](/concepts/determinism). -The main composition also defines the output frame and total duration. +## What can go on the timeline -## When to create another composition +A clip is any element with timing attributes on it: -Separate a part when it has a clear job and can be understood on its own. +- `