docs(studio-app): show the app working, three new pages, today's UI

docs/custom.css

@@ -1334,3 +1334,35 @@ header.is-frame ~ #body-content #content-area {
     padding-right: 2.5rem;
   }
 }
+
+/* An image set beside the text it explains (magazine style); full width on narrow screens. */
+.hf-aside {
+  float: right;
+  width: 46%;
+  margin: 0.25rem 0 1rem 1.5rem;
+  border-radius: 0.5rem;
+  border: 1px solid rgb(0 0 0 / 0.08);
+}
+.dark .hf-aside {
+  border-color: rgb(255 255 255 / 0.1);
+}
+@media (max-width: 640px) {
+  .hf-aside {
+    float: none;
+    width: 100%;
+    margin: 0.5rem 0 1rem;
+  }
+}
+
+/* A row of portrait films with a caption under each (explainer styles and similar) */
+.hf-shelf { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 1rem; margin: 1.25rem 0 2rem; }
+.hf-shelf p { margin: 0.5rem 0 0; font-size: 0.875rem; line-height: 1.45; }
+@media (max-width: 640px) { .hf-shelf { grid-template-columns: minmax(0, 1fr); } }
+
+/* Short looping clips that show where a control is, floated beside the text that names it */
+.hf-spot { aspect-ratio: 16 / 10; object-fit: cover; border-radius: 0.6rem; background: rgb(0 0 0 / 0.06);
+  box-shadow: 0 0 0 1px rgb(0 0 0 / 0.08); margin: 0.25rem 0 1rem 1.25rem; }
+.dark .hf-spot { box-shadow: 0 0 0 1px rgb(255 255 255 / 0.1); }
+h2 { clear: both; }
+
+.hf-spot.hf-spot-inline { width: 100%; margin: 0; }

docs/docs.json

