How the editor is built
Yaazh's editor is where a recording, or any video, becomes a finished edit: a media browser, a player, an inspector and a timeline, over a project saved as JSON. The app is Tauri 2. A small Rust core owns what has to be native (capture, files, ffmpeg, extra windows), and a React 19 + TypeScript webview, built with Vite and Tailwind v4 and holding its state in zustand, owns the interface, the editing model and the frame compositor.
UI
src/components/** and src/pages/Editor.tsx. A component reads state from a store and calls an action. It holds no editing logic and does not call a service that a store could call for it.
Stores
src/store/**, zustand. The open project and everything derived from it, the playhead and selection, the UI state, settings, and every editing action with its undo step.
Pure logic
src/lib/**. No React, no stores, no Tauri: timeline maths, the playback clock, the compositor, the inspector's search index. This is what the tests in tests/ target.
Services and Rust
src/services/** talks to the OS and to Rust through services/api.ts (typed commands) and services/bridge.ts (Tauri IPC, or services/mock.ts in a plain browser). Rust commands live in src-tauri/src/**.
UI components/editor/**, pages/Editor.tsx
reads state with selectors, calls actions
│
▼
Stores store/** (zustand)
the project + derived data, playhead, selection, every edit, undo
│ │
▼ ▼
Pure logic lib/** Services services/**
timeline, api.ts → bridge.ts
clock, │ Tauri IPC: invoke, events, asset:// media
compositor │ (services/mock.ts when there is no Tauri)
(tested) ▼
Rust src-tauri/src/commands/* thin wrappers → export/ ffmpeg/ project/ mcp/ …Assistants edit through the same stores. Rust serves the MCP connection (src-tauri/src/mcp/), but the tools themselves run in the webview (src/services/mcp/) against the live project, so an assistant's change is an ordinary edit: it shows at once, it can be undone and autosave writes it.
Set up, run and build
| You need | Why |
|---|---|
| Node.js 22.18 or newer | The developer scripts use Node's TypeScript stripping. The workspace is verified on Node 24. |
| pnpm | The repository has a pnpm-lock.yaml. Scripts also run with npm run. |
| Rust stable, 1.80 or newer | The rust-version in src-tauri/Cargo.toml. |
| Visual Studio Build Tools, "Desktop development with C++" | The MSVC linker and the Windows SDK. Build from PowerShell: Git Bash's link shadows MSVC's link.exe. |
| Edge or Chrome | The hidden-browser checks (npm run try) and web-part renders drive a headless copy. |
| ffmpeg (optional) | Not needed to build: the app finds ffmpeg 5 or newer, or downloads a static build on first use. On PATH (or in FOCAL_FFMPEG) only to make the mock's demo clip. |
Install
In the app's folder (still named
focal/), runpnpm install.Run the editor in a browser
pnpm dev --port 5177, then openhttp://localhost:5177. With no Tauri present,services/bridge.tssends every command toservices/mock.ts, which signs in a mock account and serves a demo project fromdev-assets/demo.mp4(git-ignored; make one withnode scripts/make-demo-clip.mjs). Recording, export, presets and file dialogs are simulated. This is the fastest loop for layout work.Run the real app
pnpm tauri devbuilds the Rust side and starts Vite on port 1420 with hot reload. Vite holds 1420 strictly for Tauri, which is why the browser loop uses another port.Build it
pnpm tauri build --no-bundletakes about three minutes and writessrc-tauri/target/release/focal.exe.pnpm tauri buildmakes the installers.npm run buildbuilds the frontend only: it regeneratessrc/services/mcp/editorSchema.json, runstscand runsvite build.
pnpm install
pnpm dev --port 5177 # the editor in a browser, mock backend
pnpm tauri dev # the native app, hot reload
pnpm tauri build --no-bundle # ~3 min: src-tauri/target/release/focal.exe
pnpm tauri build # installersWhere code goes
| What | Where |
|---|---|
| Pure logic: no React, no stores | src/lib/**. This is what tests target. |
| Talking to Rust, the OS or files | src/services/** |
| App state and every editing action | src/store/** (zustand). Actions live here, not in components. |
| UI | src/components/**, pages in src/pages/** |
| Hooks that wire the UI to the stores | src/hooks/**: usePlaybackEngine, useEditorShortcuts, useWindowShortcuts |
| Rust commands | src-tauri/src/**: thin wrappers in commands/, the work in its own module |
| Tests | tests/** (Vitest), Rust tests beside the code and in src-tauri/tests/ |
| Docs | docs/*.md, changed in the same change as the code |
If a rule can be expressed without React, it belongs in src/lib, with a test. A component that grows editing logic is the most common way this layout erodes.
Split at about 300 lines
Files stay small and single-purpose. When one grows past about 300 lines, split it the way components/editor/library/ and components/editor/inspector/ are split: a shell, a table of contents, and one file per panel. In the browser that is LibraryPanel.tsx (shell), tabs.tsx (table) and one file per tab; in the inspector it is Inspector.tsx (shell and ROUTES) and one file per panel in inspector/.
The editor's main files
| File | What it is |
|---|---|
src/pages/Editor.tsx | The layout: header, browser · player · inspector, timeline across the bottom. Mounts the editor's shortcuts and the 2.5 s autosave. |
components/editor/library/ | The media browser: LibraryPanel, LibraryRail, LibraryToolbar, TabRow and the tab table tabs.tsx. |
components/editor/Preview.tsx | The player. Mounts usePlaybackEngine, draws with renderFrame, owns the transform handles and drops onto the video. |
components/editor/Inspector.tsx | The right panel: the ROUTES table, the project page and its groups; panels in inspector/. |
components/editor/timeline/ | Timeline.tsx (lanes and drop targets), lanes.tsx, Block.tsx, BlockMenu.tsx, AudioLane.tsx, GroupLanes.tsx (the recording's layers). |
components/editor/CommandMenu.tsx | The command menu, mounted once per window by the shell in App.tsx. |
components/ui/ | The primitives: Controls.tsx, NumberField.tsx, Group.tsx, Button.tsx, PanelResizer.tsx, Dialog.tsx. |
State, actions and undo
| Store | Holds |
|---|---|
store/project.ts · useProjectStore | project, events, derived, dirty, past/future; load, update, pushHistory, undo, redo, save. |
store/playback.ts · usePlaybackStore | The playhead in output time (tOut), playing, and the selection: a SelectionKind plus an id. |
store/ui.ts · useUiStore | The view (Home, Record, Editor, Board, Code), open dialogs, the command menu and the timeline scope ("main", "group", compound:<id>). |
store/settings.ts · useSettingsStore | App preferences in localStorage: the open browser tab, panel widths, the last export. A storage listener carries changes to the other windows so none writes an older copy back. |
store/actions.ts and store/*Actions.ts | The editing actions, split by subject (clipActions.ts, mediaActions.ts, keyframeActions.ts, zOrderActions.ts…). The transport bar, shortcuts, context menus, the command menu and assistant tools all call the same ones. |
Every change goes through update
/** Apply a change. `history` (default true) records an undo step. */
update: (fn: (p: Project) => Project, opts?: { history?: boolean; replan?: boolean }) => void;
/** Push a pre-change snapshot (used by drags that update live with history: false). */
pushHistory: (snapshot: Project) => void;
/** Convenience: patch the timeline with one undo step. */
export function updateTimeline(fn: (tl: Project["timeline"], p: Project) => Project["timeline"], opts?: { history?: boolean }): void- Return new objects, never mutate.
derive()decides what to rebuild by comparing references (a newtimelinerebuilds the play segments; a newcameraorzoomsre-simulates the camera), and structural sharing is what keeps whole-project undo cheap. - After every change the store runs
growToFit(lib/timeline/length.ts: the project is exactly as long as what is on it, with a recording as the floor), thenderiverebuilds only what changed: the event index, camera track, cursor track, keystrokes, play segments, sound cues and viewport. - Undo snapshots the whole
Project, up to 80 steps (MAX_HISTORY). - A drag is one undo step. Update live with
{ history: false }on every move, then push the snapshot taken on pointer-down when it is released. - Autosave runs 2.5 s after the last change (
pages/Editor.tsxcallssave(), which invokessave_project). The header's dot shows saved, waiting or writing; Ctrl+S saves now. - Who changed what. Edits made while an assistant's tool runs are attributed to it (
lib/project/actor.ts), andstore/history.tsfiles them as versions for the History panel.
// timeline/Block.tsx, while the pointer moves
useProjectStore.getState().update(() => moveSelection(d.snapshot!, d.plan!, s - d.s0), { history: false });
// timeline/ClipVolume.tsx, on release
if (d.snapshot) useProjectStore.getState().pushHistory(d.snapshot);The project model
A project is a folder, by default under Videos\Focal\ (src-tauri/src/paths.rs); New project can put one anywhere. The editor writes project.json; Rust writes the recording's own files. docs/project-format.md is the field-by-field reference.
| File | Written by | What it holds |
|---|---|---|
project.json | The editor | The serialized Project from src/lib/types.ts, written whole. Rust treats it as opaque JSON and reads only name, durationMs, width and height for the home grid. |
events.json | Rust | Cursor moves, clicks, keys, scrolls, window switches and marks, in ms of video time with coordinates 0..1. Imported videos and blank projects get empty arrays. |
recording.mp4, system.wav, thumb.jpg | Rust | The screen, the system sound and the home-screen thumbnail. |
camera.webm / camera.mp4 | The webview | Camera and microphone, from MediaRecorder. |
category.txt, tags.txt | Rust | Filing for the home screen. Kept out of project.json because the editor writes that file whole from the project it has open, and would drop a field it was never told about. |
Project has settings groups (camera, cursor, background, frame, effects, motion, screenMotion, filters, enhanceVideo, webcam, audio, music, sounds, captions), the media library mediaPool, syncOffsetMs, and the timeline (TimelineModel): trim, cuts, holes, gaps, speeds, zooms, layouts, masks, cursorHides, splits, audioMutes, audioGains, media, tracks, groups, transitions, progress and more.
Two clocks
Source time is milliseconds in the recording. Output time is milliseconds in the finished video, after cuts, holes, gaps and speed regions. lib/timeline/mapping.ts converts between them (buildSegments, outToSrc, srcToOut). Items on tracks are placed in source time (start/end) but play on the output clock (mediaTimeAt in lib/timeline/clips.ts), so a cut underneath a clip is skipped rather than cutting the clip. Keyframe times are ms after the item's start. Know which clock a value is in before you add to it.
Tracks and lanes
Top to bottom (components/editor/timeline/Timeline.tsx): the "Add video track" drop strip · overlay tracks, highest drawn on top (MediaItem.track) · effect lanes (Zoom, Camera, Moves, Speed, Masks, Cursor, Captions, Progress, Tracking, Motion) · Video, the recording · its sound (Voice, System, Music) · audio tracks · the "Add audio track" strip. A lane exists only while something is on it, or while a thing of its kind is selected. Track counts come from the items (trackCount, audioTrackCount in lib/media/tracks.ts); timeline.overlayTracks and audioTracks are still in the file but nothing reads them for the layout.
- Delete on a piece of the recording leaves an empty stretch (
timeline.holes,lib/timeline/holes.ts): the screen picture and its own sound go, the time stays, and everything on the tracks keeps its place. - Ripple delete closes the gap; a cut takes the time out of the output; a gap (
lib/timeline/gaps.ts) puts empty time in. - Clip speed (
lib/media/clipSpeed.ts) retimes one clip; a speed region retimes the whole sequence and only exists for a recording.
The recording is a compound clip
On the main timeline the recording is one block on the Video lane. Opening it (double-click, right-click › Open compound clip, or the scope picker above the timeline) sets ui.timelineScope to "group" and shows its layers as lanes (timeline/GroupLanes.tsx): Background, Screen, Camera, Cursor, Keys, Voice and System. The layers are the recording's own, so Delete switches one off (switchLayerOff in store/actions.ts); only the screen cannot go: split it and delete pieces. A project started from a blank canvas has no Video lane at all: its canvas is a backdrop, not something you cut.
The playback clock
The hidden <video> of the recording is the clock, and everything else follows it. hooks/usePlaybackEngine.ts, mounted by Preview.tsx, runs one requestAnimationFrame loop. Each frame it asks stepClock in lib/playback/clock.ts, a pure function of the element's state, what the clock says now, then moves everything else to match.
export function stepClock(video: MainLike, segments: readonly PlaySegment[], durationMs: number, tOut: number, now: number, st: ClockState): Decision
export type Decision =
| { kind: "stop" }
| { kind: "wait"; tSrc: number; reseek: boolean }
| { kind: "wall"; tOut: number; tSrc: number; nudge: boolean }
| { kind: "gap"; tOut: number; tSrc: number }
| { kind: "jump"; tOut: number; tSrc: number; seekTo: number | null; speed: number; chase?: boolean }
| { kind: "advance"; tOut: number; tSrc: number; speed: number };| Decision | When |
|---|---|
advance | The ordinary frame: the clock is wherever the element is, mapped through the kept segments. |
jump | The end of a segment: carry on into the next, seeking only across a real cut, never at a speed boundary. |
wait | The element is mid-seek: draw, hold the clock. A seek not landed after 2.5 s is asked for again once, and given up on after 6 s. |
wall | The recording ran out before the timeline did, or stalled: the clock runs off the wall clock. A stalled element is nudged with play(), an ended one never is. |
gap | Inserted empty time: the recording is parked on the frame it resumes from while the clock runs off the wall. |
stop | Nothing left to play. |
The rules
- The clock never runs backwards on its own. Only a seek somebody asked for moves it back.
- Nothing runs ahead of a clock that has stopped. While the recording seeks, the camera, the system audio, the music and every media clip are parked, paused, on the time the clock will resume at. An element at the end of its own file is never
play()ed again: that starts it over from the top. - A silent recording does not set the pace. When the voice comes from somewhere else, the clock keeps real time (within
PACE_SLACK, 3%) and the picture is pulled after it. The code lists this as a third rule beside the two inCLAUDE.md.
Everything else follows
The camera, system audio, music, background video and every media clip are kept on the clock by followClock(el, targetSec, run, baseRate, mode), which answers hold, park, seek, steer or done. Anything heard is steered gently (GENTLE: the rate leans at most 6% and only a half-second drift is seeked). A silent picture that has to match the one under it is steered hard (LOCKED, lib/playback/pictureLock.ts). A blank canvas hands the clock no picture at all (NO_PICTURE in the engine), so it runs off the wall.
Never seek an element every frame
A seek that cannot land (a file that will not seek accurately) starves the decoder and freezes the picture. Ask once, allow a retry after a while, and let a near-enough frame be near enough. needsHoldSeek is the pattern to copy:
/** A frame frozen this far off its mark is the right frame to the eye (ms). */
export const HOLD_TOLERANCE_MS = 120;
/** Never ask one element for the same frozen frame more often than this (ms). */
export const HOLD_RETRY_MS = 400;
export function needsHoldSeek(offMs: number, edgeMs: number, last: { edge: number; at: number } | undefined, nowMs: number): boolean {
if (offMs <= HOLD_TOLERANCE_MS) return false;
// A different frame is a different question, and gets asked straight away.
if (!last || Math.abs(last.edge - edgeMs) >= 1) return true;
return nowMs - last.at > HOLD_RETRY_MS;
}Web Audio taps are one-way
createMediaElementSource can be called once per element, ever, and a tapped cross-origin element is silent unless it was loaded with crossOrigin; the asset protocol is another origin. So build a graph only for an element that needs one. lib/audio/voiceGraph.ts does exactly that: the first attach reloads the element with crossOrigin set, and puts it back as it was if that reload fails.
One renderer for preview and export
renderFrame in lib/render/compositor.ts draws any moment of the edit onto a 2D canvas. The player (Preview.tsx), the frame capture (services/frameCapture.ts) and the exporter (services/export.ts) all call it, so what you preview is what you export. A feature drawn only in the player is not a feature.
export function renderFrame(ctx: CanvasRenderingContext2D, outW: number, outH: number, scene: Scene, src: FrameSources, tSrc: number, tOut?: number): FrameResultScene carries the project and its derived data; FrameSources carries decoded frames, media pixels, the webcam matte and the background video. The FrameResult it returns (layout, the bubble's rect, the caption box, the progress box) is what the player hangs its handles on.
| Step | What is drawn |
|---|---|
| 1 | The background (render/background.ts). |
| 2–5 | The screen layer (render/screenLayer.ts): card shadow; chrome and inset; the video through the camera pose with colour filters, motion blur and the vignette; masks, typing halo, window outline and cursor inside the video; the frame border. Drawn offscreen and composited (render/cardMotion.ts) only while a screen move is live. |
| 6 | Keystroke chips, then media items by track (render/media.ts), with the camera bubble at its layer (webcam.layer) or over all of them; frame masks; transitions painted over the recording's own cuts. |
| 7 | Captions, in the output frame, over everything. |
| 8 | The progress indicator, last: the only thing that reads the output clock. |
Filters, blend modes and masks
- Colour filters.
FilterSettingsbecomes a canvas filter string throughfilterString()plusdrawVignette()(lib/render/filters.ts). The recording's grade isproject.filters; every item can carry its ownfilters. - Blend modes. Any canvas composite operation.
inspector/BlendPicker.tsxpreviews each with CSSmix-blend-mode, which takes the same names, so the sample is the real thing. - Masks.
lib/render/masks.ts; a mask can follow a motion track (trackedMasks). Blur masks use canvasfilter, which needs Safari/WebKit 18 or newer on macOS; older WebKit falls back to pixelation.
Anything built out of these works in the preview and the export alike, which is the point. Something that only exists in a browser panel is not a filter.
A transition is one definition in four files
| File | Says |
|---|---|
lib/media/transitionKinds.ts | What it is called, what it is filed under, the other editors' names for it, and whether it is painted over the frame (paint). |
lib/media/transitionMotion.ts | What it does to each clip: modifier(kind, progress, side). |
lib/media/transitionShapes.ts | The shape a wipe reveals through, as normalized geometry: a canvas path (render/reveal.ts) and a CSS clip-path from one definition. |
lib/media/transitionPaint.ts | What is painted over the frame, and how far through it is. The canvas work is lib/render/transitionPaint.ts. |
The browser's tiles are built by lib/media/transitionPreview.ts from the same modifier() and the same shapes, so a new kind needs no preview code and a tile can never promise a move the video does not make. Painters get a fixed, small number of draws, never read pixels back, and exit early while they would be too faint to see: a transition that stutters is worse than none.
Export
Queue it
Every desktop export, including a selection and an assistant's, calls
runExport(services/export.ts). In the app that goes toservices/backgroundExport.ts, which snapshots the project, derived data, options and custom assets and submits a job to the native queue (src-tauri/src/commands/background_export.rs). Later edits do not change a submitted job.Render in a hidden window
The queue runs one job at a time, with up to eight pending. A hidden renderer window (
pages/ExportWorker.tsx, route#/export-worker/) claims the snapshot and callsrenderExport. Closing an editor does not cancel its jobs; jobs do not survive quitting.Draw every frame
renderExportwrites the sound effects to a WAV (renderSfxWav) and prepares the music, opens the sources (services/frames.ts:MediabunnySource, a sequential WebCodecs decode, for every file that allows it;VideoElementSource, a hidden<video>seeked frame by frame, as the fallback) and draws each output frame withrenderFrame.Encode
WebCodecs through mediabunny (
avcfor MP4,vp9for WebM) into a temp file; otherwise raw RGBA frames piped to ffmpeg (export_begin,export_frame,export_finish). GIF always goes through ffmpeg.Finalize in Rust
export::finalize(src-tauri/src/export/mod.rs) makes the GIF palette, or muxes every audio input with one graph frombuild_full_mix_graph(src-tauri/src/ffmpeg/filters.rs): voice and system audio one piece per kept segment, each exactly as long as its picture; clip audio; the effects WAV; music with fades and ducking; all throughamix … normalize=0. The optional enhance pass re-encodes once before muxing.
What keeps the file equal to the preview
- Sound is numbers first. A treatment resolves to numbers, and both engines build from those: the voice changer in
lib/audio/voice.tsfeedslib/audio/voiceGraph.ts(Web Audio) andvoice_chaininsrc-tauri/src/ffmpeg/filters.rs(ffmpeg). Never teach one of them something the other does not know. - Mutes and volumes are converted to output time (
muteRangesOut,gainRangesOutinlib/timeline/clips.ts) and becomevolume=…:enable='between(t,a,b)'filters. - Clamp numbers on the Rust side to what each ffmpeg filter accepts. A filter string ffmpeg rejects fails the whole export.
- A selection export is the ordinary export with
ExportOptions.range: the frame clock starts atrange.startMs, and Rust cuts the finished audio graph once (with_range), so picture and sound share one origin. - Audio on its own (
export_audio_only,src-tauri/src/export/audio.rs) uses the same mix graph without music or effects: a small mono file for transcription.
npx vitest run tests/background-export.test.ts tests/export-activity.test.ts tests/frame-readiness.test.ts
cd src-tauri && cargo test # filters, mix graph, export options
cd src-tauri && cargo test --test export_mux -- --ignored --nocapture # the real ffmpeg graphThe editor shell
The layout is the one every NLE uses: a header across the top (pages/Editor.tsx), the media browser, the player and the inspector under it, and the timeline across the whole bottom, capped at half the window's height so the player keeps its half. The header is a container query, so it gives way by measuring itself, not the window. All three panels resize (ui/PanelResizer.tsx; sizes in settings.libraryWidth, inspectorWidth, timelineHeight); the inspector is capped at 42% of the window, and the browser folds to its rail under 1000 px.
The browser
The rail shows six groups (GROUPS in lib/library/groups.ts); the tabs of the open group sit across the top of the panel as pills that wrap rather than scroll (TabRow.tsx). Each tab is one TabDef in components/editor/library/tabs.tsx, and GROUP_OF files it.
| Group | Tabs (id) |
|---|---|
| Clips | Media (media), Audio (audio), Phone (phone), Shorts (shorts) |
| Text | Titles (titles), Cards (cards), Captions (captions), Web parts (webparts) |
| Graphics | Elements (elements), Progress (progress), Stickers (stickers), Sprites (sprites) |
| Polish | Transitions (transitions), Effects (effects), Filters (filters) |
| Saved | Templates (templates), Looks (looks), Custom library (custom) |
| Plugins | Plugins (plugins); see the plugin docs |
The inspector
- The timeline is where you choose; the inspector is where you change.
ROUTESincomponents/editor/Inspector.tsxmaps eachSelectionKind(store/playback.ts) to a header and only its own tabs. A selected media item opensMediaInspectorinstead. - Nothing selected shows the project page: the recording's layers as cards with an on/off switch, then collapsible groups (Output, Background, Sound, Automatic, Masks & highlights, Motion tracking, Overlays), each with a one-line summary from
lib/project/summaries.tsso it says what it is set to while closed. - Search at the top of the panel (
inspector/InspectorSearch.tsx) ranks hits from the settings index inlib/inspector/settings.ts; choosing one selects the right thing, opens the tab or group, scrolls to it and rings it (lib/inspector/reveal.ts).
Command menu and window shortcuts
- The command menu (
components/editor/CommandMenu.tsx, built oncmdk) is mounted once per window by the shell inApp.tsx. - Ctrl+Shift+P opens it in every main and project window, on every page, even while typing:
hooks/useWindowShortcuts.tslistens onwindowin the capture phase, so a panel that stops its own keys cannot swallow it. In the editor Ctrl+K opens it too (hooks/useEditorShortcuts.ts). - Outside the editor it holds what applies everywhere, Reload window and the theme; in the editor every editor action is listed above them.
- Reload window is
reloadWindow()instore/windowActions.ts, with its rules inlib/window/reload.ts(reloadBlocker,resumeFor,parseResume). It refuses while recording or while the assistant is mid-step in this window, saves the project first and does not reload if that fails. A project window reopens its project from its own address; the main window carries its page and project throughsessionStorage. Exports, the recorder and the assistant link are native and carry on. - While you type, groups are ranked by their best match (
orderGroupsinlib/commands/order.ts), because cmdk 1.1.1's own group sort looks groups up by an id that is never on the page and leaves them in written order. Tests:tests/window-reload.test.ts,tests/command-order.test.ts. - The editor's own keys are in
hooks/useEditorShortcuts.ts, which ignores keys typed into an input, textarea or editable element;ShortcutsDialog.tsxlists them.
Windows
A project is open in one window at a time: two editors on one project.json would each save over the other. Project windows (src-tauri/src/commands/project_windows.rs, store/projectWindows.ts) are the editor and nothing else; recording, the MCP listener and the phone link stay in the main window (MainWindowOnly in App.tsx).
Recipes: adding something
Each recipe is the whole change. Where a table is keyed by a union type (Record<LibraryTab, …>, Record<TransitionKind, …>), the compiler points at every place a new id still needs, so run npx tsc --noEmit early.
A browser tab
Name it
Add the id to
LibraryTabinstore/settings.ts. Tab ids are alsosettings.libraryTabvalues.File it
Add it to
GROUP_OFinlib/library/groups.ts. The table is keyed by tab, so a tab cannot compile without a group.Describe it
One
TabDefincomponents/editor/library/tabs.tsx:id,label, a one-linehint,icon, itspanel(which receivesTabProps), itscategories, and optionallyaction(buttons beside the title),head,searchableanduseCounts. The shell (LibraryPanel,LibraryRail,LibraryToolbar) needs no change.Make it draggable
Everything in it must drag onto the timeline and drop on the player. See the next recipe but one.
{
id: "plugins",
label: "Plugins",
hint: "Media, publishing and custom workflows",
icon: Puzzle,
panel: PluginsTab,
action: PluginsActions,
searchable: true,
categories: [],
},An inspector panel
A kind to select
If it is a new kind of thing, add it to
SelectionKindinstore/playback.ts.One route
One line in
ROUTESincomponents/editor/Inspector.tsx, keyed by that kind: title, hint, icon and tabs. Tab ids come fromPanelTabIdinlib/inspector/panels.ts.The panel
One file in
components/editor/inspector/, about one subject (rule 11).One way in
Selecting the thing on the timeline is the only way in. Do not add a second route to the same panel. Add its settings to the settings index.
background: { title: "Background", hint: "Behind the recording", icon: Palette, tabs: [{ id: "bg", label: "Background", icon: Palette, render: () => <BackgroundPanel /> }] },A project-wide setting
- A
Groupon the inspector's project page (Inspector.tsx) withright={<Value>…</Value>}, so the group says what it is set to while closed. - The summary is a pure function in
lib/project/summaries.ts(tested intests/project-summaries.test.ts). - Its id goes in
PROJECT_GROUP(lib/inspector/panels.ts), never as a loose string. - And one place in the settings index, below.
Any setting at all
Add it to the right place in PLACES in lib/inspector/settings.ts: one string. A setting that is not in the index cannot be found by name, which is the same as not being there. Targets use the typed group and tab ids, so a rename that would break a jump fails to compile. Test: tests/inspector-search.test.ts.
{
where: "Project · Output",
target: { page: "project", group: PROJECT_GROUP.output },
about: "aspect ratio resolution size vertical square landscape portrait youtube tiktok reels shorts export frame",
settings: ["Screen shape", "Framing", "Crop the recording", "Window follows the cursor", "Show the whole screen, no zoom"],
},Something draggable from the browser
A payload
A case in the
DropPayloadunion instore/mediaActions.ts.Where it lands
Handle it in
dropOnTimeline. A drop on the player goes throughdropOnPreview, which picks the top free track at the playhead and calls the same function, so one case serves both.If it is a sound
Return true for it in
isAudioPayload, so it lands on an audio track.On the tile
Make the tile
draggableand set the payload underDROP_MIME(application/x-focal).
// store/mediaActions.ts, in DropPayload
| { type: "filter"; id: string }
// library/FiltersTab.tsx, on the tile
e.dataTransfer.setData(DROP_MIME, JSON.stringify({ type: "filter", id: p.id }));A timeline lane
- A
LaneDefincomponents/editor/timeline/Timeline.tsx, usually ineffectLanes, guarded so it exists only while something is on it (wanted(count, kind): a count above zero, or a thing of its kind selected). - Render its blocks for that id in
renderMainLane;RangeLaneintimeline/lanes.tsxdraws any list of time ranges. - Its blocks select a
SelectionKind, which routes to an inspector panel. - Keep the panel's automatic height honest: it includes
SCROLLBAR_H(rule 2).
A keyboard shortcut
- The key in
hooks/useEditorShortcuts.ts, calling a store action. Match Filmora's or CapCut's key where they have one. Keys that must work in every window, on every page, belong inhooks/useWindowShortcuts.tsinstead. - A row in
ROWSincomponents/editor/ShortcutsDialog.tsx. - A command in
components/editor/CommandMenu.tsxwith the samekeysand the same action:{ id: "zoom", group: "Timeline", label: "Add zoom at playhead", keys: ["Z"], run: addZoomAtPlayhead }.
An audio treatment
- A preset in
VOICESinlib/audio/voice.ts, with its id inVoiceId. It resolves to numbers (VoiceFilter: semitones, cutoffs, shelves, drive, echo, gain, copies). - The player (
lib/audio/voiceGraph.ts) and the exporter (voice_chaininsrc-tauri/src/ffmpeg/filters.rs, with a mirroredVoiceFilterstruct) both build from those numbers. A preset made of existing numbers needs nothing else; a new kind of number must be taught to both, or neither. - Tests:
tests/voice.test.ts, and the Rust filter tests (cargo test).
A transition
- The id in
TransitionKind(src/lib/types.ts) and an entry inTRANSITIONS(lib/media/transitionKinds.ts); setpaint: trueif it plays over the frame. - What it does to a clip in
modifier()(transitionMotion.ts); a reveal shape intransitionShapes.ts; a painted one inPAINTS(lib/media/transitionPaint.ts) andlib/render/transitionPaint.ts. - Its sound:
TRANSITION_RECIPEinlib/sfx/motionRecipes.tsis keyed by every kind. Made-sound ids (gen:tr-<kind>) are written into projects: add them, never rename them. - No preview code. Tests:
tests/transition-kinds.test.ts,tests/transitions.test.ts,tests/transition-paint-canvas.test.ts.
An animation
- Clip-wide: the id in
AnimationInorAnimationOutand a row inANIMATIONS_INorANIMATIONS_OUT(lib/media/animations.ts), its off-screen pose inoffState, and an entry inOVERSHOOTif it settles back. Its sound goes inANIMATION_IN_RECIPEorANIMATION_OUT_RECIPE(lib/sfx/motionRecipes.ts). - Text: the id in
TextAnimId, a preset inTEXT_ANIMATIONSand its per-letter or per-word state intextUnitState(lib/media/textAnimations.ts). - Both are pure functions the previews call, so a chip in the panel is the animation, not a drawing of it.
A language in the Code explainer
- The id in
LanguageId(lib/code/types.ts). - An adapter in
lib/code/run/adapters/: a pureRunPlanof files and steps, with the run folder written as{dir}(RUN_DIR), registered inADAPTERS(adapters/index.ts). - An entry in
LANGUAGES(lib/code/languages.ts), its tool inLANGUAGE_TOOL(lib/code/run/tools.ts; a new program also goes inToolPaths), comment prefixes inCOMMENT_PREFIXES(lib/code/source/blocks.ts) and patterns inRULES(lib/code/explain/rules.ts). - The program's name in
TOOLCHAINSinsrc-tauri/src/code_run/allow.rs, or the runner refuses to start it. That allow-list is what stops a compromised page from namingcmd.exe. Readdocs/code-explainer.mdfirst.
Something on the explain board
- A click effect: its id in
BoardClickEffect(lib/board/types.ts), a length inCLICK_EFFECT_MSand a case inparticlesAt(lib/board/clickEffects.ts), and a row inBOARD_CLICK_EFFECTS(lib/board/options.ts). - A mouse binding: a
MouseAction(lib/board/types.ts), a row inMOUSE_ACTIONSand a line incontrolHints(lib/board/controls.ts), so the shortcut list says what it does. - The board engine stays DOM-free (
docs/board.md).
A web part
Nothing per component: the whole library is src/lib/webparts/catalog.json. The renderer copied from json-websites lives in webparts/src (imports @webparts/, motion as motion-v14) and is not type-checked here. Yaazh's own code is webparts/main.tsx, src-tauri/src/webparts/ and src/lib/webparts/. Read docs/webparts.md before touching src-tauri/src/webparts/clock.js: it is what makes a frame the same picture every time.
A backend command
The command
A
#[tauri::command]function insrc-tauri/src/commands/<area>.rs. Keep it thin: blocking work goes throughtauri::async_runtime::spawn_blocking, and the logic lives in its own module (export/,project/…). A new file needs apub modline incommands/mod.rs.Register it
Add it to
tauri::generate_handler![…]insrc-tauri/src/lib.rs.Type it
A wrapper in
src/services/api.tsthat callscall<T>("your_command", args).Mock it
A case in
mockInvokeinsrc/services/mock.ts; otherwise the browser loop throwsmock: unknown command. Call it from a store or a service, never from a component.
An assistant tool
See Assistant tools: one new file, then three generated outputs.
The 12 UI rules
Each of these has been asked for by name. Break one only with a reason in a comment.
Nothing scrolls sideways to hide a control
A tool you have to scroll to find is a tool you do not have. When a row is too narrow, drop the words first with container queries on the row (
@containerwith@min-[840px]:inline, because panel widths decide the space, not the window), then wrap onto a second line. Never hide a button.No accidental scrollbars
A panel's automatic height includes its own scrollbar (
SCROLLBAR_HinTimeline.tsx).globals.cssstyles scrollbars unlayered, so a utility needs!to beat it:scrollbar-none!.Show, don't name
Effects, grades, masks and transitions are shown doing it, on a frame of the user's own recording (
library/frame.ts,library/FrameLayer.tsx), with the untouched frame a hover away. A thumbnail can arrive as adata:URL, so use<img>layers, never CSSurl(...)in an inline style.State is visible without opening anything
Collapsed groups carry a value chip; layer cards say On or Off and what they are set to; tiles carry length, size and an "in use" flag.
Destructive actions are labelled
"Delete" with the word on it, in the row that owns the thing, not an anonymous bin at the end of a strip. The recording's own layers are switched off, not deleted.
Previews are real
Video tiles scrub under the pointer, sounds have decoded waveforms and a scrubber, transitions loop while hovered.
Reuse the primitives
ui/Controls.tsx(Section,Field,SliderField,Switch,Select,Segmented,ColorSwatches),ui/NumberField,ui/Group,ui/Button,library/MediaTile(Tile,Empty,tileGrid),library/WaveStrip. New styling that duplicates one of these is a bug.Tokens only
bg-surface,bg-surface-2/3/4,border-line,border-line-strong,text-fg,text-fg-2,text-fg-3,accent,accent-soft,danger,warn,success. No raw hex in components: the light theme overrides the tokens.Every panel fits a 280 px column
And reads at 320 px. Truncate with
truncateplusmin-w-0, never with a fixed width.Behaviour follows the editors people know
Filmora, CapCut, Premiere and Resolve: their structure and their keys, never their visual skin.
One home per setting, one subject per panel
If a control belongs in two places, one of them is a link or a scope (
SoundPanel'sscope), not a copy. A panel showing six unrelated subjects is split: that is howEffectsPanelbecameMaskPanelandKeystrokesPanel.The layout is the standard one
Header across the top; browser, player and inspector under it; the timeline across the whole bottom, capped at half the window's height. The header measures itself, not the window.
Assistant tools (MCP)
Yaazh serves MCP so Claude Code, Claude Desktop, Cursor, Antigravity and other MCP clients can edit a project, and its built-in assistant panel uses the same tools. Rust is the transport (src-tauri/src/mcp/: a loopback HTTP server, JSON-RPC, the handshake and a token); the tools run in the webview (src/services/mcp/) against the live project. A tool that cannot do what was asked returns a result saying why (isError) rather than throwing.
Write the module
Create a file in
src/services/mcp/tools/that exports typedMcpTool[]andtoolModule = { tools, group, essential }. Vite's eager glob inregistry.tsdiscovers it; a duplicate tool name, or a…Toolsarray exported withouttoolModule, throws.Describe it
Write the description for a reader who has never seen the code. The tool list carries its first sentence and
helpserves the rest.docis an optional catalogue line;essentialon the module (true, false or a list of names) or on one tool decides the smaller connection;startupis an optional short startup rule, but prefer help text to permanent prompt growth.Generate
npm run mcp:generateupdates the table indocs/mcp.md,docs/mcp-tools.generated.mdandsrc-tauri/src/mcp/tool-discovery.generated.txt. Commit them with the feature.npm run mcp:checkis read-only and fails on drift.Measure and test
npm run mcp:costprints each tool's estimate and both budgets (exit 1 when a guard fails), then run the tests below. Do not add imports or name lists inregistry.ts,rpc.rsorinstructions.md: the table and startup guidance are generated.
import { data, schema, type McpTool } from "../types";
export const myTools: McpTool[] = [{
name: "my_feature", title: "My feature", readOnly: true,
description: "Explain what it does, its limits and the intended workflow here; help retains the full description.",
inputSchema: schema({}), run: () => data({ available: true }),
}];
export const toolModule = {
tools: myTools, group: "My feature", essential: false,
};The token budget
tools/list is read by the model on every turn, so its size is a real cost. tests/mcp-budget.test.ts fails when the whole list reaches 28,500 tokens or 170 per tool, when the essentials reach 16,000 tokens or 70% of the whole, or when a description reaches 700 characters. The estimate is JSON characters divided by four, not billed tokens. tests/mcp-tools.test.ts holds the contract: snake_case names, every argument described, and the readOnly, destructive and openWorld annotations that decide whether a client asks before running a tool.
npm run mcp:generate
npm run mcp:check
npm run mcp:cost
npx vitest run tests/mcp-budget.test.ts tests/mcp-tools.test.ts
npm run mcp -- get_project_overview --project "project-id" # call the running appTest and verify a change
npx tsc --noEmit # must be clean
npx vitest run # must be green; add tests for new lib/ logic
npx vitest run tests/playback-clock.test.ts # one file
pnpm test:rust # cargo test in src-tauri
pnpm dev --port 5177 # layout checks with the mock backend
pnpm tauri build --no-bundle # then launch src-tauri/target/release/focal.exe- Vitest runs in Node (
environment: "node"invitest.config.ts), with no DOM. That is the practical reason logic goes insrc/lib: there it can be tested. - Layout is checked in the browser loop at
localhost:5177: every panel at a 280 px column, nothing scrolling sideways, no stray scrollbars. - Browser and media code runs for real in a hidden browser:
npm run try -- <entry>starts a temporary Vite server and an isolated hidden Edge or Chrome, calls the entry (a default export,run({ videos, args, mount }), or--export name --args), and leavesresult.jsonandscreenshot.pngin.tmp/try/<run>/. Tauri IPC is unavailable there; the browser mock applies. - Rust live tests are ignored by default:
record_smoke,system_audio,export_muxandlink_downloadrun withcargo test --test <name> -- --ignored --nocaptureinsidesrc-tauri/. - Release builds are what gets tested by hand: close a running
focal.exefrom this build, runpnpm tauri build --no-bundleand launchsrc-tauri/target/release/focal.exeon its own. Do not edit source while someone is testing atauri devsession: it reloads under them. - Docs: the matching
docs/page changes in the same change.
npm run try -- scripts/fixtures/try-video.ts "C:/clips/example.mp4"
npm run try -- src/lib/timeline/mapping.ts --export outputDuration --args "[[]]"If npm or npx misbehaves
Every script is a thin wrapper over Node, and an npm or npx shim that breaks (it happens on machines with a hand-assembled Node install) is no reason to skip a check. Run the scripts directly:
node node_modules/typescript/bin/tsc --noEmit
node node_modules/vitest/vitest.mjs run
node scripts/claim.mjs list
node scripts/mcp-generate.mjs # --check for mcp:check
node scripts/mcp-cost.mjs
node scripts/try.mjs scripts/fixtures/try-video.ts "C:/clips/example.mp4"Coordinating with other sessions
Several people and agents work in this repository at once. Before you edit shared files, check and claim them. Claims are advisory and directory-aware (a folder overlaps everything under it), and they expire after two hours.
npm run claim -- check src/lib/playback/clock.ts --owner my-session
npm run claim -- add src/lib/playback/clock.ts tests/playback-clock.test.ts --owner my-session
npm run claim -- list
npm run claim -- release --owner my-session- Use a unique owner per session, or set
FOCAL_CLAIM_OWNER.addis atomic and refuses another owner's active overlap;checkexits with code 2 on a conflict. - The default lifetime is 120 minutes;
--ttl-minaccepts 1 to 1440. Add again to renew. Release your claims when you finish. - A conflict is a reason to coordinate, not to overwrite another session's work. Claims do not lock files.
- The live record is the git-ignored
.agent-claims.json. After a crash, check that the process ID in.agent-claims.lockis gone before removing a stale lock. - Use
npm run claim -- listrather than reading the archived diary indocs/coordination/.
Facts worth knowing
- The playback clock is the recording. Everything else follows it. Never seek an element every frame; copy
needsHoldSeek. - Web Audio taps are one-way. One
createMediaElementSourceper element, ever; a tapped cross-origin element is silent withoutcrossOrigin. - A portal is not where it looks. React bubbles events through the React tree, so a menu, popover or dialog rendered in a portal still fires the handlers of the component it was written inside. On the timeline a right-click menu's press reached the lanes' marquee handler, which took the pointer capture, and the menu item never saw its own pointerup. Anything that handles pointers over a container checks
ref.current?.contains(e.target)first (Timeline.tsxdoes); menus stop their own pointer and click events too. - The canvas draws synchronously. A font must be loaded before the frame that uses it, or the frame falls back silently (
services/fontLoad.ts,lib/render/webFonts.ts).document.fonts.checkanswers true for a family with no faces at all; measure text against a fallback to know. - project.json is written whole. Per-project facts that live outside the model (
category.txt,tags.txt) have files of their own, or the editor's next save drops them. - Ids written into projects are forever. Generated sound ids (
gen:tr-<kind>,gen:an-<in|out>-<preset>), transition kinds and preset ids are stored the moment someone picks one: add, never rename. - One project, one window. Every window reports which project it has (
window_project); asking for one that is open elsewhere brings that window forward instead. - Secrets. Nothing in the repository hardcodes a key or sends the user's details anywhere. Keys are the user's own, kept in their settings (the Freesound key is
settings.freesoundKey). - Old names on purpose.
focal.exe,com.focal.recorder,%LOCALAPPDATA%\Focaland thefocal.*identifiers stay as they are; Yaazh reads existing data from there. - Line endings are mixed. Working copies hold both CRLF and LF files. A scripted edit must keep each file's endings; exact old-to-new replacements in a script are safer than shell heredocs, which mangle backslashes.
- Build from PowerShell on Windows. Git Bash's
linkshadows MSVC'slink.exe.

