@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
md 183 lines 12.3 KB
Rendered Raw
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 (`![...](/abs/path.mp4)`), 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.