Renderer
React 19 + Vite, inside the sandboxed renderer. It only talks to the Main through window.api (see ipc.md).
src/renderer/src/ app/ App (providers + IPC event bridge), router, page registry (PAGES, NAV) components/ layout/ AppShell (sidebar + outlet + status bar), Sidebar, StatusBar ui/ shadcn/ui-style primitives (Button, Card, Badge, …) data/ TanStack Query hooks per domain + query-keys guides/ in-app user guides: <lang>/<id>.md, getGuide/useGuide i18n/ i18next instance, locales/en/*, typed keys lib/ ipc (unwrap/IpcCallError), query-client, cn() pages/ screens (placeholders until built) test/ fake window.api for component testsRouting
TanStack Router, routes defined in code (app/router.tsx), hash history because the packaged renderer loads from file://. Tests use a memory history. / redirects to /translate. The router context carries the QueryClient for future loaders.
Data layer
- One hook module per IPC domain (
data/jobs.ts,data/sidecars.ts,data/settings.ts,data/app.ts). Every key comes fromdata/query-keys.ts(qk), hierarchical soqk.jobs.allinvalidates the list and every detail. unwrap()turns the{ ok, error }envelope into a thrownIpcCallError { code }, so TanStack Query sees failures as errors.- No polling and no global store. IPC events patch the cache directly:
jobs:progress→applyJobProgressupdates the list and the detail withsetQueryData; a job that is not cached (e.g. created by a batch) invalidates the list; terminal states invalidateqk.jobs.allbecause the event carries noresult/error. The subscription lives once inApp(EventBridge). - Navigation and filter state belong in the URL (search params), not in a store.
i18n
i18next with English as the default and source language. Namespaces: common (UI text) and errors. Keys are typed (i18n/i18next.d.ts), so a typo is a compile error.
- The Main never sends user-facing text.
errorMessage(err)(i18n/error-message.ts) mapsIpcCallError.codetoerrors:<code>; unknown codes and non-IPC errors fall back toerrors:unknownwith the code. The rawmessageis never shown (it may carry paths or HTTP details). src/shared/error-codes.tsis the single list of codes (APP_ERROR_CODESfromAppError, plusFORBIDDEN/INTERNALfromcreateHandler).locales/en/errors.tssatisfies Record<ErrorCode, string>: a new backend code without a message fails to compile, and a test checks every code at runtime.- Adding a language: a new
locales/<lang>/folder with the same shape asen.
Foundation
- UI primitives (
components/ui/, shadcn style on our tokens, Radix underneath):Button,Badge,Card,Input/Textarea,Field/Label(wiresaria-describedby/aria-invalid),Select,Checkbox,Switch,Dialog,Popover,Tooltip(needs the rootTooltipProvider),Command(cmdk, for searchable pickers),Tabs,Progress(0..1, indeterminate without a value),Toaster(sonner; calltoastfromsonner). - Common components (
components/common/):ErrorBoundary(one around the router, one per page keyed by the path; logs throughreportError(err, 'boundary')),GuideView(bundled guide in the app language; guide links callonNavigate, other links go throughapp:open-external; no raw HTML),WaitLabel(progress.waitingwith a live countdown,lib/use-countdown.ts). - Data hooks (
data/):useSettings/useUpdateSettings/useResetSettings(the Main returns the full snapshot, which replaces the cache),useApiKeyStatus/useSetApiKeyanduseTmdbKeyStatus/useSetTmdbKey(nullclears; a new OpenRouter key invalidates the catalog and the free quota),useModels,useFreeQuota,isFreeModel(same rule as the Main),usePresets,useJobs. - Language: setting
ui.language(en,pt-BR,null= system).useLanguageSync(in the rootEventBridge) switches i18next and<html lang>;resolveAppLanguagemaps the request to a supported language (exact, base language, English). UI strings without a translation fall back to English (bothenandpt-BRare complete).
Onboarding
Route /welcome, outside the shell (no sidebar). The shell layout route (id: 'shell') has a beforeLoad guard: while the API key, the default model or the default target language is missing (isOnboarded), every page redirects there. The guard uses ensureQueryData with the same query options as the hooks (settingsQuery, apiKeyStatusQuery); an IPC failure lets the user in rather than locking the app.
Steps, saved as they go (no “submit at the end”): OpenRouter key (KeyForm, checked by the Main in GET /key before saving: LLM_AUTH / NETWORK), models (ModelPicker), languages (LanguagePicker), video tools (sidecar install, optional), TMDB key (optional). The page opens at the first required step that is not done; later required steps unlock in order. “Start translating” goes to /translate.
Reusable pieces built here: KeyForm (write-only secret: saved / replace / remove, no-keyring warning, guide link), GuideDialog (guide in a dialog with back navigation between guides), ModelPicker (catalog search, favorites first, price per 1M tokens, free / reliable JSON / moderated badges, default), LanguagePicker (curated BCP-47 list in lib/languages.ts, names from Intl.DisplayNames in the UI language), useListWithDefault (favorites + default as one optimistic value; the same rule as PreferencesService, in lib/favorites.ts, so a patch never conflicts).
Tests: test/setup-dom.ts adds the jsdom gaps cmdk/Radix need (ResizeObserver, scrollIntoView, pointer capture); test/fixtures.ts has the settings of an onboarded user.
Translate a file
pages/translate/. The flow is a pure reducer (wizard-state.ts: steps, validation, automatic track choice, buildJobRequest), tested without React; the page only renders the current step.
- File: drop zone (
window.api.files.pathFor) or the native dialog; the type comes from the extension (sourceKindOf,src/shared/file-types.ts, shared with the Main’s path guard). A subtitle file goes throughtranslateand has no track step and no mux options; a video goes throughpipeline. - Track (video):
media:probe; image-based and unsupported tracks are listed but disabled with the reason; a track is preselected (pickTrack: first preferred source language, full over forced). Attached fonts are mentioned. - Preset & context: preset with its details (media type, temperature, style, glossary size), suggested from the TMDB work like a batch work (
suggestPreset: a user preset whose normalized name — no case/accents/punctuation/year/season — is contained in, or contains, the work’stitleororiginalTitlewins, longest name first then most recent, names under 3 characters and built-ins never match; otherwise the built-in for the work’s type,source: 'name' | 'flavor'; hintsuggestion-hint.tsx, shared with the batch):presetId: nullfollows the suggestion (and a new match), picking it again returns to following it, no work = the Settings default;buildJobRequestsends the effective one. The suggestion follows the work even when its details are not sent to the AI; model from the favorites only, target language fromtranslation.targetLangs, both prefilled with the defaults (left unset in the request so the Main applies them), notes (≤ 4,000). - Output: folder (default next to the source) and, for videos, what to write: MKV with the subtitle (
mux), subtitle only (subtitle, for players that load external subtitles by file name) orboth.setDefault/keepOriginalSubtitlesonly exist when an MKV is written. A preview shows the file name(s) and folder, and “Replace files that already exist” (overwrite) swaps the default(2)suffix. The sharedOutputStepserves the single and batch wizards; the last mode is remembered in Settings (output.mode, defaultmux) and followed until the user picks one (outputMode: null). - Extract (single and batch) has the same name preview,
naming(player=<base>.<lang>.<ext>,track= with the track id; remembered inoutput.extractNaming) andoverwrite, with a warning when several tracks of one language need a.nsuffix. - Job: created with
confirmBeforeTranslate: true.JobDetailfollows it throughuseJob(patched byjobs:progress):awaiting-confirmationshowsPreflightReview(lines, requests, tokens, cost range or “free”/dynamic price, approximate tokenizer, model and catalog date, free-quota warning,CoverageSummarybar of translatable / skipped / untranslated lines,CoverageList, and for a subtitle file theFileCheckbelow), thenJobProgress(step, lines, parts done and in flight, cached, cost,WaitLabel; during translation the bar isTranslationTimeline: the episode in timestamp order with cache, translated, in-flight and failed ranges and a mark at each lane cut), thenJobResult(outputs, cost, untranslated lines, warnings, or the localized error). These live incomponents/jobs/and are shared with the queue throughJobDetail. - File check (
components/jobs/file-check.tsx): for a subtitle file the wizard passesinspectPathtoJobDetail, and the preflight review callsfiles:inspect(useInspectSubtitle, cached forever per path, never blocks confirming; a failure is a muted line).EncodingIndicatorshows the detected encoding, confidence badge (certain/high/medium/low), BOM and line endings;mediumgets a warning andlowa destructive alert. There is no encoding picker:jobs:createhas no encoding override, so the alert tells the user to re-save the file as UTF-8.DiagnosticsListis collapsed by default (severity, line, column, localized message perfileCheck.code.<CODE>, unknown codes fall back to a generic text,fix: automarked “fixed on export”). Videos have no check: the track is extracted inside the job andjobs:preflightcarries only coverage. The queue’s detail panel has no source path either, so it shows coverage only.
The wizard state (and the job it started) survives page switches: Translate (mode choice, single wizard, batch wizard), Extract and Mux keep their state in lib/page-state.ts (usePageState / usePageReducer: a keyed in-memory store over useSyncExternalStore, one key per screen, never shared between screens). A renderer reload starts clean; the jobs themselves live in the Main and show in the queue. Tests reset it after each test (test/setup-dom.ts).
Translate several files (batch)
Translate opens on a choice (translate-entry.tsx): One file (the wizard above, whose first step’s “Back” returns to the choice) or Several files or a folder (pages/translate/batch/). There is no separate Batch page in the sidebar. The batch wizard keeps the single-file look: the same StepBar (generic over the step type), card, footer and summary aside.
Steps: Files → Tracks (videos only) → Works → Preset & context → Output, then Review cost → Translation (BatchRun).
- Files (
files-step.tsx): a folder (native dialog, “Include subfolders”, re-scanned when toggled) or several files (dialog or drag & drop).useBatchPlans(data/batches.ts) asksbatches:planfor both kinds,pipeline(videos) andtranslate(subtitle files): loose files are split by extension, a folder is scanned twice. When both have files, the user picks which to translate.truncatedandrejectedare shown. Every file then goes throughmedia:identify(useIdentifyAll, same cache as the single-file panel); rows exist only once all are settled, since the grouping depends on them. A status line counts ready / need you / left out / works. - Rows (
batch-rows.ts):seedRows(plan + identification; skipped files start out and cannot be included back; outputs of an earlier translation (previousOutputs: a target-language suffix likeX.pt-BR.mkvwith its sourceX.mkv, orX.en.srtfor subtitles, in the same set) start out but can be included back, labelled in “Left out”; absolute anime numberingShow - 28is read as season 1) plus usereditsper path (include,trackId,season,episode), so a late identification never overwrites a change. Tracks are compared by signature (language + name + format), since ids differ between releases.rowProblem:no-subtitle-track/no-supported-track/probe-failed(skipped),no-track(blocking),odd-track(not the work’s majority track),no-episode(series without numbers). - Tracks (
tracks-step.tsx): “Need you” first (the fix inline, or “Leave out”), then one card per work with the work’s track (applied by signature to every file that has it) and the per-file override; left-out files at the end. - Works (
works.ts,works-step.tsx): the unit of context.autoGroupgroups by TMDB match (tmdb:<id>), else by the parsed title (name:<title>); skipped files belong to no work. The grouping stays automatic (grouping: null) until the user edits it: rename, re-match on TMDB (TitleSearch, synopsis below), “Merge with…”, “Move to…” per file (or “New work”,manual:<n>), “Group automatically again”. Episode numbers are edited here. - Preset & context (
settings-step.tsx): there is no batch-wide preset. The batch defaults are model, language and notes (PresetStepwithwithPreset={false}); every work card has its ownPresetPicker, prefilled with a suggestion from its TMDB details (lib/preset-suggestion.ts: Animation genre id 16 + original languagejaor countryJP→builtin:anime; genre 99 →builtin:documentary; elsebuiltin:movie/builtin:seriesby kind; details cached before the ids existed fall back to the English genre name and kana in the original title).Work.presetIdis the user’s pick (null= follow the suggestion, which then tracks a new TMDB match; no match = the Settings default, resolved by the Main);workPresetgives the effective one andbuildBatchRequestsends it in every group. Why: the Job Memory key includes the preset’s style, so one preset for a mixed folder (movie + anime) both translates worse and misses the cache of files translated earlier with the right preset. Then “Use the batch defaults” or “Customize this work” (model, language, notes) and “Send the title, genres and synopsis” for works with a TMDB match. Never per file. - Output (
batch-output-step.tsx): the sharedOutputStep(folder, mux options for videos; with a folder and an output dir the structure is mirrored), “Show the total cost and wait for my confirmation”, and a review per work. - Request (
buildBatchRequestinbatch-state.ts): included files in plan order, each withgroup(index intogroups),trackIdsand, for a series whose media goes to the AI,season/episode. Each work becomes aBatchGroup(name,mediawhen included, and all its settings when customized); unset defaults are left to the Main. - Backdrop (
batch-backdrop.tsx): from Works on, the artwork of one work (with media included), drawn again on every step change (drawin the state, generated in the click handler). A mosaic was tried and rejected: under the gradient and the 92% panels it reads as texture. - After creating (
batch-detail.tsx):BatchRunkeeps the step bar with two more steps, Review cost and Translation, driven bybatchPhase(batch-progress.ts:reviewwhile a file is queued/probing/extracting/estimating or awaits confirmation and nothing translates yet, or whenever one awaits;run;done). The card shows the phase, an overall bar weighted per step (jobFraction: translation ≈ 68%, extraction 15%, by kind; awaiting = up to the preflight) with %, per-state counts, the cost review (each awaiting file’sresult.preflight: lines to translate, cache, parts, cost; the batch total frombatches:get; free-quota warning; “N still being prepared” while estimates arrive one by one) with “Confirm all” (batches:confirm), “Cancel all”, and each file live (step, %, lines, cost so far, untranslated count; links to?job=in the queue). Every grid/flex row ismin-w-0so long release names truncate instead of widening the card.useBatchrefetchesbatches:getwhenever a job of the batch changes status.
Batches of extract and mux have their own wizards inside Extract and Mux (see Extract and Mux in batch). Known limitations: no batch view after leaving the page (the jobs show one by one in the queue, with the “Batch” badge; batches:list is unused), and no way to remove a whole batch.
Media context panel
components/media/, shown above the preset step of the wizard. MediaChoice (media-choice.ts) lives in the wizard state: ref, auto (recognized from the file name), season/episode, include, seeded.
media:identify(file name only) seeds the choice once per file; a user change is never overwritten. States: identifying,matched(“Recognized from the file name”),not-found(search above),offlineor an IPC error (continue without context),no-key(one line, the TMDB guide andKeyFormon demand; saving the key invalidates the media queries).- Title field (
TitleSearch): TMDB search debounced 350 ms in a popover (cmdk without client filtering), poster thumbnails, Enter picks the first result. - Details from
media:lookup(a cache hit in the Main): poster, year, kind, runtime, genres, synopsis. A movie picked for a file withSxxEyyshows a warning. - Series: editable season/episode (
EpisodeFields) pre-filled from the file name; “From the file name” uses the same violet as “Recognized from the file name”; a changed number says what the file name had; absolute anime numbering asks for season/episode; the episode title and synopsis load for the numbers. - “Include these details” (dims the details when off). The request carries
mediaonly when included, with the episode only for a series with both numbers (buildJobRequest). - “Metadata and images from TMDB” in the panel (TMDB terms).
Artwork backdrop (Backdrop): the chosen title’s backdropUrl behind the wizard, and the job’s frozen media behind the queue inspector. Job.media (JobMediaSummary: title, kind, year, poster, backdrop, episode, no synopsis) is derived by the Main from the persisted spec (src/main/jobs/media-summary.ts), so the queue never calls TMDB. The image fades in at 55% under a gradient; panels on top stay bg-card/92.
Wizard navigation and summary
- The step bar (
step-bar.tsx) is centered, with arrows between steps; done steps show a check.furthestin the wizard state records the furthest step reached: any reached step can be opened from the bar (forward too) without “Continue”, as long as every step before it is still valid (canGo). Changing the file resetsfurthestand shows “The file changed, so the next steps need another look.” WizardSummary(right column, sticky) lists file, track, preset, model, target language, media and output; each row opens its step when reachable.existingTarget(lib/existing-subtitle.ts) detects a subtitle already in the target language (a video track, compared by base language with ISO 639-2 codes mapped, or a subtitle file named for it). The summary warns, and “Estimate cost” asks “Translate anyway?” before creating the job.- A job whose lines are all cached still stops for review (see
preflight.md).
Queue and status bar
pages/queue/. Workspace layout: the job list on the left (tabs All / Active / Needs you / Done with counts, matchesFilter in data/jobs.ts; “Needs you” = awaiting confirmation, failed, interrupted), the selected job on the right. The selection is the ?job= search param, so the wizard’s “Open in Queue” lands on the job and the browser history keeps it.
The inspector is JobDetail (components/jobs/), the same component the wizard shows after creating a job: header (kind, batch, status, attempt, dates), preflight review / live progress / result, and the actions that apply to the state (cancel with the billing hint, confirm, retry for failed/cancelled/interrupted, remove for terminal jobs). JobError turns error codes into actions: LLM_DAILY_LIMIT shows the local time of 00:00 UTC, LLM_CREDITS opens OpenRouter’s credits page, SIDECAR_MISSING installs the missing tools; interrupted explains that a retry resumes from the step that stopped. Only codes are used, never the Main’s message.
Status bar: running/queued/awaiting counts and average progress, the lane cooldown countdown (latest waiting.reason === 'cooldown' among jobs, cooldownUntil), the cost of this session (sessionCost: jobs created since the renderer started; final cost when finished, cost so far when running), tools and API key.
Settings
pages/settings/, one tab per section, every field saving on its own (useSetting(key) → [value, set], errors from the Main as a toast). NumberSetting saves on blur/Enter only when the value is in range (otherwise it keeps the text and shows the range); nullable fields save null when cleared (“Always ask”, “No limit”).
- General: app language (system / each language in its own name), default preset, jobs at the same time, auto-confirm threshold, preferred source languages (ordered chips: move up, remove, add), detailed logs, system notifications (general switch + jobs / batches / updates, disabled while the general one is off).
- Keys:
KeyFormfor OpenRouter (cannot be removed: the app needs it) and TMDB (removable), each with its guide. - Translation cache: size on disk, line count, least recently used date; prune by age or clear all, disabled with an explanation while a job is active (
MEMORY_BUSYnever reaches the user). - Video tools:
ToolsPanel(components/sidecars/, shared with the onboarding) and a re-check. - Advanced: “Parallel translation” group (lanes per file, in-flight caps for paid/free;
NumberSettingwithrecommendeddraws the accepted range with the recommended band and a marker, and warns without blocking outside it, plus a warning whenjobs.concurrency × perJob > paidMaxInFlight), free-model quota today and the detected tier, tier override, requests per minute (free / paid), attempts, waits in seconds (stored in ms), extra chunk rounds, “Restore defaults” (settings:resetwith the advanced keys only), and the limits guide. - About: version, platform, the update panel, the automatic-check switch (
updates.autoCheck), data folder, the full TMDB notice. The panel followsAppUpdateStatus.state(seeipc.md) and every step is an explicit click:idle/not-available→ “Check for updates”;available→ version, size, collapsible release notes and “Download”;downloading→ progress bar from the event plus “Cancel download”;downloaded→ “Restart and update”;error→ non-blocking message (offline or typed error) and “Try again”;unsupported→ explanation and “Open the release page” (fallbackUrlviaapp.openExternal), with Download/Install hidden.UPDATE_JOBS_ACTIVEon install opens a confirmation dialog (“Back” changes nothing; “Cancel jobs and update” retries withconfirmJobs: true). Release notes arrive as untrusted HTML:components/common/release-notes.tsxrebuilds them from a tag allowlist (no attributes, no links, no images) instead of injecting HTML.
Models and Languages
Thin pages over the onboarding pickers (ModelPicker, LanguagePicker, useListWithDefault). Models adds “Refresh list” (models:list { force: true }, bypassing the Main’s 24 h cache), the catalog date, the free-model requests left today, and a warning listing favorites that are no longer in the OpenRouter catalog (the picker cannot show them) with a “Remove” each; removing the default promotes the next favorite.
Presets
pages/presets/. Built-in and custom presets on the left (checkbox per preset to export), the editor on the right. Built-ins are read-only with “Duplicate” (the copy opens selected, “Copied from …”). The form keeps text drafts (preset-draft.ts: same limits as the Main’s PresetInputSchema, validated before sending, errors shown after the first save attempt), trims on save and drops empty optional glossary fields. Media type is free text with suggestions; temperature 0 to 2. Under the style prompt, editable presets show an informational tip recommending English instructions (never an error, never blocks saving; see presets.md). The glossary editor needs a term plus a translation or a rule per row (≤ 500 rows). Delete asks first; PRESET_IN_USE and PRESET_NAME_TAKEN come back as toasts. Import asks the name-conflict policy (rename / skip), opens the native dialog and lists what was imported and what was skipped with the reason.
Extract and Mux
Both open on a single-form page that creates one job and then shows it with JobDetail (like the wizard); “Select several files” switches to the batch wizard (extract-entry.tsx / mux-entry.tsx, mode kept in usePageState under extract.mode / mux.mode, so the choice survives page switches). Shared pieces moved out of the wizard: FileDrop (components/files/, accept limits the kinds), OutputFolder, and TrackPicker (components/media/, single for translate, multi for extract, preselects with pickTrack from lib/tracks.ts).
- Extract: video, one or more tracks, output folder →
{ kind: 'extract', trackIds }. - Mux: video, subtitle files (native dialog, several at once, duplicates ignored, ≤ 32), per row: language (guessed from the file name suffix by
guessSubtitleLanguage,lib/subtitle-lang.ts: skipsforced/sdh/…, accepts only real languages soDr.Who.srtis not “who”), track name (defaults to the language name), at most one default; optionssetDefault/keepOriginalSubtitles. “Create video” stays disabled until every row has a language. Row logic is pure (pages/mux/mux-rows.ts).
Extract and Mux in batch
Same shell as the Translate batch, without the cost step (nothing is billed): StepBar with the canGo/furthest rules (back always; forward to a reached step while every earlier one is valid), one card per step, a footer whose first “Back” returns to the single-file form, and an INVALID_INPUT item N: … from batches:create mapped back to the included row (failedItem), shown as an alert with a button back to the step (Tracks / Pairing), where that row opens already. State lives in usePageReducer (extract.batch / mux.batch) as edits on top of the plan, keyed by path; the plan stays a query (useExtractPlan / useMuxPlan in data/batches.ts, staleTime: Infinity) and is never copied into the state. A new source drops the edits but keeps the output folder (and, for mux, the options). Reducers, row building and request building are pure and tested (*-batch-state.ts).
Shared pieces: SourcePicker and PlanNotices (components/files/source-picker.tsx: folder + “Include subfolders” or several files, dialog or drag & drop; truncated and rejected), OutputFolder, Collapsible and useTrackText from the Translate batch, and SimpleBatchRun (components/jobs/simple-batch-run.tsx, ns: 'extractBatch' | 'muxBatch'): batch name, overall bar (batchFraction), counts queued / running / done / failed (jobCounts, simple-batch-counts.ts), each file live (step and % while running, status pill, the job’s error through errorMessage; links to ?job=), “Cancel all” while active, “Open in Queue” and “Extract other files” / “Mux other videos” (resets the wizard). The created batch id is kept as extract.batch.id / mux.batch.id, so the run survives page switches too.
- Extract (
pages/extract/batch/): Files → Tracks → Output.- Files (
extract-files-step.tsx):batches:planwithkind: 'extract'; the dialog offers videos only. Ready / left-out counts; skipped files (no-subtitle-track,no-supported-track,probe-failed) are listed with the reason and cannot be included. - Tracks (
extract-tracks-step.tsx): one tri-state checkbox per kind of track across the included files (signatureChoices: language + name + format, the sametrackSignatureas Translate, since ids differ between releases;selected/filescounter; toggling appliessignatureEditsto every file that has it), then each file expandable to fine-tune its tracks (image tracks shown, disabled) or leave it out; files left out can be included back. Starts from the plan’s selection (every supported text track); an included file with no track blocks (rowBlocked). - Output: folder (mirrored with a folder source, next to each video without one) and a “N files, M tracks” review →
{ kind: 'extract', root, items: [{ path, trackIds }], outputDir? }.
- Files (
- Mux (
pages/mux/batch/): Files → Pairing → Output.- Files (
mux-files-step.tsx):batches:planwithkind: 'mux'over MKVs and subtitles (the Main pairs them, seejobs.md); loose files of other types are dropped before the call. Counts paired / unmatched subtitles / videos without subtitles. - Pairing (
mux-pairing-step.tsx):buildViewmerges the plan withassign(subtitle → video, ornull= dropped),excludedvideos, per-subtitlesubsedits (language, name) anddefaults(video → default subtitle,null= none, no key = its first subtitle). Unresolved subtitles (the plan could not pair them) come first and block until assigned to a video or ignored. Each included video is expandable: per subtitle, language (undallowed, shown as “Undetermined”, prefilled from the file name suffix by the Main), track name (placeholder = language name), default checkbox (at most one per video), “Move to” another video and remove; a badge says when it was paired by episode or by hand. Videos without subtitles can take a loose one; left-out videos can be restored. Blocks: unresolved subtitles, no included video, a subtitle without language, more than 32 per video (MAX_SUBS_PER_VIDEO; full videos are not offered as targets). - Output: folder,
setDefault/keepOriginalSubtitles(batch-wide), mirror note, name collisions under the output folder (outputCollisions: the Main appends(2), so it is a warning, not a block), a free-space note, and a “N videos, M subtitles” review →{ kind: 'mux', root, items: [{ video, subtitles: [{ path, language, name?, default? }] }], outputDir?, options }. A refused item highlights the video and, when the reason names it, the subtitle.
- Files (
Logs
pages/logs/. The last 1,000 lines (logs:tail) and then live lines (useLiveLogs: logs:watch on while the page is mounted, off when leaving; at most 2,000 lines kept). Filters are local (level, area, job) so changing them never drops live lines; ?job= filters to one job and JobDetail links there (“Show logs”), and each line with a jobId links back to the queue. Details (stderr, HTTP bodies) are collapsible. Follows the bottom while live. “Open log folder” and “Export logs” use the Main’s channels.
Field help, labels and links
HelpTip(components/ui/help-tip.tsx): a ”?” next to a label with a tooltip explanation (hover or keyboard focus; also the accessible description).FieldandSettingRowtake ahelpprop. Tooltips carry their own provider, so they work in dialogs and tests.Buttondefaults totype="button": a button inside a<form>(the glossary editor’s “Add entry” and remove) must never submit it. Submit buttons saytype="submit".Fieldusescontent-start, so a taller neighbour (a two-line hint, an error) never pushes the label and control down.- Built-in presets and the four known media types are shown in the app language (
lib/preset-labels.ts); custom names stay as typed; a duplicated preset gets a free ”(copy)” name in the app language. - Language names start with a capital (“Português (Brasil)”).
- Guides render GFM tables (
remark-gfm); in a dialog the guide’s own title is hidden. New guide:choosing-models(how to read prices, context, Reliable JSON, moderation, and how to choose), linked from Models and the onboarding. - Models: sort (OpenRouter order, price up/down, context) and filters (provider, free only, Reliable JSON, not moderated, favorites only) in
lib/model-list.ts; favorites stay on top. - Queue: the job list is resizable with the mouse or arrow keys (
ResizableAside, width kept in localStorage), names truncate with an ellipsis (full name on hover), and jobs with TMDB context show the title and episode below. - Sidebar: the logo (
assets/logo.svg), Translate on its own at the top (larger, highlighted by colour and a gradient when active), then the Work and Manage groups with more spacing. - Status bar: queue counts and progress, the lane cooldown, the session cost, the installed tool versions (link to Settings → Video tools), the OpenRouter and TMDB key status (link to Settings → Keys), and the app version with an update hint (link to Settings → About). Settings keeps its tab in the URL (
?tab=). - Models: one price range (USD per 1M tokens) that both the input and the output price must fit (
inPriceRange,PRICE_STOPSinlib/model-list.ts). The stops are fixed (0, 0.1 … 0.5, 1, 3, 5, 10+): fine-grained where most of the catalog sits, the last one meaning “and above”; with the upper end at the top, dynamic-price models stay listed. The “N of M · K favorites” count sits below the list, right-aligned. Rows never truncate: names, ids and prices wrap. On the Models and Languages pages the last favorite/language cannot be removed (the app needs a default; the onboarding still allows it while choosing). - Everything clickable shows the pointer cursor (Tailwind v4 removed it for buttons; restored in
styles/main.css). Guides take the full width of their container. - About: version, author, the update panel, repository and “Buy me a coffee” (both hosts are in the Main’s external-link allowlist).
- Update state:
useAppUpdateStatusreadsapp:get-update-stateonce;useAppUpdateEvents(inEventBridge) patchesqk.app.update()fromapp:update-statewithsetQueryData, no polling. Outside Settings the signals are a dot on the Settings sidebar item, the status-bar hint and a dialog (app/update-dialog.tsx, mounted once inApp) that opens once per version per session when the state becomesavailable: current → new version, publish date, size and the sanitized release notes (ReleaseNotes). “See details and update” navigates to Settings → About, where the download happens; “Later”, Esc, the overlay and the close button just dismiss it until the next app start (the seen set lives in memory, there is no persistent “skip this version”).unsupported,error/offline andnot-availableopen nothing. Never an automatic download or install.
Polish
- Locales:
i18n/locales/<lang>/{common,errors}.ts. Every non-English file is typedLocaleShape<typeof en>(i18n/locale-shape.ts), so a missing or extra key fails the typecheck, andi18n/locales.test.tschecks that every string keeps the same{{variables}}as English. Adding a language: add it toAPP_LANGUAGES(contract), translate both files and every guide, register it ini18n/index.ts. The language picker (LanguageSelect) is in Settings and on the first onboarding screen. - Notifications: emitted by the Main (see
notifications.md); the renderer only follows a click:app/navigation-events.ts(useNavigationEventsinEventBridge) mapsapp:navigateto the queue job, the batch on Translate (?batch=) or Settings → About. - Bundle: screens are
React.lazychunks (app/screens.ts, rendered inSuspenseby the router), the guide viewer (react-markdown) loads only when a guide opens, and the renderer build is minified (electron.vite.config.ts; electron-vite leaves it off by default). Entry chunk ≈ 380 kB (was ≈ 2.2 MB unminified, single chunk). - Accessibility: labelled controls (
Field,aria-labelon icon buttons),aria-currenton steps and selections,role="alert"/status/logwhere state changes, visible focus everywhere, andprefers-reduced-motionturns off spinners, pulses and transitions. Not yet audited with a screen reader on each OS.
In-app guides
User guides (OpenRouter key, limits and retries, TMDB key) live in src/renderer/src/guides/<lang>/<id>.md, outside docs/ (which is for developers), with one file per language (en, pt-BR). guides.ts bundles them with import.meta.glob('?raw'); useGuide(id) returns the guide in the current i18next language (exact, then base language, then English). It uses i18n.language, not resolvedLanguage, so a guide can already be shown in a language the UI does not have yet. Links between guides are relative .md links (guideIdFromHref turns them into in-app navigation). guides.test.ts fails when a translation is missing or a cross-link is broken. Details: guides/README.md.
Theme
Dark only (color-scheme: dark), pink (--primary) and violet (--violet) on a deep plum background. Tokens use shadcn/ui names (background, card, muted, primary, ring…) so its components drop in unchanged; bg-brand is the pink→violet gradient. The values come from src/shared/brand/ (shared with the site), imported by styles/main.css: see Brand tokens. Panels over media artwork use Card (bg-card/92 + blur): semi-opaque, never fully transparent. Icons: lucide-react.
Tests
vitest + Testing Library. Renderer test files start with // @vitest-environment jsdom. test/fake-api.ts installs a typed window.api where every unmocked call rejects (a test cannot pass on an accidental channel) and emit() pushes IPC events.