Files
youtube-generator/docs/TECH-SPEC.md
T
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

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.