Files
youtube-generator/docs/TECH-SPEC.md
T
poli0981andClaude Opus 5.5 cefbbd13ee feat(editor): add DLSS 5 neural rendering, more frame generation modes and a custom LUT
Video settings:
- NVIDIA frame generation gains x6 (the multiplier was already in the list
  but offered by no vendor) and Dynamic Multi Frame Generation (DLSS 4.5).
- "Custom…" for every vendor reveals a text field (`frameGenCustom`); the
  description prints what was typed, like a custom graphics preset, and
  nothing for an empty box.
- A "DLSS 5 Neural Rendering" switch (`dlssNeuralRendering`), shown for
  NVIDIA only and printed after the DLSS mode:
  "Ultra - NVIDIA DLSS Quality + NVIDIA DLSS 5 Neural Rendering + NVIDIA
  Dynamic Multi Frame Generation". Another vendor turns it off
  (`coerceDlssNeuralRendering`: the vendor switch, applied profiles and
  templates, backup import).
- Editor store v21 -> v22 back-fills both fields.
- composeGraphicsPart's vendor half moves into small helpers.

My Rig: "Custom" is the LUT field's first suggestion (typing it works too,
any case). The rig block then prints just "LUT applied" in the output
language ("Có áp dụng LUT") instead of "LUT: Custom" — a field's
`customNoteKey`. No migration: the rig is a string map.

i18n: the new editor and description keys in all 8 locales and
_schema.json; brand names stay English. tests/engine/graphics-vendor.test.ts
also holds every vendor's options to their labels in the schema.

Docs: FEATURES (upscaler / frame-gen table, LUT Custom), TECH-SPEC (input
fields, store v22, rig block), CLAUDE.md (how to add an option).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 10:46:35 +07:00

