# CLAUDE.md — YTDescGen ## Project Overview **YTDescGen** generates YouTube titles, descriptions and tags for Gameplay No Commentary channels, in eight languages, with profiles (channel), presets (game) and templates (whole form) to skip repeated data entry. - **Web app**: — a Cloudflare Worker (Turnstile gate + static build), deployed by Cloudflare Workers Builds on every push to `main`. See [docs/HOSTING.md](docs/HOSTING.md). - **Desktop** (Windows / macOS / Linux) and **Android** apps: Tauri 2, released from signed tags. - **Repository**: `github.com/poli0981/youtube-generator` · **License**: Apache-2.0 (`LICENSE`, `NOTICE`, REUSE-compliant). - **Maintainer**: poli0981 (SkullMute). Contacts by purpose: see `src/config/about.ts` and README. **Status: maintenance mode** (since v1.6.0). Don't propose new features. Every change must fall under the policy in [`CONTRIBUTING.md` → Maintenance mode](CONTRIBUTING.md#maintenance-mode): - dependency updates on the regular schedule; - security fixes (a CVE rated high or critical, a serious runtime issue); - major language, runtime or framework upgrades; - bug, UI/UX and accessibility fixes, and adding or removing an option in one of the app's lists (stores, platforms, genres, video types, content warnings, tech notes, GPUs, upscaler / frame-gen modes) when people really need it; - translation fixes (wording that doesn't fit a culture or region, misleading spelling); - Cloudflare / Worker changes the platform forces, website incidents. `.github/workflows/maintenance-triage.yml` closes out-of-scope issues and pull requests (label `out-of-scope`); `feat(options)`, `feat(a11y)` and `feat(i18n)` pull requests stay open. ## Tech Stack | Layer | Technology | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | UI | React 19, TypeScript 7 (strict), Radix primitives (`radix-ui`), Motion (LazyMotion), cmdk, sonner, lucide-react + simple-icons | | Build | Vite 8 (Rolldown); config imports need `.ts` extensions; Node 26 (`.node-version`) | | Type checking | TypeScript 7 `tsc` (`@typescript/native`); `typescript` is an npm alias for `@typescript/typescript6`, the 6.0 API typescript-eslint loads | | Styling | Tailwind CSS 4, CSS-first `@theme` tokens in `src/styles/globals.css` | | State | Zustand 5 + `persist` (localStorage) — the only store on every platform | | Routing | React Router 7 — `BrowserRouter` on the web, `HashRouter` in Tauri | | i18n | i18next + react-i18next, 8 locales (en, vi, ja, es, ko, zh, pt-BR, id); `en` bundled, others lazy | | Desktop / Android | Tauri 2 (Rust) — see `src-tauri/` | | Web hosting | Cloudflare Workers (`worker/`, `wrangler.jsonc`), Turnstile, Web Analytics | | Tests | Vitest (node environment; Worker tests included) | | Quality | ESLint, Prettier, knip, coverage thresholds, bundle budget, licence allow-list, copyright years, REUSE, actionlint/zizmor, cargo fmt/clippy/deny, SonarCloud (CI-based), Qodana (JS + Rust) | ## Project Structure ``` src/ App.tsx, main.tsx # router, providers, start-up effects engine/ # pure template engine — no React, no DOM template-renderer.ts # renderAll(): title + description + tags title-builder.ts # titles (badge position, separator, case, order) title-variants.ts # alternative title shapes description-builder.ts # the description, block by block tag-generator.ts # tag pools, YouTube's tag length count, trimming timeline-parser.ts # timestamps → chapters, YouTube's chapter rules channel-phrase.ts # drops "on {{channel}}" when there is no channel name types.ts # GeneratorInput, CONTENT_WARNINGS, TECH_NOTES, option lists rig-block.ts, limits.ts, social-post-builder.ts, pinned-comment-builder.ts, playlist-builder.ts, endings-format.ts, graphics-vendor.ts, upscale.ts (upscaled in the editor: one rule for title, description and form) config/ # static data: video types, genres, platforms (stores), # social fields/platforms, GPU catalog, rig fields, # content-warning-groups / tech-note-groups (editor groups), # library-fields (profile/preset/per-video field lists), # contact-emails (purpose words), brand (copyright years), # legal, about, field limits, Vietnamese banks, … store/ # Zustand stores; each exports its version + migrate fn editor-store.ts # the draft (EditorData, migrateEditorState, editorDataOf) profile-store.ts, preset-store.ts, template-store.ts, history-store.ts settings-store.ts + settings-heal.ts # settings; healed on every load log-store.ts, pending-invalid-store.ts # typed-but-invalid values, for Strict Mode utils/ backup/ # backup format v2, detect, sanitize, restore (+undo), # collect, desktop auto-backups, start-up recovery library-apply.ts # apply profile/preset/template, next part, start over store-paste.ts # store links pasted anywhere native.ts # typed bridge to the Tauri commands file-ops.ts # save/open text files on every platform validation.ts, url-extractors.ts, log-storage.ts, … hooks/, components/, pages/, i18n/, styles/ worker/ # Cloudflare Worker: gate, cookies, headers, rate limits, routing build-plugins/ # legal pages at build time; web-only extras src-tauri/src/ # lib.rs (plugins, tray), storage.rs (name-only file # commands), file_dialog.rs (native Save/Open) migration-page/ # moving notice for the old GitHub Pages address (until 2026-11-29) tests/ # engine, store, utils, worker, build, i18n, config, hooks, scripts scripts/ # locale validation + generator, version sync, Tauri versions, # bundle budget, licences/third-party notices, copyright # years, brand assets docs/ # DEVELOPMENT, HOSTING, ARCHITECTURE, FEATURES, ROADMAP, # TECH-SPEC, I18N, PACKAGING, CONTENT-INVENTORY i18n/vi/ # Vietnamese: DEVELOPMENT, CONTENT-INVENTORY, DISCLAIMER assets/brand/ # logo sources: every icon and the link-preview card come from them public/ # static web files (_headers, icons, manifest, 404, robots, sitemap) LICENSES/ # license texts for REUSE ``` ## Coding Conventions ### TypeScript - Strict mode; no `any` — use `unknown` + type guards. - Prefer `interface` for object shapes; `as const` for static config arrays. - `src/` is typed against `lib` ES2022 — the browsers' floor (Chrome 111, Safari 16.4, Firefox 114), because Vite never polyfills. Don't reach for newer built-ins in the app without raising that floor; tests, scripts, worker and build plugins get ES2025 (`tsconfig.check.json`). `target` is ES2025 (ES2026 waits for TypeScript 7.1). - Erasable syntax only (`erasableSyntaxOnly`, `verbatimModuleSyntax`): no enums, namespaces or parameter properties; `import type` for types. - React 19: `ref` is an ordinary prop — no `forwardRef`. - Regexes must stay linear (SonarCloud S8786): no unbounded quantifier that can restart inside its own run (`\s+$`, a leading `\s+` in an unanchored pattern, `\s*` next to `\s*`) — trim first, anchor, bound the run, or use a loop. ### React - Function components only; shared logic in `use*` hooks. - Pages are lazy-loaded; keep the Editor (landing page) light — the **initial load budget is 280 KB gzip** (`npm run check:bundle`), no chunk over 500 KB raw. - Read store slices with selectors; avoid prop drilling beyond two levels. ### Naming - Files: `kebab-case.ts`, components `PascalCase.tsx`; stores `use[Name]Store`; constants `UPPER_SNAKE_CASE`. ### Styling - Tailwind utilities and the design tokens (`bg-surface-1`, `text-text-muted`, `accent`, …) — no hard-coded colours, no inline styles. - Dark by default, light via class; touch targets grow on coarse pointers (`pointer-coarse:`), nothing clickable under 24 px. - Contrast is WCAG AA in both themes and `tests/styles/contrast.test.ts` checks every token: text tokens on surfaces, white text only on the `*-solid` fills (`bg-accent-solid`, `bg-danger-solid`), never on `bg-accent`. - Focus: the global `:focus-visible` outline; a control that swaps it for a ring uses `outline-hidden` (stays visible in forced colours), not `outline-none`. - Watch Tailwind 4 specificity: a base `inline-flex` beats a plain `hidden` — wrap responsive visibility in an element. ### i18n - Every user-visible string goes through `t()`; UI strings in `ui.json`, generated text in `templates.json`. - New keys go into **all 8 locales** and `_schema.json`; `npm run validate:locales` must pass. - No plural suffixes (`_one`/`_other`) — the key sets must match across locales; write count-neutral text. ### State - Stores are persisted with Zustand `persist`; a shape change bumps the store's exported version and adds a step to its exported migrate function (backups replay the same steps). Steps must be idempotent. - Settings are healed on every load (`healSettings`); consent and UI-state fields are device-local and never exported. ### Engine - Pure functions only: typed input → string. No React, clipboard, storage or DOM; the year and other environment values come from the caller. ## Key Design Decisions 1. **The engine is framework-agnostic** (`src/engine/` has no React imports). 2. **i18n covers the UI and the generated text**, as separate namespaces. 3. **Profiles vs presets vs templates**: profile = channel (rarely changes), preset = game (reused across parts), template = the whole form. The field lists live in `src/config/library-fields.ts`. 4. **Tags are generated**, then trimmed to YouTube's own length count. 5. **Your data stays on your device.** localStorage is the only store; backups are files the user controls (plus automatic backups in the desktop app's data folder). 6. **The desktop webview never names a path**: Rust commands take file names under the app data folder or open the native dialog themselves. Blocking work in an `async` command (a dialog, file I/O) goes through `tauri::async_runtime::spawn_blocking` — SonarCloud flags it otherwise (`rust:S7493`). 7. **The web app is gated** by Turnstile, verified server-side in the Worker; the gate fails open if its secret is missing. ## Development Commands ```bash npm install npm run dev # Vite dev server (http://localhost:5173) npm run build # typecheck + production build npm run test:run # all tests (npm test = watch mode) npm run test:coverage # with coverage thresholds npm run typecheck # src npm run typecheck:all # src + tests + scripts + worker + build plugins npm run lint && npm run format:check npm run knip # unused files/exports/dependencies npm run validate:locales npm run check:bundle # after build: initial load / chunk budget npm run check:licenses # licence allow-list + THIRD_PARTY_NOTICES in sync (generate:third-party fixes) npm run check:copyright # NOTICE, REUSE.toml, installer copyright = HEAD's year (update:copyright fixes) npm run check:version # the six version fields agree npm run check:tauri # @tauri-apps/* and tauri crates on the same major.minor npm run cf:dev # wrangler dev (copy .dev.vars.example to .dev.vars — test keys only) npm run cf:check # wrangler deploy --dry-run npm run tauri:dev # desktop app against the dev server npm run tauri:build # desktop installers npm run generate:locale # scaffold a new locale folder from en (-- --lang xx) npm run generate:brand # favicon, PWA icons, link-preview card from assets/brand/ # src-tauri/: cargo fmt --check · cargo clippy --all-targets --locked -- -D warnings · cargo test ``` ## Git Workflow - `main` only: feature branches (`feat/…`, `fix/…`, `docs/…`, `chore/…`) → PR → `main`. Every merge to `main` deploys the web app. - Commit and PR-title format: `type(scope): message` (`feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`) — CI checks PR titles, and the message must start with a lower-case letter (`feat(editor): warnings for AI…`, not `feat(editor): AI…`). - Commits and release tags are GPG-signed; never bypass signing or hooks. - Required checks: `check`, `dependency-review`, `workflow-lint`, `reuse`, `pr-title`. ## Releases - Bump the version in all six places: `package.json`, `package-lock.json` (×2), `src-tauri/tauri.conf.json`, `src-tauri/Cargo.toml`, `src-tauri/Cargo.lock` (`npm run check:version`), and add a `CHANGELOG.md` entry. - Push a signed tag `vX.Y.Z` → the release workflows verify, build the desktop and Android artifacts and create a **draft** release. The maintainer publishes it. ## Important Notes for Claude Code - Run the gates before committing: `typecheck`, `typecheck:all`, `lint`, `format:check`, `test:run`, `knip`, `validate:locales`, `check:version`, `check:tauri`, `check:licenses`, `check:copyright`, `build` + `check:bundle`; `cargo fmt/clippy/test` when `src-tauri/` changes. In the first commit of a new year, `npm run update:copyright` (CI's `check:copyright` fails until then). A dependency change can make `check:licenses` fail: `npm run generate:third-party` rewrites the notices, and a new direct crate in `src-tauri/Cargo.toml` that isn't Tauri's needs its license in `OTHER_CRATES` (`scripts/lib/third-party.ts`). - New contact-email purpose words: `src/config/contact-emails.ts` (lower-case; a test keeps every locale's example address valid). - New language: follow `docs/I18N.md` (register it, both namespaces, tag pools, `channel-phrase.ts` patterns, browser detection). - New genre: `src/config/genres.ts` + its tag pool in `src/engine/tag-generator.ts` (a test keeps them in sync). - New video type: `src/config/video-types.ts` + every `templates.json` (titles, intros, pinned-comment greetings). - New content warning / tech note: the id in `CONTENT_WARNINGS` / `TECH_NOTES` (`src/engine/types.ts`), a group in `src/config/content-warning-groups.ts` / `tech-note-groups.ts`, the editor label (`ui.json`) and description line (`templates.json`) in all 8 locales and `_schema.json` — tests fail on any gap — and the row in `docs/CONTENT-INVENTORY.md` (+ vi). Don't repeat a fact that has its own field (language patch, game version, difficulty, the Video settings upscaler). - New store platform: `src/config/platforms.ts` (URL pattern, `tagName`), optionally a name extractor in `src/utils/url-extractors.ts`. - New upscaler / frame-gen option: the id in `src/config/graphics-settings.ts`, the vendor's list in `src/engine/graphics-vendor.ts`, the editor label (`editor.upscaleQuality.` / `editor.frameGenMultiplier.`, `ui.json`) and the description label (`description.graphics.upscale|frameGen.`, `templates.json`) in all 8 locales and `_schema.json` — `tests/engine/graphics-vendor.test.ts` fails on a gap. A new id only widens the lists (no store bump); a new field does need one. - UI changes follow the accessibility checklist in `ACCESSIBILITY.md` (#for-contributors): keyboard, names via `Field` / `IconButton`, announced errors, tokens only, reduced motion, 24 px targets. Generated text gets `lang` (the output language); pages name themselves with `useDocumentTitle`, which `RouteAnnouncer` reads out. Update ACCESSIBILITY.md (+ `docs/i18n/vi/`) when what it promises changes. - Never commit `note.txt`, `warning.txt` or `__pycache__/`; never put real secrets in files (`.dev.vars` holds Cloudflare's public Turnstile test keys only). - SonarCloud (project `poli0981_youtube-generator`) is CI-based: the `sonarcloud` job in `ci.yml` scans every PR from this repository and every push to `main`, with the coverage from `check`; settings in `sonar-project.properties`; Automatic Analysis is off. Keep it at 0 open issues and the quality gate (Sonar way: A ratings, reviewed hotspots, ≤ 3 % duplication, ≥ 80 % coverage on new code) green — the job fails with the gate. Coverage covers what `coverage.include` in `vitest.config.ts` lists (the logic layers); everything else is in `sonar.coverage.exclusions`, because a file missing from the LCOV report counts as 0 % — a new source folder goes into one list or the other. The version passed to the scanner starts each release's new-code period. Fork and Dependabot PRs skip the scan (no `SONAR_TOKEN`). Check a PR with `https://sonarcloud.io/api/issues/search?componentKeys=poli0981_youtube-generator&pullRequest=&resolved=false` and its gate with `https://sonarcloud.io/api/qualitygates/project_status?projectKey=poli0981_youtube-generator&pullRequest=`. Workflows install with `npm ci --ignore-scripts` and call local binaries (`npm run …`), never `npx` for a package that isn't installed. - Qodana (`.github/workflows/qodana.yml`) runs on every PR and push to `main`: job `typescript` is Qodana for JS in native mode (`qodana.yaml`, Cloud project `yt-ts-js`, secret `QODANA_TOKEN_TS_JS`), job `rust` is Qodana for Rust, Early Access, in Docker on `src-tauri/` (`src-tauri/qodana.yaml`, project `yt-rust`, secret `QODANA_TOKEN_RUST`). Both gate on zero problems: fix a finding, or exclude it in the `qodana.yaml` with a comment saying why. Both skip without their token (Dependabot and fork PRs). It needs an Ultimate licence (currently the trial): when it lapses both jobs fail at the licence check. - TypeScript bumps may be manual: `@typescript/native` (`npm:typescript@^7`) and `typescript` (`npm:@typescript/typescript6@^6`) are npm aliases Dependabot may not follow. Stop the dev server before `npm ci` on Windows — it locks native modules (EPERM). - The Cloudflare dashboard, publishing releases and repository settings are the maintainer's; ask before touching them.