Compare commits

...
74 Commits
Author SHA1 Message Date
poli0981andClaude Opus 5.5 886d25b588 fix(quality): clear the 44 open SonarCloud issues
Regexes with super-linear backtracking (S8786 x16) are rewritten to stay
linear on long runs; each new pattern gives the same results as the old one
on 150k-450k fuzzed inputs (except where noted) and finishes adversarial
50k-character inputs in under 3 ms:
- tag-generator QUALIFIER_SUFFIX_RE starts just before a `:`/space run
  (`(^|[^:\s])…` + "$1"), never inside one
- timeline-parser matches `line.trimEnd()` with a greedy label, and renders
  with trimEnd(); cleanCpuName collapses whitespace before the patterns
- editor-store endings, Google Play urlPattern (lookahead for `id=`),
  channel-phrase punctuation, SPDX OR/AND split, legal-docs slug and link
  stripping (link text/URL may not contain `[`), base64url padding, and a
  loop for trailing slashes in the worker router

Others:
- S2871: sorts take the shared code-unit comparator (same order as before;
  THIRD_PARTY_NOTICES is unchanged)
- S4822: ErrorBoundary catches the logger import with .catch(), which a
  try/catch never could
- S3516: migrateProfilesState returns a new object
- S7773: Number.parseInt (x10)
- S9379: Modal takes an initialFocusRef (Radix onOpenAutoFocus), so the
  shortcut search box gets focus without an autoFocus attribute
- S2245: generateId drops the Math.random fallback; getRandomValues exists
  everywhere the app runs, and a non-random ID is worse than an error
- S4036: NOSONAR on the dev script's `git` call (PATH lookup by design)
- S6505/S8543: every workflow installs with `npm ci --ignore-scripts`, and CI
  runs `npm run cf:check` instead of `npx wrangler …`
- S6358: Android sets allowBackup="false" — app data is no longer copied to
  Google Drive backups; Backup & Restore moves it to a new phone

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 15:05:16 +07:00
poli0981 abfcd96eb5 Merge pull request #211 from poli0981/refactor/react-19-refs
refactor(ui): take refs as a prop instead of forwardRef
2026-10-22 15:05:08 +07:00
poli0981andClaude Opus 5.5 52fc677ce5 refactor(ui): take refs as a prop instead of forwardRef
React 19 passes `ref` to function components as an ordinary prop, and the
React team has said forwardRef will be deprecated in a future release.
Button, IconButton, Input, Select and Textarea become plain function
components whose props extend ComponentProps<"button" | "input" | …>,
which already carries `ref`; each passes it on (Button to both Slot.Root
and <button>; IconButton through its props to Button). Their displayName
lines go too: the function names show in DevTools.

IconButton and RigEditor import the ReactNode type instead of reaching for
the global `React` namespace.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 15:03:13 +07:00
poli0981 e3d86ea6cd Merge pull request #210 from poli0981/chore/deps-2026-10-22b
chore(deps): fold the newer Dependabot bumps; fix the @vitest/mocker alerts
2026-10-22 15:03:04 +07:00
poli0981andClaude Opus 5.5 1e3e20c6d4 chore(deps): fold the newer Dependabot bumps; fix the @vitest/mocker alerts
- vitest + @vitest/coverage-v8 4.1.12: @vitest/mocker 4.1.12 fixes alerts
  #44 and #45 (manual-mock code injection, Windows redirect traversal).
  Dependabot's security update could not land on its own: vitest 4.1.11
  pins @vitest/mocker 4.1.11.
- i18n: i18next 26.4.5
- tauri: @tauri-apps/api 2.12.4, plugin-opener 2.7.2, cli 2.12.3
- ui: lucide-react 1.57.0, radix-ui 1.8.1
- lint-and-format: typescript-eslint 8.71.2
- build-tooling: postcss 8.5.30
- actions: setup-java 6.1.0, zizmor-action 0.7.1
- THIRD_PARTY_NOTICES regenerated

Supersedes #197 #198 #199 #206 #207 #208.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 15:01:16 +07:00
poli0981 4019c2151e Merge pull request #209 from poli0981/chore/typescript-7
chore(typescript): move to TypeScript 7 with an ES2025 target
2026-10-22 15:01:08 +07:00
poli0981andClaude Opus 5.5 ad523ea0fb chore(typescript): move to TypeScript 7 with an ES2025 target
TypeScript 7.0 is the native compiler and ships no JavaScript API, which
typescript-eslint still needs. Install both, as Microsoft documents it:
- "@typescript/native": "npm:typescript@^7.0.2" gives `tsc` = 7.0
- "typescript": "npm:@typescript/typescript6@^6.0.2" gives the 6.0 API
  that typescript-eslint loads (its peer range stops below 6.1), and `tsc6`
CI fails if `tsc` ever resolves to TypeScript 6 (@typescript/old, pulled in
by the 6.0 package, ships a `tsc` too).

tsconfig.json (src):
- target ES2025: the newest year TypeScript 7.0, esbuild and Vite all know
- lib ES2022 + DOM: the browser floor (Vite's baseline-widely-available,
  Chrome 111 / Safari 16.4 / Firefox 114), because nothing polyfills
- baseUrl removed (gone in 7.0; paths were already relative), DOM.Iterable
  dropped (merged into DOM), `types: []` spelled out, erasableSyntaxOnly and
  verbatimModuleSyntax on (both clean)
tsconfig.check.json: lib ES2025 for tests, scripts, worker and build plugins.

Platform floor: the Tauri build no longer lowers to es2020; it shares the
web build's baseline (the stylesheet already needed Chromium 99+ /
Safari 15.4+). macOS minimumSystemVersion is 11.0 (the build is arm64).

Also: eslint.config.js uses ESLint's defineConfig (tseslint.config is
deprecated); THIRD_PARTY_NOTICES names the real package behind an npm
alias, sorted with a shared code-unit comparator (src/utils/sort.ts);
Dependabot groups typescript + @typescript/*; a test's typed-array
annotation follows TypeScript 7's lib.dom.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 14:48:21 +07:00
poli0981 706a9c89a2 Merge pull request #205 from poli0981/chore/node-26
chore(node): move the toolchain to Node 26
2026-10-22 14:47:28 +07:00
poli0981andClaude Opus 5.5 3c53fd4fe5 chore(node): move the toolchain to Node 26
- .node-version 22 -> 26 (CI, the release workflows and Workers Builds
  read it; Workers Builds also has NODE_VERSION=26 set)
- package.json engines: node >=26
- vitest: run workers with --no-experimental-webstorage. Node 25+ defines
  a global `localStorage` that is undefined without --localstorage-file;
  zustand's persist only falls back to memory when reading the storage
  throws, so every store `set` crashed on undefined.setItem (39 tests in
  4 files). Without Web Storage the stores fall back as they did on 22.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 14:43:32 +07:00
poli0981 eb96954d21 Merge pull request #204 from poli0981/chore/deps-2026-10-22
chore(deps): fold the open Dependabot bumps; fix the vite launch-editor alerts
2026-10-22 14:43:19 +07:00
poli0981andClaude Opus 5.5 701b661a0d chore(deps): fold the open Dependabot bumps; fix the vite launch-editor alerts
- i18n: i18next 26.4.4
- tauri: @tauri-apps/api 2.12.3, plugin-opener 2.7.1, cli 2.12.2
  (crates stay on 2.12)
- ui: lucide-react 1.55.0, radix-ui 1.8.0
- lint-and-format: eslint 10.12.0, knip 6.41.0, prettier 3.9.10,
  typescript-eslint 8.71.1
- build-tooling: @vitejs/plugin-react 6.1.2, marked 18.1.1,
  postcss 8.5.29, vite 8.3.4 (alerts #41-#43: launch-editor, fixed in 8.3.3)
- actions: setup-node 7.1.0, rust-toolchain 683b588, upload-artifact 7.0.2,
  scorecard 2.5.0
- THIRD_PARTY_NOTICES regenerated

Supersedes #197 #198 #199 #200 #201 #202 #203.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 14:40:53 +07:00
poli0981andClaude Opus 5.5 9901ed844b chore(deps): fold the open Dependabot bumps into one update; fix sharp and source-map-js alerts (#196)
- ui: lucide-react 1.52.0, motion 13.5.1, radix-ui 1.7.0
- tauri: @tauri-apps/api + cli 2.12.1 (crates stay on 2.12)
- i18n: react-i18next 17.0.16
- wrangler 4.149.0, which brings sharp 0.35.5 (alert #40) and
  shares the top-level esbuild instead of nesting its own
- source-map-js 1.2.2 (alert #39)
- THIRD_PARTY_NOTICES regenerated

Supersedes #190 #191 #192 #193 #194.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 05:34:06 +07:00
poli0981 7f56a5f22a Merge pull request #195 from poli0981/dependabot/github_actions/actions-cfc9a39341
ci: bump dtolnay/rust-toolchain from 7e38f4b43b4db5c8dd498af069a4f6196df1d067 to e2a55d2ffb04f378e9626c28d38b36d230d1e12f in the actions group
2026-10-16 05:21:43 +07:00
dependabot[bot] 1aebe75501 ci: bump dtolnay/rust-toolchain
Bumps the actions group with 1 update: [dtolnay/rust-toolchain](https://github.com/dtolnay/rust-toolchain).


Updates `dtolnay/rust-toolchain` from 7e38f4b43b4db5c8dd498af069a4f6196df1d067 to e2a55d2ffb04f378e9626c28d38b36d230d1e12f
- [Release notes](https://github.com/dtolnay/rust-toolchain/releases)
- [Commits](https://github.com/dtolnay/rust-toolchain/compare/7e38f4b43b4db5c8dd498af069a4f6196df1d067...e2a55d2ffb04f378e9626c28d38b36d230d1e12f)

---
updated-dependencies:
- dependency-name: dtolnay/rust-toolchain
  dependency-version: e2a55d2ffb04f378e9626c28d38b36d230d1e12f
  dependency-type: direct:production
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-10-13 14:22:49 +00:00
poli0981 3c9e52b541 Merge pull request #188 from poli0981/docs/v1.2.0
docs: v1.2.0 — sync docs and templates, changelog; bump to 1.2.0
2026-10-12 22:14:55 +07:00
poli0981andClaude Opus 5.5 e50d324d0a docs(changelog): v1.2.0 — bilingual lines, cargo checks
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 22:12:28 +07:00
poli0981andClaude Opus 5.5 bc27ce95d5 docs: v1.2.0 — sync docs and templates, changelog; bump to 1.2.0
Docs had drifted since 1.0.0: README missed the 1.1.0 features and
showed an Android step that overwrites the committed Gradle project;
ROADMAP, PACKAGING, ARCHITECTURE and TECH-SPEC still described 1.0.0;
CONTRIBUTING and the PR template listed half the gates; SECURITY named
1.0.x; CLAUDE.md's structure and gate list were out of date.
webapp/TAURI.md (Node 25, no .rpm) is folded into PACKAGING and removed.

Also: purpose-word validation documented in ARCHITECTURE, two stale code
comments (about.ts, vietnamese-banks.ts), .gitignore for the
maintainer's local note files, and the CHANGELOG entry.

Six manifests bumped 1.1.0 -> 1.2.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 22:10:58 +07:00
poli0981 f2e6e21555 Merge pull request #187 from poli0981/chore/legal-sync
chore(legal): sync notices, REUSE and privacy with the code
2026-10-12 22:06:40 +07:00
poli0981 eee07f9390 Merge pull request #186 from poli0981/feat/ai-content-warnings
feat(editor): warnings for AI-generated game content, plus three more disclosures
2026-10-12 22:03:23 +07:00
poli0981andClaude Opus 5.5 261457ae38 chore(legal): sync notices, REUSE and privacy with the code
- THIRD_PARTY_NOTICES said the app uses the operating system's fonts; it
  bundles Inter and JetBrains Mono (OFL-1.1). The Rust table claimed to
  list the direct dependencies of src-tauri but only took names starting
  with "tauri", so serde was missing. The generator now reads Cargo.toml's
  dependency tables and fails on a crate whose license it doesn't know.
- REUSE.toml credited the Gradle wrapper to the project; it is Gradle's
  ("the original author or authors", Apache-2.0).
- The Privacy Policy lists the session-only ytdescgen-chunk-reload flag
  next to the localStorage keys. Not a material change, so the terms
  version stays 2; the Effective date moves.
- DISCLAIMER (+ vi) pointed at a THIRD_PARTY_NOTICES section by an old
  heading.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 22:00:02 +07:00
poli0981andClaude Opus 5.5 7a81690974 feat(editor): AI-generated content warnings and three more disclosures
A new content-warning group, AI-generated content (7): general, art /
visuals, voices, music / sound, text / dialogue, generated live while
playing, and disclosed by the developer. It follows Steam's AI
disclosure (made with AI during development vs generated live while the
game runs); machine translation stays the Language patch field.

Also simulated gambling and in-game purchases (ESRB / PEGI descriptors
with no warning so far), and a tech note for upscaling / frame-generation
artifacts (which upscaler was on is already the Video settings line).

A test now fails when a content warning or tech note has no editor label
or description bullet in _schema.json, and so in any locale; tech notes
get the group-parity test content warnings already had.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 21:56:53 +07:00
poli0981 2173671e91 Merge pull request #184 from poli0981/docs/v1.1.0
docs: v1.1.0 — changelog and docs; bump to 1.1.0
2026-10-03 09:20:28 +07:00
poli0981andClaude Opus 5.5 5fb454a943 docs: v1.1.0 — changelog and docs; bump to 1.1.0
- CHANGELOG: v1.1.0 (copyright email and purpose words, Hide scrollbars,
  installer copyright string, copyright-year check, the rust-toolchain pin)
- FEATURES: the four split contact lines, purpose words, the Settings row,
  the profile's emails
- TECH-SPEC / ARCHITECTURE: editor store v20, hideScrollbars without a
  settings bump, theme-init and App applying the scrollbar class, the new
  CI step and scripts
- DEVELOPMENT (en + vi), CLAUDE.md: check:copyright / update:copyright
- I18N: 1,253 UI + 574 template keys per locale
- six manifests 1.0.0 -> 1.1.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 09:16:03 +07:00
poli0981 1c32f33769 Merge pull request #182 from poli0981/chore/copyright-years
chore(legal): keep copyright years current, checked in CI
2026-10-03 09:15:52 +07:00
poli0981 0f884f3397 Merge pull request #181 from poli0981/feat/hide-scrollbars
feat(settings): option to hide scrollbars
2026-10-03 09:15:29 +07:00
poli0981 87ff484136 Merge pull request #180 from poli0981/feat/purpose-emails
feat(editor): copyright email and purpose words for split contact emails
2026-10-03 09:15:23 +07:00
poli0981andClaude Opus 5.5 38f47add8b chore(legal): keep copyright years current, checked in CI
Every notice already says 2026, which is right: the first commit is from
2026-04-07, so there is no 2025 to fix and no 2025-2026 range to claim.
What was missing is anything keeping the years current.

- src/config/brand.ts: COPYRIGHT_START_YEAR and copyrightYears(), "2026"
  now and "2026-2027" from the first commit made in 2027
- npm run check:copyright (CI, next to check:licenses) holds NOTICE,
  REUSE.toml and the installers' copyright string to HEAD's commit year,
  not the clock, so old commits stay green; npm run update:copyright
  rewrites them
- tauri.conf.json gains bundle.copyright, so the .exe/NSIS, macOS and
  Linux packages stop shipping an empty copyright field
- the /legal pages' footer prints the same range at build time

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 09:13:52 +07:00
poli0981andClaude Opus 5.5 c46c7a4588 feat(settings): option to hide scrollbars
Settings › Appearance › Hide scrollbars removes every scrollbar in the
app; the mouse wheel, touchpad, touch and keyboard still scroll.

- hideScrollbars setting (default off), coerced to a boolean by
  healSettings; portable like the theme, no store version bump (the heal
  back-fills it, and older builds can still read newer backups)
- applied as <html class="hide-scrollbars">: theme-init.js before first
  paint, main.tsx at boot, an App store subscription afterwards (the
  toggle, a restored backup and its undo)
- unlayered CSS beats .scrollbar-thin: scrollbar-width: none on every
  element for Chromium and Firefox, ::-webkit-scrollbar for the WebKit
  webviews on macOS and Linux
- labels in 8 locales

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 09:13:48 +07:00
poli0981andClaude Opus 5.5 116dc1c7e6 feat(editor): copyright email and purpose words for split contact emails
With "Split contact email by purpose" on, the contact block gains a fourth
line, Copyright / DMCA, and every purpose address has to say what it is
for: the part before @ must contain one of the field's words
(src/config/contact-emails.ts), matched case-insensitively anywhere in it,
so name+dmca@gmail.com works. A missing word is an error like a malformed
address: the value is not saved and Strict Mode blocks. Addresses saved
before the rule are flagged, never rewritten.

- validatePurposeEmails() on top of validateEmails(); Strict Mode and the
  three purpose inputs use it, the general Contact field does not
- copyrightEmail: EditorData, defaults, field cap, PROFILE_FIELDS (optional
  on Profile, like the v1.0.0 additions); editor store v19 -> v20
- description: "©️ Copyright / DMCA: …" after the game-keys line, 8 locales
- help texts list each field's words; the Spanish examples now carry one
  (sponsors@, games@), and a test keeps every locale's examples valid

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 09:13:45 +07:00
poli0981 1252d88883 Merge pull request #183 from poli0981/ci/rust-toolchain-pin
ci: pin dtolnay/rust-toolchain to a master commit
2026-10-03 09:13:32 +07:00
poli0981andClaude Opus 5.5 d24bf1192e ci: pin dtolnay/rust-toolchain to a master commit
workflow-lint started failing on every pull request: zizmor reports
impostor-commit for dtolnay/rust-toolchain@6bed076 (# stable). The
action's `stable` branch is regenerated from master (last on 2026-10-01),
so the commit pinned from it no longer belongs to the repository's
history, and the `# stable` comment no longer matches either.

Pin 7e38f4b, the current master head (the regenerated `stable` is that
commit plus a default toolchain), in rust.yml and both release workflows.
Master keeps its history, and every step already passes
`toolchain: stable`, which master's action.yml requires.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 09:09:00 +07:00
poli0981 e7d16d8873 Merge pull request #178 from poli0981/docs/v1.0.0
docs: v1.0.0 — changelog, contacts, hosting guide, refreshed docs; bump to 1.0.0
2026-09-30 23:31:08 +07:00
poli0981andClaude Opus 5.5 5b61533465 docs: refresh the technical and feature docs for v1.0.0
Every claim checked against the code.

- TECH-SPEC: current configs (React 19 / Vite 8 / Tailwind 4, the web vs
  Tauri build), Cloudflare hosting and the Worker, store versions and
  migrations, the backup format, engine rules added in 1.0, CI as it is.
- ARCHITECTURE: layers, web vs Tauri, routing and start-up, the engine,
  state, backup & restore, web delivery, the hardened Tauri shell.
- PACKAGING: tauri.conf and capabilities as shipped, the eleven
  name-only commands and what they guard, where desktop data lives, the
  first-start recovery of pre-1.0 files, the release workflows; the
  auto-update flow that never existed is gone.
- FEATURES, CONTENT-INVENTORY (+ vi): recounted from config (42 genres,
  16 store entries, 22 social/donate fields, 7 cross-post platforms,
  37 Vietnamese banks); shortcuts that never existed removed.
- DEVELOPMENT (+ vi): main-only branching, every npm script, Rust 1.90,
  Cloudflare local dev with test keys, the Rust checks.
- I18N: both namespaces and all seven registration places, including
  the check page's own language list; ROADMAP: v1.0.0 shipped + backlog.
- DISCLAIMER (vi): eight languages. The locale template script now
  prints the full registration checklist; a stale comment in main.tsx
  about the removed settings file is corrected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 23:29:10 +07:00
poli0981andClaude Opus 5.5 bca589e169 docs: v1.0.0 — changelog, README, contacts, hosting guide, CLAUDE.md; bump to 1.0.0
- CHANGELOG: the v1.0.0 entry (moving house, new interface, data fixes,
  backup & restore, faster entry, catalogs, desktop hardening, CI).
- README: the web app at ytgenerator.stream, what moved from GitHub
  Pages, current features, privacy as it is now (Cloudflare delivery,
  Turnstile, cookieless analytics on the web only), contacts by purpose;
  the dead Discord invite and the old email are gone.
- docs/HOSTING.md (new): Worker routing, cookies, headers, secrets,
  one-time dashboard settings, local dev, previews and rollback.
- CLAUDE.md rewritten for the real stack, layout, commands and rules.
- CONTRIBUTING / PR template / issue templates: main-only branching,
  the required checks, 8 locales, Android and current versions; issue
  links to security advisories, the wiki, Discord and poli0981.dev/links.
- DISCLAIMER (+ Vietnamese), NOTICE: current model disclosure and the
  copyright / DMCA contacts. PRIVACY: backup locations and the moving
  notice on the old address.
- Version 1.0.0 in package.json, package-lock.json, tauri.conf.json,
  Cargo.toml and Cargo.lock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 23:06:01 +07:00
poli0981 6e071b65db Merge pull request #176 from poli0981/chore/pages-migration
ci(pages): moving notice on the old GitHub Pages address
2026-09-30 22:36:12 +07:00
poli0981 6af4b067d4 Merge pull request #175 from poli0981/feat/quick-entry
feat(editor): quick start, next part, store links pasted anywhere, more stores and platforms
2026-09-30 22:34:06 +07:00
poli0981andClaude Opus 5.5 dc8fc396f1 ci(pages): moving notice on the old GitHub Pages address
poli0981.github.io/youtube-generator still serves v0.38 to old bookmarks,
and the data people saved there can't follow to ytgenerator.stream on its
own (browser storage belongs to a site). A single static page replaces it:

- reads the ytdescgen-* stores this browser saved on the old address and
  downloads them as a backup file in the new format (Settings › Restore
  reads it: migrations, the preview and Undo apply as for any backup);
- points to ytgenerator.stream, in English or Vietnamese;
- noindex, canonical to the new site, and a 404 copy for old deep links.

pages-migration.yml deploys it by hand (workflow_dispatch, pinned
actions, job-scoped permissions). The page, the workflow and the
github-pages environment go on 2026-11-29.

A regression test feeds the page's exact output through the restore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 22:33:29 +07:00
poli0981 1e42a2975b Merge pull request #174 from poli0981/feat/backup-restore
feat(data): backup & restore with preview and undo; desktop files by name only
2026-09-30 22:30:01 +07:00
poli0981andClaude Opus 5.5 3c985a07d6 feat(editor): quick start, next part, store links pasted anywhere, more stores and platforms
Editor:
- Quick start at the top: pick the channel profile and the game preset
  (remembered per device); replacing fields that hold something else asks
  first, everything offers Undo; "Update profile / preset" appears when the
  editor drifts from the one in use.
- Next part (number + 1) and New video (same game) clear what belonged to
  the last video: boss, timestamps, endings, pinned comment, sponsor…
  Applying a preset for another game or a template does the same first.
- Start over replaces Clear Draft and keeps the channel (profile fields);
  a new draft starts in the Default Output Language (it was always "en").
- A store link pasted anywhere — the page, the Game name field, another
  store's field — lands in the right store field, sets the platform for a
  game's first link and names the game from it (Roman numerals and
  well-known possessives restored: "Final Fantasy VII", "Baldur's Gate 3").
  Steam links keep their name slug and drop tracking parameters.
- Game-name suggestions from presets and history.

Catalogs:
- Stores: EA app, Ubisoft, Battle.net, Google Play, App Store, Meta Quest.
- Social: YouTube, Threads, Kick, Reddit, Bilibili; "X (Twitter)" with the
  X mark; threads.net and youtu.be links accepted.
- Cross-posting: YouTube Shorts, X (counted the way X counts — CJK,
  Vietnamese letters with diacritics and emoji count twice), Threads (one
  topic tag), Bluesky; hashtag caps per platform.
- Banks: MBV, VCBNeo, Vikki Bank (renamed OceanBank, CBBank, DongA Bank —
  saved old names get a one-click switch), Cake by VPBank, Timo.

Output:
- An empty channel name no longer leaves "…of Hades on ." — the channel
  phrase is dropped per language (8 locales, every template tested).
- Title alternatives are real title shapes with the user's separator and
  badge case; "Use this shape" sets them (new Title order setting:
  game first / video first); over-long ones can't be copied.
- Copy All can include the tags (setting); Batch picks Part or Demo part
  and continues from the editor's part number; Ctrl/Cmd+S saves the
  output to History.
- Social editor headings and hints translated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 22:29:44 +07:00
poli0981andClaude Opus 5.5 3912ca5152 feat(data): backup & restore with preview and undo; desktop files by name only
Storage (desktop):
- The webview can no longer name a path. Five commands that read, wrote,
  listed and deleted any path the frontend sent are replaced by name-only
  commands (backups, logs) that resolve under the app data folder, and by
  export/import commands that open the native dialog from Rust, so the only
  file touched is the one the user picked (json/jsonl/txt/csv/md, 20 MB).
  The fs and shell plugins are removed (Rust, npm, capabilities).
- The settings "mirror" file is gone: it was written next to the data
  folder (a missing path separator) and never read back. On first start
  the file becomes a restorable backup — never applied on its own — and
  the stray log folder is merged into the right one.
- Automatic backups on desktop: after library changes (quiet 30 s, at most
  every 10 min, skipped when unchanged or empty), newest ten kept, plus one
  before every restore. Settings lists them with Restore.
- One tray icon, built in code with the app icon (the config entry that
  could add a second, iconless one is removed).

Backup & restore (every platform):
- Format 2 files carry each section's store version; imports run the
  stores' own migrations (now exported functions), then a whitelist
  sanitizer: known fields and values only, editor limits, safe unique ids.
- Reads every earlier export: v0.15-v0.38 envelopes (log exports were
  labelled "history"), pre-v0.15 bare arrays, the old desktop data file.
- Restore dialog: new / already here / different per item, merge (keep the
  newer one, or both) or replace, section and item selection, one step,
  Undo. Newer-version sections are shown, not restored.
- Settings: Back up (choose sections) / Restore / drop a file. Consent and
  panel state are never exported or overwritten.
- History export as CSV (spreadsheet-safe) or JSON; logs export as "logs";
  dated file names; no more 250 ms timer guessing that a picker was
  cancelled.

Library:
- Templates save every editor field; presets save store link types and the
  other per-game fields; profiles save donate, community links and the
  custom graphics preset. Edit forms can update from the current editor,
  start fresh each time they open, and save on Enter. Toasts translated.

Dev: Vite no longer watches src-tauri (cargo's locked .dll crashed
`tauri dev` on Windows).

Verified in `tauri dev` on Windows under a test identifier: legacy file
recovered, old logs merged, auto backup, restore from the legacy backup
with a backup before it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 22:05:12 +07:00
poli0981 db613e011b Merge pull request #173 from poli0981/feat/data-input-io
fix(data): hardware names, YouTube's tag count, chapters, history duplicates, validation
2026-09-30 21:15:42 +07:00
poli0981andClaude Opus 5.5 7e6c12152f fix(data): hardware names, YouTube's tag count, chapters, history duplicates, validation
Hardware
- GPU catalog rewritten with stable ids and official names: descriptions
  read "NVIDIA GeForce RTX 5080", "AMD Radeon RX 9070 XT", "Apple M4 Pro"
  instead of "NVIDIA RTX 5080" / "AMD RX 9070 XT" / "Apple Silicon M4 Pro".
  Cards that never shipped (RX 9080, RX 9090 XT, Arc B380) are gone;
  RTX 50/40/30 laptop GPUs, RX 9070 GRE, VRAM variants, Radeon/Intel
  integrated graphics, handheld APUs and Apple M5 (Pro/Max/Ultra) added.
  One searchable picker ("5080", "rog ally") replaces Brand › Series ›
  Model, with free text for anything else.
- Old `brand|series|model` values are migrated (editor v19, profiles v3,
  templates v2, and on load/import); unknown cards keep their full name.
- RAM: 24/48/192 GB, LPDDR4/4X/5/5X, optional speed ("32 GB DDR5-6000");
  no DDR6/DDR7; plain "DDR"; "48GB GB" fixed; changing the size no longer
  clears the type. OS: SteamOS, Bazzite, CachyOS, Nobara, openSUSE,
  Fedora 43/44; Linux reads "Ubuntu 24.04 LTS". CPU: suggestions, and
  Windows' "Intel(R) Core(TM) … CPU @ 3.60GHz" is tidied on blur.
- The rig block uses translated labels in a fixed order (CPU, GPU, RAM…)
  in both the description and the social captions.

Tags
- Measured the way YouTube counts (quotes around multi-word tags, one
  comma between): 15 of 51 real tag sets were over 500 by YouTube's count
  while showing under. Counters and the limit warning use the same count.
- Trimming keeps trying shorter tags after one that doesn't fit.
- "Elden Ring Steam", "itch.io gameplay" (was STEAM / ITCHIO); no platform
  tags for a publisher site; "best open world games" (was "openworld");
  RPG/simulation/card pools no longer carry other genres' tags.

Timestamps
- Keywords need a word boundary: "Final Fantasy VII" stays a title (was
  "Ending Fantasy VII"), "Introduction" stays whole.
- Accepts [0:00], 0:00 - label and editor frame counts; pt-BR and
  Indonesian keywords; a Tidy up button; a live check of YouTube's
  chapter rules (0:00 first, 3+, 10 s apart, in order).

Output and data
- History keeps one entry per video (updated in place) instead of one per
  Output visit; existing duplicates are folded (history v3). The History
  Limit is healed on every load.
- A field over its limit blocks only its own copy button (Copy All: title
  or description); a warning when YouTube would reject "<" or ">".
- Validation: Steam /sub/, /bundle/ and s.team links, GOG/Humble/xbox.com
  without www, regional Nintendo sites, Microsoft Store, Luna; social
  links with www./m./twitter.com; phone, YouTube Music and
  video-in-playlist links (normalised); email domains need a TLD; the live
  URL is validated; no bare "#" hashtag.
- The engine takes the year from the caller; "Ending N" follows the output
  language.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 21:11:58 +07:00
poli0981 7f8dc0ad64 Merge pull request #172 from poli0981/feat/ui-redesign
feat(ui): redesign — design system, app shell, command palette, every page
2026-09-30 21:11:28 +07:00
poli0981andClaude Opus 5.5 a2715f9c69 feat(ui): redesign — design system, app shell, command palette, every page
A new, compact interface on Radix primitives, Motion, cmdk and sonner.

Design system
- Tokens for surfaces, text, accent and states in dark and light, used
  everywhere (no more hard-coded red/yellow/pink); Inter and JetBrains
  Mono self-hosted; compact controls that grow to 44px on touch screens.
- Primitives rebuilt on Radix: Button, IconButton (cannot render without
  a name), Field/Input/Select/Textarea (labels wired to controls; the ten
  selects that shared id="type" are gone), Switch, Checkbox, Tabs,
  SegmentedControl, Accordion (closed content is inert), Dialog,
  AlertDialog, Sheet, Popover, Tooltip, Card, Badge, Banner, EmptyState,
  PageHeader, NumberField.
- Animated icons (copy→check, sun↔moon, hover micro-motion on the nav)
  that follow the OS reduce-motion setting.

App shell
- Collapsible sidebar with grouped pages and a sliding active marker;
  top bar with the command palette, output/interface language, theme
  and donate; on phones a bottom bar with four pages plus "More".
- Ctrl/⌘+K command palette: go anywhere, copy title/description/tags,
  apply a profile/preset/template, switch theme or languages.
- Skip link, one h1 per page, <main> focusable; toasts no longer share a
  corner with three other floating elements.

Pages
- Editor: two columns with a sticky live preview (tabs, counters, copy)
  or a sheet on phones; sections reordered so video type and game come
  first; genres are a searchable picker instead of a wall of 42 chips;
  expand/collapse all; a button to the Output page.
- Output: a YouTube preview (what search results and the "…more" fold
  show), language tabs, Copy All in the header (floating on phones).
- Profiles/presets/templates share one card with Apply + Undo; History,
  Logs, Batch, Social, Playlist, Settings, About, Legal, the consent
  screen and the error pages all use the same primitives.

Fixes
- Ctrl/⌘+Shift+C ignored the YouTube limits and Strict Mode.
- Number settings clamped on every keystroke; they now save on blur.
- Hard-coded English on Playlist, Batch, Logs, Profiles and Settings.
- Flags as language icons (Windows shows letters) → native name + code.
- The consent screen could not change language or theme.
- About: dead Discord invite removed; contact addresses by purpose.
- Desktop window is resizable (1280×820, min 960×640).

Initial load 262 KB gzip (budget 280): the command palette, the genre
list and the Output page load on demand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 20:42:43 +07:00
poli0981 676ed417c4 Merge pull request #171 from poli0981/ci/quality-gates
ci: security, licensing and style gates; pin every action by SHA
2026-09-30 20:15:32 +07:00
poli0981andClaude Opus 5.5 1b5051beaa ci: keep release builds off the npm cache; week-long Dependabot cooldown
zizmor (workflow-lint) flagged three things:

- cache-poisoning: setup-node v7 restores the npm cache unless told not
  to, and the release workflows publish what they build. They now set
  `package-manager-cache: false`, so a cache written by another workflow
  can never reach a release artifact.
- dependabot-cooldown: raise every ecosystem to 7 days.
- dangerous-triggers: the two `workflow_run` notifiers are ignored with
  the reason in zizmor.yml; the shared workflows only read run metadata
  and pass untrusted fields through `env:`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 20:00:55 +07:00
poli0981andClaude Opus 5.5 a70580e703 ci: security, licensing and style gates; pin every action by SHA
New checks
- security.yml: dependency-review blocks PRs that add a high/critical
  advisory; actionlint + zizmor lint the workflows themselves (template
  injection, permissions, credential persistence, unpinned uses); OpenSSF
  Scorecard weekly and on main (published, not uploaded as alerts).
- compliance.yml: REUSE lint over the whole repo (REUSE.toml + LICENSES/,
  no per-file headers) and Conventional-Commit PR titles.
- rust.yml (src-tauri changes + weekly): rustfmt, clippy -D warnings,
  cargo test, and cargo-deny for RustSec advisories, licenses and sources.
- ci.yml `check` gains: coverage thresholds (src/engine, worker),
  check:licenses, check:bundle, and a `wrangler deploy --dry-run`.

Licensing
- THIRD_PARTY_NOTICES.md is now generated from package.json, the installed
  packages and Cargo.toml/Cargo.lock (`npm run generate:third-party`); CI
  fails when it is stale or when anything bundled into the app carries a
  license outside the allowlist. It had drifted to React 18 / Vite 7 /
  Tailwind 3.
- Vite's build.license emits the full text of every bundled package's
  license to /licenses/third-party.md (served publicly, before the gate).

Bundle budget
- scripts/check-bundle-size.ts measures what CLAUDE.md's "500KB" never
  defined: initial load (everything index.html references) <= 280 KB gzip
  (197 KB today) and no JS chunk over 500 KB raw.

Coverage
- @vitest/coverage-v8; thresholds sit just under today's numbers. The
  engine is at 89% lines / 64% functions — not the 100% CLAUDE.md claimed.

Supply chain
- Every third-party action pinned to a commit SHA (Dependabot updates the
  SHA and its version comment); checkout never persists credentials.
- Release workflows: a `verify` job (typecheck, tests, version sync, Tauri
  alignment, tag == package version) gates the build; no dependency caches
  in release jobs; permissions granted per job.
- Reusable Discord workflows receive only the secrets they declare instead
  of `secrets: inherit` (which exposed the Android signing keys to them).
- Rust: cargo-deny found RUSTSEC-2026-0194/0195 (quick-xml DoS, via plist)
  that Dependabot had not raised; plist 1.10 brings quick-xml 0.41.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:46:24 +07:00
poli0981 416d9f3ee2 Merge pull request #170 from poli0981/chore/deps-2026-09
chore(deps): fold the open Dependabot bumps into one update; Tauri 2.12 drops rand
2026-09-30 19:43:45 +07:00
poli0981andClaude Opus 5.5 ffd1c7900d chore(tauri): regenerate capability schemas for tauri 2.12
tauri-build rewrites src-tauri/gen/schemas on the first build after an
upgrade; commit them with the crate bump so the next build is a no-op.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:35:03 +07:00
poli0981andClaude Opus 5.5 f230f036a1 chore(deps): fold the open Dependabot bumps into one update; Tauri 2.12 drops rand
One lockfile instead of nine PRs: every minor/patch the open Dependabot PRs
proposed, plus everything else that moved within range.

npm (`npm update --save`)
- react/react-dom 19.3, vite 8.3, i18next 26.4, react-i18next 17.0.15,
  react-router 7.18.4, eslint 10.11, typescript-eslint 8.71, knip 6.38,
  prettier 3.9.9, @vitejs/plugin-react 6.1, @tauri-apps/* 2.12 / plugins,
  @types/*, @testing-library/react, postcss, autoprefixer, tsx.
- Security: vitest + @vitest/mocker 4.1.11 (path traversal via redirect
  mock), @humanfs/node 0.16.8 (symlinked copy). `npm audit`: 0.
- Majors stay out (TypeScript 7, Vitest 5, lucide-react 1).

Rust (`cargo update -p tauri …`)
- tauri 2.12, tauri-build 2.7, dialog 2.8, fs 2.6, opener 2.7, shell 2.4,
  single-instance 2.5 — matching the npm side minor for minor.
- tauri 2.12 no longer depends on kuchikiki, so `rand` 0.7.3 (the unsound
  custom-logger advisory) leaves Cargo.lock entirely. Only glib 0.18 (gtk-rs
  0.18 Linux stack) remains ignored.

CI and config
- New `npm run check:tauri`: the tauri CLI refuses to build when the npm
  packages and crates differ in major.minor, and CI never runs `tauri build`
  — so a one-sided bump merged green and broke the next release tag. Now CI
  says which side lags.
- dependabot.yml: 3-day cooldown for version updates (security updates are
  exempt), new ui / cloudflare / testing / types groups, rand ignore removed.
- actions/setup-java v5 -> v6 (release-android).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:34:44 +07:00
poli0981 d7abc1e508 Merge pull request #169 from poli0981/feat/turnstile-gate
feat(web): Turnstile gate, in-site legal pages and clean URLs
2026-09-30 19:30:34 +07:00
poli0981andClaude Opus 5.5 85a8dc121b fix(legal): build heading anchors without a tag-stripping regex
CodeQL flagged the `<[^>]+>` replace in slugify as incomplete multi-character
sanitisation. The character filter after it already reduced anything that is
not a letter or digit to a hyphen, so no markup could survive; drop the regex
and let that one rule do the work.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:29:05 +07:00
poli0981andClaude Opus 5.5 5ced6b4a86 feat(web): Turnstile gate, in-site legal pages and clean URLs on ytgenerator.stream
A Worker (worker/) now sits in front of the static build, configured from the
same wrangler.jsonc. Cloudflare builds and deploys it; nothing in GitHub
Actions does.

Gate
- First visit shows a branded check page (8 languages, Accept-Language) with
  Cloudflare Turnstile. The token is verified server-side against
  TURNSTILE_SECRET: success, hostname, action "enter", age <= 300 s. Only
  Cloudflare's own test-key results skip the hostname/action check, so
  `npm run cf:dev` works with the published test keys.
- Pass -> `__Host-ytg_gate` (HttpOnly, Secure, SameSite=Lax, 24 h): an HMAC
  over expiry + a user-agent hash, keyed from the Turnstile secret, so no
  second secret exists and a cookie copied into a scraper is useless.
- The page reloads in place instead of redirecting, so there is no `next`
  parameter to open-redirect with; /__gate/status lets the page tell a
  cookie-blocking browser what is wrong instead of looping; after one
  failure it waits for a click rather than resubmitting.
- Missing secret = deployment mistake: the site stays up without the gate and
  the Worker logs it, instead of locking every visitor out.
- The agree box on the gate records `ytg_terms`, which the app reads on boot
  so web visitors meet one blocking screen, not two.

Headers and static files
- worker/headers.ts sets CSP (nonce + strict-dynamic on the gate, no script
  at all on legal pages), nosniff, Referrer-Policy, Permissions-Policy, COOP,
  CORP, X-Frame-Options on everything the Worker returns; _headers covers
  the files served directly; a test keeps the two baselines identical.
- `not_found_handling: "404-page"` (a static 404.html) instead of the SPA
  fallback, which would have handed index.html past the gate for any
  excluded path. The Worker serves the shell itself by fetching "/" - not
  "/index.html", which html_handling would 307 back to the home page.
- security.txt (RFC 9116) is generated per build so Expires stays ~6 months
  ahead; the Web Analytics beacon is injected into the web build only.
- theme-init.js applies the saved theme before first paint (no inline script).

Legal in-site
- build-plugins/legal-docs.ts renders TERMS, PRIVACY, DISCLAIMER (+ vi),
  LICENSE, THIRD_PARTY_NOTICES, SECURITY, NOTICE and CODE_OF_CONDUCT at build
  time into static /legal pages (public, before the gate) and a lazy
  `virtual:legal-docs` module for the in-app Legal Center, which works
  offline on desktop and Android and never leaves the webview.
- PRIVACY, TERMS and SECURITY rewritten for Cloudflare hosting, Turnstile,
  Web Analytics and the two cookies; contacts moved to the poli0981.dev
  aliases (privacy@, legal@, dmca@, copyright@, security@, code@).
- CURRENT_TERMS_VERSION 1 -> 2: the Privacy Policy changed materially.

App
- Web uses BrowserRouter (real paths; analytics can count them), Tauri keeps
  HashRouter; old /#/x bookmarks are rewritten to /x before the router reads
  them. Consent is a layout route; /legal sits outside it.
- <html lang> follows the UI language; a stale chunk after a deploy triggers
  one reload instead of an error page.

.gitattributes pins LF everywhere so Windows checkouts stop failing Prettier.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:26:40 +07:00
poli0981 c6e43f8e13 Merge pull request #167 from poli0981/feat/cloudflare-hosting
fix(web): serve ytgenerator.stream from the root, retire the GitHub Pages deploy
2026-09-30 19:24:32 +07:00
poli0981andClaude Opus 5.5 1fc939b711 fix(web): serve from ytgenerator.stream root and retire the GitHub Pages deploy
The Worker connected to ytgenerator.stream was serving a build made for the
GitHub Pages sub-path: index.html asked for /youtube-generator/assets/*.js, the
SPA fallback answered every one of those with index.html, and the site loaded
blank. Both builds are now served from `/`.

- vite.config.ts: base "/" for web and Tauri alike.
- wrangler.jsonc: the one Cloudflare file in the repo. Assets-only for now
  (dist/, SPA fallback, custom domain declared so `wrangler deploy` never
  detaches it, workers.dev off, build.command runs `npm run build`).
- public/_headers: CSP, nosniff, Referrer-Policy, Permissions-Policy, COOP,
  X-Frame-Options; immutable caching for hashed /assets/*. No HSTS - the
  zone edge already sends it with preload.
- index.html, manifest, robots, sitemap: canonical/OG/JSON-LD on the new
  domain, pt-BR and id added to the locale metadata, Android listed.
- Brand: one SVG source in assets/brand/ now drives the favicon, the PWA
  icons (192/512/maskable), apple-touch-icon, a 1200x630 link-preview card
  and every Tauri desktop/Android/iOS icon. The desktop and Android apps had
  been shipping a flat indigo placeholder square; manifest and index.html
  pointed at four PNGs that did not exist. `npm run generate:brand`
  re-renders the web images; the Android adaptive icon gets a glyph-only
  foreground on the brand colour instead of a tile on a white disc.
- deploy-web.yml and notify-deploy.yml removed, .nojekyll dropped. The last
  Pages deployment stays online untouched until the data-migration page
  replaces it.
- .node-version pins Node 22 for Workers Builds; wrangler, @tauri-apps/cli
  and @resvg/resvg-js are pinned dev dependencies (`npm run cf:dev`,
  `npm run cf:check` for a dry-run deploy).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:02:57 +07:00
poli0981 35b5badbac Merge pull request #152 from poli0981/dependabot/github_actions/actions-674967a53d
ci: bump actions/upload-artifact from 6 to 7 in the actions group
2026-08-18 11:16:25 +07:00
dependabot[bot] 37b9638b61 ci: bump actions/upload-artifact from 6 to 7 in the actions group
Bumps the actions group with 1 update: [actions/upload-artifact](https://github.com/actions/upload-artifact).


Updates `actions/upload-artifact` from 6 to 7
- [Commits](https://github.com/actions/upload-artifact/compare/v6...v7)

---
updated-dependencies:
- dependency-name: actions/upload-artifact
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-08-17 13:46:42 +00:00
poli0981 55a0236cc5 Merge pull request #150 from poli0981/docs/readme-refresh
docs(readme): refresh the stack, model and binary-size claims
2026-08-17 13:12:09 +07:00
poli0981andClaude Opus 5 b7be12824c docs(readme): refresh the stack, model and binary-size claims
Three things had gone stale or were never quite right:

- **Tech stack** still said React 18 / Tailwind 3. v0.37.0 moved to React 19,
  Tailwind 4, Zustand 5 and i18next 26.
- **AI disclosure** named "model 4.7 Opus, 1M-context variant", two
  generations old. Now names the family rather than pinning a version that
  goes stale on every model release.
- **"~8 MB native desktop app"** was optimistic and incomplete. Measured
  against the v0.37.0 assets: the Windows exe is 2 MB, the msi and macOS
  bundle 4 MB, deb/rpm 5 MB — but the Linux AppImage is 76 MB because it is
  self-contained, and the APK is 54 MB. Says "2–5 MB installers" and calls out
  the AppImage rather than quoting one number that only holds for some
  platforms.

Checked and left alone: "248 content-warning IDs across 12 groups" is exactly
right (`CONTENT_WARNINGS` has 248 unique ids, `CONTENT_WARNING_GROUPS` has 12).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 13:05:52 +07:00
poli0981 5edd0d6bfd Merge pull request #148 from poli0981/feat/v0.36.0-locales
feat: v0.38.0 — Portuguese (Brazil) and Indonesian
2026-08-17 12:50:12 +07:00
poli0981andClaude Opus 5 b920d3567e chore(release): v0.38.0 — Portuguese (Brazil) and Indonesian
Two new locales, 1,562 strings each, complete: titles, every description
block, all 248 content warnings, tech notes, playthrough notes, pinned
comments, playlist copy, and the whole interface.

Brazil is a top-three market for gameplay viewing and Indonesia the largest in
Southeast Asia. Both use Latin script, so neither needed font or layout work.

**docs/I18N.md was wrong about what registering a locale takes**, and this
release is where that bit. It claimed `SUPPORTED_LANGUAGES` was "the only
registration step". It is one of four, and they fail differently:

  SupportedLanguage union        compile error
  CORE_TAGS_BY_LANG              compile error  (there are TWO such records,
  MULTILINGUAL_TAGS              compile error   not one — the doc mentioned one)
  detectBrowserLanguage          SILENT

The silent one matters most: the language works perfectly and simply never
auto-selects for a visitor whose browser is set to it. `SUPPORTED_LANGUAGES`
also wasn't type-bound to the union, and every consumer casts, so a mismatch
between the first two compiled cleanly — it now carries a `satisfies` clause.

`tests/i18n/locale-registration.test.ts` exists to close those gaps: it checks
the picker list against the locale directories on disk in BOTH directions, plus
namespace files, flags, native names and tag pools.

Browser-language detection now matches the full BCP-47 tag before the bare
language, or `pt-BR` would be reduced to `pt` and never found. Any other
Portuguese variant resolves to pt-BR rather than falling through to English.

115 UI keys were not hand-translated at all: their English text is
byte-identical to a string already translated in templates.json (graphics
presets, ray-tracing modes, difficulty names, content-warning labels), so they
are copied across. Translating those twice risks a checkbox and the rendered
description disagreeing about what the same option is called.

Deliberately left in English, matching what the Spanish locale already does:
vendor product names (NVIDIA DLSS, AMD FSR, Intel XeSS, Fluid Motion Frames),
platform brands, hardware acronyms, genre terms that are loanwords in both
languages, and example URLs/emails in placeholders. So pt-BR reads 1,344/1,562
and id 1,308/1,562 "differing from English" — the remainder are those
pass-throughs, not gaps.

Both are AI-translated and NOT native-reviewed. Recorded in DISCLAIMER.md
alongside JA/ES/KO/ZH.

Also replaces `__dirname` in the Vite and Vitest configs with
`import.meta.dirname` — Vite 8's native config loader doesn't provide the CJS
global and warned on every run.

v0.36.0 is skipped: the dependency release shipped first and took 0.37.0.

Tests 692 → 698. Validator now 1,562 keys x 8 locales.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 12:46:54 +07:00
poli0981andClaude Opus 5 3b0db9a95f feat(i18n): translate the editor's game-info and video-settings labels
120 more keys per locale: section headings, game / channel / boss / DLC / mod
fields, the gacha quest taxonomy, GPU-RAM-OS pickers, the Vietnamese donate
block, graphics-preset and video-style options, timestamps and store links.

Vendor tech names stay in English throughout — DLSS, FSR, XeSS, DLAA, the frame
generation multipliers, NVIDIA / AMD / Intel. They are product names, and the
templates locale already keeps them, so translating the picker but not the
rendered line would make the two disagree.

Note for anyone editing these files by script: `ui.json` contains literal keys
that themselves contain dots — `"frameGenMultiplier.nvidia"` sits directly
beside a plain `"frameGenMultiplier"` leaf — so a naive split-on-dot path walk
resolves to the wrong node, or crashes.

pt-BR now 1039/1562 translated, id 1003/1562. The remainder is `editor.*`
content-warning and tech-note checkbox labels.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 12:37:52 +07:00
poli0981andClaude Opus 5 bbf201c30f feat(i18n): translate the UI chrome for pt-BR and id
~500 keys per locale: tabs, About, Output, common actions, error pages, the
consent gate, video types, genres, rig labels, Profiles / Presets / Templates /
History, the whole Settings page, Social, Batch, shortcuts, validation
messages, Playlist and Logs.

115 of them were not translated by hand at all — their English text is
byte-identical to a string already translated in templates.json (graphics
presets, ray-tracing modes, difficulty names, content-warning labels), so they
are copied across. Translating those twice risks a checkbox and the rendered
description disagreeing about what the same option is called.

Left as English on purpose: brand and product names (Ko-fi, Patreon, PayPal,
GitHub, Discord, Steam, Twitch, TikTok, Mastodon, Bluesky), hardware acronyms
(CPU, GPU, RAM), genre terms that are loanwords in both languages (RPG, JRPG,
FPS, MMO, Indie, Metroidvania, Roguelike, Souls-like, SHMUP, Battle Royale),
and resolution / FPS values.

Still to do: `editor.*`, the largest single block.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 12:37:52 +07:00
poli0981andClaude Opus 5 e56c32e76a feat(i18n): translate templates.json for pt-BR and id
563 keys per locale — the strings YouTube viewers actually read: titles,
description blocks, all 250 content warnings, tech notes, playthrough notes,
pinned comments, playlist copy and timeline keywords.

Left identical to English on purpose, matching what the existing Spanish locale
does: separator glyphs, empty video-type keys, vendor product names (NVIDIA
DLSS / AMD FSR / Intel XeSS / Frame Generation), and loanwords that are the
same word in both target languages (Demo, Beta, Speedrun, New Game+, Normal,
Ultra, Jumpscare, Doomscrolling).

Not yet registered in code — the locales are inert until `SUPPORTED_LANGUAGES`,
the `SupportedLanguage` union, `detectBrowserLanguage` and `MULTILINGUAL_TAGS`
name them. ui.json and that wiring follow.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 12:37:52 +07:00
poli0981 841df7d246 Merge pull request #146 from poli0981/fix/android-release-upload
fix(ci): upload the Android APK with gh instead of action-gh-release
2026-08-17 12:07:25 +07:00
poli0981andClaude Opus 5 b244063555 fix(ci): upload the Android APK with gh instead of action-gh-release
The v0.35.0 APK built successfully three times and was never attached. The
build was fine every time; the upload step failed with "Resource not accessible
by integration" on update-a-release.

`softprops/action-gh-release@v3` was resolving the target release from
GITHUB_REF rather than from the `tag_name` it was handed. On the tag push it
looked for a release tagged `refs/tags/v0.35.0`; on the workflow_dispatch re-run
it looked for one tagged `refs/heads/main`. Neither exists, so it fell through
to CREATING a release against a branch ref, which the token is quite right to
refuse. The permissions were never the problem — the job log shows
`Contents: write` on every run.

Replaced with `gh release upload`, which is pre-installed on every runner and
takes the tag as a positional argument, so it cannot make that substitution.
`--clobber` makes a re-run idempotent.

Also uploads the APK as a workflow artifact first, so a failed release upload
never costs another 20-minute NDK build to recover from — which is what it cost
to diagnose this.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 12:06:07 +07:00
poli0981 bb0a40cfae Merge pull request #145 from poli0981/chore/v0.37.0-deps
chore: v0.37.0 — dependency modernization
2026-08-17 11:46:29 +07:00
poli0981andClaude Opus 5 0c7fb31165 chore(release): v0.37.0 — dependency modernization
Every major the project had been sitting on, brought current. No user-facing
feature changes; the app should behave identically.

  React 18 → 19 (+ types, @vitejs/plugin-react 6)
  Tailwind 3 → 4
  ESLint 9 → 10 (+ eslint-plugin-react-hooks 5 → 7)
  Zustand 4 → 5
  i18next 23 → 26, react-i18next 15 → 17
  @testing-library/*, typescript-eslint 8.67, Vite/Vitest/tsx/knip patches

**React 19** needed exactly one source change: `useRef<T>(null)` is now typed
`RefObject<T | null>` rather than `RefObject<T>`. The old type quietly claimed a
ref was non-null before its element mounted; ScrollToTopButton now matches,
which makes its existing null check honest rather than defensive.

**Tailwind 4** moves configuration from `tailwind.config.ts` (deleted) into
CSS. The tokens live in an `@theme` block that maps Tailwind's names onto the
existing `:root` / `.light` variables, so the runtime theme toggle still owns
the values and keeps working untouched. `darkMode: "class"` becomes
`@custom-variant dark` — the app toggles a class on <html> rather than
following the OS, so the default prefers-color-scheme variant would be wrong.
Verified in the browser in both themes; a CSS migration fails visually, not at
build time.

**The lint upgrade earned its keep.** `react-hooks/set-state-in-effect` (new in
v7, React Compiler-aware) flagged seven sites. Four were real extra render
passes:

  - use-online-status rewritten to `useSyncExternalStore`. It had been
    re-reading `navigator.onLine` inside an effect to close the gap between
    first render and the listeners attaching — subscribing properly removes the
    gap instead of patching it.
  - ShortcutHelpModal derives its filter from `open` instead of resetting state
    in an effect, so a modal that is closed most of the time stops scheduling
    work on unrelated parent updates.
  - DraftIndicator and use-languages-ready now guard their setters.

Three remain as warnings, deliberately. They genuinely sync state FROM an
external source (i18next bundle readiness, a text mirror of a numeric store
field, a useMemo the compiler cannot preserve) and need a restructure rather
than a guard. Recorded in eslint.config.js with the reason — downgraded, not
silenced, and not a reason to hold back ESLint 10.

**lucide-react deliberately stays at 0.577.0.** 1.x removes every brand icon;
upstream dropped them for trademark reasons. Taking it would mean either a
generic globe beside a Facebook link or re-adding the marks ourselves and
inheriting the exposure lucide just shed. 0.577 already delivered the win —
main bundle 175 kB → 137 kB.

knip now ignores `tailwindcss`: after the migration its only reference is
`@import "tailwindcss"` in CSS, which knip does not follow.

Full gate green — typecheck, typecheck:all, lint, format:check,
validate:locales, knip, check:version, 692 tests, build — plus a browser check
of both themes with the editor and batch pages functional.

0.36.0 is reserved for the two new locales.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 11:43:51 +07:00
poli0981 11a822a881 Merge pull request #144 from poli0981/docs/v0.35.0
docs: correct the i18n registration claim, document v0.35.0
2026-08-17 11:33:23 +07:00
poli0981andClaude Opus 5 08be7d1ff8 docs: correct the i18n guide's registration claim, document v0.35.0
**docs/I18N.md was wrong in a way that would waste a contributor's afternoon.**
It said adding a locale to `SUPPORTED_LANGUAGES` was "the only registration
step". It is one of four, and the missing ones fail differently: the
`SupportedLanguage` union is a compile error, `MULTILINGUAL_TAGS` is a compile
error, but `detectBrowserLanguage`'s own hardcoded copy of the list fails
*silently* — the language works and simply never auto-selects for a visitor
whose browser is set to it. Also noted: `SUPPORTED_LANGUAGES` is not type-bound
to the union and every consumer casts, so a mismatch compiles cleanly.

Also documents the `--copy-english` / `--force` flags on the locale generator,
which only started existing in v0.35.0 despite having been advertised in
package.json since v0.1.

Elsewhere:

- **DEVELOPMENT.md** — the five new npm scripts, including why `format:check`
  excludes markdown and locale JSON, and why `typecheck:all` exists.
- **TECH-SPEC.md** — the real CI job, a new Field Limits section, and how
  over-limit enforcement derives from the engine's long-ignored `warnings`.
- **ARCHITECTURE.md** — the settings→engine mapping and its two guards, the
  two-source validation state, and an honest note that the first Strict Mode
  implementation typechecked, passed tests, and did nothing.
- **FEATURES.md** — the settings table still listed `Default Genre` and
  `Auto-save Draft`, removed in v0.22.0 and v0.3. Replaced, plus a guardrails
  section.
- **README.md** — guardrails in the feature list, and a link to the wiki.

The wiki itself (12 pages: quick start, glossary, field reference, guardrails,
batch/social, import-export, languages, privacy, troubleshooting, FAQ, release
process) is published separately — it lives in its own repository.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 11:32:09 +07:00
poli0981 03174084cf Merge pull request #143 from poli0981/chore/deps-minor
chore(deps): consolidate the six Dependabot minor bumps
2026-08-17 11:29:16 +07:00
poli0981andClaude Opus 5 d6de8764f1 chore(deps): consolidate the six Dependabot minor bumps into one lockfile
The new grouped Dependabot config opened six PRs within minutes of landing.
Merging them one at a time would mean six lockfile rebases and six CI runs for
what is a single dependency resolution, so this applies all of them together:

  i18next-resources-to-backend 1.2.1 → 1.2.3
  @tauri-apps/{api,plugin-dialog,plugin-fs,plugin-opener} → latest 2.x
  lucide-react 0.400.0 → 0.577.0
  eslint + @eslint/js 9.39.4 → 9.39.5, typescript-eslint 8.58 → 8.67
  knip 6.14.1 → 6.32.2, prettier 3.8.1 → 3.9.6,
  prettier-plugin-tailwindcss 0.6.14 → 0.8.1
  vite 8.0.16 → 8.2.1, vitest 4.1.8 → 4.1.10, tsx 4.22 → 4.23,
  postcss 8.5.15 → 8.5.26, autoprefixer 10.4.27 → 10.5.4

All within-major; the majors (React 19, Tailwind 4, ESLint 10, i18next 26,
Zustand 5) are held back by the Dependabot ignore rule and belong to their own
planned release.

The `lint-and-format` group's own PR was RED, and correctly so: prettier 3.9
formats six files differently, and Dependabot cannot run `npm run format` for
itself. Reformatted here — which is the format gate doing exactly its job on
its first real outing.

lucide-react's jump also drops the main bundle 175 kB → 137 kB (gzip 48 → 37).

Verified: typecheck, typecheck:all, lint, format:check, validate:locales, knip,
check:version, 692 tests and build all pass, and the app renders with icons
intact in the browser.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-17 11:21:30 +07:00
poli0981 ff8c1133e6 Merge pull request #137 from poli0981/dependabot/github_actions/actions-859475a651
ci: bump the actions group with 4 updates
2026-08-17 11:18:43 +07:00
dependabot[bot] 913e82f6b5 ci: bump the actions group with 4 updates
Bumps the actions group with 4 updates: [actions/checkout](https://github.com/actions/checkout), [actions/setup-node](https://github.com/actions/setup-node), [actions/cache](https://github.com/actions/cache) and [tauri-apps/tauri-action](https://github.com/tauri-apps/tauri-action).


Updates `actions/checkout` from 6 to 7
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v6...v7)

Updates `actions/setup-node` from 6 to 7
- [Release notes](https://github.com/actions/setup-node/releases)
- [Commits](https://github.com/actions/setup-node/compare/v6...v7)

Updates `actions/cache` from 5 to 6
- [Release notes](https://github.com/actions/cache/releases)
- [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md)
- [Commits](https://github.com/actions/cache/compare/v5...v6)

Updates `tauri-apps/tauri-action` from 0 to 1
- [Release notes](https://github.com/tauri-apps/tauri-action/releases)
- [Changelog](https://github.com/tauri-apps/tauri-action/blob/dev/CHANGELOG.md)
- [Commits](https://github.com/tauri-apps/tauri-action/compare/v0...v1)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: actions
- dependency-name: actions/setup-node
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: actions
- dependency-name: actions/cache
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: actions
- dependency-name: tauri-apps/tauri-action
  dependency-version: '1'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-08-17 03:42:57 +00:00
428 changed files with 38759 additions and 19874 deletions

No files matched your search

+5
View File
@@ -0,0 +1,5 @@
# Copy to .dev.vars for `npm run cf:dev`. These are Cloudflare's public
# Turnstile TEST keys: the widget always passes and the secret accepts only the
# dummy token it produces. Never put the real secret in a file.
TURNSTILE_SITE_KEY=1x00000000000000000000AA
TURNSTILE_SECRET=1x0000000000000000000000000000000AA
+13
View File
@@ -0,0 +1,13 @@
# LF in the repository and in every checkout, on every OS. Prettier enforces
# `endOfLine: "lf"`, and a Windows checkout with core.autocrlf=true otherwise
# turns every file it touches (checkout, stash, rebase) into a formatting
# failure that CI never sees.
* text=auto eol=lf
# Binary assets — never touch.
*.png binary
*.ico binary
*.icns binary
*.jks binary
*.keystore binary
*.woff2 binary
+10 -7
View File
@@ -12,8 +12,8 @@ body:
id: version
attributes:
label: App version
description: From the About page or the title bar. Example `v0.13.0`.
placeholder: v0.13.0
description: From the About page. Example `v1.2.0`.
placeholder: v1.2.0
validations:
required: true
- type: dropdown
@@ -21,10 +21,11 @@ body:
attributes:
label: Where are you running YTDescGen?
options:
- Web (GitHub Pages)
- Web (ytgenerator.stream)
- Desktop — Windows (Tauri)
- Desktop — macOS (Tauri)
- Desktop — Linux (Tauri)
- Android (APK)
- Local dev (npm run dev)
validations:
required: true
@@ -32,14 +33,14 @@ body:
id: os
attributes:
label: Operating system
description: e.g. Windows 11 25H2, macOS 14.6, Ubuntu 24.04
description: e.g. Windows 11 25H2, macOS 26, Ubuntu 24.04, Android 15
validations:
required: true
- type: input
id: browser
attributes:
label: Browser (web only)
description: e.g. Chrome 131, Brave 1.70, Safari 17. Leave blank for desktop.
description: e.g. Chrome 141, Firefox 144, Safari 26. Leave blank for the desktop and Android apps.
- type: dropdown
id: language
attributes:
@@ -50,7 +51,9 @@ body:
- 日本語 (ja)
- Español (es)
- 한국어 (ko)
- 中文 (zh)
- 简体中文 (zh)
- Português (BR) (pt-BR)
- Bahasa Indonesia (id)
validations:
required: true
- type: textarea
@@ -81,7 +84,7 @@ body:
id: console
attributes:
label: Console / log output
description: Open DevTools (web) or the log panel (desktop) and paste any errors. Rendered as code.
description: Paste errors from the app's Logs page (all platforms) or the browser's DevTools console (web). Rendered as code.
render: shell
- type: textarea
id: screenshots
+11 -2
View File
@@ -1,8 +1,17 @@
blank_issues_enabled: false
contact_links:
- name: Discord — General chat
url: https://discord.gg/2aNR3aVt
- name: Report a security vulnerability
url: https://github.com/poli0981/youtube-generator/security/advisories/new
about: Privately, please — never in a public issue. See SECURITY.md.
- name: User guide (wiki)
url: https://github.com/poli0981/youtube-generator/wiki
about: How-tos, backup & restore, troubleshooting and the FAQ.
- name: Discord
url: https://discord.gg/kDM9GMu5vm
about: For casual questions, gameplay chat, or quick help. Use a bug report or feature request for anything actionable.
- name: All channels and contacts
url: https://poli0981.dev/links/
about: Email addresses by purpose and every other way to reach the maintainer.
- name: GitHub Discussions
url: https://github.com/poli0981/youtube-generator/discussions
about: Ideas, Q&A, and release announcements live here.
@@ -31,11 +31,18 @@ body:
options:
- Editor
- Output / preview
- Batch
- Social captions
- Playlist
- History
- Profiles / presets
- Templates (description, title, tags)
- Backup & restore
- i18n / locales
- Settings
- Web app (ytgenerator.stream)
- Desktop (Tauri)
- Android
- Documentation
validations:
required: true
+12 -5
View File
@@ -17,10 +17,15 @@
## Checklist
- [ ] `npm run typecheck` passes
- [ ] `npm run lint` passes
- [ ] `npm run validate:locales` passes (required if you touched `src/i18n/locales/` or `_schema.json`)
- [ ] `npm run test:run` passes
- [ ] `npm run typecheck` and `npm run typecheck:all` pass
- [ ] `npm run lint` and `npm run format:check` pass
- [ ] `npm run validate:locales` passes — new strings are in all 8 locales (en, vi, ja, es, ko, zh, pt-BR, id)
- [ ] `npm run test:coverage` passes, with tests for the change
- [ ] `npm run knip` passes — no unused files, exports or dependencies
- [ ] `npm run check:version`, `check:tauri`, `check:licenses` and `check:copyright` pass
- [ ] `npm run build && npm run check:bundle` stay within budget
- [ ] Touched `worker/` or `wrangler.jsonc`: `npm run cf:check`
- [ ] Touched `src-tauri/`: `cargo fmt --check`, `cargo clippy --all-targets --locked -- -D warnings`, `cargo test`
- [ ] No secrets, credentials, or PII committed
- [ ] No new runtime dependencies without prior discussion in an issue
- [ ] Commit messages follow `type(scope): message`
@@ -32,12 +37,14 @@ If this PR touches the UI, attach screenshots or short recordings at:
- Desktop (≥1024px)
- Tablet (768px)
- Mobile (390px)
- Dark and light theme
- The desktop / Android app, if the change is platform-specific
Otherwise delete this section.
-->
## AI-Assisted Contribution
- [ ] Yes — AI tool used: <!-- e.g. Claude Code 4.7 Opus, Cursor, GitHub Copilot -->
- [ ] Yes — AI tool used: <!-- e.g. Claude Code (Claude Opus 5.5), Cursor, GitHub Copilot -->
- [ ] No
If yes: did you review every line of generated code/text yourself before submitting? <!-- yes/no -->
+69 -16
View File
@@ -5,19 +5,27 @@
# below add scheduled VERSION updates so the tree does not silently rot between
# advisories, and carry the ignore rules that keep unfixable alerts quiet.
#
# Why the cargo ignores: `rand` and `glib` are transitive dependencies of tauri,
# and their security fixes require semver-major bumps that the dependency
# tree does not allow, so every Dependabot security-update job for them
# fails with `security_update_not_possible` (runs 27387346373, 27387346324):
# `cooldown` holds version updates back for a week after a release is
# published. Most npm supply-chain compromises are caught and yanked within
# that window; security updates ignore the cooldown and still arrive at once.
#
# Why the cargo ignore: `glib` is a transitive dependency of tauri's Linux
# stack, and its security fix requires a semver-major bump the tree does not
# allow, so every Dependabot security-update job for it fails with
# `security_update_not_possible`:
#
# rand 0.7.3 (fix: 0.8.6) pinned by
# tauri -> tauri-utils -> kuchikiki -> selectors -> phf_codegen 0.8
# -> phf_generator 0.8 (requires rand ^0.7)
# glib 0.18.5 (fix: 0.20.0) pinned by
# tauri's gtk-rs 0.18 Linux stack (gtk/gdk/gio 0.18 require glib 0.18)
#
# Remove these ignores once tauri updates kuchikiki / the gtk-rs bindings
# (re-check with: cargo update -p rand@0.7.3 --precise 0.8.6 --dry-run).
# Remove the ignore once tauri moves to gtk-rs >= 0.20. (`rand` 0.7.3, the
# other long-standing one, left the tree in v1.0.0 when tauri 2.12 dropped
# kuchikiki.)
#
# Tauri moves in lockstep: the tauri CLI refuses to build when the
# @tauri-apps/* npm packages and the tauri crates differ in major.minor. When
# the `tauri` npm group arrives, run `cargo update -p tauri` (and the plugin
# crates) in src-tauri/ on the same branch — `npm run check:tauri` in CI says
# which ones.
version: 2
updates:
@@ -25,6 +33,8 @@ updates:
directory: "/"
schedule:
interval: "weekly"
cooldown:
default-days: 7
open-pull-requests-limit: 5
commit-message:
prefix: "chore(deps)"
@@ -32,21 +42,61 @@ updates:
groups:
# One PR per family instead of one per package. A split React or
# typescript-eslint bump is never independently mergeable anyway, and
# CI has to run for each PR.
# CI has to run for each PR. A package joins the FIRST group it matches,
# so the specific families come before the catch-alls.
react:
patterns: ["react", "react-dom", "@types/react", "@types/react-dom"]
i18n:
patterns: ["i18next*", "react-i18next"]
tauri:
patterns: ["@tauri-apps/*"]
ui:
patterns:
[
"radix-ui",
"@radix-ui/*",
"motion",
"cmdk",
"sonner",
"lucide-react",
"clsx",
"@fontsource*",
"react-router*",
"zustand",
]
cloudflare:
patterns: ["wrangler", "@cloudflare/*"]
# TypeScript 7 (`tsc`) and the TypeScript 6 API that typescript-eslint
# still needs, installed side by side as npm aliases (see package.json).
# Dependabot may not resolve `npm:` aliases — if no PR shows up for a new
# 7.x, bump both by hand.
typescript:
patterns: ["typescript", "@typescript/*"]
lint-and-format:
patterns: ["eslint*", "@eslint/*", "typescript-eslint", "prettier*", "knip"]
build-tooling:
patterns: ["vite", "vitest", "@vitejs/*", "tailwindcss", "postcss", "autoprefixer", "tsx"]
patterns:
[
"vite",
"vitest",
"@vitest/*",
"@vitejs/*",
"tailwindcss",
"@tailwindcss/*",
"postcss",
"autoprefixer",
"tsx",
"marked",
"@resvg/*",
]
testing:
patterns: ["@testing-library/*"]
types:
patterns: ["@types/*"]
ignore:
# Majors land in their own planned release (see docs/ROADMAP.md) because
# each one needs a real migration — React 19, Tailwind 4 and ESLint 10 all
# change APIs the app uses directly. Dependabot handles minor + patch.
# Majors land in their own planned release because each one needs a real
# migration (Vitest 5 is the current example). Dependabot handles minor +
# patch.
- dependency-name: "*"
update-types: ["version-update:semver-major"]
@@ -55,16 +105,19 @@ updates:
schedule:
interval: "weekly"
# No version-update PRs; this entry only feeds ignore rules to security
# updates. The Rust side is pinned to whatever tauri's tree allows.
# updates. The Rust side moves with tauri (see the note at the top).
open-pull-requests-limit: 0
cooldown:
default-days: 7
ignore:
- dependency-name: "rand"
- dependency-name: "glib"
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
cooldown:
default-days: 7
open-pull-requests-limit: 3
commit-message:
prefix: "ci"
+19 -9
View File
@@ -10,32 +10,42 @@ on:
required: true
type: string
# `link-discussion` needs `contents: write` (to edit the release) and
# `discussions: write` (so GitHub auto-creates the linked Discussion under
# the configured category). The reusable announce job only needs read.
permissions:
contents: write
discussions: write
contents: read
jobs:
link-discussion:
runs-on: ubuntu-latest
# `contents: write` edits the release; `discussions: write` lets GitHub
# auto-create the linked Discussion under the configured category.
permissions:
contents: write
discussions: write
steps:
- name: Link release to Announcements discussion
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# Via env, never interpolated into the script: a tag name is
# user-controlled text.
TAG: ${{ github.event.release.tag_name || inputs.tag }}
REPO: ${{ github.repository }}
# Setting --discussion-category on a published release causes
# GitHub to auto-create the linked Discussion. Requires the
# repo to have Discussions enabled with an "Announcements"
# category (configured manually under repo Settings).
run: |
gh release edit "${{ github.event.release.tag_name || inputs.tag }}" \
--repo "${{ github.repository }}" \
--discussion-category "Announcements"
gh release edit "$TAG" --repo "$REPO" --discussion-category "Announcements"
announce:
needs: link-discussion
permissions:
contents: read
uses: poli0981/.github/.github/workflows/announce-release.yml@main
with:
tag_override: ${{ inputs.tag || '' }}
secrets: inherit
# Only what the shared workflow declares — not `inherit`, which would hand
# every repository secret (Android signing keys included) to it.
secrets:
DISCORD_RELEASES_WEBHOOK: ${{ secrets.DISCORD_RELEASES_WEBHOOK }}
DISCORD_REPO_WEBHOOK: ${{ secrets.DISCORD_REPO_WEBHOOK }}
DISCORD_PING_ROLE_ID: ${{ secrets.DISCORD_PING_ROLE_ID }}
+49 -12
View File
@@ -2,7 +2,7 @@ name: CI
on:
push:
branches: [main, dev]
branches: [main]
pull_request:
branches: [main]
@@ -21,30 +21,46 @@ concurrency:
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
jobs:
# `check` is the required status on `main` (ruleset "main-protection") — keep
# the job id stable.
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
# Actions are pinned by commit SHA (a tag can be moved; a SHA cannot).
# Dependabot keeps the SHA and the version comment up to date.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
node-version: 22
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version-file: .node-version
cache: npm
- run: npm ci
# No dependency lifecycle scripts, in every workflow. The only packages
# that have one (esbuild, workerd, fsevents) take their native binary
# from optionalDependencies; the script only double-checks it.
- run: npm ci --ignore-scripts
# `tsc` must be TypeScript 7 (@typescript/native). The `typescript` alias
# (@typescript/typescript6, the API typescript-eslint loads) pulls in
# TypeScript 6 as @typescript/old, which ships a `tsc` too — npm links the
# first one by path order. Fail loudly if that ever flips, instead of
# silently type-checking with 6.
- name: TypeScript 7 is the `tsc` on PATH
run: ./node_modules/.bin/tsc --version | grep -q '^Version 7\.'
# --- correctness ------------------------------------------------------
# `typecheck` covers src/ (what Vite actually builds); `typecheck:all`
# adds tests/ and scripts/, which went unchecked until v0.35.0 and were
# hiding three silently-stale fixture fields.
# `typecheck` covers src/ (what Vite builds); `typecheck:all` adds tests/,
# scripts/, worker/ and build-plugins/.
- name: Type check (src)
run: npm run typecheck
- name: Type check (tests + scripts)
- name: Type check (tests, scripts, worker, build plugins)
run: npm run typecheck:all
- name: Lint
run: npm run lint
- name: Validate locales
run: npm run validate:locales
- name: Test
run: npm run test:run
# Coverage thresholds for src/engine and worker live in vitest.config.ts.
- name: Test (with coverage thresholds)
run: npm run test:coverage
# --- consistency ------------------------------------------------------
- name: Check formatting
@@ -55,11 +71,26 @@ jobs:
# thing that notices when one is missed — see scripts/check-version-sync.ts.
- name: Check version sync
run: npm run check:version
# tauri build refuses mismatched npm/crate minors, and CI never runs it.
- name: Check Tauri npm/crate alignment
run: npm run check:tauri
# --- licensing --------------------------------------------------------
# Every package bundled into the app has an allowed license, and
# THIRD_PARTY_NOTICES.md matches what is actually installed.
- name: Check licenses and third-party notices
run: npm run check:licenses
# NOTICE, REUSE.toml and the installers' copyright string state the
# years ("2026", later "2026-2027"). The first commit in a new year
# fails here until `npm run update:copyright` extends them.
- name: Check copyright years
run: npm run check:copyright
# --- security ---------------------------------------------------------
# Advisory-only: a fresh high-severity advisory in a transitive dep must
# not turn every unrelated PR red before Dependabot has had a chance to
# open its fix PR. The Dependabot alerts tab is the source of truth.
# open its fix PR. The Dependabot alerts tab is the source of truth, and
# dependency-review (security.yml) blocks PRs that *introduce* one.
- name: Audit dependencies
run: npm audit --audit-level=high
continue-on-error: true
@@ -67,3 +98,9 @@ jobs:
# --- build ------------------------------------------------------------
- name: Build
run: npm run build
- name: Check bundle budget
run: npm run check:bundle
# Validates wrangler.jsonc and bundles the Worker exactly as Workers
# Builds will — without deploying anything.
- name: Dry-run the Cloudflare deploy
run: npm run cf:check
+57
View File
@@ -0,0 +1,57 @@
name: Compliance
on:
pull_request:
branches: [main]
types: [opened, edited, synchronize, reopened]
push:
branches: [main]
permissions:
contents: read
concurrency:
group: compliance-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
jobs:
# REUSE (https://reuse.software): every file in the repo has a declared
# copyright holder and SPDX license — via REUSE.toml, not per-file headers.
# Fails when a file arrives that the annotations do not cover (e.g. a font
# or icon under another license) until REUSE.toml says what it is.
reuse:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: fsfe/reuse-action@676e2d560c9a403aa252096d99fcab3e1132b0f5 # v6.0.0
# PR titles follow the commit convention (`type(scope): message`) — merge
# commits carry them into main's history and the changelog.
pr-title:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
permissions:
pull-requests: read
steps:
- uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
types: |
feat
fix
refactor
perf
docs
test
ci
build
chore
revert
requireScope: false
subjectPattern: ^(?![A-Z]).+$
subjectPatternError: |
The subject "{subject}" should start with a lower-case letter, like
the rest of the history (e.g. "feat(editor): add next-part button").
-31
View File
@@ -1,31 +0,0 @@
name: Deploy to GitHub Pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run build
- uses: actions/configure-pages@v6
- uses: actions/upload-pages-artifact@v5
with:
path: dist
- id: deployment
uses: actions/deploy-pages@v5
+7 -4
View File
@@ -2,9 +2,10 @@ name: Notify CI Failures
on:
workflow_run:
# Match the exact `name:` of the CI workflow (.github/workflows/ci.yml).
# Renaming CI silently breaks this filter — keep them in sync.
workflows: ["CI"]
# Match the exact `name:` of each watched workflow (ci.yml, security.yml,
# compliance.yml, rust.yml). Renaming one silently breaks this filter —
# keep them in sync.
workflows: ["CI", "Security", "Compliance", "Rust"]
types: [completed]
# REQUIRED: declare permissions matching the reusable workflow's needs.
@@ -16,4 +17,6 @@ permissions:
jobs:
notify:
uses: poli0981/.github/.github/workflows/notify-ci-failure.yml@main
secrets: inherit
# Only the webhook the shared workflow declares — not `inherit`.
secrets:
DISCORD_CI_WEBHOOK: ${{ secrets.DISCORD_CI_WEBHOOK }}
-18
View File
@@ -1,18 +0,0 @@
name: Notify Deploy Status
on:
workflow_run:
# Match the exact `name:` of the deploy workflow
# (.github/workflows/deploy-web.yml). Renaming it silently breaks this
# filter — keep them in sync.
workflows: ["Deploy to GitHub Pages"]
types: [completed]
permissions:
contents: read
actions: read
jobs:
notify:
uses: poli0981/.github/.github/workflows/notify-deploy.yml@main
secrets: inherit
@@ -15,4 +15,6 @@ permissions:
jobs:
notify:
uses: poli0981/.github/.github/workflows/notify-release-pipeline.yml@main
secrets: inherit
# Only the webhook the shared workflow declares — not `inherit`.
secrets:
DISCORD_RELEASE_PIPELINE_WEBHOOK: ${{ secrets.DISCORD_RELEASE_PIPELINE_WEBHOOK }}
+38
View File
@@ -0,0 +1,38 @@
name: Pages migration notice
# The app moved to https://ytgenerator.stream. What used to be the GitHub
# Pages site (poli0981.github.io/youtube-generator) is replaced by a single
# static page that hands visitors the data their browser saved there — as a
# backup file the new site restores — and points them to the new address.
#
# Run by hand once; the page is removed on 2026-11-29 together with this
# workflow and the github-pages environment (tracked in an issue).
on:
workflow_dispatch:
permissions: {}
concurrency:
group: pages
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: migration-page
- id: deployment
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+77 -28
View File
@@ -6,51 +6,80 @@ on:
workflow_dispatch:
inputs:
tag:
description: "Tag to build (e.g. v0.29.0). The manifests must already carry this version."
description: "Tag to build (e.g. v1.0.0). The manifests must already carry this version."
required: true
type: string
permissions:
contents: write
contents: read
jobs:
build-android:
# Same gate as release-desktop.yml: never sign an APK for a tag whose code
# fails the checks or whose version fields disagree with the tag.
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.inputs.tag || github.ref }}
- uses: actions/setup-node@v6
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
cache: npm
node-version-file: .node-version
# Release artifacts are built from a clean install: a cache written
# by any other workflow must not be able to feed into them.
package-manager-cache: false
- run: npm ci --ignore-scripts
- run: npm run typecheck
- run: npm run test:run
- run: npm run check:version
- run: npm run check:tauri
- name: Tag matches the manifests
env:
TAG: ${{ github.event.inputs.tag || github.ref_name }}
run: |
version="v$(node -p "require('./package.json').version")"
if [ "$version" != "$TAG" ]; then
echo "::error::Tag $TAG does not match package.json ($version)"
exit 1
fi
- uses: actions/setup-java@v5
build-android:
needs: verify
runs-on: ubuntu-latest
permissions:
contents: write # upload the APK to the draft release
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.inputs.tag || github.ref }}
persist-credentials: false
# No dependency caches in a release job (see release-desktop.yml).
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version-file: .node-version
# Release artifacts are built from a clean install: a cache written
# by any other workflow must not be able to feed into them.
package-manager-cache: false
- uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
with:
distribution: temurin
java-version: "17"
- uses: android-actions/setup-android@v4
- uses: android-actions/setup-android@be39fa834029ff78f1a44aa3bb0819b8fc2bd8fd # v4.0.4
- name: Install Android NDK (r27 LTS)
run: sdkmanager "ndk;27.3.13750724"
- uses: dtolnay/rust-toolchain@stable
# A master commit, not the regenerated `stable` branch — see rust.yml.
- uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8
with:
toolchain: stable
targets: aarch64-linux-android,armv7-linux-androideabi,i686-linux-android,x86_64-linux-android
- name: Cache cargo
uses: actions/cache@v5
with:
path: |
~/.cargo/registry
~/.cargo/git
src-tauri/target
key: ${{ runner.os }}-android-cargo-${{ hashFiles('src-tauri/Cargo.lock') }}
- run: npm ci
- run: npm ci --ignore-scripts
- name: Install Tauri CLI
run: cargo install tauri-cli --version "^2" --locked
@@ -79,11 +108,31 @@ jobs:
NDK_HOME: ${{ env.ANDROID_HOME }}/ndk/27.3.13750724
run: cargo tauri android build --apk
- name: Upload APK to draft release
uses: softprops/action-gh-release@v3
# Keep the APK regardless of whether the release upload works, so a
# broken upload never costs a 20-minute rebuild.
- name: Upload APK as workflow artifact
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
tag_name: ${{ github.event.inputs.tag || github.ref_name }}
draft: true
files: src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk
name: ytdescgen-android-apk
path: src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk
if-no-files-found: error
# Uses `gh` (pre-installed on every runner) rather than a third-party
# action. `softprops/action-gh-release@v3` resolved the target release
# from GITHUB_REF instead of the `tag_name` it was given, so on a tag push
# it looked for a release tagged `refs/tags/v0.35.0` and on a
# workflow_dispatch it looked for one tagged `refs/heads/main` — neither
# exists, so it tried to CREATE a release on a branch ref and got
# "Resource not accessible by integration". The v0.35.0 APK was built
# three times before this was pinned down.
#
# `gh release upload` takes the tag as a positional argument and cannot
# make that mistake. `--clobber` makes a re-run idempotent.
- name: Upload APK to draft release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ github.event.inputs.tag || github.ref_name }}
REPO: ${{ github.repository }}
APK: src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk
run: |
gh release upload "$TAG" "$APK" --clobber --repo "$REPO"
+49 -9
View File
@@ -10,15 +10,48 @@ on:
workflow_dispatch:
inputs:
tag:
description: "Tag to build (e.g. v0.9.0). The job still expects the manifests to already carry this version."
description: "Tag to build (e.g. v1.0.0). The job still expects the manifests to already carry this version."
required: true
type: string
permissions:
contents: write
contents: read
jobs:
# Nothing gets built for a tag whose code does not pass the gate or whose
# six version fields disagree with the tag itself.
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.inputs.tag || github.ref }}
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version-file: .node-version
# Release artifacts are built from a clean install: a cache written
# by any other workflow must not be able to feed into them.
package-manager-cache: false
- run: npm ci --ignore-scripts
- run: npm run typecheck
- run: npm run test:run
- run: npm run check:version
- run: npm run check:tauri
- name: Tag matches the manifests
env:
TAG: ${{ github.event.inputs.tag || github.ref_name }}
run: |
version="v$(node -p "require('./package.json').version")"
if [ "$version" != "$TAG" ]; then
echo "::error::Tag $TAG does not match package.json ($version)"
exit 1
fi
build:
needs: verify
permissions:
contents: write # create the draft release and upload the binaries
strategy:
fail-fast: false
matrix:
@@ -52,17 +85,24 @@ jobs:
bundleArgs: ""
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v6
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# On `workflow_dispatch` checkout the requested tag; on a
# tag push we already get the tag commit by default.
ref: ${{ github.event.inputs.tag || github.ref }}
- uses: actions/setup-node@v6
persist-credentials: false
# No dependency caches in a release job: a poisoned cache entry written
# by any other workflow would otherwise flow straight into the binaries.
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
cache: npm
- uses: dtolnay/rust-toolchain@stable
node-version-file: .node-version
# Release artifacts are built from a clean install: a cache written
# by any other workflow must not be able to feed into them.
package-manager-cache: false
# A master commit, not the regenerated `stable` branch — see rust.yml.
- uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8
with:
toolchain: stable
targets: ${{ matrix.target }}
- name: Install Linux dependencies
if: matrix.os == 'ubuntu-latest'
@@ -74,8 +114,8 @@ jobs:
libayatana-appindicator3-dev \
librsvg2-dev \
patchelf
- run: npm ci
- uses: tauri-apps/tauri-action@v0
- run: npm ci --ignore-scripts
- uses: tauri-apps/tauri-action@1deb371b0cd8bd54025b384f1cd735e725c4060f # v1.0.0
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# AppImage bundling on hosted runners flakes: linuxdeploy (itself
+78
View File
@@ -0,0 +1,78 @@
name: Rust
# The Tauri shell changes rarely, so this only runs when it does (or weekly,
# to catch new RustSec advisories). Not a required check for that reason.
on:
pull_request:
branches: [main]
paths:
- "src-tauri/**"
- ".github/workflows/rust.yml"
push:
branches: [main]
paths:
- "src-tauri/**"
- ".github/workflows/rust.yml"
schedule:
- cron: "41 4 * * 1"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: rust-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
jobs:
lint-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install Linux dependencies
run: |
sudo apt-get update
sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev \
libayatana-appindicator3-dev librsvg2-dev patchelf
# Pinned to a commit on master, with the toolchain passed explicitly: the
# action's `stable` branch is regenerated from master, which orphans any
# SHA pinned there (zizmor: impostor-commit). Master keeps its history.
- uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8
with:
toolchain: stable
components: rustfmt, clippy
- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
with:
workspaces: src-tauri
# tauri::generate_context!() embeds the frontend at compile time, so
# clippy and the tests need a built dist/.
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version-file: .node-version
cache: npm
- run: npm ci --ignore-scripts
- run: npm run build
- name: rustfmt
working-directory: src-tauri
run: cargo fmt --all -- --check
- name: clippy
working-directory: src-tauri
run: cargo clippy --all-targets --locked -- -D warnings
- name: test
working-directory: src-tauri
run: cargo test --locked
# RustSec advisories, license allowlist, duplicate/banned crates and
# registry sources for the whole crate tree (src-tauri/deny.toml).
cargo-deny:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: EmbarkStudios/cargo-deny-action@3c6349835b2b7b196a839186cb8b78e02f7b5f25 # v2.1.1
with:
manifest-path: src-tauri/Cargo.toml
command: check advisories licenses sources
+87
View File
@@ -0,0 +1,87 @@
name: Security
on:
pull_request:
branches: [main]
push:
branches: [main]
schedule:
# Mondays 04:17 UTC — new advisories and Scorecard drift surface weekly
# even when nothing is being merged.
- cron: "17 4 * * 1"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: security-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
jobs:
# Blocks a PR that ADDS a dependency with a known high/critical advisory.
# Licenses are checked by `npm run check:licenses` (ci.yml) instead: the
# dependency graph's license data is patchy for npm and would flag noise.
dependency-review:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
with:
fail-on-severity: high
license-check: false
# Lint the workflows themselves: syntax/expressions (actionlint) and
# security smells — template injection, over-broad permissions, credential
# persistence, unpinned actions (zizmor, config in .github/zizmor.yml).
workflow-lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: actionlint
uses: docker://rhysd/actionlint:1.7.12
with:
args: -color
- name: zizmor
uses: zizmorcore/zizmor-action@85b2b9fb8e3325e7a23d7d0a9d7ba5ae0f999e3e # v0.7.1
with:
# Report in the log and fail the job; no SARIF upload, so findings
# are fixed in the PR instead of piling up as code-scanning alerts.
advanced-security: false
min-severity: medium
# OpenSSF Scorecard: supply-chain posture (pinned deps, token permissions,
# branch protection …). Informational — results go to the job summary and
# scorecard.dev, not to code scanning.
scorecard:
if: github.event_name != 'pull_request'
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write # publish_results: signs the result for scorecard.dev
actions: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
with:
results_file: scorecard.json
results_format: json
publish_results: true
- name: Summarise
run: |
{
echo "### OpenSSF Scorecard"
echo
echo "| Check | Score |"
echo "| --- | --- |"
jq -r '.checks[] | "| \(.name) | \(.score) |"' scorecard.json
echo
echo "Aggregate: **$(jq -r '.score' scorecard.json) / 10**"
} >> "$GITHUB_STEP_SUMMARY"
+20
View File
@@ -0,0 +1,20 @@
# zizmor (workflow security linter) configuration — see security.yml.
rules:
unpinned-uses:
config:
policies:
# The shared notification / announcement workflows live in the
# maintainer's own `poli0981/.github` repository and are deliberately
# tracked at `main`, so a fix there reaches every repo at once.
"poli0981/*": any
# Everything else must be pinned to a full commit SHA.
"*": hash-pin
dangerous-triggers:
ignore:
# Both run on `workflow_run` so a failure (or a release build) anywhere
# can be reported to Discord. Neither checks out the triggering run's
# code nor downloads its artifacts: the shared workflows only read run
# metadata, and pass every untrusted field (branch, commit message,
# actor) to the notifier script through `env:`, never by interpolation.
- notify-ci-failure.yml
- notify-release-pipeline.yml
+11
View File
@@ -22,3 +22,14 @@ src-tauri/gen/android/.gradle/
src-tauri/gen/android/.idea/
src-tauri/gen/android/build/
src-tauri/gen/android/app/build/
# Cloudflare (wrangler dev / dry runs)
.wrangler/
.dev.vars
.dev.vars.*
!.dev.vars.example
# Maintainer's local notes and Python caches — never committed (CLAUDE.md)
note.txt
warning.txt
__pycache__/
+1
View File
@@ -0,0 +1 @@
26
+194
View File
@@ -2,6 +2,200 @@
All notable changes to YTDescGen ship as tagged releases on `main`.
## v1.2.0 — 2026-10-12
Say when a game is **made with AI**: a new group of content warnings for AI-generated game content, three more disclosures, and the docs, notices and wiki brought back in line with the app. Web, desktop and Android all ship as 1.2.0.
### Added
- **AI-generated content** — a new content-warning group, the thirteenth, for games that are made or run with generative AI (a story _about_ AI is still "AI / artificial intelligence themes"):
- AI-generated content (general) · AI art / visuals · AI / synthetic voices · AI music / sound · AI-written text / dialogue
- **Generated live by AI while playing** — the game makes content as you play, so a viewer's own run may differ
- **AI use disclosed by the developer** — the store page says so (Steam shows an "AI Generated Content Disclosure"), so viewers know you aren't guessing
The split follows Steam's AI disclosure: content made with AI during development and shipped, and content an AI generates while the game runs. Machine translation stays a playthrough note (**Language patch → Machine translation**). YouTube doesn't ask for gameplay footage to be labelled as altered or synthetic — these lines are for viewers. In all eight output languages, next to the English line like every warning.
- **Simulated gambling** (Mature / Sensitive) and **In-game purchases** (Internet / Digital life, next to loot boxes) — the two ESRB / PEGI descriptors that had no warning.
- **Tech note: Upscaling / frame-gen artifacts** (Video quality) — "Possible upscaling / frame-generation artifacts (DLSS, FSR, XeSS)". Which upscaler and frame generation were on is already the 🖥 Video settings line; the note only warns about what they do to the footage.
257 content warnings in 13 groups, 25 tech notes — all listed in [docs/CONTENT-INVENTORY.md](docs/CONTENT-INVENTORY.md).
### Changed
- **Third-party notices** said the app uses the operating system's fonts; it bundles **Inter** and **JetBrains Mono** (OFL-1.1), and now says so. The Rust table lists every direct crate — `serde` was missing — and a crate with no known license stops the generator ([scripts/lib/third-party.ts](scripts/lib/third-party.ts)).
- **REUSE**: the Gradle wrapper under `src-tauri/gen/android/` is credited to Gradle's authors, not to the project.
- **Privacy Policy** (Effective 2026-10-12) lists the one `sessionStorage` flag, `ytdescgen-chunk-reload`, next to the `localStorage` keys. Not a material change: nobody is asked to accept the terms again.
- **Security policy**: 1.2.x is the supported version.
- **Docs**: README (contact emails by purpose, themes and scrollbars, installer sizes, the Android build step), ROADMAP (1.1.0 and 1.2.0; finished items checked off), PACKAGING (the installers' copyright, the yearly `update:copyright`, v1.1.0 sizes, `tauri info`), ARCHITECTURE and TECH-SPEC (purpose-word validation, versions, test count), FEATURES, I18N, CONTENT-INVENTORY + Vietnamese (now with the tech notes), CONTRIBUTING and the PR template (the full gate list), the issue templates, DISCLAIMER + Vietnamese, CLAUDE.md. `webapp/TAURI.md` (Node 25, no `.rpm`) is folded into PACKAGING and removed.
- **Wiki**: Home (1.2.0, what's new in 1.1 and 1.2), Field Reference (warnings and tech notes, the copyright / DMCA line and purpose words, Hide scrollbars), FAQ ("How do I say a game uses AI-generated content?"), Release Process (copyright years, the wiki step, the rust-toolchain pin).
### Under the hood
- No store version bump: the warning and tech-note lists only grow. The backup whitelist checks ids against them, so a 1.2.0 backup restores on 1.1.0 without the new ids.
- **A test fails when a content warning or tech note has no editor label or description line** in `_schema.json` — and so, through `validate:locales`, in any locale. Until now a missing key showed the raw key in the editor and silently dropped the line from the description. Tech notes also get the group-parity test content warnings already had.
- New strings in all eight locales (1,264 UI + 584 template keys each).
- typecheck, typecheck:all, lint, format:check, validate:locales, knip, check:version, check:tauri, check:licenses, check:copyright, **984 tests**, build and `cargo fmt` / `clippy` / `test` all pass; initial load 275.2 of 280 KB gzip. Verified live in the browser: the new group and its search, pick order in the description, the bilingual English · Vietnamese lines and the tech note.
- `.gitignore` covers the maintainer's local `note.txt`, `warning.txt` and `__pycache__/`.
- Six manifests bumped 1.1.0 → 1.2.0.
## v1.1.0 — 2026-10-03
A small release: a **copyright email** and **purpose words** for the split contact block, an option to **hide scrollbars**, and copyright years that keep themselves current. Web, desktop and Android all ship as 1.1.0.
### Added
- **Copyright / DMCA email.** With Settings › _Split contact email by purpose_ on, the contact block gains a fourth line, `©️ Copyright / DMCA: …`, in all eight output languages. It is saved with the channel profile.
- **Purpose words before the @.** In split mode every purpose address has to say what it is for: the part before `@` must contain one of the field's words ([src/config/contact-emails.ts](src/config/contact-emails.ts)), in any case and anywhere, so Gmail's `name+dmca@gmail.com` works.
- Advertising / sponsorship: sponsor, ads, advert, business, biz, partner, collab, brand, marketing, promo
- Game keys & playtest: key, game, gaming, press, media, review, playtest, beta, curator
- Copyright / DMCA: dmca, takedown, copyright, legal, rights, claim
A missing word is an error like a malformed address: the value is not saved, and Strict Mode blocks. The help text under each field lists its words. The general Contact address has no rule.
- **Hide scrollbars** (Settings › Appearance). No scrollbar anywhere in the app — the mouse wheel, touchpad, touch and keyboard still scroll. Off by default; it travels with backups, like the theme.
### Changed
- **Addresses saved before this release** in the advertising or game-keys field are left exactly as they are. If one has no purpose word, Strict Mode points at it — edit it, or use the `name+sponsor@gmail.com` form.
- The Spanish example addresses now carry a purpose word (`sponsors@`, `games@`).
- **The desktop installers carry a copyright string**, `Copyright 2026 poli0981 (SkullMute)`. The Windows `.exe` / NSIS copyright field, the macOS `Info.plist` and the Linux packages had none.
### Under the hood
- **Copyright years, checked.** 2026 is right everywhere — the first commit is from 2026-04-07, so there was no 2025 to correct. [src/config/brand.ts](src/config/brand.ts) now owns the start year and `copyrightYears()`. **`npm run check:copyright`** (in CI) holds NOTICE, REUSE.toml and the installers' copyright string to the year of HEAD's commit — "2026", then "2026-2027" from the first commit of 2027 — and **`npm run update:copyright`** rewrites them. The `/legal` pages' footer prints the same range.
- **CI**: `dtolnay/rust-toolchain` is pinned to a commit on its master branch. Its `stable` branch is regenerated upstream, which orphaned the old pin and turned `workflow-lint` (zizmor: impostor-commit) red on every pull request.
- Editor store v19 → v20 (`copyrightEmail`, additive), so a backup's draft made by 1.1.0 needs 1.1.0 to restore; everything else in it still restores on 1.0.0. `hideScrollbars` joins the settings without a version bump.
- New strings in all eight locales (1,253 UI + 574 template keys each).
- typecheck, typecheck:all, lint, format:check, validate:locales, knip, check:version, check:licenses, check:copyright, **968 tests** and build all pass; verified live in the browser — the purpose-word errors and Strict Mode, the copyright line in the description, and the scrollbar toggle (on, off, after a reload).
- Six manifests bumped 1.0.0 → 1.1.0.
## v1.0.0 — 2026-09-30
**YTDescGen moves to [ytgenerator.stream](https://ytgenerator.stream)**, gets a new interface, and the data it writes is right: hardware names, YouTube's own tag count, chapters, history. Backups you can preview and undo, a quick start for the next video, and a hardened desktop app. Web, desktop and Android all ship as 1.0.0.
### Moving house
- **The web app lives at [ytgenerator.stream](https://ytgenerator.stream)**, served by a Cloudflare Worker that Cloudflare builds and deploys from `main` (`wrangler.jsonc` is the only Cloudflare file). GitHub Pages is retired: until **2026-11-29** the old address shows a moving notice that **downloads the data your browser saved there as a backup file** — restore it on the new site in Settings › Backup & restore. See [Moving from GitHub Pages](https://github.com/poli0981/youtube-generator/wiki/Moving-from-GitHub-Pages).
- **A Cloudflare Turnstile check** (usually invisible) runs once a day before the web app loads. The token is verified server-side; a signed, `HttpOnly` `__Host-` cookie remembers the pass for 24 hours. Agreeing to the terms on that page counts, so web visitors see one screen, not two.
- **Legal pages in the site**: Terms, Privacy, Disclaimer (+ Vietnamese), Security, License, Notice, Code of Conduct and third-party notices are rendered at build time — public and crawlable at `/legal/*`, and offline in the app's Legal Center. The Privacy Policy was rewritten for Cloudflare hosting, Turnstile and Web Analytics, so everyone accepts the terms once more (**terms version 2**).
- **Cloudflare Web Analytics** (cookieless) in the web build only; the desktop and Android apps have no analytics.
- Security headers on everything (CSP per page type, COOP/CORP, frame and referrer policies), `/.well-known/security.txt`, HSTS preload at the edge, clean URLs on the web (old `/#/…` links still work).
- **New contacts** by purpose: contact@, security@, privacy@, legal@, dmca@, copyright@, code@ and sponsor@ poli0981.dev, plus [poli0981.dev](https://poli0981.dev/) and [poli0981.dev/links](https://poli0981.dev/links/). The dead Discord invite is gone.
- **Brand**: one logo drives the favicon, PWA icons, link-preview card and every desktop/Android icon — the apps used to ship a plain purple square.
### New interface
- **Design system** on Radix primitives, Motion and sonner: consistent dark and light themes, self-hosted Inter/JetBrains Mono (with Vietnamese), compact controls (larger on touch screens), animated icons that respect _reduce motion_, real focus handling in dialogs, labelled controls.
- **App shell**: collapsible sidebar, a top bar with the output and interface languages, a **bottom bar on phones**, and a **⌘/Ctrl + K command palette** (navigate, copy, apply profile/preset/template, theme, languages, help).
- **Editor**: a **sticky live preview** beside the form (a sheet on phones), sections in the order a video is filled in, a searchable genre picker, collapsed sections that show a summary.
- **Output**: a **YouTube preview** — the title where search results cut it and the description above "…more".
- Every page restyled; hard-coded English translated; flag emoji (which Windows shows as letters) replaced by language names.
- Desktop window resizable (1280×820 by default).
### Data that is right
- **Hardware names**: _NVIDIA GeForce RTX 5080_ (was "NVIDIA RTX 5080"), _AMD Radeon RX 9070 XT_, _Apple M4 Pro_, laptop GPUs named as such. One **searchable GPU picker** replaces Brand › Series › Model; cards that never shipped are gone; laptop, integrated, handheld and Apple M5 chips added. RAM gains 24/48/192 GB, LPDDR and speeds ("32 GB DDR5-6000"); OS lists SteamOS, Bazzite, CachyOS and current Fedora/macOS; pasted Windows CPU names are tidied. Old saved values are migrated. The rig block is labelled in the output language, in a fixed order.
- **Tags counted the way YouTube counts them** (quotes around multi-word tags, commas between them): 15 of 51 real tag sets were over 500 while showing as under. Trimming keeps trying shorter tags; platform names read "Steam", "itch.io".
- **Chapters**: "Final Fantasy VII" no longer turns into "Ending Fantasy VII"; `[0:00]` and frame-accurate times are read; a live check shows whether YouTube will show chapters (0:00 first, at least 3, ≥ 10 s apart) and **Tidy up** rewrites pasted lists.
- **History** keeps one entry per video (every Output visit used to add one).
- **Copy** is blocked only for the field that is over its limit; Ctrl/⌘+Shift+C follows the same rules as the Output page.
- Warnings for `<` and `>` (YouTube rejects them); validation accepts real variants (Steam `/sub/` and `s.team`, regional Nintendo sites, `m.`/`www.` links, playlist links from phones) and rejects email domains without a TLD.
- **An empty channel name** no longer leaves "…of Hades on ." — the phrase is dropped in all eight languages.
### Backup & restore
- **Settings › Backup & restore**: back up everything (or chosen parts) to one file, restore from a file or by dropping it. Files from every earlier version are read — v0.15–v0.38 exports, pre-v0.15 arrays, the old desktop data file — and run through the same migrations the app uses, then a strict whitelist.
- **Preview before anything changes**: new / already here / different, per item; **Merge** (keep the newer one, or both) or **Replace**; one step, with **Undo**. Settings never carry your consent or panel state.
- **Automatic backups on desktop**: the newest ten, written after your library changes (and before every restore); restore them from Settings.
- History exports as **CSV** or JSON; exports carry the date in their names.
- Templates save **every** editor field; presets save store link types and all per-game fields; profiles save donate and community links. Edit forms can update from the current editor and save on Enter.
### Faster data entry
- **Quick start** at the top of the editor: pick the **channel profile** and the **game preset** (remembered); replacing filled-in fields asks first; "Update profile/preset" appears when the editor drifts from them.
- **Next part** and **New video, same game** clear what belonged to the last video; applying a preset for another game does too. **Start over** keeps your channel; a new draft starts in your **Default Output Language** (it always started in English).
- **Paste a store link anywhere** — it lands in the right store field, sets the platform and names the game ("Final Fantasy VII Remake", "Baldur's Gate 3"). Game-name suggestions from presets and history.
- **Title shapes**: the alternatives dialog can apply one; new **Title order** setting (game first / video first).
- **Copy All can include the tags**; **Batch** chooses Part or Demo part and continues from your part number; **Ctrl/⌘+S** saves the output to History.
### Catalogs
- Stores: EA app, Ubisoft, Battle.net, Google Play, App Store, Meta Quest.
- Social links: YouTube, Threads, Kick, Reddit, Bilibili; "X (Twitter)" with the X mark.
- Cross-posting: **YouTube Shorts, X** (counted the way X counts), **Threads, Bluesky**.
- Vietnamese banks: MBV, VCBNeo, Vikki Bank (formerly OceanBank, CBBank, DongA Bank — saved old names get a one-click switch), Cake by VPBank, Timo.
### Desktop
- **The webview can no longer name a path.** The five commands that read, wrote, listed and deleted any path it sent are replaced by name-only commands under the app's data folder and by Save/Open dialogs run from Rust (text formats only, size-capped). The fs and shell plugins are removed.
- **The settings "mirror" file never worked**: it was written next to the data folder and never read back. It is gone; on first start the old file becomes a restorable backup (never applied on its own) and stray log files are moved into place.
- One tray icon, with the app icon.
### Under the hood
- CI: dependency review, actionlint + zizmor, OpenSSF Scorecard, REUSE, Conventional-Commit titles, rustfmt/clippy/cargo test/cargo-deny, coverage thresholds, a measured bundle budget (initial load ≤ 280 KB gzip), licence allow-list and generated third-party notices, `wrangler deploy --dry-run`; every action pinned by SHA; release builds verify first.
- Dependencies current (React 19.3, Vite 8.3, Tauri 2.12); `npm audit` clean; Tauri 2.12 dropped the `rand` advisory; cargo-deny caught and fixed two `quick-xml` advisories.
- New strings in all eight locales (Japanese, Spanish, Korean, Chinese, Portuguese and Indonesian are AI-translated — see the Disclaimer).
- 930+ tests (was 698).
## v0.38.0 — 2026-08-17
Two new languages: **Portuguese (Brazil)** and **Indonesian**. Brazil is a
top-three market for gameplay viewing and Indonesia the largest in Southeast
Asia; both use Latin script, so neither needed font or layout work.
### Added
- **`pt-BR` and `id` locales** — 1,562 strings each. Both are complete: titles, every description block, all 248 content warnings, tech notes, playthrough notes, pinned comments, playlist copy, and the whole interface from the editor through Settings, Batch, Social and Logs.
- **Per-language tag pools** ([src/engine/tag-generator.ts](src/engine/tag-generator.ts)) — `CORE_TAGS_BY_LANG` and `MULTILINGUAL_TAGS` gained entries for both, so a Brazilian video gets `gameplay sem comentários` and `detonado` rather than falling back to English tags.
- **Region-aware browser detection** ([src/store/settings-heal.ts](src/store/settings-heal.ts)) — `detectBrowserLanguage` now matches the full BCP-47 tag before the bare language, or `pt-BR` would be reduced to `pt` and never found. Any other Portuguese variant also resolves to `pt-BR` rather than falling through to English.
### Fixed
- **`docs/I18N.md` was wrong about what registering a locale takes.** It said `SUPPORTED_LANGUAGES` was "the only registration step". It is one of four, and they fail differently: the `SupportedLanguage` union and the two tag-pool records are compile errors, but `detectBrowserLanguage`'s own hardcoded copy of the list fails **silently** — the language works and simply never auto-selects for a visitor whose browser is set to it. `SUPPORTED_LANGUAGES` is also not type-bound to the union, and every consumer casts, so a mismatch between the first two compiles cleanly. Corrected, and `SUPPORTED_LANGUAGES` now carries a `satisfies` clause that binds it to the union.
- **`__dirname` in the Vite and Vitest configs** replaced with `import.meta.dirname`. Vite 8's native config loader — planned to become the default — doesn't provide the CJS global, and warned on every run.
### Under the hood
- **New guard: [tests/i18n/locale-registration.test.ts](tests/i18n/locale-registration.test.ts)** checks the picker list against the locale directories on disk *in both directions*, plus namespace files, flags, native names and tag pools. It exists specifically to close the two registration gaps that fail silently.
- 115 UI keys were not hand-translated at all — their English text is byte-identical to a string already translated in `templates.json` (graphics presets, ray-tracing modes, difficulty names, content-warning labels), so they are copied across. Translating those twice risks a checkbox and the rendered description disagreeing about what the same option is called.
- Left as English on purpose, matching what the Spanish locale already does: vendor product names (NVIDIA DLSS, AMD FSR, Intel XeSS, Fluid Motion Frames), platform brands (Ko-fi, Patreon, Discord, Steam, TikTok), hardware acronyms (CPU, GPU, RAM), genre terms that are loanwords in both languages (RPG, FPS, MMO, Indie, Metroidvania, Roguelike, Battle Royale), and example URLs / emails in placeholders. **pt-BR 1,344 / 1,562 and id 1,308 / 1,562 strings differ from English**; the remainder are those pass-throughs, not gaps.
- Both are **AI-translated and not native-reviewed** — recorded in [DISCLAIMER.md](DISCLAIMER.md) alongside JA / ES / KO / ZH. Native-speaker corrections are the most welcome contribution to this project; `src/i18n/locales/<code>/*.json` can be edited straight from GitHub's web UI.
- Validator now **1,562 keys × 8 locales**. typecheck, typecheck:all, lint, format:check, validate:locales, knip, check:version, **698 tests** and build all pass; verified live in the browser — both languages appear in every picker, generate correctly translated titles and descriptions, and translate the interface itself.
- Six manifests bumped 0.37.0 → 0.38.0. (v0.36.0 was skipped: the dependency release shipped first and had already taken 0.37.0.)
## v0.37.0 — 2026-08-17
A **dependency modernization** release. No user-facing feature changes; the app
should behave identically. Every major the project had been sitting on is now
current, and the two new lint rules that came with them found four real
performance bugs.
### Changed
- **React 18 → 19**, `@types/react` 19, `@vitejs/plugin-react` 6. One source change: React 19 types `useRef<T>(null)` as `RefObject<T | null>` rather than `RefObject<T>` — the old type quietly claimed a ref was non-null before its element mounted. [ScrollToTopButton](src/components/layout/ScrollToTopButton.tsx) now matches, which keeps its existing null check honest.
- **Tailwind 3 → 4** ([src/styles/globals.css](src/styles/globals.css)) — configuration moves from `tailwind.config.ts` (deleted) into CSS. The design tokens live in an `@theme` block that maps Tailwind's names onto the existing `:root` / `.light` variables, so the runtime theme toggle keeps working exactly as before. `darkMode: "class"` becomes `@custom-variant dark`, because the app toggles a class on `<html>` rather than following the OS. PostCSS now loads `@tailwindcss/postcss`. Verified in the browser in both themes.
- **ESLint 9 → 10** + `eslint-plugin-react-hooks` 5 → 7, which enables the React Compiler diagnostics.
- **Zustand 4 → 5**, **i18next 23 → 26**, **react-i18next 15 → 17**, `@testing-library/*`, `typescript-eslint` 8.67, plus the Vite / Vitest / tsx / knip / Tauri-plugin patch line.
### Fixed
The new `react-hooks/set-state-in-effect` rule flagged seven call sites. Four were real extra render passes and are fixed:
- **[use-online-status](src/hooks/use-online-status.ts)** rewritten to `useSyncExternalStore`. It was re-reading `navigator.onLine` inside an effect to close the gap between the first render and the listeners attaching — subscribing properly removes the gap rather than patching it, and costs one render fewer on every mount.
- **[ShortcutHelpModal](src/components/ui/ShortcutHelpModal.tsx)** derives its filter from `open` instead of resetting state in an effect, so a modal that spends most of its life closed no longer schedules work on unrelated parent updates.
- **[DraftIndicator](src/components/editor/DraftIndicator.tsx)** and **[use-languages-ready](src/hooks/use-languages-ready.ts)** now guard their setters.
Three remain as **warnings**, deliberately: they genuinely sync state *from* an external source (i18next bundle readiness, a text mirror of a numeric store field, and a `useMemo` the compiler can't preserve). Each needs a restructure rather than a guard, so they are recorded in [eslint.config.js](eslint.config.js) rather than silenced or used as a reason to hold back the upgrade.
### Not upgraded
- **`lucide-react` stays at 0.577.0.** 1.x removes every brand icon (Instagram, Facebook, GitHub, YouTube, X) — upstream dropped them for trademark reasons. Taking 1.x would mean either a generic globe next to a Facebook link, or re-adding the marks ourselves and inheriting the exposure lucide just shed. Neither is worth it: 0.577 already delivered the win, cutting the main bundle **175 kB → 137 kB**.
### Under the hood
- `knip` now ignores `tailwindcss`, whose only reference after the migration is `@import "tailwindcss"` in CSS — which knip doesn't follow.
- Full gate green: typecheck, typecheck:all, lint, format:check, validate:locales, knip, check:version, **692 tests**, build. Verified live in the browser: both themes render, icons intact, editor and batch functional.
- Six manifests bumped 0.35.0 → 0.37.0. (0.36.0 is reserved for the two new locales.)
## v0.35.0 — 2026-08-17
A **guardrails** release. Four things the app quietly let you do wrong — publish
+135 -258
View File
@@ -1,300 +1,177 @@
# CLAUDE.md — YouTube Description Generator (YTDescGen)
# CLAUDE.md — YTDescGen
## Project Overview
**YTDescGen** is a desktop-capable web application that generates YouTube video titles, descriptions, and tags for Gameplay No Commentary channels. It supports multiple languages, game genres, and video types with a profile/preset system to eliminate repetitive data entry.
**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.
- **Repository**: `github.com/poli0981/youtube-generator`
- **License**: Apache-2.0 (see `LICENSE` + `NOTICE`)
- **Primary Language**: TypeScript
- **Stack**: React 18 + Vite 8 + Tailwind CSS 3 + Zustand + Tauri 2 (desktop)
- **Target Platforms**: Web (GitHub Pages), Desktop (Windows/macOS/Linux via Tauri)
- **Web app**: <https://ytgenerator.stream> — 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.
## Tech Stack
| Layer | Technology | Why |
|-------|-----------|-----|
| Framework | React 18 | Familiar from F2P tracker dashboard |
| Build | Vite 8 | Fast HMR, Rolldown bundler |
| Language | TypeScript (strict) | Type safety for template engine |
| Styling | Tailwind CSS 3 | Utility-first, fast iteration |
| State | Zustand + persist middleware | Simple, localStorage/file persistence |
| Router | React Router 6 (HashRouter) | GitHub Pages compatible |
| i18n | i18next + react-i18next | Industry standard, lazy-load locales |
| Desktop | Tauri 2 | Lightweight Rust-based, ~5MB binary |
| Testing | Vitest + React Testing Library | Vite-native, fast |
| Lint | ESLint + Prettier | Consistent code style |
| CI/CD | GitHub Actions | Familiar workflow |
| Layer | Technology |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| UI | React 19, TypeScript (strict), Radix primitives (`radix-ui`), Motion (LazyMotion), cmdk, sonner, lucide-react + simple-icons |
| Build | Vite 8 (Rolldown); config imports need `.ts` extensions |
| 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 |
## Project Structure
```
yt-desc-gen/
├── CLAUDE.md # ← You are here
├── README.md
├── LICENSE
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.ts
├── index.html
│
├── docs/ # Project documentation
│ ├── DEVELOPMENT.md # Toolchain / IDE / build commands (EN)
│ ├── ARCHITECTURE.md # Technical architecture
│ ├── FEATURES.md # Complete feature list
│ ├── ROADMAP.md # Development phases
│ ├── TECH-SPEC.md # Technical specifications
│ ├── I18N.md # Internationalization guide
│ ├── PACKAGING.md # Desktop packaging guide
│ └── i18n/vi/ # Vietnamese mirrors (DEVELOPMENT, DISCLAIMER)
│
├── src/
│ ├── main.tsx # Entry point
│ ├── App.tsx # Root component + router
│ ├── vite-env.d.ts
│ │
│ ├── config/ # Static data & constants
│ │ ├── video-types.ts # VIDEO_TYPES array
│ │ ├── genres.ts # GENRES array (extensible)
│ │ ├── platforms.ts # Store platforms (Steam, Epic, etc.)
│ │ ├── rig-fields.ts # Hardware field definitions
│ │ ├── social-fields.ts # Social/donate link definitions
│ │ └── defaults.ts # Default state values
│ │
│ ├── i18n/ # Internationalization
│ │ ├── index.ts # i18next setup
│ │ └── locales/
│ │ ├── en/
│ │ │ ├── ui.json # UI strings (buttons, labels)
│ │ │ └── templates.json # Description templates
│ │ ├── vi/
│ │ ├── ja/
│ │ ├── es/ # Spanish (example extension)
│ │ ├── ko/ # Korean (future)
│ │ ├── zh/ # Chinese (future)
│ │ └── _schema.json # JSON schema for locale validation
│ │
│ ├── engine/ # Core template engine (pure functions, no React)
│ │ ├── title-builder.ts # Title generation + quality-badge helper
│ │ ├── title-variants.ts # A/B variant title generator (v0.5)
│ │ ├── description-builder.ts # Description generation logic
│ │ ├── tag-generator.ts # Tag generation + dedup + char limit
│ │ ├── template-renderer.ts # Orchestrator: combines title + desc + tags
│ │ └── types.ts # Shared types for engine
│ │
│ ├── store/ # State management (Zustand)
│ │ ├── editor-store.ts # Current editor form state
│ │ ├── profile-store.ts # Saved profiles (social, rig, channel)
│ │ ├── preset-store.ts # Game presets (name + store links)
│ │ ├── template-store.ts # Full-form snapshots (v0.5)
│ │ ├── history-store.ts # Generated output history
│ │ └── settings-store.ts # App settings (theme, default language, description toggles)
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── use-generated-output.ts # Memoized template rendering
│ │ ├── use-clipboard.ts # Copy-to-clipboard with feedback
│ │ ├── use-char-count.ts # Character count with limit warning
│ │ └── use-debounce.ts # Input debouncing
│ │
│ ├── components/ # Reusable UI components
│ │ ├── ui/ # Primitives
│ │ │ ├── Button.tsx
│ │ │ ├── Input.tsx
│ │ │ ├── Textarea.tsx
│ │ │ ├── Toggle.tsx
│ │ │ ├── ChipGroup.tsx
│ │ │ ├── Select.tsx
│ │ │ ├── Badge.tsx
│ │ │ ├── Tooltip.tsx
│ │ │ ├── Modal.tsx
│ │ │ └── Toast.tsx
│ │ │
│ │ ├── editor/ # Editor-specific components
│ │ │ ├── VideoTypeSelector.tsx
│ │ │ ├── LanguageSelector.tsx
│ │ │ ├── GenreSelector.tsx
│ │ │ ├── GameInfoForm.tsx
│ │ │ ├── VideoSettingsForm.tsx
│ │ │ ├── TimestampEditor.tsx
│ │ │ ├── StoreLinkEditor.tsx
│ │ │ ├── RigEditor.tsx
│ │ │ ├── SocialEditor.tsx
│ │ │ ├── WarningToggles.tsx
│ │ │ └── QuickPreview.tsx
│ │ │
│ │ ├── output/ # Output display components
│ │ │ ├── OutputPreview.tsx
│ │ │ ├── TitleOutput.tsx
│ │ │ ├── DescriptionOutput.tsx
│ │ │ ├── TagOutput.tsx
│ │ │ ├── CharCounter.tsx
│ │ │ ├── CopyButton.tsx
│ │ │ └── CopyAllBar.tsx
│ │ │
│ │ ├── profiles/ # Profile management
│ │ │ ├── ProfileList.tsx
│ │ │ ├── ProfileCard.tsx
│ │ │ ├── ProfileSaveForm.tsx
│ │ │ └── GamePresetManager.tsx
│ │ │
│ │ └── layout/ # App shell
│ │ ├── AppShell.tsx
│ │ ├── Sidebar.tsx
│ │ ├── Header.tsx
│ │ └── TabBar.tsx
│ │
│ ├── pages/ # Route pages
│ │ ├── EditorPage.tsx
│ │ ├── OutputPage.tsx
│ │ ├── ProfilesPage.tsx
│ │ ├── HistoryPage.tsx
│ │ ├── SettingsPage.tsx
│ │ └── BatchPage.tsx
│ │
│ ├── utils/ # Shared utilities
│ │ ├── clipboard.ts
│ │ ├── char-count.ts
│ │ ├── sanitize.ts
│ │ ├── export.ts # JSON/CSV export
│ │ └── import.ts # JSON import
│ │
│ └── styles/
│ └── globals.css # Tailwind directives + custom vars
│
├── src-tauri/ # Tauri desktop shell (Phase 4)
│ ├── Cargo.toml
│ ├── tauri.conf.json
│ ├── src/
│ │ └── main.rs
│ └── icons/
│
├── tests/
│ ├── engine/ # Unit tests for template engine
│ │ ├── title-builder.test.ts
│ │ ├── description-builder.test.ts
│ │ └── tag-generator.test.ts
│ ├── store/ # Store tests
│ └── components/ # Component tests
│
├── scripts/ # Build/dev scripts
│ ├── validate-locales.ts # Validate all locale files have same keys
│ └── generate-locale-template.ts # Generate empty locale from schema
│
└── .github/
└── workflows/
├── ci.yml # Lint + test + build
├── deploy-web.yml # Deploy to GitHub Pages
└── release-desktop.yml # Build Tauri binaries
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
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, 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 enabled (`strict: true` in tsconfig)
- Prefer `interface` over `type` for object shapes
- Use `const` assertions for static config arrays
- No `any` — use `unknown` + type guards
- Barrel exports via `index.ts` per directory
- Strict mode; no `any` — use `unknown` + type guards.
- Prefer `interface` for object shapes; `as const` for static config arrays.
### React
- Functional components only, no class components
- Custom hooks for shared logic — prefix with `use`
- Memoize expensive computations with `useMemo`
- Use `React.lazy()` for page-level code splitting
- No prop drilling beyond 2 levels — use Zustand store
- 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` / `PascalCase.tsx` for components
- Variables/functions: `camelCase`
- Types/interfaces: `PascalCase`
- Constants: `UPPER_SNAKE_CASE`
- Store slices: `use[Name]Store`
- Files: `kebab-case.ts`, components `PascalCase.tsx`; stores `use[Name]Store`; constants `UPPER_SNAKE_CASE`.
### Styling
- Tailwind utility classes — no inline styles, no CSS modules
- Custom colors defined in `tailwind.config.ts`
- Dark theme by default, optional light theme via class toggle
- Responsive: mobile-first, breakpoints at `sm`, `md`, `lg`
- 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.
- Watch Tailwind 4 specificity: a base `inline-flex` beats a plain `hidden` — wrap responsive visibility in an element.
### i18n
- All user-facing strings go through `t()` function
- Template strings (description/title) use dedicated locale file
- UI strings and template strings are separate namespace files
- Never hardcode user-visible text in components
### State Management
- Zustand stores with `persist` middleware for localStorage
- Separate stores by domain (editor, profiles, presets, settings)
- Keep stores flat — no deep nesting
- Actions defined inside the store, not externally
- 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.
### Engine (template logic)
- Pure functions only — no React dependencies
- 100% unit test coverage for engine/
- Each function takes typed input, returns string
- No side effects — no clipboard, no storage, no DOM
### 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. **Engine is framework-agnostic**: `src/engine/` has zero React imports. This allows reuse if migrating to another framework, CLI tool, or VS Code extension.
2. **i18n covers both UI and templates**: UI labels (`ui.json`) and generated content (`templates.json`) are separate. Adding a language means adding 2 JSON files + registering in config.
3. **Profiles vs Presets**: Profile = user identity (channel, social, rig — rarely changes). Preset = game identity (name, store links — reused across parts). These are separate stores.
4. **Tags are generated, not hand-written**: Tag engine combines genre pool + core pool + platform + quality + multilingual + trending. User can edit the final output but doesn't build tags manually.
5. **Tauri for desktop**: Chosen over Electron for ~5MB binary vs ~150MB. Familiar Rust toolchain. Web version works independently without Tauri.
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.
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
# Install dependencies
npm install
# Development server
npm run dev
# Build for web
npm run build
# Preview production build
npm run preview
# Run tests
npm run test
# Lint
npm run lint
# Type check
npm run typecheck
# Validate locale files
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
# Desktop dev (requires Tauri CLI)
npm run tauri dev
# Desktop build
npm run tauri build
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` — stable releases
- `dev` — integration branch
- Feature branches: `feat/feature-name`
- Commit format: `type(scope): message`
- Types: `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`
- Example: `feat(engine): add Spanish template support`
- `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
- Always run `npm run typecheck` before committing
- When adding a new language: follow docs/I18N.md checklist
- When adding a new genre: add to `src/config/genres.ts` + tag pool in `src/engine/tag-generator.ts`
- When adding a new video type: add to `src/config/video-types.ts` + update all template files in `src/i18n/locales/*/templates.json`
- Engine tests must pass before any PR merge
- Keep bundle size under 500KB (excluding Tauri)
- 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`.
- Never commit `note.txt`, `warning.txt` or `__pycache__/`; never put real secrets in files (`.dev.vars` holds Cloudflare's public Turnstile test keys only).
- The Cloudflare dashboard, publishing releases and repository settings are the maintainer's; ask before touching them.
+1 -1
View File
@@ -6,7 +6,7 @@ By participating in this project — opening issues, submitting pull requests, c
## Reporting
Report violations privately to the maintainer: `lopop05905@proton.me`.
Report violations privately to the maintainer: `code@poli0981.dev`.
All reports are reviewed and investigated promptly and fairly. The maintainer is obligated to respect the privacy and security of the reporter.
+23 -11
View File
@@ -11,13 +11,19 @@ Participation is governed by the [Code of Conduct](./CODE_OF_CONDUCT.md). By con
1. Read the [Development Guide](./docs/DEVELOPMENT.md) — also available in [Vietnamese](./docs/i18n/vi/DEVELOPMENT.md).
2. Install dependencies: `npm install`.
3. Start the dev server: `npm run dev`.
4. Before opening a PR run all gates:
4. Before opening a PR, run the same gates CI runs (the required `check` job):
```bash
npm run typecheck
npm run lint
npm run typecheck && npm run typecheck:all
npm run lint && npm run format:check
npm run validate:locales
npm run test:run
npm run test:coverage
npm run knip
npm run check:version && npm run check:tauri && npm run check:licenses
npm run check:copyright
npm run build && npm run check:bundle
npm run cf:check
```
`check:licenses` fails when `THIRD_PARTY_NOTICES.md` is stale — `npm run generate:third-party` rewrites it. `check:copyright` fails in the first commit of a new year — `npm run update:copyright` fixes it. Touched `src-tauri/`? Also `cargo fmt --check`, `cargo clippy --all-targets --locked -- -D warnings` and `cargo test` in `src-tauri/` (after `npm run build` — see the [Development Guide](./docs/DEVELOPMENT.md#rust-checks)).
## How to Contribute
@@ -30,8 +36,10 @@ Use the templates in `.github/ISSUE_TEMPLATE/`:
### Pull Requests
- Branch from `dev`, not `main`.
- Commit format: `type(scope): message` — e.g. `feat(engine): add Spanish template support`. Types: `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`.
- Branch from `main` (`feat/…`, `fix/…`, `docs/…`) and open the PR against `main`. Every merge to `main` deploys the web app, so `main` stays releasable.
- Commit format and **PR title**: `type(scope): message` — e.g. `feat(engine): add Spanish template support`. Types: `feat`, `fix`, `refactor`, `docs`, `test`, `ci`, `chore`. CI checks the PR title.
- Required checks: `check`, `dependency-review`, `workflow-lint`, `reuse`, `pr-title`. When `src-tauri/` changes, the Rust workflow's `lint-and-test` and `cargo-deny` run too, and GitHub's CodeQL code scanning runs on every PR. Commits on `main` are signed.
- PR titles start with a lower-case letter after the colon (`feat(editor): add …`, not `feat(editor): Add …`).
- One logical change per PR. Don't bundle unrelated refactors.
- All locale files must stay in lock-step — see the i18n section below.
- AI-assisted contributions are welcome but **must be disclosed** in the PR description.
@@ -41,10 +49,10 @@ Use the templates in `.github/ISSUE_TEMPLATE/`:
If your change adds or removes any user-facing string:
1. Update the locale schema at `src/i18n/locales/_schema.json` first.
2. Add the key to **all 6 locales** (`en` / `vi` / `ja` / `es` / `ko` / `zh`).
2. Add the key to **all 8 locales** (`en` / `vi` / `ja` / `es` / `ko` / `zh` / `pt-BR` / `id`).
3. `npm run validate:locales` must pass.
Native-speaker corrections to AI-translated locales (JA / ES / KO / ZH) are especially welcome — see [DISCLAIMER.md](./DISCLAIMER.md) for the current translation-quality status.
Native-speaker corrections to AI-translated locales (JA / ES / KO / ZH / PT-BR / ID) are especially welcome — see [DISCLAIMER.md](./DISCLAIMER.md) for the current translation-quality status.
## Auto-ignored Contributions
@@ -53,9 +61,9 @@ The following are closed without review and may result in a contributor ban —
- **Suspected malicious code.** If a PR contains code we suspect may be a supply-chain attack, obfuscation, credential harvesting, cryptominer, or any form of malware — even if CodeQL and Dependabot don't flag it, the maintainer may investigate manually. **Detection equals ban.**
- **Unverified or suspicious links** in issues, PRs, or comments (pastebin scrapers, redirect chains, unfamiliar shortlinks, link-shortener URLs without context).
- **Behavior or language violating** [GitHub's Acceptable Use Policies](https://docs.github.com/en/site-policy/acceptable-use-policies).
- **Off-topic / rambling reports** that don't get to the point. Example of what gets ignored: *"Good morning, today is a beautiful day, I was just wondering if maybe…"* — get straight to the problem.
- **Off-topic / rambling reports** that don't get to the point. Example of what gets ignored: _"Good morning, today is a beautiful day, I was just wondering if maybe…"_ — get straight to the problem.
- **PRs that touch hundreds of files for a one-line fix** (typical sign of an auto-formatter run on unrelated files).
- **Tests deleted, or `--no-verify` used to bypass pre-commit hooks.**
- **Tests deleted or skipped to make CI pass.**
- **"AI rewrote my entire codebase in a different style" PRs.** AI-assisted edits are welcome (disclosed); whole-repo rewrites are not.
- **Spam, drive-by typo fixes** that don't address a real issue, and karma-farming PRs.
@@ -63,7 +71,7 @@ The following are closed without review and may result in a contributor ban —
- Bug fixes with a reproduction case and a regression test.
- Locale corrections from native speakers.
- New content-warning IDs with all 6 translations and a clear rationale (especially horror-genre vocabulary).
- New content-warning or tech-note IDs with all 8 translations and a clear rationale (especially horror-genre vocabulary) — the checks fail until every locale has its label and description line.
- New video types or genres that fit the gameplay no-commentary use case.
- Accessibility and mobile-responsive improvements.
- Performance fixes with a `before/after` measurement.
@@ -75,6 +83,10 @@ The following are closed without review and may result in a contributor ban —
- Renaming files without coordinating with open PRs.
- Changes to the LICENSE or NOTICE files (these are governance, not contributions).
## Contact
Questions about contributing or conduct: `code@poli0981.dev`. Security issues go through [SECURITY.md](./SECURITY.md), never a public issue.
## License
By contributing, you agree your contribution will be licensed under the [Apache License 2.0](./LICENSE), the same license as the project, and that you have the right to grant that license.
+18 -11
View File
@@ -4,7 +4,7 @@
YTDescGen is a personal project built by a single maintainer (`@poli0981`) for use with the [`@SkullMute`](https://www.youtube.com/@SkullMute) YouTube channel and shared publicly as open source. It is **not a commercial product** and there is no support obligation.
Code, documentation, locale translations, and design decisions in this repository were **co-authored with the assistance of Anthropic's Claude Code (model 4.7 Opus, 1M-context variant)**. All commits, releases, and architectural decisions are reviewed and approved by the maintainer before merging.
Code, documentation, locale translations, and design decisions in this repository were **co-authored with the assistance of Anthropic's Claude Code (Claude Opus models; v1.0.0 through v1.2.0 with Claude Opus 5.5)**. All commits, releases, and architectural decisions are reviewed and approved by the maintainer before merging.
This disclosure applies to:
@@ -12,21 +12,24 @@ This disclosure applies to:
- Documentation in `docs/` and all root markdown files.
- Locale files in `src/i18n/locales/`.
- CI/CD workflows in `.github/workflows/`.
- The Cloudflare Worker in `worker/` and the build plugins in `build-plugins/`.
See also: [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md) § "AI-Assisted Development Disclosure".
See also: [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md) § "AI-assisted development".
## Translation quality
The application UI ships in six languages. Authoring quality varies:
The application UI ships in eight languages. Authoring quality varies:
| Locale | Authoring | Notes |
| --- | --- | --- |
| English (`en`) | Maintainer + AI | Primary working locale. Strings reviewed before commit. |
| Vietnamese (`vi`) | Maintainer (native) + AI | Reviewed by the maintainer, who is a native Vietnamese speaker. |
| Japanese (`ja`) | AI-translated | Not native-reviewed. Grammar and tone may be imperfect. |
| Spanish (`es`) | AI-translated | Not native-reviewed. Regional voice (LatAm vs. Castilian) not specifically targeted. |
| Korean (`ko`) | AI-translated | Not native-reviewed. Honorific register chosen for neutrality, not specific cultural fit. |
| Chinese (`zh`) | AI-translated | Simplified Chinese only. Not native-reviewed. |
| Locale | Authoring | Notes |
| ---------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| English (`en`) | Maintainer + AI | Primary working locale. Strings reviewed before commit. |
| Vietnamese (`vi`) | Maintainer (native) + AI | Reviewed by the maintainer, who is a native Vietnamese speaker. |
| Japanese (`ja`) | AI-translated | Not native-reviewed. Grammar and tone may be imperfect. |
| Spanish (`es`) | AI-translated | Not native-reviewed. Regional voice (LatAm vs. Castilian) not specifically targeted. |
| Korean (`ko`) | AI-translated | Not native-reviewed. Honorific register chosen for neutrality, not specific cultural fit. |
| Chinese (`zh`) | AI-translated | Simplified Chinese only. Not native-reviewed. |
| Portuguese, Brazil (`pt-BR`) | AI-translated | Not native-reviewed. Brazilian Portuguese specifically — European Portuguese is not separately targeted. |
| Indonesian (`id`) | AI-translated | Not native-reviewed. Standard Indonesian; gaming loanwords kept in English where that is the common usage. |
If you're a native speaker and spot mistranslations, please open an issue or PR — see [CONTRIBUTING.md](./CONTRIBUTING.md) § "i18n Contributions".
@@ -51,3 +54,7 @@ Use of Claude Code during development does **not** make this an Anthropic produc
## Not legal or financial advice
Any mention of GDPR, CCPA, copyright law, YouTube's monetization policies, or similar topics in this repository's documentation is provided for orientation only and is **not legal advice**. Consult a qualified lawyer in your jurisdiction if you need an authoritative answer.
## Contact
Copyright or DMCA notices: **dmca@poli0981.dev** (see [TERMS.md](./TERMS.md)). Licensing and attribution: **copyright@poli0981.dev**. Anything else: **contact@poli0981.dev** · [poli0981.dev/links](https://poli0981.dev/links/).
+201
View File
@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for describing the origin of the Work and
reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Support. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or support.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied. See the License for the specific language governing permissions and
limitations under the License.
+3 -2
View File
@@ -6,7 +6,8 @@
- **GitHub**: <https://github.com/poli0981>
- **YouTube** (reference channel): <https://www.youtube.com/@SkullMute>
- **Email** (security & private contact): `lopop05905@proton.me`
- **Website**: <https://poli0981.dev/> · all channels at <https://poli0981.dev/links/>
- **Email**: `code@poli0981.dev` (project) · `security@poli0981.dev` (vulnerabilities, see [SECURITY.md](./SECURITY.md))
- **Areas of responsibility**: all — core engine, locale management, UI, Tauri desktop shell, releases, CI/CD.
## Maintainer Responsibilities
@@ -19,7 +20,7 @@
## Becoming a Maintainer
There is currently no formal pathway. The project has been solo since inception. If you'd like to help maintain a specific area — most realistically, native-speaker review for one of the AI-translated locales (JA / ES / KO / ZH) — open an issue describing what you'd like to take on.
There is currently no formal pathway. The project has been solo since inception. If you'd like to help maintain a specific area — most realistically, native-speaker review for one of the AI-translated locales (JA / ES / KO / ZH / PT-BR / ID) — open an issue describing what you'd like to take on.
Persistent, high-quality contributions over time are the path. There is no application form.
+4 -2
View File
@@ -8,8 +8,10 @@ see LICENSE for the full terms, or visit:
http://www.apache.org/licenses/LICENSE-2.0
This product was co-developed with the assistance of Anthropic's
Claude Code 4.7 Opus (1M context). See DISCLAIMER.md and
THIRD_PARTY_NOTICES.md for details.
Claude Code (Claude Opus models; most recently Claude Opus 5.5).
See DISCLAIMER.md and THIRD_PARTY_NOTICES.md for details.
Licensing and attribution questions: copyright@poli0981.dev
Third-party dependencies retain their respective licenses; see
THIRD_PARTY_NOTICES.md for the complete attribution list.
+70 -44
View File
@@ -1,75 +1,101 @@
# Privacy Policy
**Effective:** 2026-05-14
**Effective:** 2026-10-12
YTDescGen is an **offline-first** template engine for generating YouTube video metadata. This document describes what data the application handles, where it lives, and what it never collects.
This policy covers YTDescGen — the web app at **https://ytgenerator.stream** and the desktop (Windows, macOS, Linux) and Android apps built from the same source. It is maintained by **poli0981 (SkullMute)**, who is responsible for it. Questions and requests: **privacy@poli0981.dev**.
## What We Collect
## In short
**Nothing.** The application sends no data to any server controlled by the maintainer.
- There is **no account** and **no YTDescGen server that receives your work**. Everything you type — profiles, presets, templates, drafts, history — is stored **on your own device** and nowhere else.
- The **web app** is delivered through **Cloudflare**. To do that, Cloudflare necessarily sees technical request data (such as your IP address), runs a one-time **Turnstile** bot check before you enter, and provides **cookieless** visit statistics (**Cloudflare Web Analytics**).
- The **desktop and Android apps** have none of that: no analytics, no bot check, no telemetry.
- Nothing is sold, shared for advertising, or used to profile you.
There is no analytics provider, no telemetry, no crash reporter, no A/B testing, no advertising network, no behavioral tracking. There is no backend.
## 1. What stays on your device
## What Stays on Your Device
### Web app
### Web version (GitHub Pages)
Your work is saved in your browser's **`localStorage`** for `ytgenerator.stream`:
The web build stores your work in your browser's **`localStorage`** only. Keys used:
| Key | Contents |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `ytdescgen-settings` | Theme, languages, editor preferences, the version of these terms you accepted and when |
| `ytdescgen-profiles` | Saved channel profiles (channel name, social links, contact emails, PC rig) |
| `ytdescgen-presets` | Saved game presets (game name, genres, store links) |
| `ytdescgen-templates` | Saved full-form templates |
| `ytdescgen-history` | Recently generated titles, descriptions and tags |
| `ytdescgen-editor-draft` | The draft currently open in the editor |
| `ytdescgen-logs` | The app's own event log (errors, imports, exports) |
| Key prefix | Purpose |
| --- | --- |
| `ytdesc:editor` | Current editor draft |
| `ytdesc:settings` | Theme, default language, accordion state, hashtag preferences |
| `ytdesc:profiles` | Saved channel / social / rig profiles |
| `ytdesc:presets` | Saved game presets |
| `ytdesc:templates` | Saved full-form snapshots |
| `ytdesc:history` | Recently generated outputs |
| `ytdesc:logs` | Application event log |
This data never leaves your browser unless **you** export it. Clearing site data, using a private window, or a "clear cookies and site data on exit" setting erases it.
`localStorage` is scoped to the origin and never transmitted. Clearing your browser data, browsing in a private/incognito window, or signing out wipes all of it.
One more value can appear in **`sessionStorage`**, for the open tab only: `ytdescgen-chunk-reload`, a flag written only when an update has replaced the files the app was about to load, so that it reloads itself once instead of over and over. It holds no data and disappears when the tab closes.
### Desktop version (Tauri)
### Desktop and Android apps
The desktop build uses the operating system's standard application-data directory:
The apps keep the same data in the app's own WebView storage and application-data folder (the event log and automatic backups live there too):
- **Windows**: `%APPDATA%\com.skullmute.ytdescgen`
- **macOS**: `~/Library/Application Support/com.skullmute.ytdescgen`
- **Linux**: `~/.config/com.skullmute.ytdescgen`
- **Windows:** `%APPDATA%\com.skullmute.ytdescgen` and `%LOCALAPPDATA%\com.skullmute.ytdescgen`
- **macOS:** `~/Library/Application Support/com.skullmute.ytdescgen`
- **Linux:** `~/.local/share/com.skullmute.ytdescgen`
- **Android:** the app's private storage (removed when you uninstall the app or clear its data)
The same key set as the web version is stored as JSON files there. Uninstalling the application or deleting that directory removes everything.
The desktop app keeps its automatic backups (the newest ten, plus one made before each restore) in the `backups` folder inside the application-data folder, and its event log in `logs`. Uninstalling the app or deleting those folders removes everything. The apps make no network requests of their own; links you choose to open (store pages, donation pages, this policy on the web) open in your browser.
## Third-Party Services
### The old address
The application does **not** call third-party APIs at runtime.
Until 29 November 2026, `poli0981.github.io/youtube-generator` — where the web app used to live — shows a moving notice hosted by **GitHub Pages**. Browser storage belongs to a site, so data saved there can't move on its own: the notice reads what your browser saved on that address and lets you download it as a file. Nothing is uploaded; GitHub, as the host, receives the usual request data (see the [GitHub Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement)).
Optional links you may click — donation buttons, store links you paste into a draft, social links you save to your profile — navigate **away** from the application to third-party sites. Those sites have their own privacy policies; the maintainer is not responsible for them.
## 2. What the web app's hosting provider processes
YouTube oEmbed, the Steam store API, Twitch helix, and similar services are **not** fetched by this application.
The web app is hosted on **Cloudflare Workers**. Cloudflare acts as a service provider (processor) for the site and handles:
## Cookies / Local Storage Distinction
- **Delivery and security.** Every request carries technical data — IP address, browser user-agent, requested URL, referrer, date and time. Cloudflare uses it to deliver the site, keep it available and protect it from abuse. Error and request logs for the site's Worker (Cloudflare Workers Logs) are kept by Cloudflare for a short period (currently up to 7 days) and are used only to fix problems.
- **Turnstile bot check.** Before you enter, [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/) runs a check — usually invisible — that evaluates technical browser and device signals and your IP address to tell people from automated traffic. Its data handling is described in Cloudflare's [Turnstile Privacy Addendum](https://www.cloudflare.com/turnstile-privacy-policy/). YTDescGen receives only a pass/fail result.
- **Cloudflare Web Analytics.** Aggregate, **cookieless** statistics: page views, referrer, country, browser, operating system and device type, and page-load performance. It sets no cookies, uses no local storage and does not fingerprint visitors. See [Cloudflare's Web Analytics privacy notes](https://www.cloudflare.com/web-analytics/) and the [Cloudflare Privacy Policy](https://www.cloudflare.com/privacypolicy/).
The web version uses **`localStorage`**, not cookies. No cookie is set by the application. GitHub Pages itself may issue a session cookie at the platform level — that is GitHub's, not ours, and is governed by [GitHub's Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement).
Cloudflare operates a global network, so this data may be processed outside your country under Cloudflare's data-processing terms (including the EU Standard Contractual Clauses).
The first-run consent acknowledgement (added in v0.28.0) is recorded **inside the existing settings record** — a `legalConsentVersion` number plus a local timestamp — not as a separate cookie or storage key. It never leaves your device.
## 3. Cookies
## Children's Privacy
The web app sets exactly two cookies, both first-party and both needed for the bot check:
This application is not directed at children under 13 and does not knowingly process any personal data from anyone.
| Cookie | Purpose | Lifetime |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `__Host-ytg_gate` | Remembers that this browser passed the Turnstile check. Contains only an expiry time, a shortened one-way hash of your browser's user-agent string and a signature — no identifier. `HttpOnly`, `Secure`. | 24 hours |
| `ytg_terms` | Records which version of these Terms and this Privacy Policy you agreed to on the check page, so the app does not ask twice. | 1 year |
## GDPR / CCPA / Equivalent Rights
There are no advertising, tracking or third-party analytics cookies. Cloudflare's own security systems may set strictly necessary cookies of their own as described in Cloudflare's [cookie policy](https://www.cloudflare.com/cookie-policy/).
Because no data ever leaves your device:
## 4. Legal bases (EEA/UK)
- **Right to access**: your data is already accessible — open DevTools → Application → Local Storage on the web, or browse the application-data directory on desktop.
- **Right to erasure**: clear your browser's site data (web) or delete the application-data directory / uninstall the app (desktop).
- **Right to portability**: use the in-app **Export** action in `Profiles` / `Presets` / `Templates` / `History` / `Logs` to download JSON.
- **Right to object / restrict processing**: not applicable — no processing happens off-device.
- **Right to know what is sold or shared**: nothing. Nothing is sold or shared.
- Operating and securing the web app, including the bot check and its cookies: **legitimate interests** (Art. 6(1)(f) GDPR); the cookies are strictly necessary for a service you request, so they need no separate consent.
- Aggregate, cookieless visit statistics: **legitimate interests** in understanding how the site is used.
- Everything in section 1 is processed only on your device, by you.
## Changes to This Policy
## 5. What is never done
If this policy changes, the change is committed to the repository under `PRIVACY.md` with the `Effective` date updated. There is no notification mechanism because the application has no way to reach you.
- No selling or renting of data, no advertising networks, no behavioural profiling.
- No YouTube, Google, Steam or other third-party account access — the app never sees your channel.
- No crash reporting or telemetry from the desktop or Android apps.
## Contact
## 6. Your rights
`lopop05905@proton.me`
- **Access and portability:** your content is already on your device; **Settings › Backup & restore** saves all of it (or the parts you choose) as one file, and the library and History pages export their own lists.
- **Erasure:** clear site data (web) or uninstall the app / delete its folders (desktop, Android).
- **Data processed by Cloudflare:** write to **privacy@poli0981.dev**. Because YTDescGen has no accounts, it holds no data that can be looked up by your name or email; requests about Cloudflare's own processing can also go to Cloudflare directly.
- You may also complain to your local data-protection authority.
## 7. Children
YTDescGen is not directed at children under 13 (or the minimum age of digital consent in your country) and does not knowingly process their personal data.
## 8. Changes
Changes are published at [ytgenerator.stream/legal/privacy](https://ytgenerator.stream/legal/privacy) and in the repository's `PRIVACY.md`, with the **Effective** date updated. When a change is material, the app asks you to review and accept it again on your next visit.
## 9. Contact
- Privacy and data requests: **privacy@poli0981.dev**
- Security issues: **security@poli0981.dev** (see the [Security Policy](SECURITY.md))
- Everything else: **contact@poli0981.dev** · [poli0981.dev/links](https://poli0981.dev/links/)
+82 -59
View File
@@ -1,47 +1,56 @@
# 🎮 YTDescGen
**YouTube Gameplay Description Generator** — an offline-first template engine for Gameplay No Commentary YouTube channels.
**YouTube Gameplay Description Generator** — a template engine for Gameplay No Commentary YouTube channels.
Generate YouTube titles, descriptions, and tags in six languages with one click. Save channel, rig, and game presets to skip repetitive data entry. Works in the browser (GitHub Pages), as a ~8 MB native desktop app (Windows / macOS / Linux), or as an installable Android APK — all from one Tauri 2 codebase.
**Use it at [ytgenerator.stream](https://ytgenerator.stream)**, or install the desktop app (Windows / macOS / Linux, 3–6 MB installers) or the Android app from [Releases](https://github.com/poli0981/youtube-generator/releases). One codebase: React + Tauri 2.
Generate YouTube titles, descriptions and tags in eight languages. Save your channel as a profile and each game as a preset, and every new video is a few clicks.
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen)](./docs/DEVELOPMENT.md)
[![Latest release](https://img.shields.io/github/v/release/poli0981/youtube-generator?include_prereleases)](https://github.com/poli0981/youtube-generator/releases)
[![Last commit](https://img.shields.io/github/last-commit/poli0981/youtube-generator)](https://github.com/poli0981/youtube-generator/commits)
> **Moved from GitHub Pages?** Data saved at the old `poli0981.github.io/youtube-generator` address stays in that browser. Open the old address once — it offers your data as a backup file — then restore it in **Settings › Backup & restore**. Details: [Moving from GitHub Pages](https://github.com/poli0981/youtube-generator/wiki/Moving-from-GitHub-Pages).
---
## What is YTDescGen
YTDescGen is a single-purpose template engine. It does **one** job: turn a small set of structured fields (video type, game name, genres, rig, social links, content warnings, …) into a publish-ready YouTube title + description + tag set.
YTDescGen does **one** job: turn a small set of structured fields (video type, game, genres, rig, social links, content warnings, …) into a publish-ready YouTube title, description and tag set.
It doesn't talk to the YouTube API. It doesn't upload anything. It doesn't track you. There is no server. State lives in your browser's `localStorage` (web) or your OS application-data directory (desktop) — and nowhere else.
It doesn't talk to the YouTube API and has no account. Your work — profiles, presets, templates, history, drafts — stays on your device. See [Privacy](#privacy).
Built for the gameplay no-commentary niche — especially horror / scary games — by someone running the [@SkullMute](https://www.youtube.com/@SkullMute) channel who got tired of pasting the same boilerplate into every video. Released under Apache 2.0 in case it's useful to anyone else.
## Features
- **20 video types** — Full Gameplay, Part, Boss Fight, Boss No-Hit, Ending, Speedrun, 100%, DLC, NG+, Challenge, Side Quest, Secret, Comparison, Guide, Mods, Collectibles, Livestream, Gacha Quest, Demo, Demo Part.
- **6 UI languages** — English, Vietnamese, Japanese, Spanish, Korean, Chinese. *(VI authored by a native speaker; JA / ES / KO / ZH AI-translated — see [DISCLAIMER.md](./DISCLAIMER.md).)*
- **40+ game genres** — across action, RPG, FPS, horror, soulslike, indie, simulation, fighting, and more.
- **248 content-warning IDs** across 12 groups — spoilers, photosensitive/VFX, audio, dialogue/language, phobias (incl. color phobias), mental health, social phenomena, internet/digital life, sensitive themes (incl. method-specific death/violence and suggestive imagery), horror-specific, playstyle, and gameplay disclosure (mods / cheats / glitches / guide-assisted / educational purpose). Sets viewer expectations before they hit play.
- **Profile system** — save channel / social / rig info once, reuse across every video.
- **Game presets** — save game name + store links once, reuse across the entire part series.
- **Snapshot templates** — save full-form configurations and recall in one click.
- **Smart tag generation** — combines genre pool, platform, quality tier, multilingual hooks, and trending terms; auto-dedup and 500-char-limit aware.
- **Character counters** — real-time limits for title (100), description (5000), tags (500).
- **Batch mode** — generate metadata for all parts of a series in one pass.
- **Cross-post captions** — a dedicated **Social** tab re-packages the same YouTube source into short-form captions for **TikTok** (4,000-char), **Instagram Reels**, and **Facebook Reels** — title, rig, content warnings, copyright, thanks, and hashtags (game + genre + curated per-platform popular tags). Single + bulk modes, per-platform character limits with smart overflow trimming, and JSON import/export.
- **Desktop app** — Windows, macOS & Linux native binaries via Tauri (~8 MB).
- **Android app** — installable, sideloadable `.apk` built from the same Tauri 2 codebase. **Requires Android 11+** (tested 11–16; real-device test on Android 12). Grab it from [Releases](https://github.com/poli0981/youtube-generator/releases) and enable "Install unknown apps" to sideload.
- **Mobile-responsive web** — drawer navigation, touch-sized controls, iOS-safe text-input behavior. Tested down to 360 × 640.
- **100% offline** — no server, no telemetry, no account. See [PRIVACY.md](./PRIVACY.md).
- **8 languages** — English, Vietnamese, Japanese, Spanish, Korean, Chinese, Portuguese (Brazil), Indonesian — for the interface and the generated text. _(Vietnamese is native-reviewed; the others are AI-translated — see [DISCLAIMER.md](./DISCLAIMER.md).)_
- **40+ genres** and **257 content warnings** in 13 groups — including whether the game uses **AI-generated** art, voices, music or text — so viewers know what to expect before they press play.
- **Quick start** — pick your channel profile and the game's preset at the top of the editor; **Next part**, **New video, same game** and **Start over** clear exactly what belonged to the last video.
- **Paste a store link anywhere** — it lands in the right store field and names the game (Steam, Epic, GOG, PlayStation, Xbox, Nintendo, itch.io, Humble, EA app, Ubisoft, Battle.net, Google Play, App Store, Meta Quest, Amazon Luna).
- **Live preview** beside the form and a **YouTube preview** (where search results cut the title, what shows above "…more").
- **Tags counted the way YouTube counts them**, **chapter check** for timestamps, and per-field character limits (title 100, description 5000, tags 500) — only the field that is over can't be copied.
- **Correct hardware names** — "NVIDIA GeForce RTX 5080", "AMD Radeon RX 9070 XT", "Apple M4 Pro" — from a searchable GPU picker.
- **Backup & restore** — one file with everything, a preview of what's new or different before anything changes, merge or replace, and Undo. The desktop app also keeps automatic backups.
- **Batch mode** — every part of a series in one pass, in several languages.
- **Cross-post captions** — TikTok, YouTube Shorts, Instagram Reels, Facebook Reels, X, Threads and Bluesky, each within its own limit.
- **Command palette** (Ctrl/⌘ + K) and keyboard shortcuts.
- **Contact emails by purpose** — one contact line, or separate lines for contact, advertising, game keys & playtest and copyright / DMCA, each purpose address checked for a word that says what it is for (`sponsor@…`, `keys@…`, `dmca@…`).
- **Guardrails** — length caps on every field and an opt-in **Strict Mode** that blocks copy and export while a field has an error.
- **Dark and light themes**, larger controls on touch screens, and an option to hide every scrollbar.
- **Desktop app** — Windows, macOS & Linux via Tauri; **Android app** — Android 11+, sideloaded from [Releases](https://github.com/poli0981/youtube-generator/releases).
## Quick Start
Use the web app: **<https://ytgenerator.stream>** — a quick bot check runs on your first visit each day.
Build it yourself:
```bash
git clone https://github.com/poli0981/youtube-generator.git
cd yt-desc-gen
cd youtube-generator
npm install
npm run dev # web dev server at http://localhost:5173
```
@@ -50,64 +59,67 @@ Desktop build (Windows / macOS / Linux):
```bash
npm run tauri:build
# Output: src-tauri/target/release/bundle/{msi,deb,dmg,app}
# Output: src-tauri/target/release/bundle/{msi,nsis,deb,rpm,appimage,dmg,app}
```
Android build (`.apk`) — requires the Android SDK + NDK + a JDK:
```bash
cargo tauri android init # one-time; generates src-tauri/gen/android
cargo tauri android build --apk
cargo tauri android build --apk # the Gradle project in src-tauri/gen/android is committed — don't re-run `init`
# Output: src-tauri/gen/android/app/build/outputs/apk/universal/release/
```
See [`docs/PACKAGING.md`](./docs/PACKAGING.md#android-apk-packaging) for the SDK/NDK setup and signing steps.
Full development setup, IDE config, and troubleshooting: see [`docs/DEVELOPMENT.md`](./docs/DEVELOPMENT.md). Vietnamese version: [`docs/i18n/vi/DEVELOPMENT.md`](./docs/i18n/vi/DEVELOPMENT.md).
See [`docs/PACKAGING.md`](./docs/PACKAGING.md#android-apk-packaging) for the SDK/NDK setup and signing, [`docs/DEVELOPMENT.md`](./docs/DEVELOPMENT.md) for the full toolchain (Vietnamese: [`docs/i18n/vi/DEVELOPMENT.md`](./docs/i18n/vi/DEVELOPMENT.md)), and [`docs/HOSTING.md`](./docs/HOSTING.md) for how the web app is hosted.
## Use Cases
- **Gameplay no-commentary channels** — the primary target. Default templates assume no voice-over and lean on visual hooks, music attribution, and timestamps.
- **Horror / scary-game channels** — the content-warning system is especially deep here (analog horror, liminal spaces, pursuit / chase, entity / SCP-style, body horror, etc.).
- **Gameplay no-commentary channels** — the primary target. Default templates assume no voice-over and lean on visual hooks, music attribution and timestamps.
- **Horror / scary-game channels** — the content-warning system is especially deep here (analog horror, liminal spaces, pursuit / chase, entity / SCP-style, body horror, …).
- **Demo / Early Access playthroughs** — dedicated video types and language-patch / game-version disclosure fields.
- **Speedrunners and 100% completionists** — playstyle disclosures, run-type metadata, and difficulty fields.
- **Solo creators tired of copy-paste** — profiles and presets exist specifically to eliminate repetitive data entry.
- **Speedrunners and 100% completionists** — playstyle disclosures, run-type metadata and difficulty fields.
- **Solo creators tired of copy-paste** — profiles, presets and templates exist to eliminate repetitive data entry.
## Privacy & Offline-First
## Privacy
Nothing leaves your device. No analytics, no telemetry, no tracking. The web version stores your work in `localStorage`; the desktop version stores it in the OS application-data directory. Clearing site data (web) or uninstalling the app (desktop) wipes everything. Full details in [PRIVACY.md](./PRIVACY.md).
- **Your work stays on your device**: the browser's storage for `ytgenerator.stream`, or the app's own folders on desktop and Android. No account, no YouTube access, nothing sold or shared.
- **The web app** is delivered by **Cloudflare**, which runs a **Turnstile** bot check once a day and provides **cookieless** visit statistics (Web Analytics). Two first-party cookies remember the check and the terms you accepted.
- **The desktop and Android apps** have no analytics, no bot check and no telemetry.
Full details: [PRIVACY.md](./PRIVACY.md), also at [ytgenerator.stream/legal/privacy](https://ytgenerator.stream/legal/privacy).
## Tech Stack
React 18 · TypeScript (strict) · Vite 8 · Tailwind CSS 3 · Zustand · i18next · Tauri 2 (Rust stable).
React 19 · TypeScript (strict) · Vite 8 · Tailwind CSS 4 · Radix · Motion · Zustand 5 · i18next · Tauri 2 (Rust) · Cloudflare Workers.
Architecture overview: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
## Documentation
| Document | What's in it |
| --- | --- |
| [Development Guide](./docs/DEVELOPMENT.md) | Toolchain, IDE setup, build commands, troubleshooting. *(Also: [Vietnamese](./docs/i18n/vi/DEVELOPMENT.md).)* |
| [Architecture](./docs/ARCHITECTURE.md) | Layer model, data flow, engine design. |
| [Features](./docs/FEATURES.md) | Full feature matrix. |
| [Content Inventory](./docs/CONTENT-INVENTORY.md) | Every video type, genre, and content warning the editor surfaces. *(Also: [Vietnamese](./docs/i18n/vi/CONTENT-INVENTORY.md).)* |
| [Roadmap](./docs/ROADMAP.md) | Development phases. |
| [Tech Spec](./docs/TECH-SPEC.md) | Implementation details and configs. |
| [i18n Guide](./docs/I18N.md) | Adding new locales. |
| [Packaging](./docs/PACKAGING.md) | Tauri desktop + Android release builds and signing. |
| [Contributing](./CONTRIBUTING.md) | PR process, commit conventions, auto-ignore rules. |
| [Security](./SECURITY.md) | Reporting vulnerabilities. |
| [Privacy](./PRIVACY.md) | Data handling (TL;DR: none). |
| [Disclaimer](./DISCLAIMER.md) | AI-assistance and translation-quality disclosure. *(Also: [Vietnamese](./docs/i18n/vi/DISCLAIMER.md).)* |
| [Terms of Use](./TERMS.md) | Acceptable use and license compliance. |
| [Code of Conduct](./CODE_OF_CONDUCT.md) | Contributor Covenant v2.1. |
| [Maintainers](./MAINTAINERS.md) | Who runs this. |
| [Third-Party Notices](./THIRD_PARTY_NOTICES.md) | Dependency attribution. |
| [Changelog](./CHANGELOG.md) | Per-release notes. |
| Document | What's in it |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Wiki](https://github.com/poli0981/youtube-generator/wiki)** | **User documentation** — quick start, backup & restore, every field and its limit, shortcuts, troubleshooting, FAQ. Start here if you're using the app rather than building it. |
| [Development Guide](./docs/DEVELOPMENT.md) | Toolchain, IDE setup, build commands, troubleshooting. _(Also: [Vietnamese](./docs/i18n/vi/DEVELOPMENT.md).)_ |
| [Hosting](./docs/HOSTING.md) | How ytgenerator.stream is built, deployed and protected. |
| [Architecture](./docs/ARCHITECTURE.md) | Layer model, data flow, engine design. |
| [Features](./docs/FEATURES.md) | Full feature matrix. |
| [Content Inventory](./docs/CONTENT-INVENTORY.md) | Every video type, genre, content warning and tech note the editor surfaces. _(Also: [Vietnamese](./docs/i18n/vi/CONTENT-INVENTORY.md).)_ |
| [Roadmap](./docs/ROADMAP.md) | What shipped and what's next. |
| [Tech Spec](./docs/TECH-SPEC.md) | Implementation details and configs. |
| [i18n Guide](./docs/I18N.md) | Adding new locales. |
| [Packaging](./docs/PACKAGING.md) | Tauri desktop + Android release builds and signing. |
| [Contributing](./CONTRIBUTING.md) | PR process, commit conventions, required checks. |
| [Security](./SECURITY.md) | Reporting vulnerabilities. |
| [Privacy](./PRIVACY.md) | What is stored where, and what Cloudflare processes. |
| [Terms of Use](./TERMS.md) | Acceptable use, license compliance, DMCA. |
| [Disclaimer](./DISCLAIMER.md) | AI-assistance and translation-quality disclosure. _(Also: [Vietnamese](./docs/i18n/vi/DISCLAIMER.md).)_ |
| [Code of Conduct](./CODE_OF_CONDUCT.md) | Contributor Covenant v2.1. |
| [Maintainers](./MAINTAINERS.md) | Who runs this. |
| [Third-Party Notices](./THIRD_PARTY_NOTICES.md) | Dependency attribution. |
| [Changelog](./CHANGELOG.md) | Per-release notes. |
## Contributing
PRs welcome — read [CONTRIBUTING.md](./CONTRIBUTING.md) first. Native-speaker corrections to AI-translated locales (JA / ES / KO / ZH) are especially appreciated.
PRs welcome — read [CONTRIBUTING.md](./CONTRIBUTING.md) first. Native-speaker corrections to the AI-translated locales (JA / ES / KO / ZH / PT-BR / ID) are especially appreciated.
## License
@@ -115,19 +127,30 @@ Licensed under the **[Apache License 2.0](./LICENSE)**. See [`NOTICE`](./NOTICE)
## AI Disclosure
This project was co-authored with **Anthropic's Claude Code (model 4.7 Opus, 1M-context variant)**. Source code, locale translations, documentation, and CI workflows were generated or edited with AI assistance, then reviewed by the human maintainer (`@poli0981`) before being committed. See [DISCLAIMER.md](./DISCLAIMER.md) for the full disclosure.
This project was co-authored with **Anthropic's Claude Code** (Claude Opus models; most recently Claude Opus 5.5). Source code, locale translations, documentation and CI workflows were generated or edited with AI assistance, then reviewed by the human maintainer (`@poli0981`) before being merged. See [DISCLAIMER.md](./DISCLAIMER.md) for the full disclosure.
## Contact
| For | Where |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Anything general | `contact@poli0981.dev` |
| Security vulnerabilities | [GitHub advisory](https://github.com/poli0981/youtube-generator/security/advisories/new) or `security@poli0981.dev` — see [SECURITY.md](./SECURITY.md) |
| Privacy and data requests | `privacy@poli0981.dev` |
| Terms, legal | `legal@poli0981.dev` |
| Copyright / DMCA notices | `dmca@poli0981.dev` |
| Licensing and attribution | `copyright@poli0981.dev` |
| Code, contributions, conduct | `code@poli0981.dev` |
| Sponsorship | `sponsor@poli0981.dev` |
Maintainer: [poli0981.dev](https://poli0981.dev/) · every channel at [poli0981.dev/links](https://poli0981.dev/links/).
## Channel & Socials
Reference channel and maintainer links:
- **YouTube**: [@SkullMute](https://www.youtube.com/@SkullMute)
- **X / Twitter**: [@SkullMute0011](https://x.com/SkullMute0011)
- **X**: [@SkullMute0011](https://x.com/SkullMute0011)
- **Bluesky**: [skullmute0011.bsky.social](https://bsky.app/profile/skullmute0011.bsky.social)
- **Mastodon**: [@skullmute1122@mastodon.social](https://mastodon.social/@skullmute1122)
- **Discord** (project / repo): [join](https://discord.gg/2aNR3aVt)
- **Discord** (gaming): [join](https://discord.gg/kDM9GMu5vm)
- **Discord**: [join](https://discord.gg/kDM9GMu5vm)
- **Steam**: [profile](https://steamcommunity.com/profiles/76561199544666292/)
- **Patreon / Ko-fi**: `skullmute`
- **Telegram**: `@SkullMute0011` (bot: `@my_skull_bot`)
- **Email** (security & private contact): `lopop05905@proton.me`
+27
View File
@@ -0,0 +1,27 @@
# REUSE (https://reuse.software) licensing information for the whole
# repository, checked in CI by .github/workflows/compliance.yml.
#
# Everything here is original work released under Apache-2.0 unless a more
# specific annotation below says otherwise. Add one whenever a file under
# another license lands (a font, a vendored icon set, …) — CI fails until it
# is declared.
version = 1
[[annotations]]
path = "**"
precedence = "aggregate"
SPDX-FileCopyrightText = "2026 poli0981 (SkullMute) and YTDescGen contributors"
SPDX-License-Identifier = "Apache-2.0"
# The Gradle wrapper that Tauri's Android template commits is Gradle's own
# code, not the project's: its headers read "Copyright 2015 the original
# author or authors" under Apache-2.0.
[[annotations]]
path = [
"src-tauri/gen/android/gradlew",
"src-tauri/gen/android/gradlew.bat",
"src-tauri/gen/android/gradle/wrapper/gradle-wrapper.jar",
]
precedence = "override"
SPDX-FileCopyrightText = "2015 the original author or authors"
SPDX-License-Identifier = "Apache-2.0"
+17 -9
View File
@@ -2,12 +2,12 @@
## Supported Versions
Only the latest released version of YTDescGen receives security updates. This is a solo open-source project; there are no LTS branches.
Only the latest released version of YTDescGen receives security updates, and the web app at https://ytgenerator.stream always runs the latest `main`. This is a solo open-source project; there are no LTS branches.
| Version | Supported |
| ------- | --------- |
| 0.13.x | ✅ |
| < 0.13 | ❌ |
| 1.2.x | ✅ |
| < 1.2 | ❌ |
## Reporting a Vulnerability
@@ -15,14 +15,16 @@ Please report security issues **privately**. Do not open a public issue.
**Preferred channels (in order):**
1. **GitHub Security Advisory** — open a draft advisory in this repository's `Security` tab.
2. **Email** — `lopop05905@proton.me` with subject prefix `[SECURITY]`.
1. **GitHub Security Advisory** — [open a draft advisory](https://github.com/poli0981/youtube-generator/security/advisories/new) in this repository.
2. **Email** — **security@poli0981.dev** with the subject prefix `[SECURITY]`.
The same contacts are published in [`/.well-known/security.txt`](https://ytgenerator.stream/.well-known/security.txt) (RFC 9116).
Include:
- A description of the issue and its potential impact.
- Steps to reproduce, ideally a minimal proof-of-concept.
- The affected version (`node -p "require('./package.json').version"`).
- The affected version (About page, or `node -p "require('./package.json').version"`) or URL.
- Whether the issue is already public.
## Response Timeline
@@ -35,16 +37,22 @@ Include:
In scope:
- The web bundle deployed to GitHub Pages.
- The Tauri desktop binaries (Windows, macOS, Linux).
- The web app at `ytgenerator.stream`, including its Cloudflare Worker (`worker/`): the Turnstile gate, its cookies, and the security headers.
- The desktop binaries (Windows, macOS, Linux) and the Android APK published on the GitHub releases page, including the Tauri commands in `src-tauri/`.
- CI/CD workflows in `.github/workflows/`.
Out of scope:
- Vulnerabilities in third-party dependencies — report those upstream and we'll bump.
- Issues requiring physical access to the user's device.
- Cloudflare's own platform (Turnstile, Workers, the CDN) — report to [Cloudflare](https://www.cloudflare.com/disclosure/).
- Volumetric denial-of-service, rate-limit or spam findings, and automated scanner output without a demonstrated impact.
- Issues requiring physical access to the user's device, or a malicious browser extension.
- Self-XSS in user-supplied template content (the app deliberately renders user input as plain text in the preview).
## Safe Harbour
Good-faith research that follows this policy — no data destruction, no privacy violations of other users, no service degradation, and private reporting — will not be pursued.
## No Bounty
This is a solo open-source project. Credit in release notes and a thank-you in `MAINTAINERS.md` is the only reward we can offer.
+20 -15
View File
@@ -1,14 +1,14 @@
# Terms of Use
**Effective:** 2026-05-14
**Effective:** 2026-09-30
These terms govern your use of YTDescGen — both the web version hosted at the project's GitHub Pages URL and any Tauri desktop binaries distributed under this project.
These terms govern your use of YTDescGen — the web app at **https://ytgenerator.stream** and the desktop and Android apps distributed from this project's [GitHub releases](https://github.com/poli0981/youtube-generator/releases). By using YTDescGen you agree to them, together with the [Privacy Policy](PRIVACY.md) and the [Disclaimer](DISCLAIMER.md).
## License
YTDescGen is licensed under the **[Apache License 2.0](./LICENSE)**. You may use, modify, and redistribute it under those terms.
YTDescGen's source code is licensed under the **[Apache License 2.0](LICENSE)**. You may use, modify, and redistribute it under those terms.
Apache 2.0 grants a patent license (Section 3) and an irrevocable copyright license (Section 2). It does **not** grant trademark rights — see Section 6 of the LICENSE.
Apache 2.0 grants a patent license (Section 3) and an irrevocable copyright license (Section 2). It does **not** grant trademark rights — see Section 6 of the LICENSE. The name "YTDescGen" and its logo identify this project; forks should use their own name.
## Acceptable Use
@@ -21,18 +21,19 @@ You may use YTDescGen for any lawful purpose. You may **not** use it to:
- Violate applicable law in your jurisdiction, including but not limited to **GDPR** (EU), **CCPA / CPRA** (California), **PIPL** (China), **LGPD** (Brazil), the **Vietnamese Cybersecurity Law**, or equivalent data-protection / cybercrime regulation in your country.
- Bypass YouTube's policies on metadata (misleading thumbnails / titles / tags) using the application.
## GitHub Terms
## The web app
If you use the web version hosted on GitHub Pages, your use is also subject to:
The web app is hosted on Cloudflare. To keep it available for people, it asks each browser to pass a short **Cloudflare Turnstile** check before entering. When using the web app you must not:
- [GitHub's Terms of Service](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service)
- [GitHub's Acceptable Use Policies](https://docs.github.com/en/site-policy/acceptable-use-policies)
- Attempt to bypass, automate, or defeat the check, or reuse its cookies outside the browser that earned them.
- Scrape, crawl at volume, load-test, or otherwise place an unreasonable load on the site.
- Probe for vulnerabilities outside the process in the [Security Policy](SECURITY.md).
These apply alongside this document; in case of conflict, GitHub's policies govern the hosted artifact.
The web app is provided free of charge and may be changed, rate-limited, or taken offline at any time without notice. The desktop and Android apps work without it.
## No Warranty
See [DISCLAIMER.md](./DISCLAIMER.md) and `LICENSE` §§ 7–8. The software is provided **as-is** with no warranty of any kind, express or implied.
See [DISCLAIMER.md](DISCLAIMER.md) and `LICENSE` §§ 7–8. The software is provided **as-is** with no warranty of any kind, express or implied.
## Generated Content
@@ -43,6 +44,10 @@ YTDescGen produces text intended to be pasted into YouTube descriptions. **You
- Not including misleading information, copyright-infringing material, or any prohibited content listed in YouTube's policies.
- Truthful representation of run-type, difficulty, blind status, mod / cheat usage, and similar disclosures the application optionally exposes.
## Copyright Complaints
If you believe material in this project's repository, releases or website infringes your copyright, send a notice to **dmca@poli0981.dev** with: identification of the work, the location of the material, your contact details, a good-faith statement that the use is not authorised, and a statement — under penalty of perjury — that the notice is accurate and that you are the owner or authorised to act for the owner. Licensing and attribution questions go to **copyright@poli0981.dev**.
## Contributions
By submitting a contribution (issue, pull request, comment, locale translation, screenshot, log dump), you agree:
@@ -50,18 +55,18 @@ By submitting a contribution (issue, pull request, comment, locale translation,
1. Your contribution is licensed under Apache 2.0, the same as the project.
2. You have the right to grant that license (you wrote it, or it's compatibly licensed and credited).
3. You will not include malicious code or knowingly vulnerable dependencies.
4. You will follow the [Code of Conduct](./CODE_OF_CONDUCT.md) and [Contributing Guide](./CONTRIBUTING.md).
4. You will follow the [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](CONTRIBUTING.md).
Violations may result in your contribution being closed and, in severe cases, a permanent ban from the repository — see `CONTRIBUTING.md` § "Auto-ignored Contributions".
Violations may result in your contribution being closed and, in severe cases, a permanent ban from the repository — see `CONTRIBUTING.md` § "Auto-ignored Contributions". Contributions made on GitHub are also subject to [GitHub's Terms of Service](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service).
## Termination
These terms remain in effect for as long as you use the software. Your rights under Apache 2.0 are perpetual subject to that license's termination clauses (notably § 3 patent retaliation).
These terms remain in effect for as long as you use the software. Your rights under Apache 2.0 are perpetual subject to that license's termination clauses (notably § 3 patent retaliation). Access to the web app may be refused to anyone who breaks the rules in "The web app" above.
## Changes
Updates to these terms are committed under `TERMS.md` with the `Effective` date updated. Continued use of the software after a change constitutes acceptance.
Updates are published at [ytgenerator.stream/legal/terms](https://ytgenerator.stream/legal/terms) and in the repository's `TERMS.md`, with the `Effective` date updated. When a change is material, the app asks you to review and accept it again; continued use after that constitutes acceptance.
## Contact
`lopop05905@proton.me`
Legal questions: **legal@poli0981.dev** · Everything else: **contact@poli0981.dev**
+80 -55
View File
@@ -1,79 +1,104 @@
<!-- Generated by scripts/third-party.ts (npm run generate:third-party). Edit the script, not this file; CI fails when it is stale. -->
# Third-Party Notices
YTDescGen incorporates the following third-party software. Each dependency retains its own license; consult the linked project page for the full text of each license.
YTDescGen is built on the open-source software and services below. Each component keeps its own license; the linked project pages carry the full terms.
## Runtime Dependencies (web bundle)
The **complete license text of every package bundled into the web app** — including transitive dependencies such as `scheduler` or `@babel/runtime` — is published with each release at [`/licenses/third-party.md`](https://ytgenerator.stream/licenses/third-party.md), generated by Vite from the exact build.
## Runtime dependencies
Bundled into the web app and the desktop / Android apps.
| Package | Version | License | Project |
| --- | --- | --- | --- |
| `react` | ^18.3.0 | MIT | <https://github.com/facebook/react> |
| `react-dom` | ^18.3.0 | MIT | <https://github.com/facebook/react> |
| `react-router-dom` | ^6.26.0 | MIT | <https://github.com/remix-run/react-router> |
| `react-i18next` | ^15.0.0 | MIT | <https://github.com/i18next/react-i18next> |
| `i18next` | ^23.15.0 | MIT | <https://github.com/i18next/i18next> |
| `zustand` | ^4.5.0 | MIT | <https://github.com/pmndrs/zustand> |
| `react-hot-toast` | ^2.4.0 | MIT | <https://github.com/timolins/react-hot-toast> |
| `lucide-react` | ^0.400.0 | ISC | <https://github.com/lucide-icons/lucide> |
| `clsx` | ^2.1.0 | MIT | <https://github.com/lukeed/clsx> |
| `@tauri-apps/api` | ^2.11.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/tauri> |
| `@tauri-apps/plugin-dialog` | ^2.0.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `@tauri-apps/plugin-fs` | ^2.0.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `@tauri-apps/plugin-opener` | ^2.0.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `@tauri-apps/plugin-shell` | ^2.0.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `@fontsource-variable/inter` | 5.3.0 | OFL-1.1 | <https://github.com/fontsource/font-files> |
| `@fontsource-variable/jetbrains-mono` | 5.3.0 | OFL-1.1 | <https://github.com/fontsource/font-files> |
| `@tauri-apps/api` | 2.12.4 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/tauri> |
| `@tauri-apps/plugin-opener` | 2.7.2 | MIT OR Apache-2.0 | <https://github.com/tauri-apps/plugins-workspace> |
| `clsx` | 2.1.1 | MIT | <https://github.com/lukeed/clsx> |
| `cmdk` | 1.1.1 | MIT | <https://github.com/pacocoursey/cmdk> |
| `i18next` | 26.4.5 | MIT | <https://github.com/i18next/i18next> |
| `i18next-resources-to-backend` | 1.2.3 | MIT | <https://github.com/i18next/i18next-resources-to-backend> |
| `lucide-react` | 1.57.0 | ISC | <https://github.com/lucide-icons/lucide> |
| `motion` | 13.5.1 | MIT | <https://github.com/motiondivision/motion> |
| `radix-ui` | 1.8.1 | MIT | <https://github.com/radix-ui/primitives> |
| `react` | 19.3.0 | MIT | <https://github.com/react/react> |
| `react-dom` | 19.3.0 | MIT | <https://github.com/react/react> |
| `react-i18next` | 17.0.16 | MIT | <https://github.com/i18next/react-i18next> |
| `react-router-dom` | 7.18.4 | MIT | <https://github.com/remix-run/react-router> |
| `simple-icons` | 16.33.0 | CC0-1.0 | <https://simpleicons.org> |
| `sonner` | 2.0.8 | MIT | <https://github.com/emilkowalski/sonner> |
| `zustand` | 5.0.15 | MIT | <https://github.com/pmndrs/zustand> |
## Build / Dev Dependencies
## Build and development tools
Used to build, test and check YTDescGen. Not shipped to users.
| Package | Version | License | Project |
| --- | --- | --- | --- |
| `vite` | ^7.3.3 | MIT | <https://github.com/vitejs/vite> |
| `@vitejs/plugin-react` | ^4.3.0 | MIT | <https://github.com/vitejs/vite-plugin-react> |
| `typescript` | ^5.5.0 | Apache-2.0 | <https://github.com/microsoft/TypeScript> |
| `tsx` | ^4.16.0 | MIT | <https://github.com/privatenumber/tsx> |
| `tailwindcss` | ^3.4.0 | MIT | <https://github.com/tailwindlabs/tailwindcss> |
| `prettier-plugin-tailwindcss` | ^0.6.0 | MIT | <https://github.com/tailwindlabs/prettier-plugin-tailwindcss> |
| `postcss` | ^8.5.14 | MIT | <https://github.com/postcss/postcss> |
| `autoprefixer` | ^10.4.0 | MIT | <https://github.com/postcss/autoprefixer> |
| `eslint` | ^9.0.0 | MIT | <https://github.com/eslint/eslint> |
| `@eslint/js` | ^9.0.0 | MIT | <https://github.com/eslint/eslint> |
| `eslint-plugin-react-hooks` | ^5.0.0 | MIT | <https://github.com/facebook/react> |
| `typescript-eslint` | ^8.0.0 | MIT | <https://github.com/typescript-eslint/typescript-eslint> |
| `prettier` | ^3.3.0 | MIT | <https://github.com/prettier/prettier> |
| `vitest` | ^3.2.4 | MIT | <https://github.com/vitest-dev/vitest> |
| `@testing-library/react` | ^16.0.0 | MIT | <https://github.com/testing-library/react-testing-library> |
| `@testing-library/jest-dom` | ^6.4.0 | MIT | <https://github.com/testing-library/jest-dom> |
| `@types/react` | ^18.3.0 | MIT | DefinitelyTyped |
| `@types/react-dom` | ^18.3.0 | MIT | DefinitelyTyped |
| `@eslint/js` | 10.0.1 | MIT | <https://github.com/eslint/eslint> |
| `@resvg/resvg-js` | 2.6.2 | MPL-2.0 | — |
| `@tailwindcss/postcss` | 4.3.3 | MIT | <https://github.com/tailwindlabs/tailwindcss> |
| `@tauri-apps/cli` | 2.12.3 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/tauri> |
| `@testing-library/jest-dom` | 7.0.1 | MIT | <https://github.com/testing-library/jest-dom> |
| `@testing-library/react` | 16.3.3 | MIT | <https://github.com/testing-library/react-testing-library> |
| `@types/node` | 26.6.3 | MIT | <https://github.com/DefinitelyTyped/DefinitelyTyped> |
| `@types/react` | 19.3.0 | MIT | <https://github.com/DefinitelyTyped/DefinitelyTyped> |
| `@types/react-dom` | 19.3.0 | MIT | <https://github.com/DefinitelyTyped/DefinitelyTyped> |
| `@typescript/typescript6` | 6.0.2 | Apache-2.0 | <https://github.com/microsoft/TypeScript> |
| `@vitejs/plugin-react` | 6.1.2 | MIT | <https://github.com/vitejs/vite-plugin-react> |
| `@vitest/coverage-v8` | 4.1.12 | MIT | <https://github.com/vitest-dev/vitest> |
| `autoprefixer` | 10.6.1 | MIT | <https://github.com/postcss/autoprefixer> |
| `eslint` | 10.12.0 | MIT | <https://github.com/eslint/eslint> |
| `eslint-plugin-react-hooks` | 7.1.1 | MIT | <https://github.com/facebook/react> |
| `knip` | 6.41.0 | ISC | <https://github.com/webpro-nl/knip> |
| `marked` | 18.1.1 | MIT | <https://github.com/markedjs/marked> |
| `postcss` | 8.5.30 | MIT | <https://github.com/postcss/postcss> |
| `prettier` | 3.9.10 | MIT | <https://github.com/prettier/prettier> |
| `prettier-plugin-tailwindcss` | 0.8.1 | MIT | <https://github.com/tailwindlabs/prettier-plugin-tailwindcss> |
| `tailwindcss` | 4.3.3 | MIT | <https://github.com/tailwindlabs/tailwindcss> |
| `tsx` | 4.23.15 | MIT | <https://github.com/privatenumber/tsx> |
| `typescript` | 7.0.2 | Apache-2.0 | <https://github.com/microsoft/TypeScript> |
| `typescript-eslint` | 8.71.2 | MIT | <https://github.com/typescript-eslint/typescript-eslint> |
| `vite` | 8.3.4 | MIT | <https://github.com/vitejs/vite> |
| `vitest` | 4.1.12 | MIT | <https://github.com/vitest-dev/vitest> |
| `wrangler` | 4.149.0 | MIT OR Apache-2.0 | <https://github.com/cloudflare/workers-sdk> |
## Tauri Desktop (Rust crates)
## Desktop and Android shell (Rust crates)
Direct dependencies of `src-tauri/`. Transitive crates are checked in CI by `cargo deny` (see `src-tauri/deny.toml`); `cargo tree` lists them all.
| Crate | Version | License | Project |
| --- | --- | --- | --- |
| `tauri` | ^2 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/tauri> |
| `tauri-build` | ^2 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/tauri> |
| `tauri-plugin-dialog` | ^2 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `tauri-plugin-fs` | ^2 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `tauri-plugin-opener` | ^2 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `tauri-plugin-shell` | ^2 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `tauri-plugin-single-instance` | ^2 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `serde` | ^1 | Apache-2.0 OR MIT | <https://github.com/serde-rs/serde> |
| `serde_json` | ^1 | Apache-2.0 OR MIT | <https://github.com/serde-rs/json> |
| `serde` | 1.0.228 | MIT OR Apache-2.0 | <https://github.com/serde-rs/serde> |
| `tauri` | 2.12.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/tauri> |
| `tauri-build` | 2.7.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/tauri> |
| `tauri-plugin-dialog` | 2.8.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `tauri-plugin-opener` | 2.7.0 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
| `tauri-plugin-single-instance` | 2.5.1 | Apache-2.0 OR MIT | <https://github.com/tauri-apps/plugins-workspace> |
Transitive dependencies are not enumerated here. `cargo tree` (in `src-tauri/`) and `npm list --all` produce the exhaustive trees; this list covers the direct dependencies declared in `package.json` and `src-tauri/Cargo.toml`.
## Fonts and icons
## Fonts & Icons
- **Icons:** [Lucide](https://lucide.dev/) (`lucide-react`, ISC). Brand marks, where shown, come from [Simple Icons](https://simpleicons.org/) (CC0-1.0); the trademarks belong to their owners.
- **Fonts:** [Inter](https://rsms.me/inter/) and [JetBrains Mono](https://www.jetbrains.com/lp/mono/), bundled with the app from the `@fontsource-variable` packages above (SIL Open Font License 1.1, `OFL-1.1`).
The application uses **system fonts** (`Inter` / `SF Pro` / `Segoe UI` / `Roboto`, fallback `sans-serif`). No custom font files are bundled in the web build.
## Services (web app only)
Icons are provided by [`lucide-react`](https://github.com/lucide-icons/lucide) (ISC license — see above).
The web app at ytgenerator.stream is delivered by Cloudflare. These are services, not bundled code; the [Privacy Policy](PRIVACY.md) explains what each processes.
## AI-Assisted Development Disclosure
| Service | Purpose | Terms |
| --- | --- | --- |
| Cloudflare Workers | Hosting and delivery | <https://www.cloudflare.com/terms/> |
| Cloudflare Turnstile | Bot check before entering | <https://www.cloudflare.com/turnstile-privacy-policy/> |
| Cloudflare Web Analytics | Cookieless, aggregate visit statistics | <https://www.cloudflare.com/privacypolicy/> |
Per [`DISCLAIMER.md`](./DISCLAIMER.md), this project was co-authored with **Anthropic's Claude Code (model 4.7 Opus, 1M-context variant)**. The model contributed to source code, locale translations, documentation, and CI configuration. All output was reviewed by the human maintainer (`@poli0981`) before being committed.
The desktop and Android apps use none of them.
No third-party content was reproduced verbatim from the model's training data. Any external text quoted in this repository (notably the Apache License 2.0 in [`LICENSE`](./LICENSE) and the Contributor Covenant link in [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)) is sourced from canonical public locations.
## AI-assisted development
Claude is a product of Anthropic, PBC — <https://www.anthropic.com>. No license is granted by Anthropic to use this project; the Apache 2.0 license in `LICENSE` is granted by `@poli0981` as the project author.
As described in the [Disclaimer](DISCLAIMER.md), YTDescGen is developed with **Anthropic's Claude Code** (Claude Opus models). The model contributes source code, translations, documentation and CI configuration; every change is reviewed by the maintainer (`@poli0981`) before it is merged. Claude is a product of Anthropic, PBC — <https://www.anthropic.com>. The Apache-2.0 license in [`LICENSE`](LICENSE) is granted by the project author, not by Anthropic.
## Reporting an Omission
## Questions and omissions
If you believe a dependency is missing from this list, please open an issue or PR per [`CONTRIBUTING.md`](./CONTRIBUTING.md).
Licensing and attribution questions: **copyright@poli0981.dev**. If you believe something is missing here, open an issue or pull request per [`CONTRIBUTING.md`](CONTRIBUTING.md).
+11
View File
@@ -0,0 +1,11 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
<!-- Android adaptive-icon foreground: glyph only, transparent canvas. The
launcher masks a 108dp layer down to a ~66dp circle, so the artwork is
scaled to keep its bounding-box diagonal inside that safe zone. The
background layer is the flat brand colour in ic_launcher_background.xml. -->
<g transform="translate(256 256) scale(.72) translate(-256 -252)">
<path d="M176 118c0-17.9 19.4-29.1 34.9-20.1l128.2 74c15.5 9 15.5 31.2 0 40.2l-128.2 74C195.4 295.1 176 283.9 176 266z" fill="#fff"/>
<rect x="136" y="322" width="240" height="32" rx="16" fill="#fff" fill-opacity=".92"/>
<rect x="136" y="374" width="160" height="32" rx="16" fill="#fff" fill-opacity=".6"/>
</g>
</svg>

After

Width:  |  Height:  |  Size: 779 B

+16
View File
@@ -0,0 +1,16 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
<defs>
<linearGradient id="ytg-bg" x1="0" y1="0" x2="512" y2="512" gradientUnits="userSpaceOnUse">
<stop offset="0" stop-color="#6366F1"/>
<stop offset="1" stop-color="#A855F7"/>
</linearGradient>
</defs>
<!-- Full-bleed: the platform applies its own mask. Artwork sits inside the
80% safe zone (a 0.72 scale about the centre keeps every corner in). -->
<rect width="512" height="512" fill="url(#ytg-bg)"/>
<g transform="translate(256 256) scale(.72) translate(-256 -251)">
<path d="M176 118c0-17.9 19.4-29.1 34.9-20.1l128.2 74c15.5 9 15.5 31.2 0 40.2l-128.2 74C195.4 295.1 176 283.9 176 266z" fill="#fff"/>
<rect x="136" y="322" width="240" height="32" rx="16" fill="#fff" fill-opacity=".92"/>
<rect x="136" y="374" width="160" height="32" rx="16" fill="#fff" fill-opacity=".6"/>
</g>
</svg>

After

Width:  |  Height:  |  Size: 907 B

+12
View File
@@ -0,0 +1,12 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
<defs>
<linearGradient id="ytg-bg" x1="40" y1="24" x2="472" y2="488" gradientUnits="userSpaceOnUse">
<stop offset="0" stop-color="#6366F1"/>
<stop offset="1" stop-color="#A855F7"/>
</linearGradient>
</defs>
<rect width="512" height="512" rx="120" fill="url(#ytg-bg)"/>
<path d="M176 118c0-17.9 19.4-29.1 34.9-20.1l128.2 74c15.5 9 15.5 31.2 0 40.2l-128.2 74C195.4 295.1 176 283.9 176 266z" fill="#fff"/>
<rect x="136" y="322" width="240" height="32" rx="16" fill="#fff" fill-opacity=".92"/>
<rect x="136" y="374" width="160" height="32" rx="16" fill="#fff" fill-opacity=".6"/>
</svg>

After

Width:  |  Height:  |  Size: 678 B

+33
View File
@@ -0,0 +1,33 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
<defs>
<linearGradient id="ytg-bg" x1="40" y1="24" x2="472" y2="488" gradientUnits="userSpaceOnUse">
<stop offset="0" stop-color="#6366F1"/>
<stop offset="1" stop-color="#A855F7"/>
</linearGradient>
<radialGradient id="glow-a" cx="1040" cy="40" r="620" gradientUnits="userSpaceOnUse">
<stop offset="0" stop-color="#7C3AED" stop-opacity=".42"/>
<stop offset="1" stop-color="#7C3AED" stop-opacity="0"/>
</radialGradient>
<radialGradient id="glow-b" cx="120" cy="640" r="520" gradientUnits="userSpaceOnUse">
<stop offset="0" stop-color="#4F46E5" stop-opacity=".30"/>
<stop offset="1" stop-color="#4F46E5" stop-opacity="0"/>
</radialGradient>
</defs>
<rect width="1200" height="630" fill="#0B0B12"/>
<rect width="1200" height="630" fill="url(#glow-a)"/>
<rect width="1200" height="630" fill="url(#glow-b)"/>
<g transform="translate(96 179) scale(.53125)">
<rect width="512" height="512" rx="120" fill="url(#ytg-bg)"/>
<path d="M176 118c0-17.9 19.4-29.1 34.9-20.1l128.2 74c15.5 9 15.5 31.2 0 40.2l-128.2 74C195.4 295.1 176 283.9 176 266z" fill="#fff"/>
<rect x="136" y="322" width="240" height="32" rx="16" fill="#fff" fill-opacity=".92"/>
<rect x="136" y="374" width="160" height="32" rx="16" fill="#fff" fill-opacity=".6"/>
</g>
<g font-family="Segoe UI, Inter, Helvetica Neue, Arial, sans-serif">
<text x="410" y="268" font-size="92" font-weight="700" fill="#F4F4F8" letter-spacing="-1.5">YTDescGen</text>
<text x="412" y="334" font-size="34" fill="#B4B4C6">Titles, descriptions &amp; tags for gameplay videos</text>
<text x="412" y="384" font-size="28" fill="#8E8EA6">8 languages · Web · Windows · macOS · Linux · Android</text>
<text x="412" y="452" font-size="30" font-weight="600" fill="#A5A6FB">ytgenerator.stream</text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 1.9 KiB

+341
View File
@@ -0,0 +1,341 @@
import { readFileSync } from "fs";
import { posix, resolve } from "path";
import { Marked, type Tokens } from "marked";
import type { Plugin } from "vite";
import { LOGO_SVG, SITE_ORIGIN, copyrightYears } from "../src/config/brand.ts";
import { LEGAL_DOCS, legalDocPath, type LegalDoc, type LegalDocId } from "../src/config/legal.ts";
/**
* Renders the repo-root legal documents at build time, twice:
*
* 1. `virtual:legal-docs` — { [id]: { title, effective, html: { en, vi? } } },
* imported lazily by the in-app Legal Center, so desktop and Android carry
* the documents offline and nothing is fetched from GitHub any more.
* 2. `dist/legal/<id>.html` (+ `<id>.vi.html`, `index.html`) — plain pages
* with no script, which the Cloudflare Worker serves to anyone, before the
* Turnstile gate: people must be able to read the Terms and the Privacy
* Policy before they are asked to agree to them.
*
* `marked` runs only here, in Node — it adds nothing to the app bundle.
*/
const VIRTUAL_ID = "virtual:legal-docs";
const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_ID}`;
const REPO_BLOB = "https://github.com/poli0981/youtube-generator/blob/main/";
const ROOT = resolve(import.meta.dirname, "..");
type DocLang = "en" | "vi";
export interface RenderedLegalDoc {
title: string;
/** ISO date from an `**Effective:**` / `**Last updated:**` line, if any. */
effective: string | null;
html: Partial<Record<DocLang, string>>;
}
/** Repo-relative source file → document id, for cross-document links. */
const SOURCE_TO_ID: ReadonlyMap<string, LegalDocId> = new Map(
LEGAL_DOCS.flatMap((doc): [string, LegalDocId][] =>
doc.sourceVi
? [
[doc.source, doc.id],
[doc.sourceVi, doc.id],
]
: [[doc.source, doc.id]],
),
);
/** Titles for the plain-text sources, which have no heading to read. */
const PLAIN_TEXT_TITLES: Partial<Record<LegalDocId, string>> = {
license: "Apache License 2.0",
notice: "NOTICE",
};
const HTML_ESCAPES: Readonly<Record<string, string>> = {
"&": "&amp;",
"<": "&lt;",
">": "&gt;",
'"': "&quot;",
"'": "&#39;",
};
export function escapeHtml(text: string): string {
return text.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch] ?? ch);
}
/** Point relative links at the in-site page, or at GitHub for anything else. */
export function rewriteHref(href: string, fromFile: string): string {
if (/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(href)) return href;
const hashAt = href.indexOf("#");
const pathPart = hashAt >= 0 ? href.slice(0, hashAt) : href;
const hash = hashAt >= 0 ? href.slice(hashAt) : "";
const resolved = posix.normalize(posix.join(posix.dirname(fromFile), pathPart));
const id = SOURCE_TO_ID.get(resolved);
return id ? `${legalDocPath(id)}${hash}` : `${REPO_BLOB}${resolved}${hash}`;
}
/**
* Heading text → anchor id. Everything that is not a letter or digit becomes a
* hyphen, which also rules out any markup ending up in an attribute.
*/
function slugify(text: string): string {
return (
text
.toLowerCase()
.replace(/[^\p{L}\p{N}]+/gu, "-")
// The line above leaves at most one hyphen in a row.
.replace(/^-|-$/g, "")
);
}
function stripInlineMarkdown(text: string): string {
return (
text
.replace(/[`*_~]/g, "")
// Neither part may contain `[`, so a failed match is never re-scanned
// from a later `[` inside it (linear even on unbalanced brackets).
.replace(/\[([^[\]]+)\]\([^)[]*\)/g, "$1")
.trim()
);
}
export function renderMarkdown(source: string, fromFile: string): { title: string; html: string } {
// Links are rewritten in the renderer rather than a `walkTokens` hook: that
// hook only runs inside `marked.parse()`, and this renders via
// `lexer()` + `parser()` so it can read the title from the tokens.
const marked = new Marked({
gfm: true,
renderer: {
heading({ tokens, depth, text }) {
const inner = this.parser.parseInline(tokens);
return `<h${depth} id="${slugify(text)}">${inner}</h${depth}>\n`;
},
link({ href, title, tokens }) {
const inner = this.parser.parseInline(tokens);
const target = rewriteHref(href, fromFile);
const external = /^https?:/i.test(target);
const titleAttr = title ? ` title="${escapeHtml(title)}"` : "";
const rel = external ? ` target="_blank" rel="noopener noreferrer"` : "";
return `<a href="${escapeHtml(target)}"${titleAttr}${rel}>${inner}</a>`;
},
},
});
const tokens = marked.lexer(source);
const h1 = tokens.find((t): t is Tokens.Heading => t.type === "heading" && t.depth === 1);
const html = marked.parser(tokens);
return { title: h1 ? stripInlineMarkdown(h1.text) : "", html };
}
export function extractEffectiveDate(source: string): string | null {
const match =
/\*\*(?:Effective(?: date)?|Last updated|Ngày hiệu lực|Cập nhật lần cuối):?\*\*:?\s*(\d{4}-\d{2}-\d{2})/i.exec(
source,
);
return match?.[1] ?? null;
}
function readSource(file: string): string {
return readFileSync(resolve(ROOT, file), "utf8").replace(/\r\n/g, "\n");
}
function renderSource(doc: LegalDoc, file: string): { title: string; html: string } {
const text = readSource(file);
if (file.endsWith(".md")) return renderMarkdown(text, file);
return {
title: PLAIN_TEXT_TITLES[doc.id] ?? doc.id,
html: `<pre class="plain">${escapeHtml(text.trim())}</pre>`,
};
}
export function renderAllLegalDocs(): Record<LegalDocId, RenderedLegalDoc> {
const out = {} as Record<LegalDocId, RenderedLegalDoc>;
for (const doc of LEGAL_DOCS) {
const en = renderSource(doc, doc.source);
const rendered: RenderedLegalDoc = {
title: en.title,
effective: extractEffectiveDate(readSource(doc.source)),
html: { en: en.html },
};
if (doc.sourceVi) rendered.html.vi = renderSource(doc, doc.sourceVi).html;
out[doc.id] = rendered;
}
return out;
}
// ---------------------------------------------------------------------------
// Static pages
const PAGE_CSS = `
:root{color-scheme:dark light;--bg:#0b0b12;--card:#12121a;--border:#262636;--text:#e7e7ef;--muted:#9a9ab0;--link:#a5a6fb;--code:#1b1b27;font-family:system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif}
@media (prefers-color-scheme:light){:root{--bg:#f7f7fb;--card:#fff;--border:#e3e3ee;--text:#17171f;--muted:#5b5b70;--link:#4f46e5;--code:#f1f1f7}}
*{box-sizing:border-box}
body{margin:0;background:var(--bg);color:var(--text);line-height:1.65}
a{color:var(--link)}
a:focus-visible{outline:2px solid var(--link);outline-offset:2px}
.top{position:sticky;top:0;z-index:1;display:flex;align-items:center;justify-content:space-between;gap:12px;padding:12px 20px;background:color-mix(in srgb,var(--bg) 86%,transparent);backdrop-filter:blur(10px);border-bottom:1px solid var(--border)}
.brand{display:flex;align-items:center;gap:10px;color:var(--text);text-decoration:none;font-weight:700;letter-spacing:-.01em}
.brand svg{width:28px;height:28px}
.open{font-size:14px;font-weight:600;text-decoration:none;padding:7px 14px;border-radius:10px;color:#fff;background:linear-gradient(135deg,#6366f1,#a855f7)}
.layout{display:grid;grid-template-columns:220px minmax(0,1fr);gap:32px;max-width:1080px;margin:0 auto;padding:32px 20px 64px}
nav p{margin:0 0 8px;font-size:12px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}
nav ul{list-style:none;margin:0;padding:0;position:sticky;top:76px}
nav a{display:block;padding:6px 10px;border-radius:8px;color:var(--muted);text-decoration:none;font-size:14px}
nav a:hover{color:var(--text);background:var(--card)}
nav a[aria-current=page]{color:var(--text);background:var(--card);font-weight:600}
article{min-width:0;background:var(--card);border:1px solid var(--border);border-radius:16px;padding:28px 32px}
.meta{display:flex;flex-wrap:wrap;gap:8px 16px;margin:0 0 20px;font-size:13px;color:var(--muted)}
article h1{font-size:28px;line-height:1.25;margin:0 0 8px;letter-spacing:-.015em}
article h2{font-size:20px;margin:32px 0 10px;padding-top:8px;border-top:1px solid var(--border)}
article h3{font-size:16px;margin:24px 0 8px}
article p,article li{font-size:15px}
article table{width:100%;border-collapse:collapse;margin:16px 0;font-size:14px;display:block;overflow-x:auto}
article th,article td{text-align:left;padding:8px 10px;border-bottom:1px solid var(--border);vertical-align:top}
article code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.88em;background:var(--code);padding:.12em .38em;border-radius:6px}
article pre{background:var(--code);padding:16px;border-radius:12px;overflow-x:auto;font-size:13px;line-height:1.55}
article pre code{background:none;padding:0}
article pre.plain{white-space:pre-wrap;word-break:break-word}
article blockquote{margin:16px 0;padding:4px 16px;border-left:3px solid #6366f1;color:var(--muted)}
.cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(230px,1fr));gap:12px;margin-top:20px}
.cards a{display:block;padding:16px;border:1px solid var(--border);border-radius:12px;text-decoration:none;color:var(--text);background:var(--bg)}
.cards a:hover{border-color:#6366f1}
.cards span{display:block;font-size:13px;color:var(--muted);margin-top:4px;line-height:1.5}
footer{max-width:1080px;margin:0 auto;padding:0 20px 40px;font-size:13px;color:var(--muted)}
@media (max-width:760px){.layout{grid-template-columns:1fr;padding-top:20px}nav ul{position:static;display:flex;flex-wrap:wrap;gap:4px}article{padding:20px 18px}}
`;
/** One-line summaries for the static Legal index (English, like the pages). */
const DOC_SUMMARIES: Readonly<Record<LegalDocId, string>> = {
terms: "What you may and may not do with YTDescGen and what it generates.",
privacy: "What stays on your device, and what Cloudflare processes on the web.",
disclaimer: "No warranty, AI-assisted development and translations, no affiliation.",
license: "The Apache License 2.0 the source code is released under.",
"third-party": "Open-source libraries, fonts and services YTDescGen relies on.",
security: "How to report a vulnerability privately, and what is in scope.",
notice: "The Apache-2.0 NOTICE file with copyright and attribution.",
conduct: "Contributor Covenant rules for the project's community spaces.",
};
function pageShell(options: {
title: string;
canonicalPath: string;
description: string;
activeId: LegalDocId | null;
body: string;
lang: DocLang;
}): string {
const nav = LEGAL_DOCS.map((doc) => {
const current = doc.id === options.activeId ? ' aria-current="page"' : "";
return `<li><a href="${legalDocPath(doc.id)}"${current}>${escapeHtml(TITLE_BY_ID[doc.id])}</a></li>`;
}).join("");
return `<!doctype html>
<html lang="${options.lang}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="dark light">
<meta name="theme-color" content="#0b0b12">
<title>${escapeHtml(options.title)} — YTDescGen</title>
<meta name="description" content="${escapeHtml(options.description)}">
<link rel="canonical" href="${SITE_ORIGIN}${options.canonicalPath}">
<link rel="icon" type="image/svg+xml" href="/favicon.svg">
<style>${PAGE_CSS}</style>
</head>
<body>
<header class="top"><a class="brand" href="/">${LOGO_SVG}<span>YTDescGen</span></a><a class="open" href="/">Open the app</a></header>
<div class="layout">
<nav aria-label="Legal documents"><p>Legal</p><ul>${nav}</ul></nav>
<main>${options.body}</main>
</div>
<footer>© ${copyrightYears(new Date().getUTCFullYear())} poli0981 (SkullMute) · Source code under the Apache License 2.0 · <a href="https://github.com/poli0981/youtube-generator">GitHub</a> · <a href="mailto:contact@poli0981.dev">contact@poli0981.dev</a></footer>
</body>
</html>
`;
}
const TITLE_BY_ID: Record<LegalDocId, string> = {
terms: "Terms of Use",
privacy: "Privacy Policy",
disclaimer: "Disclaimer",
license: "License (Apache-2.0)",
"third-party": "Third-Party Notices",
security: "Security Policy",
notice: "NOTICE",
conduct: "Code of Conduct",
};
function docPage(id: LegalDocId, doc: RenderedLegalDoc, lang: DocLang): string {
const html = doc.html[lang] ?? doc.html.en ?? "";
// The documents state their own effective date, so the meta line only
// carries the language switch.
const meta: string[] = [];
if (doc.html.vi) {
meta.push(
lang === "en"
? `<a href="${legalDocPath(id)}?lang=vi" hreflang="vi" lang="vi">Tiếng Việt</a>`
: `<a href="${legalDocPath(id)}" hreflang="en" lang="en">English</a>`,
);
}
const metaLine = meta.length ? `<p class="meta">${meta.join(" · ")}</p>` : "";
// Plain-text sources carry no <h1>; give them one.
const heading = /^\s*<h1[\s>]/.test(html) ? "" : `<h1>${escapeHtml(TITLE_BY_ID[id])}</h1>`;
return pageShell({
title: TITLE_BY_ID[id],
canonicalPath: legalDocPath(id),
description: DOC_SUMMARIES[id],
activeId: id,
lang,
body: `<article>${heading}${metaLine}${html}</article>`,
});
}
function indexPage(): string {
const cards = LEGAL_DOCS.map(
(doc) =>
`<a href="${legalDocPath(doc.id)}"><strong>${escapeHtml(TITLE_BY_ID[doc.id])}</strong><span>${escapeHtml(DOC_SUMMARIES[doc.id])}</span></a>`,
).join("");
return pageShell({
title: "Legal",
canonicalPath: "/legal",
description: "Terms, privacy, licensing and security information for YTDescGen.",
activeId: null,
lang: "en",
body: `<article><h1>Legal</h1><p>Terms, privacy, licensing and security information for YTDescGen — the same documents the app shows in its Legal Center.</p><div class="cards">${cards}</div></article>`,
});
}
export function legalDocsPlugin(options: { emitStaticPages: boolean }): Plugin {
return {
name: "ytdescgen:legal-docs",
resolveId(id) {
return id === VIRTUAL_ID ? RESOLVED_VIRTUAL_ID : null;
},
load(id) {
if (id !== RESOLVED_VIRTUAL_ID) return null;
for (const doc of LEGAL_DOCS) {
this.addWatchFile(resolve(ROOT, doc.source));
if (doc.sourceVi) this.addWatchFile(resolve(ROOT, doc.sourceVi));
}
return `export const LEGAL_CONTENT = ${JSON.stringify(renderAllLegalDocs())};\n`;
},
generateBundle() {
if (!options.emitStaticPages) return;
const docs = renderAllLegalDocs();
this.emitFile({ type: "asset", fileName: "legal/index.html", source: indexPage() });
for (const doc of LEGAL_DOCS) {
const rendered = docs[doc.id];
this.emitFile({
type: "asset",
fileName: `legal/${doc.id}.html`,
source: docPage(doc.id, rendered, "en"),
});
if (rendered.html.vi) {
this.emitFile({
type: "asset",
fileName: `legal/${doc.id}.vi.html`,
source: docPage(doc.id, rendered, "vi"),
});
}
}
},
};
}
+67
View File
@@ -0,0 +1,67 @@
import type { Plugin } from "vite";
import { SITE_ORIGIN } from "../src/config/brand.ts";
import { legalDocPath } from "../src/config/legal.ts";
/**
* Build steps that only make sense for the web deployment on
* ytgenerator.stream — never for the Tauri desktop / Android bundles, which
* stay free of network beacons (their CSP would block them anyway).
*/
/**
* The Cloudflare Web Analytics snippet, byte-for-byte as issued for this
* site. Cookieless; allowed by the app shell's CSP (worker/headers.ts).
*/
export const CF_WEB_ANALYTICS_SNIPPET = `<!-- Cloudflare Web Analytics -->
<script type='module' src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "84187c3714aa49e1ad8ef93ad6d422e7"}'>
</script>
<!-- End Cloudflare Web Analytics -->`;
export function cloudflareWebAnalytics(): Plugin {
return {
name: "ytdescgen:cf-web-analytics",
apply: "build",
transformIndexHtml: {
order: "post",
handler(html) {
return html.replace("</body>", `${CF_WEB_ANALYTICS_SNIPPET}\n </body>`);
},
},
};
}
/** Days until the generated security.txt expires (RFC 9116 wants < 1 year). */
export const SECURITY_TXT_LIFETIME_DAYS = 180;
/**
* RFC 9116 security.txt, regenerated on every build so `Expires` always sits
* ~6 months ahead of the last deploy instead of silently lapsing.
*/
export function renderSecurityTxt(now: Date): string {
const expires = new Date(now.getTime() + SECURITY_TXT_LIFETIME_DAYS * 86_400_000);
return [
"# Security contact for YTDescGen — https://ytgenerator.stream",
"# Scope, response times and disclosure policy are in the Policy link below.",
"Contact: mailto:security@poli0981.dev",
"Contact: https://github.com/poli0981/youtube-generator/security/advisories/new",
`Expires: ${expires.toISOString().replace(/\.\d{3}Z$/, "Z")}`,
"Preferred-Languages: en, vi",
`Canonical: ${SITE_ORIGIN}/.well-known/security.txt`,
`Policy: ${SITE_ORIGIN}${legalDocPath("security")}`,
"",
].join("\n");
}
export function securityTxt(): Plugin {
return {
name: "ytdescgen:security-txt",
apply: "build",
generateBundle() {
this.emitFile({
type: "asset",
fileName: ".well-known/security.txt",
source: renderSecurityTxt(new Date()),
});
},
};
}
+353 -234
View File
@@ -2,132 +2,157 @@
## YTDescGen — Technical Architecture
Reflects **v1.2.0**. Implementation details (configs, interfaces, file formats, CI) are in [TECH-SPEC.md](TECH-SPEC.md); desktop and Android builds in [PACKAGING.md](PACKAGING.md); running the web deployment in [HOSTING.md](HOSTING.md).
---
## 1. High-Level Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Editor │ │ Output │ │ Profiles │ │ Batch / History│ │
│ │ Page │ │ Page │ │ Page │ │ Pages │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬────────┘ │
│ │ │ │ │ │
│ ┌────┴─────────────┴────────────┴───────────────┴────────┐ │
│ │ Shared Components (ui/, editor/, output/) │ │
│ └────────────────────────────┬────────────────────────────┘ │
├───────────────────────────────┼──────────────────────────────┤
│ Application Layer │
│ ┌────────────┐ ┌───────────┴──────────┐ ┌──────────────┐ │
│ │ Hooks │ │ State (Zustand) │ │ i18next │ │
│ │ useGenerate │ │ editor / profile / │ │ locales/ │ │
│ │ useClipboard│ │ preset / history / │ │ en/vi/ja/ │ │
│ │ useCharCount│ │ settings │ │ es/ko/zh │ │
│ └──────┬─────┘ └───────────┬───────────┘ └──────┬───────┘ │
├─────────┼────────────────────┼──────────────────────┼────────┤
│ Core Engine Layer │
│ ┌──────┴────────────────────┴──────────────────────┴──────┐ │
│ │ engine/ (Pure TypeScript) │ │
│ │ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ │ │
│ │ │ title-builder│ │description-builder│ │ tag-generator│ │ │
│ │ └──────┬───────┘ └────────┬─────────┘ └──────┬───────┘ │ │
│ │ └──────────────────┼───────────────────┘ │ │
│ │ ┌────────┴────────┐ │ │
│ │ │template-renderer│ │ │
│ │ └─────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ ┌────────────────┐ ┌───────────────┐ ┌─────────────────┐ │
│ │ localStorage │ │ File System │ │ Clipboard API │ │
│ │ (Web) │ │ (Tauri) │ │ │ │
│ └────────────────┘ └───────────────┘ └─────────────────┘ │
└──────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ Pages: Editor · Output · Profiles · History · Settings · Batch │
│ Social · Playlist · Logs · About · Legal (+ error pages) │
│ Shell: Sidebar · Header · MobileNav · CommandPalette (cmdk) │
│ Components: ui/ (Radix, Motion, sonner) · editor/ · output/ │
│ backup/ · profiles/ · presets/ · templates/ · … │
├────────────────────────────────────────────────────────────────────┤
│ Application Layer │
│ Hooks: useGeneratedOutput · useRenderOptions · useOutputCopy │
│ useOutputLimits · useStrictBlock · useSaveToHistory · … │
│ Stores (Zustand): editor · profiles · presets · templates │
│ history · settings · logs · pending-invalid │
│ i18next: 8 locales — en bundled, the other seven lazy-loaded │
│ utils/: backup/ · library-apply · store-paste · file-ops │
│ native · log-storage · validation · … │
├────────────────────────────────────────────────────────────────────┤
│ Core Engine Layer — src/engine/ (pure TypeScript) │
│ renderAll() in template-renderer │
│ ├─ title-builder │
│ ├─ description-builder ── rig-block · timeline-parser │
│ │ channel-phrase · endings-format │
│ └─ tag-generator │
│ Also: title-variants · limits · social-post-builder │
│ pinned-comment-builder · playlist-builder · graphics-vendor │
├────────────────────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ localStorage (every platform) · Clipboard API │
│ Web: File System Access API or a download │
│ Tauri: name-only Rust commands (backups, logs) · Save/Open │
│ dialogs run from Rust · opener plugin (external links) │
└────────────────────────────────────────────────────────────────────┘
```
**Error pages (v0.27):** `components/errors/` holds a reusable `ErrorPage`
(404/403/419/500/offline/runtime) driven by the pure `config/error-pages.ts`
map. The dedicated error routes (`/403`, `/419`, `/500`, `/offline`, catch-all
`*`) are declared as **siblings of the `AppShell` route group** in `App.tsx`, so
they render full-screen with no Sidebar/Header. `ErrorPage` is router-agnostic
(hash anchors + `history.back()`) so the root `ErrorBoundary` — mounted outside
`HashRouter` in `main.tsx` — can reuse it as its crash fallback.
The same source ships two ways:
```
One React source (src/), two Vite builds
┌──────────────────┴───────────────────┐
▼ ▼
┌──────────────────────────────────┐ ┌──────────────────────────────────┐
│ Web — ytgenerator.stream │ │ Tauri 2 — desktop and Android │
│ BrowserRouter (real paths) │ │ HashRouter (asset protocol) │
│ Build adds: static /legal pages, │ │ Build (TAURI_ENV_PLATFORM set): │
│ security.txt, analytics beacon │ │ es2020 target, no analytics │
│ Cloudflare Worker (worker/): │ │ Rust core (src-tauri/): │
│ Turnstile gate · headers · │ │ name-only file commands, │
│ /legal/* · static assets │ │ native dialogs, tray (desktop) │
│ Data: the browser's localStorage │ │ Data: WebView localStorage + │
│ │ │ app data dir (backups, logs) │
└──────────────────────────────────┘ └──────────────────────────────────┘
```
**Routing.** `App.tsx` picks the router at runtime: `BrowserRouter` on the web — the Worker serves the app shell for every route, and Web Analytics counts page views by path — and `HashRouter` inside Tauri, whose asset protocol has no server-side fallback. Before the router reads the URL, `main.tsx` rewrites an old web bookmark (`/#/output` → `/output`); Tauri keeps hash URLs.
**Route tree.** `/legal` and `/legal/:docId` (the Legal Center) sit outside the consent guard, so the consent screen can open each document. Everything else is inside `ConsentGuard`, a layout route that renders `ConsentGate` until the user has accepted the current terms version (`CURRENT_TERMS_VERSION` = 2 since v1.0.0). Inside it, `AppShell` holds the pages: the Editor (index route) stays in the entry bundle; Output, Profiles, History, Settings, Batch, Social, Playlist, Logs and About are `React.lazy` chunks, each wrapped in its own `ErrorBoundary` + `Suspense` so a crash on one page cannot blank the app. On the web, `/legal/<id>` loaded directly is the Worker's static page; navigated to inside the app, it is the Legal Center — the same URL either way.
**App shell.** `AppShell` combines a collapsible `Sidebar`, the `Header` top bar (output and interface languages, theme), `MobileNav` (a bottom bar on phones, with a "More" drawer), and three lazily loaded pieces: the ⌘/Ctrl + K `CommandPalette` (cmdk), the shortcut help and the backup `RestoreDialog`, mounted only while a restore is pending. UI primitives in `components/ui/` wrap Radix (Dialog, AlertDialog, Popover, Tooltip, Tabs, Switch, Checkbox, ToggleGroup); animation is Motion behind `LazyMotion` (its feature bundle loads after first paint, and `MotionConfig reducedMotion="user"` honours the OS setting); toasts are sonner.
**Error pages (v0.27).** `components/errors/` holds a reusable `ErrorPage` (404/403/419/500/offline/runtime) driven by the pure `config/error-pages.ts` map. The error routes (`/403`, `/419`, `/500`, `/offline`, catch-all `*`) are **siblings of the `AppShell` route group** inside the consent guard, so they render full-screen without the shell. `ErrorPage` is router-agnostic — Home is a plain location change (`/` on the web, `#/` in Tauri) and Back is `history.back()` — so the root `ErrorBoundary`, mounted in `main.tsx` outside the router, reuses it as its crash fallback.
**Start-up.** Before first paint:
1. `public/theme-init.js` (a plain script in `index.html`) applies the saved theme and the Hide scrollbars class (`hide-scrollbars`, v1.1.0) and sets `<html lang>` to the saved UI language, so a light-theme user sees no dark flash.
2. `main.tsx` rewrites old hash URLs (web), carries over a terms acceptance from the gate page's `ytg_terms` cookie (web), and registers a one-time reload for chunk files that a new deploy removed (`vite:preloadError`).
3. It loads the saved UI and output languages (capped at 2 s), applies the theme and scrollbar classes, installs the external-link handler (Tauri: links open in the system browser through the opener plugin), then renders.
After mount, `App.tsx` starts a first-run draft in the Default Output Language, runs the Tauri data chores (`startAppData()`: legacy-file recovery, then automatic backups on desktop) before loading the persisted logs, prefetches the Output page when the browser is idle, keeps i18next in step with the `appLanguage` setting, and keeps the `hide-scrollbars` class in step with `hideScrollbars` (the Settings toggle, a restored backup and its undo).
## 2. Core Engine Design
Engine module chứa toàn bộ logic generate — **zero framework dependency**. Mọi function đều pure: input → string.
The engine holds all generation logic with **zero framework dependency**: no React, no DOM, no storage, no clipboard. Every function is pure — typed input in, string (or list) out. Values from the environment come from the caller: the translator `t`, and the year for the copyright line and trending tags (the builders fall back to the current year when it is omitted).
| Module | Role |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template-renderer.ts` | `renderAll(input, t, options)` → `GeneratorOutput`: title + description + tags, character counts, over-limit warnings |
| `title-builder.ts` | Titles: video-type segment, quality badge (position, case), separator, order (game first / video first) |
| `title-variants.ts` | Three alternative title shapes, each built by `buildTitle` with a different order / badge position |
| `description-builder.ts` | The description, block by block (intro, timestamps, store links, video settings, rig, warnings, notes, donate, social, community, contact, copyright, …) |
| `tag-generator.ts` | Tag pools, de-duplication, YouTube's own tag-length count (`youtubeTagsLength`) and trimming |
| `timeline-parser.ts` | Timestamps → translated chapter lines; YouTube's chapter rules (`checkChapters`); "Tidy up" (`normalizeTimeline`) |
| `channel-phrase.ts` | Drops "on {{channelName}}" (per language) when the channel name is empty |
| `rig-block.ts` | The rig as localised `Label: value` lines in a fixed order (description and social captions) |
| `endings-format.ts`, `graphics-vendor.ts` | Endings lists split across videos; valid upscaler / frame-generation options per vendor |
| `limits.ts` | Over-limit status per field, Copy All rules, `<` / `>` detection |
| `social-post-builder.ts` | Captions for TikTok, YouTube Shorts, Instagram Reels, Facebook Reels, X (weighted count), Threads, Bluesky |
| `pinned-comment-builder.ts`, `playlist-builder.ts` | Pinned comment; playlist title, description and comment |
| `types.ts` | `GeneratorInput`, `GeneratorOutput`, `YT_LIMITS`, the option unions |
### 2.1 Type Definitions (`engine/types.ts`)
```typescript
// ── Video Types ──
// ── Video types (20) ──
// prettier-ignore
type VideoType =
| "full" // Full Gameplay
| "part" // Gameplay Part X
| "boss" // Boss Fight
| "boss_nohit" // Boss No Hit
| "ending" // Ending / All Endings
| "speedrun" // Speedrun
| "100percent" // 100% Completion
| "dlc" // DLC Content
| "newgame_plus" // New Game+
| "challenge" // Challenge Run
| "side_quest" // Side Quest / Optional Content
| "secret" // Secret / Hidden Content
| "comparison" // Graphics / Version Comparison
| "guide"; // Silent Guide / Walkthrough
| "full" | "part" | "full_demo" | "demo_part"
| "boss" | "boss_nohit" | "ending" | "speedrun" | "100percent"
| "dlc" | "newgame_plus" | "challenge" | "side_quest" | "secret"
| "comparison" | "guide" | "mods" | "collectibles" | "livestream" | "gacha_quest";
// ── Genre ──
// ── Genres (42, up to 3 per video — MAX_GENRES) ──
// prettier-ignore
type Genre =
| "action" | "horror" | "rpg" | "fps" | "openworld"
| "indie" | "soulslike" | "racing" | "story" | "simulation"
| "fighting" | "stealth" | "survival_craft" | "mmo"
| "rhythm" | "puzzle" | "roguelike" | "metroidvania"
| "tower_defense" | "card_game" | "battle_royale"
| "crpg" | "tactical" | "space" | "farming";
| "action" | "hack_slash" | "beatemup" | "platformer"
| "horror" | "survival_horror" | "psychological_horror"
| "rpg" | "jrpg" | "action_rpg" | "crpg"
| "fps" | "arena_shooter" | "tactical_fps" | "boomer_shooter" | "extraction_shooter" | "shmup"
| "openworld" | "indie" | "soulslike" | "racing" | "story" | "simulation" | "city_builder"
| "fighting" | "stealth" | "survival_craft" | "roguelike" | "metroidvania" | "mmo"
| "rhythm" | "puzzle" | "tower_defense" | "card_game" | "deck_builder" | "auto_battler"
| "battle_royale" | "tactical" | "space" | "farming" | "fmv" | "visual_novel";
// ── Supported Languages ──
type SupportedLanguage = "en" | "vi" | "ja" | "es" | "ko" | "zh"
| "fr" | "de" | "pt" | "ru" | "th" | "ar";
// ── Supported languages (8) ──
type SupportedLanguage = "en" | "vi" | "ja" | "es" | "ko" | "zh" | "pt-BR" | "id";
// ── Input State ──
// ── Input (abridged — about 75 fields) ──
interface GeneratorInput {
// Core
videoType: VideoType;
language: SupportedLanguage;
genre: Genre;
genres: Genre[];
// Game info
// Game and channel
gameName: string;
gameNameLocalized?: Record<SupportedLanguage, string>; // optional localized game name
channelName: string;
gameNameLocalized?: Partial<Record<SupportedLanguage, string>>;
channelName: string; // may be empty
platform: string;
// Video type-specific
partNumber?: string;
bossName?: string;
dlcName?: string;
challengeName?: string;
// Video-type specific: partNumber, bossName, dlcName, challengeName, modName, modList,
// liveUrl, scheduledTime, gacha quest fields …
// Video settings: resolution, fps, graphicsPreset, ray tracing, frame generation,
// upscaling, artStyle, videoStyleEra, versionInfo …
// Content: timestamps, playlistLink, emails, music, sponsor, publisher, content warnings,
// tech notes, playthrough notes, endings, playtest, community links …
// Video settings
resolution?: string;
fps?: string;
graphicsPreset?: string;
// Content
timestamps?: string;
playlistLink?: string;
contactEmail?: string;
// Warnings
// Deprecated since v0.11 (folded into contentWarnings), kept for old drafts
spoilerWarning: boolean;
matureWarning: boolean;
// Links
storeLinks: Record<string, string>;
social: Record<string, string>;
rig: Record<string, string>;
// Links and hardware
storeLinks: Partial<Record<string, string>>;
storeLinkTypes?: Partial<Record<string, StoreLinkType>>; // "paid" | "free" | "demo"
social: Partial<Record<string, string>>;
rig: Partial<Record<string, string>>; // GPU as "gpu:<catalog id>" since v1.0.0
}
// ── Output ──
@@ -139,33 +164,29 @@ interface GeneratorOutput {
charCounts: {
title: number;
description: number;
tags: number;
tags: number; // YouTube's count: quotes around multi-word tags + commas
};
warnings: string[]; // e.g. "Tags exceed 500 character limit"
warnings: CharLimitWarning[]; // one per field strictly over its limit
}
```
### 2.2 Template Architecture
Templates sử dụng **data-driven approach** thay vì hardcode string concatenation:
Templates are **data-driven**: every sentence the engine writes comes from the output language's `templates.json`, not from string concatenation in code. The engine interpolates `{{placeholders}}` through `t`. An excerpt of `src/i18n/locales/en/templates.json`:
```typescript
// i18n/locales/en/templates.json
```json
{
"title": {
"separator": " — ",
"separators": { "emDash": " — ", "hyphen": " - ", "colon": ": ", "pipe": " | " },
"suffix": "Gameplay No Commentary",
"videoType": {
"full": "",
"part": "Part {{partNumber}}",
"full_demo": "Demo",
"demo_part": "Demo Part {{partNumber}}",
"boss": "{{bossName}} Boss Fight",
"boss_nohit": "{{bossName}} Boss No Hit",
"ending": "Ending",
"speedrun": "Speedrun",
"100percent": "100% Completion",
"dlc": "{{dlcName}} DLC",
"newgame_plus": "New Game+",
"challenge": "{{challengeName}} Challenge"
"boss_nohit": "{{bossName}} Boss No Hit"
}
},
"description": {
@@ -176,182 +197,280 @@ Templates sử dụng **data-driven approach** thay vì hardcode string concaten
"noCommentaryLine": "No Commentary — pure gameplay for your enjoyment.",
"sections": {
"timestamps": "⏱ TIMESTAMPS",
"storeLinks": "🎮 GET THE GAME",
"videoSettings": "🖥 VIDEO SETTINGS: {{settings}}",
"storeLinksBuy": "🎮 GET THE GAME (if you want to buy)",
"storeLinksDownload": "⬇️ DOWNLOAD THE GAME (if you want to play)",
"videoSettings": "🖥 VIDEO SETTINGS",
"rig": "💻 MY RIG",
"spoilerWarning": "⚠️ SPOILER WARNING: This video contains spoilers.",
"matureWarning": "🔞 MATURE CONTENT (18+): Contains violence / strong language.",
"playlist": "▶️ Watch the full series: {{link}}",
"contact": "📧 Business inquiries: {{email}}",
"cta": "👍 Like | 🔔 Subscribe | ↗️ Share"
}
},
"rigLabels": { "cpu": "CPU", "gpu": "GPU", "ram": "RAM" }
}
}
```
The file's top-level sections are `title`, `description`, `pinnedComment`, `hashtags`, `playlist` and `timeline` (the translated chapter keywords). When the channel name is empty, the builders render `{{channelName}}` as a placeholder slot and `channel-phrase.ts` removes the words around it, per language.
### 2.3 Tag Generator Architecture
```
TagGenerator Pipeline:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Core Pool│───→│Genre Pool│───→│ Platform │───→│ Quality │
│ (always) │ │(by genre)│ │ Pool │ │ Pool │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │
└───────────────┴──────────────┴───────────────┘
│
┌─────────┴─────────┐
│ VideoType Pool │
│ (boss, speedrun…) │
└─────────┬─────────┘
│
┌─────────┴─────────┐
│ Multilingual Pool │
│ (JA, VI, ES…) │
└─────────┬─────────┘
│
┌─────────┴─────────┐
│ Trending Pool │
│ (year-based) │
└─────────┬─────────┘
│
┌─────────┴─────────┐
│ Dedup (Set) │
│ + Priority Sort │
│ + 500 char trim │
└───────────────────┘
generateTags(input, { includeMultilingualTags, includeTrendingTags, year })
priority pool source
1 game name bare tag (≤ 30 chars) + a shorter form for composites
2 core CORE_TAGS_BY_LANG[language]
3 genre GENRE_TAG_REGISTRY[genre], for every selected genre
4 video type VIDEO_TYPE_TAGS[videoType]
5 platform PLATFORMS[].tagName ("Steam", "itch.io", …)
6 quality resolution / fps
7 multilingual MULTILINGUAL_TAGS[language] (setting)
8 trending year-based, first genre only (setting)
9 publisher/developer pubDevName, as a bare tag
│
▼
de-duplicate (case-insensitive) · drop tags over 30 characters
│
▼
trimToCharLimit(tags, 500): keep tags in priority order while they fit,
measured the way YouTube measures them (youtubeTagsLength); a tag that
doesn't fit is skipped and the shorter ones after it are still tried
```
Tag pools là registry pattern — thêm genre mới chỉ cần thêm 1 entry:
The pools are registries — a new genre is one entry in `GENRE_TAG_REGISTRY` plus its search term in `GENRE_SEARCH_TERMS` (used by the trending tags), and `tests/engine/tag-generator.test.ts` fails if either disagrees with `config/genres.ts`:
```typescript
// engine/tag-generator.ts
const TAG_REGISTRY: Record<Genre, (gameName: string) => string[]> = {
action: (g) => [`${g} action`, "action game no commentary", "action adventure gameplay"],
horror: (g) => [`${g} horror`, "horror game no commentary", "survival horror gameplay"],
// ... thêm genre ở đây
export const GENRE_TAG_REGISTRY: Record<string, (gameName: string) => string[]> = {
action: (g) => [
`${g} action`,
"action game no commentary",
"action adventure gameplay",
`${g} combat`,
],
// … one entry per genre in config/genres.ts
};
```
## 3. State Architecture
```
Zustand Stores:
┌───────────────────────────────────────────────┐
│ EditorStore │
│ - videoType, language, genre │
│ - gameName, channelName, platform │
│ - timestamps, storeLinks, rig, social │
│ - spoilerWarning, matureWarning │
│ Middleware: none (ephemeral per session) │
│ + persist: auto-save draft (debounced) │
├───────────────────────────────────────────────┤
│ ProfileStore │
│ - profiles: Profile[] │
│ - activeProfileId: string | null │
│ Middleware: persist (localStorage) │
├───────────────────────────────────────────────┤
│ PresetStore │
│ - gamePresets: GamePreset[] │
│ Middleware: persist (localStorage) │
├───────────────────────────────────────────────┤
│ HistoryStore │
│ - entries: HistoryEntry[] (max 100) │
│ Middleware: persist (localStorage, pruned) │
├───────────────────────────────────────────────┤
│ SettingsStore │
│ - theme: "dark" | "light" │
│ - defaultLanguage: SupportedLanguage │
│ - defaultGenres: GenreId[] │
│ - (flags: quality badge / copyright / ...) │
│ Middleware: persist (localStorage + file) │
└───────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────┐
│ EditorStore — "ytdescgen-editor-draft", v20 │
│ - the draft: every form field (EditorData) + setter actions │
│ - persists data only (editorDataOf); migrateEditorState │
├────────────────────────────────────────────────────────────────────┤
│ ProfileStore — "ytdescgen-profiles", v3 │
│ - profiles: Profile[] — channel fields (PROFILE_FIELDS) │
├────────────────────────────────────────────────────────────────────┤
│ PresetStore — "ytdescgen-presets", v2 │
│ - presets: GamePreset[] — per-game fields (PRESET_FIELDS) │
├────────────────────────────────────────────────────────────────────┤
│ TemplateStore — "ytdescgen-templates", v2 │
│ - templates: EditorTemplate[] — whole-form snapshots │
├────────────────────────────────────────────────────────────────────┤
│ HistoryStore — "ytdescgen-history", v3 │
│ - entries: HistoryEntry[] — one per video, newest first │
│ - capped by the History Limit setting (10–500, default 100) │
├────────────────────────────────────────────────────────────────────┤
│ SettingsStore — "ytdescgen-settings", v12 │
│ - theme · hideScrollbars · appLanguage · titleFormat │
│ - description toggles · strictMode · copyAllIncludesTags · … │
│ - healSettings on every load; consent and UI state never exported │
├────────────────────────────────────────────────────────────────────┤
│ LogStore — not persisted by Zustand │
│ - ≤ 2000 entries in memory; log-storage.ts mirrors each entry │
│ - (web: localStorage "ytdescgen-logs"; Tauri: daily JSONL files) │
├────────────────────────────────────────────────────────────────────┤
│ PendingInvalidStore — not persisted (v0.35) │
│ - typed text that is invalid and therefore not saved │
├────────────────────────────────────────────────────────────────────┤
│ useRestoreDialog (utils/backup) — not persisted │
│ - the file waiting in the restore dialog │
└────────────────────────────────────────────────────────────────────┘
```
Every persisted store uses Zustand `persist` with `createJSONStorage(() => localStorage)` — **the only store on every platform**. The Tauri "mirror" file of earlier versions is gone (see [PACKAGING.md](PACKAGING.md) for how its leftovers are recovered). Each store exports its version and its migration function (`EDITOR_STORE_VERSION` / `migrateEditorState`, `PROFILE_STORE_VERSION` / `migrateProfilesState`, `PRESET_STORE_VERSION` / `migratePresetsState`, `TEMPLATE_STORE_VERSION` / `migrateTemplatesState`, `HISTORY_STORE_VERSION` / `migrateHistoryState`, `SETTINGS_STORE_VERSION` / `healSettings`). The migrations are idempotent and shared with backup import, which replays them from the version a file records (section 5).
### Profiles, presets and templates
`src/config/library-fields.ts` is the one list of which editor fields each kind of library item carries — the save forms, Apply, backups and imports all read it:
- **Profile** = the channel: `PROFILE_FIELDS` (channel name, emails, social, rig, resolution / fps / graphics preset, ad text, Vietnamese donate fields, community links).
- **Preset** = the game: `PRESET_FIELDS` (names, genres, platform, store links and their types, publisher, content warnings, language patch, game version, art style, the skip-graphics-settings switch, playlist link).
- **Template** = the whole form (every field since v1.0.0).
- `PER_VIDEO_FIELDS` is what belongs to one video only (boss, chapter, timestamps, pinned comment, endings, …).
`src/utils/library-apply.ts` does everything that fills or clears the editor in one go, each with Undo (the editor is snapshotted first): apply a profile / preset / template, **Next part** (part number + 1, per-video fields cleared), **New video, same game**, and **Start over** (keeps the profile fields and starts in the Default Output Language). Applying a preset for another game also clears the per-video fields. `QuickStart` (top of the editor) remembers the last profile and preset (`lastProfileId`, `lastPresetId`) and asks before overwriting filled-in fields. `src/utils/store-paste.ts` routes a store link pasted anywhere in the editor to the right store field (matching `PLATFORMS[].urlPattern`), sets the platform for the first link, and fills an empty game name from the URL (`url-extractors.ts`).
### Settings → engine options
`renderAll` is called from three places (the Output hook, the multi-language Output hook, BatchPage). Each used to hand-copy the same twelve settings fields into an options object, and they had drifted — BatchPage's copy silently omitted `splitContactEmail` and `showThirdPartyAds`, so Batch rendered a different description than Output from identical data.
`src/hooks/use-render-options.ts` is now the single mapping, with two guards:
- **Compile-time** — `buildRenderOptions` builds a `Required<SettingsRenderOptions>`, so omitting a key is a type error.
- **Runtime** — `tests/hooks/render-options-parity.test.ts` diffs the produced keys against `SETTINGS_DERIVED_RENDER_KEYS` in both directions.
`RenderOptions` is split accordingly: `SettingsRenderOptions` (from the user) plus `RenderOptionOverrides` (`tEn`, `bilingualContentBlocks`, `year` — decided per call site, since Output wants bilingual content blocks and Batch does not).
### Validation state
Two sources, unioned by `useStrictBlock`, because neither alone is sufficient:
| Source | Catches | Why it's needed |
| ----------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `collectEditorIssues` (pure, over `EditorData`) | Saved values that fail validation | Bad data from imports — `ValidatedInput` refuses to commit invalid text, so imports are the main way it gets in |
| `PendingInvalidStore` | Typed text that is invalid and therefore **not** saved | Otherwise a field showing a red error is invisible to every gate, because the store behind it holds the last good value |
Both are filtered through `isRelevantIssueId`, so a field that isn't currently shown (`adEmail` / `gameKeyEmail` / `copyrightEmail` with split-email off, `zaloGroupLink` outside Vietnamese output) can never block on a value with no visible input to fix it. Strict Mode is opt-in; with it off, no gate blocks.
The three purpose emails (v1.1.0) go through one validator in both places: `validatePurposeEmails` (`src/utils/validation.ts`) is `validateEmails` plus a rule that the part before `@` of every address contains one of the field's words from `PURPOSE_EMAIL_KEYWORDS` (`src/config/contact-emails.ts`). `ContactEmailEditor` uses it to refuse the value and lists the words in each field's help text; `collectEditorIssues` uses it on saved values, so an older address without a word shows up for Strict Mode rather than being rewritten.
The first implementation registered issues from the inputs themselves and cleared on unmount. It typechecked and had passing tests, and did nothing: the fields live on the Editor page while the gates live on Batch / Social / Output, so navigating away cleared every issue. Deriving from state removes the mount coupling entirely.
## 4. i18n Architecture
```
i18n/locales/
├── en/
│ ├── ui.json # UI strings: buttons, labels, tooltips, errors
│ └── templates.json # Generated content: title patterns, description sections
├── vi/
│ ├── ui.json
│ └── templates.json
├── ja/
│ ├── ui.json
│ └── templates.json
└── _schema.json # JSON Schema — validates all locale files have same keys
i18n/
├── index.ts # i18next setup + SUPPORTED_LANGUAGES
└── locales/
├── en/
│ ├── ui.json # UI strings: buttons, labels, tooltips, errors
│ └── templates.json # Generated content: titles, description blocks, pinned comment, playlist, chapter keywords
├── vi/ ja/ es/ ko/ zh/ pt-BR/ id/
│ ├── ui.json
│ └── templates.json
└── _schema.json # the expected key list for both namespaces
```
**Adding a new language** = 2 JSON files + 1 line registration. See docs/I18N.md.
`npm run validate:locales` checks every locale against `_schema.json`, and `tests/i18n/locale-registration.test.ts` checks the language list against the locale folders in both directions. **Adding a language** is two JSON files plus registration: the `SupportedLanguage` union, `SUPPORTED_LANGUAGES`, `detectBrowserLanguage` in `settings-heal.ts`, and the per-language records TypeScript enforces (the tag pools in `tag-generator.ts`, the channel-phrase patterns in `channel-phrase.ts`). The Turnstile gate page keeps its own strings and language list in `worker/gate-i18n.ts`. See [I18N.md](I18N.md).
**Lazy loading (v0.26+)**: only English is bundled into the main chunk — it is the `fallbackLng` and the engine's bilingual `tEn` translator, both of which must resolve synchronously. Every other language is fetched on first use as a Vite async chunk via `i18next-resources-to-backend` + dynamic `import()`. Generation paths gate on bundle readiness (`useLanguagesReady` hook / `ensureLanguagesLoaded`): an unloaded language would otherwise silently render English fallback output. A chunk that fails to fetch degrades to English and logs to the in-app Log page — it never hangs the UI.
**UI language vs Output language**: These are independent. User can browse the app in English but generate descriptions in Japanese. UI language follows `SettingsStore.defaultLanguage`, output language follows `EditorStore.language`.
**UI language vs output language**: independent. The UI follows `SettingsStore.appLanguage` (loaded before the first render in `main.tsx`, then kept in step with i18next by `App.tsx`); the generated text follows `EditorStore.language`. A new draft — first run or Start over — starts in `SettingsStore.defaultOutputLanguage`. Both settings default to the browser's language when it is supported.
## 5. Desktop Packaging (Tauri)
## 5. Backup & Restore
Code in `src/utils/backup/`, UI in `src/components/backup/` (`BackupSection` in Settings › Backup & restore, `ExportBackupDialog`, `RestoreDialog`). Format and rules: [TECH-SPEC.md § 4](TECH-SPEC.md#4-backup-file-format-v100).
| Module | Role |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `format.ts` | The `_format: 2` envelope, `_type` values, section list, per-section store versions, dated file names |
| `collect.ts` | Builds a backup of the chosen sections, a single-section export, or the History CSV |
| `detect.ts` | Recognises every file any version has written (v2, v0.15–v0.38 envelopes, bare arrays, the old desktop data file) and reports each section with its version |
| `sanitize.ts` | Store migrations first, then a strict whitelist; keeps device-local settings |
| `restore.ts` | Plans the restore (new / same / changed per row) and applies the choice in one step, with undo |
| `restore-flow.ts` | Gets a file into the dialog: Open dialog, drop, or one of the desktop app's own backups |
| `restore-request.ts` | `useRestoreDialog` — the pending file, kept apart so the shell can watch it without loading the rest |
| `auto-backup.ts` | Desktop automatic backups |
| `startup.ts` | Tauri start-up: legacy-file recovery, then automatic backups (desktop) |
```
Web App (React + Vite)
Restore from file · drop · desktop backup list · "Review" on the legacy toast
│ restore-flow.ts (openTextFile / readTextFile / appBackups.read)
▼
detect.ts — readBackupText → sections + recorded versions
│ (logs, social, unknown or newer files are refused with a message)
▼
useRestoreDialog.open → RestoreDialog (lazy)
│
▼
┌───────────────────┐
│ Tauri Shell │
│ ┌──────────────┐ │
│ │ WebView │ │ ← Renders the same React app
│ │ (system) │ │
│ └──────────────┘ │
│ ┌──────────────┐ │
│ │ Rust Core │ │ ← File system access, clipboard, tray
│ └──────────────┘ │
└───────────────────┘
│
restore.ts — planRestore
│ sanitize.ts: store migrations → whitelist
│ per row: new / same / changed; Merge (newer | both) or Replace
▼
Binary output:
- Windows: .msi / .exe (~8MB)
- macOS: .dmg / .app (~10MB)
applyRestore — one synchronous write to every store → toast with Undo
(desktop: a "before-restore" automatic backup is written first)
```
Export: `ExportBackupDialog` → `collectBackup(chosen sections)` → `saveTextFile` (`ytdescgen-backup-YYYY-MM-DD.json`); the library tabs and History export single sections (History also as CSV).
## 6. Web Delivery
The web build is served at <https://ytgenerator.stream> by a Cloudflare Worker (`worker/`, configured by `wrangler.jsonc`) that Cloudflare Workers Builds deploys from `main`. The Worker puts a Turnstile check in front of the app (verified server-side; a signed `HttpOnly` `__Host-ytg_gate` cookie remembers the pass for 24 hours), serves the prerendered legal pages at `/legal/*` to everyone, and sets the security headers (a CSP per page type). Agreeing to the terms on the gate page sets the `ytg_terms` cookie, which the app reads so a web visitor meets one blocking screen, not two. Build-time extras for the web only — static legal pages, `/.well-known/security.txt`, the cookieless Web Analytics beacon — come from `build-plugins/`. The desktop and Android builds use none of this and contain no analytics. Request flow, cookies, headers and operations: [HOSTING.md](HOSTING.md).
## 7. Desktop Packaging (Tauri)
```
React app (src/), built with TAURI_ENV_PLATFORM set
│
▼
┌────────────────────────────────────────┐
│ Tauri 2 shell │
│ ┌──────────────────────────────────┐ │
│ │ System WebView │ │ ← renders the same React app
│ │ WebView2 · WKWebView · WebKitGTK │ │
│ │ Android System WebView │ │
│ └──────────────────────────────────┘ │
│ ┌──────────────────────────────────┐ │
│ │ Rust core (src-tauri/src) │ │
│ │ lib.rs │ │ ← plugins, commands, tray, single instance
│ │ storage.rs │ │ ← backups and logs, by file name
│ │ file_dialog.rs │ │ ← Save / Open dialogs run in Rust
│ └──────────────────────────────────┘ │
└────────────────────────────────────────┘
│
▼
Release assets:
- Windows: .msi and NSIS .exe
- macOS (Apple silicon): .app.tar.gz
- Linux: .AppImage, .deb, .rpm
- Android: universal .apk
```
**The webview never names a path.** Since v1.0.0 the Rust side exposes only name-only commands for its own files (`backup_*` and `log_*` under the app data directory, `recover_legacy_data`) and two commands that open the native Save / Open dialog themselves (`export_text_file`, `import_text_file`: text formats only, imports capped at 20 MB). The capability file grants the webview only `core:default` and `opener:default`; the fs and shell plugins are gone. The JavaScript bridge is `src/utils/native.ts`, used by `file-ops.ts` (exports and imports on every platform), `log-storage.ts` and `utils/backup/`. Details: [PACKAGING.md](PACKAGING.md).
Tauri advantages over Electron:
- Binary size: ~8MB vs ~150MB
- Memory: ~30MB vs ~100MB+
- No bundled Chromium — uses system WebView
- Rust backend for native features
## 6. Extensibility Points
- No bundled Chromium — uses the system WebView, so installers stay a few megabytes (the v0.38.0 MSI was 4.6 MB)
- Lower memory use
- A Rust backend for native features, with a capability system that limits what the webview can call
| What | How to Extend | Files to Touch |
|------|--------------|----------------|
| New language | Add `locales/{code}/ui.json` + `templates.json`, register in `SUPPORTED_LANGUAGES` (lazy-loaded automatically) | 3 files |
| New genre | Add entry to `config/genres.ts`, add tag pool to `engine/tag-generator.ts` | 2 files |
| New video type | Add to `config/video-types.ts`, add patterns to all `templates.json` | 1 + N locale files |
| New platform/store | Add entry to `config/platforms.ts` | 1 file |
| New social link | Add entry to `config/social-fields.ts` | 1 file |
| New rig field | Add entry to `config/rig-fields.ts` | 1 file |
| Custom template | Edit `templates.json` for target language | 1 file |
| Desktop feature | Add Tauri command in `src-tauri/src/main.rs` | 1 file |
## 8. Extensibility Points
## 7. Data Flow
| What | How to extend | Files to touch |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| New language | Add `locales/{code}/ui.json` + `templates.json` and register it (see section 4 and [I18N.md](I18N.md)); lazy-loaded automatically | 2 locale files + `types.ts`, `i18n/index.ts`, `settings-heal.ts`, `tag-generator.ts`, `channel-phrase.ts` |
| New genre | Add it to the `Genre` union (`engine/types.ts`) and `config/genres.ts`, its tag pool (`GENRE_TAG_REGISTRY`) and search term (`GENRE_SEARCH_TERMS`) to `engine/tag-generator.ts` — a test keeps the three lists in sync — and its `genres.<id>` label to every `ui.json` | 3 + N locale files |
| New video type | Add it to the `VideoType` union and `config/video-types.ts`, its `videoTypes.<id>` label to every `ui.json`, and its title, intro and pinned-comment greeting to every `templates.json` | 2 + 2N locale files |
| New store / platform | Add an entry to `config/platforms.ts` (URL pattern, optional normaliser, `tagName`); optionally a game-name extractor in `utils/url-extractors.ts` | 1–2 files |
| New social link | Add an entry to `config/social-fields.ts` and its `social.<id>` label to every `ui.json` | 1 + N locale files |
| New rig field | Add an entry to `config/rig-fields.ts`, its `rig.<id>` label to every `ui.json` and `description.rigLabels.<id>` to every `templates.json` | 1 + 2N locale files |
| New cross-post platform | Add an entry to `config/social-platforms.ts` (limit, hashtags, count mode) and its `socialPost.platforms.<id>` label | 1 + N locale files |
| Custom template text | Edit `templates.json` for the target language | 1 file |
| Desktop feature | Add a command in `src-tauri/src/` (a module like `storage.rs`), register it in `lib.rs`'s `generate_handler!`, add a typed wrapper in `src/utils/native.ts`. Never take a path from the webview | 3 files |
| Persisted data shape | Bump the store's exported version and add an idempotent step to its exported migration; backups replay it | 1 file |
## 9. Data Flow
```
User Input (form)
User input (form, paste, Quick start, command palette)
│
▼
EditorStore (Zustand)
EditorStore (Zustand, persist → localStorage "ytdescgen-editor-draft")
│
├──→ useGeneratedOutput hook
├──→ useCurrentGeneratorInput → GeneratorInput
│ │
│ ├──→ titleBuilder(input, locale) → title string
│ ├──→ descriptionBuilder(input, locale) → description string
│ ├──→ tagGenerator(input) → tags string[]
│ │
│ └──→ GeneratorOutput (memoized)
│ │
│ ▼
│ OutputPage (display + copy)
│ ▼
│ useGeneratedOutput
│ ├─ useLanguagesReady ([output language])
│ ├─ i18n.getFixedT(language, "templates") + the English tEn
│ ├─ useRenderOptions (Settings → RenderOptions)
│ └─ renderAll → buildTitle · buildDescription · generateTags
│ → GeneratorOutput (memoized)
│ │
│ ▼
│ Output page · Editor live preview · Social captions ·
│ Copy (limits.ts gates) · Ctrl/⌘+Shift+C · command palette
│ │
│ └──→ HistoryStore.addEntry
│ (Output page and Ctrl/⌘+S; one entry per video)
│
├──→ ProfileStore.save() ──→ localStorage
├──→ PresetStore.save() ──→ localStorage
└──→ HistoryStore.add() ──→ localStorage
├──→ Profile / Preset / Template stores (save from the editor;
│ apply through library-apply.ts) ──→ localStorage
│
└──→ Desktop: auto-backup.ts ──→ backup_write ──→ <app data>/backups/
```
The multi-language Output tabs (`useMultilangOutput`) and BatchPage call `renderAll` themselves, once per language, with the same `useRenderOptions` mapping.
+191 -81
View File
@@ -1,15 +1,22 @@
# Content Inventory
A static manifest of every video type, game genre, and content warning surfaced in YTDescGen's editor. Maintained manually — when adding a new option to one of the source files below, **add a row here too** in the same PR.
A static manifest of every video type, game genre, content warning, tech note, store, link field and cross-post platform surfaced in YTDescGen's editor (as of v1.2.0). Maintained manually — when adding a new option to one of the source files below, **add a row here too** in the same PR.
This file exists for **transparency** — anyone curious about what the editor can describe (without installing the app or reading the source) can scan it in one minute.
**Vietnamese mirror:** [`docs/i18n/vi/CONTENT-INVENTORY.md`](./i18n/vi/CONTENT-INVENTORY.md).
**Source of truth:**
- Video types: [`src/config/video-types.ts`](../src/config/video-types.ts)
- Game genres: [`src/config/genres.ts`](../src/config/genres.ts)
- Content warnings: [`src/config/content-warning-groups.ts`](../src/config/content-warning-groups.ts)
- Tech notes: [`src/config/tech-note-groups.ts`](../src/config/tech-note-groups.ts)
- Stores: [`src/config/platforms.ts`](../src/config/platforms.ts)
- Social & donate links: [`src/config/social-fields.ts`](../src/config/social-fields.ts)
- Community links: [`src/components/editor/CommunityEditor.tsx`](../src/components/editor/CommunityEditor.tsx)
- Vietnamese banks: [`src/config/vietnamese-banks.ts`](../src/config/vietnamese-banks.ts)
- Cross-post platforms: [`src/config/social-platforms.ts`](../src/config/social-platforms.ts)
---
@@ -17,87 +24,87 @@ This file exists for **transparency** — anyone curious about what the editor c
Each video type drives a dedicated description template + title structure + tag bias. The "Extra fields" column lists fields the editor reveals when this type is selected.
| Icon | Type | Extra fields |
|---|---|---|
| 🎮 | Full Gameplay | — |
| 📂 | Gameplay Part | Part Number |
| 🎬 | Full Demo | — |
| 🎞 | Demo Part | Part Number |
| 👹 | Boss Fight | Boss Name |
| 💀 | Boss No Hit | Boss Name |
| 🏁 | Ending / All Endings | — |
| ⚡ | Speedrun | — |
| 💯 | 100% Completion | — |
| 📦 | DLC Content | DLC Name |
| 🔄 | New Game+ | — |
| 🏆 | Challenge Run | Challenge Name |
| 📌 | Side Quests | — |
| 🔍 | Secrets / Hidden | — |
| ⚖️ | Graphics Comparison | — |
| 📘 | Silent Guide | — |
| 🧩 | Modded Gameplay | Mod Name |
| ⭐ | All Collectibles | — |
| 🔴 | Livestream | Live URL, Scheduled Time |
| 🎴 | Gacha Quest | Quest Type, Chapter Name, Quest Name, Part Number |
| Icon | Type | Extra fields |
| ---- | -------------------- | ------------------------------------------------- |
| 🎮 | Full Gameplay | — |
| 📂 | Gameplay Part | Part Number |
| 🎬 | Full Demo | — |
| 🎞 | Demo Part | Part Number |
| 👹 | Boss Fight | Boss Name |
| 💀 | Boss No Hit | Boss Name |
| 🏁 | Ending / All Endings | — |
| ⚡ | Speedrun | — |
| 💯 | 100% Completion | — |
| 📦 | DLC Content | DLC Name |
| 🔄 | New Game+ | — |
| 🏆 | Challenge Run | Challenge Name |
| 📌 | Side Quests | — |
| 🔍 | Secrets / Hidden | — |
| ⚖️ | Graphics Comparison | — |
| 📘 | Silent Guide | — |
| 🧩 | Modded Gameplay | Mod Name |
| ⭐ | All Collectibles | — |
| 🔴 | Livestream | Live URL, Scheduled Time |
| 🎴 | Gacha Quest | Quest Type, Chapter Name, Quest Name, Part Number |
---
## 2. Game genres (41)
## 2. Game genres (42)
Selected genres feed the title format, the tag pool, and (when configured in Settings → Genre Playlists) the pinned-comment recommendation.
Selected genres (up to 3 per video) feed the title format, the tag pool, and (when configured in Settings → Genre Playlists) the pinned-comment recommendation.
Bulk-select groups available in the editor: **All RPGs** (rpg + jrpg + action_rpg + crpg), **All Shooters** (fps + arena_shooter + tactical_fps + boomer_shooter + extraction_shooter + shmup), **All Horror** (horror + survival_horror + psychological_horror).
Bulk-select groups available in the editor: **All RPGs** (rpg + jrpg + action_rpg + crpg), **All Shooters** (fps + arena_shooter + tactical_fps + boomer_shooter + extraction_shooter + shmup), **All Horror** (horror + survival_horror + psychological_horror). A group replaces the selection with its first three genres.
| Icon | Genre |
|---|---|
| ⚔️ | Action / Adventure |
| 🗡 | Hack & Slash |
| 👊 | Beat 'em Up |
| 🦘 | Platformer |
| 👻 | Horror / Survival |
| 🧟 | Survival Horror |
| 🧠 | Psychological Horror |
| 🛡 | RPG |
| 🎎 | JRPG |
| 🏹 | Action RPG |
| 📜 | CRPG / Isometric |
| 🔫 | FPS / Shooter |
| 🎯 | Arena Shooter |
| 🎖 | Tactical FPS |
| 💥 | Boomer Shooter |
| 🎒 | Extraction Shooter |
| 🛸 | SHMUP / Bullet Hell |
| 🌍 | Open World / Sandbox |
| 🕹 | Indie |
| 💀 | Souls-like |
| 🏎 | Racing / Sports |
| 📖 | Story / Narrative |
| 🏗 | Simulation / Strategy |
| 🏙 | City Builder |
| 🥊 | Fighting |
| 🥷 | Stealth / Espionage |
| ⛏ | Survival / Crafting |
| 🎲 | Roguelike / Roguelite |
| 🗺 | Metroidvania |
| 🌐 | MMO / Online |
| 🎵 | Rhythm / Music |
| 🧩 | Puzzle |
| 🏰 | Tower Defense |
| 🃏 | Card Game |
| 🎴 | Deck Builder |
| 🤖 | Auto Battler |
| 🏆 | Battle Royale |
| ♟ | Tactical / Turn-based |
| 🚀 | Space / Sci-Fi |
| 🌾 | Farming / Life Sim |
| 🎬 | FMV / Interactive Movie |
| 💬 | Visual Novel |
| Icon | Genre |
| ---- | ----------------------- |
| ⚔️ | Action / Adventure |
| 🗡 | Hack & Slash |
| 👊 | Beat 'em Up |
| 🦘 | Platformer |
| 👻 | Horror / Survival |
| 🧟 | Survival Horror |
| 🧠 | Psychological Horror |
| 🛡 | RPG |
| 🎎 | JRPG |
| 🏹 | Action RPG |
| 📜 | CRPG / Isometric |
| 🔫 | FPS / Shooter |
| 🎯 | Arena Shooter |
| 🎖 | Tactical FPS |
| 💥 | Boomer Shooter |
| 🎒 | Extraction Shooter |
| 🛸 | SHMUP / Bullet Hell |
| 🌍 | Open World / Sandbox |
| 🕹 | Indie |
| 💀 | Souls-like |
| 🏎 | Racing / Sports |
| 📖 | Story / Narrative |
| 🏗 | Simulation / Strategy |
| 🏙 | City Builder |
| 🥊 | Fighting |
| 🥷 | Stealth / Espionage |
| ⛏ | Survival / Crafting |
| 🎲 | Roguelike / Roguelite |
| 🗺 | Metroidvania |
| 🌐 | MMO / Online |
| 🎵 | Rhythm / Music |
| 🧩 | Puzzle |
| 🏰 | Tower Defense |
| 🃏 | Card Game |
| 🎴 | Deck Builder |
| 🤖 | Auto Battler |
| 🏆 | Battle Royale |
| ♟ | Tactical / Turn-based |
| 🚀 | Space / Sci-Fi |
| 🌾 | Farming / Life Sim |
| 🎬 | FMV / Interactive Movie |
| 💬 | Visual Novel |
---
## 3. Content warnings (248, grouped)
## 3. Content warnings (257, grouped)
Selected warnings are appended to a `⚠ CONTENT WARNINGS` block in the description, ahead of timestamps. Each group is collapsible in the editor; warnings render in description order = user's selection order.
Selected warnings are rendered in a `▸ ⚠️ CONTENT WARNINGS` block in the description, after the rig block (and the mod list, for Modded Gameplay). Each group is collapsible in the editor; warnings render in description order = user's selection order.
### Spoilers (6)
@@ -127,13 +134,13 @@ Anxiety-inducing scenes · Depression themes · Eating disorders · Substance us
Autism / neurodivergence themes · ADHD / executive dysfunction · Hikikomori / social withdrawal · NEET themes · Social anxiety themes · Social isolation / loneliness · Schizophrenia / psychosis · Burnout / overwork · Survivor guilt · Abandonment themes · Parasocial relationships · Gaslighting · Stockholm syndrome · Gaming / gambling addiction · Existential / nihilistic themes · Impostor syndrome · Midlife crisis · Quarter-life crisis · Workplace harassment · Gender-role pressure · Body shaming / appearance mockery · Unrealistic beauty standards
### Internet / Digital life (18)
### Internet / Digital life (19)
Cyberbullying / online harassment · Doxxing / privacy exposure · Trolling / griefing · Cancel culture / public shaming · Social media addiction · Doomscrolling · FOMO (fear of missing out) · Fake news / misinformation · Online scams / phishing · Catfishing / fake identity · Deepfakes / synthetic media · Cyberstalking · Dangerous viral challenges · Influencer culture / clout chasing · Online radicalization / echo chambers · Loot boxes / gacha mechanics · AI / artificial intelligence themes · Data privacy / mass surveillance
Cyberbullying / online harassment · Doxxing / privacy exposure · Trolling / griefing · Cancel culture / public shaming · Social media addiction · Doomscrolling · FOMO (fear of missing out) · Fake news / misinformation · Online scams / phishing · Catfishing / fake identity · Deepfakes / synthetic media · Cyberstalking · Dangerous viral challenges · Influencer culture / clout chasing · Online radicalization / echo chambers · Loot boxes / gacha mechanics · In-game purchases · AI / artificial intelligence themes · Data privacy / mass surveillance
### Mature / Sensitive content (66)
### Mature / Sensitive content (67)
Blood and gore · Mature 18+ · Revealing / skimpy outfits · Partial nudity · Sexualized character designs · Fan service / ecchi · Suggestive poses / camera angles · Disturbing imagery · Animal cruelty · Violence against minors · Domestic violence · Sexual assault references · Torture · Religious themes · War violence · Discrimination · State / police violence · Smoking / drinking · Detailed killing · Cult / occult · Psychological manipulation · Loss / grief · Kidnapping · Hate speech · Historical atrocities · Slavery themes · Terrorism themes · Bullying themes · Human experimentation · Cannibalism · Nuclear / radiation · Homophobia / anti-LGBTQ+ · Transphobia / anti-trans · Xenophobia / anti-foreigner · Political extremism · Religious extremism / fundamentalism · Genocide / ethnic cleansing · Holy war / sectarian conflict · Holocaust themes · Civil war · Mass / school shootings · Colonialism / imperialism · State propaganda · Surveillance / dystopian state · Conspiracy theories · Censorship themes · Ethnic / racial conflict · Refugee crisis · Revolution / uprising · Political assassination · Coup d'état · Inquisition / religious persecution · Forced labor · Ultranationalism · Hanging / strangulation · Drowning scene · Burning alive / immolation · Asphyxiation / suffocation · Bound / restrained victim · Public execution · Decapitation · Impalement · Mass-casualty event · Vehicular violence · Overdose scene · Falling from height (intentional)
Blood and gore · Mature 18+ · Revealing / skimpy outfits · Partial nudity · Sexualized character designs · Fan service / ecchi · Suggestive poses / camera angles · Disturbing imagery · Animal cruelty · Violence against minors · Domestic violence · Sexual assault references · Torture · Religious themes · War violence · Discrimination · State / police violence · Smoking / drinking · Simulated gambling · Detailed killing · Cult / occult · Psychological manipulation · Loss / grief · Kidnapping · Hate speech · Historical atrocities · Slavery themes · Terrorism themes · Bullying themes · Human experimentation · Cannibalism · Nuclear / radiation · Homophobia / anti-LGBTQ+ · Transphobia / anti-trans · Xenophobia / anti-foreigner · Political extremism · Religious extremism / fundamentalism · Genocide / ethnic cleansing · Holy war / sectarian conflict · Holocaust themes · Civil war · Mass / school shootings · Colonialism / imperialism · State propaganda · Surveillance / dystopian state · Conspiracy theories · Censorship themes · Ethnic / racial conflict · Refugee crisis · Revolution / uprising · Political assassination · Coup d'état · Inquisition / religious persecution · Forced labor · Ultranationalism · Hanging / strangulation · Drowning scene · Burning alive / immolation · Asphyxiation / suffocation · Bound / restrained victim · Public execution · Decapitation · Impalement · Mass-casualty event · Vehicular violence · Overdose scene · Falling from height (intentional)
### Heavy horror (12)
@@ -147,15 +154,118 @@ Blind playthrough · No spoilers in chat · Casual / story mode · Hardcore / ma
Mods used · Cheats / debug · Glitches used · Guide-assisted · Educational / PSA purpose
### AI-generated content (7)
AI-generated content (general) · AI art / visuals · AI / synthetic voices · AI music / sound · AI-written text / dialogue · Generated live by AI while playing · AI use disclosed by the developer
The game itself is made or run with generative AI — a story _about_ AI is "AI / artificial intelligence themes" above. The split follows Steam's AI disclosure: content made with AI during development and shipped in the game, and content an AI generates live while you play. Machine translation is the **Language patch** field in Playthrough notes, so it has no warning here. YouTube doesn't ask for gameplay footage to be labelled as altered or synthetic; these lines are for viewers.
---
## 4. Maintenance
## 4. Tech notes (25, grouped)
Selected notes are rendered in a `▸ 🛠 TECH NOTES` block right after the content warnings, in the order you picked them. They describe the recording, not the game. Facts that have their own field — difficulty, endings shown, language patch, game version, the upscaler and frame generation in Video settings — are not repeated here.
### Audio (5)
Some sections muted (copyright) · Volume reduced (copyright) · Game music replaced (copyright) · Cutscene audio muted only · Original audio kept (claim risk)
### Video quality (4)
Low resolution (hardware) · Lower graphics (performance) · FPS drops (hardware) · Upscaling / frame-gen artifacts
### Recording issues (4)
Bugs are from the game · Crash kept (transparency) · Loading screens cut · Possible OBS artifacts
### Playstyle disclaimers (8)
NOT a no-hit run · Not a clean walkthrough · Casual, no commentary · Many deaths · Slow exploration · May get stuck on puzzles · Grinding cut · Not a speedrun
### Production & attribution (4)
Exploration-focused (skip combat) · Edited for pacing · Support the developers · Online connectivity issues
---
## 5. Stores (15 + publisher site)
Each store has a link field. A store link pasted anywhere in the editor lands in the right field; the first one also sets the video's platform, whose search name is used in the tags. Each link is marked paid, free or demo.
| Store | Links accepted | Name in tags |
| -------------------------- | -------------------------------------------------------------------------- | --------------- |
| Steam | `store.steampowered.com/app/…` (also `/sub/`, `/bundle/` and `s.team/a/…`) | Steam |
| Epic Games Store | `store.epicgames.com/…` | Epic Games |
| PlayStation Store | `store.playstation.com/…` | PlayStation |
| Xbox / Microsoft Store | `xbox.com/…`, `apps.microsoft.com/…`, Microsoft Store pages | Xbox |
| Nintendo eShop | `nintendo.com/…` and the regional Nintendo sites | Nintendo Switch |
| GOG | `gog.com/…` | GOG |
| itch.io | `<dev>.itch.io/<game>` | itch.io |
| Humble Bundle | `humblebundle.com/…` | Humble Bundle |
| Amazon Luna | `luna.amazon.com/…`, Amazon storefronts | Amazon Luna |
| EA app | `ea.com/…` | EA app |
| Ubisoft Store | `store.ubisoft.com/…`, `ubisoft.com/…` | Ubisoft Connect |
| Battle.net | `shop.battle.net/…` and its regional hosts | Battle.net |
| Google Play | `play.google.com/store/apps/details?id=…` | Android |
| App Store | `apps.apple.com/…` | iOS |
| Meta Quest Store | `meta.com/…`, `oculus.com/…` | Meta Quest |
| Publisher / Developer site | any `https://` link | — |
---
## 6. Social, donate & community links
### Donate (5)
Ko-fi · Patreon · Buy Me a Coffee · PayPal · Streamlabs
### Social (17)
GitHub · YouTube · X (Twitter) · Discord · Twitch · Kick · TikTok · Instagram · Threads · Bluesky · Mastodon · Facebook · Facebook Page · Reddit · Bilibili · Telegram · Website
### Community (5)
Messenger community · Signal group · Instagram group chat · Facebook Group · Zalo group (Vietnamese output only)
### Vietnamese banks (37)
For the Donate (Vietnam) block — bank transfer, MoMo and ZaloPay — which renders only when the output language is Vietnamese. "Other" lets you type any bank; a profile saved with a bank's former name is offered the new one.
- **State-owned (4):** Vietcombank · BIDV · VietinBank · Agribank
- **Joint-stock (24):** Techcombank · MB Bank · ACB · VPBank · TPBank · Sacombank · HDBank · VIB · SHB · Eximbank · OCB · MSB · LPBank · SeABank · ABBank · BAC A Bank · PVcomBank · NCB · Nam A Bank · KienlongBank · Saigonbank · VietABank · Vietbank · BVBank
- **Renamed in 2025, and digital-first (5):** MBV (formerly OceanBank) · VCBNeo (formerly CBBank) · Vikki Bank (formerly DongA Bank) · Cake by VPBank · Timo
- **Foreign-owned (4):** HSBC Vietnam · Standard Chartered · Shinhan Bank · UOB Vietnam
---
## 7. Cross-post platforms (7)
The Social tab turns the same editor data into short-form captions. When a caption runs over the platform's limit, optional blocks are dropped (content warnings first); hashtags are capped per platform.
| Platform | Caption limit | Hashtags |
| --------------- | --------------------------------------------------------------------------------------------- | -------- |
| TikTok | 4,000 | no cap |
| YouTube Shorts | 5,000 | up to 5 |
| Instagram Reels | 2,200 | no cap |
| Facebook Reels | 2,200 | no cap |
| X | 280, counted the way X counts (CJK, Vietnamese letters with diacritics and emoji count twice) | up to 3 |
| Threads | 500 | 1 |
| Bluesky | 300 | up to 3 |
---
## 8. Maintenance
When adding a new item to any of the source files:
1. **Video types** → append to [`src/config/video-types.ts`](../src/config/video-types.ts) AND add a row in section 1 above.
2. **Genres** → append to [`src/config/genres.ts`](../src/config/genres.ts) AND add a row in section 2.
3. **Content warnings** → append to the relevant group in [`src/config/content-warning-groups.ts`](../src/config/content-warning-groups.ts) AND add the label to the right group in section 3 — keep the group count in the heading accurate.
4. Update the Vietnamese mirror at [`docs/i18n/vi/CONTENT-INVENTORY.md`](./i18n/vi/CONTENT-INVENTORY.md) in the same PR.
1. **Video types** → append to [`src/config/video-types.ts`](../src/config/video-types.ts) (plus its title, intro and pinned-comment greeting in every `templates.json`) AND add a row in section 1 above.
2. **Genres** → append to [`src/config/genres.ts`](../src/config/genres.ts) (plus its tag pool and search term in `src/engine/tag-generator.ts` — a test keeps them in sync) AND add a row in section 2.
3. **Content warnings** → append the id to `CONTENT_WARNINGS` in `src/engine/types.ts` and to the relevant group in [`src/config/content-warning-groups.ts`](../src/config/content-warning-groups.ts), plus its editor label and description bullet in every locale and `_schema.json` (a test fails without them), AND add the label to the right group in section 3 — keep the counts in the headings accurate.
4. **Tech notes** → the same in `TECH_NOTES` and [`src/config/tech-note-groups.ts`](../src/config/tech-note-groups.ts) AND section 4.
5. **Stores** → add to [`src/config/platforms.ts`](../src/config/platforms.ts) (URL pattern and `tagName`; optionally a game-name extractor in `src/utils/url-extractors.ts`) AND add a row in section 5.
6. **Social / donate links** → add to [`src/config/social-fields.ts`](../src/config/social-fields.ts) (plus its `social.<id>` label in every `ui.json`) AND add it to section 6.
7. **Vietnamese banks** → add to [`src/config/vietnamese-banks.ts`](../src/config/vietnamese-banks.ts) — for a renamed bank, add the new name and map the old one in `VIETNAMESE_BANK_RENAMES` — AND update section 6.
8. **Cross-post platforms** → add to [`src/config/social-platforms.ts`](../src/config/social-platforms.ts) (plus its `socialPost.platforms.<id>` label in every `ui.json`) AND add a row in section 7.
9. Update the Vietnamese mirror at [`docs/i18n/vi/CONTENT-INVENTORY.md`](./i18n/vi/CONTENT-INVENTORY.md) in the same PR.
Mismatch between this file and the source files is treated as a documentation bug — open an issue or PR.
+138 -38
View File
@@ -1,19 +1,19 @@
# Development Guide
This guide covers setting up YTDescGen for local development on Windows, macOS, or Linux. The application is a Vite/React web app with an optional Tauri desktop shell.
This guide covers setting up YTDescGen for local development on Windows, macOS, or Linux. The application is a Vite/React web app with an optional Tauri shell for desktop and Android. On the web it is served at [ytgenerator.stream](https://ytgenerator.stream) by a Cloudflare Worker — see [HOSTING.md](./HOSTING.md).
## Reference Workstation
The reference workstation used to develop and ship this project:
| Component | Spec |
| --- | --- |
| OS | Windows 11 Pro (24H2 or newer) |
| CPU | Modern x86-64 — 6+ cores with AVX2 (Intel 11th-gen / AMD Zen 3 or newer) |
| GPU | Discrete or integrated — Tauri's WebView2 backend runs fine on iGPU |
| RAM | 16 GB minimum, 32 GB recommended for parallel typecheck + dev server |
| Storage | 5 GB free for `node_modules` + Cargo `target/` after a full Tauri build |
| Display | 1920×1080 minimum; mobile-responsive layout tested down to 360×640 |
| Component | Spec |
| --------- | ------------------------------------------------------------------------ |
| OS | Windows 11 Pro (24H2 or newer) |
| CPU | Modern x86-64 — 6+ cores with AVX2 (Intel 11th-gen / AMD Zen 3 or newer) |
| GPU | Discrete or integrated — Tauri's WebView2 backend runs fine on iGPU |
| RAM | 16 GB minimum, 32 GB recommended for parallel typecheck + dev server |
| Storage | 5 GB free for `node_modules` + Cargo `target/` after a full Tauri build |
| Display | 1920×1080 minimum; mobile-responsive layout tested down to 360×640 |
macOS and Linux work for development. Tauri release builds are cross-compiled or run on dedicated CI runners — see [PACKAGING.md](./PACKAGING.md).
@@ -21,13 +21,13 @@ macOS and Linux work for development. Tauri release builds are cross-compiled or
Install in this order:
| Tool | Version | Why |
| --- | --- | --- |
| **Node.js** | `>= 22.12.0` | Vite 8 requires Node `^20.19` or `>= 22.12`. Use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm). |
| **npm** | bundled with Node 22 | The project uses npm; `pnpm` and `yarn` are not tested. |
| **Rust** | stable, `>= 1.78` | Required for the Tauri desktop build. Install via [rustup](https://rustup.rs/). |
| **Python** | `3.12` | Optional — only needed for some Tauri platform tooling on Windows. |
| **Tauri prerequisites** | per OS | See <https://v2.tauri.app/start/prerequisites/>. |
| Tool | Version | Why |
| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Node.js** | **22** — the version in `.node-version` | CI, the release workflows and Cloudflare Workers Builds all read `.node-version`. Vite 8 needs Node `^20.19` or `>= 22.12` and wrangler needs `>= 22`, so use 22.12 or newer. Use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) (fnm reads `.node-version`). |
| **npm** | bundled with Node 22 | The project uses npm; `pnpm` and `yarn` are not tested. |
| **Rust** | stable, `>= 1.90` | Required for the Tauri desktop and Android builds (Tauri 2.12 needs Rust 1.90). Install via [rustup](https://rustup.rs/); its default profile includes `rustfmt` and `clippy`. |
| **Python** | `3.12` | Optional — only needed for some Tauri platform tooling on Windows. |
| **Tauri prerequisites** | per OS | See <https://v2.tauri.app/start/prerequisites/>. |
### Windows specifics
@@ -52,7 +52,7 @@ The reference workflow uses **JetBrains 2026.x** IDEs (WebStorm or RustRover) as
- Enable the **Tailwind CSS** plugin.
- Enable the **i18next** plugin (or rely on `src/i18n/locales/_schema.json` for autocomplete).
- Settings → Languages → TypeScript → "Use TypeScript from `node_modules/typescript`".
- Settings → Code Style → Prettier → Run on save (`src/**/*.{ts,tsx,json,css}`).
- Settings → Code Style → Prettier → Run on save (`{src,tests,scripts,worker,build-plugins}/**/*.{ts,tsx,css}` — the same files `npm run format` covers).
### VS Code
@@ -79,23 +79,93 @@ npm run dev
# → http://localhost:5173
```
The dev server is the app alone: no Turnstile gate and no analytics. To run the Worker that serves the web app, see [Cloudflare Worker (local)](#cloudflare-worker-local).
## Branches and Pull Requests
- Branch from `main` (`feat/…`, `fix/…`, `docs/…`, `chore/…`) and open the pull request against `main`. There is no other long-lived branch, and every merge to `main` deploys the web app.
- PR titles use the commit format `type(scope): message`; CI checks them.
- Every PR runs the `check` job (below), `dependency-review`, `workflow-lint`, `reuse` and `pr-title`; the Rust jobs `lint-and-test` and `cargo-deny` run when `src-tauri/` changes.
Full rules: [CONTRIBUTING.md](../CONTRIBUTING.md).
## Common Commands
| Command | What it does |
| --- | --- |
| `npm run dev` | Vite dev server, hot reload, web only. |
| `npm run build` | Production web bundle into `dist/`. |
| `npm run preview` | Serve the production bundle for sanity-testing. |
| `npm run typecheck` | `tsc --noEmit`. Run before every PR. |
| `npm run lint` | ESLint. Use `npm run lint:fix` to autofix. |
| `npm run format` | Prettier write across `src/`. |
| `npm run test` | Vitest watch mode. |
| `npm run test:run` | Vitest single-run (for CI / pre-commit). |
| `npm run test:coverage` | Coverage report into `coverage/`. |
| `npm run validate:locales` | Enforces all 6 locales match `_schema.json` exactly. **Must pass before any locale-touching PR merges.** |
| `npm run generate:locale` | Scaffold an empty locale from `_schema.json` for a new language. |
| `npm run tauri:dev` | Tauri desktop in dev mode (auto-restarts on Rust or frontend changes). |
| `npm run tauri:build` | Tauri release binary for the current platform. |
### Develop and build
| Command | What it does |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run dev` | Vite dev server, hot reload, web only. |
| `npm run build` | `tsc` + production web bundle into `dist/`. The web build also gets the Web Analytics beacon, `/.well-known/security.txt` and the static `/legal/*` pages; builds started by the Tauri CLI leave them out. |
| `npm run preview` | Serve the production bundle for sanity-testing (without the Worker). |
| `npm run cf:dev` | `wrangler dev` — the Worker in front of `dist/` on `http://localhost:8787`. See [Cloudflare Worker (local)](#cloudflare-worker-local). |
| `npm run tauri:dev` | Tauri desktop in dev mode (also `npm run tauri dev`): starts `npm run dev` and opens the app window on it. Frontend changes hot-reload; Rust changes rebuild the app. |
| `npm run tauri:build` | Tauri release binary for the current platform. |
### Check
| Command | What it does |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run typecheck` | `tsc --noEmit` over `src/` — what Vite actually builds. |
| `npm run typecheck:all` | Same, plus `tests/`, `scripts/`, `worker/` and `build-plugins/` (`tsconfig.check.json`), which the base config deliberately excludes. Added in v0.35.0 after it turned out tests and scripts had **never** been type-checked — and immediately found three fields silently missing from the editor→engine parity fixture. |
| `npm run lint` | ESLint over `src/`, `tests/`, `scripts/`, `worker/` and `build-plugins/`. Use `npm run lint:fix` to autofix. |
| `npm run format` | Prettier write across `src/`, `tests/`, `scripts/`, `worker/` and `build-plugins/` (`.ts`, `.tsx`, `.css`). |
| `npm run format:check` | Same, read-only. CI gate. Markdown and the locale JSON are deliberately out of scope. |
| `npm run knip` | Dead-code / unused-dependency check. CI gate. |
| `npm run validate:locales` | Enforces all 8 locales match `_schema.json` exactly. **Must pass before any locale-touching PR merges.** |
| `npm run test` | Vitest watch mode. |
| `npm run test:run` | Vitest single-run. |
| `npm run test:coverage` | Single run with a coverage report into `coverage/`; fails below the thresholds for `src/engine/` and `worker/` set in `vitest.config.ts`. This is what CI runs. |
| `npm run check:version` | Asserts all **six** version fields agree (`package.json`, both `package-lock.json` entries, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`). The only thing that notices a missed one. |
| `npm run check:tauri` | The `@tauri-apps/*` npm packages and the Tauri crates must share major.minor. The Tauri CLI refuses to build otherwise, and CI never runs a Tauri build. |
| `npm run check:licenses` | Every bundled package has an allowed license, and `THIRD_PARTY_NOTICES.md` matches what is installed. |
| `npm run check:copyright` | NOTICE, REUSE.toml and the installers' copyright string (`tauri.conf.json`) state the copyright years for the year of HEAD's commit — "2026", then "2026-2027" from the first commit of 2027. CI gate (v1.1.0). |
| `npm run check:bundle` | Run after `npm run build`: the initial load must stay ≤ 280 KB gzip and no JS chunk over 500 KB raw. |
| `npm run cf:check` | `wrangler deploy --dry-run`: validates `wrangler.jsonc` and bundles the Worker the way Workers Builds will, without deploying. |
### Generate
| Command | What it does |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run generate:locale` | Scaffold a locale from the English source. `--lang <code>`, plus optional `--copy-english` / `--force`. (Advertised since v0.1 but only actually written in v0.35.0.) |
| `npm run generate:third-party` | Rewrite `THIRD_PARTY_NOTICES.md` from the installed packages — needed after a dependency change, or `check:licenses` fails. |
| `npm run update:copyright` | Rewrite the copyright years in NOTICE, REUSE.toml and `tauri.conf.json` — needed with the first commit of a new year, or `check:copyright` fails. |
| `npm run generate:brand` | Rasterise the brand SVGs in `assets/brand/` into the web's PNG icons and link-preview card in `public/`. The PNGs are committed. The desktop and Android icons come from the same logo: `npx tauri icon assets/brand/logo.svg`. |
## Before You Open a PR
Run what CI's `check` job runs:
```bash
npm run typecheck && npm run typecheck:all
npm run lint && npm run format:check
npm run validate:locales
npm run test:coverage
npm run knip
npm run check:version && npm run check:tauri && npm run check:licenses
npm run check:copyright
npm run build && npm run check:bundle
npm run cf:check
```
Touched `src-tauri/`? Also run the [Rust checks](#rust-checks).
## Cloudflare Worker (local)
The web app is served by a Cloudflare Worker ([`worker/`](../worker), configured in [`wrangler.jsonc`](../wrangler.jsonc)) that puts the Turnstile gate, the security headers and the public `/legal` pages in front of `dist/`. To run it locally:
```bash
cp .dev.vars.example .dev.vars # Cloudflare's public Turnstile TEST keys only
npm run build # the Worker serves dist/
npm run cf:dev # wrangler dev → http://localhost:8787
```
- `.dev.vars` (git-ignored) holds Cloudflare's published Turnstile **test** keys: the widget always passes and the secret only accepts the dummy token it produces. Never put the real secret in a file — production keeps `TURNSTILE_SECRET` as a Cloudflare Secret.
- Without `.dev.vars` the Worker has no `TURNSTILE_SECRET` and fails open: the app loads without the gate.
- The Worker serves the last build — run `npm run build` again to see frontend changes behind it.
- Worker tests run with the rest of the suite (`tests/worker/`).
Deployment, cookies, headers, secrets and rollback: [HOSTING.md](./HOSTING.md).
## Tauri Desktop Build
@@ -103,16 +173,37 @@ See [PACKAGING.md](./PACKAGING.md) for the full release pipeline. Quick local bu
```bash
npm run tauri:build
# Output: src-tauri/target/release/bundle/{msi,deb,dmg,app}
# Output: src-tauri/target/release/bundle/
# Windows: MSI + NSIS installers · Linux: deb, rpm, AppImage · macOS: .app + DMG
```
The first build takes ~5–10 minutes (cold Cargo cache). Subsequent builds are incremental.
The Vite dev server does not watch `src-tauri/**` or `.wrangler/**` (`server.watch.ignored` in `vite.config.ts`): while `tauri dev` runs, Cargo rewrites files under `src-tauri/target`, and watching them crashed Vite on Windows with `EBUSY` on a locked `.dll`.
### Rust checks
The same steps as the `lint-and-test` job in `.github/workflows/rust.yml`, which runs when `src-tauri/` changes (and weekly):
```bash
npm run build # tauri::generate_context!() embeds dist/, so clippy and the tests need a build
cd src-tauri
cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked
```
The `cargo-deny` job checks RustSec advisories, licenses and crate sources against `src-tauri/deny.toml`. Locally (after `cargo install cargo-deny`): `cargo deny check advisories licenses sources` in `src-tauri/`.
## Troubleshooting
### `validate:locales` fails after adding a key
You forgot to update `src/i18n/locales/_schema.json`. The schema is the source of truth; locales must match it exactly.
You forgot to update `src/i18n/locales/_schema.json`, or one of the 8 locales. The schema is the source of truth; every locale must match it exactly.
### `validate:locales` fails but I didn't touch locales
Someone — or a merge from `main` — added a key to `_schema.json` (for example the label of a new `CONTENT_WARNINGS` id from `src/engine/types.ts`) that isn't in every locale yet. New keys need a value in all 8 locales.
### Tauri build fails with `link.exe not found` (Windows)
@@ -122,6 +213,18 @@ Install Visual Studio Build Tools 2022 + Desktop C++ workload, then restart your
Install the per-distro Tauri prerequisites listed at <https://v2.tauri.app/start/prerequisites/>.
### `check:tauri` fails after a dependency update
A `@tauri-apps/*` npm package moved to a new minor version without the crates (or the other way round). Run `cargo update -p tauri` (and the plugin crates `check:tauri` names) in `src-tauri/` on the same branch.
### `check:bundle` can't find `dist/index.html`
It measures a build — run `npm run build` first.
### `npm run cf:dev` shows no Turnstile gate
`.dev.vars` is missing, so the Worker has no secret and serves the app without the gate. Copy `.dev.vars.example` to `.dev.vars` and restart.
### `npm install` is slow or hangs
Disable corporate VPNs / proxies that block the npm registry. The lock file is committed; offline installs work after one successful online install.
@@ -134,13 +237,10 @@ Since v0.26, only English ships in the main chunk; the other languages are
lazy-loaded async chunks fetched on first use (see `src/i18n/index.ts` and
docs/I18N.md). The restart advice above still applies to all of them.
### Pre-commit hook fails on `validate:locales` but I didn't touch locales
You probably added a new key to `_schema.json` indirectly via the engine types (`src/engine/types.ts` → `CONTENT_WARNINGS`). New IDs require translations in all 6 locales.
## See Also
- [ARCHITECTURE.md](./ARCHITECTURE.md) — layer model, data flow, engine design.
- [HOSTING.md](./HOSTING.md) — how ytgenerator.stream is built, deployed and protected.
- [I18N.md](./I18N.md) — adding new languages step-by-step.
- [PACKAGING.md](./PACKAGING.md) — Tauri release builds and signing.
- [Top-level CONTRIBUTING.md](../CONTRIBUTING.md) — PR process, commit conventions, auto-ignore rules.
+419 -210
View File
@@ -1,9 +1,26 @@
# Complete Feature List
## YTDescGen — All Features (Current + Planned)
## YTDescGen — All Features (v1.2.0 + Planned)
---
## 🌍 Where It Runs
| Platform | Where | Bot check & analytics |
| ----------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Web** | [ytgenerator.stream](https://ytgenerator.stream) | A Cloudflare **Turnstile** check (usually invisible), remembered for 24 hours; **cookieless** Web Analytics |
| **Desktop** | Windows, macOS, Linux — [Releases](https://github.com/poli0981/youtube-generator/releases) | Neither |
| **Android** | Android 11+, sideloaded `.apk` — [Releases](https://github.com/poli0981/youtube-generator/releases) | Neither |
The web app is a Cloudflare Worker in front of the static build, and
Cloudflare Workers Builds deploys every merge to `main` — see
[HOSTING.md](./HOSTING.md). On every platform your data stays on the device.
GitHub Pages is retired. Until **2026-11-29** the old
`poli0981.github.io/youtube-generator` address shows a moving notice whose
**Download my data** button saves what the browser stored there as a backup
file — restore it in **Settings › Backup & restore**.
## 🎬 Video Types (20 types)
Twenty video types, each driving a dedicated description template, title
@@ -11,119 +28,212 @@ structure, and tag bias. The complete table — every type with its icon and
the extra fields the editor reveals — is in
[Content Inventory](./CONTENT-INVENTORY.md).
## 🌐 Languages (6 shipped)
## 🌐 Languages (8 shipped)
All six locales ship today — UI strings and description templates fully
All eight locales ship today — UI strings and description templates fully
translated and parity-validated by `npm run validate:locales`.
| Code | Language | Native Name | Status |
|------|----------|-------------|--------|
| `en` | English | English | ✅ Shipped |
| `vi` | Vietnamese | Tiếng Việt | ✅ Shipped |
| `ja` | Japanese | 日本語 | ✅ Shipped |
| `es` | Spanish | Español | ✅ Shipped |
| `ko` | Korean | 한국어 | ✅ Shipped |
| `zh` | Chinese (Simplified) | 简体中文 | ✅ Shipped |
| Code | Language | Native Name | Status |
| ------- | -------------------- | ---------------- | ---------- |
| `en` | English | English | ✅ Shipped |
| `vi` | Vietnamese | Tiếng Việt | ✅ Shipped |
| `ja` | Japanese | 日本語 | ✅ Shipped |
| `es` | Spanish | Español | ✅ Shipped |
| `ko` | Korean | 한국어 | ✅ Shipped |
| `zh` | Chinese (Simplified) | 简体中文 | ✅ Shipped |
| `pt-BR` | Portuguese (Brazil) | Português (BR) | ✅ Shipped |
| `id` | Indonesian | Bahasa Indonesia | ✅ Shipped |
Further locales (French, German, Portuguese, Russian, Thai, Arabic) are
tracked in [Roadmap § 5.3](./ROADMAP.md).
The interface language and the output language are chosen separately. The
Output page, Batch and Social can render several output languages at once.
Japanese, Spanish, Korean, Chinese, Portuguese and Indonesian are
AI-translated — see [DISCLAIMER.md](../DISCLAIMER.md).
Further locales (French, German, Russian, Thai, Arabic) are tracked in
[Roadmap § 5.3](./ROADMAP.md). Arabic additionally needs RTL layout work —
see [I18N.md](./I18N.md).
Each language requires:
- `ui.json` — UI labels, buttons, placeholders, error messages
- `templates.json` — Title patterns, description sections, CTA text
- `templates.json` — everything the engine writes: title patterns, description blocks, rig labels, timestamp keywords, pinned comments, CTA text
## 🎮 Game Genres (41 genres)
## 🎮 Game Genres (42 genres)
Forty-one genres feed the title format, the tag pool, and (when configured
Forty-two genres feed the title format, the tag pool, and (when configured
in Settings → Genre Playlists) the pinned-comment playlist recommendation.
The complete list — with icons and bulk-select groups — is in
[Content Inventory](./CONTENT-INVENTORY.md).
A video takes up to **3** genres, picked from a searchable list or with the
All RPGs / All Shooters / All Horror shortcuts. The complete list — with
icons and bulk-select groups — is in [Content Inventory](./CONTENT-INVENTORY.md).
## 🛒 Store Platforms (9 platforms)
## 🛒 Store Platforms (15 stores + publisher site)
| ID | Label | URL Prefix |
|----|-------|-----------|
| `steam` | Steam | `https://store.steampowered.com/app/` |
| `epic` | Epic Games Store | `https://store.epicgames.com/` |
| `ps` | PlayStation Store | `https://store.playstation.com/` |
| `xbox` | Xbox / Microsoft Store | `https://www.xbox.com/games/` |
| `nintendo` | Nintendo eShop | `https://www.nintendo.com/store/` |
| `gog` | GOG | `https://www.gog.com/game/` |
| `itchio` | itch.io | `https://itch.io/` |
| `humble` | Humble Bundle | `https://www.humblebundle.com/store/` |
| `amazon` | Amazon Luna | `https://www.amazon.com/luna/` |
| ID | Label | URL Prefix | Name in tags |
| ------------ | -------------------------- | ------------------------------------------------ | --------------- |
| `steam` | Steam | `https://store.steampowered.com/app/` | Steam |
| `epic` | Epic Games Store | `https://store.epicgames.com/` | Epic Games |
| `ps` | PlayStation Store | `https://store.playstation.com/` | PlayStation |
| `xbox` | Xbox / Microsoft Store | `https://www.xbox.com/games/` | Xbox |
| `nintendo` | Nintendo eShop | `https://www.nintendo.com/store/` | Nintendo Switch |
| `gog` | GOG | `https://www.gog.com/game/` | GOG |
| `itchio` | itch.io | `https://<dev>.itch.io/<game>` | itch.io |
| `humble` | Humble Bundle | `https://www.humblebundle.com/store/` | Humble Bundle |
| `amazon` | Amazon Luna | `https://luna.amazon.com/game/` | Amazon Luna |
| `ea` | EA app | `https://www.ea.com/games/` | EA app |
| `ubisoft` | Ubisoft Store | `https://store.ubisoft.com/` | Ubisoft Connect |
| `battlenet` | Battle.net | `https://shop.battle.net/` | Battle.net |
| `googleplay` | Google Play | `https://play.google.com/store/apps/details?id=` | Android |
| `appstore` | App Store | `https://apps.apple.com/app/` | iOS |
| `meta` | Meta Quest Store | `https://www.meta.com/experiences/` | Meta Quest |
| `publisher` | Publisher / Developer site | any `https://` link | — |
## ☕ Social & Donate Links (12 fields)
EA app, Ubisoft, Battle.net, Google Play, App Store and Meta Quest are new in
v1.0.0. Validation accepts the variants people actually paste (Steam `/sub/`,
`/bundle/` and `s.team` links, regional Nintendo sites, `www.`-less hosts);
Steam links lose their tracking parameters. Each link is marked **paid**,
**free** or **demo**, and the store block's heading switches to "DOWNLOAD THE
GAME" when most links are free or demos.
### Donate
| ID | Label | Prefix |
|----|-------|--------|
| `kofi` | Ko-fi | `https://ko-fi.com/` |
| `patreon` | Patreon | `https://patreon.com/` |
## ☕ Social & Donate Links (22 fields)
### Donate (5)
| ID | Label | Prefix |
| -------------- | --------------- | --------------------------- |
| `kofi` | Ko-fi | `https://ko-fi.com/` |
| `patreon` | Patreon | `https://patreon.com/` |
| `buymeacoffee` | Buy Me a Coffee | `https://buymeacoffee.com/` |
| `paypal` | PayPal | `https://paypal.me/` |
| `streamlabs` | Streamlabs | `https://streamlabs.com/` |
| `paypal` | PayPal | `https://paypal.me/` |
| `streamlabs` | Streamlabs | `https://streamlabs.com/` |
### Social
| ID | Label | Prefix |
|----|-------|--------|
| `github` | GitHub | `https://github.com/` |
| `twitter` | Twitter / X | `https://x.com/` |
| `discord` | Discord | `https://discord.gg/` |
| `twitch` | Twitch | `https://twitch.tv/` |
| `tiktok` | TikTok | `https://tiktok.com/@` |
| `instagram` | Instagram | `https://instagram.com/` |
| `website` | Website | — |
### Social (17)
## 💻 Rig Fields (8 fields)
| ID | Label | Prefix |
| ----------- | ------------- | --------------------------------- |
| `github` | GitHub | `https://github.com/` |
| `youtube` | YouTube | `https://www.youtube.com/` |
| `twitter` | X (Twitter) | `https://x.com/` |
| `discord` | Discord | `https://discord.gg/` |
| `twitch` | Twitch | `https://twitch.tv/` |
| `kick` | Kick | `https://kick.com/` |
| `tiktok` | TikTok | `https://tiktok.com/@` |
| `instagram` | Instagram | `https://instagram.com/` |
| `threads` | Threads | `https://www.threads.com/@` |
| `bluesky` | Bluesky | `https://bsky.app/profile/` |
| `mastodon` | Mastodon | — (full URL including the server) |
| `facebook` | Facebook | `https://facebook.com/` |
| `fb_page` | Facebook Page | `https://facebook.com/` |
| `reddit` | Reddit | `https://www.reddit.com/` |
| `bilibili` | Bilibili | `https://space.bilibili.com/` |
| `telegram` | Telegram | `https://t.me/` |
| `website` | Website | — |
| ID | Label | Example |
|----|-------|---------|
| `cpu` | CPU | Intel i9-14900K / AMD Ryzen 9 7950X |
| `gpu` | GPU | NVIDIA RTX 4090 / AMD RX 7900 XTX |
| `ram` | RAM | 32GB DDR5-6000 |
| `storage` | Storage | 2TB Samsung 990 PRO NVMe |
| `motherboard` | Motherboard | ASUS ROG Maximus Z790 |
| `monitor` | Monitor | LG 27GP950 27" 4K 144Hz |
| `capture` | Capture Software | OBS Studio 30.x |
| `controller` | Controller | DualSense / Xbox Elite Series 2 |
YouTube, Threads, Kick, Reddit and Bilibili are new in v1.0.0; "Twitter / X"
is now "X (Twitter)" (same `twitter` id, so saved links still load).
### Community & Vietnam
- **Community** block — Messenger community, Signal group, Instagram group chat
and Facebook Group links for every language; a Zalo group link for
Vietnamese output only.
- **Donate (Vietnam)** — bank transfer (a list of 37 Vietnamese banks, or
type your own), account number and holder, MoMo and ZaloPay. Rendered only
when the output language is Vietnamese. v1.0.0 added MBV, VCBNeo, Vikki
Bank, Cake by VPBank and Timo; a profile saved with OceanBank, CBBank or
DongA Bank is offered the new name in one click.
## 💻 Rig Fields (10 fields)
Printed in this order, with labels in the output language.
| ID | Label | Input | Example |
| -------------- | ---------------- | ----------------------------------------------------------- | ------------------------------------ |
| `cpu` | CPU | Text with suggestions; names pasted from Windows are tidied | AMD Ryzen 7 9800X3D |
| `gpu` | GPU | Searchable catalog (below) or your own text | NVIDIA GeForce RTX 5080 |
| `ram` | RAM | Size + type (DDR, LPDDR) + speed | 32 GB DDR5-6000 |
| `motherboard` | Motherboard | Text | ASUS ROG Strix X870E-E Gaming |
| `storage` | Storage | Text | 2TB Samsung 990 PRO NVMe |
| `os` | Operating System | Windows / macOS / Linux + version or distro + edition | Windows 11 Pro, Ubuntu 24.04 LTS |
| `monitor` | Monitor | Text | LG 27GP950 27" 4K 144Hz |
| `capture` | Capture Software | Text | OBS Studio 31 |
| `controller` | Controller | Text | DualSense / Xbox Wireless Controller |
| `video_editor` | Video Editor | Dropdown + version | DaVinci Resolve Studio 19.1 |
**GPU catalog (v1.0.0)** — 198 models in 29 groups: NVIDIA GeForce (desktop
and laptop), AMD Radeon (including integrated), Intel Arc and integrated,
Apple M1–M5 and handheld PCs, each printed under its official name ("NVIDIA
GeForce RTX 5080", "AMD Radeon RX 9070 XT", "Apple M4 Pro"). Cards that never
shipped are not listed. Values saved by older versions (Brand › Series ›
Model) are migrated.
## 📄 Output Sections (Description Structure)
Mỗi ngôn ngữ có description structure như sau (tất cả sections optional):
Every block is optional and skipped when empty. In order:
```
1. Intro line (auto-generated from video type + game name)
2. No Commentary tagline
3. ─── Timestamps ─── (if provided)
4. ─── Store Links ─── (if any platform link provided)
5. ─── Video Settings ─── (resolution / FPS / graphics)
6. ─── My Rig ─── (if any rig field provided)
7. ─── Content Warnings ─── (if any selected — 248 IDs across 12 groups)
8. ─── Donate Links ─── (if any provided)
9. ─── Social Links ─── (if any provided)
10. ─── Playlist Link ─── (if provided)
11. ─── Contact Email ─── (if provided)
12. CTA line (Like / Subscribe / Share)
13. Hashtags (3 max, auto-generated)
1. Intro line (video type + game; gacha quests have their own openings)
2. Livestream link / scheduled time (Livestream only)
3. Playthrough notes (run type, difficulty, endings shown, language patch, game version)
4. No Commentary tagline
5. ⏱ Timestamps (keywords translated into the output language)
6. 🎮 Store links (heading depends on paid vs. free / demo links)
7. © Game copyright line (opt-in)
8. 🧪 Playtest / early access (when a playtest link is set)
9. 🖥 Video settings (skipped for games without graphics settings)
10. 💻 My rig
11. 🧩 Mod list (Modded Gameplay only)
12. ⚠️ Content warnings (257 IDs across 13 groups, incl. AI-generated content — v1.2.0)
13. 🛠 Tech notes (25 IDs across 5 groups)
14. Translation-quality note (opt-in; not for English or Vietnamese)
15. 🎁 Sponsor credit (opt-in)
16. 🤝 Sponsors & partners (opt-in)
17. 🎵 Music / sound
18. ☕ Donate links
19. 🏦 Bank transfer / e-wallet (Vietnamese output only)
20. 🔗 Social links
21. 💬 Community
22. ▶️ Playlist link
23. 📧 Contact email(s) — one line, or split by purpose: contact, advertising,
game keys & playtest, copyright / DMCA (v1.1.0)
24. CTA line (Like / Subscribe / Share)
25. © Copyright line (on by default; needs a channel name)
26. 📋 Usage policy (opt-in)
27. Hashtags (1–3, auto-generated)
```
With one output language selected, the Output page shows content warnings,
tech notes and playthrough notes bilingually (English · output language)
unless the output is English; with several languages selected, each tab —
like each Batch row — stays in its own language. An empty channel name drops
the "on …" phrase from every sentence, in all eight languages.
The Output page also shows the thumbnail text, your pinned-comment draft and,
opt-in, a generated pinned-comment template.
## 🔁 Cross-Post Captions (Social tab)
A dedicated **Social** tab re-packages the same editor source that drives the
YouTube description into short-form captions for other platforms — no
re-typing. Each caption is derived live from the current form.
| Platform | Caption limit | Popular hashtags appended |
|----------|--------------|----------------------------|
| TikTok | 4,000 | `#fyp #foryou #foryoupage #gaming #gamingtiktok #gameplay #gamer` |
| Instagram Reels | 2,200 | `#reels #reelsinstagram #gaming #gamingreels #gamer #instagaming #videogames` |
| Facebook Reels | 2,200 | `#reels #facebookreels #fbreels #gaming #gameplay #gamingcommunity #videogames` |
| Platform | Caption limit | Hashtags | Popular hashtags appended |
| --------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------- |
| TikTok | 4,000 | no cap | `#fyp #foryou #foryoupage #gaming #gamingtiktok #gameplay #gamer` |
| YouTube Shorts | 5,000 | up to 5 | `#shorts #gaming #gameplay` |
| Instagram Reels | 2,200 | no cap | `#reels #reelsinstagram #gaming #gamingreels #gamer #instagaming #videogames` |
| Facebook Reels | 2,200 | no cap | `#reels #facebookreels #fbreels #gaming #gameplay #gamingcommunity #videogames` |
| X | 280, **counted the way X counts** | up to 3 | `#gaming` |
| Threads | 500 | 1 | — |
| Bluesky | 300 | up to 3 | `#gaming` |
YouTube Shorts, X, Threads and Bluesky are new in v1.0.0. X's count weighs
CJK characters, Vietnamese letters with diacritics and emoji double.
Each caption pulls, in order: **Title** (quality badge suppressed for
short-form), **My Rig**, **Content Warnings**, **Thanks / sponsor credit**,
**Copyright**, and **hashtags** (game + primary genre + the curated
per-platform popular set, deduplicated case-insensitively).
**Copyright**, and **hashtags** (game, `#GameplayNoCommentary`, primary genre,
then the platform's popular set — deduplicated case-insensitively and capped
per platform).
- **Overflow handling** — when a caption exceeds the platform limit, optional
blocks are dropped in priority order (warnings → copyright → thanks → rig).
@@ -141,114 +251,207 @@ per-platform popular set, deduplicated case-insensitively).
### Tag Pools by Category
| Pool | Triggered By | Sample Output |
|------|-------------|---------------|
| Core | Always | `[game] gameplay`, `[game] no commentary`, `gameplay no commentary` |
| Genre | Genre selection | `horror game no commentary`, `RPG gameplay no commentary` |
| VideoType | Video type | `[game] boss fight`, `[game] speedrun`, `[game] all endings` |
| Platform | Platform field | `[game] PC`, `PC gameplay`, `[game] Steam` |
| Quality | Resolution/FPS | `[game] 4K`, `4K gameplay no commentary`, `[game] 4K 60FPS` |
| Multilingual JA | Always | `[game] ゲームプレイ`, `[game] 実況なし` |
| Multilingual VI | Always | `[game] gameplay không bình luận` |
| Multilingual ES | If ES enabled | `[game] sin comentarios`, `juego de acción` |
| Trending | Always | `[game] 2026`, `best [genre] games 2026` |
| Pool | Triggered By | Sample Output |
| ------------ | --------------------------------- | ------------------------------------------------------------------------ |
| Game name | Always | `[game]` (shortened to fit 30 characters) |
| Core | Always, in the output language | `[game] gameplay`, `[game] no commentary`, `gameplay no commentary` |
| Genre | Each selected genre | `horror game no commentary`, `RPG gameplay no commentary` |
| VideoType | Video type | `[game] boss fight`, `[game] speedrun`, `[game] all endings` |
| Platform | Platform field | `[game] Steam`, `Steam gameplay`, `[game] Steam gameplay` |
| Quality | Resolution / FPS | `[game] 4K`, `4K gameplay no commentary`, `[game] 4K 60fps` |
| Multilingual | Setting on — output language only | `[game] tiếng Việt` (vi), `[game] 日本語` (ja), `[game] en español` (es) |
| Trending | Setting on | `[game] 2026`, `best horror games 2026`, `horror gameplay 2026` |
| Publisher | Publisher / developer set | `[publisher]` |
### Tag Pipeline
1. Collect tags from all applicable pools
2. Deduplicate (Set-based)
3. Priority sort (core first, trending last)
4. Trim to 500 character limit (drop lowest priority first)
5. Output as comma-separated string
1. Collect tags from all applicable pools, in the priority order above
2. Deduplicate case-insensitively; drop any tag over 30 characters
3. Fit to **500 characters the way YouTube counts them** — every tag, plus
the quotes YouTube puts around a tag with a space, plus a comma between
tags. A tag that doesn't fit is skipped and shorter ones after it are
still tried (v1.0.0; the old count missed the quotes)
4. Output as comma-separated string
Game names are cleaned of characters YouTube splits tags on (`,` `;` `|`) and
of ™ / ® / ©.
## ⚡ Faster Data Entry (v1.0.0)
- **Quick start** — at the top of the editor, pick a **channel profile** and
a **game preset** (both remembered). If that would replace fields you
already filled, it asks first. "Update profile" / "Update preset" appears
when the editor no longer matches them.
- **Next part** — same game, next part: the part number goes up by one and
what belonged to the last video (boss, timestamps, endings, pinned comment,
sponsor, …) is cleared.
- **New video, same game** — the same clean-up, without touching the part
number. Applying a preset for another game clears those fields too.
- **Start over** — clears the game and video fields but keeps your channel
(name, contact, social links, rig, donate and community links); the draft
starts in your **Default Output Language**.
- **Paste a store link anywhere** — on the page, in the Game name field or in
the wrong store's field: the link lands in the right store field, sets the
platform when it's the game's first store link, and fills an empty Game
name from the link ("Final Fantasy VII Remake").
- **Game-name suggestions** — the Game name field suggests names from your
presets and history.
- **Title shapes** — the Output page's title alternatives (game first, video
first, quality badge first); "Use this shape" saves one to the title
format.
- **Batch** — Part or Demo part N…M (up to 100 parts) in several languages at
once, continuing from the editor's part number.
- **Save to History** — Ctrl/⌘+S from any page.
Applying a profile, preset or template, Next part, New video, Start over and
a pasted store link can each be undone from the toast they show.
## 🖥 Interface (v1.0.0)
- **App shell** — a collapsible sidebar, a top bar with the output and
interface languages, and on phones a bottom bar (Editor, Output, Batch,
Profiles, More).
- **Command palette** (Ctrl/⌘+K) — go to any page or the Legal Center; copy
the title, description, tags or everything; apply a saved profile, game
preset or template; switch theme, interface language or output language;
open the shortcuts, the wiki or a bug report.
- **Live preview** — the generated title, description and tags beside the
editor form (a sheet on phones), with the same counters and copy rules as
the Output page.
- **YouTube preview** (Output) — where search results cut the title (about
70 characters) and what shows above "…more" (about the first 150
characters of the description).
- **Chapter check** (Timestamps) — whether YouTube will show chapters (first
timestamp at 0:00, at least 3, ascending, each at least 10 seconds long);
**Tidy up** rewrites a pasted list as one `M:SS label` per line.
- **Pages** — Editor, Output, Batch, Social, Playlist; Profiles (profiles,
game presets, templates), History; Settings, Logs, About; the Legal Center.
- Dark and light themes; scrollbars can be hidden (v1.1.0); animated icons
follow the system's _reduce motion_; controls grow on touch screens.
## 💾 Data Persistence
### Profile (saved once, reused always)
```typescript
interface Profile {
id: string; // uuid
name: string; // "Main Channel"
channelName: string;
contactEmail: string;
social: Record<string, string>;
rig: Record<string, string>;
resolution: string;
fps: string;
graphicsPreset: string;
createdAt: string;
updatedAt: string;
}
```
Everything stays on the device: the browser's storage for
`ytgenerator.stream` on the web, the app's own storage on desktop and
Android. There is no account and no server-side copy.
### Game Preset (saved per game, reused for all parts)
```typescript
interface GamePreset {
id: string;
gameName: string;
gameNameLocalized?: Record<string, string>;
genre: Genre;
platform: string;
storeLinks: Record<string, string>;
spoilerWarning: boolean;
matureWarning: boolean;
createdAt: string;
}
```
| Item | What it holds | Where |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **Profile** — the channel | Channel name; contact emails (general, advertising, game keys, copyright); social and donate links; community links; Vietnamese bank / MoMo / ZaloPay details; rig; resolution, FPS and graphics preset; sponsors & partners text | Profiles › Profiles |
| **Game preset** — the game | Game name (+ per-language names); genres; platform; store links and their type (paid / free / demo); publisher / developer; content warnings; language patch; game version; art style; "no graphics settings"; series playlist | Profiles › Game presets |
| **Template** — the whole form | Every editor field | Profiles › Templates |
| **History** | One entry per video — game, video type, language, genres, title, description, tags. Saving the same video again updates its entry (v1.0.0) | History |
| **Draft** | The editor form, saved as you type | — |
### History Entry (auto-saved per generation)
```typescript
interface HistoryEntry {
id: string;
gameName: string;
videoType: VideoType;
language: SupportedLanguage;
title: string;
description: string;
tags: string;
createdAt: string;
}
```
The field lists live in `src/config/library-fields.ts`. Profiles, presets and
templates export and import as JSON; History exports as **CSV** or JSON.
Backups and exports carry the date in their file names
(`ytdescgen-backup-2026-09-30.json`).
### Backup & restore (v1.0.0)
In **Settings › Backup & restore**:
- **Back up** everything — or chosen parts: profiles, game presets,
templates, history, settings, the current draft — to one JSON file.
Settings never carry your legal consent or which panels are open.
- **Restore** from a file, or drop the file on the section. Files from every
earlier version are read (v0.15–v0.38 exports, pre-v0.15 arrays, the old
desktop data file) and go through the same migrations the app runs on its
own data.
- **Preview before anything changes**: each item is _new_, _already here_ or
_different_. **Merge** adds what's new and, for items that differ, keeps
the newer one or both; **Replace** makes each chosen section match the
file. One step, with **Undo**.
- **Automatic backups (desktop)** — the newest ten in the app's data folder,
written after the library changes and before every restore. Restore any of
them from the same section, or **Back up now**.
## ⌨️ Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Ctrl+Enter` | Generate output (switch to Output tab) |
| `Ctrl+Shift+C` | Copy all (title + description + tags) |
| `Ctrl+Shift+T` | Copy title only |
| `Ctrl+Shift+D` | Copy description only |
| `Ctrl+Shift+G` | Copy tags only |
| `Ctrl+S` | Save current form as draft |
| `Ctrl+P` | Quick-switch profile |
| `Ctrl+/` | Show keyboard shortcuts |
| `Escape` | Close modal / clear selection |
`Ctrl` on Windows / Linux / Android, `⌘` on a Mac — both work everywhere.
| Shortcut | Action |
| ---------------------------- | --------------------------------------------------------------- |
| `Ctrl/⌘+K` | Command palette |
| `Ctrl/⌘+Enter` or `Ctrl/⌘+G` | Generate (switch to Output) |
| `Ctrl/⌘+Shift+C` | Copy All — same limits and Strict Mode rules as the Output page |
| `Ctrl/⌘+S` | Save the current output to History |
| `Ctrl/⌘+B` | Collapse / expand the sidebar |
| `Ctrl/⌘+/` or `?` | Show keyboard shortcuts (`?` only outside text fields) |
| `Escape` | Close modal |
## 🔧 Settings
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| Theme | dark / light | dark | App color theme |
| Default UI Language | SupportedLanguage | en | Language for app interface |
| Default Output Language | SupportedLanguage | en | Default language for generated output |
| Default Genre | Genre | action | Pre-selected genre on new session |
| Auto-save Draft | boolean | true | Auto-save form state to localStorage |
| Show Character Count | boolean | true | Display char counters on output |
| Compact Tag Display | boolean | false | Tags as comma list vs chip display |
| History Limit | number | 100 | Max history entries to keep |
| Include Multilingual Tags | boolean | true | Add JA/VI tags to tag output |
| Include Trending Tags | boolean | true | Add year-based trending tags |
| Hashtag Count | 1-3 | 3 | Number of hashtags to generate |
| Setting | Type | Default | Description |
| -------------------------- | ------------------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| Theme | dark / light | dark | App color theme |
| Hide scrollbars | boolean | false | v1.1.0. No scrollbar anywhere in the app; wheel, touch and keyboard still scroll |
| App Language | SupportedLanguage | browser-detected | Language of the interface |
| Default Output Language | SupportedLanguage | browser-detected | Language a new draft starts in (first run, Start over) |
| Show Character Count | boolean | true | Display char counters on output. **Does not** affect copy blocking |
| Compact Tag Display | boolean | false | Tags as comma list vs chip display |
| Copy All includes the tags | boolean | false | v1.0.0. Copy All copies title, description, then tags |
| **Strict Mode** | boolean | **false** | v0.35.0. Blocks Generate / Copy / Export while any field has a hard error |
| Show quality badge | boolean | true | `[2K 60FPS]`-style badge in the title when resolution or FPS is above the defaults |
| Title order | game first / video first | game first | v1.0.0. "Hades — Part 3" or "Part 3 — Hades" |
| Quality badge position | prefix / middle / suffix | middle | Where the badge sits in the title |
| Segment separator | em dash / hyphen / colon / pipe | em dash | Characters come from each locale |
| Badge case | upper / lower | upper | "2K" or "2k" |
| Include Multilingual Tags | boolean | true | Add tags in the output language |
| Include Trending Tags | boolean | true | Add year-based trending tags |
| Hashtag Count | 1-3 | 3 | Number of hashtags to generate |
| Genre Playlists | map | `{}` | One playlist URL per genre (42), collapsed by default |
| History Limit | 10–500 | 100 | Max history entries to keep |
| Log Retention | 1–90 days | 7 | Log files older than this are deleted at boot |
"Browser-detected" means the browser's language when it is one of the eight,
otherwise English. `Default Genre` and `Auto-save Draft` were removed in
v0.22.0 and v0.3 respectively — the draft autosaves unconditionally, so the
toggle was dead. **Backup & restore** is the last section of the page.
### Description toggles
`showCopyright` · `showUsagePolicy` · `showSponsorCredit` · `showGameCopyright`
· `showThirdPartyAds` · `showTranslationQuality` · `splitContactEmail` ·
`showPinnedCommentTemplate` · `pinnedCommentIncludeAskNextGame` ·
`pinnedCommentIncludeGenrePlaylist`
On by default: `showCopyright` and `pinnedCommentIncludeAskNextGame`.
## 🛡 Guardrails
| Mechanism | Scope |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Character limits** | Title 100 / description 5,000 / tags 500 (tags counted the way YouTube counts them). Since v1.0.0 only the field that is over can't be copied; the others still can. Copy All is blocked when the title or description is over — or the tags, when Copy All includes them. In Batch an over-limit part blocks only its own field; Copy All Batch is blocked when any part is over |
| **Characters YouTube rejects** | The Output page warns when the title or description contains `<` or `>` |
| **Field limits** | Hard `maxLength` per category: URL 200, email 320, short name 100, label 300, long text 2,000, timestamps 5,000, numeric 10. Imported values are clamped too |
| **Strict Mode** | Opt-in. Blocks Generate / Copy / Export on hard errors only; warnings (e.g. a working link on a non-standard prefix) never block. Log export is exempt |
Emails are capped at **three per field**, enforced on the increase so an
over-cap legacy value stays editable, and a domain without a TLD is rejected.
With the contact email split by purpose, the advertising, game-keys and
copyright addresses also need a purpose word before `@` — `sponsors@…`,
`keys@…`, `dmca@…` or `name+dmca@gmail.com` (v1.1.0; the words are in
`src/config/contact-emails.ts`). Invalid input is never committed to the
store, so a malformed URL cannot reach the generated description whether
Strict Mode is on or off.
## 🖥 Desktop App Features (Tauri)
| Feature | Description |
|---------|-------------|
| System Tray | Minimize to tray, quick access |
| Native Clipboard | Direct clipboard write (no browser permission) |
| File Export | Save outputs as `.txt` / `.json` to file system |
| File Import | Import profiles/presets from JSON file |
| Auto-update | Tauri updater (check GitHub releases) |
| Offline | Full functionality without internet |
| Global Hotkey | System-wide hotkey to open app (optional) |
| Feature | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| System Tray | One tray icon (the app icon) with Show / Quit; left-click shows the window; closing the window hides it to the tray |
| Single instance | Launching the app again brings the running window forward |
| Files | Export and import through native Save / Open dialogs run from Rust — text formats only (`json`, `jsonl`, `txt`, `csv`, `md`), imports capped in size. The webview never handles a file path (v1.0.0) |
| Automatic backups | The newest ten in the app's data folder (see Backup & restore) |
| Logs | One log file per day in the app's data folder, pruned by Log Retention |
| Offline | Full functionality without internet; no analytics, no Turnstile check |
| Window | Resizable, 1280×820 by default |
| Installer | The Windows MSI / NSIS installers show the license page |
There is no auto-updater yet — new versions come from
[Releases](https://github.com/poli0981/youtube-generator/releases).
## 📱 Android App (v0.29)
@@ -256,61 +459,67 @@ An installable, sideloadable `.apk` built from the same Tauri 2 codebase — no
separate mobile project. Build with `cargo tauri android build --apk`; see
[PACKAGING.md](./PACKAGING.md#android-apk-packaging).
| Feature | Description |
|---------|-------------|
| Same codebase | One Tauri 2 project produces web, desktop, and Android |
| Min version | Android 11+ (minSdk 30); `targetSdk` 36 (Android 16) |
| Tested | Android 11 → 16 (emulators); real device on Android 12 |
| Signed APK | Self-signed release APK for sideloading; CI publishes it to GitHub Releases |
| Responsive UI | Drawer navigation, touch-sized controls, safe-area insets |
| File export | Routed through the WebView download (lands in Downloads) on Android |
| Persistence | App-private data dir (`appDataDir()`) + localStorage; works offline |
| No tray | Desktop-only tray / single-instance are `#[cfg(desktop)]`-gated out |
| Feature | Description |
| ------------- | ---------------------------------------------------------------------------------------------- |
| Same codebase | One Tauri 2 project produces web, desktop, and Android |
| Min version | Android 11+ (minSdk 30); `targetSdk` 36 (Android 16) |
| Tested | Android 11 → 16 (emulators); real device on Android 12 |
| Signed APK | Self-signed release APK for sideloading; CI publishes it to GitHub Releases |
| Responsive UI | Bottom tab bar (Editor, Output, Batch, Profiles, More), touch-sized controls, safe-area insets |
| File export | Routed through the WebView download (lands in Downloads) on Android |
| Persistence | App-private storage; works offline |
| No tray | Desktop-only tray / single-instance / automatic backups are left out |
## 🚦 Error Pages & Offline (v0.27)
A single reusable, fully-localized `ErrorPage` component (`src/components/errors/`)
backed by a pure kind→meta config (`src/config/error-pages.ts`). All copy ships
in every locale (en/vi/ja/es/ko/zh).
in all eight locales.
| Kind | Route | Trigger |
|------|-------|---------|
| 404 Not found | catch-all `*` | A mistyped / dead hash route (live — was a blank screen before) |
| 403 Forbidden | `/#/403` | Designed page, route-reachable for future triggers |
| 419 Expired | `/#/419` | Designed page, route-reachable for future triggers |
| 500 Server error | `/#/500` | Designed page (covers 408/5xx), route-reachable for future triggers |
| Offline | `/#/offline` + banner | `navigator.onLine` flips false |
| Runtime crash | — | A render error caught by `ErrorBoundary` (shared `contained` variant) |
Routes are real paths on the web (`/403`) and hash routes in the desktop and
Android apps (`/#/403`). Old `/#/…` links on the web still work — they are
rewritten to the path form (v1.0.0).
| Kind | Route | Trigger |
| ---------------- | ------------------- | --------------------------------------------------------------------- |
| 404 Not found | catch-all `*` | A mistyped / dead route (live — was a blank screen before) |
| 403 Forbidden | `/403` | Designed page, route-reachable for future triggers |
| 419 Expired | `/419` | Designed page, route-reachable for future triggers |
| 500 Server error | `/500` | Designed page (covers 408/5xx), route-reachable for future triggers |
| Offline | `/offline` + banner | `navigator.onLine` flips false |
| Runtime crash | — | A render error caught by `ErrorBoundary` (shared `contained` variant) |
- **Full-screen, no shell** — dedicated error routes render outside `AppShell`
(no Sidebar/Header), with Home / Back / (Reload) / Report-a-bug actions.
- **Non-blocking offline banner** — a dismissible bottom strip; the app stays
fully usable offline, and a toast confirms when the connection returns.
## ⚖️ Legal & Consent (v0.28)
## ⚖️ Legal & Consent (v0.28, reworked in v1.0.0)
A first-run **consent gate** (`src/components/ConsentGate.tsx`, backed by the
pure `src/config/legal.ts`) blocks the app until the user reviews the legal
documents and ticks one "I agree" checkbox.
| Aspect | Behaviour |
|--------|-----------|
| Documents | Terms of Use, Privacy Policy, Disclaimer, License — linked to the GitHub-hosted copies (open in the browser); also surfaced in About → Legal |
| Acceptance | One combined checkbox; Continue disabled until checked |
| Persistence | Stored in the existing settings record (`legalConsentVersion` + timestamp) — **no cookie, no new storage key** |
| Re-prompt | Version-based — only when `CURRENT_TERMS_VERSION` is raised (terms changed); also re-shows in fresh / incognito storage |
| Desktop | Same in-app gate on Windows/macOS/Linux, **plus** a license-acceptance page in the Windows MSI/NSIS installer (`bundle.licenseFile`) |
| Layout | Full-screen, non-dismissible, theme- and locale-aware (all 6 languages) |
| Aspect | Behaviour |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Documents | Terms of Use, Privacy Policy, Disclaimer, License (the four you agree to), plus Third-party notices, Security, Notice and Code of Conduct — rendered from the repository's files at build time into the in-app **Legal Center** (offline on desktop and Android; linked from the sidebar, About and the command palette). The Disclaimer also has a Vietnamese version |
| On the web | The same documents are public pages at `/legal/<doc>` (e.g. `/legal/privacy`), readable before the Turnstile check |
| Acceptance | One combined checkbox; Continue disabled until checked; each document opens in the Legal Center; language and theme can be changed on the gate |
| Persistence | `legalConsentVersion` + timestamp in the settings record. On the web, agreeing on the Turnstile page sets a `ytg_terms` cookie the app reads, so a web visitor sees one blocking screen, not two |
| Re-prompt | Version-based — only when `CURRENT_TERMS_VERSION` is raised (terms changed); also re-shows in fresh / incognito storage. Version **2** since v1.0.0 (Cloudflare hosting, Turnstile and Web Analytics in the Privacy Policy) |
| Desktop | Same in-app gate on Windows/macOS/Linux, **plus** a license-acceptance page in the Windows MSI/NSIS installer (`bundle.licenseFile`) |
| Layout | Full-screen, non-dismissible, theme- and locale-aware (all 8 languages) |
## 🔌 Future Extension Points
| Extension | Description | Effort |
|-----------|-------------|--------|
| VS Code Extension | Command palette → generate description | Medium |
| CLI Tool | `ytdesc generate --game "Elden Ring" --type full --lang en` | Low |
| Browser Extension | Right-click on YouTube Studio → auto-fill | High |
| YouTube API | Auto-apply description to video via API | High |
| Template Marketplace | Share/import community templates | Medium |
| AI Tag Suggestions | Use game name to suggest trending tags | Medium |
| Thumbnail Text | Generate text overlay suggestions for thumbnails | Low |
| Multi-channel | Support multiple YouTube channels per profile | Low |
See [ROADMAP.md](./ROADMAP.md) for the post-1.0 backlog.
| Extension | Description | Effort |
| -------------------- | ----------------------------------------------------------- | ------ |
| VS Code Extension | Command palette → generate description | Medium |
| CLI Tool | `ytdesc generate --game "Elden Ring" --type full --lang en` | Low |
| Browser Extension | Right-click on YouTube Studio → auto-fill | High |
| YouTube API | Auto-apply description to video via API | High |
| Template Marketplace | Share/import community templates | Medium |
| AI Tag Suggestions | Use game name to suggest trending tags | Medium |
| Thumbnail Text | Generate text overlay suggestions for thumbnails | Low |
+100
View File
@@ -0,0 +1,100 @@
# Hosting — ytgenerator.stream
How the web app is built, deployed and protected. The desktop and Android apps don't use any of this.
## Overview
| Piece | Where |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Domain | `ytgenerator.stream`, on Cloudflare (DNS, TLS, HSTS preload at the zone edge) |
| Hosting | Cloudflare Worker **`youtube-generator`** with static assets from `dist/` |
| Build & deploy | **Workers Builds**, connected to this repository in the Cloudflare dashboard. Every push to `main` builds and deploys to production; other branches get preview versions. There is **no GitHub Actions deploy workflow** |
| Configuration | [`wrangler.jsonc`](../wrangler.jsonc) — the only Cloudflare file in the repo |
| Worker code | [`worker/`](../worker) — the Turnstile gate, the legal pages route, security headers |
| Build-time web extras | [`build-plugins/web-only.ts`](../build-plugins/web-only.ts) (Web Analytics beacon, `security.txt`) and [`build-plugins/legal-docs.ts`](../build-plugins/legal-docs.ts) (legal pages) |
GitHub Pages (`poli0981.github.io/youtube-generator`) is retired. Until 2026-11-29 it serves only a moving notice from [`migration-page/`](../migration-page), published by hand with the `pages-migration.yml` workflow; issue #177 tracks removing it.
## Request flow
`wrangler.jsonc` sends every request **through the Worker first**, except content-hashed build output (`/assets/*`) and the public files that browsers, crawlers and the manifest fetch without cookies (icons, `favicon`, `robots.txt`, `sitemap.xml`, `manifest.webmanifest`, `/.well-known/*`, `/licenses/*`, `theme-init.js`, `404.html`). Those are served straight from the assets with the headers in [`public/_headers`](../public/_headers).
The Worker ([`worker/router.ts`](../worker/router.ts)):
| Path | Response |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /__gate/verify` | Verifies a Turnstile token server-side with `TURNSTILE_SECRET` (success, hostname, `action === "enter"`, age ≤ 300 s), then sets the gate cookie and the terms cookie |
| `GET /__gate/status` | `204` when the gate cookie is valid — lets the gate page detect a browser that refuses cookies instead of looping |
| `/legal`, `/legal/<doc>` | The prerendered legal pages — always public, so the Terms and Privacy Policy can be read before agreeing (`?lang=vi` for the Vietnamese pages that exist) |
| anything else | Gate cookie valid → the file, or the app shell for routes (fetched as `/`, so deep links survive); otherwise → the gate page for documents and `403` for other requests |
`not_found_handling` is `404-page`, **not** the SPA fallback: with the SPA fallback, any path excluded from the Worker would be answered with `index.html` without passing the gate.
### Cookies
| Cookie | Set by | Purpose |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__Host-ytg_gate` | `/__gate/verify` | `v1.<expiry>.<UA hash>.<HMAC>` — HttpOnly, Secure, SameSite=Lax, 24 h (`GATE_TTL_SECONDS`). The HMAC key is derived from `TURNSTILE_SECRET`, so there is no second secret |
| `ytg_terms` | `/__gate/verify` | The terms version the visitor agreed to on the gate page; the app reads it so a web visitor sees one blocking screen, not two |
If `TURNSTILE_SECRET` is missing the gate **fails open** (the site stays up and the Worker logs an error) rather than locking everyone out.
### Headers
`_headers` does not apply to responses the Worker creates, so [`worker/headers.ts`](../worker/headers.ts) sets them itself: a CSP per page type (the app shell allows the Web Analytics beacon; the gate page uses a nonce + `strict-dynamic`; legal pages allow no script at all), `nosniff`, `Referrer-Policy`, `Permissions-Policy`, `Cross-Origin-Opener-Policy`, `Cross-Origin-Resource-Policy` and `X-Frame-Options`. A test keeps the Worker baseline and `_headers` identical. **HSTS is not repeated** — the zone edge already sends `max-age=31536000; includeSubDomains; preload`.
### Web-only build extras
- **Cloudflare Web Analytics**: the beacon snippet is injected into `index.html` only for the web build — never in `npm run dev` or the Tauri builds.
- **`/.well-known/security.txt`** (RFC 9116) is regenerated on every build, so `Expires` is always about six months ahead.
- **Legal pages** are rendered from the repository's Markdown at build time, to static `/legal/*.html` and to a lazy chunk for the in-app Legal Center.
## Configuration and secrets
| Name | Kind | Where |
| -------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `TURNSTILE_SITE_KEY` | public var | `wrangler.jsonc` |
| `GATE_TTL_SECONDS` | public var | `wrangler.jsonc` |
| `TURNSTILE_SECRET` | **Secret** | Cloudflare dashboard (Worker › Settings › Variables and Secrets) or `npx wrangler secret put TURNSTILE_SECRET`. Never committed |
It must be a **Secret**, not a plain-text variable: `wrangler deploy` removes plain-text variables that `wrangler.jsonc` doesn't declare, and keeps secrets.
The custom domain is declared in `routes` because `wrangler deploy` detaches any custom domain that isn't listed.
## Dashboard settings (one-time)
These live in Cloudflare, not in the repository:
1. **Workers Builds** — build command empty (`wrangler.jsonc` runs `npm run build`), deploy command `npx wrangler deploy`, non-production deploy command `npx wrangler versions upload`. Root directory `/`; Node comes from `.node-version`.
2. **Turnstile widget** — hostname `ytgenerator.stream` (add the `workers.dev` subdomain if preview URLs should pass the gate).
3. **Web Analytics** — the manual beacon is used; turn off _automatic setup_ for the hostname so visits aren't counted twice.
4. **Redirect rule** — `www.ytgenerator.stream/*` → `concat("https://ytgenerator.stream", http.request.uri.path)`, 301, preserving the query string.
5. **HSTS** — enabled at the zone with `includeSubDomains` and `preload`.
## Local development
```bash
cp .dev.vars.example .dev.vars # Cloudflare's public Turnstile TEST keys only
npm run build
npm run cf:dev # wrangler dev: the Worker + dist/ on http://localhost:8787
npm run cf:check # wrangler deploy --dry-run: validates config and bundles the Worker
```
The test keys always pass. Never put the real secret in a file. Worker tests run with the rest (`npm run test:run`, `tests/worker/`).
## Releases, previews and rollback
- A merge to `main` is a production deploy. CI's required `check` job already ran `npm run build` and `npm run cf:check` on the pull request.
- Branch builds upload a **preview version** (`preview_urls: true`); preview URLs pass the gate only if their hostname is allowed in the Turnstile widget.
- **Rollback**: Cloudflare dashboard › the Worker › Deployments › pick an earlier version, or `npx wrangler rollback`. Rolling back the Worker also rolls back its assets.
- Each deploy posts a **Workers Builds** check run on the merge commit in GitHub; open its details link for the build log.
## Checking production
```bash
curl -sI https://ytgenerator.stream/ # gate page (no cookie) with the gate CSP
curl -sI https://ytgenerator.stream/assets/<hash>.js # immutable caching
curl -s https://ytgenerator.stream/.well-known/security.txt
curl -sI https://ytgenerator.stream/legal/privacy # public, script-free CSP
curl -sI https://www.ytgenerator.stream/x?y=1 # 301 to https://ytgenerator.stream/x?y=1
```
+282 -179
View File
@@ -8,140 +8,154 @@
YTDescGen has **two independent language contexts**:
1. **UI Language** — The app interface (buttons, labels, tooltips). Controlled by `SettingsStore.defaultLanguage`. Affects how the app *looks*.
2. **Output Language** — The generated title/description/tags. Controlled by `EditorStore.language`. Affects what the app *produces*.
1. **UI Language** — the app interface (buttons, labels, tooltips). Stored as `appLanguage` in the settings store (`src/store/settings-store.ts`); changed from the top bar, Settings or the command palette. Affects how the app _looks_.
2. **Output Language** — the generated title/description/tags. Stored as `language` in the editor store (`src/store/editor-store.ts`), per draft; a new draft starts in **Settings › Default Output Language**. Affects what the app _produces_. The Output page, Batch and Social can also render several output languages at once.
These are independent: a Vietnamese user can browse the app in Vietnamese (UI) while generating descriptions in Japanese (output).
These are independent: a Vietnamese user can browse the app in Vietnamese (UI) while generating descriptions in Japanese (output). Both defaults follow the browser's language when it is one of the eight, otherwise English.
## Locales (8)
| Code | Language | Authoring |
| ------- | -------------------- | ----------------------------------------------------- |
| `en` | English | Source locale; the only one bundled in the main chunk |
| `vi` | Vietnamese | Reviewed by the maintainer, a native speaker |
| `ja` | Japanese | AI-translated, not native-reviewed |
| `es` | Spanish | AI-translated, not native-reviewed |
| `ko` | Korean | AI-translated, not native-reviewed |
| `zh` | Chinese (Simplified) | AI-translated, not native-reviewed |
| `pt-BR` | Portuguese (Brazil) | AI-translated, not native-reviewed |
| `id` | Indonesian | AI-translated, not native-reviewed |
The authoring status of each locale is recorded in [DISCLAIMER.md](../DISCLAIMER.md).
## Two Namespaces
| Namespace | File | Holds | Rendered in |
| ----------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `ui` | `ui.json` | Everything the interface shows | the UI language |
| `templates` | `templates.json` | Everything the engine writes: title patterns, description blocks, rig labels (`description.rigLabels`), timestamp keywords (`timeline.keywords`), pinned comments, playlist copy, hashtags | the output language |
**Rule: generated text lives in `templates.json`.** A sentence or label the
engine writes into a title, description or caption is looked up in
`templates.json`, in the output language, through the `t` the engine is
given (`i18n.getFixedT(language, "templates")`, see
`src/hooks/use-generated-output.ts`) — it is never typed into
`src/engine/`. v1.0.0 moved the rig labels there (`description.rigLabels.*`);
they used to print as English field names in every language.
What stays in code is per-language data that isn't a sentence:
- the tag pools `CORE_TAGS_BY_LANG` and `MULTILINGUAL_TAGS` in `src/engine/tag-generator.ts` (search terms), and
- the patterns in `src/engine/channel-phrase.ts` that remove the words going with an empty channel name ("on", "trên kênh", "による"…).
Both are typed `Record<SupportedLanguage, …>`, so a new language is a compile
error until it has an entry — see Steps 5 and 6.
## File Structure
```
src/i18n/
├── index.ts # i18next init + SUPPORTED_LANGUAGES (en eager, others lazy-loaded)
├── locales/
│ ├── _schema.json # JSON Schema defining all required keys
│ ├── en/
│ │ ├── ui.json # UI strings (buttons, labels, errors, tooltips)
│ │ └── templates.json # Generated content (title, description patterns)
│ ├── vi/
│ │ ├── ui.json
│ │ └── templates.json
│ ├── ja/
│ │ ├── ui.json
│ │ └── templates.json
│ └── es/ # Example: adding Spanish
│ ├── ui.json
│ └── templates.json
└── locales/
├── _schema.json # Every required key, per namespace
├── en/
│ ├── ui.json # UI strings (buttons, labels, errors, tooltips)
│ └── templates.json # Generated content (titles, description blocks, …)
├── vi/
├── ja/
├── es/
├── ko/
├── zh/
├── pt-BR/
└── id/ # Each with the same ui.json + templates.json
```
`_schema.json` lists, for each object path in each namespace, the keys it
must contain — an excerpt:
```json
{
"ui": {
"sidebar": ["expand", "collapse"]
},
"templates": {
"title.separators": ["emDash", "hyphen", "colon", "pipe"]
}
}
```
Adding or removing a key means editing `_schema.json` **and** all 8 locales.
## Adding a New Language — Checklist
The examples use French (`fr`), one of the locales on the
[roadmap](./ROADMAP.md).
### Step 1: Create locale files
```bash
# Generate empty locale from schema
npm run generate:locale -- --lang es
# Generate empty locale from the English source
npm run generate:locale -- --lang fr
# This creates:
# src/i18n/locales/es/ui.json (all keys, empty values)
# src/i18n/locales/es/templates.json (all keys, empty values)
# src/i18n/locales/fr/ui.json (all keys, empty values)
# src/i18n/locales/fr/templates.json (all keys, empty values)
# Prefer editing in place over working from blanks? Pre-fill with English:
npm run generate:locale -- --lang fr --copy-english
# Overwrite an existing locale directory:
npm run generate:locale -- --lang fr --force
```
The output is key-for-key identical to English, so `npm run validate:locales`
passes the moment the files are written — it checks key parity, not whether the
values were actually translated.
Or copy from English and translate:
```bash
cp -r src/i18n/locales/en src/i18n/locales/es
cp -r src/i18n/locales/en src/i18n/locales/fr
```
### Step 2: Translate ui.json
```jsonc
// src/i18n/locales/es/ui.json
What a finished file looks like — an excerpt of
`src/i18n/locales/es/ui.json` (locale files are plain JSON: no comments, no
trailing commas):
```json
{
"app": {
"title": "Generador de Descripción YT",
"subtitle": "Motor de plantillas Gameplay No Commentary"
},
"tabs": {
"editor": "✏️ Editor",
"output": "📄 Resultado",
"profiles": "💾 Perfiles",
"history": "📜 Historial",
"settings": "⚙️ Ajustes",
"batch": "📦 Lote"
},
"editor": {
"videoType": "Tipo de Video",
"language": "Idioma",
"genre": "Género del Juego",
"gameName": "Nombre del Juego",
"channelName": "Nombre del Canal",
"platform": "Plataforma",
"resolution": "Resolución",
"fps": "FPS",
"graphics": "Gráficos",
"timestamps": "Marcas de Tiempo",
"storeLinks": "Enlaces de Tienda",
"rig": "Mi PC",
"social": "Redes Sociales y Donaciones",
"warnings": "Advertencias",
"spoilerWarning": "Advertencia de Spoiler",
"matureWarning": "Contenido para Adultos (18+)",
"playlistLink": "Enlace de Lista de Reproducción",
"contactEmail": "Correo de Contacto"
"editor": "Editor",
"output": "Resultado",
"profiles": "Perfiles",
"history": "Historial",
"settings": "Ajustes",
"batch": "Lote",
"social": "Redes",
"playlist": "Playlist",
"logs": "Registros",
"about": "Acerca de",
"reportBug": "Reportar bug"
},
"output": {
"title": "📌 Título",
"description": "📝 Descripción",
"tags": "🏷 Etiquetas",
"title": "Título",
"description": "Descripción",
"tags": "Etiquetas",
"copyTitle": "Copiar Título",
"copyDescription": "Copiar Descripción",
"copyTags": "Copiar Etiquetas",
"copyAll": "📋 Copiar Todo",
"copied": "✓ ¡Copiado!",
"copyAll": "Copiar Todo",
"copied": "¡Copiado!",
"charCount": "{{count}}/{{limit}}"
},
"profiles": {
"saveProfile": "Guardar Perfil",
"loadProfile": "Cargar",
"deleteProfile": "Eliminar",
"profileName": "Nombre del Perfil",
"noProfiles": "No hay perfiles guardados.",
"gamePresets": "Preajustes de Juegos"
},
"common": {
"save": "Guardar",
"cancel": "Cancelar",
"delete": "Eliminar",
"confirm": "Confirmar",
"export": "Exportar",
"import": "Importar",
"reset": "Restablecer",
"search": "Buscar"
},
"videoTypes": {
"full": "Gameplay Completo",
"part": "Gameplay Parte",
"boss": "Pelea de Jefe",
"boss_nohit": "Jefe Sin Golpes",
"ending": "Final / Todos los Finales",
"speedrun": "Speedrun",
"100percent": "100% Completado",
"dlc": "Contenido DLC",
"newgame_plus": "New Game+",
"challenge": "Desafío",
"side_quest": "Misiones Secundarias",
"secret": "Secretos / Ocultos",
"comparison": "Comparación de Gráficos",
"guide": "Guía Silenciosa"
}
}
```
### Step 3: Translate templates.json
```jsonc
// src/i18n/locales/es/templates.json
An excerpt of `src/i18n/locales/es/templates.json`:
```json
{
"title": {
"separator": " — ",
@@ -150,71 +164,96 @@ cp -r src/i18n/locales/en src/i18n/locales/es
"full": "",
"part": "Parte {{partNumber}}",
"boss": "{{bossName}} Pelea de Jefe",
"boss_nohit": "{{bossName}} Jefe Sin Golpes",
"ending": "Final",
"speedrun": "Speedrun",
"100percent": "100%",
"dlc": "{{dlcName}} DLC",
"newgame_plus": "New Game+",
"challenge": "Desafío {{challengeName}}",
"side_quest": "Misiones Secundarias",
"secret": "Secretos",
"comparison": "Comparación",
"guide": "Guía"
"dlc": "{{dlcName}} DLC"
}
},
"description": {
"intro": {
"full": "Este video presenta el gameplay completo de {{gameName}} en {{channelName}}.",
"part": "Este video presenta la Parte {{partNumber}} de {{gameName}} en {{channelName}}.",
"boss": "Este video presenta la pelea de jefe {{bossName}} de {{gameName}} en {{channelName}}.",
"boss_nohit": "Este video presenta la pelea de jefe {{bossName}} (sin golpes) de {{gameName}} en {{channelName}}.",
"ending": "Este video presenta el final de {{gameName}} en {{channelName}}.",
"speedrun": "Este video presenta un speedrun de {{gameName}} en {{channelName}}.",
"100percent": "Este video presenta el 100% completado de {{gameName}} en {{channelName}}.",
"dlc": "Este video presenta el DLC {{dlcName}} de {{gameName}} en {{channelName}}.",
"newgame_plus": "Este video presenta el New Game+ de {{gameName}} en {{channelName}}.",
"challenge": "Este video presenta el desafío {{challengeName}} de {{gameName}} en {{channelName}}.",
"side_quest": "Este video presenta las misiones secundarias de {{gameName}} en {{channelName}}.",
"secret": "Este video presenta los secretos y contenido oculto de {{gameName}} en {{channelName}}.",
"comparison": "Este video compara los gráficos de {{gameName}} en {{channelName}}.",
"guide": "Este video es una guía silenciosa de {{gameName}} en {{channelName}}."
"part": "Este video presenta la Parte {{partNumber}} de {{gameName}} en {{channelName}}."
},
"noCommentaryLine": "Sin comentarios — gameplay puro para tu disfrute.",
"noCommentaryLine": "Sin Comentarios — gameplay puro para tu disfrute.",
"sections": {
"timestamps": "⏱ MARCAS DE TIEMPO",
"storeLinks": "🎮 OBTENER EL JUEGO",
"videoSettings": "🖥 AJUSTES DE VIDEO: {{settings}}",
"rig": "💻 MI PC",
"spoilerWarning": "⚠️ ADVERTENCIA DE SPOILER: Este video contiene spoilers. ¡Míralo bajo tu propio riesgo!",
"matureWarning": "🔞 CONTENIDO PARA ADULTOS (18+): Contiene violencia / lenguaje fuerte / contenido gráfico.",
"playlist": "▶️ Ver la serie completa: {{link}}",
"contact": "📧 Consultas comerciales: {{email}}",
"rig": "💻 MI EQUIPO",
"cta": "👍 Me gusta | 🔔 Suscríbete | ↗️ Comparte"
},
"rigLabels": {
"cpu": "CPU",
"gpu": "GPU",
"os": "Sistema Operativo"
}
},
"tags": {
"multilingual": [
"{{gameName}} sin comentarios",
"{{gameName}} gameplay completo",
"juego de acción sin comentarios"
]
"timeline": {
"keywords": {
"chapter": "Capítulo {{n}}",
"boss": "Jefe {{n}}",
"final_boss": "Jefe Final",
"credits": "Créditos"
}
}
}
```
- Keep every `{{variable}}` exactly as it is; only the text around it is translated.
- Sentences that name the channel (`{{channelName}}`) must still read naturally when the channel phrase is removed — see Step 5.
- Don't use i18next plural suffixes (`_one`, `_other`, …). Languages need different plural forms, so the key sets would differ between locales and `validate:locales` would fail. Write count-neutral text instead (`"{{n}} damaged item(s) skipped"`).
### Step 4: Register the language
Registering a locale touches several files, and two of them fail **silently**
if missed. `tests/i18n/locale-registration.test.ts` guards the picker list
against the locale folders on disk, in both directions.
```typescript
// src/i18n/index.ts — add to SUPPORTED_LANGUAGES (the only registration step)
// 1. src/engine/types.ts — the union the whole engine is typed against
export type SupportedLanguage = "en" | "vi" | "ja" | "es" | "ko" | "zh" | "pt-BR" | "id" | "fr";
// 2. src/i18n/index.ts — every language picker shows `nativeName (id)`.
// `flag` is no longer displayed, but the registration test requires it.
export const SUPPORTED_LANGUAGES = [
{ id: "en", label: "English", flag: "🇬🇧", nativeName: "English" },
{ id: "vi", label: "Vietnamese", flag: "🇻🇳", nativeName: "Tiếng Việt" },
{ id: "ja", label: "Japanese", flag: "🇯🇵", nativeName: "日本語" },
{ id: "es", label: "Spanish", flag: "🇪🇸", nativeName: "Español" }, // ← Add here
] as const;
// …
{ id: "fr", label: "French", flag: "🇫🇷", nativeName: "Français" },
] as const satisfies readonly {
id: SupportedLanguage;
label: string;
flag: string;
nativeName: string;
}[];
// 3. src/store/settings-heal.ts — detectBrowserLanguage's own copy of the list.
// Bare codes go in `supported`, region-qualified ones (like "pt-BR") in `REGIONAL`.
// Miss this and the language works, but is never auto-selected for a
// first-time visitor whose browser is set to it.
const supported: SupportedLanguage[] = ["en", "vi", "ja", "es", "ko", "zh", "id", "fr"];
// 4. src/engine/tag-generator.ts — CORE_TAGS_BY_LANG + MULTILINGUAL_TAGS (Step 6)
// 5. src/engine/channel-phrase.ts — DROP + FALLBACK (Step 5)
```
The `satisfies` clause makes an id that isn't in the union a compile error.
Items 4 and 5 are `Record<SupportedLanguage, …>`, so TypeScript catches those
too once the union has the new code.
Two more places, outside `src/`:
- **`worker/gate-i18n.ts`** — the Turnstile gate page, the first screen every
web visitor sees, has its own copy of the languages: add the code to
`GateLang`, its strings to `GATE_STRINGS`, and its `Accept-Language` prefix
to `PREFIX_TO_LANG`. `GateLang` is not tied to `SupportedLanguage`, so a miss
is **silent** — those visitors get the gate page in English. Update
`tests/worker/gate-i18n.test.ts` too; it pins the list of gate languages.
- **`DISCLAIMER.md`** (and `docs/i18n/vi/DISCLAIMER.md`) — add the locale to
the translation-quality table.
Optional: if the new locale is human-reviewed, add it to `TRANSLATION_TRUSTED`
in `src/engine/description-builder.ts` so it doesn't get the AI-translation
note, and update `description.translationQuality.intro` (which names the
reviewed languages) in every locale.
`npm run generate:locale` prints a shorter checklist on success; the list
above is the complete one.
No import or `resources` edits needed (v0.26+): locales are lazy-loaded
through a dynamic `import("./locales/<code>/<ns>.json")`, so Vite picks the
new files up automatically as async chunks — **the file names must stay
@@ -223,18 +262,66 @@ exactly `ui.json` and `templates.json`**. Only English is eagerly bundled
static imports for other languages, that would drag them back into the
main chunk.
### Step 5: Add multilingual tag pool
### Step 5: Channel-phrase patterns
Without a channel name, sentences such as "…of Hades on {{channelName}}." must
not end in "on ." (fixed in v1.0.0). The engine renders `{{channelName}}` as a
placeholder, then removes the words that go with it, per language:
```typescript
// src/engine/tag-generator.ts — add to MULTILINGUAL_TAG_POOLS
multilingual_es: (gameName: string) => [
`${gameName} sin comentarios`,
`${gameName} gameplay completo`,
`juego sin comentarios`,
],
// src/engine/channel-phrase.ts
const DROP: Record<SupportedLanguage, readonly RegExp[]> = {
// …
"pt-BR": [new RegExp(`\\s+no ${S}`, "g")], // "…de Hades no {{channelName}}." → "…de Hades."
};
/** For a sentence shape none of the patterns covers: a neutral stand-in. */
const FALLBACK: Record<SupportedLanguage, string> = {
// …
"pt-BR": "este canal",
};
```
### Step 6: Validate
Write the patterns for the phrases your `templates.json` actually uses. Then
add the code to `LANGS` in `tests/engine/channel-phrase.test.ts`: it renders
every template that names the channel with an empty channel and fails on any
leftover.
### Step 6: Tag pools
```typescript
// src/engine/tag-generator.ts
export const CORE_TAGS_BY_LANG: Record<SupportedLanguage, (gameName: string) => string[]> = {
// …
"pt-BR": (g) => [
`${g} gameplay`,
`${g} sem comentários`,
"gameplay sem comentários",
`${g} detonado`,
`${g} jogo completo`,
`${g} gameplay sem comentarios`,
],
};
export const MULTILINGUAL_TAGS: Record<SupportedLanguage, (gameName: string) => string[]> = {
// …
"pt-BR": (g) => [`${g} português`, `${g} em português`, "gameplay em português"],
};
```
Core tags come right after the game name in the tag list; multilingual tags
are added when **Settings › Include Multilingual Tags** is on, for the output
language only. Tags longer than 30 characters are dropped, and the
registration test checks that each language's core tags use the game name.
### Step 7: Check the font
The bundled Inter font covers Latin (including Vietnamese), Cyrillic and
Greek. Other scripts use the system fonts in `--font-sans-stack`
(`src/styles/globals.css`), which already lists Noto Sans JP / KR / SC for
CJK — add a fallback there if the new language uses another script.
### Step 8: Validate
```bash
npm run validate:locales
@@ -242,26 +329,36 @@ npm run validate:locales
# Reports missing/extra keys per language
```
### Step 7: Test
### Step 9: Test
```bash
npm run test -- --grep "i18n"
# Runs i18n-related tests including new language
npm run test:run -- tests/i18n tests/engine/channel-phrase.test.ts tests/engine/tag-generator.test.ts tests/worker/gate-i18n.test.ts
# Then the whole suite and the type check
npm run test:run
npm run typecheck && npm run typecheck:all
```
## Locale Validation Script
The `scripts/validate-locales.ts` script ensures all locale files are complete:
The `scripts/validate-locales.ts` script checks every locale folder against
`_schema.json`. At v1.2.0 (1,264 UI + 584 template keys per locale):
```
✓ en/ui.json — 47/47 keys
✓ en/templates.json — 32/32 keys
✓ vi/ui.json — 47/47 keys
✓ vi/templates.json — 32/32 keys
✓ ja/ui.json — 47/47 keys
✓ ja/templates.json — 32/32 keys
✗ es/ui.json — 45/47 keys (missing: editor.dlcName, editor.challengeName)
✓ es/templates.json — 32/32 keys
✓ en/ui.json — 1264/1264 keys
✓ en/templates.json — 584/584 keys
✓ es/ui.json — 1264/1264 keys
✓ es/templates.json — 584/584 keys
…
✓ zh/templates.json — 584/584 keys
All locale files are complete!
```
A gap fails the run and names the keys:
```
✗ fr/ui.json — 1245/1247 keys
Missing: editor.quick.nextPart, editor.quick.newVideo
```
## Template Interpolation
@@ -272,33 +369,39 @@ Templates use `{{variable}}` syntax (i18next default):
"intro": "This video features the full gameplay of {{gameName}} on {{channelName}}."
```
Engine passes variables:
The engine gets a `t` fixed to the output language and passes the variables:
```typescript
t("templates:description.intro.full", {
gameName: state.gameName,
channelName: state.channelName,
// src/hooks/use-generated-output.ts
const t = i18n.getFixedT(input.language, "templates");
// src/engine/description-builder.ts
const intro = t(`description.intro.${input.videoType}`, {
gameName,
channelName: channelOrSlot(input.channelName), // a placeholder when there is no channel
partNumber: input.partNumber ?? "",
// …
});
sections.push(withoutEmptyChannel(intro, input.language));
```
## RTL Language Support (Arabic)
For Arabic (`ar`), add RTL handling:
```typescript
// src/i18n/index.ts
export const RTL_LANGUAGES = ["ar"] as const;
// src/App.tsx — set dir attribute
const isRTL = RTL_LANGUAGES.includes(currentLanguage);
<div dir={isRTL ? "rtl" : "ltr"}>
```
Not supported yet. Arabic (`ar`) would need `dir="rtl"` on `<html>` — set
next to `lang`, which `src/main.tsx` updates on every `languageChanged` — and
a right-to-left pass over the layout.
## Contributing Translations
Community members can contribute translations by:
1. Fork the repository
2. Copy `src/i18n/locales/en/` to `src/i18n/locales/{code}/`
3. Translate all strings
4. Run `npm run validate:locales` to check completeness
5. Submit a PR with the new locale files
2. Run `npm run generate:locale -- --lang {code}` (or copy `src/i18n/locales/en/` to `src/i18n/locales/{code}/`)
3. Translate all strings in both files
4. Register the language (Step 4 above)
5. Run `npm run validate:locales` and the tests in Step 9
6. Submit a PR with the new locale files
Native-speaker corrections to the AI-translated locales are the most welcome
contribution of all. `src/i18n/locales/<code>/*.json` can be edited straight
from GitHub's web UI; see [CONTRIBUTING.md](../CONTRIBUTING.md).
+292 -223
View File
@@ -1,113 +1,126 @@
# Desktop Packaging Guide
## YTDescGen — Tauri Desktop App
## YTDescGen — Tauri 2 Desktop and Android Apps
Reflects **v1.2.0**: Windows, macOS (Apple silicon) and Linux desktop apps plus an Android APK, all built from the same Tauri 2 project in `src-tauri/`. The web app is deployed separately — see [HOSTING.md](HOSTING.md).
---
## Why Tauri?
| Feature | Tauri 2 | Electron |
|---------|---------|----------|
| Binary size | ~8 MB | ~150 MB |
| Memory usage | ~30 MB | ~100 MB+ |
| Bundled runtime | System WebView | Chromium |
| Backend language | Rust | Node.js |
| Security | Strict CSP, no Node in renderer | Full Node access |
| Auto-update | Built-in updater | electron-updater |
| CI build time | ~5 min | ~10 min |
| Feature | Tauri 2 | Electron |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| Download size | 3–6 MB installers (v1.1.0: MSI 4.1 MB, NSIS 3.1 MB, `.deb` 5.3 MB); the AppImage, which bundles its libraries, 80 MB | ~150 MB |
| Memory usage | Lower — no second browser engine | Higher — bundled Chromium + Node.js |
| Bundled runtime | System WebView | Chromium |
| Backend language | Rust | Node.js |
| Security model | Capability allow-list and CSP; no Node.js in the webview | Node.js main process, Chromium renderer |
| Auto-update | Updater plugin available — not used by this app | electron-updater |
Kokone đã quen Rust (từ hệ sinh thái Tauri/build tooling). Binary nhỏ, tốn ít RAM, deploy đơn giản.
The maintainer already knew Rust from the Tauri / build-tooling ecosystem; the small binary, low memory use and simple deployment settled it.
## Prerequisites
```bash
# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
- **Rust** (stable) via [rustup](https://rustup.rs/).
- **Node.js 22** (`.node-version`) and npm.
- **Tauri CLI** — the npm package `@tauri-apps/cli` is a pinned dev dependency, so `npm run tauri …` (or `npm run tauri:dev` / `npm run tauri:build`) needs nothing else. The cargo CLI (`cargo install tauri-cli --version "^2" --locked`, then `cargo tauri …`) works the same way; the Android release job uses it.
- **Platform tools**:
- Windows: Microsoft C++ Build Tools. WebView2 ships with Windows 10/11; the installers bootstrap it where it is missing (`webviewInstallMode: downloadBootstrapper`).
- macOS: Xcode Command Line Tools.
- Linux: `libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev patchelf` (what CI installs).
- **Android**: see [Android (.apk) Packaging](#android-apk-packaging).
# Tauri CLI
cargo install tauri-cli
`npm run tauri info` prints the Rust toolchain, WebView, Node and bundler versions it finds, and the bundle targets — run it first when a build fails; most "Tauri won't build" problems are a version mismatch.
# Node.js 22+
# npm already installed from web development
# Platform-specific
# Windows: Microsoft Visual Studio C++ Build Tools
# macOS: Xcode Command Line Tools
```
`npm run check:tauri` fails when the `@tauri-apps/*` npm packages and the `tauri` crates differ in major.minor — `tauri build` refuses to run in that state, and no workflow runs `tauri build` before a release tag does.
## Project Setup
### 1. Initialize Tauri in existing Vite project
The project was initialised once with `tauri init` (not needed again). `src-tauri/` is committed, except build output (`target/`, the Gradle build folders) and the Android signing files:
```bash
npm run tauri init
```
src-tauri/
├── Cargo.toml, Cargo.lock, build.rs
├── deny.toml # cargo-deny: advisories, licences, sources
├── tauri.conf.json
├── capabilities/default.json # what the webview may call
├── installer-license.txt # Windows installers' licence page
├── icons/ # desktop + Android icons (from assets/brand/logo.svg)
├── src/
│ ├── main.rs # desktop entry → yt_desc_gen_lib::run()
│ ├── lib.rs # plugins, commands, tray, single instance
│ ├── storage.rs # backups and logs under the app data directory
│ └── file_dialog.rs # native Save / Open dialogs
└── gen/android/ # the Android Gradle project (committed)
```
This creates `src-tauri/` directory.
The icons come from the one brand logo: `npx tauri icon assets/brand/logo.svg` regenerates them (`npm run generate:brand` does the same for the web's favicon, PWA icons and link-preview card).
### 2. tauri.conf.json
### 1. tauri.conf.json
```jsonc
```json
{
"$schema": "https://raw.githubusercontent.com/nicedoc/tauri/dev/tooling/cli/schema.json",
"$schema": "https://raw.githubusercontent.com/tauri-apps/tauri/dev/crates/tauri-cli/schema.json",
"productName": "YTDescGen",
"version": "1.2.0",
"identifier": "com.skullmute.ytdescgen",
"build": {
"beforeBuildCommand": "npm run build",
"beforeDevCommand": "npm run dev",
"devPath": "http://localhost:5173",
"distDir": "../dist"
"frontendDist": "../dist",
"devUrl": "http://localhost:5173"
},
"package": {
"productName": "YTDescGen",
"version": "0.1.0"
},
"tauri": {
"bundle": {
"active": true,
"identifier": "com.skullmute.ytdescgen",
"icon": [
"icons/32x32.png",
"icons/128x128.png",
"icons/128x128@2x.png",
"icons/icon.icns",
"icons/icon.ico"
],
"targets": ["msi", "nsis", "dmg", "app"],
"windows": {
"webviewInstallMode": {
"type": "downloadBootstrapper"
}
}
},
"app": {
"windows": [
{
"title": "YTDescGen",
"width": 1100,
"height": 750,
"minWidth": 800,
"minHeight": 600,
"width": 1280,
"height": 820,
"minWidth": 960,
"minHeight": 640,
"resizable": true,
"maximizable": true,
"fullscreen": false,
"center": true
}
],
"security": {
"csp": "default-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com"
"csp": "default-src 'self'; style-src 'self' 'unsafe-inline'"
}
},
"bundle": {
"active": true,
"copyright": "Copyright 2026 poli0981 (SkullMute)",
"licenseFile": "installer-license.txt",
"icon": [
"icons/32x32.png",
"icons/128x128.png",
"icons/128x128@2x.png",
"icons/icon.icns",
"icons/icon.ico"
],
"targets": "all",
"android": {
"minSdkVersion": 30
},
"systemTray": {
"iconPath": "icons/icon.png",
"iconAsTemplate": true
},
"updater": {
"active": true,
"dialog": true,
"endpoints": [
"https://github.com/poli0981/yt-desc-gen/releases/latest/download/latest.json"
]
"windows": {
"webviewInstallMode": {
"type": "downloadBootstrapper"
}
}
}
}
```
Notes:
- The window opens at 1280×820 and can be resized down to 960×640.
- The CSP allows only the app's own files (plus inline styles, which Radix, Motion and sonner set). That is why the Vite build never inlines assets as `data:` URIs (`assetsInlineLimit: 0`) and the fonts are self-hosted. The Tauri build also carries no analytics beacon — Vite adds it only to the web build.
- There is **no `trayIcon` entry**: the tray icon is built in code (`lib.rs`), with the app icon — a `trayIcon` entry would add a second one.
- There is **no `updater` configuration** — see [Updates](#updates).
- `targets: "all"` builds every bundle the platform supports (MSI + NSIS on Windows, `.app` + `.dmg` on macOS, `.deb` + `.rpm` + AppImage on Linux); the release workflow narrows macOS to `.app`.
- `bundle.copyright` (v1.1.0) is the installers' copyright string — the Windows file properties, the macOS `Info.plist` and the Linux packages. `npm run check:copyright` (in CI) holds its year to the year of the newest commit, together with NOTICE and REUSE.toml, and `npm run update:copyright` rewrites all three: the first commit of a new year needs it.
> **Installer license page (v0.28).** The real `src-tauri/tauri.conf.json`
> sets `bundle.licenseFile: "installer-license.txt"` (path relative to
> `src-tauri/`). Tauri shows that file as an "accept the terms" page in the
@@ -117,108 +130,146 @@ This creates `src-tauri/` directory.
> the per-bundler keys (`bundle.windows.wix.licenseFile` wants `.rtf`,
> `bundle.windows.nsis.licenseFile` accepts `.txt`).
### 3. Rust Backend (src-tauri/src/main.rs)
### 2. Capabilities (src-tauri/capabilities/default.json)
```rust
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
use tauri::{Manager, SystemTray, SystemTrayMenu, SystemTrayMenuItem, SystemTrayEvent};
#[tauri::command]
fn save_to_file(path: String, content: String) -> Result<(), String> {
std::fs::write(&path, &content).map_err(|e| e.to_string())
}
#[tauri::command]
fn read_from_file(path: String) -> Result<String, String> {
std::fs::read_to_string(&path).map_err(|e| e.to_string())
}
fn main() {
let tray_menu = SystemTrayMenu::new()
.add_item(tauri::CustomMenuItem::new("show", "Show"))
.add_native_item(SystemTrayMenuItem::Separator)
.add_item(tauri::CustomMenuItem::new("quit", "Quit"));
let system_tray = SystemTray::new().with_menu(tray_menu);
tauri::Builder::default()
.system_tray(system_tray)
.on_system_tray_event(|app, event| match event {
SystemTrayEvent::LeftClick { .. } => {
let window = app.get_window("main").unwrap();
window.show().unwrap();
window.set_focus().unwrap();
}
SystemTrayEvent::MenuItemClick { id, .. } => match id.as_str() {
"show" => {
let window = app.get_window("main").unwrap();
window.show().unwrap();
window.set_focus().unwrap();
}
"quit" => {
std::process::exit(0);
}
_ => {}
},
_ => {}
})
.invoke_handler(tauri::generate_handler![save_to_file, read_from_file])
.run(tauri::generate_context!())
.expect("error while running tauri application");
```json
{
"identifier": "default",
"description": "Default capabilities for YTDescGen. File access goes through the app's own name-only commands and native dialogs run from Rust, so the webview gets no dialog, fs or shell permissions.",
"windows": ["main"],
"permissions": ["core:default", "opener:default"]
}
```
The webview can call Tauri's core APIs, the opener plugin (external links open in the system browser, mail client or dialler) and the app's own commands — nothing else. v1.0.0 removed the `fs` and `shell` plugins and their permissions. `tauri-plugin-dialog` is still a dependency, but only Rust uses it: the webview has no dialog permission and no dialog JavaScript package. (`tauri-plugin-fs` still appears in `Cargo.lock` as a dependency of the dialog plugin; the app does not register it.)
### 3. Rust Backend (src-tauri/src)
`main.rs` only calls `yt_desc_gen_lib::run()`. `lib.rs`, abridged:
```rust
mod file_dialog;
mod storage;
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
// Shared by every platform (desktop + Android). No command takes a path.
let builder = tauri::Builder::default()
.plugin(tauri_plugin_dialog::init())
.plugin(tauri_plugin_opener::init())
.invoke_handler(tauri::generate_handler![
storage::backup_list,
storage::backup_read,
storage::backup_write,
storage::backup_delete,
storage::log_append,
storage::log_list,
storage::log_read,
storage::log_delete,
storage::recover_legacy_data,
file_dialog::export_text_file,
file_dialog::import_text_file,
]);
#[cfg(desktop)]
{
// tauri_plugin_single_instance (first desktop plugin: a second launch
// focuses the running window), a tray icon built in setup() with the
// app icon and a Show / Quit menu, close-to-tray, and exit prevention
// unless Quit was chosen from the tray.
}
#[cfg(not(desktop))]
builder
.run(tauri::generate_context!())
.expect("error while building tauri application");
}
```
The commands:
| Command | Arguments | What it does |
| --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `backup_list` | — | Lists the backups in `<app data>/backups/`, newest first (`name`, `size`, `modifiedMs`) |
| `backup_read` | `name` | Reads one backup (at most 32 MB) |
| `backup_write` | `name`, `content` | Writes atomically (temporary file + rename); after writing a `ytdescgen-backup-*` file, deletes all but the newest ten of those |
| `backup_delete` | `name` | Deletes one backup (a missing file is not an error) |
| `log_append` | `name`, `content` | Appends one entry (at most 256 KB) to `<app data>/logs/<name>` |
| `log_list` | — | The log file names, sorted |
| `log_read` | `name` | Reads one log file (at most 32 MB) |
| `log_delete` | `name` | Deletes one log file |
| `recover_legacy_data` | — | Moves files written by versions before 1.0 into place (see [Legacy files](#legacy-files-from-versions-before-10)); returns `{ backups, logsMoved }` |
| `export_text_file` | `suggestedName`, `content`, `filterName`, `extensions`, `title?` | Opens the native Save dialog **in Rust** and writes the file the user picked; returns its name, or `null` when cancelled |
| `import_text_file` | `filterName`, `extensions`, `title?` | Opens the native Open dialog in Rust and returns `{ name, text }`, or `null` when cancelled |
What makes them safe:
- **Names, not paths.** `storage.rs` builds every path itself, under Tauri's `app_data_dir()`, from a name that must match `ytdescgen-<lowercase letters, digits, hyphens>.json` (at most 100 bytes) for backups or `ytdescgen-YYYYMMDD.jsonl` for logs. Anything else — `..`, separators, other extensions — is rejected before a path exists.
- **Dialogs run in Rust.** `file_dialog.rs` accepts only the extensions `json`, `jsonl`, `txt`, `csv` and `md`; reduces a suggested name to its file name (`../../x/backup.json` → `backup.json`); makes a saved file end in an allowed extension (`backup` → `backup.json`, `backup.exe` → `backup.exe.json`); and refuses imports over 20 MB or that are not UTF-8 (a byte-order mark is stripped). The chosen path never passes through JavaScript. On desktop the dialog is attached to the app window.
- **Removed in v1.0.0**: the five commands that read, wrote, appended to, listed and deleted any path the webview sent (`save_to_file`, `read_from_file`, `append_to_file`, `list_dir`, `delete_file`), and the fs and shell plugins.
Both modules have unit tests (`cargo test` in `src-tauri/`): the name rules, path rejection, backup pruning, legacy recovery, dialog filters and the import checks.
### 4. Frontend Tauri Integration
```typescript
// src/utils/platform.ts
export const IS_TAURI = "__TAURI__" in window;
- **`src/utils/platform.ts`** — `IS_TAURI` (`"__TAURI_INTERNALS__" in window`), `IS_MOBILE` (an Android user agent) and `IS_MAC` (how shortcuts are spelled).
- **`src/utils/native.ts`** — the typed bridge to the commands above; `invoke` from `@tauri-apps/api/core` is imported lazily, so the web build never loads it. Exposes `appBackups` (`list`, `read`, `write`, `remove`), `appLogs` (`append`, `list`, `read`, `remove`), `recoverLegacyData`, `nativeSaveTextFile`, `nativeOpenTextFile`, and `HAS_NATIVE_DIALOGS = IS_TAURI && !IS_MOBILE`.
- **`src/utils/file-ops.ts`** — exports and imports on every platform:
// src/utils/file-ops.ts
import { IS_TAURI } from "./platform";
```typescript
// saveTextFile({ content, filename, mimeType?, description? }) → "saved" | "cancelled" | "failed"
// 1. Tauri desktop: nativeSaveTextFile → export_text_file (dialog + write in Rust)
// 2. Web with the File System Access API (Chromium): showSaveFilePicker
// 3. Anything else (Android, Firefox, Safari): a blob download
//
// openTextFile({ extensions, description? }) → picked | cancelled | failed
// Tauri desktop: nativeOpenTextFile → import_text_file
// Elsewhere: a hidden <input type="file">; its "cancel" event reports a
// dismissed picker (no focus-timer guessing). readTextFile() applies the
// same extension and 20 MB checks to dropped files.
```
export async function saveFile(content: string, filename: string): Promise<void> {
if (IS_TAURI) {
const { save } = await import("@tauri-apps/api/dialog");
const { invoke } = await import("@tauri-apps/api/tauri");
const path = await save({ defaultPath: filename });
if (path) await invoke("save_to_file", { path, content });
} else {
// Web fallback: download via blob
const blob = new Blob([content], { type: "text/plain" });
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = filename;
a.click();
URL.revokeObjectURL(url);
}
}
- **`src/utils/log-storage.ts`** — in Tauri, one JSONL line per log entry through `appLogs.append` into the day's file; at start-up it loads the files inside the retention window and deletes older ones. On the web it uses the `ytdescgen-logs` localStorage key instead.
- **`src/utils/open-external.ts`** — in Tauri, external links go through the opener plugin. `target="_blank"` is stripped from external anchors and clicks are intercepted in the capture phase, so a link can neither navigate the app's own webview nor trigger the webview's new-window handling (which failed on Android).
- **`src/utils/backup/startup.ts`** — `startAppData()`, run once from `App.tsx` in Tauri builds: legacy-file recovery, then automatic backups on desktop.
export async function loadFile(): Promise<string | null> {
if (IS_TAURI) {
const { open } = await import("@tauri-apps/api/dialog");
const { invoke } = await import("@tauri-apps/api/tauri");
const path = await open({ filters: [{ name: "JSON", extensions: ["json"] }] });
if (typeof path === "string") return invoke("read_from_file", { path });
return null;
} else {
// Web fallback: file input
return new Promise((resolve) => {
const input = document.createElement("input");
input.type = "file";
input.accept = ".json";
input.onchange = async () => {
const file = input.files?.[0];
if (file) resolve(await file.text());
else resolve(null);
};
input.click();
});
}
}
```
## Where the Apps Keep Data
- **Everything the app holds** — profiles, presets, templates, history, settings and the current draft — is in the **WebView's localStorage**, under the same `ytdescgen-*` keys as the web app (Zustand `persist`). On Windows that is WebView2's profile in `%LOCALAPPDATA%\com.skullmute.ytdescgen\EBWebView`. There is no second copy: the settings "mirror" file of earlier versions is gone.
- **Files the app writes itself** live under Tauri's `app_data_dir()` — `<data dir>/com.skullmute.ytdescgen`, which is `%APPDATA%\com.skullmute.ytdescgen` on Windows:
- `backups/` — `ytdescgen-backup-YYYYMMDD-HHmm.json` files: the automatic backups, **Back up now**, and the backup written before each restore (with a `-before-restore` suffix); the newest ten of these are kept (desktop only). Also the recovered legacy files (`ytdescgen-legacy-data*.json`), which are never deleted automatically. On desktop, Settings › Backup & restore lists them all and restores any of them.
- `logs/` — `ytdescgen-YYYYMMDD.jsonl`, one file per day, deleted after the Log retention setting (1–90 days, default 7).
- **Exports** go wherever the user picks in the Save dialog (desktop) or are downloaded (Android).
Automatic backups: 5 s after start, then after the library changes (30 s quiet, at most every 10 minutes), only when the data differs from the last backup and the library is not empty. Format and rules: [TECH-SPEC.md § 4](TECH-SPEC.md#4-backup-file-format-v100).
### Legacy files from versions before 1.0
Before v1.0.0 the frontend glued file names onto the data directory without a separator, so the settings "mirror" was written as `…\com.skullmute.ytdescgensettings.json` next to the data folder — and never read back — and the log files landed in a `…\com.skullmute.ytdescgenlogs\` folder beside it.
On start, `startAppData()` calls `recover_legacy_data`, which:
- moves the old data file (from the glued path, or `settings.json` inside the data folder) into `backups/` as `ytdescgen-legacy-data.json` (`-2`, `-3`, … when taken). It is **never applied on its own** — the data in the app is usually newer. A toast offers **Review**, which opens the restore preview for that file; on desktop it also stays listed under Settings › Backup & restore.
- merges the stray daily log files into `logs/` (appending when that day's file already exists) and removes the stray folder once it is empty; anything else in it is left alone.
The recovery runs in every Tauri build (desktop and Android); a second run finds nothing to do.
## Versioning
A release bumps the version in **six places**, and `npm run check:version` (in CI and in the release `verify` job) fails until they agree:
| File | Field |
| --------------------------- | ----------------------- |
| `package.json` | `version` |
| `package-lock.json` | `version` |
| `package-lock.json` | `packages[""].version` |
| `src-tauri/tauri.conf.json` | `version` |
| `src-tauri/Cargo.toml` | `[package] version` |
| `src-tauri/Cargo.lock` | the `yt-desc-gen` entry |
`npm version --no-git-tag-version <version>` covers the first three; the Rust / Tauri files are edited by hand (cargo also rewrites the `Cargo.lock` entry on the next non-`--locked` build or check in `src-tauri/`). Add the `CHANGELOG.md` entry in the same change.
The copyright year is not part of the version, but the first release of a new year needs `npm run update:copyright` first — `check:copyright` fails until then (see the `bundle.copyright` note above).
## Build & Release
@@ -228,8 +279,8 @@ export async function loadFile(): Promise<string | null> {
# Web only
npm run dev
# Desktop (opens native window with hot reload)
npm run tauri dev
# Desktop (native window against the Vite dev server, with hot reload)
npm run tauri:dev
```
### Production Build
@@ -239,38 +290,60 @@ npm run tauri dev
npm run build
# Desktop → src-tauri/target/release/bundle/
npm run tauri build
npm run tauri:build
```
Output locations:
- Windows: `src-tauri/target/release/bundle/msi/YTDescGen_0.1.0_x64.msi`
- macOS: `src-tauri/target/release/bundle/dmg/YTDescGen_0.1.0_aarch64.dmg`
The Tauri CLI runs `npm run build` first (`beforeBuildCommand`) with `TAURI_ENV_PLATFORM` set, which switches Vite to the Tauri build: `es2020` target, the Legal Center content only, and no static legal pages, `security.txt` or analytics beacon.
Output file names, with the v1.1.0 release sizes:
| Platform | Bundle | File | Size |
| --------------------- | -------------------------------- | ---------------------------------------- | ------ |
| Windows | MSI | `YTDescGen_<version>_x64_en-US.msi` | 4.1 MB |
| Windows | NSIS | `YTDescGen_<version>_x64-setup.exe` | 3.1 MB |
| macOS (Apple silicon) | `.app`, archived by tauri-action | `YTDescGen_<version>_aarch64.app.tar.gz` | 4.1 MB |
| Linux | Debian | `YTDescGen_<version>_amd64.deb` | 5.3 MB |
| Linux | RPM | `YTDescGen-<version>-1.x86_64.rpm` | 5.3 MB |
| Linux | AppImage | `YTDescGen_<version>_amd64.AppImage` | 80 MB |
| Android | Universal APK | `app-universal-release.apk` | 44 MB |
### GitHub Actions Release
The live workflow lives at [.github/workflows/release-desktop.yml](../.github/workflows/release-desktop.yml). Pushing a `v*` tag (e.g. `v0.10.0`) triggers a three-platform matrix build (Windows, macOS ARM, Linux) and uploads each installer to a single draft GitHub Release named `YTDescGen v__VERSION__`. Publish the draft manually after smoke-testing the binaries.
Pushing a `v*` tag (signed, e.g. `v1.0.0`) runs [.github/workflows/release-desktop.yml](../.github/workflows/release-desktop.yml) and [.github/workflows/release-android.yml](../.github/workflows/release-android.yml). Both start with a **`verify`** job, and their build jobs `needs: verify`:
Matrix entries:
```yaml
- run: npm ci # a clean install: package-manager-cache: false
- run: npm run typecheck
- run: npm run test:run
- run: npm run check:version
- run: npm run check:tauri
- name: Tag matches the manifests # "v" + package.json version must equal the tag
```
| Runner | Target | Output |
|---|---|---|
| `windows-latest` | `x86_64-pc-windows-msvc` | `.msi`, `.exe` (NSIS) |
| `macos-14` | `aarch64-apple-darwin` | `.app.tar.gz` |
| `ubuntu-latest` | `x86_64-unknown-linux-gnu` | `.AppImage`, `.deb` |
Release jobs use no dependency caches — a poisoned cache entry written by another workflow must not reach the binaries — and every action is pinned by commit SHA.
Linux runners install `libwebkit2gtk-4.1-dev`, `libgtk-3-dev`, `libayatana-appindicator3-dev`, `librsvg2-dev`, and `patchelf` before building — Tauri's webview + AppImage tooling needs these.
The desktop build is a three-platform matrix; `tauri-apps/tauri-action` builds each target and uploads its bundles to one **draft** GitHub Release named `YTDescGen vX.Y.Z`:
| Runner | Target | Output |
| ---------------- | -------------------------- | --------------------------- |
| `windows-latest` | `x86_64-pc-windows-msvc` | `.msi`, `.exe` (NSIS) |
| `macos-14` | `aarch64-apple-darwin` | `.app.tar.gz` |
| `ubuntu-latest` | `x86_64-unknown-linux-gnu` | `.AppImage`, `.deb`, `.rpm` |
Linux runners install `libwebkit2gtk-4.1-dev`, `libgtk-3-dev`, `libayatana-appindicator3-dev`, `librsvg2-dev` and `patchelf` before building — Tauri's webview and AppImage tooling need them. AppImage bundling runs with `APPIMAGE_EXTRACT_AND_RUN=1` (linuxdeploy needs FUSE, which hosted runners don't reliably provide) and `NO_STRIP=true`.
`fail-fast: false` keeps the other platforms going if one breaks. The `bundleArgs` matrix field is concatenated with `--target ${{ matrix.target }}` and passed through to `tauri build`.
**macOS notes (v0.9.1+):**
- **DMG bundling is skipped** (`--bundles app`). Tauri's DMG bundler runs an AppleScript that flakes intermittently on hosted macOS runners (the headless display can't load Finder fast enough for `osascript` to position icons), so we ship a `.app.tar.gz` instead. Users expand the archive and drag the `.app` into `/Applications`.
- **Intel macOS (`macos-13`) is NOT built.** GitHub started deprecating the `macos-13` free runner pool in 2025; jobs queue indefinitely. If Intel support becomes a priority, switch the macos-14 entry's target to `universal-apple-darwin` (Tauri builds both archs and lipos them into one universal binary) — the runner already has the toolchain capacity.
**Code signing is intentionally skipped** for both Windows and macOS — this is an open-source personal tool, and signing certificates carry recurring cost. End users will see the standard "unverified publisher" / "unidentified developer" prompts on first launch. Document the bypass steps in the release notes if needed.
**Code signing is intentionally skipped** for both Windows and macOS — this is an open-source personal tool, and signing certificates carry recurring cost. End users will see the standard "unverified publisher" / "unidentified developer" prompts on first launch. Document the bypass steps in the release notes if needed. (The Android APK is signed — see below.)
**Auto-changelog** (`git-cliff`) is out of scope; release notes come from the tag's annotated message via the default `tauri-action` behaviour. CHANGELOG.md is hand-maintained.
**Release notes.** tauri-action gives the draft a fixed body ("See the assets to download the installer for your platform."). `CHANGELOG.md` is hand-maintained and is the source for the notes; the maintainer smoke-tests the binaries and publishes the draft by hand. Publishing triggers `announce-release.yml` (the Announcements discussion and Discord).
**Manual re-run:** the workflow accepts `workflow_dispatch` with a `tag` input — `gh workflow run release-desktop.yml -f tag=v0.9.0` rebuilds an existing release without deleting + recreating the tag. Useful when a transient runner failure costs a single arch's binary.
**Manual re-run:** both workflows accept `workflow_dispatch` with a `tag` input — `gh workflow run release-desktop.yml -f tag=v1.0.0` rebuilds an existing release without deleting and recreating the tag. The manifests at that tag must already carry the version, or `verify` stops the run. Useful when a transient runner failure costs a single platform's binary.
**Backfill for pre-workflow tags:** `v0.8.0` and `v0.8.1` predate the multi-platform matrix and only have local Windows builds. To attach binaries retroactively, build manually then `gh release create v0.8.0 --notes-file CHANGELOG.md path/to/*.msi …`.
@@ -285,12 +358,12 @@ is gated behind `#[cfg(desktop)]` so the library compiles for Android.
### Requirements & tested versions
| | |
|---|---|
| **Minimum OS** | **Android 11** (API level 30, `minSdk 30`). The APK will not install below this. |
| **Target OS** | **Android 16** (API level 36, `targetSdk 36`). |
| **Architectures** | Universal APK — `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`. |
| **Tested** | **Android 11 → 16.** The v0.29.0 build was verified on Android emulators across this range **and on a real device running Android 12** (the maintainer's phone). |
| | |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Minimum OS** | **Android 11** (API level 30, `minSdk 30`). The APK will not install below this. |
| **Target OS** | **Android 16** (API level 36, `targetSdk 36`, `compileSdk 36`). |
| **Architectures** | Universal APK — `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`. |
| **Tested** | **Android 11 → 16.** The v0.29.0 build was verified on Android emulators across this range **and on a real device running Android 12** (the maintainer's phone). |
Where the value lives: `bundle.android.minSdkVersion` in
[`src-tauri/tauri.conf.json`](../src-tauri/tauri.conf.json) is the source of
@@ -306,11 +379,11 @@ directly if you change the floor without re-running `init`.
- **A modern, patched WebView.** The app renders entirely in the system WebView,
whose minimum is Android 10. On Android 11+ the WebView auto-updates via Google
Play, so the rendering/JS engine stays current and patched. This is exactly why
the **real-device test on Android 12 worked**, while a *stale* Android-12
the **real-device test on Android 12 worked**, while a _stale_ Android-12
emulator stuck on WebView 91 showed a black screen (the `crypto.randomUUID`
boot crash) — that class of bug is fixed in v0.29.0 and is moot on an
up-to-date WebView.
- **Security upkeep.** Even though Google's *OS-level* monthly security bulletins
- **Security upkeep.** Even though Google's _OS-level_ monthly security bulletins
for Android 11–13 have ended (Android 12 in 2025, Android 13 in early 2026),
Android 11+ keeps receiving security updates for the components that matter to a
sandboxed WebView app: Google Play system updates (Project Mainline), Google
@@ -319,8 +392,8 @@ directly if you change the floor without re-running `init`.
### Prerequisites
- **Android SDK** — platform-tools, a platform (e.g. `android-34`/`android-36`), build-tools. Install via Android Studio or the command-line tools.
- **Android NDK** — r27 LTS recommended (e.g. `27.3.13750724`).
- **Android SDK** — platform-tools, a platform (e.g. `android-36`), build-tools. Install via Android Studio or the command-line tools.
- **Android NDK** — r27 LTS (`27.3.13750724`, what CI uses).
- **JDK 17** — Android Studio's bundled JBR works (`…/Android Studio/jbr`).
- **Rust android targets**:
```bash
@@ -372,7 +445,7 @@ keyPassword=<key-password>
```
`app/build.gradle.kts` carries a `release` `signingConfigs` block that reads this
file, guarded by `if (exists())` — a missing keystore yields an *unsigned*
file, guarded by `if (exists())` — a missing keystore yields an _unsigned_
release build rather than a hard failure (handy for contributors).
### Build
@@ -386,6 +459,7 @@ cargo tauri android build --apk
- `cargo tauri android build --apk --target aarch64` builds an arm64-only APK (smaller download; covers virtually all modern phones).
- The build runs `npm run build` first (the `beforeBuildCommand`), then Gradle. The first build takes several minutes (Rust × up to 4 ABIs + a cold Gradle).
- For on-device iteration with hot reload: `cargo tauri android dev`.
- With the npm CLI instead of the cargo one: `npm run tauri android build -- --apk`.
Install on a device: copy the APK over (or `adb install -r <apk>`) and enable
"Install unknown apps" for the source app.
@@ -393,48 +467,43 @@ Install on a device: copy the APK over (or `adb install -r <apk>`) and enable
### CI
[.github/workflows/release-android.yml](../.github/workflows/release-android.yml)
builds and signs the APK on a `v*` tag (or `workflow_dispatch`) and attaches it
to the same draft GitHub Release as the desktop binaries. It needs four repo
secrets:
runs on a `v*` tag (or `workflow_dispatch` with a `tag`). After `verify`, the
`build-android` job sets up JDK 17 (Temurin), the Android SDK, NDK
`27.3.13750724`, the four Rust Android targets and the cargo Tauri CLI; decodes
the keystore into `$RUNNER_TEMP`; writes `src-tauri/gen/android/keystore.properties`;
and runs `cargo tauri android build --apk` with `NDK_HOME` pinned to that NDK.
| Secret | Value |
|---|---|
The APK is kept as the workflow artifact `ytdescgen-android-apk`, then attached
to the draft release with `gh release upload <tag> --clobber`. That upload needs
the draft the desktop workflow creates; if the Android job gets there first,
re-run it. It needs four repo secrets:
| Secret | Value |
| ------------------------- | --------------------------------------------------------- |
| `ANDROID_KEYSTORE_BASE64` | base64 of the `.jks` (`base64 -w0 ytdescgen-release.jks`) |
| `ANDROID_STORE_PASSWORD` | keystore store password |
| `ANDROID_KEY_PASSWORD` | key password |
| `ANDROID_KEY_ALIAS` | `ytdescgen` |
| `ANDROID_STORE_PASSWORD` | keystore store password |
| `ANDROID_KEY_PASSWORD` | key password |
| `ANDROID_KEY_ALIAS` | `ytdescgen` |
### App-level changes for Android
- **`src-tauri/src/lib.rs`** — tray / single-instance / hide-to-tray / exit-prevention are `#[cfg(desktop)]`; the dialog/fs/opener/shell plugins and the six file commands run on every platform.
- **`src-tauri/src/lib.rs`** — tray / single-instance / hide-to-tray / exit-prevention are `#[cfg(desktop)]`; the dialog and opener plugins and the eleven commands are registered on every platform.
- **`src-tauri/Cargo.toml`** — `tauri-plugin-single-instance` lives in a desktop-only `[target.'cfg(not(any(target_os = "android", target_os = "ios")))'.dependencies]` table.
- **`src/utils/platform.ts` / `file-ops.ts`** — `IS_MOBILE` routes file export through the WebView blob download on Android (the native save dialog is unreliable under scoped storage). Settings persist via `appDataDir()` (app-private storage) **and** localStorage, both of which work on Android.
- **`src/utils/native.ts` / `file-ops.ts`** — `HAS_NATIVE_DIALOGS` is false on Android (a picked location there is a content URI, not a path), so exports are a WebView download and imports use the file input. Automatic backups are desktop-only; the legacy-file recovery runs on Android too.
- **Storage** — as on desktop, everything is in the WebView's localStorage; the app's own data directory holds `logs/` and, after an upgrade from an older version, the recovered legacy file in `backups/`.
## Auto-Update Flow
## Updates
```
App Start
│
▼
Check GitHub Releases endpoint
│
├─ No update → Continue normally
│
└─ Update available
│
▼
Show dialog: "Update v0.2.0 available. Install now?"
│
├─ Yes → Download + install + restart
└─ No → Dismiss, ask again next launch
```
The app has no in-app updater: no updater plugin, no `updater` configuration, and it never checks for new versions. New versions are published as GitHub Releases; users download the installer or APK for their platform and install it over the existing app. User data is outside the installation — in the WebView storage and the app data directory described above — so it is kept. An Android update must be signed with the same keystore to install over an existing copy.
## Offline Capability
The app is fully offline-capable because:
- All templates and configs are bundled
- State persists in localStorage (web) or app data directory (Tauri)
- No external API calls required
- Fonts can be bundled locally for desktop
The desktop and Android apps work fully offline:
Only auto-update requires internet connectivity.
- All templates, configuration and translations are bundled; the non-English locales are separate chunks inside the app.
- The legal documents are rendered into the build at build time (the Legal Center reads them locally).
- Fonts (Inter, JetBrains Mono) are self-hosted.
- State lives in the WebView's localStorage; backups and logs in the app data directory.
- The app makes no network requests of its own. Only external links (opened in the system browser) need a connection.
The web app is the same code, but reaching it needs the network: the Turnstile check runs at the edge before the app loads, at most once a day per browser (see [HOSTING.md](HOSTING.md)).
+124 -16
View File
@@ -2,13 +2,20 @@
## YTDescGen — Phased Development Plan
> **Status (2026-10-12): v1.2.0 is the current release.** Phases 1–4 are the original
> plan, kept as a record; notes added beside or under an item say what has
> changed since. Every release is listed in [CHANGELOG.md](../CHANGELOG.md).
> What's next: Phase 5 and the backlog at the end of this page.
---
## Phase 1 — MVP Core (Priority: P0) ✅ COMPLETED 2026-04-07
**Goal**: Ứng dụng web chạy được, generate title + description + tags, copy to clipboard.
**Estimated**: 3-4 days | **Actual**: 1 day
### Tasks
```
1.1 Project scaffold
- [x] Vite + React 18 + TypeScript setup
@@ -57,15 +64,19 @@
- [x] EditorPage (form + quick preview)
- [x] OutputPage (title + desc + tags + copy)
- [x] React Router setup (HashRouter)
(v1.0.0: real paths on the web; hash routes only in the desktop/Android apps)
1.8 Testing
- [x] Vitest config
- [x] Engine unit tests (title, description, tags) — 42 tests
- [ ] Smoke tests for main pages (deferred to Phase 3)
- [ ] Smoke tests for main pages (deferred to Phase 3; still open — the
suite runs in Node without a DOM, see the backlog)
1.9 CI/CD
- [x] GitHub Actions: lint + typecheck + test
- [x] GitHub Actions: deploy to GitHub Pages
(retired in v1.0.0 — Cloudflare Workers Builds deploys ytgenerator.stream
from main; see HOSTING.md)
### Definition of Done
- [x] User can select video type, language, genre
@@ -73,16 +84,18 @@
- [x] Title, description, and tags generate correctly in EN/VI/JA
- [x] Copy buttons work for title, description, tags, and all
- [x] Character counts displayed (5000 desc, 500 tags)
- [x] CI passes, deploys to GitHub Pages
- [x] CI passes, deploys to GitHub Pages (ytgenerator.stream since v1.0.0)
```
---
## Phase 2 — Profiles & Presets (Priority: P1) ✅ COMPLETED 2026-04-07
**Goal**: Lưu thông tin tái sử dụng, không phải nhập lại mỗi lần.
**Estimated**: 2-3 days | **Actual**: 1 day
### Tasks
```
2.1 Profile system
- [x] profile-store.ts (Zustand + persist)
@@ -133,10 +146,12 @@
---
## Phase 3 — Polish & Advanced Features (Priority: P1-P2) ✅ COMPLETED 2026-04-07
**Goal**: Batch mode, history, keyboard shortcuts, theme.
**Estimated**: 2-3 days | **Actual**: 1 day
### Tasks
```
3.1 History system
- [x] history-store.ts (max entries, auto-prune, configurable limit)
@@ -145,6 +160,7 @@
- [x] Delete history entries
- [x] Search/filter history by game name or title
- [x] Auto-save to history on OutputPage view
(v1.0.0: one entry per video, updated in place)
3.2 Batch mode
- [x] BatchPage UI
@@ -168,10 +184,12 @@
3.5 Keyboard shortcuts
- [x] Global keyboard listener (useKeyboardShortcuts hook)
- [x] Ctrl+Enter (go to output), Ctrl+Shift+C (copy all), Ctrl+S (save draft)
(v1.0.0: Ctrl/⌘+S saves the output to History — the draft saves itself;
Ctrl/⌘+K opens the command palette)
- [x] Ctrl+/ shortcut help modal
3.6 UX Polish
- [x] Toast notifications for copy/save/delete (react-hot-toast)
- [x] Toast notifications for copy/save/delete (react-hot-toast; sonner since v1.0.0)
- [x] Responsive layout (mobile-first, lg breakpoint for sidebar)
- [x] Scrollable tab bar for mobile
- [x] Empty states for all list pages
@@ -199,10 +217,12 @@
---
## Phase 4 — Desktop App (Priority: P2) ✅ COMPLETED 2026-04-08
**Goal**: Đóng gói thành ứng dụng desktop bằng Tauri.
**Estimated**: 2-3 days | **Actual**: 1 day
### Tasks
```
4.1 Tauri setup
- [x] Install Tauri CLI v2 + dependencies (@tauri-apps/api, plugins)
@@ -210,9 +230,12 @@
- [x] tauri.conf.json configuration (Tauri v2 format)
- [x] App icons (all sizes via cargo tauri icon)
- [x] Capabilities (default.json with dialog, fs, shell permissions)
(v1.0.0: only core + opener; the fs and shell plugins are removed)
4.2 Desktop features
- [x] Native file save/load via Tauri commands (save_to_file, read_from_file)
(v1.0.0: replaced by name-only commands under the app's data folder
and Save / Open dialogs run from Rust)
- [x] Platform detection (IS_TAURI flag)
- [x] File ops with web fallback (src/utils/file-ops.ts)
- [x] System tray with Show/Quit menu
@@ -225,18 +248,21 @@
4.4 Build pipeline
- [x] GitHub Actions: release-desktop.yml (Windows + macOS cross-compile)
(now Windows, macOS and Linux; Android via release-android.yml)
- [x] Tag-triggered release (v* tags)
- [x] Verified local build: MSI 4.1MB, NSIS 2.7MB, EXE 14MB
4.5 Platform-specific
- [x] Windows: MSI + NSIS installers built successfully
- [ ] macOS: requires macOS runner (CI handles this)
- [x] macOS: built on the macos-14 CI runner (Apple Silicon .app)
- [x] Offline functionality verified (all bundled, no API calls)
- [x] Vite base URL conditional (/ for Tauri, /yt-desc-gen/ for web)
(v1.0.0: / for both)
### Definition of Done
- [x] Windows installer < 15MB (4.1MB MSI), installs and runs
- [ ] macOS .app < 15MB (CI-only, not locally testable)
- [x] macOS .app < 15MB (CI-only, not locally testable; 4.1 MB `.app.tar.gz`
in v1.1.0)
- [ ] Auto-update from GitHub Releases (deferred — needs signing)
- [x] All web features work identically in desktop
- [x] Offline mode fully functional
@@ -244,11 +270,66 @@
---
## v1.0.0 — Stable Release ✅ SHIPPED 2026-09-30
**Goal**: A stable 1.0 on its own domain, with data that is right. Web, desktop
and Android all ship as 1.0.0 — the full list is in
[CHANGELOG.md](../CHANGELOG.md#v100--2026-09-30).
### Contents
```
- [x] Web app at ytgenerator.stream — Cloudflare Worker, deployed by Workers
Builds from main; GitHub Pages retired (moving notice until 2026-11-29)
- [x] Turnstile check before the web app; cookieless Web Analytics (web only);
legal pages served in-site; terms version 2
- [x] New interface — design system, app shell with a bottom bar on phones,
command palette (Ctrl/⌘+K), live preview, YouTube preview
- [x] Backup & restore — preview (new / already here / different), merge or
replace, undo, drag-and-drop, automatic desktop backups, History as CSV
- [x] Quick start — profile + preset pickers, Next part, New video same game,
Start over keeps the channel
- [x] Faster entry — store links pasted anywhere, game-name suggestions,
title shapes + Title order, Copy All with tags, Batch Part / Demo part,
Ctrl/⌘+S saves to History
- [x] Data that is right — GPU catalog and hardware names, tags counted the way
YouTube counts them, chapter check + Tidy up, one History entry per
video, per-field copy gating
- [x] Catalogs — EA app, Ubisoft, Battle.net, Google Play, App Store, Meta
Quest; YouTube, Threads, Kick, Reddit, Bilibili links; YouTube Shorts,
X, Threads, Bluesky captions; five Vietnamese banks
- [x] Desktop hardening — the webview never names a path, Save / Open dialogs
run from Rust, fs and shell plugins removed, one tray icon
- [x] CI — dependency review, workflow lint, OpenSSF Scorecard, REUSE, PR
titles, Rust checks, coverage thresholds, bundle budget, licence
allow-list, Cloudflare dry-run; every action pinned by SHA
```
---
## v1.1.0 — Contacts ✅ SHIPPED 2026-10-03
A copyright / DMCA email and purpose words for the split contact block, an
option to hide scrollbars, and copyright years checked in CI —
[CHANGELOG.md](../CHANGELOG.md#v110--2026-10-03).
## v1.2.0 — AI disclosure ✅ SHIPPED 2026-10-12
Content warnings for games made with generative AI (a new group of seven),
simulated gambling, in-game purchases and a tech note for upscaling /
frame-generation artifacts; a test that every warning and tech note is
translated; third-party notices, REUSE and the docs brought in line with the
code — [CHANGELOG.md](../CHANGELOG.md#v120--2026-10-12).
---
## Phase 5 — Extensions & Ecosystem (Priority: P2-P3)
**Goal**: IDE extension, CLI, community features.
**Estimated**: Ongoing
### Tasks
```
5.1 CLI tool
- [ ] Standalone Node.js CLI using engine/
@@ -263,31 +344,58 @@
- [ ] Settings sync with VS Code settings
5.3 Additional languages
- [ ] French, German, Portuguese, Russian, Thai, Arabic
- [ ] Community contribution guide for translations
- [ ] Locale validation CI check
- [x] Portuguese — shipped as Brazilian Portuguese (pt-BR) in v0.38.0,
together with Indonesian (id)
- [ ] French, German, Russian, Thai, Arabic
- [x] Community contribution guide for translations (docs/I18N.md,
CONTRIBUTING.md)
- [x] Locale validation CI check (npm run validate:locales in the
required `check` job)
5.4 Template customization
- [ ] Custom template editor in app
- [ ] Template import/export
- [ ] Template sharing (JSON format)
(Full-form templates — every editor field — already export and
import as JSON on Profiles › Templates; these items are about
editing the description templates themselves.)
5.5 Quality of life
- [ ] YouTube API integration (auto-apply description)
- [ ] Tag trend analysis (what's trending for the genre)
- [ ] Multi-channel profile support
- [x] Multi-channel profile support — one profile per channel, as many
as you like; Quick start picks one per video (v1.0.0)
```
---
## Backlog (after v1.0.0)
Ideas carried over from the v1.0.0 planning — not scheduled.
```
- [ ] Auto-fill game info from Steam through the Worker — needs rate limiting
and a decision for the desktop app
- [ ] More genres: Sports, Point & Click, MOBA, Party — the taxonomy is still
to decide
- [ ] PWA offline for the web — conflicts with the Turnstile gate in front of
the app
- [ ] PGP signature for security.txt
- [ ] Smoke tests for the main pages — needs a DOM test environment (the
suite runs in Node)
```
---
## Timeline Summary
| Phase | Scope | Days | Cumulative |
|-------|-------|------|------------|
| Phase 1 | MVP Core | 3-4 | 3-4 days |
| Phase 2 | Profiles & Presets | 2-3 | 5-7 days |
| Phase 3 | Polish & Advanced | 2-3 | 7-10 days |
| Phase 4 | Desktop App | 2-3 | 9-13 days |
| Phase 5 | Extensions | Ongoing | — |
| Phase | Scope | Days | Cumulative |
| ------- | ------------------ | ------- | ---------- |
| Phase 1 | MVP Core | 3-4 | 3-4 days |
| Phase 2 | Profiles & Presets | 2-3 | 5-7 days |
| Phase 3 | Polish & Advanced | 2-3 | 7-10 days |
| Phase 4 | Desktop App | 2-3 | 9-13 days |
| Phase 5 | Extensions | Ongoing | — |
**MVP usable after Phase 1** (~3-4 days). Full-featured after Phase 3 (~7-10 days).
**v1.0.0 shipped on 2026-09-30; the current release is v1.2.0 (2026-10-12).**
+516 -229
View File
@@ -2,17 +2,20 @@
## YTDescGen — Implementation Details
Reflects **v1.2.0**. 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
```jsonc
```json
{
"name": "yt-desc-gen",
"version": "0.20.0",
"version": "1.2.0",
"private": true,
"license": "Apache-2.0",
"type": "module",
"scripts": {
"dev": "vite",
@@ -21,55 +24,91 @@
"test": "vitest",
"test:run": "vitest run",
"test:coverage": "vitest run --coverage",
"lint": "eslint src/ --ext .ts,.tsx",
"lint:fix": "eslint src/ --ext .ts,.tsx --fix",
"lint": "eslint src/ tests/ scripts/ worker/ build-plugins/",
"lint:fix": "eslint src/ tests/ scripts/ worker/ build-plugins/ --fix",
"knip": "knip",
"typecheck": "tsc --noEmit",
"format": "prettier --write \"src/**/*.{ts,tsx,json,css}\"",
"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"
"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": {
"react": "^18.3.0",
"react-dom": "^18.3.0",
"react-router-dom": "^6.26.0",
"zustand": "^4.5.0",
"i18next": "^23.15.0",
"react-i18next": "^15.0.0",
"react-hot-toast": "^2.4.0",
"lucide-react": "^0.400.0",
"clsx": "^2.1.0"
"@fontsource-variable/inter": "^5.3.0",
"@fontsource-variable/jetbrains-mono": "^5.3.0",
"@tauri-apps/api": "^2.12.0",
"@tauri-apps/plugin-opener": "^2.7.0",
"clsx": "^2.1.1",
"cmdk": "^1.1.1",
"i18next": "^26.4.2",
"i18next-resources-to-backend": "^1.2.3",
"lucide-react": "^1.49.0",
"motion": "^13.4.6",
"radix-ui": "^1.6.7",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"react-i18next": "^17.0.15",
"react-router-dom": "^7.18.4",
"simple-icons": "^16.33.0",
"sonner": "^2.0.8",
"zustand": "^5.0.15"
},
"devDependencies": {
"@types/react": "^18.3.0",
"@types/react-dom": "^18.3.0",
"@vitejs/plugin-react": "^4.3.0",
"typescript": "^5.5.0",
"vite": "^5.4.0",
"vitest": "^2.0.0",
"@testing-library/react": "^16.0.0",
"@testing-library/jest-dom": "^6.4.0",
"tailwindcss": "^3.4.0",
"postcss": "^8.4.0",
"autoprefixer": "^10.4.0",
"eslint": "^9.0.0",
"@eslint/js": "^9.0.0",
"typescript-eslint": "^8.0.0",
"eslint-plugin-react-hooks": "^4.6.0",
"prettier": "^3.3.0",
"prettier-plugin-tailwindcss": "^0.6.0",
"@tauri-apps/cli": "^2.0.0",
"@tauri-apps/api": "^2.0.0",
"tsx": "^4.16.0"
"@eslint/js": "^10.0.1",
"@resvg/resvg-js": "2.6.2",
"@tailwindcss/postcss": "^4.3.3",
"@tauri-apps/cli": "2.12.0",
"@testing-library/jest-dom": "^7.0.1",
"@testing-library/react": "^16.3.3",
"@types/node": "^26.6.3",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"@vitejs/plugin-react": "^6.1.1",
"@vitest/coverage-v8": "^4.1.11",
"autoprefixer": "^10.6.1",
"eslint": "^10.11.0",
"eslint-plugin-react-hooks": "^7.1.1",
"knip": "^6.38.0",
"marked": "18.0.14",
"postcss": "^8.5.28",
"prettier": "^3.9.9",
"prettier-plugin-tailwindcss": "^0.8.1",
"tailwindcss": "^4.3.3",
"tsx": "^4.23.15",
"typescript": "^5.9.3",
"typescript-eslint": "^8.71.0",
"vite": "^8.3.1",
"vitest": "^4.1.11",
"wrangler": "4.144.0"
}
}
```
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`.
- **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.
- **Node 22** comes from `.node-version`, which CI, the release workflows and Cloudflare Workers Builds all read.
### tsconfig.json
```jsonc
```json
{
"compilerOptions": {
"target": "ES2020",
@@ -106,36 +145,70 @@
}
```
`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`, plus the `vitest/globals` and `node` types those need.
### 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()],
base: "/yt-desc-gen/", // GitHub Pages
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(__dirname, "./src"),
"@config": path.resolve(__dirname, "./src/config"),
"@engine": path.resolve(__dirname, "./src/engine"),
"@store": path.resolve(__dirname, "./src/store"),
"@hooks": path.resolve(__dirname, "./src/hooks"),
"@components": path.resolve(__dirname, "./src/components"),
"@pages": path.resolve(__dirname, "./src/pages"),
"@utils": path.resolve(__dirname, "./src/utils"),
"@i18n": path.resolve(__dirname, "./src/i18n"),
"@": 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: {
// Old Android System WebViews choke on Vite's modern default target.
target: isTauri ? "es2020" : undefined,
// 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: {
manualChunks: {
react: ["react", "react-dom"],
router: ["react-router-dom"],
i18n: ["i18next", "react-i18next"],
// 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;
},
},
},
@@ -143,78 +216,130 @@ export default defineConfig({
});
```
### tailwind.config.ts
What differs between the two builds:
```typescript
import type { Config } from "tailwindcss";
| | 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 | `es2020` |
export default {
content: ["./index.html", "./src/**/*.{ts,tsx}"],
darkMode: "class",
theme: {
extend: {
colors: {
surface: {
0: "var(--surface-0)", // deepest background
1: "var(--surface-1)", // card background
2: "var(--surface-2)", // elevated surface
3: "var(--surface-3)", // hover/active state
},
border: {
DEFAULT: "var(--border)",
strong: "var(--border-strong)",
},
text: {
primary: "var(--text-primary)",
secondary: "var(--text-secondary)",
muted: "var(--text-muted)",
},
accent: {
DEFAULT: "var(--accent)",
hover: "var(--accent-hover)",
muted: "var(--accent-muted)",
},
success: "var(--success)",
warning: "var(--warning)",
danger: "var(--danger)",
},
fontFamily: {
sans: ["var(--font-sans)"],
mono: ["var(--font-mono)"],
},
},
},
plugins: [],
} satisfies Config;
`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"
]
},
"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. Request flow, cookies, headers and operations: [HOSTING.md](HOSTING.md).
The Worker (`worker/`): `index.ts` (entry; injects the clock, `fetch` and random ids), `router.ts` (routing), `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
// 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;
videoType: VideoType; // 20 video types
language: SupportedLanguage;
genre: Genre;
/** 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;
partNumber?: string;
bossName?: string;
dlcName?: string;
challengeName?: string;
resolution?: string;
fps?: string;
graphicsPreset?: string;
timestamps?: string;
playlistLink?: string;
contactEmail?: string;
// Video-type specific: partNumber, bossName, dlcName, challengeName, modName, modList,
// liveUrl, scheduledTime, gachaQuestType, chapterName, questName, characterName,
// anniversaryYear, gachaVersion.
// Video settings: resolution, fps, graphicsPreset (+ graphicsPresetCustom),
// skipGraphicsSettings, rayTracingModes, frameGenVendor, frameGenMultiplier,
// upscaleQuality, 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>>;
}
@@ -222,12 +347,15 @@ export interface GeneratorOutput {
title: string;
description: string;
tags: string[];
/** The tags joined with ", " — what Copy puts on the clipboard. */
tagString: string;
charCounts: {
title: number; // YouTube limit: 100
description: number; // YouTube limit: 5000
tags: number; // YouTube limit: 500
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[];
}
@@ -235,186 +363,345 @@ export interface CharLimitWarning {
field: "title" | "description" | "tags";
current: number;
limit: number;
message: string;
message: string; // English; the UI builds its own text from the numbers
}
// YouTube official limits
// YouTube limits
export const YT_LIMITS = {
TITLE_MAX: 100,
DESCRIPTION_MAX: 5000,
TAGS_MAX: 500,
SINGLE_TAG_MAX: 30, // single tag character limit
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), 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), and values go through `formatRigValue` (`gpu:nvidia-rtx-5080` → "NVIDIA GeForce RTX 5080"). 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
// src/store/editor-store.ts (abridged)
import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
import type { GeneratorInput } from "@engine/types";
import { DEFAULTS } from "@config/defaults";
interface EditorState extends GeneratorInput {
// Actions
set: <K extends keyof GeneratorInput>(key: K, value: GeneratorInput[K]) => void;
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;
loadProfile: (profile: Partial<GeneratorInput>) => void;
loadPreset: (preset: Partial<GeneratorInput>) => void;
setStoreLinkType: (platformId: string, type: StoreLinkType) => void;
loadProfile: (profile: Partial<EditorData>) => void;
loadPreset: (preset: Partial<EditorData>) => void;
reset: () => void;
}
export const useEditorStore = create<EditorState>()(
/** Bump together with a new step in migrateEditorState. */
export const EDITOR_STORE_VERSION = 20;
export const useEditorStore = create<EditorData & EditorActions>()(
persist(
(set) => ({
...DEFAULTS.editor,
...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 },
})),
loadProfile: (profile) => set((state) => ({ ...state, ...profile })),
loadPreset: (preset) => set((state) => ({ ...state, ...preset })),
reset: () => set(DEFAULTS.editor),
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),
partialize: (state) => {
// Exclude actions from persistence
const { set: _s, setNested: _sn, loadProfile: _lp, loadPreset: _lpre, reset: _r, ...data } = state;
return data;
},
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 */
}
```
## 4. GitHub Actions CI
| Store | localStorage key | Version | Migration (exported) |
| ------------------ | ------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------- |
| `useEditorStore` | `ytdescgen-editor-draft` | `EDITOR_STORE_VERSION` = 20 | `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.
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` |
| `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`) |
| `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
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main, dev]
pull_request:
branches: [main]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run typecheck
- run: npm run lint
- run: npm run validate:locales
- run: npm run test:run
- run: npm run build
- run: npm ci
# 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
# 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: npx wrangler deploy --dry-run --outdir .wrangler/dry-run
```
```yaml
# .github/workflows/deploy-web.yml
name: Deploy to GitHub Pages
- **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.
- 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 and Rust cancel superseded runs through a `concurrency` group, except on `main`, where each commit's result is a record the release process reads back.
on:
push:
branches: [main]
**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).
permissions:
contents: read
pages: write
id-token: write
**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.
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run build
- uses: actions/configure-pages@v6
- uses: actions/upload-pages-artifact@v5
with:
path: dist
- id: deployment
uses: actions/deploy-pages@v5
```
## 6. Testing Strategy
## 5. Testing Strategy
Vitest runs `tests/**/*.test.{ts,tsx}` and `src/**/*.test.{ts,tsx}` in the **node** environment, with `globals: true`: 984 tests in 51 files at v1.2.0. Directories: `tests/engine`, `store`, `utils` (backup detect / sanitize / restore, quick entry, validation, the migration page), `worker` (router, 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 result = buildTitle({
gameName: "Elden Ring",
videoType: "full",
language: "en",
});
expect(result).toBe("Elden Ring — Gameplay No Commentary");
const t = createMockT("en");
expect(buildTitle(makeInput(), t)).toBe("Elden Ring — Gameplay No Commentary");
});
it("generates part title with number", () => {
const result = buildTitle({
gameName: "Elden Ring",
videoType: "part",
partNumber: "5",
language: "en",
});
const t = createMockT("en");
const result = buildTitle(makeInput({ videoType: "part", partNumber: "5" }), t);
expect(result).toBe("Elden Ring — Part 5 — Gameplay No Commentary");
});
it("generates boss title in Japanese", () => {
const result = buildTitle({
gameName: "エルデンリング",
videoType: "boss",
bossName: "マルギット",
language: "ja",
});
expect(result).toBe("エルデンリング — マルギット ボス戦 — Gameplay No Commentary");
});
it("warns when title exceeds 100 characters", () => {
// ... test char limit warning
});
});
```
## 6. YouTube Character Limits Reference
`npm run test:coverage` (what CI runs) measures `src/engine/**`, `worker/**` and `build-plugins/**` with V8 and fails below these thresholds — the engine is what the whole app trusts, the Worker is what guards the site:
| Field | Limit | Behavior When Exceeded |
|-------|-------|----------------------|
| Title | 100 chars | YouTube truncates with "..." |
| Description | 5,000 chars | YouTube silently truncates |
| Tags (total) | 500 chars | YouTube rejects all tags |
| Single Tag | 30 chars | YouTube rejects that tag |
| Hashtags in description | 60 max, 3 shown | First 3 shown above title |
| Playlist title | 150 chars | Truncated |
| 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`, and `tests/worker/headers.test.ts` (keeps the Worker's baseline headers in step with `public/_headers`). 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`.
+191 -81
View File
@@ -1,15 +1,22 @@
# Danh mục Nội dung
Bản kê khai tĩnh cho mọi loại video, thể loại game, và cảnh báo nội dung trong editor của YTDescGen. Cập nhật thủ công — khi thêm mục mới vào một trong các file nguồn dưới đây, **thêm dòng tương ứng vào đây** trong cùng PR.
Bản kê khai tĩnh cho mọi loại video, thể loại game, cảnh báo nội dung, ghi chú kỹ thuật, cửa hàng, trường link và nền tảng đăng chéo trong editor của YTDescGen (tính đến v1.2.0). Cập nhật thủ công — khi thêm mục mới vào một trong các file nguồn dưới đây, **thêm dòng tương ứng vào đây** trong cùng PR.
File này tồn tại để **minh bạch** — bất kỳ ai tò mò về việc editor có thể mô tả được gì (mà không cần cài app hay đọc source) đều có thể quét trong một phút.
**Bản gốc tiếng Anh:** [`docs/CONTENT-INVENTORY.md`](../../CONTENT-INVENTORY.md).
**Nguồn tham chiếu (source of truth):**
- Loại video: [`src/config/video-types.ts`](../../../src/config/video-types.ts)
- Thể loại game: [`src/config/genres.ts`](../../../src/config/genres.ts)
- Cảnh báo nội dung: [`src/config/content-warning-groups.ts`](../../../src/config/content-warning-groups.ts)
- Ghi chú kỹ thuật: [`src/config/tech-note-groups.ts`](../../../src/config/tech-note-groups.ts)
- Cửa hàng: [`src/config/platforms.ts`](../../../src/config/platforms.ts)
- Link mạng xã hội & donate: [`src/config/social-fields.ts`](../../../src/config/social-fields.ts)
- Link cộng đồng: [`src/components/editor/CommunityEditor.tsx`](../../../src/components/editor/CommunityEditor.tsx)
- Ngân hàng Việt Nam: [`src/config/vietnamese-banks.ts`](../../../src/config/vietnamese-banks.ts)
- Nền tảng đăng chéo: [`src/config/social-platforms.ts`](../../../src/config/social-platforms.ts)
---
@@ -17,87 +24,87 @@ File này tồn tại để **minh bạch** — bất kỳ ai tò mò về việ
Mỗi loại video kéo theo một template description, cấu trúc title, và tag bias riêng. Cột "Trường bổ sung" liệt kê các trường editor sẽ hiển thị khi chọn loại video tương ứng.
| Icon | Loại | Trường bổ sung |
|---|---|---|
| 🎮 | Gameplay đầy đủ | — |
| 📂 | Gameplay theo phần | Số phần |
| 🎬 | Demo đầy đủ | — |
| 🎞 | Demo theo phần | Số phần |
| 👹 | Đấu trùm | Tên trùm |
| 💀 | Đấu trùm không trúng đòn | Tên trùm |
| 🏁 | Kết thúc / Toàn bộ Ending | — |
| ⚡ | Speedrun | — |
| 💯 | Hoàn thành 100% | — |
| 📦 | Nội dung DLC | Tên DLC |
| 🔄 | New Game+ | — |
| 🏆 | Thử thách | Tên thử thách |
| 📌 | Nhiệm vụ phụ | — |
| 🔍 | Bí mật / Ẩn | — |
| ⚖️ | So sánh đồ họa | — |
| 📘 | Hướng dẫn không lời | — |
| 🧩 | Chơi với Mod | Tên Mod |
| ⭐ | Toàn bộ vật phẩm sưu tầm | — |
| 🔴 | Livestream | URL Live, Thời gian dự kiến |
| 🎴 | Nhiệm vụ Gacha | Loại nhiệm vụ, Tên chapter, Tên quest, Số phần |
| Icon | Loại | Trường bổ sung |
| ---- | ------------------------- | ---------------------------------------------- |
| 🎮 | Gameplay đầy đủ | — |
| 📂 | Gameplay theo phần | Số phần |
| 🎬 | Demo đầy đủ | — |
| 🎞 | Demo theo phần | Số phần |
| 👹 | Đấu trùm | Tên trùm |
| 💀 | Đấu trùm không trúng đòn | Tên trùm |
| 🏁 | Kết thúc / Toàn bộ Ending | — |
| ⚡ | Speedrun | — |
| 💯 | Hoàn thành 100% | — |
| 📦 | Nội dung DLC | Tên DLC |
| 🔄 | New Game+ | — |
| 🏆 | Thử thách | Tên thử thách |
| 📌 | Nhiệm vụ phụ | — |
| 🔍 | Bí mật / Ẩn | — |
| ⚖️ | So sánh đồ họa | — |
| 📘 | Hướng dẫn không lời | — |
| 🧩 | Chơi với Mod | Tên Mod |
| ⭐ | Toàn bộ vật phẩm sưu tầm | — |
| 🔴 | Livestream | URL Live, Thời gian dự kiến |
| 🎴 | Nhiệm vụ Gacha | Loại nhiệm vụ, Tên chapter, Tên quest, Số phần |
---
## 2. Thể loại game (41)
## 2. Thể loại game (42)
Thể loại được chọn ảnh hưởng đến định dạng title, tag pool, và (khi cấu hình ở Settings → Genre Playlists) gợi ý playlist trong pinned comment.
Thể loại được chọn (tối đa 3 cho mỗi video) ảnh hưởng đến định dạng title, tag pool, và (khi cấu hình ở Settings → Genre Playlists) gợi ý playlist trong pinned comment.
Các nhóm bulk-select trong editor: **All RPGs** (rpg + jrpg + action_rpg + crpg), **All Shooters** (fps + arena_shooter + tactical_fps + boomer_shooter + extraction_shooter + shmup), **All Horror** (horror + survival_horror + psychological_horror).
Các nhóm bulk-select trong editor: **All RPGs** (rpg + jrpg + action_rpg + crpg), **All Shooters** (fps + arena_shooter + tactical_fps + boomer_shooter + extraction_shooter + shmup), **All Horror** (horror + survival_horror + psychological_horror). Bấm một nhóm sẽ thay lựa chọn hiện tại bằng ba thể loại đầu tiên của nhóm đó.
| Icon | Thể loại |
|---|---|
| ⚔️ | Hành động / Phiêu lưu |
| 🗡 | Hack & Slash |
| 👊 | Beat 'em Up |
| 🦘 | Platformer |
| 👻 | Kinh dị / Sinh tồn |
| 🧟 | Kinh dị Sinh tồn |
| 🧠 | Kinh dị Tâm lý |
| 🛡 | RPG |
| 🎎 | JRPG |
| 🏹 | Action RPG |
| 📜 | CRPG / Góc nhìn từ trên |
| 🔫 | FPS / Bắn súng |
| 🎯 | Bắn súng Arena |
| 🎖 | Bắn súng Chiến thuật |
| 💥 | Boomer Shooter |
| 🎒 | Extraction Shooter |
| 🛸 | SHMUP / Bullet Hell |
| 🌍 | Thế giới mở / Sandbox |
| 🕹 | Indie |
| 💀 | Souls-like |
| 🏎 | Đua xe / Thể thao |
| 📖 | Cốt truyện |
| 🏗 | Mô phỏng / Chiến thuật |
| 🏙 | Xây thành |
| 🥊 | Đối kháng |
| 🥷 | Lén lút / Gián điệp |
| ⛏ | Sinh tồn / Chế tạo |
| 🎲 | Roguelike / Roguelite |
| 🗺 | Metroidvania |
| 🌐 | MMO / Trực tuyến |
| 🎵 | Âm nhạc / Nhịp điệu |
| 🧩 | Giải đố |
| 🏰 | Tower Defense |
| 🃏 | Bài / Card |
| 🎴 | Deck Builder |
| 🤖 | Auto Battler |
| 🏆 | Battle Royale |
| ♟ | Chiến thuật theo lượt |
| 🚀 | Không gian / Sci-Fi |
| 🌾 | Nông trại / Life Sim |
| 🎬 | FMV / Phim tương tác |
| 💬 | Visual Novel |
| Icon | Thể loại |
| ---- | ----------------------- |
| ⚔️ | Hành động / Phiêu lưu |
| 🗡 | Hack & Slash |
| 👊 | Beat 'em Up |
| 🦘 | Platformer |
| 👻 | Kinh dị / Sinh tồn |
| 🧟 | Kinh dị Sinh tồn |
| 🧠 | Kinh dị Tâm lý |
| 🛡 | RPG |
| 🎎 | JRPG |
| 🏹 | Action RPG |
| 📜 | CRPG / Góc nhìn từ trên |
| 🔫 | FPS / Bắn súng |
| 🎯 | Bắn súng Arena |
| 🎖 | Bắn súng Chiến thuật |
| 💥 | Boomer Shooter |
| 🎒 | Extraction Shooter |
| 🛸 | SHMUP / Bullet Hell |
| 🌍 | Thế giới mở / Sandbox |
| 🕹 | Indie |
| 💀 | Souls-like |
| 🏎 | Đua xe / Thể thao |
| 📖 | Cốt truyện |
| 🏗 | Mô phỏng / Chiến thuật |
| 🏙 | Xây thành |
| 🥊 | Đối kháng |
| 🥷 | Lén lút / Gián điệp |
| ⛏ | Sinh tồn / Chế tạo |
| 🎲 | Roguelike / Roguelite |
| 🗺 | Metroidvania |
| 🌐 | MMO / Trực tuyến |
| 🎵 | Âm nhạc / Nhịp điệu |
| 🧩 | Giải đố |
| 🏰 | Tower Defense |
| 🃏 | Bài / Card |
| 🎴 | Deck Builder |
| 🤖 | Auto Battler |
| 🏆 | Battle Royale |
| ♟ | Chiến thuật theo lượt |
| 🚀 | Không gian / Sci-Fi |
| 🌾 | Nông trại / Life Sim |
| 🎬 | FMV / Phim tương tác |
| 💬 | Visual Novel |
---
## 3. Cảnh báo nội dung (248, chia nhóm)
## 3. Cảnh báo nội dung (257, chia nhóm)
Cảnh báo được chọn sẽ thêm vào khối `⚠ CONTENT WARNINGS` trong description, trước phần timestamp. Mỗi nhóm có thể thu gọn trong editor; cảnh báo hiển thị theo thứ tự người dùng chọn.
Cảnh báo được chọn sẽ hiển thị trong khối cảnh báo nội dung của description (`▸ ⚠️ CẢNH BÁO NỘI DUNG` khi output là tiếng Việt), ngay sau khối cấu hình máy (và danh sách mod, với loại Chơi với Mod). Mỗi nhóm có thể thu gọn trong editor; cảnh báo hiển thị theo thứ tự người dùng chọn.
### Spoiler (6)
@@ -127,13 +134,13 @@ Cảnh gây lo âu · Trầm cảm · Rối loạn ăn uống · Sử dụng ch
Tự kỷ / thần kinh đa dạng · ADHD / rối loạn tập trung · Hikikomori / ẩn dật xã hội · NEET (không học không làm) · Lo âu xã hội · Cô lập xã hội / cô đơn · Tâm thần phân liệt / loạn thần · Burnout / kiệt sức · Mặc cảm sống sót · Bị bỏ rơi / sang chấn · Quan hệ parasocial · Gaslighting / thao túng · Hội chứng Stockholm · Nghiện game / cờ bạc · Khủng hoảng hiện sinh · Hội chứng kẻ mạo danh · Khủng hoảng tuổi trung niên · Khủng hoảng tuổi 1/4 · Quấy rối nơi làm việc · Áp lực vai trò giới · Miệt thị ngoại hình (body shaming) · Chuẩn mực ngoại hình phi thực tế
### Internet / Đời sống số (18)
### Internet / Đời sống số (19)
Bắt nạt / quấy rối qua mạng · Doxxing / phơi bày thông tin cá nhân · Trolling / phá game · Văn hóa tẩy chay / bêu rếu công khai · Nghiện mạng xã hội · Lướt tin tiêu cực vô độ (doomscrolling) · Hội chứng sợ bỏ lỡ (FOMO) · Tin giả / thông tin sai lệch · Lừa đảo trực tuyến / phishing · Giả mạo danh tính trên mạng (catfishing) · Deepfake / nội dung giả mạo bằng AI · Theo dõi / rình rập qua mạng · Trào lưu / thử thách nguy hiểm trên mạng · Văn hóa influencer / câu tương tác · Cực đoan hóa qua mạng / buồng vang thông tin · Loot box / cơ chế gacha · Chủ đề AI / trí tuệ nhân tạo · Riêng tư dữ liệu / giám sát diện rộng
Bắt nạt / quấy rối qua mạng · Doxxing / phơi bày thông tin cá nhân · Trolling / phá game · Văn hóa tẩy chay / bêu rếu công khai · Nghiện mạng xã hội · Lướt tin tiêu cực vô độ (doomscrolling) · Hội chứng sợ bỏ lỡ (FOMO) · Tin giả / thông tin sai lệch · Lừa đảo trực tuyến / phishing · Giả mạo danh tính trên mạng (catfishing) · Deepfake / nội dung giả mạo bằng AI · Theo dõi / rình rập qua mạng · Trào lưu / thử thách nguy hiểm trên mạng · Văn hóa influencer / câu tương tác · Cực đoan hóa qua mạng / buồng vang thông tin · Loot box / cơ chế gacha · Mua vật phẩm trong game · Chủ đề AI / trí tuệ nhân tạo · Riêng tư dữ liệu / giám sát diện rộng
### Nội dung nhạy cảm / 18+ (66)
### Nội dung nhạy cảm / 18+ (67)
Máu me · 18+ · Trang phục hở hang · Kh*a th*n một phần · Tạo hình nhân vật bị t*nh d*c hóa · Yếu tố fan service · Tư thế / góc quay gợi cảm · Hình ảnh gây khó chịu · B*o h*nh động vật · Trẻ em chịu tác động · B*o h*nh gia đình · Tham chiếu x*m h*i t*nh d*c · Tra tấn · Tôn giáo · Tác động vật lý chiến tranh · Phân biệt đối xử · Tác động vật lý từ chính quyền · Hút thuốc / uống rượu · G*ết người chi tiết · Tà giáo / huyền bí · Thao túng tâm lý · Mất mát / đau buồn · Bắt cóc · Phát ngôn thù hận · Tội ác lịch sử · Nô lệ · Khủng bố · Bắt nạt · Thử nghiệm trên người · Ăn thịt người · Hạt nhân / phóng xạ · Kỳ thị người đồng tính / LGBTQ+ (homophobia) · Kỳ thị người chuyển giới (transphobia) · Bài ngoại (xenophobia) · Cực đoan chính trị · Cực đoan tôn giáo / cuồng tín · Diệt chủng / thanh trừng sắc tộc · Thánh chiến / xung đột tôn giáo · Đại nạn Holocaust · Nội chiến · Xả súng hàng loạt / xả súng trường học · Chủ nghĩa thực dân / đế quốc · Tuyên truyền nhà nước · Nhà nước giám sát / dystopia · Thuyết âm mưu · Kiểm duyệt / cấm phát ngôn · Xung đột sắc tộc / chủng tộc · Khủng hoảng tị nạn · Cách mạng / nổi dậy · Ám sát chính trị · Đảo chính · Toà án dị giáo / săn phù thủy · Lao động cưỡng bức · Chủ nghĩa dân tộc cực đoan · Treo c* / siết c* · Cảnh ch*t đuối · Cảnh thiêu s*ng · Cảnh ngạt th* · Bị trói / cầm tù tra tấn · Cảnh hành quyết công khai · Cảnh chặt đầu · Cảnh đâm xuyên cơ thể · Thương vong hàng loạt · Tác động vật lý bằng phương tiện · Cảnh sử dụng quá liều · Ngã / nhảy từ trên cao
Máu me · 18+ · Trang phục hở hang · Kh*a th*n một phần · Tạo hình nhân vật bị t*nh d*c hóa · Yếu tố fan service · Tư thế / góc quay gợi cảm · Hình ảnh gây khó chịu · B*o h*nh động vật · Trẻ em chịu tác động · B*o h*nh gia đình · Tham chiếu x*m h*i t*nh d*c · Tra tấn · Tôn giáo · Tác động vật lý chiến tranh · Phân biệt đối xử · Tác động vật lý từ chính quyền · Hút thuốc / uống rượu · Cờ bạc mô phỏng · G*ết người chi tiết · Tà giáo / huyền bí · Thao túng tâm lý · Mất mát / đau buồn · Bắt cóc · Phát ngôn thù hận · Tội ác lịch sử · Nô lệ · Khủng bố · Bắt nạt · Thử nghiệm trên người · Ăn thịt người · Hạt nhân / phóng xạ · Kỳ thị người đồng tính / LGBTQ+ (homophobia) · Kỳ thị người chuyển giới (transphobia) · Bài ngoại (xenophobia) · Cực đoan chính trị · Cực đoan tôn giáo / cuồng tín · Diệt chủng / thanh trừng sắc tộc · Thánh chiến / xung đột tôn giáo · Đại nạn Holocaust · Nội chiến · Xả súng hàng loạt / xả súng trường học · Chủ nghĩa thực dân / đế quốc · Tuyên truyền nhà nước · Nhà nước giám sát / dystopia · Thuyết âm mưu · Kiểm duyệt / cấm phát ngôn · Xung đột sắc tộc / chủng tộc · Khủng hoảng tị nạn · Cách mạng / nổi dậy · Ám sát chính trị · Đảo chính · Toà án dị giáo / săn phù thủy · Lao động cưỡng bức · Chủ nghĩa dân tộc cực đoan · Treo c* / siết c* · Cảnh ch*t đuối · Cảnh thiêu s*ng · Cảnh ngạt th* · Bị trói / cầm tù tra tấn · Cảnh hành quyết công khai · Cảnh chặt đầu · Cảnh đâm xuyên cơ thể · Thương vong hàng loạt · Tác động vật lý bằng phương tiện · Cảnh sử dụng quá liều · Ngã / nhảy từ trên cao
### Kinh dị nặng (12)
@@ -147,15 +154,118 @@ Lần đầu chơi (blind) · Không spoiler trong chat · Chế độ easy / st
Dùng mod · Bật cheat / debug · Dùng glitch · Có guide hỗ trợ · Game mục đích giáo dục / tuyên truyền
### Nội dung do AI tạo (7)
Nội dung do AI tạo (chung) · Hình ảnh / đồ họa AI · Giọng nói AI / tổng hợp · Nhạc / âm thanh AI · Văn bản / thoại do AI viết · AI tạo nội dung trực tiếp khi chơi · Nhà phát triển có công bố dùng AI
Bản thân game được làm hoặc chạy bằng AI tạo sinh — còn game có cốt truyện _về_ AI là "Chủ đề AI / trí tuệ nhân tạo" ở trên. Cách chia theo phần công bố AI của Steam: nội dung làm bằng AI trong quá trình phát triển rồi đưa vào game, và nội dung AI tạo trực tiếp khi đang chơi. Dịch máy là trường **Language patch** trong Ghi chú lượt chơi nên không có cảnh báo riêng ở đây. YouTube không yêu cầu gắn nhãn nội dung chỉnh sửa / tổng hợp cho video gameplay; các dòng này là để người xem biết.
---
## 4. Bảo trì
## 4. Ghi chú kỹ thuật (25, chia nhóm)
Ghi chú được chọn hiển thị trong khối `▸ 🛠 TECH NOTES` (`▸ 🛠 GHI CHÚ KỸ THUẬT` khi output là tiếng Việt) ngay sau cảnh báo nội dung, theo thứ tự người dùng chọn. Chúng nói về bản quay, không phải về game. Những thông tin đã có trường riêng — độ khó, ending đã chiếu, language patch, phiên bản game, upscaler và frame generation trong Video settings — không lặp lại ở đây.
### Âm thanh (5)
Tắt tiếng (bản quyền) · Giảm volume (bản quyền) · Thay nhạc (bản quyền) · Chỉ tắt cutscene · Giữ audio gốc (rủi ro claim)
### Chất lượng video (4)
Độ phân giải thấp (phần cứng) · Hạ đồ họa (hiệu năng) · Sụt FPS (phần cứng) · Lỗi hình do upscaling / frame gen
### Lỗi quay (4)
Bug là từ game · Giữ crash (minh bạch) · Cắt loading screen · Có thể có lỗi OBS
### Ghi chú cách chơi (8)
KHÔNG phải no-hit run · Không phải walkthrough mượt · Giải trí, không bình luận · Nhiều lần chết · Khám phá chậm · Có thể bí ở puzzle · Cắt phần cày · Không phải speedrun
### Sản xuất & ghi nhận (4)
Khám phá (skip combat) · Edit cho hợp nhịp · Ủng hộ nhà phát triển · Lỗi kết nối online
---
## 5. Cửa hàng (15 + trang nhà phát hành)
Mỗi cửa hàng có một ô link riêng. Dán link cửa hàng vào bất kỳ đâu trong editor, link sẽ tự vào đúng ô; link đầu tiên còn đặt luôn nền tảng của video, và tên tìm kiếm của nền tảng đó được dùng trong tag. Mỗi link được đánh dấu là trả phí, miễn phí hoặc demo.
| Cửa hàng | Link được chấp nhận | Tên dùng trong tag |
| ------------------------------------ | ----------------------------------------------------------------------- | ------------------ |
| Steam | `store.steampowered.com/app/…` (cả `/sub/`, `/bundle/` và `s.team/a/…`) | Steam |
| Epic Games Store | `store.epicgames.com/…` | Epic Games |
| PlayStation Store | `store.playstation.com/…` | PlayStation |
| Xbox / Microsoft Store | `xbox.com/…`, `apps.microsoft.com/…`, các trang Microsoft Store | Xbox |
| Nintendo eShop | `nintendo.com/…` và các trang Nintendo theo khu vực | Nintendo Switch |
| GOG | `gog.com/…` | GOG |
| itch.io | `<dev>.itch.io/<game>` | itch.io |
| Humble Bundle | `humblebundle.com/…` | Humble Bundle |
| Amazon Luna | `luna.amazon.com/…`, các cửa hàng Amazon | Amazon Luna |
| EA app | `ea.com/…` | EA app |
| Ubisoft Store | `store.ubisoft.com/…`, `ubisoft.com/…` | Ubisoft Connect |
| Battle.net | `shop.battle.net/…` và các host theo khu vực | Battle.net |
| Google Play | `play.google.com/store/apps/details?id=…` | Android |
| App Store | `apps.apple.com/…` | iOS |
| Meta Quest Store | `meta.com/…`, `oculus.com/…` | Meta Quest |
| Trang nhà phát hành / nhà phát triển | mọi link `https://` | — |
---
## 6. Link mạng xã hội, donate & cộng đồng
### Donate (5)
Ko-fi · Patreon · Buy Me a Coffee · PayPal · Streamlabs
### Mạng xã hội (17)
GitHub · YouTube · X (Twitter) · Discord · Twitch · Kick · TikTok · Instagram · Threads · Bluesky · Mastodon · Facebook · Facebook Page · Reddit · Bilibili · Telegram · Website
### Cộng đồng (5)
Cộng đồng Messenger · Nhóm Signal · Nhóm chat Instagram · Nhóm Facebook · Nhóm Zalo (chỉ khi output là tiếng Việt)
### Ngân hàng Việt Nam (37)
Dùng cho khối Donate (Việt Nam) — chuyển khoản ngân hàng, MoMo và ZaloPay — khối này chỉ hiển thị khi output là tiếng Việt. Mục "Khác (nhập tay)" cho phép gõ tên bất kỳ ngân hàng nào; profile còn lưu tên cũ của một ngân hàng đã đổi tên sẽ được gợi ý tên mới.
- **Ngân hàng thương mại nhà nước (4):** Vietcombank · BIDV · VietinBank · Agribank
- **Ngân hàng TMCP (24):** Techcombank · MB Bank · ACB · VPBank · TPBank · Sacombank · HDBank · VIB · SHB · Eximbank · OCB · MSB · LPBank · SeABank · ABBank · BAC A Bank · PVcomBank · NCB · Nam A Bank · KienlongBank · Saigonbank · VietABank · Vietbank · BVBank
- **Đổi tên năm 2025, và ngân hàng số (5):** MBV (trước là OceanBank) · VCBNeo (trước là CBBank) · Vikki Bank (trước là DongA Bank) · Cake by VPBank · Timo
- **Ngân hàng 100% vốn nước ngoài (4):** HSBC Vietnam · Standard Chartered · Shinhan Bank · UOB Vietnam
---
## 7. Nền tảng đăng chéo (7)
Tab Mạng xã hội dùng lại chính dữ liệu trong editor để tạo caption video ngắn. Khi caption vượt giới hạn của nền tảng, các khối tùy chọn sẽ bị bỏ bớt (cảnh báo nội dung bị bỏ trước); số hashtag được giới hạn theo từng nền tảng.
| Nền tảng | Giới hạn caption | Hashtag |
| --------------- | ------------------------------------------------------------------------------- | -------------- |
| TikTok | 4.000 | không giới hạn |
| YouTube Shorts | 5.000 | tối đa 5 |
| Instagram Reels | 2.200 | không giới hạn |
| Facebook Reels | 2.200 | không giới hạn |
| X | 280, đếm theo cách của X (chữ CJK, chữ tiếng Việt có dấu và emoji tính gấp đôi) | tối đa 3 |
| Threads | 500 | 1 |
| Bluesky | 300 | tối đa 3 |
---
## 8. Bảo trì
Khi thêm mục mới vào bất kỳ file nguồn nào:
1. **Loại video** → thêm vào [`src/config/video-types.ts`](../../../src/config/video-types.ts) VÀ thêm dòng vào mục 1 ở trên.
2. **Thể loại** → thêm vào [`src/config/genres.ts`](../../../src/config/genres.ts) VÀ thêm dòng vào mục 2.
3. **Cảnh báo nội dung** → thêm vào nhóm phù hợp ở [`src/config/content-warning-groups.ts`](../../../src/config/content-warning-groups.ts) VÀ thêm label vào đúng nhóm ở mục 3 — giữ số đếm trong tiêu đề chính xác.
4. Cập nhật cả bản gốc EN tại [`docs/CONTENT-INVENTORY.md`](../../CONTENT-INVENTORY.md) trong cùng PR.
1. **Loại video** → thêm vào [`src/config/video-types.ts`](../../../src/config/video-types.ts) (kèm title, câu mở đầu và lời chào pinned comment trong mọi file `templates.json`) VÀ thêm dòng vào mục 1 ở trên.
2. **Thể loại** → thêm vào [`src/config/genres.ts`](../../../src/config/genres.ts) (kèm tag pool và từ khóa tìm kiếm trong `src/engine/tag-generator.ts` — có test giữ hai bên khớp nhau) VÀ thêm dòng vào mục 2.
3. **Cảnh báo nội dung** → thêm id vào `CONTENT_WARNINGS` trong `src/engine/types.ts` và vào nhóm phù hợp ở [`src/config/content-warning-groups.ts`](../../../src/config/content-warning-groups.ts), kèm label trong editor và dòng description ở mọi locale và `_schema.json` (thiếu là test báo lỗi), VÀ thêm label vào đúng nhóm ở mục 3 — giữ số đếm trong tiêu đề chính xác.
4. **Ghi chú kỹ thuật** → tương tự với `TECH_NOTES` và [`src/config/tech-note-groups.ts`](../../../src/config/tech-note-groups.ts) VÀ mục 4.
5. **Cửa hàng** → thêm vào [`src/config/platforms.ts`](../../../src/config/platforms.ts) (URL pattern và `tagName`; có thể thêm hàm đọc tên game trong `src/utils/url-extractors.ts`) VÀ thêm dòng vào mục 5.
6. **Link mạng xã hội / donate** → thêm vào [`src/config/social-fields.ts`](../../../src/config/social-fields.ts) (kèm label `social.<id>` trong mọi file `ui.json`) VÀ thêm vào mục 6.
7. **Ngân hàng Việt Nam** → thêm vào [`src/config/vietnamese-banks.ts`](../../../src/config/vietnamese-banks.ts) — ngân hàng đổi tên thì thêm tên mới và ánh xạ tên cũ trong `VIETNAMESE_BANK_RENAMES` — VÀ cập nhật mục 6.
8. **Nền tảng đăng chéo** → thêm vào [`src/config/social-platforms.ts`](../../../src/config/social-platforms.ts) (kèm label `socialPost.platforms.<id>` trong mọi file `ui.json`) VÀ thêm dòng vào mục 7.
9. Cập nhật cả bản gốc EN tại [`docs/CONTENT-INVENTORY.md`](../../CONTENT-INVENTORY.md) trong cùng PR.
Sai lệch giữa file này và file nguồn được xem là lỗi tài liệu — mở issue hoặc PR.
+138 -38
View File
@@ -2,20 +2,20 @@
> **Lưu ý dịch thuật:** Tiếng Anh là phiên bản chính ([`docs/DEVELOPMENT.md`](../../DEVELOPMENT.md)). Bản tiếng Việt này có thể chậm cập nhật một vài commit.
Hướng dẫn này bao gồm cách cài đặt YTDescGen để phát triển cục bộ trên Windows, macOS hoặc Linux. Ứng dụng là một web app Vite/React với tùy chọn vỏ desktop Tauri.
Hướng dẫn này bao gồm cách cài đặt YTDescGen để phát triển cục bộ trên Windows, macOS hoặc Linux. Ứng dụng là một web app Vite/React, kèm vỏ Tauri (tùy chọn) cho desktop và Android. Bản web chạy tại [ytgenerator.stream](https://ytgenerator.stream) thông qua một Cloudflare Worker — xem [HOSTING.md](../../HOSTING.md).
## Cấu hình máy tham chiếu
Cấu hình máy đã dùng để phát triển và phát hành dự án:
| Thành phần | Thông số |
| --- | --- |
| OS | Windows 11 Pro (24H2 trở lên) |
| CPU | x86-64 hiện đại — 6 nhân trở lên có AVX2 (Intel gen 11 / AMD Zen 3 hoặc mới hơn) |
| GPU | Rời hoặc tích hợp — backend WebView2 của Tauri chạy thoải mái trên iGPU |
| RAM | Tối thiểu 16 GB, khuyến nghị 32 GB để chạy song song typecheck + dev server |
| Lưu trữ | 5 GB trống cho `node_modules` + `target/` Cargo sau khi build Tauri đầy đủ |
| Màn hình | Tối thiểu 1920×1080; layout mobile đã test đến 360×640 |
| Thành phần | Thông số |
| ---------- | -------------------------------------------------------------------------------- |
| OS | Windows 11 Pro (24H2 trở lên) |
| CPU | x86-64 hiện đại — 6 nhân trở lên có AVX2 (Intel gen 11 / AMD Zen 3 hoặc mới hơn) |
| GPU | Rời hoặc tích hợp — backend WebView2 của Tauri chạy thoải mái trên iGPU |
| RAM | Tối thiểu 16 GB, khuyến nghị 32 GB để chạy song song typecheck + dev server |
| Lưu trữ | 5 GB trống cho `node_modules` + `target/` Cargo sau khi build Tauri đầy đủ |
| Màn hình | Tối thiểu 1920×1080; layout mobile đã test đến 360×640 |
macOS và Linux đều dùng được để phát triển. Build release Tauri được cross-compile hoặc chạy trên CI riêng — xem [PACKAGING.md](../../PACKAGING.md).
@@ -23,13 +23,13 @@ macOS và Linux đều dùng được để phát triển. Build release Tauri
Cài theo thứ tự:
| Công cụ | Phiên bản | Lý do |
| --- | --- | --- |
| **Node.js** | `>= 22.12.0` | Vite 8 yêu cầu Node `^20.19` hoặc `>= 22.12`. Dùng [nvm](https://github.com/nvm-sh/nvm) hoặc [fnm](https://github.com/Schniz/fnm). |
| **npm** | đi kèm Node 22 | Dự án dùng npm; `pnpm` và `yarn` chưa test. |
| **Rust** | stable, `>= 1.78` | Bắt buộc cho build Tauri. Cài qua [rustup](https://rustup.rs/). |
| **Python** | `3.12` | Tùy chọn — chỉ cần cho một số tooling Tauri trên Windows. |
| **Tauri prerequisites** | theo OS | Xem <https://v2.tauri.app/start/prerequisites/>. |
| Công cụ | Phiên bản | Lý do |
| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Node.js** | **22** — đúng phiên bản trong `.node-version` | CI, các workflow release và Cloudflare Workers Builds đều đọc `.node-version`. Vite 8 cần Node `^20.19` hoặc `>= 22.12`, còn wrangler cần `>= 22`, nên hãy dùng 22.12 trở lên. Dùng [nvm](https://github.com/nvm-sh/nvm) hoặc [fnm](https://github.com/Schniz/fnm) (fnm đọc được `.node-version`). |
| **npm** | đi kèm Node 22 | Dự án dùng npm; `pnpm` và `yarn` chưa test. |
| **Rust** | stable, `>= 1.90` | Bắt buộc cho bản build Tauri desktop và Android (Tauri 2.12 cần Rust 1.90). Cài qua [rustup](https://rustup.rs/); profile mặc định đã có sẵn `rustfmt` và `clippy`. |
| **Python** | `3.12` | Tùy chọn — chỉ cần cho một số tooling Tauri trên Windows. |
| **Tauri prerequisites** | theo OS | Xem <https://v2.tauri.app/start/prerequisites/>. |
### Windows
@@ -54,7 +54,7 @@ Quy trình tham chiếu dùng **JetBrains 2026.x** (WebStorm hoặc RustRover) l
- Bật plugin **Tailwind CSS**.
- Bật plugin **i18next** (hoặc dùng `src/i18n/locales/_schema.json` để autocomplete).
- Settings → Languages → TypeScript → "Use TypeScript from `node_modules/typescript`".
- Settings → Code Style → Prettier → Run on save (`src/**/*.{ts,tsx,json,css}`).
- Settings → Code Style → Prettier → Run on save (`{src,tests,scripts,worker,build-plugins}/**/*.{ts,tsx,css}` — đúng các file mà `npm run format` xử lý).
### VS Code
@@ -81,23 +81,93 @@ npm run dev
# → http://localhost:5173
```
Dev server chỉ chạy riêng app: không có cổng Turnstile, không có analytics. Muốn chạy Worker phục vụ bản web, xem mục **Cloudflare Worker (chạy cục bộ)** bên dưới.
## Nhánh và Pull Request
- Tạo nhánh từ `main` (`feat/…`, `fix/…`, `docs/…`, `chore/…`) và mở pull request vào `main`. Không có nhánh dài hạn nào khác, và mỗi lần merge vào `main` đều deploy bản web.
- Tiêu đề PR theo định dạng commit `type(scope): message`; CI có kiểm tra.
- Mỗi PR đều chạy job `check` (xem bên dưới), `dependency-review`, `workflow-lint`, `reuse` và `pr-title`; hai job Rust `lint-and-test` và `cargo-deny` chạy khi có thay đổi trong `src-tauri/`.
Quy định đầy đủ: [CONTRIBUTING.md](../../../CONTRIBUTING.md).
## Lệnh thường dùng
| Lệnh | Tác dụng |
| --- | --- |
| `npm run dev` | Vite dev server, hot reload, chỉ web. |
| `npm run build` | Bundle web production vào `dist/`. |
| `npm run preview` | Phục vụ bundle production để kiểm tra. |
| `npm run typecheck` | `tsc --noEmit`. Chạy trước mỗi PR. |
| `npm run lint` | ESLint. Dùng `npm run lint:fix` để autofix. |
| `npm run format` | Chạy Prettier trên `src/`. |
| `npm run test` | Vitest chế độ watch. |
| `npm run test:run` | Vitest chạy một lần (cho CI / pre-commit). |
| `npm run test:coverage` | Báo cáo coverage vào `coverage/`. |
| `npm run validate:locales` | Bắt buộc cả 6 locale có cùng key với `_schema.json`. **Phải pass trước khi merge PR động đến locale.** |
| `npm run generate:locale` | Scaffold locale rỗng từ `_schema.json` cho ngôn ngữ mới. |
| `npm run tauri:dev` | Tauri desktop chế độ dev (tự restart khi đổi Rust hoặc frontend). |
| `npm run tauri:build` | Build binary Tauri release cho platform hiện tại. |
### Phát triển và build
| Lệnh | Tác dụng |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run dev` | Vite dev server, hot reload, chỉ web. |
| `npm run build` | `tsc` + bundle web production vào `dist/`. Bản build web có thêm beacon Web Analytics, `/.well-known/security.txt` và các trang tĩnh `/legal/*`; bản build do Tauri CLI chạy thì không có những thứ này. |
| `npm run preview` | Phục vụ bundle production để kiểm tra (không qua Worker). |
| `npm run cf:dev` | `wrangler dev` — Worker đứng trước `dist/` tại `http://localhost:8787`. Xem mục **Cloudflare Worker (chạy cục bộ)**. |
| `npm run tauri:dev` | Tauri desktop chế độ dev (hoặc `npm run tauri dev`): chạy `npm run dev` rồi mở cửa sổ app trỏ vào đó. Sửa frontend thì hot reload; sửa Rust thì app được build lại. |
| `npm run tauri:build` | Build binary Tauri release cho platform hiện tại. |
### Kiểm tra
| Lệnh | Tác dụng |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run typecheck` | `tsc --noEmit` trên `src/` — đúng phần Vite build. |
| `npm run typecheck:all` | Như trên, thêm `tests/`, `scripts/`, `worker/` và `build-plugins/` (`tsconfig.check.json`) — những thư mục config gốc cố ý bỏ qua. Có từ v0.35.0, khi phát hiện tests và scripts **chưa từng** được type-check — và lần chạy đầu đã tìm ra ba field bị thiếu âm thầm trong fixture parity editor→engine. |
| `npm run lint` | ESLint trên `src/`, `tests/`, `scripts/`, `worker/` và `build-plugins/`. Dùng `npm run lint:fix` để tự sửa. |
| `npm run format` | Chạy Prettier (ghi file) trên `src/`, `tests/`, `scripts/`, `worker/` và `build-plugins/` (`.ts`, `.tsx`, `.css`). |
| `npm run format:check` | Như trên nhưng chỉ kiểm tra. Là cổng CI. Markdown và JSON locale cố ý nằm ngoài phạm vi. |
| `npm run knip` | Tìm code chết / dependency không dùng. Là cổng CI. |
| `npm run validate:locales` | Bắt buộc cả 8 locale khớp chính xác với `_schema.json`. **Phải pass trước khi merge PR động đến locale.** |
| `npm run test` | Vitest chế độ watch. |
| `npm run test:run` | Vitest chạy một lần. |
| `npm run test:coverage` | Chạy một lần kèm báo cáo coverage vào `coverage/`; fail nếu thấp hơn ngưỡng đặt cho `src/engine/` và `worker/` trong `vitest.config.ts`. CI chạy lệnh này. |
| `npm run check:version` | Kiểm tra cả **sáu** trường version khớp nhau (`package.json`, hai chỗ trong `package-lock.json`, `tauri.conf.json`, `Cargo.toml`, `Cargo.lock`). Đây là thứ duy nhất phát hiện khi bỏ sót một chỗ. |
| `npm run check:tauri` | Các package npm `@tauri-apps/*` và các crate Tauri phải cùng major.minor. Tauri CLI sẽ từ chối build nếu lệch, mà CI thì không chạy build Tauri. |
| `npm run check:licenses` | Mọi package được bundle đều có license nằm trong danh sách cho phép, và `THIRD_PARTY_NOTICES.md` khớp với những gì đang cài. |
| `npm run check:copyright` | NOTICE, REUSE.toml và chuỗi copyright của bộ cài (`tauri.conf.json`) phải ghi đúng năm theo năm của commit HEAD — "2026", rồi "2026-2027" từ commit đầu tiên của năm 2027. Gate của CI (v1.1.0). |
| `npm run check:bundle` | Chạy sau `npm run build`: lần tải đầu phải ≤ 280 KB gzip và không chunk JS nào vượt 500 KB (chưa nén). |
| `npm run cf:check` | `wrangler deploy --dry-run`: kiểm tra `wrangler.jsonc` và bundle Worker y như Workers Builds sẽ làm, nhưng không deploy. |
### Sinh file
| Lệnh | Tác dụng |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npm run generate:locale` | Tạo khung locale mới từ bản tiếng Anh. `--lang <mã>`, thêm tùy chọn `--copy-english` / `--force`. (Được nhắc đến từ v0.1 nhưng đến v0.35.0 mới thật sự có script.) |
| `npm run generate:third-party` | Ghi lại `THIRD_PARTY_NOTICES.md` từ các package đang cài — cần chạy sau khi đổi dependency, nếu không `check:licenses` sẽ fail. |
| `npm run update:copyright` | Ghi lại năm bản quyền trong NOTICE, REUSE.toml và `tauri.conf.json` — cần chạy với commit đầu tiên của năm mới, nếu không `check:copyright` sẽ fail. |
| `npm run generate:brand` | Chuyển các SVG thương hiệu trong `assets/brand/` thành icon PNG và ảnh preview khi chia sẻ link của bản web, đặt trong `public/`. Các file PNG được commit. Icon desktop và Android dùng chung logo đó: `npx tauri icon assets/brand/logo.svg`. |
## Trước khi mở PR
Chạy đúng những gì job `check` của CI chạy:
```bash
npm run typecheck && npm run typecheck:all
npm run lint && npm run format:check
npm run validate:locales
npm run test:coverage
npm run knip
npm run check:version && npm run check:tauri && npm run check:licenses
npm run check:copyright
npm run build && npm run check:bundle
npm run cf:check
```
Có động đến `src-tauri/`? Chạy thêm phần **Kiểm tra Rust** bên dưới.
## Cloudflare Worker (chạy cục bộ)
Bản web được phục vụ bởi một Cloudflare Worker ([`worker/`](../../../worker), cấu hình trong [`wrangler.jsonc`](../../../wrangler.jsonc)), đứng trước `dist/` để lo cổng Turnstile, các security header và các trang `/legal` công khai. Để chạy cục bộ:
```bash
cp .dev.vars.example .dev.vars # chỉ chứa key TEST công khai của Cloudflare Turnstile
npm run build # Worker phục vụ dist/
npm run cf:dev # wrangler dev → http://localhost:8787
```
- `.dev.vars` (đã nằm trong `.gitignore`) chứa các key Turnstile **test** mà Cloudflare công bố: widget luôn pass, và secret chỉ chấp nhận token giả do chính widget đó tạo ra. Tuyệt đối không ghi secret thật vào file — trên production, `TURNSTILE_SECRET` được lưu dưới dạng Secret của Cloudflare.
- Không có `.dev.vars` thì Worker không có `TURNSTILE_SECRET` và sẽ fail open: app vẫn tải lên nhưng không qua cổng.
- Worker phục vụ bản build gần nhất — chạy lại `npm run build` để thấy thay đổi ở frontend.
- Test của Worker chạy chung với cả bộ test (`tests/worker/`).
Deploy, cookie, header, secret và rollback: [HOSTING.md](../../HOSTING.md).
## Build Tauri desktop
@@ -105,16 +175,37 @@ Xem [PACKAGING.md](../../PACKAGING.md) cho pipeline release đầy đủ. Build
```bash
npm run tauri:build
# Output: src-tauri/target/release/bundle/{msi,deb,dmg,app}
# Output: src-tauri/target/release/bundle/
# Windows: bộ cài MSI + NSIS · Linux: deb, rpm, AppImage · macOS: .app + DMG
```
Build đầu tiên mất khoảng 5–10 phút (Cargo cache rỗng). Build sau đó là incremental.
Vite dev server không theo dõi `src-tauri/**` và `.wrangler/**` (`server.watch.ignored` trong `vite.config.ts`): khi `tauri dev` đang chạy, Cargo liên tục ghi lại các file trong `src-tauri/target`, và việc theo dõi chúng từng làm Vite crash trên Windows với lỗi `EBUSY` do file `.dll` bị khóa.
### Kiểm tra Rust
Giống các bước của job `lint-and-test` trong `.github/workflows/rust.yml` (chạy khi `src-tauri/` thay đổi, và hằng tuần):
```bash
npm run build # tauri::generate_context!() nhúng dist/, nên clippy và test cần có bản build
cd src-tauri
cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked
```
Job `cargo-deny` kiểm tra advisory RustSec, license và nguồn crate theo `src-tauri/deny.toml`. Chạy cục bộ (sau khi `cargo install cargo-deny`): `cargo deny check advisories licenses sources` trong `src-tauri/`.
## Khắc phục sự cố
### `validate:locales` fail sau khi thêm key
Bạn quên cập nhật `src/i18n/locales/_schema.json`. Schema là source of truth; locale phải khớp 100%.
Bạn quên cập nhật `src/i18n/locales/_schema.json`, hoặc còn thiếu ở một trong 8 locale. Schema là nguồn chuẩn; mọi locale phải khớp 100%.
### `validate:locales` fail mà mình không động đến locale
Có người — hoặc một lần merge từ `main` — đã thêm key vào `_schema.json` (ví dụ nhãn cho một id mới trong `CONTENT_WARNINGS` ở `src/engine/types.ts`) mà chưa có ở mọi locale. Key mới cần có giá trị ở cả 8 locale.
### Build Tauri báo `link.exe not found` (Windows)
@@ -124,6 +215,18 @@ Cài Visual Studio Build Tools 2022 + workload Desktop C++, sau đó khởi đ
Cài Tauri prerequisites theo distro tại <https://v2.tauri.app/start/prerequisites/>.
### `check:tauri` fail sau khi cập nhật dependency
Một package npm `@tauri-apps/*` đã lên minor mới mà crate chưa lên (hoặc ngược lại). Chạy `cargo update -p tauri` (và các crate plugin mà `check:tauri` liệt kê) trong `src-tauri/`, trên cùng nhánh.
### `check:bundle` không tìm thấy `dist/index.html`
Lệnh này đo bản build — hãy chạy `npm run build` trước.
### `npm run cf:dev` không hiện cổng Turnstile
Thiếu `.dev.vars`, nên Worker không có secret và phục vụ app mà không qua cổng. Copy `.dev.vars.example` thành `.dev.vars` rồi chạy lại.
### `npm install` chậm / treo
Tắt VPN/proxy doanh nghiệp chặn npm registry. Lock file đã commit; install offline chạy được sau lần install thành công đầu tiên.
@@ -136,13 +239,10 @@ Từ v0.26, chỉ tiếng Anh nằm trong main chunk; các ngôn ngữ khác là
chunk lazy-load, tải khi dùng lần đầu (xem `src/i18n/index.ts` và
docs/I18N.md). Lời khuyên restart ở trên vẫn áp dụng cho tất cả.
### Pre-commit hook fail ở `validate:locales` mà mình không động đến locale
Có thể bạn vô tình thêm key mới vào `_schema.json` thông qua `src/engine/types.ts` → `CONTENT_WARNINGS`. ID mới cần dịch ở cả 6 locale.
## Xem thêm
- [ARCHITECTURE.md](../../ARCHITECTURE.md) — mô hình layer, data flow, thiết kế engine.
- [HOSTING.md](../../HOSTING.md) — cách ytgenerator.stream được build, deploy và bảo vệ.
- [I18N.md](../../I18N.md) — thêm ngôn ngữ mới từng bước.
- [PACKAGING.md](../../PACKAGING.md) — Tauri release build và signing.
- [CONTRIBUTING.md ở root](../../../CONTRIBUTING.md) — quy trình PR, quy ước commit, auto-ignore rules.
+18 -11
View File
@@ -6,7 +6,7 @@
YTDescGen là dự án cá nhân do một người duy trì (`@poli0981`) để dùng cho kênh YouTube [`@SkullMute`](https://www.youtube.com/@SkullMute), và chia sẻ công khai dưới dạng mã nguồn mở. Đây **không phải sản phẩm thương mại** và không có nghĩa vụ hỗ trợ.
Mã nguồn, tài liệu, bản dịch locale, và các quyết định thiết kế trong repo này được **đồng tác giả với sự hỗ trợ của Anthropic's Claude Code (model 4.7 Opus, cửa sổ context 1M)**. Tất cả commit, release, và quyết định kiến trúc được người duy trì xem xét và phê duyệt trước khi merge.
Mã nguồn, tài liệu, bản dịch locale, và các quyết định thiết kế trong repo này được **đồng tác giả với sự hỗ trợ của Anthropic's Claude Code (các model Claude Opus; từ bản v1.0.0 đến v1.2.0 dùng Claude Opus 5.5)**. Tất cả commit, release, và quyết định kiến trúc được người duy trì xem xét và phê duyệt trước khi merge.
Tuyên bố này áp dụng cho:
@@ -14,21 +14,24 @@ Tuyên bố này áp dụng cho:
- Tài liệu trong `docs/` và các file markdown ở root.
- File locale trong `src/i18n/locales/`.
- Workflow CI/CD trong `.github/workflows/`.
- Cloudflare Worker trong `worker/` và các build plugin trong `build-plugins/`.
Xem thêm: [`THIRD_PARTY_NOTICES.md`](../../../THIRD_PARTY_NOTICES.md) § "AI-Assisted Development Disclosure".
Xem thêm: [`THIRD_PARTY_NOTICES.md`](../../../THIRD_PARTY_NOTICES.md) § "AI-assisted development".
## Chất lượng bản dịch
UI ứng dụng hỗ trợ sáu ngôn ngữ. Chất lượng tác giả khác nhau:
Ứng dụng có tám ngôn ngữ. Chất lượng tác giả khác nhau:
| Locale | Tác giả | Ghi chú |
| --- | --- | --- |
| Tiếng Anh (`en`) | Người duy trì + AI | Locale làm việc chính. Chuỗi được review trước khi commit. |
| Tiếng Việt (`vi`) | Người duy trì (bản ngữ) + AI | Review bởi người duy trì là người bản ngữ tiếng Việt. |
| Tiếng Nhật (`ja`) | AI dịch | Không có review bản ngữ. Ngữ pháp và văn phong có thể chưa chuẩn. |
| Tiếng Tây Ban Nha (`es`) | AI dịch | Không có review bản ngữ. Không nhắm cụ thể vào giọng vùng miền (LatAm vs. Castilian). |
| Tiếng Hàn (`ko`) | AI dịch | Không có review bản ngữ. Honorific register chọn ở mức trung tính. |
| Tiếng Trung (`zh`) | AI dịch | Giản thể. Không có review bản ngữ. |
| Locale | Tác giả | Ghi chú |
| ---------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Tiếng Anh (`en`) | Người duy trì + AI | Locale làm việc chính. Chuỗi được review trước khi commit. |
| Tiếng Việt (`vi`) | Người duy trì (bản ngữ) + AI | Review bởi người duy trì là người bản ngữ tiếng Việt. |
| Tiếng Nhật (`ja`) | AI dịch | Không có review bản ngữ. Ngữ pháp và văn phong có thể chưa chuẩn. |
| Tiếng Tây Ban Nha (`es`) | AI dịch | Không có review bản ngữ. Không nhắm cụ thể vào giọng vùng miền (LatAm vs. Castilian). |
| Tiếng Hàn (`ko`) | AI dịch | Không có review bản ngữ. Honorific register chọn ở mức trung tính. |
| Tiếng Trung (`zh`) | AI dịch | Giản thể. Không có review bản ngữ. |
| Tiếng Bồ Đào Nha, Brazil (`pt-BR`) | AI dịch | Không có review bản ngữ. Nhắm riêng tiếng Bồ Đào Nha Brazil, không nhắm bản châu Âu. |
| Tiếng Indonesia (`id`) | AI dịch | Không có review bản ngữ. Tiếng Indonesia chuẩn; thuật ngữ game giữ tiếng Anh khi đó là cách dùng phổ biến. |
Nếu bạn là người bản ngữ và phát hiện dịch sai, vui lòng mở issue hoặc PR — xem [CONTRIBUTING.md](../../../CONTRIBUTING.md) § "i18n Contributions".
@@ -53,3 +56,7 @@ Việc dùng Claude Code trong quá trình phát triển **không** biến đây
## Không phải tư vấn pháp lý hay tài chính
Bất kỳ đề cập nào đến GDPR, CCPA, luật bản quyền, chính sách monetization của YouTube, hay các chủ đề tương tự trong tài liệu repo này chỉ để định hướng — **không phải tư vấn pháp lý**. Tham vấn luật sư có chuyên môn ở khu vực của bạn nếu cần câu trả lời chính thống.
## Liên hệ
Thông báo bản quyền / DMCA: **dmca@poli0981.dev** (xem [TERMS.md](../../../TERMS.md)). Giấy phép và ghi công: **copyright@poli0981.dev**. Việc khác: **contact@poli0981.dev** · [poli0981.dev/links](https://poli0981.dev/links/).
+20 -1
View File
@@ -1,8 +1,9 @@
import js from "@eslint/js";
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";
import reactHooks from "eslint-plugin-react-hooks";
export default tseslint.config(
export default defineConfig(
js.configs.recommended,
...tseslint.configs.strict,
{
@@ -13,6 +14,24 @@ export default tseslint.config(
...reactHooks.configs.recommended.rules,
"@typescript-eslint/no-explicit-any": "error",
"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
// eslint-plugin-react-hooks 7 turned on the React Compiler diagnostics.
// They are worth having — four of the seven they flagged on arrival were
// real extra render passes and were fixed (use-online-status moved to
// `useSyncExternalStore`, ShortcutHelpModal now derives instead of
// resetting in an effect, DraftIndicator and use-languages-ready were
// guarded).
//
// Three remain, all genuinely syncing state FROM an external source:
// src/hooks/use-languages-ready.ts — i18next bundle readiness
// src/components/editor/PlaytestEditor.tsx — text mirror of a store number
// src/components/editor/StoreLinkEditor.tsx — compiler can't preserve a useMemo
//
// Each needs a real restructure, not a guard, so they are warnings rather
// than a reason to hold back the ESLint 10 upgrade or to delete the rule.
// Downgrade — do not remove: the signal is the point.
"react-hooks/set-state-in-effect": "warn",
"react-hooks/preserve-manual-memoization": "warn",
},
},
{
+21 -17
View File
@@ -2,37 +2,41 @@
<html lang="en" class="dark">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
<meta name="color-scheme" content="dark light" />
<meta name="theme-color" content="#0a0a0a" />
<meta name="theme-color" content="#0b0b12" />
<title>YTDescGen — YouTube Title, Description & Tag Generator for Gameplay Channels</title>
<meta name="description" content="Generate YouTube titles, descriptions, and tags for Gameplay No Commentary channels — multilingual templates, profile presets, and a Tauri-based desktop build." />
<meta name="keywords" content="youtube, gameplay, no commentary, description generator, tags generator, video title, vietnamese, japanese, korean, spanish, chinese, multilingual, tauri, desktop" />
<meta name="description" content="Generate YouTube titles, descriptions, and tags for Gameplay No Commentary channels — eight languages, reusable profiles and presets, on the web or as a desktop and Android app." />
<meta name="keywords" content="youtube, gameplay, no commentary, description generator, tags generator, video title, vietnamese, japanese, korean, spanish, chinese, portuguese, indonesian, multilingual, desktop, android" />
<meta name="author" content="SkullMute (poli0981)" />
<meta name="robots" content="index, follow" />
<meta name="generator" content="Vite + React" />
<link rel="canonical" href="https://poli0981.github.io/youtube-generator/" />
<link rel="icon" type="image/svg+xml" href="/youtube-generator/favicon.svg" />
<link rel="apple-touch-icon" href="/youtube-generator/apple-touch-icon.png" />
<link rel="manifest" href="/youtube-generator/manifest.webmanifest" />
<link rel="canonical" href="https://ytgenerator.stream/" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="icon" type="image/x-icon" href="/favicon.ico" sizes="16x16 32x32 48x48" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
<link rel="manifest" href="/manifest.webmanifest" />
<script src="/theme-init.js"></script>
<!-- OpenGraph -->
<meta property="og:type" content="website" />
<meta property="og:site_name" content="YTDescGen" />
<meta property="og:title" content="YTDescGen — YouTube Title, Description & Tag Generator" />
<meta property="og:description" content="Multilingual title, description, and tag generator for Gameplay No Commentary channels." />
<meta property="og:url" content="https://poli0981.github.io/youtube-generator/" />
<meta property="og:image" content="https://poli0981.github.io/youtube-generator/og-image.png" />
<meta property="og:url" content="https://ytgenerator.stream/" />
<meta property="og:image" content="https://ytgenerator.stream/og-image.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="YTDescGen — titles, descriptions and tags for gameplay videos" />
<meta property="og:locale" content="en_US" />
<meta property="og:locale:alternate" content="vi_VN" />
<meta property="og:locale:alternate" content="ja_JP" />
<meta property="og:locale:alternate" content="es_ES" />
<meta property="og:locale:alternate" content="ko_KR" />
<meta property="og:locale:alternate" content="zh_CN" />
<meta property="og:locale:alternate" content="pt_BR" />
<meta property="og:locale:alternate" content="id_ID" />
<!-- Twitter / X card -->
<meta name="twitter:card" content="summary_large_image" />
@@ -40,7 +44,7 @@
<meta name="twitter:creator" content="@SkullMute0011" />
<meta name="twitter:title" content="YTDescGen — YouTube Title, Description & Tag Generator" />
<meta name="twitter:description" content="Multilingual title, description, and tag generator for Gameplay No Commentary channels." />
<meta name="twitter:image" content="https://poli0981.github.io/youtube-generator/og-image.png" />
<meta name="twitter:image" content="https://ytgenerator.stream/og-image.png" />
<!-- Structured data -->
<script type="application/ld+json">
@@ -49,11 +53,11 @@
"@type": "WebApplication",
"name": "YTDescGen",
"alternateName": "YouTube Description Generator",
"url": "https://poli0981.github.io/youtube-generator/",
"url": "https://ytgenerator.stream/",
"applicationCategory": "MultimediaApplication",
"operatingSystem": "Web, Windows, macOS, Linux",
"description": "Generate YouTube titles, descriptions, and tags for Gameplay No Commentary channels — multilingual templates, profile presets, and a Tauri-based desktop build.",
"inLanguage": ["en", "vi", "ja", "es", "ko", "zh"],
"operatingSystem": "Web, Windows, macOS, Linux, Android",
"description": "Generate YouTube titles, descriptions, and tags for Gameplay No Commentary channels — eight languages, reusable profiles and presets, on the web or as a desktop and Android app.",
"inLanguage": ["en", "vi", "ja", "es", "ko", "zh", "pt-BR", "id"],
"offers": {
"@type": "Offer",
"price": "0",
@@ -62,7 +66,7 @@
"author": {
"@type": "Person",
"name": "SkullMute",
"url": "https://github.com/poli0981"
"url": "https://poli0981.dev/"
},
"license": "https://github.com/poli0981/youtube-generator/blob/main/LICENSE"
}
+8 -8
View File
@@ -1,13 +1,13 @@
{
"$schema": "https://unpkg.com/knip@6/schema.json",
"entry": ["scripts/*.ts", "tests/**/*.test.ts"],
"project": ["src/**/*.{ts,tsx}", "scripts/**/*.ts", "tests/**/*.ts"],
"ignoreExportsUsedInFile": true,
"ignoreDependencies": [
"@tauri-apps/plugin-fs",
"@tauri-apps/plugin-shell",
"@testing-library/jest-dom",
"@testing-library/react"
"project": [
"src/**/*.{ts,tsx}",
"scripts/**/*.ts",
"tests/**/*.ts",
"worker/**/*.ts",
"build-plugins/**/*.ts"
],
"ignoreBinaries": ["tauri"]
"ignoreExportsUsedInFile": true,
"ignoreDependencies": ["tailwindcss", "@testing-library/jest-dom", "@testing-library/react"]
}
+55
View File
@@ -0,0 +1,55 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="robots" content="noindex" />
<meta name="color-scheme" content="dark light" />
<title>YTDescGen has moved to ytgenerator.stream</title>
<meta
name="description"
content="YTDescGen now lives at ytgenerator.stream. Download the data you saved here and restore it there."
/>
<link rel="canonical" href="https://ytgenerator.stream/" />
<link rel="stylesheet" href="/youtube-generator/style.css" />
<script src="/youtube-generator/app.js" defer></script>
</head>
<body>
<main class="card">
<p class="brand">YTDescGen</p>
<h1 data-i18n="title">YTDescGen has moved to ytgenerator.stream</h1>
<p data-i18n="lead">
The app now lives at its own address. Everything you saved on this old address — profiles,
presets, templates, history, settings — stays in this browser, so bring it along in two
steps.
</p>
<ol class="steps">
<li>
<strong data-i18n="step1">Download your data</strong>
<p id="found" class="muted" data-i18n="searching">Looking for saved data…</p>
<button id="download" type="button" disabled data-i18n="download">
Download my data
</button>
</li>
<li>
<strong data-i18n="step2">Restore it on the new site</strong>
<p class="muted" data-i18n="step2Hint">
Open Settings › Backup &amp; restore, choose Restore and pick the file — or drop it
there. You'll see what's new before anything changes.
</p>
<a class="button primary" href="https://ytgenerator.stream/settings" data-i18n="open">
Open ytgenerator.stream
</a>
</li>
</ol>
<p class="muted small" data-i18n="notice">
This page stays until 29 November 2026. The desktop and Android apps aren't affected.
</p>
<p class="small">
<button id="language" type="button" class="link" data-i18n="switch">Tiếng Việt</button>
</p>
</main>
</body>
</html>
+173
View File
@@ -0,0 +1,173 @@
// YTDescGen moved from poli0981.github.io/youtube-generator to
// ytgenerator.stream. Browser storage belongs to a site, so data saved on the
// old address can't follow on its own: this page reads it and hands it over
// as a backup file (the format the new site's Settings › Restore reads).
(function () {
"use strict";
// Store key, where a list section keeps its items, and the backup section.
var STORES = [
{ key: "ytdescgen-profiles", section: "profiles", list: "profiles" },
{ key: "ytdescgen-presets", section: "presets", list: "presets" },
{ key: "ytdescgen-templates", section: "templates", list: "templates" },
{ key: "ytdescgen-history", section: "history", list: "entries" },
{ key: "ytdescgen-settings", section: "settings", list: null },
{ key: "ytdescgen-editor-draft", section: "draft", list: null },
];
var TEXT = {
en: {
title: "YTDescGen has moved to ytgenerator.stream",
lead: "The app now lives at its own address. Everything you saved on this old address — profiles, presets, templates, history, settings — stays in this browser, so bring it along in two steps.",
step1: "Download your data",
searching: "Looking for saved data…",
found: "Found: {list}.",
none: "Nothing was saved in this browser — you can go straight to the new site.",
unavailable:
"This browser won't let the page read its storage (private mode?). Open the page in the browser you used before.",
download: "Download my data",
step2: "Restore it on the new site",
step2Hint:
"Open Settings › Backup & restore, choose Restore and pick the file — or drop it there. You'll see what's new before anything changes.",
open: "Open ytgenerator.stream",
notice:
"This page stays until 29 November 2026. The desktop and Android apps aren't affected.",
switch: "Tiếng Việt",
profiles: "Profiles ({n})",
presets: "Game presets ({n})",
templates: "Templates ({n})",
history: "History ({n})",
settings: "Settings",
draft: "Editor draft",
},
vi: {
title: "YTDescGen đã chuyển sang ytgenerator.stream",
lead: "Ứng dụng giờ có địa chỉ riêng. Mọi thứ bạn đã lưu ở địa chỉ cũ này — hồ sơ, preset, template, lịch sử, cài đặt — vẫn nằm trong trình duyệt này, hãy mang theo bằng hai bước.",
step1: "Tải dữ liệu của bạn",
searching: "Đang tìm dữ liệu đã lưu…",
found: "Tìm thấy: {list}.",
none: "Trình duyệt này chưa lưu gì — bạn có thể sang thẳng trang mới.",
unavailable:
"Trình duyệt không cho trang đọc bộ nhớ (chế độ ẩn danh?). Hãy mở trang bằng trình duyệt bạn đã dùng trước đây.",
download: "Tải dữ liệu của tôi",
step2: "Khôi phục trên trang mới",
step2Hint:
"Mở Cài đặt › Sao lưu & khôi phục, chọn Khôi phục rồi chọn tệp — hoặc thả tệp vào đó. Bạn sẽ xem trước những gì mới trước khi có thay đổi nào.",
open: "Mở ytgenerator.stream",
notice:
"Trang này tồn tại đến ngày 29/11/2026. Ứng dụng desktop và Android không bị ảnh hưởng.",
switch: "English",
profiles: "Hồ sơ ({n})",
presets: "Preset game ({n})",
templates: "Template ({n})",
history: "Lịch sử ({n})",
settings: "Cài đặt",
draft: "Bản nháp editor",
},
};
var lang = /^vi\b/i.test(navigator.language || "") ? "vi" : "en";
var found = null; // { data, parts } once read
var readFailed = false;
function format(template, values) {
return template.replace(/\{(\w+)\}/g, function (_, name) {
return String(values[name]);
});
}
function readStores() {
var data = {};
var parts = [];
STORES.forEach(function (store) {
var raw = localStorage.getItem(store.key);
if (!raw) return;
var saved;
try {
saved = JSON.parse(raw);
} catch (e) {
return;
}
// Zustand's saved shape: { state, version }.
var state = saved && saved.state ? saved.state : saved;
var version = saved && typeof saved.version === "number" ? saved.version : 0;
if (!state || typeof state !== "object") return;
if (store.list) {
var items = state[store.list];
if (!Array.isArray(items) || items.length === 0) return;
data[store.section] = { version: version, items: items };
parts.push({ section: store.section, n: items.length });
} else {
data[store.section] = { version: version, value: state };
parts.push({ section: store.section, n: 1 });
}
});
return { data: data, parts: parts };
}
function render() {
var text = TEXT[lang];
document.documentElement.lang = lang;
document.title = text.title;
Array.prototype.forEach.call(document.querySelectorAll("[data-i18n]"), function (el) {
var key = el.getAttribute("data-i18n");
if (text[key] && key !== "searching") el.textContent = text[key];
});
var status = document.getElementById("found");
var button = document.getElementById("download");
if (readFailed) {
status.textContent = text.unavailable;
button.disabled = true;
} else if (!found || found.parts.length === 0) {
status.textContent = text.none;
button.disabled = true;
} else {
var list = found.parts.map(function (part) {
return format(text[part.section], { n: part.n });
});
status.textContent = format(text.found, { list: list.join(", ") });
button.disabled = false;
}
}
function download() {
if (!found) return;
var now = new Date();
var envelope = {
_app: "ytdescgen",
_format: 2,
_type: "backup",
_schemaVersion: 1,
_appVersion: "0.38.0",
_exportedAt: now.toISOString(),
_source: "poli0981.github.io/youtube-generator",
data: found.data,
};
var blob = new Blob([JSON.stringify(envelope, null, 2)], { type: "application/json" });
var url = URL.createObjectURL(blob);
var link = document.createElement("a");
var day = now.toISOString().slice(0, 10);
link.href = url;
link.download = "ytdescgen-legacy-backup-" + day + ".json";
document.body.appendChild(link);
link.click();
link.remove();
setTimeout(function () {
URL.revokeObjectURL(url);
}, 1000);
}
document.addEventListener("DOMContentLoaded", function () {
try {
found = readStores();
} catch (e) {
readFailed = true;
}
document.getElementById("download").addEventListener("click", download);
document.getElementById("language").addEventListener("click", function () {
lang = lang === "vi" ? "en" : "vi";
render();
});
render();
});
})();
+55
View File
@@ -0,0 +1,55 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="robots" content="noindex" />
<meta name="color-scheme" content="dark light" />
<title>YTDescGen has moved to ytgenerator.stream</title>
<meta
name="description"
content="YTDescGen now lives at ytgenerator.stream. Download the data you saved here and restore it there."
/>
<link rel="canonical" href="https://ytgenerator.stream/" />
<link rel="stylesheet" href="/youtube-generator/style.css" />
<script src="/youtube-generator/app.js" defer></script>
</head>
<body>
<main class="card">
<p class="brand">YTDescGen</p>
<h1 data-i18n="title">YTDescGen has moved to ytgenerator.stream</h1>
<p data-i18n="lead">
The app now lives at its own address. Everything you saved on this old address — profiles,
presets, templates, history, settings — stays in this browser, so bring it along in two
steps.
</p>
<ol class="steps">
<li>
<strong data-i18n="step1">Download your data</strong>
<p id="found" class="muted" data-i18n="searching">Looking for saved data…</p>
<button id="download" type="button" disabled data-i18n="download">
Download my data
</button>
</li>
<li>
<strong data-i18n="step2">Restore it on the new site</strong>
<p class="muted" data-i18n="step2Hint">
Open Settings › Backup &amp; restore, choose Restore and pick the file — or drop it
there. You'll see what's new before anything changes.
</p>
<a class="button primary" href="https://ytgenerator.stream/settings" data-i18n="open">
Open ytgenerator.stream
</a>
</li>
</ol>
<p class="muted small" data-i18n="notice">
This page stays until 29 November 2026. The desktop and Android apps aren't affected.
</p>
<p class="small">
<button id="language" type="button" class="link" data-i18n="switch">Tiếng Việt</button>
</p>
</main>
</body>
</html>
+122
View File
@@ -0,0 +1,122 @@
:root {
color-scheme: dark light;
--bg: #0b0b12;
--surface: #151522;
--border: #2a2a3d;
--text: #ececf4;
--muted: #a0a0b8;
--accent: #7c6cf6;
--accent-text: #ffffff;
}
@media (prefers-color-scheme: light) {
:root {
--bg: #f5f5fa;
--surface: #ffffff;
--border: #dcdce8;
--text: #16161f;
--muted: #5c5c70;
--accent: #5b4de0;
}
}
* {
box-sizing: border-box;
}
body {
margin: 0;
min-height: 100dvh;
display: grid;
place-items: center;
padding: 24px 16px;
background: var(--bg);
color: var(--text);
font:
15px/1.6 system-ui,
-apple-system,
"Segoe UI",
Roboto,
sans-serif;
}
.card {
width: 100%;
max-width: 34rem;
padding: 28px;
border: 1px solid var(--border);
border-radius: 20px;
background: var(--surface);
}
.brand {
margin: 0 0 8px;
color: var(--accent);
font-weight: 700;
letter-spacing: 0.02em;
}
h1 {
margin: 0 0 12px;
font-size: 1.45rem;
line-height: 1.3;
}
.steps {
margin: 20px 0;
padding-left: 1.2rem;
}
.steps li {
margin-bottom: 18px;
}
.steps p {
margin: 4px 0 10px;
}
.muted {
color: var(--muted);
}
.small {
font-size: 0.85rem;
}
button,
.button {
display: inline-block;
padding: 9px 16px;
border: 1px solid var(--border);
border-radius: 10px;
background: transparent;
color: var(--text);
font: inherit;
font-weight: 600;
text-decoration: none;
cursor: pointer;
}
button:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.primary,
#download:not(:disabled) {
border-color: var(--accent);
background: var(--accent);
color: var(--accent-text);
}
.link {
padding: 0;
border: 0;
color: var(--accent);
font-weight: 500;
}
:focus-visible {
outline: 2px solid var(--accent);
outline-offset: 2px;
}
+5622 -2203
View File
File diff suppressed because it is too large. Load diff
+63 -41
View File
@@ -1,9 +1,12 @@
{
"name": "yt-desc-gen",
"version": "0.35.0",
"version": "1.2.0",
"private": true,
"license": "Apache-2.0",
"type": "module",
"engines": {
"node": ">=26"
},
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
@@ -11,57 +14,76 @@
"test": "vitest",
"test:run": "vitest run",
"test:coverage": "vitest run --coverage",
"lint": "eslint src/ tests/ scripts/",
"lint:fix": "eslint src/ tests/ scripts/ --fix",
"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}/**/*.{ts,tsx,css}\"",
"format:check": "prettier --check \"{src,tests,scripts}/**/*.{ts,tsx,css}\"",
"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"
"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": {
"@tauri-apps/api": "^2.11.0",
"@tauri-apps/plugin-dialog": "^2.0.0",
"@tauri-apps/plugin-fs": "^2.0.0",
"@tauri-apps/plugin-opener": "^2.0.0",
"@tauri-apps/plugin-shell": "^2.0.0",
"clsx": "^2.1.0",
"i18next": "^23.15.0",
"i18next-resources-to-backend": "^1.2.1",
"lucide-react": "^0.400.0",
"react": "^18.3.0",
"react-dom": "^18.3.0",
"react-hot-toast": "^2.4.0",
"react-i18next": "^15.0.0",
"react-router-dom": "^7.18.2",
"zustand": "^4.5.0"
"@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.4.5",
"i18next-resources-to-backend": "^1.2.3",
"lucide-react": "^1.57.0",
"motion": "^13.5.1",
"radix-ui": "^1.8.1",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"react-i18next": "^17.0.16",
"react-router-dom": "^7.18.4",
"simple-icons": "^16.33.0",
"sonner": "^2.0.8",
"zustand": "^5.0.15"
},
"devDependencies": {
"@eslint/js": "^9.0.0",
"@testing-library/jest-dom": "^6.4.0",
"@testing-library/react": "^16.0.0",
"@types/node": "^26.2.0",
"@types/react": "^18.3.0",
"@types/react-dom": "^18.3.0",
"@vitejs/plugin-react": "^5.2.0",
"autoprefixer": "^10.4.0",
"eslint": "^9.0.0",
"eslint-plugin-react-hooks": "^5.0.0",
"knip": "^6.14.1",
"postcss": "^8.5.25",
"prettier": "^3.3.0",
"prettier-plugin-tailwindcss": "^0.6.0",
"tailwindcss": "^3.4.0",
"tsx": "^4.22.4",
"typescript": "^5.5.0",
"typescript-eslint": "^8.0.0",
"vite": "^8.0.16",
"vitest": "^4.1.8"
"@eslint/js": "^10.0.1",
"@resvg/resvg-js": "2.6.2",
"@tailwindcss/postcss": "^4.3.3",
"@tauri-apps/cli": "2.12.3",
"@testing-library/jest-dom": "^7.0.1",
"@testing-library/react": "^16.3.3",
"@types/node": "^26.6.3",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"@typescript/native": "npm:typescript@^7.0.2",
"@vitejs/plugin-react": "^6.1.2",
"@vitest/coverage-v8": "^4.1.12",
"autoprefixer": "^10.6.1",
"eslint": "^10.12.0",
"eslint-plugin-react-hooks": "^7.1.1",
"knip": "^6.41.0",
"marked": "18.1.1",
"postcss": "^8.5.30",
"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.71.2",
"vite": "^8.3.4",
"vitest": "^4.1.12",
"wrangler": "4.149.0"
}
}
+2 -1
View File
@@ -1,6 +1,7 @@
export default {
plugins: {
tailwindcss: {},
// Tailwind 4 ships its PostCSS plugin as a separate package.
"@tailwindcss/postcss": {},
autoprefixer: {},
},
};
View File
Whitespace-only changes.
+57
View File
@@ -0,0 +1,57 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="color-scheme" content="dark light" />
<meta name="robots" content="noindex" />
<title>Page not found — YTDescGen</title>
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<style>
:root {
color-scheme: dark light;
--bg: #0b0b12;
--card: #13131c;
--border: #262636;
--text: #ececf3;
--muted: #9a9ab0;
font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
}
@media (prefers-color-scheme: light) {
:root { --bg: #f6f6fb; --card: #fff; --border: #e3e3ee; --text: #16161f; --muted: #5d5d72; }
}
body {
margin: 0;
min-height: 100vh;
display: grid;
place-items: center;
padding: 24px 16px;
background: var(--bg);
color: var(--text);
}
main {
max-width: 420px;
text-align: center;
background: var(--card);
border: 1px solid var(--border);
border-radius: 20px;
padding: 32px 24px;
}
svg { width: 48px; height: 48px; }
p.code { margin: 16px 0 4px; font: 700 44px/1 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; letter-spacing: -0.02em; }
h1 { font-size: 18px; margin: 8px 0; }
p { color: var(--muted); font-size: 14px; line-height: 1.55; }
a.btn { display: inline-block; margin-top: 12px; padding: 10px 18px; border-radius: 12px; color: #fff; font-weight: 600; text-decoration: none; background: linear-gradient(135deg, #6366f1, #a855f7); }
a.btn:focus-visible { outline: 2px solid #a5a6fb; outline-offset: 2px; }
</style>
</head>
<body>
<main>
<svg viewBox="0 0 512 512" aria-hidden="true"><defs><linearGradient id="g" x1="40" y1="24" x2="472" y2="488" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#6366F1"/><stop offset="1" stop-color="#A855F7"/></linearGradient></defs><rect width="512" height="512" rx="120" fill="url(#g)"/><path d="M176 118c0-17.9 19.4-29.1 34.9-20.1l128.2 74c15.5 9 15.5 31.2 0 40.2l-128.2 74C195.4 295.1 176 283.9 176 266z" fill="#fff"/><rect x="136" y="322" width="240" height="32" rx="16" fill="#fff" fill-opacity=".92"/><rect x="136" y="374" width="160" height="32" rx="16" fill="#fff" fill-opacity=".6"/></svg>
<p class="code">404</p>
<h1>This page doesn't exist</h1>
<p>The link may be old or mistyped. YTDescGen itself lives at the home page.</p>
<a class="btn" href="/">Open YTDescGen</a>
</main>
</body>
</html>
+30
View File
@@ -0,0 +1,30 @@
# Response headers for files Cloudflare serves straight out of dist/.
#
# Rules are additive: a path matching several blocks gets every header, and a
# header set twice is joined with a comma — so each header name appears in
# exactly one block per path. HSTS is intentionally absent: the zone edge
# already sends `max-age=31536000; includeSubDomains; preload`.
/*
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: accelerometer=(), camera=(), display-capture=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), midi=(), payment=(), usb=(), browsing-topics=()
Cross-Origin-Opener-Policy: same-origin
X-Frame-Options: DENY
Content-Security-Policy: default-src 'self'; script-src 'self' https://static.cloudflareinsights.com; connect-src 'self' https://cloudflareinsights.com; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; font-src 'self' data:; manifest-src 'self'; worker-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests
# Content-hashed build output: safe to cache forever.
/assets/*
Cache-Control: public, max-age=31536000, immutable
Cross-Origin-Resource-Policy: same-origin
/icons/*
Cache-Control: public, max-age=604800
# Link-preview crawlers and chat apps embed this from other origins.
/og-image.png
Cache-Control: public, max-age=86400
Cross-Origin-Resource-Policy: cross-origin
/manifest.webmanifest
Content-Type: application/manifest+json; charset=utf-8
Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

+11 -4
View File
@@ -1,5 +1,12 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
<rect width="64" height="64" rx="12" fill="#0a0a0a"/>
<rect x="14" y="14" width="36" height="36" rx="6" fill="none" stroke="#ec4899" stroke-width="3"/>
<path d="M22 22h20M22 30h20M22 38h12" stroke="#ec4899" stroke-width="3" stroke-linecap="round"/>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
<defs>
<linearGradient id="ytg-bg" x1="40" y1="24" x2="472" y2="488" gradientUnits="userSpaceOnUse">
<stop offset="0" stop-color="#6366F1"/>
<stop offset="1" stop-color="#A855F7"/>
</linearGradient>
</defs>
<rect width="512" height="512" rx="120" fill="url(#ytg-bg)"/>
<path d="M176 118c0-17.9 19.4-29.1 34.9-20.1l128.2 74c15.5 9 15.5 31.2 0 40.2l-128.2 74C195.4 295.1 176 283.9 176 266z" fill="#fff"/>
<rect x="136" y="322" width="240" height="32" rx="16" fill="#fff" fill-opacity=".92"/>
<rect x="136" y="374" width="160" height="32" rx="16" fill="#fff" fill-opacity=".6"/>
</svg>

Before

Width:  |  Height:  |  Size: 335 B

After

Width:  |  Height:  |  Size: 678 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

+16 -9
View File
@@ -1,32 +1,39 @@
{
"id": "/",
"name": "YTDescGen",
"short_name": "YTDescGen",
"description": "YouTube title, description, and tag generator for Gameplay No Commentary channels.",
"start_url": "/youtube-generator/",
"scope": "/youtube-generator/",
"start_url": "/",
"scope": "/",
"display": "standalone",
"background_color": "#0a0a0a",
"theme_color": "#0a0a0a",
"background_color": "#0b0b12",
"theme_color": "#0b0b12",
"lang": "en",
"categories": ["productivity", "utilities", "multimedia"],
"icons": [
{
"src": "favicon.svg",
"src": "/favicon.svg",
"sizes": "any",
"type": "image/svg+xml",
"purpose": "any"
},
{
"src": "icon-192.png",
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any maskable"
"purpose": "any"
},
{
"src": "icon-512.png",
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any maskable"
"purpose": "any"
},
{
"src": "/icons/maskable-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
]
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 178 KiB

+2 -1
View File
@@ -1,3 +1,4 @@
User-agent: *
Allow: /
Sitemap: https://poli0981.github.io/youtube-generator/sitemap.xml
Sitemap: https://ytgenerator.stream/sitemap.xml
+1 -1
View File
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://poli0981.github.io/youtube-generator/</loc>
<loc>https://ytgenerator.stream/</loc>
<changefreq>weekly</changefreq>
<priority>1.0</priority>
</url>
+26
View File
@@ -0,0 +1,26 @@
// Applies the saved theme, scrollbar preference and UI language before the
// first paint, so a light-theme user never sees the dark default flash. A
// separate file rather than an inline <script> so the Content-Security-Policy
// needs no exception.
(function () {
var root = document.documentElement;
var theme = "dark";
var hideScrollbars = false;
var lang = null;
try {
var raw = localStorage.getItem("ytdescgen-settings");
var state = raw ? JSON.parse(raw).state : null;
if (state && state.theme === "light") theme = "light";
// Unhealed raw storage, so only a real `true` counts.
if (state && state.hideScrollbars === true) hideScrollbars = true;
if (state && typeof state.appLanguage === "string") lang = state.appLanguage;
} catch (e) {
/* storage blocked or corrupt: keep the defaults */
}
root.classList.toggle("dark", theme === "dark");
root.classList.toggle("light", theme === "light");
root.style.colorScheme = theme;
// Same class as src/utils/scrollbars.ts.
root.classList.toggle("hide-scrollbars", hideScrollbars);
if (lang) root.lang = lang;
})();
+74
View File
@@ -0,0 +1,74 @@
/**
* Bundle budget for the web build — run after `npm run build`.
*
* CLAUDE.md used to say "keep the bundle under 500KB" without saying what was
* measured, and nothing measured it. This does:
*
* - INITIAL LOAD: every script, modulepreload and stylesheet `dist/index.html`
* references, summed gzip. That is what a first visit downloads before the
* app can render. Lazy chunks (pages, locales, the legal documents) are
* excluded on purpose — they only load when used.
* - LARGEST CHUNK: no single JS file over the raw limit, so one accidental
* import cannot balloon a lazy page either.
*
* Numbers are printed as a table (and to the GitHub step summary in CI).
* Run via `npm run check:bundle`.
*/
import { appendFileSync, readFileSync, readdirSync } from "fs";
import { resolve } from "path";
import { gzipSync } from "zlib";
const DIST = resolve(import.meta.dirname, "../dist");
/** v1.0.0 baseline was 193 KB gzip before the redesign; keep headroom, not a blank cheque. */
export const INITIAL_GZIP_BUDGET = 280 * 1024;
export const MAX_CHUNK_RAW = 500 * 1024;
const kb = (bytes: number): string => `${(bytes / 1024).toFixed(1)} KB`;
function initialAssets(html: string): string[] {
const refs = new Set<string>();
const pattern = /(?:src|href)="\/(assets\/[^"]+\.(?:js|css))"/g;
for (let match = pattern.exec(html); match; match = pattern.exec(html)) {
if (match[1]) refs.add(match[1]);
}
return [...refs];
}
const html = readFileSync(resolve(DIST, "index.html"), "utf8");
const initial = initialAssets(html).map((file) => {
const bytes = readFileSync(resolve(DIST, file));
return { file, raw: bytes.length, gzip: gzipSync(bytes, { level: 9 }).length };
});
const initialGzip = initial.reduce((sum, a) => sum + a.gzip, 0);
const chunks = readdirSync(resolve(DIST, "assets"))
.filter((name) => name.endsWith(".js"))
.map((name) => ({ name, raw: readFileSync(resolve(DIST, "assets", name)).length }))
.sort((a, b) => b.raw - a.raw);
const largest = chunks[0];
const rows = [
`| Initial load (${initial.length} files, gzip) | ${kb(initialGzip)} | ${kb(INITIAL_GZIP_BUDGET)} | ${initialGzip <= INITIAL_GZIP_BUDGET ? "✅" : "❌"} |`,
`| Largest chunk (${largest?.name ?? "—"}, raw) | ${kb(largest?.raw ?? 0)} | ${kb(MAX_CHUNK_RAW)} | ${(largest?.raw ?? 0) <= MAX_CHUNK_RAW ? "✅" : "❌"} |`,
];
const table = ["| Metric | Size | Budget | |", "| --- | --- | --- | --- |", ...rows].join("\n");
console.log(table);
console.log("\nInitial-load files:");
for (const a of initial.sort((x, y) => y.gzip - x.gzip)) {
console.log(
` ${a.file.padEnd(48)} ${kb(a.raw).padStart(10)} raw ${kb(a.gzip).padStart(9)} gzip`,
);
}
if (process.env.GITHUB_STEP_SUMMARY) {
appendFileSync(process.env.GITHUB_STEP_SUMMARY, `### Bundle budget\n\n${table}\n`);
}
const overChunks = chunks.filter((c) => c.raw > MAX_CHUNK_RAW);
if (initialGzip > INITIAL_GZIP_BUDGET || overChunks.length > 0) {
console.error(
"\nBundle budget exceeded — lazy-load the new code or raise the budget deliberately.",
);
process.exit(1);
}
+10
View File
@@ -0,0 +1,10 @@
/**
* CLI for scripts/lib/copyright.ts:
*
* npm run check:copyright verify NOTICE, REUSE.toml and tauri.conf.json
* state the copyright years for HEAD's year
* npm run update:copyright rewrite them to those years
*/
import { main } from "./lib/copyright";
main();
+56
View File
@@ -0,0 +1,56 @@
/**
* Verify the @tauri-apps/* npm packages and the tauri crates agree on
* major.minor.
*
* The tauri CLI refuses to build a release when they differ ("Found version
* mismatched Tauri packages"), but nothing in CI runs `tauri build` — so a
* Dependabot bump of one side merges green and the break only shows up after
* a release tag. This runs in CI instead. Run via `npm run check:tauri`.
*/
import { readFileSync } from "fs";
import { resolve } from "path";
const ROOT = resolve(import.meta.dirname, "..");
/** npm package → crate it must match. */
const PAIRS: ReadonlyArray<[npm: string, crate: string]> = [
["@tauri-apps/api", "tauri"],
["@tauri-apps/cli", "tauri"],
["@tauri-apps/plugin-opener", "tauri-plugin-opener"],
];
function npmVersion(name: string): string | null {
const lock = JSON.parse(readFileSync(resolve(ROOT, "package-lock.json"), "utf8")) as {
packages: Record<string, { version?: string }>;
};
return lock.packages[`node_modules/${name}`]?.version ?? null;
}
function crateVersion(name: string): string | null {
const lock = readFileSync(resolve(ROOT, "src-tauri/Cargo.lock"), "utf8").replace(/\r\n/g, "\n");
const match = new RegExp(`\\[\\[package\\]\\]\\nname = "${name}"\\nversion = "([^"]+)"`).exec(
lock,
);
return match?.[1] ?? null;
}
const majorMinor = (version: string): string => version.split(".").slice(0, 2).join(".");
let failed = false;
for (const [npm, crate] of PAIRS) {
const js = npmVersion(npm);
const rs = crateVersion(crate);
if (js === null || rs === null) continue; // not used on one side
const ok = majorMinor(js) === majorMinor(rs);
console.log(`${ok ? "✓" : "✗"} ${npm} ${js} ↔ ${crate} ${rs}`);
if (!ok) failed = true;
}
if (failed) {
console.error(
"\nTauri npm packages and crates differ in major.minor — `tauri build` will refuse to run.\n" +
"Update the lagging side on this branch, e.g. `cd src-tauri && cargo update -p tauri` or\n" +
"`npm install @tauri-apps/api@<crate version>`.",
);
process.exit(1);
}
+2 -4
View File
@@ -81,13 +81,11 @@ function main(): void {
} catch {
return { label: source.label, version: null };
}
let version: string | null = null;
try {
version = source.extract(raw);
return { label: source.label, version: source.extract(raw) };
} catch {
version = null;
return { label: source.label, version: null };
}
return { label: source.label, version };
});
const missing = found.filter((entry) => entry.version === null);
+97
View File
@@ -0,0 +1,97 @@
/**
* Rasterise the brand SVGs in `assets/brand/` into the web's static images.
*
* One source for every surface: the same `logo.svg` also feeds the Tauri
* desktop + Android icons (`npx tauri icon assets/brand/logo.svg`), so the
* favicon, the PWA icons, the link-preview card and the installed app can no
* longer drift apart the way the pink favicon and the flat indigo square did
* before v1.0.0.
*
* Run via `npm run generate:brand`. The PNGs are committed; this only needs
* re-running when an SVG in `assets/brand/` changes. Text in the OG card is
* laid out with the machine's fonts (Segoe UI on Windows), so regenerate on a
* machine that has a sans-serif covering Latin — the output is checked in, not
* rebuilt in CI.
*/
import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "fs";
import { dirname, resolve } from "path";
import { Resvg } from "@resvg/resvg-js";
const ROOT = resolve(import.meta.dirname, "..");
const BRAND = resolve(ROOT, "assets/brand");
const PUBLIC = resolve(ROOT, "public");
interface Target {
source: string;
out: string;
/** Output width in px; height follows the SVG's aspect ratio. */
width: number;
}
const TARGETS: readonly Target[] = [
{ source: "logo.svg", out: "apple-touch-icon.png", width: 180 },
{ source: "logo.svg", out: "icons/icon-192.png", width: 192 },
{ source: "logo.svg", out: "icons/icon-512.png", width: 512 },
{ source: "logo-maskable.svg", out: "icons/maskable-512.png", width: 512 },
{ source: "og-image.svg", out: "og-image.png", width: 1200 },
];
function render({ source, out, width }: Target): void {
const svg = readFileSync(resolve(BRAND, source), "utf8");
const png = new Resvg(svg, {
fitTo: { mode: "width", value: width },
font: { loadSystemFonts: true, defaultFontFamily: "Segoe UI" },
})
.render()
.asPng();
const target = resolve(PUBLIC, out);
mkdirSync(dirname(target), { recursive: true });
writeFileSync(target, png);
console.log(` ${out.padEnd(24)} ${width}px ${(png.length / 1024).toFixed(1)} KB`);
}
console.log("Rendering brand assets → public/");
for (const target of TARGETS) render(target);
// The favicon ships as the SVG itself — crisp at every size, one request.
copyFileSync(resolve(BRAND, "logo.svg"), resolve(PUBLIC, "favicon.svg"));
console.log(" favicon.svg (copied)");
// Legacy `/favicon.ico` requests (browsers still probe it) get the multi-size
// ICO that `tauri icon` generates from the same logo.
copyFileSync(resolve(ROOT, "src-tauri/icons/icon.ico"), resolve(PUBLIC, "favicon.ico"));
console.log(" favicon.ico (from src-tauri/icons/icon.ico)");
// Android adaptive icon. `tauri icon` pads the whole rounded-square logo onto
// a white background layer, which reads as a purple tile on a white disc in
// the launcher. Replace its foreground with the bare glyph and give the
// background layer the brand colour, in both the generated Gradle project and
// the `icons/android` copy `tauri android init` would restore from.
const ANDROID_BACKGROUND = "#8561F4"; // midpoint of the #6366F1 → #A855F7 logo gradient
const FOREGROUND_SIZES: Readonly<Record<string, number>> = {
"mipmap-mdpi": 108,
"mipmap-hdpi": 162,
"mipmap-xhdpi": 216,
"mipmap-xxhdpi": 324,
"mipmap-xxxhdpi": 432,
};
const ANDROID_RES_DIRS = [
resolve(ROOT, "src-tauri/gen/android/app/src/main/res"),
resolve(ROOT, "src-tauri/icons/android"),
];
const foregroundSvg = readFileSync(resolve(BRAND, "logo-foreground.svg"), "utf8");
for (const resDir of ANDROID_RES_DIRS) {
for (const [bucket, size] of Object.entries(FOREGROUND_SIZES)) {
const png = new Resvg(foregroundSvg, { fitTo: { mode: "width", value: size } })
.render()
.asPng();
mkdirSync(resolve(resDir, bucket), { recursive: true });
writeFileSync(resolve(resDir, bucket, "ic_launcher_foreground.png"), png);
}
mkdirSync(resolve(resDir, "values"), { recursive: true });
writeFileSync(
resolve(resDir, "values/ic_launcher_background.xml"),
`<?xml version="1.0" encoding="utf-8"?>\n<resources>\n <color name="ic_launcher_background">${ANDROID_BACKGROUND}</color>\n</resources>\n`,
);
}
console.log(` android adaptive icon glyph foreground + ${ANDROID_BACKGROUND} background`);
+8 -5
View File
@@ -121,11 +121,14 @@ function main(): void {
console.log(`\n${total} strings to translate. Remaining steps to register "${lang}":
1. src/i18n/index.ts — add to SUPPORTED_LANGUAGES (flag + nativeName)
2. src/engine/types.ts — add to the SupportedLanguage union
3. src/store/settings-heal.ts — add to detectBrowserLanguage's supported list
4. src/engine/tag-generator.ts— add a MULTILINGUAL_TAGS entry (TS enforces this)
5. npm run validate:locales — must pass before committing
1. src/i18n/index.ts — add to SUPPORTED_LANGUAGES (flag + nativeName)
2. src/engine/types.ts — add to the SupportedLanguage union
3. src/store/settings-heal.ts — add to detectBrowserLanguage's supported list (fails silently)
4. src/engine/tag-generator.ts — add CORE_TAGS_BY_LANG and MULTILINGUAL_TAGS entries (TS enforces)
5. src/engine/channel-phrase.ts— add DROP patterns and a FALLBACK noun (TS enforces)
6. worker/gate-i18n.ts — add GateLang, GATE_STRINGS and PREFIX_TO_LANG (fails silently:
the check page would show in English)
7. npm run validate:locales — must pass before committing
See docs/I18N.md for the full checklist.`);
}
+111
View File
@@ -0,0 +1,111 @@
/**
* Copyright years, kept current.
*
* npm run check:copyright fail if a notice states the wrong years
* npm run update:copyright rewrite them to the expected years
*
* The years are written by hand in three files — NOTICE, REUSE.toml and the
* installers' copyright string in src-tauri/tauri.conf.json — and nothing
* used to keep them current. Each must state `copyrightYears(year)` from
* src/config/brand.ts: "2026", then "2026-2027" from the first commit made in
* 2027, and so on.
*
* "This year" is the year HEAD was committed, not the clock: re-running CI on
* an old commit stays green, and the first new work in a new year is what asks
* for the bump. Without git (a source tarball) it falls back to the UTC year.
*
* Deliberately left alone: the `[yyyy]` placeholder in the Apache-2.0
* appendix (LICENSE, LICENSES/Apache-2.0.txt), the Gradle wrapper's own 2015
* notice, CHANGELOG history and the `{{year}}` of generated descriptions.
*/
import { execFileSync } from "child_process";
import { readFileSync, writeFileSync } from "fs";
import { resolve } from "path";
import { copyrightYears } from "../../src/config/brand.ts";
const ROOT = resolve(import.meta.dirname, "../..");
export interface Notice {
/** Repo-relative path. */
file: string;
/** Finds the notice; capture group 1 is its years ("2026", "2026-2027"). */
pattern: RegExp;
}
export const NOTICES: readonly Notice[] = [
{ file: "NOTICE", pattern: /^Copyright ([0-9]{4}(?:-[0-9]{4})?) poli0981 /m },
{
file: "REUSE.toml",
pattern: /^SPDX-FileCopyrightText = "([0-9]{4}(?:-[0-9]{4})?) poli0981 /m,
},
{
file: "src-tauri/tauri.conf.json",
pattern: /"copyright": "Copyright ([0-9]{4}(?:-[0-9]{4})?) poli0981 /,
},
];
export interface NoticeCheck {
notice: Notice;
/** The years the file states now, or null when the notice is not found. */
found: string | null;
expected: string;
}
function readRepoFile(file: string): string {
return readFileSync(resolve(ROOT, file), "utf8");
}
/** The year HEAD was committed, or this UTC year when git is unavailable. */
export function headCommitYear(): number {
try {
const options = { cwd: ROOT, encoding: "utf8" } as const;
// A dev/CI script: `git` is whichever one the developer's PATH or the CI
// image provides, by design — there is no fixed install path to pin.
const iso = execFileSync("git", ["log", "-1", "--format=%cI"], options); // NOSONAR
const year = Number(iso.trim().slice(0, 4));
if (Number.isInteger(year) && year >= 2000) return year;
} catch {
// Not a git checkout.
}
return new Date().getUTCFullYear();
}
/** Every notice's current years against the ones `year` calls for. */
export function checkNotices(year: number, read = readRepoFile): NoticeCheck[] {
const expected = copyrightYears(year);
return NOTICES.map((notice) => ({
notice,
found: notice.pattern.exec(read(notice.file))?.[1] ?? null,
expected,
}));
}
/** `raw` with the notice's years swapped for `years`; nothing else changes. */
export function withYears(raw: string, notice: Notice, years: string): string {
return raw.replace(notice.pattern, (match, current: string) => match.replace(current, years));
}
export function main(): void {
const write = process.argv.includes("--write");
let failed = false;
for (const { notice, found, expected } of checkNotices(headCommitYear())) {
if (found === expected) {
console.log(`✓ ${notice.file}: ${found}`);
} else if (found === null) {
failed = true;
console.error(`✗ ${notice.file}: no copyright notice found (expected ${expected}).`);
} else if (write) {
writeFileSync(
resolve(ROOT, notice.file),
withYears(readRepoFile(notice.file), notice, expected),
);
console.log(`✎ ${notice.file}: ${found} → ${expected}`);
} else {
failed = true;
console.error(
`✗ ${notice.file}: ${found}, expected ${expected}. Run: npm run update:copyright`,
);
}
}
if (failed) process.exit(1);
}
+259
View File
@@ -0,0 +1,259 @@
/**
* Third-party licensing, generated and enforced.
*
* npm run generate:third-party rewrite THIRD_PARTY_NOTICES.md
* npm run check:licenses fail if it is stale, or if anything shipped
* to users carries a license not on the list
*
* THIRD_PARTY_NOTICES.md used to be hand-maintained and had drifted three
* majors behind (React 18, Vite 7, Tailwind 3 …). It is now built from
* package.json, the installed packages and Cargo.toml/Cargo.lock, so CI
* catches the drift instead of a reader. The full license texts of every
* package bundled into the web app are emitted separately by Vite
* (`build.license`) to /licenses/third-party.md.
*/
import { readFileSync, writeFileSync } from "fs";
import { resolve } from "path";
import { compareCodeUnits } from "../../src/utils/sort.ts";
const ROOT = resolve(import.meta.dirname, "../..");
const NOTICES = resolve(ROOT, "THIRD_PARTY_NOTICES.md");
/** Licenses acceptable for code that ships inside the app. */
const ALLOWED = new Set([
"MIT",
"ISC",
"Apache-2.0",
"BSD-2-Clause",
"BSD-3-Clause",
"0BSD",
"CC0-1.0",
"Unlicense",
"BlueOak-1.0.0",
"OFL-1.1",
"Zlib",
"MPL-2.0",
]);
/** SPDX expression → allowed? `OR` needs one side, `AND` needs both. */
export function licenseAllowed(expression: string): boolean {
const expr = expression.trim().replace(/^\((.*)\)$/, "$1");
// Split on the bare operator; each part is trimmed by the recursive call.
if (/\sOR\s/i.test(expr)) return expr.split(/\sOR\s/i).some(licenseAllowed);
if (/\sAND\s/i.test(expr)) return expr.split(/\sAND\s/i).every(licenseAllowed);
return ALLOWED.has(expr);
}
interface PackageJson {
name?: string;
version?: string;
license?: string;
homepage?: string;
repository?: string | { url?: string };
dependencies?: Record<string, string>;
devDependencies?: Record<string, string>;
}
function readJson<T>(path: string): T {
return JSON.parse(readFileSync(path, "utf8")) as T;
}
function projectUrl(pkg: PackageJson): string {
const repo = typeof pkg.repository === "string" ? pkg.repository : pkg.repository?.url;
const fromRepo = repo
?.replace(/^git\+/, "")
.replace(/^git:\/\//, "https://")
.replace(/^github:/, "https://github.com/")
.replace(/\.git$/, "");
if (fromRepo && /^https?:\/\//.test(fromRepo)) return fromRepo;
if (fromRepo && /^[\w.-]+\/[\w.-]+$/.test(fromRepo)) return `https://github.com/${fromRepo}`;
return pkg.homepage ?? "";
}
interface Row {
name: string;
version: string;
license: string;
url: string;
}
function npmRows(keys: string[]): Row[] {
return keys
.map((key) => {
const pkg = readJson<PackageJson>(resolve(ROOT, "node_modules", key, "package.json"));
return {
// An npm alias installs under its key: `"typescript":
// "npm:@typescript/typescript6@…"` puts @typescript/typescript6 in
// node_modules/typescript. Name the package that is really there.
name: pkg.name ?? key,
version: pkg.version ?? "?",
license: pkg.license ?? "UNKNOWN",
url: projectUrl(pkg),
};
})
.sort((a, b) => compareCodeUnits(a.name, b.name));
}
/**
* Crates `src-tauri/Cargo.toml` depends on directly — the `[dependencies]`,
* `[build-dependencies]` and `[target.….dependencies]` tables. Dev-only
* dependencies don't ship and are left out.
*/
export function directCrates(toml: string): string[] {
const names = new Set<string>();
let inDependencies = false;
for (const raw of toml.replace(/\r\n/g, "\n").split("\n")) {
const line = raw.trim();
if (line.startsWith("[")) {
inDependencies = /^\[(?:target\..+\.)?(?:build-)?dependencies\]$/.test(line);
continue;
}
const name = inDependencies ? /^([A-Za-z0-9_-]+)\s*=/.exec(line)?.[1] : undefined;
if (name) names.add(name);
}
return [...names].sort(compareCodeUnits);
}
/**
* License and project page of the direct crates that aren't Tauri's own.
* Cargo.lock carries no license, so a new dependency fails the generator
* until it is added here; `cargo deny` vets the transitive tree.
*/
const OTHER_CRATES: Record<string, { license: string; url: string }> = {
serde: { license: "MIT OR Apache-2.0", url: "https://github.com/serde-rs/serde" },
};
function crateInfo(name: string): { license: string; url: string } {
if (name.startsWith("tauri-plugin")) {
return { license: "Apache-2.0 OR MIT", url: "https://github.com/tauri-apps/plugins-workspace" };
}
if (name.startsWith("tauri")) {
return { license: "Apache-2.0 OR MIT", url: "https://github.com/tauri-apps/tauri" };
}
const info = OTHER_CRATES[name];
if (!info) {
throw new Error(
`src-tauri depends on "${name}": add its license and project page to OTHER_CRATES in scripts/lib/third-party.ts`,
);
}
return info;
}
function crateRows(): Row[] {
const toml = readFileSync(resolve(ROOT, "src-tauri/Cargo.toml"), "utf8");
const lock = readFileSync(resolve(ROOT, "src-tauri/Cargo.lock"), "utf8").replace(/\r\n/g, "\n");
return directCrates(toml).map((name) => {
const version =
new RegExp(`\\[\\[package\\]\\]\\nname = "${name}"\\nversion = "([^"]+)"`).exec(lock)?.[1] ??
"?";
return { name, version, ...crateInfo(name) };
});
}
function table(rows: Row[], heading: string): string {
const lines = rows.map(
(r) => `| \`${r.name}\` | ${r.version} | ${r.license} | ${r.url ? `<${r.url}>` : "—"} |`,
);
return [
`| ${heading} | Version | License | Project |`,
"| --- | --- | --- | --- |",
...lines,
].join("\n");
}
export function renderNotices(): string {
const pkg = readJson<PackageJson>(resolve(ROOT, "package.json"));
const runtime = npmRows(Object.keys(pkg.dependencies ?? {}));
const dev = npmRows(Object.keys(pkg.devDependencies ?? {}));
return `<!-- Generated by scripts/third-party.ts (npm run generate:third-party). Edit the script, not this file; CI fails when it is stale. -->
# Third-Party Notices
YTDescGen is built on the open-source software and services below. Each component keeps its own license; the linked project pages carry the full terms.
The **complete license text of every package bundled into the web app** — including transitive dependencies such as \`scheduler\` or \`@babel/runtime\` — is published with each release at [\`/licenses/third-party.md\`](https://ytgenerator.stream/licenses/third-party.md), generated by Vite from the exact build.
## Runtime dependencies
Bundled into the web app and the desktop / Android apps.
${table(runtime, "Package")}
## Build and development tools
Used to build, test and check YTDescGen. Not shipped to users.
${table(dev, "Package")}
## Desktop and Android shell (Rust crates)
Direct dependencies of \`src-tauri/\`. Transitive crates are checked in CI by \`cargo deny\` (see \`src-tauri/deny.toml\`); \`cargo tree\` lists them all.
${table(crateRows(), "Crate")}
## Fonts and icons
- **Icons:** [Lucide](https://lucide.dev/) (\`lucide-react\`, ISC). Brand marks, where shown, come from [Simple Icons](https://simpleicons.org/) (CC0-1.0); the trademarks belong to their owners.
- **Fonts:** [Inter](https://rsms.me/inter/) and [JetBrains Mono](https://www.jetbrains.com/lp/mono/), bundled with the app from the \`@fontsource-variable\` packages above (SIL Open Font License 1.1, \`OFL-1.1\`).
## Services (web app only)
The web app at ytgenerator.stream is delivered by Cloudflare. These are services, not bundled code; the [Privacy Policy](PRIVACY.md) explains what each processes.
| Service | Purpose | Terms |
| --- | --- | --- |
| Cloudflare Workers | Hosting and delivery | <https://www.cloudflare.com/terms/> |
| Cloudflare Turnstile | Bot check before entering | <https://www.cloudflare.com/turnstile-privacy-policy/> |
| Cloudflare Web Analytics | Cookieless, aggregate visit statistics | <https://www.cloudflare.com/privacypolicy/> |
The desktop and Android apps use none of them.
## AI-assisted development
As described in the [Disclaimer](DISCLAIMER.md), YTDescGen is developed with **Anthropic's Claude Code** (Claude Opus models). The model contributes source code, translations, documentation and CI configuration; every change is reviewed by the maintainer (\`@poli0981\`) before it is merged. Claude is a product of Anthropic, PBC — <https://www.anthropic.com>. The Apache-2.0 license in [\`LICENSE\`](LICENSE) is granted by the project author, not by Anthropic.
## Questions and omissions
Licensing and attribution questions: **copyright@poli0981.dev**. If you believe something is missing here, open an issue or pull request per [\`CONTRIBUTING.md\`](CONTRIBUTING.md).
`;
}
/** Production packages (bundled into the app) whose license is not allowed. */
export function disallowedProductionLicenses(): string[] {
const lock = readJson<{
packages: Record<string, { dev?: boolean; devOptional?: boolean; license?: unknown }>;
}>(resolve(ROOT, "package-lock.json"));
const bad: string[] = [];
for (const [path, entry] of Object.entries(lock.packages)) {
if (path === "" || entry.dev || entry.devOptional) continue;
const license = typeof entry.license === "string" ? entry.license : "UNKNOWN";
if (!licenseAllowed(license)) bad.push(`${path.replace(/^.*node_modules\//, "")} (${license})`);
}
return bad;
}
export function main(): void {
const write = process.argv.includes("--write");
const expected = renderNotices();
if (write) {
writeFileSync(NOTICES, expected);
console.log("THIRD_PARTY_NOTICES.md regenerated.");
return;
}
let failed = false;
const bad = disallowedProductionLicenses();
if (bad.length > 0) {
failed = true;
console.error(`✗ Bundled packages with licenses outside the allowlist:\n ${bad.join("\n ")}`);
} else {
console.log("✓ Every bundled package has an allowed license.");
}
const current = readFileSync(NOTICES, "utf8").replace(/\r\n/g, "\n");
if (current !== expected) {
failed = true;
console.error("✗ THIRD_PARTY_NOTICES.md is stale — run `npm run generate:third-party`.");
} else {
console.log("✓ THIRD_PARTY_NOTICES.md matches package.json, the lockfile and Cargo.toml.");
}
if (failed) process.exit(1);
}
+10
View File
@@ -0,0 +1,10 @@
/**
* CLI for scripts/lib/third-party.ts:
*
* npm run generate:third-party rewrite THIRD_PARTY_NOTICES.md
* npm run check:licenses verify it is current and every bundled
* package has an allowed license
*/
import { main } from "./lib/third-party";
main();
+219 -745
View File
File diff suppressed because it is too large. Load diff
+2 -3
View File
@@ -1,6 +1,6 @@
[package]
name = "yt-desc-gen"
version = "0.35.0"
version = "1.2.0"
description = "YouTube Gameplay Description Generator"
authors = ["poli0981"]
edition = "2021"
@@ -16,9 +16,8 @@ tauri-build = { version = "2", features = [] }
[dependencies]
tauri = { version = "2", features = ["tray-icon"] }
tauri-plugin-dialog = "2"
tauri-plugin-fs = "2"
tauri-plugin-opener = "2"
tauri-plugin-shell = "2"
serde = { version = "1", features = ["derive"] }
# Desktop-only: single-instance is unsupported on mobile and must not be
# compiled into the Android/iOS library. cfg(not(any(android, ios))) is the
+4 -9
View File
@@ -1,16 +1,11 @@
{
"identifier": "default",
"description": "Default capabilities for YTDescGen",
"windows": ["main"],
"description": "Default capabilities for YTDescGen. File access goes through the app's own name-only commands and native dialogs run from Rust, so the webview gets no dialog, fs or shell permissions.",
"windows": [
"main"
],
"permissions": [
"core:default",
"dialog:default",
"dialog:allow-save",
"dialog:allow-open",
"fs:default",
"fs:allow-read-text-file",
"fs:allow-write-text-file",
"shell:default",
"opener:default"
]
}
+33
View File
@@ -0,0 +1,33 @@
# cargo-deny configuration for the Tauri shell. Run by
# .github/workflows/rust.yml (on changes under src-tauri/, and weekly for new
# RustSec advisories): `cargo deny check advisories licenses sources`.
[graph]
all-features = false
[advisories]
# Unmaintained crates only fail the check when this crate depends on them
# directly. The transitive ones today (e.g. proc-macro-error, RUSTSEC-2024-0370,
# via tauri's gtk-rs 0.18 Linux stack) have no safe upgrade until tauri moves
# on, and would otherwise keep this job permanently red. Vulnerabilities
# always fail, whatever the depth.
unmaintained = "workspace"
[licenses]
confidence-threshold = 0.9
# Permissive licenses, plus MPL-2.0 (file-level copyleft; used unmodified).
allow = [
"MIT",
"Apache-2.0",
"Apache-2.0 WITH LLVM-exception",
"BSD-3-Clause",
"ISC",
"Zlib",
"Unicode-3.0",
"MPL-2.0",
]
[sources]
unknown-registry = "deny"
unknown-git = "deny"
allow-registry = ["https://github.com/rust-lang/crates.io-index"]
@@ -5,7 +5,11 @@
<!-- AndroidTV support -->
<uses-feature android:name="android.software.leanback" android:required="false" />
<!-- allowBackup="false": the app's data (localStorage in the WebView) stays
on the device and is never copied to Google Drive backups. Users move
it to a new phone with the app's own Backup & Restore file. -->
<application
android:allowBackup="false"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:theme="@style/Theme.yt_desc_gen"
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<foreground android:drawable="@mipmap/ic_launcher_foreground"/>
<background android:drawable="@color/ic_launcher_background"/>
</adaptive-icon>
Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.4 KiB

After

Width:  |  Height:  |  Size: 3.2 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 1.2 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.4 KiB

After

Width:  |  Height:  |  Size: 2.5 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.3 KiB

After

Width:  |  Height:  |  Size: 2.0 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.9 KiB

After

Width:  |  Height:  |  Size: 840 B

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.3 KiB

After

Width:  |  Height:  |  Size: 1.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.8 KiB

After

Width:  |  Height:  |  Size: 4.2 KiB

Loaded 100 of 428 files, more files were not shown because too many files have changed in this diff. Show more