752 lines
58 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Technical Specifications
## YTDescGen — Implementation Details
Reflects **v1.5.2**. The module map and data flow are in [ARCHITECTURE.md](ARCHITECTURE.md), the desktop and Android builds in [PACKAGING.md](PACKAGING.md), and running the web deployment (Cloudflare Worker, Turnstile, secrets, rollback) in [HOSTING.md](HOSTING.md).
---
## 1. Package Configuration
### package.json
```json
{
"name": "yt-desc-gen",
"version": "1.5.2",
"private": true,
"license": "Apache-2.0",
"type": "module",
"engines": {
"node": ">=26"
},
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"preview": "vite preview",
"test": "vitest",
"test:run": "vitest run",
"test:coverage": "vitest run --coverage",
"lint": "eslint src/ tests/ scripts/ worker/ build-plugins/",
"lint:fix": "eslint src/ tests/ scripts/ worker/ build-plugins/ --fix",
"knip": "knip",
"typecheck": "tsc --noEmit",
"typecheck:all": "tsc --noEmit -p tsconfig.check.json",
"format": "prettier --write \"{src,tests,scripts,worker,build-plugins}/**/*.{ts,tsx,css}\"",
"format:check": "prettier --check \"{src,tests,scripts,worker,build-plugins}/**/*.{ts,tsx,css}\"",
"check:version": "tsx scripts/check-version-sync.ts",
"validate:locales": "tsx scripts/validate-locales.ts",
"generate:locale": "tsx scripts/generate-locale-template.ts",
"tauri": "tauri",
"tauri:dev": "tauri dev",
"tauri:build": "tauri build",
"generate:brand": "tsx scripts/generate-brand-assets.ts",
"cf:dev": "wrangler dev",
"cf:check": "wrangler deploy --dry-run --outdir .wrangler/dry-run",
"check:tauri": "tsx scripts/check-tauri-versions.ts",
"check:bundle": "tsx scripts/check-bundle-size.ts",
"check:licenses": "tsx scripts/third-party.ts",
"generate:third-party": "tsx scripts/third-party.ts --write",
"check:copyright": "tsx scripts/check-copyright.ts",
"update:copyright": "tsx scripts/check-copyright.ts --write"
},
"dependencies": {
"@fontsource-variable/inter": "^5.3.0",
"@fontsource-variable/jetbrains-mono": "^5.3.0",
"@tauri-apps/api": "^2.12.4",
"@tauri-apps/plugin-opener": "^2.7.2",
"clsx": "^2.1.1",
"cmdk": "^1.1.1",
"i18next": "~26.6.0",
"i18next-resources-to-backend": "^1.2.4",
"lucide-react": "^1.66.0",
"motion": "^13.5.1",
"radix-ui": "^1.8.1",
"react": "^19.3.1",
"react-dom": "^19.3.1",
"react-i18next": "^17.1.11",
"react-router-dom": "^7.18.5",
"simple-icons": "^16.36.0",
"sonner": "^2.0.8",
"zustand": "^5.0.16"
},
"devDependencies": {
"@eslint/js": "^10.0.1",
"@resvg/resvg-js": "2.6.2",
"@tailwindcss/postcss": "^4.3.4",
"@tauri-apps/cli": "2.12.4",
"@testing-library/jest-dom": "^7.0.1",
"@testing-library/react": "^16.3.3",
"@types/node": "^26.6.6",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"@typescript/native": "npm:typescript@^7.0.2",
"@vitejs/plugin-react": "^6.2.1",
"@vitest/coverage-v8": "^4.1.12",
"autoprefixer": "^10.6.2",
"eslint": "^10.14.0",
"eslint-plugin-react-hooks": "^7.1.1",
"knip": "^6.44.1",
"marked": "18.1.3",
"postcss": "^8.5.32",
"prettier": "^3.9.10",
"prettier-plugin-tailwindcss": "^0.8.1",
"tailwindcss": "^4.3.3",
"tsx": "^4.23.15",
"typescript": "npm:@typescript/typescript6@^6.0.2",
"typescript-eslint": "^8.72.1",
"vite": "^8.3.5",
"vitest": "^4.1.12",
"wrangler": "4.156.2"
}
}
```
Notes:
- **UI stack**: React 19, React Router 7, Zustand 5, i18next 26 / react-i18next 17, Radix primitives through the single `radix-ui` package (Dialog, AlertDialog, Popover, Tooltip, Tabs, Switch, Checkbox, ToggleGroup, Slot), Motion (loaded through `LazyMotion`), cmdk for the command palette, sonner for toasts (react-hot-toast is gone), lucide-react 1.x for UI icons and simple-icons (CC0-1.0) for the brand marks lucide 1.x dropped.
- **Tauri on the JavaScript side** is only `@tauri-apps/api` (for `invoke`) and `@tauri-apps/plugin-opener`. There are no dialog, fs or shell plugin packages: file access goes through the app's own Rust commands (see [PACKAGING.md](PACKAGING.md)). `@tauri-apps/cli` is pinned exactly, and `npm run check:tauri` keeps the npm packages on the same major.minor as the crates.
- **Build-time only**: `marked` renders the legal documents and `@resvg/resvg-js` rasterises the brand assets; neither ships in the app. `wrangler` is pinned exactly for `cf:dev` / `cf:check`.
- **i18next stays on 26.6.x** (`~26.6.0`, and a Dependabot ignore for 26.7.x): 26.7 adds the debug-mode warnings for the move to v27 — about 1.9 KB gzip that would take the initial load over its 280 KB budget. The tilde and the ignore go with the i18next 27 migration (`.github/dependabot.yml` has the note).
- **Fonts** are self-hosted: `@fontsource-variable/inter` and `@fontsource-variable/jetbrains-mono` are imported in `src/main.tsx`, and each subset (latin, latin-ext, vietnamese, …) is fetched only when a page uses it.
- **TypeScript 7** checks types: `@typescript/native` is an npm alias for `typescript@7`, the native compiler, and supplies `tsc`. TypeScript 7.0 ships no JavaScript API, so `typescript` is an alias for `@typescript/typescript6` — the TypeScript 6.0 API that typescript-eslint loads (its peer range stops below 6.1), plus `tsc6`. Both are Microsoft's documented side-by-side setup. `@typescript/typescript6` pulls TypeScript 6 in as `@typescript/old`, which ships a `tsc` too; CI fails if the `tsc` on `PATH` is not 7.x. Dependabot may not follow `npm:` aliases, so TypeScript bumps can be manual.
- **Node 26** comes from `.node-version`, which CI, the release workflows and Cloudflare Workers Builds all read; `engines.node` says `>=26`. Vitest runs its workers with `--no-experimental-webstorage`: Node 25+ defines a `localStorage` global that is `undefined` without `--localstorage-file`, and zustand's `persist` crashes on it instead of falling back to memory.
- **Installs skip lifecycle scripts** in every workflow (`npm ci --ignore-scripts`). The three packages that have one — esbuild, workerd, fsevents — take their native binary from `optionalDependencies`.
### tsconfig.json
```jsonc
{
"compilerOptions": {
// The newest ECMAScript year that TypeScript 7.0, esbuild (tsx, wrangler)
// and Vite all understand. ES2026 arrives with TypeScript 7.1.
"target": "ES2025",
// `lib` is the runtime floor, not the syntax target. Vite lowers syntax but
// never polyfills, so a built-in typed here must exist in every engine the
// app supports: Vite's `baseline-widely-available` — Chrome 111, Safari
// 16.4, Firefox 114 (ES2023's copy-array methods need Firefox 115). Raise it
// when that floor moves. Code that runs on Node or workerd gets the newer
// lib in tsconfig.check.json.
"lib": ["ES2022", "DOM"],
// TypeScript 6+ no longer loads every installed @types package. The app
// needs none: `vite/client` comes in through src/vite-env.d.ts.
"types": [],
"module": "ESNext",
"skipLibCheck": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"erasableSyntaxOnly": true,
"moduleDetection": "force",
"noEmit": true,
"jsx": "react-jsx",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noUncheckedIndexedAccess": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"paths": {
"@/*": ["./src/*"],
"@config/*": ["./src/config/*"],
"@engine/*": ["./src/engine/*"],
"@store/*": ["./src/store/*"],
"@hooks/*": ["./src/hooks/*"],
"@components/*": ["./src/components/*"],
"@pages/*": ["./src/pages/*"],
"@utils/*": ["./src/utils/*"],
"@i18n/*": ["./src/i18n/*"],
},
},
"include": ["src"],
}
```
`tsconfig.json` covers only `src/` — what `vite build` compiles. `tsconfig.check.json` extends it for `npm run typecheck:all`: it adds `tests`, `scripts`, `worker` and `build-plugins`, the `vitest/globals` and `node` types those need, and `lib: ["ES2025", "DOM"]` — they run on Node 26 or workerd, not in the app's browsers. There is no `baseUrl` (TypeScript 7 dropped it); `paths` are relative. `erasableSyntaxOnly` keeps out the TypeScript syntax that only TypeScript can emit (enums, namespaces, parameter properties), which Oxc, esbuild and Node's type stripping all rely on.
### vite.config.ts
```typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "path";
import { legalDocsPlugin } from "./build-plugins/legal-docs.ts";
import { cloudflareWebAnalytics, securityTxt } from "./build-plugins/web-only.ts";
// Set by the Tauri CLI for `tauri dev` / `tauri build`.
const isTauri = !!process.env.TAURI_ENV_PLATFORM;
export default defineConfig({
plugins: [
react(),
// In-app Legal Center content for every build; the static /legal pages,
// security.txt and the analytics beacon only for the web deployment.
legalDocsPlugin({ emitStaticPages: !isTauri }),
...(isTauri ? [] : [securityTxt(), cloudflareWebAnalytics()]),
],
// Web: https://ytgenerator.stream (Cloudflare Workers static assets).
// Tauri: its own asset protocol. The GitHub Pages sub-path is gone.
base: "/",
resolve: {
alias: {
"@": path.resolve(import.meta.dirname, "./src"),
"@config": path.resolve(import.meta.dirname, "./src/config"),
"@engine": path.resolve(import.meta.dirname, "./src/engine"),
"@store": path.resolve(import.meta.dirname, "./src/store"),
"@hooks": path.resolve(import.meta.dirname, "./src/hooks"),
"@components": path.resolve(import.meta.dirname, "./src/components"),
"@pages": path.resolve(import.meta.dirname, "./src/pages"),
"@utils": path.resolve(import.meta.dirname, "./src/utils"),
"@i18n": path.resolve(import.meta.dirname, "./src/i18n"),
},
},
server: {
// `tauri dev` rebuilds under src-tauri/target while Vite runs; watching
// it crashed Vite on Windows (EBUSY on the locked .dll).
watch: { ignored: ["**/src-tauri/**", "**/.wrangler/**"] },
},
build: {
// No `target`: both builds use Vite's default, `baseline-widely-available`
// (Chrome 111, Safari 16.4, Firefox 114) — the floor tsconfig's `lib` holds.
//
// The Tauri CSP allows only 'self' for images and fonts: no data: URIs.
assetsInlineLimit: 0,
// Full license texts of the bundled packages, linked from the
// third-party notices.
license: { fileName: "licenses/third-party.md" },
rollupOptions: {
output: {
// Rolldown (Vite 8) only accepts the function form of manualChunks.
manualChunks(id) {
if (/[\\/]node_modules[\\/]react(-dom)?[\\/]/.test(id)) return "react";
if (/[\\/]node_modules[\\/]react-router(-dom)?[\\/]/.test(id)) return "router";
if (
/[\\/]node_modules[\\/](i18next|react-i18next|i18next-resources-to-backend)[\\/]/.test(
id,
)
)
return "i18n";
return undefined;
},
},
},
},
});
```
What differs between the two builds:
| | Web build | Tauri build (`TAURI_ENV_PLATFORM` set) |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Legal documents | `virtual:legal-docs` (lazy chunk for the Legal Center) **and** static `dist/legal/<id>.html` (+ `<id>.vi.html`, `index.html`) | `virtual:legal-docs` only |
| `/.well-known/security.txt` | Generated on every build (RFC 9116, `Expires` 180 days ahead) | — |
| Cloudflare Web Analytics beacon | Injected before `</body>` of `index.html` (build only, never in `npm run dev`) | — |
| JS target | Vite default (`baseline-widely-available`) | the same (before v1.3.0: `es2020`) |
`build-plugins/legal-docs.ts` renders the repository's legal files (`TERMS.md`, `PRIVACY.md`, `DISCLAIMER.md` + `docs/i18n/vi/DISCLAIMER.md`, `LICENSE`, `THIRD_PARTY_NOTICES.md`, `SECURITY.md`, `NOTICE`, `CODE_OF_CONDUCT.md`; list in `src/config/legal.ts`) with `marked` at build time. `build-plugins/web-only.ts` holds the analytics snippet and the `security.txt` generator.
### Styling: Tailwind CSS 4
There is no `tailwind.config.ts` (removed in v0.37.0). PostCSS loads `@tailwindcss/postcss` and `autoprefixer` (`postcss.config.js`), and Tailwind is configured in CSS, in `src/styles/globals.css`:
```css
@import "tailwindcss";
/* The app toggles a .dark / .light class on <html> instead of following the OS. */
@custom-variant dark (&:where(.dark, .dark *));
/* Tailwind names → runtime variables. The values live in the :root / .light blocks,
which is what the theme toggle rewrites. */
@theme {
--color-surface-0: var(--surface-0);
--color-surface-1: var(--surface-1);
--color-text-primary: var(--text-primary);
--color-accent: var(--accent);
--font-sans: var(--font-sans-stack);
--radius-card: 0.875rem;
/* Controls are compact with a mouse and 44px on touch screens. */
--spacing-control: var(--control-h);
/* … the full token list is in the file … */
}
```
Components use the tokens (`bg-surface-1`, `text-text-muted`, `rounded-card`, …), never raw colours. `public/theme-init.js` applies the saved theme and the Hide scrollbars class (and sets `<html lang>` to the saved UI language) before the first paint; it is a separate file rather than an inline script so the Content-Security-Policy needs no exception.
### wrangler.jsonc
The only Cloudflare file in the repository; Workers Builds runs `npx wrangler deploy` on every push to `main`. Its settings, without the file's comments:
```json
{
"name": "youtube-generator",
"main": "worker/index.ts",
"compatibility_date": "2026-09-25",
"workers_dev": false,
"preview_urls": true,
"routes": [{ "pattern": "ytgenerator.stream", "custom_domain": true }],
"build": { "command": "npm run build" },
"assets": {
"directory": "./dist",
"binding": "ASSETS",
"not_found_handling": "404-page",
"run_worker_first": [
"/*",
"!/assets/*",
"!/icons/*",
"!/.well-known/*",
"!/favicon.svg",
"!/favicon.ico",
"!/apple-touch-icon.png",
"!/og-image.png",
"!/manifest.webmanifest",
"!/robots.txt",
"!/sitemap.xml",
"!/theme-init.js",
"!/licenses/*",
"!/404.html"
]
},
"ratelimits": [
{ "name": "RATE_LIMIT", "namespace_id": "1001", "simple": { "limit": 120, "period": 60 } },
{ "name": "VERIFY_RATE_LIMIT", "namespace_id": "1002", "simple": { "limit": 10, "period": 60 } }
],
"vars": {
"TURNSTILE_SITE_KEY": "0x4AAAAAAFKFAMUx9rQ5H6bQ",
"GATE_TTL_SECONDS": "86400"
},
"observability": { "enabled": true }
}
```
Every request goes through the Worker first except content-hashed build output and the public files browsers and crawlers fetch without cookies. `not_found_handling` is `404-page`, not the SPA fallback, so no path can reach `index.html` without passing the gate. `TURNSTILE_SECRET` is a dashboard Secret, never committed. The two `ratelimits` bindings (Workers Rate Limiting API, v1.3.2) cap each client — an IPv4 address or an IPv6 /64 — at 120 Worker requests and 10 verify calls a minute, behind the zone's WAF rate limiting rule. Request flow, cookies, headers, rate limits and operations: [HOSTING.md](HOSTING.md).
The Worker (`worker/`): `index.ts` (entry; injects the clock, `fetch` and random ids), `router.ts` (routing), `rate-limit.ts` (the per-client limit checked before anything else: client key, fail-open check, the `429`), `env.ts` (bindings, constants, the gate lifetime clamped to 5 min – 30 days), `turnstile.ts` (siteverify call and verdict: success, hostname, action `enter`, token age ≤ 300 s), `cookie.ts` (the HMAC-signed `__Host-ytg_gate` cookie, key derived from the Turnstile secret, bound to a User-Agent hash), `headers.ts` (CSP per page type and the baseline security headers), `gate-page.ts` + `gate-i18n.ts` (the gate page in the app's eight languages). It uses only standard Web APIs, so it type-checks against the DOM lib and runs under Vitest in Node.
## 2. Core Engine Interfaces
`renderAll(input, t, options?)` in `src/engine/template-renderer.ts` is the entry point: it calls `buildTitle`, `buildDescription` and `generateTags` and returns a `GeneratorOutput`. `t` is an i18next translator fixed to the output language and the `templates` namespace.
```typescript
// src/engine/types.ts — abridged; the file has every field with its history.
export type SupportedLanguage = "en" | "vi" | "ja" | "es" | "ko" | "zh" | "pt-BR" | "id";
export interface GeneratorInput {
videoType: VideoType; // 20 video types
language: SupportedLanguage;
/** 1–3 genres (MAX_GENRES); the first drives the genre hashtag and trending tags. */
genres: Genre[];
gameName: string;
gameNameLocalized?: Partial<Record<SupportedLanguage, string>>;
/** May be empty: the channel phrase is then dropped (channel-phrase.ts). */
channelName: string;
platform: string;
// Video-type specific: partNumber, bossName, dlcName, challengeName, modName, modList,
// liveUrl, scheduledTime, gachaQuestType, chapterName, questName, characterName,
// anniversaryYear, gachaVersion.
// Video settings: resolution, upscaledFrom (v1.5.0), fps, graphicsPreset (+ graphicsPresetCustom),
// skipGraphicsSettings, rayTracingModes, frameGenVendor, frameGenMultiplier
// (+ frameGenCustom, v1.6.0), upscaleQuality, dlssNeuralRendering (v1.6.0),
// artStyle, videoStyleEra, versionInfo.
// Content: timestamps, playlistLink, contactEmail, adEmail, gameKeyEmail,
// copyrightEmail, musicAttribution, sponsorName, sponsorPlatform, pubDevName,
// thirdPartyAdText,
// playthroughStatus, difficulty, endings, languagePatch, gameVersion,
// contentWarnings, techNotes, playtest fields, community invite links,
// Vietnamese donate fields.
/** @deprecated v0.11 — folded into contentWarnings. */
spoilerWarning: boolean;
/** @deprecated v0.11 — folded into contentWarnings. */
matureWarning: boolean;
storeLinks: Partial<Record<string, string>>;
/** "paid" | "free" | "demo" per store link. */
storeLinkTypes?: Partial<Record<string, StoreLinkType>>;
social: Partial<Record<string, string>>;
/** Since v1.0.0 the GPU is stored as `gpu:<catalog id>` (src/config/gpu-catalog.ts). */
rig: Partial<Record<string, string>>;
}
export interface GeneratorOutput {
title: string;
description: string;
tags: string[];
/** The tags joined with ", " — what Copy puts on the clipboard. */
tagString: string;
charCounts: {
title: number;
description: number;
/** youtubeTagsLength(tags) — YouTube's count, not tagString.length. */
tags: number;
};
/** One entry per field that is strictly over its limit. */
warnings: CharLimitWarning[];
}
export interface CharLimitWarning {
field: "title" | "description" | "tags";
current: number;
limit: number;
message: string; // English; the UI builds its own text from the numbers
}
// YouTube limits
export const YT_LIMITS = {
TITLE_MAX: 100,
DESCRIPTION_MAX: 5000,
TAGS_MAX: 500,
SINGLE_TAG_MAX: 30,
HASHTAG_MAX: 3,
} as const;
export interface TitleFormatConfig {
badgePosition: TitleBadgePosition; // "prefix" | "middle" | "suffix"
separator: TitleSeparatorId; // "emDash" | "hyphen" | "colon" | "pipe"
badgeCase: TitleBadgeCase; // "upper" | "lower"
/** v1.0.0. Missing on settings saved before — read as "gameFirst". */
order?: TitleOrder; // "gameFirst" | "typeFirst"
}
```
`RenderOptions` = `SettingsRenderOptions` (the twelve settings-derived knobs, built by `buildRenderOptions` in `src/hooks/use-render-options.ts`) + `RenderOptionOverrides` (`tEn`, `bilingualContentBlocks`, `year`, decided per call site). The year for the copyright line and trending tags comes in as an option so tests are deterministic; the builders fall back to the current year when it is omitted.
### 2.1 Engine rules added or changed in v1.0.0
**Tag length, counted the way YouTube counts it** (`tag-generator.ts`):
- `youtubeTagsLength(tags)` = the sum of each tag's length, plus 2 for the quotes YouTube puts around any tag containing whitespace, plus one comma between tags. The old measure (length of the `", "`-joined string) ignored the quotes; 15 of 51 real tag sets were over 500 by YouTube's count while showing as under.
- `generateTags` collects, in priority order: the game name (bare, and a shortened form for composites), the boss name for the video types whose `extraFields` include `bossName` (v1.4.0 — `bossNameTag`: NFC, every mark but in-word `'` `’` `-` and digit-to-digit `.` removed, dots between initials dropped, the name before its title or the leading words when over 30 characters), core tags for the output language, genre tags for every selected genre, video-type tags, platform tags, quality tags, the output language's multilingual tags (setting), trending tags for the first genre (setting), and the publisher/developer name. It then de-duplicates case-insensitively, drops tags over 30 characters, and `trimToCharLimit(tags, 500)` keeps tags in priority order while they fit — a tag that doesn't fit is skipped and the shorter ones after it are still tried.
- Platform tags use `PlatformConfig.tagName` ("Steam", "Epic Games", "itch.io"), not the id; the publisher's own site has no tag name and adds no platform tags.
**Empty channel name** (`channel-phrase.ts`, used by the description, pinned comment and playlist builders): templates render with `CHANNEL_SLOT` (`@@CHANNEL@@`) in place of an empty channel name. `withoutEmptyChannel(text, language)` then removes the words that go with the channel name in that language ("trên kênh", "による", "en", "no", "di", …) and the English "on" (for English, and for locales that still carry English sentences for newer video types), replaces any slot left over with a neutral fallback ("this channel", "kênh", …) and tidies the spacing before punctuation. "…of Hades on ." no longer happens in any of the eight languages.
**Rig block** (`rig-block.ts`): `buildRigLines(rig, t)` returns `Label: value` lines, shared by the description and the social captions. Labels come from `description.rigLabels.<field>` in the output language, the order is `RIG_FIELDS` (CPU, GPU, RAM, motherboard, storage, OS, monitor, capture, controller, video editor, LUT), and values go through `formatRigValue` (`gpu:nvidia-rtx-5080` → "NVIDIA GeForce RTX 5080"; a text field's `clean` — `cleanCpuName`, and since v1.4.0 `cleanLutName`, which cuts a pasted path or `.cube` / `.dat` file name down to the LUT's name — runs there as well as when the editor field loses focus). A field with a `customNoteKey` whose value is "Custom" (any case) prints that templates key as its whole line instead — since v1.6.0 the LUT's "LUT applied" (`description.rigNotes.lut_custom`), for a LUT of one's own. Keys that are no longer rig fields are still printed, after the known ones.
**Chapters** (`timeline-parser.ts`):
- A timestamp line may be `0:00 label`, `[0:00] label`, `(0:00) label`, `H:MM:SS`, or frame-accurate `HH:MM:SS:FF` (frames are dropped), with an optional separator (`-`, `–`, `—`, `:`, `|`, `•`, `·`).
- Latin-script keywords must end at a non-letter ("Part 2" is a part, "Party" is not). A bare "Final" counts as an ending only when nothing but a number or punctuation follows it, so "Final Fantasy VII" stays a game name.
- `checkChapters(entries)` applies YouTube's rules (`CHAPTER_RULES = { minCount: 3, minSeconds: 10 }`): first timestamp at 0:00, at least three, ascending, each chapter at least 10 s. Issues: `firstNotZero`, `tooFew`, `outOfOrder`, `tooShort`. An empty list has no issues.
- `normalizeTimeline(raw)` ("Tidy up") rewrites a pasted list as `M:SS label` lines without brackets, frames or separators; lines that are not timestamps are kept.
**Title shapes** (`title-variants.ts`): `buildTitleVariants` returns three shapes, each produced by the real `buildTitle` with a different `{ order, badgePosition }` — `default` (gameFirst, middle), `typeFirst` (typeFirst, middle), `qualityFirst` (gameFirst, prefix). The user's separator and badge case still apply, and the shape's `format` is what "Apply" writes into the `titleFormat` setting, so the Output title then matches what was shown.
**Social captions** (`social-post-builder.ts`, platforms in `src/config/social-platforms.ts`):
| Platform | Limit | Hashtags kept | Count |
| --------------- | ----- | ------------- | ---------------------------- |
| TikTok | 4,000 | all | plain length |
| YouTube Shorts | 5,000 | 5 | plain length |
| Instagram Reels | 2,200 | all | plain length |
| Facebook Reels | 2,200 | all | plain length |
| X | 280 | 3 | weighted (`xWeightedLength`) |
| Threads | 500 | 1 | plain length |
| Bluesky | 300 | 3 | plain length |
`xWeightedLength` NFC-normalises the text and walks grapheme clusters: an emoji counts 2; otherwise each code point counts 1 inside X's weight-1 ranges (U+0000–U+10FF, U+2000–U+200D, U+2010–U+201F, U+2032–U+2037) and 2 outside them (CJK, Hangul, Vietnamese letters from Latin Extended Additional). When a caption is over its limit, optional blocks are dropped in the order warnings → copyright → thanks → rig; `isOver` reports any overflow that remains.
**Limits and forbidden characters** (`limits.ts`): see [§ 7](#7-youtube-character-limits-reference).
## 3. Zustand Store Pattern
Every persisted store follows the same shape. The editor store, abridged:
```typescript
// src/store/editor-store.ts (abridged)
import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
export interface EditorData {
/* every form field */
}
interface EditorActions {
set: <K extends keyof EditorData>(key: K, value: EditorData[K]) => void;
setNested: <G extends "storeLinks" | "social" | "rig">(
group: G,
key: string,
value: string,
) => void;
setStoreLinkType: (platformId: string, type: StoreLinkType) => void;
loadProfile: (profile: Partial<EditorData>) => void;
loadPreset: (preset: Partial<EditorData>) => void;
reset: () => void;
}
/** Bump together with a new step in migrateEditorState. */
export const EDITOR_STORE_VERSION = 22;
export const useEditorStore = create<EditorData & EditorActions>()(
persist(
(set) => ({
...initialState, // built from DEFAULTS.editor (src/config/defaults.ts)
set: (key, value) => set({ [key]: value }),
setNested: (group, key, value) =>
set((state) => ({ [group]: { ...state[group], [key]: value } })),
setStoreLinkType: (platformId, type) =>
set((state) => ({ storeLinkTypes: { ...state.storeLinkTypes, [platformId]: type } })),
// normalizeEditorPatch maps legacy values and clamps string lengths.
loadProfile: (profile) => set((state) => ({ ...state, ...normalizeEditorPatch(profile) })),
loadPreset: (preset) => set((state) => ({ ...state, ...normalizeEditorPatch(preset) })),
reset: () => set(initialState),
}),
{
name: "ytdescgen-editor-draft",
storage: createJSONStorage(() => localStorage),
version: EDITOR_STORE_VERSION,
migrate: (persistedState, version) => migrateEditorState(persistedState, version),
partialize: (state) => editorDataOf(state), // data only, never the actions
},
),
);
/** The persist migration — exported, and run again by backup import. */
export function migrateEditorState(persistedState: unknown, version: number): EditorData {
/* one `if (version < N)` block per schema change; every step is idempotent */
}
```
| Store | localStorage key | Version | Migration (exported) |
| ------------------ | ------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------- |
| `useEditorStore` | `ytdescgen-editor-draft` | `EDITOR_STORE_VERSION` = 22 | `migrateEditorState` |
| `useProfileStore` | `ytdescgen-profiles` | `PROFILE_STORE_VERSION` = 3 | `migrateProfilesState` |
| `usePresetStore` | `ytdescgen-presets` | `PRESET_STORE_VERSION` = 2 | `migratePresetsState` |
| `useTemplateStore` | `ytdescgen-templates` | `TEMPLATE_STORE_VERSION` = 2 | `migrateTemplatesState` |
| `useHistoryStore` | `ytdescgen-history` | `HISTORY_STORE_VERSION` = 3 | `migrateHistoryState` |
| `useSettingsStore` | `ytdescgen-settings` | `SETTINGS_STORE_VERSION` = 12 | `healSettings` (`settings-heal.ts`), as `migrate` **and** in `merge`, so it runs on every load |
v1.0.0 migration steps: editor v19, profiles v3 and templates v2 move the GPU to the catalog format (`migrateRig`: `brand|series|model` → `gpu:<id>`, or the full name as free text when the card is not in the catalog); history v3 folds the duplicates older versions piled up into one entry per video (`dedupeHistory`; a video is game name (case-insensitive) + video type + language + title), keeping the newest.
v1.1.0: editor v20 back-fills `copyrightEmail` (the fourth split contact line) with `""`. `Profile.copyrightEmail` is optional, like the v1.0.0 additions, so the profile store stays at v3. The settings gain `hideScrollbars` without a version bump: `healSettings` back-fills and coerces it on every load, and the unchanged version keeps a 1.1.0 settings backup restorable on 1.0.0.
v1.2.0: nine content-warning ids and one tech note, and no version bump anywhere — the lists only widen. The backup whitelist (`choiceList` in `src/utils/backup/sanitize.ts`) checks against `CONTENT_WARNINGS` / `TECH_NOTES`, so a 1.1.0 build restoring a 1.2.0 backup keeps everything except the ids it doesn't know.
v1.5.0: editor v21 back-fills `upscaledFrom` (recorded at a lower resolution, upscaled to `resolution` in the video editor) with `""` and turns an unknown value into `""`; `normalizeEditorPatch` does the same for an applied profile or template, and the backup whitelist checks it against `UPSCALED_FROM_OPTIONS`. `Profile.upscaledFrom` is optional, so the profile store stays at v3. The engine's own tech note (`AUTO_TECH_NOTES`, `editor_upscaled`) is never stored, so `techNotes` and its whitelist don't change.
v1.5.1: the settings gain `singleKeyShortcuts` (default `true`: the bare `?` opens the shortcut list) without a version bump, like `hideScrollbars` — `healSettings` back-fills it and turns anything but a boolean into `true`.
v1.6.0: editor v22 back-fills `frameGenCustom` (the frame generation typed for the new `"custom"` multiplier) with `""` and `dlssNeuralRendering` (NVIDIA DLSS 5 Neural Rendering) with `false`, coercing values of the wrong type. The multiplier list only widens (`x6` and `dynamic` for NVIDIA, `custom` for every vendor), and the backup whitelist checks it against `FRAMEGEN_MULTIPLIERS`. `normalizeEditorPatch` and the backup import turn `dlssNeuralRendering` off for any vendor but NVIDIA (`coerceDlssNeuralRendering`). Neither field is a profile or preset field, like the rest of the frame-gen settings. The LUT's "Custom" needs no migration: it is a rig value like any LUT name.
Rules:
- **localStorage is the only store**, on the web, desktop and Android. The desktop "mirror" file of earlier versions (`storage-adapter.ts`, `saveSettings`, `checkDataFileHealth`) was removed in v1.0.0; it was written next to the data folder and never read back. [PACKAGING.md](PACKAGING.md) covers how the leftover file is recovered.
- `partialize` persists data only. A shape change bumps the store's exported version and adds an idempotent step to its exported migration; backup import replays the same steps from the version a file records.
- Settings are healed on every load, not only on a version change, so a hand-edited value never reaches the app. Seven settings are device-local and never exported or overwritten by an import (`LOCAL_SETTINGS_KEYS` in `src/utils/backup/sanitize.ts`): `legalConsentVersion`, `legalConsentAt`, `editorAccordionState`, `settingsAccordionState`, `sidebarCollapsed`, `lastProfileId`, `lastPresetId`.
- **Not persisted by Zustand**: `useLogStore` (up to 2,000 entries in memory; `src/utils/log-storage.ts` mirrors each entry to the `ytdescgen-logs` localStorage key on the web, capped at 5,000, or to daily JSONL files in Tauri), `usePendingInvalidStore` (typed-but-invalid text) and `useRestoreDialog` (the file waiting in the restore dialog).
## 4. Backup File Format (v1.0.0)
Code: `src/utils/backup/`. Every export since v1.0.0 is a `_format: 2` envelope:
```json
{
"_app": "ytdescgen",
"_format": 2,
"_type": "backup",
"_schemaVersion": 1,
"_appVersion": "1.0.0",
"_exportedAt": "2026-09-30T14:00:00.000Z",
"data": {
"profiles": { "version": 3, "items": [] },
"settings": { "version": 12, "value": {} }
}
}
```
- `_type`: `backup` | `profiles` | `presets` | `templates` | `settings` | `history` | `logs` | `social`.
- **`backup`**: `_schemaVersion` is the container version (`BACKUP_CONTAINER_VERSION` = 1). `data` holds any of the sections `profiles`, `presets`, `templates`, `history`, `settings`, `draft`, each as `{ version, items }` (lists) or `{ version, value }` (settings, draft), where `version` is the store version the data is in (`SECTION_VERSIONS`). Settings are written without the device-local keys.
- **Single-section export** (`_type: "profiles"`, … — the library tabs and History): `_schemaVersion` is that store's version and `data` is the items (or the value).
- `logs` and `social` files are exports only; they are recognised and refused by restore.
- File names: `ytdescgen-<kind>-YYYY-MM-DD.<ext>` (`datedFileName`, local date). History also exports CSV (`historyToCsv`): UTF-8 with a byte-order mark, CRLF, RFC 4180 quoting, and a `'` prefix on cells a spreadsheet would read as a formula.
### Reading a file (`detect.ts`)
| File | Written by | Read as |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `_format: 2` backup or section export | v1.0.0+ | As recorded. `_format` > 2, or a backup `_schemaVersion` > 1, is refused as "made by a newer version" |
| `{ "_app": "ytdescgen", "_type": "profile" \| "preset" \| "template" \| "settings" \| "history" \| "social", … }` | v0.15 – v0.38 | One section. A `history` file whose rows are log entries is a logs export |
| Bare array | before v0.15 | Section guessed from the first row |
| `{ "ytdescgen-settings": …, "ytdescgen-profiles": …, … }` | The desktop app's old data file; the pre-v0.18 Settings export, which dumped it | Each store key, as `{ state, version }` or bare data |
| Bare settings object (`appLanguage` / `theme`) | Hand-made, pre-v0.18 | Settings, version 0 |
An unknown version is read as 0: every migration step is idempotent, so running all of them on data that didn't need them changes nothing. A section saved by a newer store version than this build's is marked `tooNew` — shown in the preview but not restorable.
### Cleaning (`sanitize.ts`)
1. **Store migration first** — the store's own exported function, from the recorded version. List sections migrate in one pass (so the history de-duplication works across rows); if that throws, row by row, and a row that still throws is dropped instead of failing the file.
2. **Whitelist** — only known fields with the right types; choice fields limited to known ids (video types, languages, genres, graphics options, content warnings, tech notes, …); strings cut to the editor's limits (`PATCH_FIELD_LIMITS`, `FIELD_LIMITS`); map keys `^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$` (at most 100 entries); an id that is not `^[A-Za-z0-9_-]{1,64}$`, or repeats one already taken, is replaced by a new one; at most 5,000 items per section. Nothing is copied by key except the whitelist, so a key like `__proto__`, or `set` (which once overwrote an editor action), cannot reach a store.
3. **Settings** go through `healSettings` and keep this device's local keys. Dropped rows are counted per section and reported.
### Restoring (`restore.ts`)
- `planRestore(file, readCurrentData())` marks every incoming row `new`, `same` or `changed`. A row is matched to an existing item by id, then by content (ignoring `id`, `createdAt`, `updatedAt`), then — for history — by video (`historyKey`). `incomingNewer` compares `updatedAt ?? createdAt`. Settings and the draft are `same` or `changed`.
- The choice (`RestoreChoice`): sections and rows (by default every row that would change something; in Replace mode every row), mode `merge` or `replace`, and for Merge a conflict rule: `newer` (replace the item here only when the incoming copy is newer) or `both` (add the incoming copy with a new id; profiles and templates get a free name such as "Main (2)"; history has no "both" — one entry per video).
- **Replace** makes the section exactly the selected rows; a matched row keeps the id it has here, so nothing pointing at it breaks.
- In either mode, restored history is sorted newest first, de-duplicated per video and cut to the history limit (the incoming limit when settings are restored too).
- `applyRestore` writes every store synchronously, in one step, and returns `undo`, which puts back only the sections that restore changed — edits made afterwards in other sections survive. The desktop app also writes a `…-before-restore` automatic backup first.
### Automatic backups (desktop)
`auto-backup.ts` writes `ytdescgen-backup-YYYYMMDD-HHmm.json` through the `backup_write` command into `<app data>/backups/`: 5 s after start, then 30 s after the last change to profiles, presets, templates, history or settings, at most once every 10 minutes. It skips a write when the data is identical to the last backup (FNV-1a hash of `data`, seeded from the newest backup on start) or when the library (profiles, presets, templates, history) is empty, so a run of empty backups can never push the good ones out. The draft is included but does not trigger a backup. **Back up now** in Settings and the backup before a restore (`…-before-restore.json`) use the same folder and name pattern. The Rust side writes atomically (temporary file + rename) and keeps the newest ten `ytdescgen-backup-*` files; any other name, such as a recovered `ytdescgen-legacy-data.json`, is never deleted automatically.
## 5. GitHub Actions
| Workflow | Runs on | Jobs |
| ------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ci.yml` (CI) | PRs to and pushes on `main` | `check` — the required status on `main`; `sonarcloud` — the SonarCloud scan with `check`'s coverage (pushes on `main`, PRs from this repository except Dependabot's) |
| `security.yml` (Security) | PRs, pushes on `main`, weekly, manual | `dependency-review` (PRs: fails on a newly added high/critical advisory), `workflow-lint` (actionlint + zizmor, `.github/zizmor.yml`), `scorecard` (OpenSSF Scorecard, informational; not on PRs) |
| `compliance.yml` (Compliance) | PRs, pushes on `main` | `reuse` (REUSE licensing via `REUSE.toml`), `pr-title` (Conventional-Commit PR titles with a lower-case subject) |
| `rust.yml` (Rust) | Changes under `src-tauri/`, weekly, manual | `lint-and-test` (`cargo fmt --all -- --check`, `cargo clippy --all-targets --locked -- -D warnings`, `cargo test --locked`, after `npm run build` because `generate_context!` embeds `dist/`), `cargo-deny` (`check advisories licenses sources`, `src-tauri/deny.toml`) |
| `qodana.yml` (Qodana) | PRs to and pushes on `main`, manual | `typescript` — Qodana for JS in native mode (`qodana.yaml`); `rust` — Qodana for Rust, Early Access, in Docker (`src-tauri/qodana.yaml`); both skip without their token (Dependabot and fork PRs) |
| `release-desktop.yml`, `release-android.yml` | `v*` tags, manual with a `tag` input | `verify`, then the builds — see [PACKAGING.md](PACKAGING.md) |
| `announce-release.yml` | Release published, manual | Links the release to an Announcements discussion and posts to Discord |
| `notify-ci-failure.yml`, `notify-release-pipeline.yml` | `workflow_run` | Discord notifications through the maintainer's shared workflows |
| `pages-migration.yml` | Manual only | Publishes `migration-page/` to the old GitHub Pages address until 2026-11-29 |
The `check` job, in order:
```yaml
- run: npm ci --ignore-scripts
# correctness
- run: npm run typecheck # src/
- run: npm run typecheck:all # + tests/, scripts/, worker/, build-plugins/
- run: npm run lint
- run: npm run validate:locales
- run: npm run test:coverage # thresholds in vitest.config.ts
- uses: actions/upload-artifact # coverage/lcov.info, for the sonarcloud job
# consistency
- run: npm run format:check
- run: npm run knip
- run: npm run check:version # the six version fields agree
- run: npm run check:tauri # @tauri-apps/* npm packages and tauri crates on the same major.minor
# licensing
- run: npm run check:licenses # allow-list + THIRD_PARTY_NOTICES.md matches what is installed
- run: npm run check:copyright # NOTICE, REUSE.toml, installer copyright state HEAD's year
# security (advisory: a fresh transitive advisory must not redden unrelated PRs)
- run: npm audit --audit-level=high
continue-on-error: true
# build
- run: npm run build
- run: npm run check:bundle # initial load ≤ 280 KB gzip, no JS chunk > 500 KB raw
- run: npm run cf:check # wrangler deploy --dry-run
```
Then `sonarcloud` (after `check` succeeds):
```yaml
- uses: actions/checkout # fetch-depth: 0 — new code is told from old by git blame
- uses: actions/download-artifact # the coverage report from check
- run: jq -r .version package.json # → sonar.projectVersion
- uses: SonarSource/sonarqube-scan-action # SONAR_TOKEN, sonar-project.properties
```
- **Bundle budget** (`scripts/check-bundle-size.ts`): the initial load is every script, modulepreload and stylesheet `dist/index.html` references, summed gzip — lazy chunks (pages, locales, legal documents) are excluded. The result is printed as a table and added to the job summary.
- **Licences** (`scripts/lib/third-party.ts`): every package bundled into the app must carry an allowed licence (MIT, ISC, Apache-2.0, BSD-2/3-Clause, 0BSD, CC0-1.0, Unlicense, BlueOak-1.0.0, OFL-1.1, Zlib, MPL-2.0), and `THIRD_PARTY_NOTICES.md` is generated (`npm run generate:third-party`) and checked, not hand-written.
- **Copyright years** (`scripts/lib/copyright.ts`, v1.1.0): NOTICE, REUSE.toml and `bundle.copyright` in `tauri.conf.json` must state `copyrightYears(<year of HEAD's commit>)` from `src/config/brand.ts` — "2026", then "2026-2027" from the first commit of 2027. The commit year rather than the clock keeps old commits green; `npm run update:copyright` rewrites the three files. The `/legal` pages' footer uses the same helper at build time.
- **Wrangler dry run** validates `wrangler.jsonc` and bundles the Worker exactly as Workers Builds will, without deploying.
- **SonarCloud** (CI-based; Automatic Analysis is off in the project's settings): `sonar-project.properties` makes the whole repository main code except the tests (`tests/**` and any `src/**/*.test.ts(x)`, analysed as tests) and the binary files (icons, the Gradle wrapper's jar), imports `coverage/lcov.info` and excludes from coverage everything Vitest does not measure (see [Testing Strategy](#6-testing-strategy)). The scan waits for the quality gate — Sonar way: A security, reliability and maintainability ratings, every security hotspot reviewed, ≤ 3 % duplication and ≥ 80 % coverage on new code — and fails the job when it fails. New code is "since the previous version": the job reads `package.json`'s version into `sonar.projectVersion`, so every release starts a new period. The scan runs in a job of its own so that `SONAR_TOKEN` never shares a job with npm packages. PRs from forks and from Dependabot get no repository secrets and skip it; the condition checks the PR author, not `github.actor` (zizmor's `bot-conditions`).
- **Qodana** (v1.6.0; JetBrains, Ultimate licence — the account runs the trial): `qodana.yml` runs Qodana for JS in native mode, on the runner's Node 26 and `node_modules` (`qodana.yaml`), and Qodana for Rust (Early Access, Docker only) on `src-tauri/` (`src-tauri/qodana.yaml`: its `bootstrap` installs the packages `rust.yml` installs, and a stand-in `dist/index.html` lets `generate_context!` expand). Both use the `qodana.recommended` profile and a quality gate of zero problems; every exclusion in a `qodana.yaml` says why. Every run analyses the whole project (`pr-mode: false`). Results go to Qodana Cloud (projects `yt-ts-js` and `yt-rust`), the run's annotations and the `qodana-report-*` artifacts — no PR comment. A `tokens` job checks for `QODANA_TOKEN_TS_JS` and `QODANA_TOKEN_RUST`, which Dependabot and fork PRs don't get, so the analysis is skipped there; the token reaches only the scan step, never the `npm ci` one. Not a required check. When the licence lapses, both jobs fail at the licence check.
- Every workflow declares least-privilege `permissions`, checks out with `persist-credentials: false`, and pins actions by commit SHA (Dependabot keeps the SHAs and version comments current). The exceptions are the actionlint Docker image (pinned by version tag) and the maintainer's own `poli0981/.github` reusable workflows (tracked at `main`, allowed in `.github/zizmor.yml`). CI, Security, Compliance, Rust and Qodana cancel superseded runs through a `concurrency` group, except on `main`, where each commit's result is a record the release process reads back.
**Web deployment is not a GitHub workflow.** Cloudflare Workers Builds builds and deploys the Worker and `dist/` on every push to `main` (preview versions for other branches). The old `deploy-web.yml` (GitHub Pages) is gone; `pages-migration.yml` only serves the moving notice, which hands visitors the data their browser saved on the old address as a `_format: 2` backup file. See [HOSTING.md](HOSTING.md).
**Why these gates exist (v0.35.0).** Several gates were installed and configured long before they ran: `knip` had a `knip.json`, Prettier had a config and a `format` script. Turning them on found real problems at once — most notably that `tsconfig.json` covers only `src/`, so `tests/` and `scripts/` had never been type-checked, which hid three fields missing from the editor → engine parity fixture.
## 6. Testing Strategy
Vitest runs `tests/**/*.test.{ts,tsx}` and `src/**/*.test.{ts,tsx}` in the **node** environment, with `globals: true`: 1131 tests in 54 files at v1.5.2. Directories: `tests/engine`, `store`, `styles` (WCAG AA contrast of the colour tokens), `utils` (backup detect / sanitize / restore, quick entry, validation, the migration page), `worker` (router, rate limits, cookie, Turnstile verdicts, headers, gate language), `build` (legal pages, web-only plugins), `config`, `hooks`, `i18n`, `scripts`. No test renders components: React Testing Library is installed but jsdom is not, so a rendering test would need both jsdom and a `// @vitest-environment jsdom` docblock.
Engine tests build a full `GeneratorInput` and pass a mock translator (`tests/helpers/mock-t.ts`) that reads the real `templates.json` files (en, vi, ja):
```typescript
// tests/engine/title-builder.test.ts
import { describe, it, expect } from "vitest";
import { buildTitle } from "@engine/title-builder";
import { createMockT } from "../helpers/mock-t";
import type { GeneratorInput } from "@engine/types";
function makeInput(overrides: Partial<GeneratorInput> = {}): GeneratorInput {
return {
videoType: "full",
language: "en",
genres: ["action"],
gameName: "Elden Ring",
channelName: "TestChannel",
platform: "steam",
spoilerWarning: false,
matureWarning: false,
storeLinks: {},
social: {},
rig: {},
...overrides,
};
}
describe("buildTitle", () => {
it("generates full gameplay title in English", () => {
const t = createMockT("en");
expect(buildTitle(makeInput(), t)).toBe("Elden Ring — Gameplay No Commentary");
});
it("generates part title with number", () => {
const t = createMockT("en");
const result = buildTitle(makeInput({ videoType: "part", partNumber: "5" }), t);
expect(result).toBe("Elden Ring — Part 5 — Gameplay No Commentary");
});
});
```
`npm run test:coverage` (what CI runs) measures the logic layers with V8 — `src/engine/**`, `src/config/**`, `src/store/**`, `src/utils/**`, `worker/**` (except `worker/index.ts`, the runtime wiring) and `build-plugins/**` — and writes `coverage/lcov.info` for SonarCloud. Components, pages and hooks are checked in the running app, `src/i18n` is i18next set-up and `scripts/` is tooling; SonarCloud would count a file missing from the report as 0 % covered, so `sonar.coverage.exclusions` lists all of them, and a new source folder goes into one list or the other. The run fails below these thresholds — the engine is what the whole app trusts, the Worker is what guards the site:
| Scope | Statements | Branches | Functions | Lines |
| ----------------------------------------- | ---------- | -------- | --------- | ----- |
| `src/engine/**` | 88 % | 85 % | 60 % | 88 % |
| `worker/**` (excluding `worker/index.ts`) | 95 % | 85 % | 95 % | 95 % |
Guard tests worth knowing: `tests/hooks/render-options-parity.test.ts` (settings → engine options), `tests/hooks/generator-input-mapping.test.ts` (editor → engine input), `tests/i18n/locale-registration.test.ts` (language registration in both directions), `tests/config/content-warning-groups.test.ts` and `tech-note-groups.test.ts` (every id in exactly one group, with an editor label and a description line in `_schema.json` — v1.2.0), the genre/tag-pool sync in `tests/engine/tag-generator.test.ts`, `tests/worker/headers.test.ts` (keeps the Worker's baseline headers in step with `public/_headers`), and `tests/styles/contrast.test.ts` (v1.5.1: every text token reaches 4.5:1 on the surfaces in both themes, white text on the `*-solid` fills, 3:1 for marks on `accent`). The Rust side has its own `cargo test` suite (name validation, path rejection, pruning, legacy recovery, dialog filters).
## 7. YouTube Character Limits Reference
| Field | Limit | When exceeded |
| ---------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------- |
| Title | 100 chars | Studio won't save it |
| Description | 5,000 chars | Studio won't save it |
| Tags (total) | 500 chars, counted YouTube's way: quotes around multi-word tags + one comma between tags | Studio won't save the tag list |
| Single tag | 30 chars (`SINGLE_TAG_MAX`) | The generator drops longer tags |
| Hashtags in description | 60 max, 3 shown | First 3 shown above the title |
| Playlist title | 150 chars | Truncated |
| `<` or `>` in title or description | not allowed | Studio rejects the text |
### Enforcement (v1.0.0)
`renderAll` returns `warnings: CharLimitWarning[]` with one entry per field that is **strictly over** its limit (never at the 80 % counter threshold), so a warning is an exact "YouTube will reject this" signal. `src/engine/limits.ts` is the single derivation, shared by the Output page, Batch, the command palette and the Ctrl/⌘+Shift+C shortcut (`useOutputCopy`):
- `getOutputLimitStatus(output)` / `mergeLimitStatus(statuses)` — one output, or several merged (multi-language Copy All, Copy All Batch), keeping the worst offender per field.
- **Per field** (changed in v1.0.0 from all-or-nothing per output): `isFieldOver(status, field)` blocks copying only the field that is over (`useCopyGate` puts the reason in the button's tooltip); the other fields stay copyable.
- **Copy All** copies title + description, plus the tags when the `copyAllIncludesTags` setting is on (`copyAllText`); `isCopyAllBlocked(status, withTags)` blocks it when the title or description is over, or the tags when they are included.
- With the opt-in Strict Mode setting on, `useStrictBlock` blocks every copy while the editor has an error (a saved value that fails validation, or typed text that is invalid and therefore not saved).
- `fieldsWithForbiddenChars(output)` reports a title or description containing `<` or `>`; the Output page shows a warning for each (it does not block copying).
Deliberately not gated by `YT_LIMITS`: thumbnail text and the pinned comment (different surfaces), the Playlist tab (150-character title), and social captions (per-platform limits in `SOCIAL_PLATFORMS`).
## 8. Field Limits (v0.35.0)
`src/config/field-limits.ts` — caps on what can be _typed_, distinct from YouTube's caps on what is _generated_.
```typescript
export const FIELD_LIMITS = {
URL: 200,
EMAIL_FIELD: 320, // 3 addresses; RFC 5321 caps a single one at 254
SHORT_NAME: 100,
LABEL: 300,
LONG_TEXT: 2000,
TIMESTAMPS: YT_LIMITS.DESCRIPTION_MAX,
NUMERIC: 10,
} as const;
```
Values are UTF-16 code units, matching the DOM `maxLength` attribute — an emoji costs 2. Grapheme counting would be more correct but cannot be enforced by the browser, and these are ceilings against absurd input, not a character budget.
`maxLength` only constrains typing and pasting, so `clampField` is applied in `normalizeEditorPatch` (via `PATCH_FIELD_LIMITS`) whenever a profile, preset or template is applied, and backup restore cuts every string to the same limits in `sanitize.ts`.