@@ -253,23 +253,19 @@
         "icon": "laptop",
         "groups": [
           {
-            "group": "Get started",
+            "group": "Studio app",
             "pages": [
               "studio-app/index",
-              "studio-app/connect-your-agent"
-            ]
-          },
-          {
-            "group": "Make videos",
-            "pages": [
               "studio-app/first-video",
+              "studio-app/existing-project",
+              "studio-app/reference-video",
+              "studio-app/brand-kits",
+              "studio-app/video-clips",
               "studio-app/edit-with-the-agent",
-              "studio-app/export"
-            ]
-          },
-          {
-            "group": "Help",
-            "pages": [
+              "studio-app/workspace",
+              "studio-app/connect-your-agent",
+              "studio-app/export",
+              "studio-app/share",
               "studio-app/troubleshooting"
             ]
           }

docs/snippets/docs-video.jsx

@@ -5,6 +5,7 @@ export const DocsVideo = ({
   autoPlay = false,
   loop = false,
   portrait = false,
+  aspect, // e.g. "16 / 10" for app recordings; the frame is 16 / 9 otherwise
 }) => {
   const videoRef = useRef(null);
   const playerRef = useRef(null);
@@ -13,10 +14,30 @@ export const DocsVideo = ({
   const [enhanced, setEnhanced] = useState(false);
   const [playing, setPlaying] = useState(false);
   const [waiting, setWaiting] = useState(false);
-  const [muted, setMuted] = useState(false);
+  // Browsers only autoplay muted video, so an autoplaying player starts muted; the sound button unmutes it.
+  const [muted, setMuted] = useState(autoPlay);
   const [currentTime, setCurrentTime] = useState(0);
   const [duration, setDuration] = useState(0);
   const [playbackRate, setPlaybackRate] = useState(1);
+  // Lazy, like ShowcaseWall's: a reduce-motion visitor's first render must not autoplay. The controls still play it.
+  const [reduced, setReduced] = useState(
+    () => typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches,
+  );
+  useEffect(() => {
+    const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const onChange = (event) => setReduced(event.matches);
+    query.addEventListener("change", onChange);
+    return () => query.removeEventListener("change", onChange);
+  }, []);
+  // Turning Reduce Motion on mid-visit must stop an autoplaying loop for real: React props can't pause it or drop
+  // its file. The play button loads it again (togglePlayback).
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!reduced || !autoPlay || !video) return;
+    video.pause();
+    video.removeAttribute("src");
+    video.load();
+  }, [reduced, autoPlay]);
   const [controlsVisible, setControlsVisible] = useState(false);
   const [fullscreen, setFullscreen] = useState(false);
   const [fullscreenSupported, setFullscreenSupported] = useState(false);
@@ -49,6 +70,7 @@ export const DocsVideo = ({
     const video = videoRef.current;
     if (!video) return;
     if (video.paused || video.ended) {
+      if (!video.getAttribute("src")) video.src = src; // dropped when Reduce Motion stopped the loop
       if (video.ended) video.currentTime = 0;
       setWaiting(true);
       try {
@@ -191,6 +213,7 @@ export const DocsVideo = ({
       <div
         ref={playerRef}
         className="hf-docs-video"
+        style={aspect ? { aspectRatio: aspect } : undefined}
         role="region"
         aria-label={title}
         tabIndex={0}
@@ -207,7 +230,8 @@ export const DocsVideo = ({
           aria-label={title}
           src={src}
           poster={poster}
-          autoPlay={autoPlay}
+          autoPlay={autoPlay && !reduced}
+          muted={autoPlay}
           loop={loop}
           playsInline
           preload="metadata"

docs/snippets/hover-video.jsx

@@ -1,4 +1,4 @@
-export const HoverVideo = ({ src, poster, className, hasAudio = true }) => {
+export const HoverVideo = ({ src, poster, className, label, hasAudio = true }) => {
   const videoRef = useRef(null);
   const wrapRef = useRef(null);
   const [muted, setMuted] = useState(true);
@@ -86,6 +86,7 @@ export const HoverVideo = ({ src, poster, className, hasAudio = true }) => {
     <div ref={wrapRef} className={className} style={{ position: "relative", overflow: "hidden" }}>
       <video
         ref={videoRef}
+        aria-label={label}
         className="absolute inset-0 h-full w-full object-cover"
         src={inView ? src : undefined}
         poster={poster}

docs/studio-app/brand-kits.mdx

@@ -0,0 +1,72 @@
+---
+title: "Use your brand kit"
+sidebarTitle: "Brand kits"
+description: "Make every video in your brand: build a brand kit from your website or your own files, then use it for a project in the HyperFrames Studio app."
+---
+
+import { HoverVideo } from "/snippets/hover-video.jsx";
+
+A **brand kit** holds your colors, fonts, logos and files. Pick one for a project and the agent builds every video
+in it: your main logo leads titles and end cards, and your colors and text styles set the look.
+
+Brand kits need you to be signed in. If the app says **Sign in to use brand kits.**, sign in first. If it says brand
+kits aren't switched on for your workspace yet, your workspace doesn't have the feature.
+
+## Make a kit
+
+<HoverVideo className="hf-aside hf-spot" src="https://static.heygen.ai/hyperframes-oss/docs/studio-demos/brand-kits-nav-v2.mp4" poster="/public/images/studio-app/spots/brand-kits-nav-v2.jpg" hasAudio={false} label="Brand kits in the sidebar" />
+
+Open **Brand kits** in the sidebar, under **Home**.
+
+<Tabs>
+  <Tab title="From your website">
+    On the **New brand kit** card, type your site, such as `yoursite.com`, and choose **Scan my site**. The app reads
+    your colors, fonts, logos and screenshots from it.
+  </Tab>
+  <Tab title="From your own files">
+    From a project's brand kit menu, choose **New kit from your own files**. You can also drop files into a chat and
+    ask Framey to put them in a kit.
+  </Tab>
+</Tabs>
+
+The agent can make a kit from a site too. It shows one approval card before it changes a kit.
+
+## What a kit holds
+
+| Part | What it does |
+| --- | --- |
+| **Colors** | Each has a role: Main, Secondary, Accent, Text, Background or Neutral |
+| **Logos** | The **Main logo** leads every title and end card. Add a full logo or a symbol |
+| **Text styles and fonts** | The type the video uses, with your font files |
+| **Files** | Screenshots, product images and audio the agent can use |
+| **Rules** | Plain-language rules, plus a brand guide PDF if you have one |
+
+To change a kit, open it and choose **Edit**: add a color, a text style, a logo or a rule, or remove what you don't
+want. Choose **Done** when you finish. The next website scan keeps what you added.
+
+Kit files can be images (PNG, JPEG, WebP, AVIF, GIF, ICO, SVG), audio (MP3, M4A, AAC, OGG, WAV) or fonts (WOFF2, WOFF,
+TTF, OTF).
+
+## Use a kit for a project
+
+<HoverVideo className="hf-aside hf-spot" src="https://static.heygen.ai/hyperframes-oss/docs/studio-demos/brandkit-chip-v2.mp4" poster="/public/images/studio-app/spots/brandkit-chip-v2.jpg" hasAudio={false} label="The brand kit menu in a project" />
+
+Each project keeps its own kit. Open the brand kit menu in the project, **Brand kit for this project**, and pick a kit,
+or **No brand kit** to let Framey choose plain styles. A project that never picked one uses your workspace's default
+kit.
+
+From a kit's page you can also choose **Use this kit**, or start **New project with this kit**.
+
+The agent reads the kit with every message, and the app copies the kit's files into the project's
+`assets/brand-kit` folder, so the video still renders the same anywhere.
+
+## Shared kits
+
+Kits other people share with you appear under **Shared with you**. You can use them but not change them. Only a
+workspace owner or admin can change the workspace's brand settings.
+
+## Related topics
+
+- [Make your first video in the Studio app](/studio-app/first-video)
+- [Edit a video with the agent](/studio-app/edit-with-the-agent)
+- [Brand, templates and storyboards](/prompting/design-systems)

docs/studio-app/connect-your-agent.mdx

@@ -1,72 +1,74 @@
 ---
 title: "Connect your agent"
-description: "Set up Claude Code or Codex once so the HyperFrames Studio app can build and change your videos."
+description: "Pick the agent the HyperFrames Studio app works with: Claude Code, Codex, Grok, Antigravity, GitHub Copilot, or OpenCode for free. The app installs it for you."
 ---
 
-The app makes your videos with an agent that runs on your computer: **Claude Code** or **Codex**. You set one up
-once. After that, every request you send goes to it.
+import { HoverVideo } from "/snippets/hover-video.jsx";
 
-| Agent | You need |
-| --- | --- |
-| Claude Code | A Claude account or an Anthropic Console account. The app installs it for you. |
-| Codex | A ChatGPT account. You install it and sign in with two commands. |
+The app makes your videos with an agent that runs on your computer. The first time you send a request without one,
+the **Connect an agent** sheet opens: choose an agent and the app installs it for you, then helps you sign in.
+
+| Agent | Sign-in | Cost |
+| --- | --- | --- |
+| Claude Code | Your browser opens Claude's sign-in: a Claude account or an Anthropic Console account. | Billed by Anthropic |
+| Codex | Your browser opens Codex's sign-in: your ChatGPT account. | Billed by OpenAI |
+| Grok | Grok gives you a code to confirm in your browser. | Billed by xAI |
+| Antigravity | Signs in from Terminal: the sheet gives you the command. | Billed by Google |
+| GitHub Copilot | Signs in from Terminal: the sheet gives you the command. | Billed by GitHub |
+| OpenCode | None: it runs free models. Sign in to a provider from Terminal to add its models. | Free |
 
 Runs bill to the plan of the account your agent is signed in with. To use an API key instead, change **Bill runs
 to** in **Settings** > **Permissions**.
 
-If both are ready and you have not picked one, the app uses Claude Code.
-
-## Claude Code
+## Set one up
 
-The first time you send a request without an agent, the **Connect Claude Code** screen opens with three steps.
+<HoverVideo className="hf-aside hf-spot" src="https://static.heygen.ai/hyperframes-oss/docs/studio-demos/settings-permissions-v2.mp4" poster="/public/images/studio-app/spots/settings-permissions-v2.jpg" hasAudio={false} label="Settings, Permissions: every agent and its state" />
 
 <Steps>
-  <Step title="Install Claude Code">
-    Choose **Install Claude Code**, then **Install** in the dialog. The app runs Anthropic's official installer,
-    which puts Claude Code in your home folder. It takes about a minute.
+  <Step title="Choose an agent">
+    In **Connect an agent**, choose **Install** next to the agent you want, or **Use** next to one already on your
+    computer. The app asks **Install … from …?** and runs that company's official installer. It takes about a minute.
   </Step>
   <Step title="Sign in">
-    Choose **Sign in to Claude**. Your browser opens Claude's sign-in. Use your Claude account or an Anthropic Console
-    account, then come back to the app.
+    Choose **Sign in to Claude Code** (or your agent's name) and finish in your browser, or follow the sheet's
+    Terminal step for Antigravity, GitHub Copilot and OpenCode.
   </Step>
-  <Step title="Check that it answers">
-    The app checks that Claude Code runs. When it shows **Claude Code is connected**, it sends the request you
-    started with.
+  <Step title="Send">
+    When the agent answers, the app sends the request you started with.
   </Step>
 </Steps>
 
-If a step fails, the app shows a command you can run yourself. Choose **Copy command**, then **Open Terminal**, and
-paste it:
+If a step fails, the sheet shows the command to run yourself: choose **Copy**, then **Open Terminal**, and paste it.
 
-```bash
-# Install Claude Code
-curl -fsSL https://claude.ai/install.sh | bash
+| Agent | Install command | Sign in |
+| --- | --- | --- |
+| Claude Code | `curl -fsSL https://claude.ai/install.sh \| bash` | `claude auth login` |
+| Codex | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` | `codex login` |
+| Grok | `curl -fsSL https://x.ai/cli/install.sh \| bash` | `grok login` |
+| Antigravity | `curl -fsSL https://antigravity.google/cli/install.sh \| bash` | run `agy` once |
+| GitHub Copilot | `curl -fsSL https://gh.io/copilot-install \| bash` | `copilot login` |
+| OpenCode | `curl -fsSL https://opencode.ai/v2/install \| bash` | optional: `opencode providers login` |
 
-# Sign in
-claude auth login
-```
+## Access: Auto or Full access
 
-## Codex
+<HoverVideo className="hf-aside hf-spot" src="https://static.heygen.ai/hyperframes-oss/docs/studio-demos/settings-agent-v2.mp4" poster="/public/images/studio-app/spots/settings-agent-v2.jpg" hasAudio={false} label="Settings, Agent: Auto or Full access" />
 
-The app does not install Codex for you. Open **Settings** > **Agent** or the agent picker in the chat header, find
-Codex, and use its buttons:
+**Auto**, the default, lets your agent work in your project and use the internet, and blocks risky steps. **Full
+access** lets it install and run anything, with no checks. Change it in **Settings** > **Agent**.
 
-1. **Copy install command**, then paste it into a terminal:
-   ```bash
-   curl -fsSL https://chatgpt.com/codex/install.sh | sh
-   ```
-2. **Copy sign-in command** (`codex`), run it in a terminal, and sign in with your ChatGPT account.
-3. Back in the app, choose **Check again**. Codex shows **Ready**.
+GitHub Copilot and OpenCode only run with **Full access**: the first time you send to one, the app asks to **Turn on**
+Full access.
 
 ## Switch agents
 
-Use the agent picker in the chat header, or **Settings** > **Agent**, and choose **Use** next to the agent you want.
-The choice applies to your next request.
+<HoverVideo className="hf-aside hf-spot" src="https://static.heygen.ai/hyperframes-oss/docs/studio-demos/agent-picker-v2.mp4" poster="/public/images/studio-app/spots/agent-picker-v2.jpg" hasAudio={false} label="The agent picker in the chat header" />
 
-Each agent row shows its state: **Ready**, **Not signed in**, **Not installed**, or **Installed, but won't start**,
-with the button that fixes it.
+Open the agent picker in the chat header and choose a ready agent; it's used from your next request. To set the
+agent, model and effort for every new request, use **Settings** > **Agent**. **Settings** > **Permissions** lists
+every agent with its state (**Ready**, **Not signed in**, **Not installed**, **Needs an update**) and the button that
+fixes it.
 
 ## Related topics
 
 - [Make your first video](/studio-app/first-video)
-- [Updates and troubleshooting](/studio-app/troubleshooting)
+- [Troubleshooting](/studio-app/troubleshooting)