Developers

Work on Yaazh's editor

For a developer joining the project to change the editor. How to run it with or without the native app, where each kind of code lives, how one clock and one renderer carry an edit from the preview to the exported file, and the exact steps for each common addition.

1
renderer for the preview and the export
12
UI rules, each asked for by name
~300
lines before a file is split
The Plugins panel or an AI assistant asks Yaazh to run an action. Yaazh sends the action as JSON to your HTTPS service and gets JSON back.AI assistantplugin_toolPlugins panelyou, by handYaazhYour serviceHTTPS · any languagePOST { action, input }200 { result }Never sentfiles, accounts

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/**.

The layers
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 needWhy
Node.js 22.18 or newerThe developer scripts use Node's TypeScript stripping. The workspace is verified on Node 24.
pnpmThe repository has a pnpm-lock.yaml. Scripts also run with npm run.
Rust stable, 1.80 or newerThe 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 ChromeThe 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.
  1. Install

    In the app's folder (still named focal/), run pnpm install.

  2. Run the editor in a browser

    pnpm dev --port 5177, then open http://localhost:5177. With no Tauri present, services/bridge.ts sends every command to services/mock.ts, which signs in a mock account and serves a demo project from dev-assets/demo.mp4 (git-ignored; make one with node scripts/make-demo-clip.mjs). Recording, export, presets and file dialogs are simulated. This is the fastest loop for layout work.

  3. Run the real app

    pnpm tauri dev builds 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.

  4. Build it

    pnpm tauri build --no-bundle takes about three minutes and writes src-tauri/target/release/focal.exe. pnpm tauri build makes the installers. npm run build builds the frontend only: it regenerates src/services/mcp/editorSchema.json, runs tsc and runs vite build.

Terminal (in focal/)
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              # installers

Where code goes

WhatWhere
Pure logic: no React, no storessrc/lib/**. This is what tests target.
Talking to Rust, the OS or filessrc/services/**
App state and every editing actionsrc/store/** (zustand). Actions live here, not in components.
UIsrc/components/**, pages in src/pages/**
Hooks that wire the UI to the storessrc/hooks/**: usePlaybackEngine, useEditorShortcuts, useWindowShortcuts
Rust commandssrc-tauri/src/**: thin wrappers in commands/, the work in its own module
Teststests/** (Vitest), Rust tests beside the code and in src-tauri/tests/
Docsdocs/*.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

FileWhat it is
src/pages/Editor.tsxThe 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.tsxThe player. Mounts usePlaybackEngine, draws with renderFrame, owns the transform handles and drops onto the video.
components/editor/Inspector.tsxThe 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.tsxThe 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

StoreHolds
store/project.ts · useProjectStoreproject, events, derived, dirty, past/future; load, update, pushHistory, undo, redo, save.
store/playback.ts · usePlaybackStoreThe playhead in output time (tOut), playing, and the selection: a SelectionKind plus an id.
store/ui.ts · useUiStoreThe view (Home, Record, Editor, Board, Code), open dialogs, the command menu and the timeline scope ("main", "group", compound:<id>).
store/settings.ts · useSettingsStoreApp 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.tsThe 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

src/store/project.ts
/** 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 new timeline rebuilds the play segments; a new camera or zooms re-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), then derive rebuilds 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.tsx calls save(), which invokes save_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), and store/history.ts files them as versions for the History panel.
The drag pattern
// 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.

FileWritten byWhat it holds
project.jsonThe editorThe 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.jsonRustCursor 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.jpgRustThe screen, the system sound and the home-screen thumbnail.
camera.webm / camera.mp4The webviewCamera and microphone, from MediaRecorder.
category.txt, tags.txtRustFiling 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.

src/lib/playback/clock.ts (abridged)
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 };
DecisionWhen
advanceThe ordinary frame: the clock is wherever the element is, mapped through the kept segments.
jumpThe end of a segment: carry on into the next, seeking only across a real cut, never at a speed boundary.
waitThe 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.
wallThe 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.
gapInserted empty time: the recording is parked on the frame it resumes from while the clock runs off the wall.
stopNothing 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 in CLAUDE.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:

src/lib/playback/clock.ts
/** 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.

src/lib/render/compositor.ts
export function renderFrame(ctx: CanvasRenderingContext2D, outW: number, outH: number, scene: Scene, src: FrameSources, tSrc: number, tOut?: number): FrameResult

Scene 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.

StepWhat is drawn
1The background (render/background.ts).
2–5The 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.
6Keystroke 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.
7Captions, in the output frame, over everything.
8The progress indicator, last: the only thing that reads the output clock.

Filters, blend modes and masks

  • Colour filters. FilterSettings becomes a canvas filter string through filterString() plus drawVignette() (lib/render/filters.ts). The recording's grade is project.filters; every item can carry its own filters.
  • Blend modes. Any canvas composite operation. inspector/BlendPicker.tsx previews each with CSS mix-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 canvas filter, 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

FileSays
lib/media/transitionKinds.tsWhat 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.tsWhat it does to each clip: modifier(kind, progress, side).
lib/media/transitionShapes.tsThe 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.tsWhat 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

  1. Queue it

    Every desktop export, including a selection and an assistant's, calls runExport (services/export.ts). In the app that goes to services/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.

  2. 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 calls renderExport. Closing an editor does not cancel its jobs; jobs do not survive quitting.

  3. Draw every frame

    renderExport writes 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 with renderFrame.

  4. Encode

    WebCodecs through mediabunny (avc for MP4, vp9 for WebM) into a temp file; otherwise raw RGBA frames piped to ffmpeg (export_begin, export_frame, export_finish). GIF always goes through ffmpeg.

  5. Finalize in Rust

    export::finalize (src-tauri/src/export/mod.rs) makes the GIF palette, or muxes every audio input with one graph from build_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 through amix … 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.ts feeds lib/audio/voiceGraph.ts (Web Audio) and voice_chain in src-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, gainRangesOut in lib/timeline/clips.ts) and become volume=…: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 at range.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.
Checking an export change
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 graph

The 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.

GroupTabs (id)
ClipsMedia (media), Audio (audio), Phone (phone), Shorts (shorts)
TextTitles (titles), Cards (cards), Captions (captions), Web parts (webparts)
GraphicsElements (elements), Progress (progress), Stickers (stickers), Sprites (sprites)
PolishTransitions (transitions), Effects (effects), Filters (filters)
SavedTemplates (templates), Looks (looks), Custom library (custom)
PluginsPlugins (plugins); see the plugin docs

The inspector

  • The timeline is where you choose; the inspector is where you change. ROUTES in components/editor/Inspector.tsx maps each SelectionKind (store/playback.ts) to a header and only its own tabs. A selected media item opens MediaInspector instead.
  • 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.ts so 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 in lib/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 on cmdk) is mounted once per window by the shell in App.tsx.
  • Ctrl+Shift+P opens it in every main and project window, on every page, even while typing: hooks/useWindowShortcuts.ts listens on window in 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() in store/windowActions.ts, with its rules in lib/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 through sessionStorage. Exports, the recorder and the assistant link are native and carry on.
  • While you type, groups are ranked by their best match (orderGroups in lib/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.tsx lists 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

  1. Name it

    Add the id to LibraryTab in store/settings.ts. Tab ids are also settings.libraryTab values.

  2. File it

    Add it to GROUP_OF in lib/library/groups.ts. The table is keyed by tab, so a tab cannot compile without a group.

  3. Describe it

    One TabDef in components/editor/library/tabs.tsx: id, label, a one-line hint, icon, its panel (which receives TabProps), its categories, and optionally action (buttons beside the title), head, searchable and useCounts. The shell (LibraryPanel, LibraryRail, LibraryToolbar) needs no change.

  4. Make it draggable

    Everything in it must drag onto the timeline and drop on the player. See the next recipe but one.

components/editor/library/tabs.tsx
{
  id: "plugins",
  label: "Plugins",
  hint: "Media, publishing and custom workflows",
  icon: Puzzle,
  panel: PluginsTab,
  action: PluginsActions,
  searchable: true,
  categories: [],
},

An inspector panel

  1. A kind to select

    If it is a new kind of thing, add it to SelectionKind in store/playback.ts.

  2. One route

    One line in ROUTES in components/editor/Inspector.tsx, keyed by that kind: title, hint, icon and tabs. Tab ids come from PanelTabId in lib/inspector/panels.ts.

  3. The panel

    One file in components/editor/inspector/, about one subject (rule 11).

  4. 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.

components/editor/Inspector.tsx: one line in ROUTES
background: { title: "Background", hint: "Behind the recording", icon: Palette, tabs: [{ id: "bg", label: "Background", icon: Palette, render: () => <BackgroundPanel /> }] },

A project-wide setting

  • A Group on the inspector's project page (Inspector.tsx) with right={<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 in tests/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.

lib/inspector/settings.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

  1. A payload

    A case in the DropPayload union in store/mediaActions.ts.

  2. Where it lands

    Handle it in dropOnTimeline. A drop on the player goes through dropOnPreview, which picks the top free track at the playhead and calls the same function, so one case serves both.

  3. If it is a sound

    Return true for it in isAudioPayload, so it lands on an audio track.

  4. On the tile

    Make the tile draggable and set the payload under DROP_MIME (application/x-focal).

A payload and its tile
// 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 LaneDef in components/editor/timeline/Timeline.tsx, usually in effectLanes, 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; RangeLane in timeline/lanes.tsx draws 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 in hooks/useWindowShortcuts.ts instead.
  • A row in ROWS in components/editor/ShortcutsDialog.tsx.
  • A command in components/editor/CommandMenu.tsx with the same keys and the same action: { id: "zoom", group: "Timeline", label: "Add zoom at playhead", keys: ["Z"], run: addZoomAtPlayhead }.

An audio treatment

  • A preset in VOICES in lib/audio/voice.ts, with its id in VoiceId. It resolves to numbers (VoiceFilter: semitones, cutoffs, shelves, drive, echo, gain, copies).
  • The player (lib/audio/voiceGraph.ts) and the exporter (voice_chain in src-tauri/src/ffmpeg/filters.rs, with a mirrored VoiceFilter struct) 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 in TRANSITIONS (lib/media/transitionKinds.ts); set paint: true if it plays over the frame.
  • What it does to a clip in modifier() (transitionMotion.ts); a reveal shape in transitionShapes.ts; a painted one in PAINTS (lib/media/transitionPaint.ts) and lib/render/transitionPaint.ts.
  • Its sound: TRANSITION_RECIPE in lib/sfx/motionRecipes.ts is 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 AnimationIn or AnimationOut and a row in ANIMATIONS_IN or ANIMATIONS_OUT (lib/media/animations.ts), its off-screen pose in offState, and an entry in OVERSHOOT if it settles back. Its sound goes in ANIMATION_IN_RECIPE or ANIMATION_OUT_RECIPE (lib/sfx/motionRecipes.ts).
  • Text: the id in TextAnimId, a preset in TEXT_ANIMATIONS and its per-letter or per-word state in textUnitState (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 pure RunPlan of files and steps, with the run folder written as {dir} (RUN_DIR), registered in ADAPTERS (adapters/index.ts).
  • An entry in LANGUAGES (lib/code/languages.ts), its tool in LANGUAGE_TOOL (lib/code/run/tools.ts; a new program also goes in ToolPaths), comment prefixes in COMMENT_PREFIXES (lib/code/source/blocks.ts) and patterns in RULES (lib/code/explain/rules.ts).
  • The program's name in TOOLCHAINS in src-tauri/src/code_run/allow.rs, or the runner refuses to start it. That allow-list is what stops a compromised page from naming cmd.exe. Read docs/code-explainer.md first.

Something on the explain board

  • A click effect: its id in BoardClickEffect (lib/board/types.ts), a length in CLICK_EFFECT_MS and a case in particlesAt (lib/board/clickEffects.ts), and a row in BOARD_CLICK_EFFECTS (lib/board/options.ts).
  • A mouse binding: a MouseAction (lib/board/types.ts), a row in MOUSE_ACTIONS and a line in controlHints (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

  1. The command

    A #[tauri::command] function in src-tauri/src/commands/<area>.rs. Keep it thin: blocking work goes through tauri::async_runtime::spawn_blocking, and the logic lives in its own module (export/, project/…). A new file needs a pub mod line in commands/mod.rs.

  2. Register it

    Add it to tauri::generate_handler![…] in src-tauri/src/lib.rs.

  3. Type it

    A wrapper in src/services/api.ts that calls call<T>("your_command", args).

  4. Mock it

    A case in mockInvoke in src/services/mock.ts; otherwise the browser loop throws mock: 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.

  1. 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 (@container with @min-[840px]:inline, because panel widths decide the space, not the window), then wrap onto a second line. Never hide a button.

  2. No accidental scrollbars

    A panel's automatic height includes its own scrollbar (SCROLLBAR_H in Timeline.tsx). globals.css styles scrollbars unlayered, so a utility needs ! to beat it: scrollbar-none!.

  3. 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 a data: URL, so use <img> layers, never CSS url(...) in an inline style.

  4. 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.

  5. 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.

  6. Previews are real

    Video tiles scrub under the pointer, sounds have decoded waveforms and a scrubber, transitions loop while hovered.

  7. 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.

  8. 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.

  9. Every panel fits a 280 px column

    And reads at 320 px. Truncate with truncate plus min-w-0, never with a fixed width.

  10. Behaviour follows the editors people know

    Filmora, CapCut, Premiere and Resolve: their structure and their keys, never their visual skin.

  11. 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's scope), not a copy. A panel showing six unrelated subjects is split: that is how EffectsPanel became MaskPanel and KeystrokesPanel.

  12. 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.

  1. Write the module

    Create a file in src/services/mcp/tools/ that exports typed McpTool[] and toolModule = { tools, group, essential }. Vite's eager glob in registry.ts discovers it; a duplicate tool name, or a …Tools array exported without toolModule, throws.

  2. Describe it

    Write the description for a reader who has never seen the code. The tool list carries its first sentence and help serves the rest. doc is an optional catalogue line; essential on the module (true, false or a list of names) or on one tool decides the smaller connection; startup is an optional short startup rule, but prefer help text to permanent prompt growth.

  3. Generate

    npm run mcp:generate updates the table in docs/mcp.md, docs/mcp-tools.generated.md and src-tauri/src/mcp/tool-discovery.generated.txt. Commit them with the feature. npm run mcp:check is read-only and fails on drift.

  4. Measure and test

    npm run mcp:cost prints 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 in registry.ts, rpc.rs or instructions.md: the table and startup guidance are generated.

src/services/mcp/tools/<yourArea>.ts
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.

Terminal
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 app

Test and verify a change

Before you call it done
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" in vitest.config.ts), with no DOM. That is the practical reason logic goes in src/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 leaves result.json and screenshot.png in .tmp/try/<run>/. Tauri IPC is unavailable there; the browser mock applies.
  • Rust live tests are ignored by default: record_smoke, system_audio, export_mux and link_download run with cargo test --test <name> -- --ignored --nocapture inside src-tauri/.
  • Release builds are what gets tested by hand: close a running focal.exe from this build, run pnpm tauri build --no-bundle and launch src-tauri/target/release/focal.exe on its own. Do not edit source while someone is testing a tauri dev session: it reloads under them.
  • Docs: the matching docs/ page changes in the same change.
Hidden-browser checks
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:

The same checks without the npm shim
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.

Terminal
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. add is atomic and refuses another owner's active overlap; check exits with code 2 on a conflict.
  • The default lifetime is 120 minutes; --ttl-min accepts 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.lock is gone before removing a stale lock.
  • Use npm run claim -- list rather than reading the archived diary in docs/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 createMediaElementSource per element, ever; a tapped cross-origin element is silent without crossOrigin.
  • 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.tsx does); 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.check answers 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%\Focal and the focal.* 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 link shadows MSVC's link.exe.