**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>
13 KiB
Technical Specifications
YTDescGen — Implementation Details
1. Package Configuration
package.json
{
"name": "yt-desc-gen",
"version": "0.20.0",
"private": true,
"type": "module",
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"preview": "vite preview",
"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",
"typecheck": "tsc --noEmit",
"format": "prettier --write \"src/**/*.{ts,tsx,json,css}\"",
"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"
},
"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"
},
"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"
}
}
tsconfig.json
{
"compilerOptions": {
"target": "ES2020",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"module": "ESNext",
"skipLibCheck": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"isolatedModules": true,
"moduleDetection": "force",
"noEmit": true,
"jsx": "react-jsx",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noUncheckedIndexedAccess": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@config/*": ["./src/config/*"],
"@engine/*": ["./src/engine/*"],
"@store/*": ["./src/store/*"],
"@hooks/*": ["./src/hooks/*"],
"@components/*": ["./src/components/*"],
"@pages/*": ["./src/pages/*"],
"@utils/*": ["./src/utils/*"],
"@i18n/*": ["./src/i18n/*"]
}
},
"include": ["src"]
}
vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "path";
export default defineConfig({
plugins: [react()],
base: "/yt-desc-gen/", // GitHub Pages
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"),
},
},
build: {
rollupOptions: {
output: {
manualChunks: {
react: ["react", "react-dom"],
router: ["react-router-dom"],
i18n: ["i18next", "react-i18next"],
},
},
},
},
});
tailwind.config.ts
import type { Config } from "tailwindcss";
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;
2. Core Engine Interfaces
// src/engine/types.ts
export interface GeneratorInput {
videoType: VideoType;
language: SupportedLanguage;
genre: Genre;
gameName: string;
gameNameLocalized?: Partial<Record<SupportedLanguage, string>>;
channelName: string;
platform: string;
partNumber?: string;
bossName?: string;
dlcName?: string;
challengeName?: string;
resolution?: string;
fps?: string;
graphicsPreset?: string;
timestamps?: string;
playlistLink?: string;
contactEmail?: string;
spoilerWarning: boolean;
matureWarning: boolean;
storeLinks: Partial<Record<string, string>>;
social: Partial<Record<string, string>>;
rig: Partial<Record<string, string>>;
}
export interface GeneratorOutput {
title: string;
description: string;
tags: string[];
tagString: string;
charCounts: {
title: number; // YouTube limit: 100
description: number; // YouTube limit: 5000
tags: number; // YouTube limit: 500
};
warnings: CharLimitWarning[];
}
export interface CharLimitWarning {
field: "title" | "description" | "tags";
current: number;
limit: number;
message: string;
}
// YouTube official limits
export const YT_LIMITS = {
TITLE_MAX: 100,
DESCRIPTION_MAX: 5000,
TAGS_MAX: 500,
SINGLE_TAG_MAX: 30, // single tag character limit
HASHTAG_MAX: 3,
} as const;
3. Zustand Store Pattern
// src/store/editor-store.ts
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;
setNested: <G extends "storeLinks" | "social" | "rig">(
group: G,
key: string,
value: string,
) => void;
loadProfile: (profile: Partial<GeneratorInput>) => void;
loadPreset: (preset: Partial<GeneratorInput>) => void;
reset: () => void;
}
export const useEditorStore = create<EditorState>()(
persist(
(set) => ({
...DEFAULTS.editor,
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),
}),
{
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;
},
},
),
);
4. GitHub Actions CI
# .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
# correctness
- run: npm run typecheck # src/
- run: npm run typecheck:all # + tests/ and scripts/
- run: npm run lint
- run: npm run validate:locales
- run: npm run test:run
# consistency
- run: npm run format:check
- run: npm run knip
- run: npm run check:version
# security (advisory — a fresh transitive advisory must not redden
# every unrelated PR before Dependabot opens its fix)
- run: npm audit --audit-level=high
continue-on-error: true
- run: npm run build
The workflow also declares permissions: contents: read (least privilege, and
it clears CodeQL's actions/missing-workflow-permissions alert) and a
concurrency group that cancels superseded runs everywhere except main, where
each commit's result is a historical record the release process reads back.
Why these gates exist. Every one of them was already installed and
configured before v0.35.0, and none of them ran. knip was in package.json
with a knip.json beside it. Prettier had a config and a format script.
Turning them on found real problems immediately — most notably that
tsconfig.json covers only src/, so tests/ and scripts/ had never been
type-checked, which was hiding three fields silently missing from the
editor→engine parity fixture whose entire job is catching that class of drift.
# .github/workflows/deploy-web.yml
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
5. Testing Strategy
// tests/engine/title-builder.test.ts
import { describe, it, expect } from "vitest";
import { buildTitle } from "@engine/title-builder";
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");
});
it("generates part title with number", () => {
const result = buildTitle({
gameName: "Elden Ring",
videoType: "part",
partNumber: "5",
language: "en",
});
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
| 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 |
Enforcement (v0.35.0)
renderAll has always returned warnings: CharLimitWarning[]; until v0.35.0
nothing in the UI read it. src/engine/limits.ts is now the single derivation,
consumed by useOutputLimits on Output and precomputed per row in Batch.
The rule is all-or-nothing per output: one over-limit field disables every
copy button for that output. checkTitleWarning / checkDescriptionWarning
only fire when a field is strictly over, never at the 80 % counter threshold,
so a non-empty warnings array is an exact "YouTube will reject this" signal.
Deliberately not gated by YT_LIMITS: thumbnail text and the pinned comment
(different surfaces), the Playlist tab (150-char title, not 100), and social
captions (per-platform caps in SOCIAL_PLATFORMS).
7. 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.
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 to cover profile / preset / template imports.