The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 07:15 UTC
| 1 | --- |
| 2 | name: launch-video |
| 3 | description: Make a short launch video (1920x1080 MP4 plus an outro PNG) that demos a T3 Code feature, built from the real app with added motion, for an X/Twitter announcement or release thread. Use when asked for a launch video, demo video, feature teaser or announcement clip, or to add a video to a release tweet. |
| 4 | --- |
| 5 | |
| 6 | # Launch videos |
| 7 | |
| 8 | A launch video is 20–30 seconds: the app goes through one story in two or three beats, |
| 9 | the camera punches in on each, a caption names it, and an outro card closes. Frames are |
| 10 | rendered one by one in headless Chromium, so the result is deterministic. |
| 11 | |
| 12 | There are two ways to build one: |
| 13 | |
| 14 | - **Real app (default).** A staging script runs the real server and web client with fictional |
| 15 | data and the free replay agent, drives the flow in a browser, and freezes the page at each |
| 16 | beat into `beats/<name>.html`. The story stacks those frozen pages and adds the motion: the |
| 17 | camera, cursor, pops, glows, typing and captions. The UI is whatever the app draws today, so |
| 18 | re-staging on main updates the video. `stagings/linked-environments/` is a finished example. |
| 19 | - **Mock.** `template/story.html` is a hand-built HTML copy of the app (the 0.1.11 tunnels |
| 20 | video). Use it only for what a staging can't produce, such as another app on the desktop or |
| 21 | a desktop-only screen. It drifts as the app changes. |
| 22 | |
| 23 | ## Workflow (real app) |
| 24 | |
| 25 | 1. **Learn the feature.** Read the PRs and the components it touches. Write down the one |
| 26 | thing a user can now do that they couldn't before, in the user's words. |
| 27 | 2. **Write the story** before any code: who the user is, what they want, and two or three |
| 28 | beats that get them there. Show it to the maintainer if the angle is a guess. |
| 29 | 3. **Stage it.** Copy `stagings/linked-environments/` to `stagings/<slug>/`. |
| 30 | - `serve.mjs` builds fresh homes under `.t3/launch/<slug>/` with `scripts/stage-env.mjs`. |
| 31 | Each home gets a fictional machine label, the replay agent, and no paid provider. |
| 32 | It starts the servers, creates projects, writes `<out>/stage.json` and keeps running. |
| 33 | Run it in the background. |
| 34 | - `drive.mjs` opens the web client with `openBrowser()` (1440×720, dark, release |
| 35 | branding) and walks the flow. It calls `beat(name)` at each moment the video needs. |
| 36 | Re-run it as often as you like against the same servers. |
| 37 | - Agent turns: pass `claude: [turns]` to `prepareHome` and the real Claude provider runs |
| 38 | `scripts/fake-claude.mjs` as its CLI, so the video shows Claude's logo, models, thinking |
| 39 | and tool rows. Each turn is `{ match, steps }`: `think`, `text`, `bash` (+ `output`, `ms`), |
| 40 | `wait`, and `tool` (+ `input`), which calls that T3 MCP tool for real, e.g. |
| 41 | `delegate_task`. Match generated titles with a `{ match: "title", repeat: true }` turn. |
| 42 | `<var:name>` is filled from the JSON file at `FAKE_CLAUDE_VARS`, for ids that change |
| 43 | every run. `fake-claude.log` in the home records the protocol, for debugging. |
| 44 | - Data a real flow can't produce cheaply goes into the app's own stores, never into pixels. |
| 45 | `insertPeerLinks` writes link rows into a stopped server; `serveDescriptors` makes fake |
| 46 | machines answer the reachability probe. The client's saved environments and routes live |
| 47 | in IndexedDB (`t3code:connection-runtime` / `catalog` / `document`): write the document |
| 48 | from the page after its first load, then reload. Route kinds come from hostnames |
| 49 | (`*.localhost` is LAN, `*.ts.net` Tailscale); Chrome's |
| 50 | `--host-resolver-rules=MAP *.tail-demo.ts.net 127.0.0.1` makes fake tailnet names work. |
| 51 | - Gestures: hold the mouse down, move in steps, and `saveBeat` mid-drag to freeze the |
| 52 | app's own drag line and highlight; animate between those beats with `Kit.reveal`. |
| 53 | - A capped, scrolling modal freezes at different scroll offsets per beat. Freeze at a |
| 54 | viewport tall enough that nothing scrolls, and size `.app` to match. |
| 55 | - Without `claude`, turns go to the dev replay agent (`apps/server/scripts/dev-replay-agent.ts`), |
| 56 | which shows as an ACP provider. |
| 57 | 4. **Create the story:** `scripts/new.sh ~/launch-videos/<slug>`, then copy the beats in, or |
| 58 | pass that directory as the staging's `<out>`. Add one `<iframe data-beat>` per beat and |
| 59 | write `setup()` and `placeCursor()` (see Anatomy). |
| 60 | 5. **Find targets** in a beat: `scripts/find.mjs <dir>/beats/<name>.html "<text>"` prints |
| 61 | selectors and boxes for the elements containing that text and their ancestors. |
| 62 | 6. **Probe** with contact sheets at every beat, fix, repeat: |
| 63 | `scripts/sheet.sh ~/launch-videos/<slug> 1,4.5,8,12,16,21,26` then Read `sheet.png`. |
| 64 | The times are video seconds (after `Kit.timeline`), not animation seconds. Read the |
| 65 | full-size frames in `probe/` to check small text. A probe takes about 2 s a frame. |
| 66 | 7. **Render:** `scripts/render.sh ~/launch-videos/<slug> t3code-<slug>` gives |
| 67 | `t3code-<slug>.mp4` and `outro.png`. A 30 s video takes 3–6 minutes. |
| 68 | 8. **Hand back** with the video and outro embedded (``), the caption |
| 69 | copy, any `Kit.text` edits, and anything you assumed rather than verified. |
| 70 | |
| 71 | The scripts need this repo's `node_modules` (`vp i`) for `playwright-core`, any Chromium in |
| 72 | the Playwright cache (or `CHROME=/path`), and `ffmpeg` on PATH. Stop `serve.mjs` with your |
| 73 | harness's task stop; it ends its servers' process groups. |
| 74 | |
| 75 | ### Staging traps |
| 76 | |
| 77 | - **Machine names and icons.** `T3CODE_ENVIRONMENT_LABEL` and `T3CODE_ENVIRONMENT_MACHINE_KIND` |
| 78 | (laptop, desktop, cloud, linux, mac-mini, mac-studio) override what the server detects. |
| 79 | `prepareHome({ label, machine })` records them and `startEnvironment` and `cli()` pass them |
| 80 | on; the CLI needs them too, because a link introduces the machine by its label. |
| 81 | - **Linked environments** refuse loopback addresses ("this machine"), and plain http works |
| 82 | only on tailnet names. `serve.mjs` links to this machine's tailnet DNS name. |
| 83 | - **Leaks.** Grep the beats for the real hostname, username and tailnet name before |
| 84 | rendering. `snapshot.mjs` drops hidden inputs' values (they hold local paths). |
| 85 | - **Timing.** A replayed turn streams in real time (each frame delay caps at 2 s). Make a |
| 86 | recording long enough for the drive to catch the state you need, and freeze beats on a |
| 87 | timer when the UI summarises (a running command shows only "Running pnpm"). |
| 88 | - **Agent wake-ups.** When a delegated child finishes, the parent agent gets a new turn. Give |
| 89 | its recording a second turn, or the first replays and delegates again. |
| 90 | |
| 91 | ## What the maintainers asked for |
| 92 | |
| 93 | These came from review of the 0.1.11 videos. Each one was a real correction. |
| 94 | |
| 95 | - **It must look like the real app.** "Quite far off how it actually looks" was the first |
| 96 | round's verdict on a mock. Stage the real app; mock only what can't be staged, rebuilt from |
| 97 | the real component (strings live in `apps/web/src/i18n/translations/en.json` under hashed |
| 98 | keys, so grep by the text). |
| 99 | - **Punchier than the app.** Extra motion is welcome (pops, glows, punch-ins, typing), as |
| 100 | long as every pixel it moves is the real UI. |
| 101 | - **Readable on a phone.** Captions are 40px; zoom the camera 1.5–1.9× onto whatever the |
| 102 | beat is about. If text is under ~14px after zoom, zoom further or cut it. |
| 103 | - **Slow enough to follow.** Slow the key interactions to 0.6–0.8× and hold 0.8–1.5 s after |
| 104 | each payoff. A viewer must see the result before the next beat starts. |
| 105 | - **A realistic example.** The demo has to be something a user would really do. A local |
| 106 | terminal querying a forwarded port was rejected ("why not use the in-app terminal?"); |
| 107 | a desktop database client was the right example. |
| 108 | - **Distinct features read as distinct.** Two features get two numbered captions and two |
| 109 | clearly separate payoffs, never one blended beat. |
| 110 | - **Brand.** Production logo only (`logo-prod.png`, from `assets/prod/`), never the blue |
| 111 | dev icon. The app's dark palette (below); orange only where the app uses it. |
| 112 | - **Only announced things.** Before showing a screen, check it ships enabled. Feature-flagged |
| 113 | or separately announced work (for 0.1.11: GitHub sign-in and PR tooling, the mobile app) |
| 114 | stays out, even as background UI. A video whose subject is an opt-in Labs feature is |
| 115 | fine when the maintainer asked for it; say where to turn it on in the caption or tweet, |
| 116 | and ask whether the outro should call it a beta. Ask when unsure. |
| 117 | - **Fictional demo data.** Project `acme/mugshot`, machine `devbox`, made-up people with |
| 118 | `@example.com`. No real people, teams, emails, repos or the user's own threads. |
| 119 | - **Timing is checked, not assumed.** Typing must finish before the cursor clicks, a |
| 120 | tooltip must appear before it is read, and card text must not overflow. The contact |
| 121 | sheet catches these; full-size probe frames catch the rest. |
| 122 | |
| 123 | ## Look |
| 124 | |
| 125 | From `apps/web/src/index.css`, dark theme: |
| 126 | |
| 127 | - Background `#000` with a faint primary glow at the top (`rgba(52,107,241,.13)`). |
| 128 | - Text `#f1f3f7`, secondary `#a3a3a3`, UI muted `#8e8e93`, dim `#636368`. |
| 129 | - Borders `#1d1d20` or white at 8%; surfaces `#0e0e0f` to `#191a1d`; chips `#191a1d`. |
| 130 | - Primary `#346bf1`, light primary `#6e9bfb`, success `#4ade80`, destructive `#e5484d`. |
| 131 | - Orange `#f07a4a` only for the agent ✳ next to a Claude model and provider marks. |
| 132 | - Fonts: Inter (UI) and JetBrains Mono as `JB` (code, ports, versions, URLs). |
| 133 | |
| 134 | ## Anatomy of a real-app story |
| 135 | |
| 136 | Everything runs on one clock in **animation seconds**. capture.mjs serves the directory over |
| 137 | HTTP, loads the beats, calls `setup()`, seeks to `layoutTime`, calls `placeCursor()`, then |
| 138 | seeks every animation (in the story and inside each beat) to each frame's time. |
| 139 | |
| 140 | - **Canvas** 1600×900 CSS px, rendered at device scale 1.2 to 1920×1080. Beats were frozen at |
| 141 | 1440×720 and `.app` scales them 1.0556× into the 1520×760 window, so beat point (x, y) is |
| 142 | canvas (40 + 1.0556·x, 26 + 1.0556·y). |
| 143 | - **Targets** are `"<beat> >> <css>"` (or `"* >> <css>"` for every beat). Prefer the app's |
| 144 | `data-*` and `aria-label` attributes; `find.mjs` prints them. A trailing `:text(words)` |
| 145 | keeps the matches containing those words, e.g. `[role=menuitem]:text(From MacBook)`. |
| 146 | - **Beat size.** Each beat records the viewport it was frozen at (`kit-viewport` meta). |
| 147 | Size `.app` and its iframes to match and scale them to the 1520×760 window |
| 148 | (1440×720 → 1.0556, 1600×800 → .95). |
| 149 | - **`setup()`**: `Kit.beats([[name, at, fade?], ...])` gives each beat one visibility window. |
| 150 | Then the motion, all at absolute times: |
| 151 | `Kit.pop / rise / slide / stagger / type / press / punch / fadeIn / draw` animate elements inside |
| 152 | a beat; `Kit.glow(target, at)` draws a ring on the story layer, so app overflow can't |
| 153 | clip it; `Kit.anim` takes raw keyframes; `Kit.text` makes a static edit (say so at |
| 154 | handback). |
| 155 | - **`placeCursor()`**: wrap in `Kit.measure` and call `Kit.camera(steps)` and |
| 156 | `Kit.cursor("#cur", steps)` there. Both take `{ t, on|at: target, ... }` steps measured at |
| 157 | `layoutTime` with the camera at rest. Pick a `layoutTime` after every entrance has |
| 158 | finished. Camera steps centre `on` at screen height `y` (default 420, clear of the captions) |
| 159 | at scale `s`; repeat a step to hold. Cursor clicks draw a ripple. |
| 160 | - **Captions** `.cap`: a numbered chip, a bold lead phrase and a muted rest. Short enough to |
| 161 | read in two seconds. Play them with `Kit.captions([[selector, from, to], ...])`, which |
| 162 | throws if two overlap; two captions crossfading read as garbled text. |
| 163 | - **Pacing**: `Kit.timeline([[realSeconds, animFrom, animTo], ...])` maps video time to |
| 164 | animation time; `animFrom == animTo` holds a frame. It also sets the video length. |
| 165 | - **Outro** `.outro`: logo, a two-line headline, "Available now in **T3 Code** `<version>`", |
| 166 | `t3.codes`. Change the headline and version, keep the rest. Hold it about 3 s. |
| 167 | |
| 168 | Two animations on one property of one element fight (the later one wins for its whole |
| 169 | fill). Give an element one animation per property, as `Kit.beats` does for visibility. |
| 170 | |
| 171 | ### Mock stories |
| 172 | |
| 173 | `template/story.html` uses the same kit (cursor, timeline) but draws the app in HTML on a |
| 174 | 2000×1000 `.stage` scaled .76 (stage point (x, y) is canvas (40 + .76·x, 26 + .76·y)), with CSS |
| 175 | `@keyframes` and delays for motion and one `@keyframes camera` for the camera. Rebuild any |
| 176 | screen it lacks from the real component's strings, layout and lucide icons. |
| 177 | |
| 178 | ## Delivery checklist |
| 179 | |
| 180 | - [ ] 1920×1080, 30 fps, 20–30 s (`render.sh` prints it). |
| 181 | - [ ] Every beat checked in a contact sheet and at full size. |
| 182 | - [ ] No unannounced feature, real person, real machine name or real thread on screen. |
| 183 | - [ ] `outro.png` exported and embedded in the reply with the video. |