diff --git a/.github/workflows/sdk-ci.yml b/.github/workflows/sdk-ci.yml
index f783557..b67d98e 100644
--- a/.github/workflows/sdk-ci.yml
+++ b/.github/workflows/sdk-ci.yml
@@ -50,7 +50,7 @@ jobs:
              git cat-file -e "$BASE_SHA^{commit}" 2>/dev/null &&
              git cat-file -e "$HEAD_SHA^{commit}" 2>/dev/null; then
             mapfile -d '' -t trust_changes < <(git diff --name-only --no-renames -z "$BASE_SHA" "$HEAD_SHA" -- \
-              .github/workflows/sdk-ci.yml scripts/verify-pr-ci-evidence.mjs)
+              .github/workflows/sdk-ci.yml scripts/verify-pr-ci-evidence.mjs scripts/validate-readme-cover-assets.mjs package.json pnpm-lock.yaml)
             if (( ${#trust_changes[@]} == 0 )); then
               allowed=true
             fi
@@ -89,10 +89,13 @@ jobs:
               path_class=must-full
               has_docs_assets=false
               has_reusable_source=false
+              has_cover_contract_change=false
+              declare -A cover_contract_paths=()
               cover_pattern='^\.github/assets/avatar-cover-(light|dark)-(en|zh-Hans)\.jpg$'
+              cover_generator='scripts/readme-cover.html'
               documentation_pattern='^(README(\.[[:alnum:]_-]+)?\.md|AGENTS\.md|packages/[[:alnum:]_.-]+/(README(\.[[:alnum:]_-]+)?|AGENTS)\.md|docs(/[[:alnum:]_.-]+)+\.(md|png|jpe?g|gif|webp|svg)|skills/[a-z0-9]+(-[a-z0-9]+)*/(SKILL\.md|references/[[:alnum:]_.-]+\.md|agents/openai\.yaml))$'
               reusable_source_pattern='^(src/|packages/|scripts/[[:alnum:]_.-]+\.mjs$|package\.json$|pnpm-lock\.yaml$|pnpm-workspace\.yaml$|tsconfig[^/]*\.json$|vite\.config\.[[:alnum:]_-]+$)'
-              must_full_pattern='^(scripts/readme-cover\.html|\.github/assets/bear-breed-profiles\.png|\.github/)'
+              must_full_pattern='^(package\.json|pnpm-lock\.yaml|scripts/validate-readme-cover-assets\.mjs|\.github/assets/bear-breed-profiles\.png|\.github/)'
 
               for (( index = 0; index < ${#changes[@]}; index += 2 )); do
                 change_status=${changes[index]}
@@ -114,11 +117,18 @@ jobs:
                   fi
                 fi
 
-                # The four generated README covers are the only .github paths
-                # eligible for docs-assets. Check them before the broad
-                # .github must-full rule so precedence cannot shadow them.
+                # A cover update is a bounded completeness rule, not a claim
+                # that these JPEGs are deterministically derived. Any change
+                # to the generator or one cover must update the generator and
+                # every cover as regular 100644 A/M files in this same diff.
                 if [[ "$changed_path" =~ $cover_pattern ]]; then
                   has_docs_assets=true
+                  has_cover_contract_change=true
+                  cover_contract_paths["$changed_path"]=1
+                elif [[ "$changed_path" == "$cover_generator" ]]; then
+                  has_docs_assets=true
+                  has_cover_contract_change=true
+                  cover_contract_paths["$changed_path"]=1
                 elif [[ "$changed_path" =~ $must_full_pattern ]]; then
                   break
                 elif [[ "$changed_path" =~ $documentation_pattern ]]; then
@@ -130,6 +140,22 @@ jobs:
                 fi
               done
 
+              if [[ "$index" -eq "${#changes[@]}" && "$has_cover_contract_change" == true ]]; then
+                required_cover_contract=(
+                  scripts/readme-cover.html
+                  .github/assets/avatar-cover-dark-en.jpg
+                  .github/assets/avatar-cover-light-en.jpg
+                  .github/assets/avatar-cover-dark-zh-Hans.jpg
+                  .github/assets/avatar-cover-light-zh-Hans.jpg
+                )
+                for required_path in "${required_cover_contract[@]}"; do
+                  if [[ -z "${cover_contract_paths[$required_path]+present}" ]]; then
+                    index=-1
+                    break
+                  fi
+                done
+              fi
+
               if [[ "$index" -eq "${#changes[@]}" ]]; then
                 if [[ "$has_docs_assets" == true && "$has_reusable_source" == false ]]; then
                   path_class=docs-assets
@@ -153,6 +179,24 @@ jobs:
           printf 'scope=%s\nbase=%s\nhead=%s\n' "$scope" "$BASE_SHA" "$HEAD_SHA" >> "$GITHUB_OUTPUT"
           printf 'Validation scope: %s\n' "$scope"
 
+      - name: Setup pnpm for documentation assets
+        if: steps.scope.outputs.scope == 'docs-assets'
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.7.0
+
+      - name: Setup Node.js for documentation assets
+        if: steps.scope.outputs.scope == 'docs-assets'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install documentation asset validator dependencies
+        if: steps.scope.outputs.scope == 'docs-assets'
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
       - name: Validate documentation, cover assets, and skill metadata
         if: steps.scope.outputs.scope == 'docs-assets'
         shell: bash
@@ -163,6 +207,8 @@ jobs:
           set -euo pipefail
           git diff --check "$BASE_SHA" "$HEAD_SHA"
 
+          node scripts/validate-readme-cover-assets.mjs
+
           python3 - <<'PY'
           import json
           import os
diff --git a/__tests__/sdkCiWorkflow.spec.ts b/__tests__/sdkCiWorkflow.spec.ts
index 4c0ff85..0e78267 100644
--- a/__tests__/sdkCiWorkflow.spec.ts
+++ b/__tests__/sdkCiWorkflow.spec.ts
@@ -1,11 +1,13 @@
 import { execFileSync } from 'node:child_process'
-import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { chmodSync, cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 
+import jpeg from 'jpeg-js'
 import { describe, expect, it } from 'vitest'
 
 const workflowPath = new URL('../.github/workflows/sdk-ci.yml', import.meta.url)
+const helperPath = new URL('../scripts/validate-readme-cover-assets.mjs', import.meta.url)
 const git = (cwd: string, args: string[]) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim()
 const commit = (cwd: string, message: string) => {
   git(cwd, ['add', '-A'])
@@ -26,13 +28,6 @@ const classifier = () => workflowBlock('Classify validation scope')
 
 const evidenceEligibility = () => workflowBlock('Guard reusable evidence trust boundary')
 
-const docsValidator = () => {
-  const workflow = readFileSync(workflowPath, 'utf8')
-  const match = workflow.match(/          python3 - <<'PY'\n([\s\S]*?)\n          PY/u)
-  expect(match?.[1]).toBeTruthy()
-  return match![1].replace(/^          /gmu, '')
-}
-
 describe('Avatar SDK CI workflow', () => {
   it('keeps the required identity behind validation and produces evidence in an isolated job', () => {
     const workflow = readFileSync(workflowPath, 'utf8')
@@ -72,6 +67,9 @@ describe('Avatar SDK CI workflow', () => {
     writeFileSync(join(root, 'README.md'), 'base\n')
     writeFileSync(join(root, 'src', 'code.ts'), 'base\n')
     writeFileSync(join(root, 'scripts', 'readme-cover.html'), '<!doctype html>\n')
+    writeFileSync(join(root, 'scripts', 'validate-readme-cover-assets.mjs'), 'base\n')
+    writeFileSync(join(root, 'package.json'), '{}\n')
+    writeFileSync(join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9\n')
     for (const cover of covers) writeFileSync(join(root, '.github', 'assets', cover), 'cover\n')
     writeFileSync(join(root, '.github', 'assets', 'bear-breed-profiles.png'), 'bear\n')
     writeFileSync(join(root, '.github', 'workflows', 'other.yml'), 'name: other\n')
@@ -83,8 +81,14 @@ describe('Avatar SDK CI workflow', () => {
       return commit(root, name)
     }
     const coverHeads = covers.map(cover => make(cover, () => writeFileSync(join(root, '.github', 'assets', cover), `new ${cover}\n`)))
+    const coverContract = make('complete cover contract', () => {
+      writeFileSync(join(root, 'scripts', 'readme-cover.html'), '<!doctype html> changed\n')
+      for (const cover of covers) writeFileSync(join(root, '.github', 'assets', cover), `new ${cover}\n`)
+    })
     const docs = make('docs', () => writeFileSync(join(root, 'README.md'), 'docs\n'))
     const source = make('source', () => writeFileSync(join(root, 'src', 'code.ts'), 'source\n'))
+    const packageJson = make('package manifest', () => writeFileSync(join(root, 'package.json'), '{"changed":true}\n'))
+    const lockfile = make('package lockfile', () => writeFileSync(join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9\nchanged: true\n'))
     const coverHtml = make('cover html', () => writeFileSync(join(root, 'scripts', 'readme-cover.html'), '<script>bad</script>\n'))
     const bear = make('bear', () => writeFileSync(join(root, '.github', 'assets', 'bear-breed-profiles.png'), 'changed\n'))
     const otherGithub = make('other github', () => writeFileSync(join(root, '.github', 'workflows', 'other.yml'), 'name: changed\n'))
@@ -112,14 +116,20 @@ describe('Avatar SDK CI workflow', () => {
       return readFileSync(output, 'utf8').match(/^scope=(.*)$/m)?.[1]
     }
 
-    for (const cover of coverHeads) expect(run('pull_request', cover, 'full')).toBe('docs-assets')
+    for (const cover of coverHeads) expect(run('pull_request', cover, 'full')).toBe('full')
+    expect(run('pull_request', coverContract, 'full')).toBe('docs-assets')
     expect(run('pull_request', docs, 'full')).toBe('docs-assets')
     expect(run('pull_request', source, 'full')).toBe('full')
-    for (const cover of coverHeads) expect(run('push', cover)).toBe('docs-assets')
+    expect(run('pull_request', packageJson, 'reused-pr-ci')).toBe('full')
+    expect(run('pull_request', lockfile, 'reused-pr-ci')).toBe('full')
+    for (const cover of coverHeads) expect(run('push', cover)).toBe('full')
+    expect(run('push', coverContract)).toBe('docs-assets')
     expect(run('push', source)).toBe('reused-pr-ci')
+    expect(run('push', packageJson)).toBe('full')
+    expect(run('push', lockfile)).toBe('full')
     expect(run('push', source, 'full')).toBe('full')
     expect(run('push', docs, 'full')).toBe('full')
-    expect(run('workflow_dispatch', coverHeads[0])).toBe('full')
+    expect(run('workflow_dispatch', coverContract)).toBe('full')
     for (const head of [coverHtml, bear, otherGithub, unknown, deletion, rename, executable, symlink, mixed]) {
       expect(run('push', head)).toBe('full')
     }
@@ -133,6 +143,9 @@ describe('Avatar SDK CI workflow', () => {
     mkdirSync(join(root, 'src'))
     writeFileSync(join(root, '.github', 'workflows', 'sdk-ci.yml'), 'base\n')
     writeFileSync(join(root, 'scripts', 'verify-pr-ci-evidence.mjs'), 'base\n')
+    writeFileSync(join(root, 'scripts', 'validate-readme-cover-assets.mjs'), 'base\n')
+    writeFileSync(join(root, 'package.json'), '{}\n')
+    writeFileSync(join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9\n')
     writeFileSync(join(root, 'src', 'code.ts'), 'base\n')
     const base = commit(root, 'base')
     const make = (path: string) => {
@@ -143,6 +156,9 @@ describe('Avatar SDK CI workflow', () => {
     const source = make('src/code.ts')
     const workflow = make('.github/workflows/sdk-ci.yml')
     const helper = make('scripts/verify-pr-ci-evidence.mjs')
+    const validator = make('scripts/validate-readme-cover-assets.mjs')
+    const packageJson = make('package.json')
+    const lockfile = make('pnpm-lock.yaml')
     const run = (head: string) => {
       const output = join(root, `eligibility-${head.slice(0, 8)}`)
       execFileSync('bash', ['-c', evidenceEligibility()], {
@@ -155,31 +171,105 @@ describe('Avatar SDK CI workflow', () => {
     expect(run(source)).toBe('true')
     expect(run(workflow)).toBe('false')
     expect(run(helper)).toBe('false')
+    expect(run(validator)).toBe('false')
+    expect(run(packageJson)).toBe('false')
+    expect(run(lockfile)).toBe('false')
   })
 
-  it('validates all four real README cover links during a cover-only update', () => {
+  it('runs the real cover validator against structural and complete-decode fixtures', () => {
     const root = mkdtempSync(join(tmpdir(), 'avatar-cover-validator-'))
     git(root, ['init', '-b', 'main'])
+    mkdirSync(join(root, 'scripts'), { recursive: true })
     mkdirSync(join(root, '.github', 'assets'), { recursive: true })
-    const en = ['.github/assets/avatar-cover-dark-en.jpg', '.github/assets/avatar-cover-light-en.jpg']
-    const zh = ['.github/assets/avatar-cover-dark-zh-Hans.jpg', '.github/assets/avatar-cover-light-zh-Hans.jpg']
-    writeFileSync(join(root, 'README.md'), en.map(path => `<img src="${path}">`).join('\n'))
-    writeFileSync(join(root, 'README.zh-Hans.md'), zh.map(path => `<img src="${path}">`).join('\n'))
-    for (const image of [...en, ...zh]) writeFileSync(join(root, image), Buffer.from([0xff, 0xd8, 0xff, 0xd9]))
+    symlinkSync(join(process.cwd(), 'node_modules'), join(root, 'node_modules'), 'dir')
+    for (const path of ['README.md', 'README.zh-Hans.md', 'scripts/readme-cover.html']) cpSync(new URL(`../${path}`, import.meta.url), join(root, path))
+    cpSync(helperPath, join(root, 'scripts', 'validate-readme-cover-assets.mjs'))
+    const covers = ['avatar-cover-dark-en.jpg', 'avatar-cover-light-en.jpg', 'avatar-cover-dark-zh-Hans.jpg', 'avatar-cover-light-zh-Hans.jpg']
+    for (const cover of covers) cpSync(new URL(`../.github/assets/${cover}`, import.meta.url), join(root, '.github', 'assets', cover))
+    for (const [, source] of readFileSync(new URL('../scripts/readme-cover.html', import.meta.url), 'utf8').matchAll(/<img\s+[^>]*\bsrc="([^"]+)"[^>]*>/gu)) {
+      const destination = join(root, source.slice(3))
+      mkdirSync(dirname(destination), { recursive: true })
+      cpSync(new URL(`../scripts/${source}`, import.meta.url), destination)
+    }
     const base = commit(root, 'base')
-    writeFileSync(join(root, en[0]), Buffer.from([0xff, 0xd8, 0xff, 0x00, 0xff, 0xd9]))
-    const valid = commit(root, 'cover update')
-    const execute = (head: string) => execFileSync('python3', ['-c', docsValidator()], {
-      cwd: root,
-      env: { ...process.env, BASE_SHA: base, HEAD_SHA: head },
-      stdio: 'pipe'
-    })
+    const execute = (head: string) => {
+      git(root, ['checkout', '--detach', head])
+      expect(git(root, ['rev-parse', 'HEAD'])).toBe(head)
+      return execFileSync('node', ['scripts/validate-readme-cover-assets.mjs'], {
+        cwd: root,
+        env: { ...process.env, BASE_SHA: base, HEAD_SHA: head },
+        stdio: 'pipe'
+      })
+    }
+    writeFileSync(join(root, 'README.md'), `${readFileSync(join(root, 'README.md'), 'utf8')}\n`)
+    const valid = commit(root, 'README-only update')
     expect(() => execute(valid)).not.toThrow()
 
-    writeFileSync(join(root, 'README.md'), `<img src="${en[0]}">\n${en[1]}`)
-    writeFileSync(join(root, en[1]), Buffer.from([0xff, 0xd8, 0xff, 0x01, 0xff, 0xd9]))
-    const missingLink = commit(root, 'missing link')
-    expect(() => execute(missingLink)).toThrow()
+    const make = (name: string, mutate: () => void) => {
+      git(root, ['checkout', '--detach', base])
+      mutate()
+      return commit(root, name)
+    }
+    const completeContract = () => {
+      for (const cover of covers) {
+        const file = join(root, '.github', 'assets', cover)
+        const data = readFileSync(file)
+        writeFileSync(file, Buffer.concat([data.subarray(0, 2), Buffer.from([0xff, 0xe0, 0, 2]), data.subarray(2)]))
+      }
+    }
+    const generatorInvalid = (name: string, mutation: (source: string) => string) => make(name, () => {
+      const file = join(root, 'scripts', 'readme-cover.html')
+      writeFileSync(file, mutation(readFileSync(file, 'utf8')))
+      completeContract()
+    })
+    const generatorScriptAttribute = generatorInvalid('script attribute', source => source.replace('<script>', '<ScRiPt type="text/javascript">'))
+    const multipleScript = generatorInvalid('multiple script', source => source.replace('</body>', '<script></script></body>'))
+    const multipleStyle = generatorInvalid('multiple style', source => source.replace('</head>', '<style></style></head>'))
+    const unsafeCss = generatorInvalid('unsafe css', source => source.replace('<style>', '<style>@import url(https://example.invalid);'))
+    const unsafeTag = generatorInvalid('unsafe tag', source => source.replace('</main>', '<iframe src="https://example.invalid"></iframe></main>'))
+    const eventAttribute = generatorInvalid('event attribute', source => source.replace('<main id="cover">', '<main id="cover" onload="alert(1)">'))
+    const traversal = generatorInvalid('traversal', source => source.replace('../src/avatarPresetSnapshots/', '../src/avatarPresetSnapshots/../'))
+    const fencedPicture = make('fenced picture', () => writeFileSync(join(root, 'README.md'), '```html\n<picture><source media="(prefers-color-scheme: dark)" srcset=".github/assets/avatar-cover-dark-en.jpg"><source media="(prefers-color-scheme: light)" srcset=".github/assets/avatar-cover-light-en.jpg"><img alt="OneWorks Avatar — a growing gallery of geometric 3D avatars and pixel styles" src=".github/assets/avatar-cover-light-en.jpg" width="1600"></picture>\n```'))
+    const commentedPicture = make('commented picture', () => writeFileSync(join(root, 'README.md'), `<!-- ${readFileSync(join(root, 'README.md'), 'utf8')} -->`))
+    const inlinePicture = make('inline picture', () => writeFileSync(join(root, 'README.md'), '`<picture><img src=".github/assets/avatar-cover-light-en.jpg"></picture>`'))
+    const wrongOrder = make('wrong picture order', () => writeFileSync(join(root, 'README.md'), readFileSync(join(root, 'README.md'), 'utf8').replace('<source media="(prefers-color-scheme: dark)"', '<img alt="OneWorks Avatar — a growing gallery of geometric 3D avatars and pixel styles" src=".github/assets/avatar-cover-light-en.jpg" width="1600"><source media="(prefers-color-scheme: dark)"')))
+    const duplicateMedia = make('duplicate cover media', () => writeFileSync(join(root, 'README.md'), `${readFileSync(join(root, 'README.md'), 'utf8')}\n<img src=".github/assets/avatar-cover-light-en.jpg">`))
+    const srcset = make('unexpected srcset', () => writeFileSync(join(root, 'README.md'), readFileSync(join(root, 'README.md'), 'utf8').replace(' width="1600">', ' width="1600" srcset=".github/assets/avatar-cover-light-en.jpg">')))
+    const symlink = make('cover symlink', () => { rmSync(join(root, '.github', 'assets', covers[0])); symlinkSync(covers[1], join(root, '.github', 'assets', covers[0])) })
+    const reencoded = () => {
+      completeContract()
+      writeFileSync(join(root, 'scripts', 'readme-cover.html'), `${readFileSync(join(root, 'scripts', 'readme-cover.html'), 'utf8')}\n`)
+    }
+    const trailing = make('trailing JPEG data', () => { reencoded(); writeFileSync(join(root, '.github', 'assets', covers[0]), Buffer.concat([readFileSync(join(root, '.github', 'assets', covers[0])), Buffer.from('trailer')])) })
+    const secondEoi = make('second JPEG EOI', () => { reencoded(); const file = join(root, '.github', 'assets', covers[0]); writeFileSync(file, Buffer.concat([readFileSync(file), Buffer.from([0xff, 0xd9])])) })
+    const truncated = make('truncated JPEG data', () => { reencoded(); const file = join(root, '.github', 'assets', covers[0]); writeFileSync(file, readFileSync(file).subarray(0, -16)) })
+    const corruptEntropy = make('corrupt JPEG entropy', () => {
+      reencoded()
+      const file = join(root, '.github', 'assets', covers[0])
+      const data = readFileSync(file)
+      const scan = data.indexOf(Buffer.from([0xff, 0xda]))
+      const entropy = scan + 2 + data.readUInt16BE(scan + 2)
+      data[entropy] = 0xff
+      data[entropy + 1] = 0x01
+      writeFileSync(file, data)
+    })
+    const wrongDimensions = make('wrong JPEG dimensions', () => {
+      reencoded()
+      const frame = Buffer.alloc(800 * 450 * 4)
+      for (let pixel = 0; pixel < frame.length; pixel += 4) {
+        frame[pixel] = (pixel * 17) & 255
+        frame[pixel + 1] = (pixel * 29) & 255
+        frame[pixel + 2] = (pixel * 43) & 255
+        frame[pixel + 3] = 255
+      }
+      writeFileSync(join(root, '.github', 'assets', covers[0]), jpeg.encode({ data: frame, width: 800, height: 450 }, 50).data)
+    })
+    const invalid = [
+      [generatorScriptAttribute, /unexpected type attribute/], [multipleScript, /head\/body\/cover structure/], [multipleStyle, /head\/body\/cover structure/], [unsafeCss, /stylesheet/], [unsafeTag, /disallowed/], [eventAttribute, /unexpected onload attribute/], [traversal, /invalid generator snapshot path/],
+      [fencedPicture, /exactly one picture/], [commentedPicture, /exactly one picture/], [inlinePicture, /exactly one picture/], [wrongOrder, /dark source, light source/], [duplicateMedia, /duplicate, unexpected, or cross-language/], [srcset, /unexpected attributes/], [symlink, /unsupported changed entry T/],
+      [trailing, /first JPEG EOI/], [secondEoi, /first JPEG EOI/], [truncated, /missing a terminal EOI|entropy stream is truncated/], [corruptEntropy, /JPEG marker stream is malformed/], [wrongDimensions, /1600x900/]
+    ] as const
+    for (const [head, reason] of invalid) expect(() => execute(head)).toThrow(reason)
   })
 
   it('keeps the repository READMEs linked to every required cover', () => {
@@ -189,5 +279,6 @@ describe('Avatar SDK CI workflow', () => {
     expect(english).toContain('.github/assets/avatar-cover-light-en.jpg')
     expect(chinese).toContain('.github/assets/avatar-cover-dark-zh-Hans.jpg')
     expect(chinese).toContain('.github/assets/avatar-cover-light-zh-Hans.jpg')
+    expect(() => readFileSync(new URL('../scripts/readme-cover-assets.json', import.meta.url), 'utf8')).toThrow()
   })
 })
diff --git a/package.json b/package.json
index 4f497da..6423ba1 100644
--- a/package.json
+++ b/package.json
@@ -36,7 +36,9 @@
   "devDependencies": {
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.2",
+    "jpeg-js": "^0.4.4",
     "jsdom": "^26.1.0",
+    "markdown-it": "^15.0.1",
     "@vitejs/plugin-react": "^5.1.2",
     "@vitejs/plugin-vue": "^5.2.4",
     "react": "^18.3.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ce4cca6..7dce445 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -33,9 +33,15 @@ importers:
       '@vitejs/plugin-vue':
         specifier: ^5.2.4
         version: 5.2.4(vite@5.4.21(sass@1.101.0))(vue@3.5.41(typescript@5.9.3))
+      jpeg-js:
+        specifier: ^0.4.4
+        version: 0.4.4
       jsdom:
         specifier: ^26.1.0
         version: 26.1.0
+      markdown-it:
+        specifier: ^15.0.1
+        version: 15.0.1
       react:
         specifier: ^18.3.1
         version: 18.3.1
@@ -865,6 +871,9 @@ packages:
   argparse@1.0.10:
     resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
 
+  argparse@3.0.1:
+    resolution: {integrity: sha512-nM4mHF/KM1v59ZNKX7zfusQz5wUAxR511YG8Vo6TyiV4aqhu++rbJW4v04xsWhpSsHFj66flT8P7znVpyO20xQ==}
+
   assertion-error@2.0.1:
     resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
     engines: {node: '>=12'}
@@ -973,6 +982,10 @@ packages:
     resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==}
     engines: {node: '>=0.12'}
 
+  entities@8.0.0:
+    resolution: {integrity: sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==}
+    engines: {node: '>=20.19.0'}
+
   es-errors@1.3.0:
     resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
     engines: {node: '>= 0.4'}
@@ -1092,6 +1105,9 @@ packages:
   jju@1.4.0:
     resolution: {integrity: sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==}
 
+  jpeg-js@0.4.4:
+    resolution: {integrity: sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg==}
+
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
@@ -1126,6 +1142,9 @@ packages:
   kolorist@1.8.0:
     resolution: {integrity: sha512-Y+60/zizpJ3HRH8DCss+q95yr6145JXZo46OTpFvDZWLfRCE4qChOyk1b26nMaNpfHHgxagk9dXT5OP0Tfe+dQ==}
 
+  linkify-it@6.1.0:
+    resolution: {integrity: sha512-wJ/TwpSDTLepCrQoYWYIExIKg5Zchex2Nn5yk2mFnB+6PtdkHtyLx742md9csRjjOnGkKIS/RrbY7l8D6gT9Vw==}
+
   local-pkg@1.2.1:
     resolution: {integrity: sha512-++gUqRDEvcnN6Zhqrr+y/CkVEHhlrR96vZn3nZZPYzMcBUyBtTKzB9NadClFIsIVSsu+3i9tfk/erqy9kAmt7Q==}
     engines: {node: '>=14'}
@@ -1146,6 +1165,13 @@ packages:
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
+  markdown-it@15.0.1:
+    resolution: {integrity: sha512-9/7gE95FNPkfUWrjJIoHZza2iLmuJlPD0UNMxPi7bxUrbCR525YZY0r+zyfes0dZI5ZZ/uNIXUJca0pJvtw41g==}
+    hasBin: true
+
+  mdurl@2.1.0:
+    resolution: {integrity: sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==}
+
   minimatch@10.2.3:
     resolution: {integrity: sha512-Rwi3pnapEqirPSbWbrZaa6N3nmqq4Xer/2XooiOKyV3q12ML06f7MOuc5DVH8ONZIFhwIYQ3yzPH4nt7iWHaTg==}
     engines: {node: 18 || 20 || >=22}
@@ -1220,6 +1246,10 @@ packages:
     resolution: {integrity: sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==}
     engines: {node: ^10 || ^12 || >=14}
 
+  punycode.js@2.3.1:
+    resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==}
+    engines: {node: '>=6'}
+
   punycode@2.3.1:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
@@ -1365,6 +1395,9 @@ packages:
     engines: {node: '>=14.17'}
     hasBin: true
 
+  uc.micro@3.0.0:
+    resolution: {integrity: sha512-U3PppEkleoTnIfi8BozMx3yju3qc/L6SwqWo2Sw+54PX+PX0q9I+r1Um5HCmqD7n9VDX5/v3vQH/AjA6deDdtw==}
+
   ufo@1.6.4:
     resolution: {integrity: sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==}
 
@@ -2227,6 +2260,8 @@ snapshots:
     dependencies:
       sprintf-js: 1.0.3
 
+  argparse@3.0.1: {}
+
   assertion-error@2.0.1: {}
 
   balanced-match@1.0.2: {}
@@ -2310,6 +2345,8 @@ snapshots:
 
   entities@7.0.1: {}
 
+  entities@8.0.0: {}
+
   es-errors@1.3.0: {}
 
   es-module-lexer@1.7.0: {}
@@ -2427,6 +2464,8 @@ snapshots:
 
   jju@1.4.0: {}
 
+  jpeg-js@0.4.4: {}
+
   js-tokens@4.0.0: {}
 
   js-tokens@9.0.1: {}
@@ -2472,6 +2511,10 @@ snapshots:
 
   kolorist@1.8.0: {}
 
+  linkify-it@6.1.0:
+    dependencies:
+      uc.micro: 3.0.0
+
   local-pkg@1.2.1:
     dependencies:
       mlly: 1.8.2
@@ -2494,6 +2537,17 @@ snapshots:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  markdown-it@15.0.1:
+    dependencies:
+      argparse: 3.0.1
+      entities: 8.0.0
+      linkify-it: 6.1.0
+      mdurl: 2.1.0
+      punycode.js: 2.3.1
+      uc.micro: 3.0.0
+
+  mdurl@2.1.0: {}
+
   minimatch@10.2.3:
     dependencies:
       brace-expansion: 5.0.9
@@ -2564,6 +2618,8 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  punycode.js@2.3.1: {}
+
   punycode@2.3.1: {}
 
   quansync@0.2.11: {}
@@ -2703,6 +2759,8 @@ snapshots:
 
   typescript@5.9.3: {}
 
+  uc.micro@3.0.0: {}
+
   ufo@1.6.4: {}
 
   universalify@2.0.1: {}
diff --git a/scripts/validate-readme-cover-assets.mjs b/scripts/validate-readme-cover-assets.mjs
new file mode 100644
index 0000000..d3c0638
--- /dev/null
+++ b/scripts/validate-readme-cover-assets.mjs
@@ -0,0 +1,219 @@
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { extname, relative, resolve, sep } from 'node:path'
+
+import { JSDOM } from 'jsdom'
+import jpeg from 'jpeg-js'
+import MarkdownIt from 'markdown-it'
+
+const root = realpathSync('.')
+const generator = 'scripts/readme-cover.html'
+const covers = [
+  '.github/assets/avatar-cover-dark-en.jpg',
+  '.github/assets/avatar-cover-light-en.jpg',
+  '.github/assets/avatar-cover-dark-zh-Hans.jpg',
+  '.github/assets/avatar-cover-light-zh-Hans.jpg'
+]
+const coverSet = new Set(covers)
+const contractSet = new Set([generator, ...covers])
+const scriptDigest = 'ec2194277b73b7795cc1b96411939c1c2518125bfcd996df39fc0c9fd926d52a'
+const markdown = new MarkdownIt({ html: true })
+const fail = message => { throw new Error(`Invalid README cover assets: ${message}`) }
+const hash = value => createHash('sha256').update(value).digest('hex')
+
+const pathAtRoot = path => {
+  if (!path || path.includes('\0') || path.startsWith('/') || path.split('/').includes('..')) fail(`unsafe path ${path}`)
+  const absolute = resolve(root, path)
+  if (absolute !== root && !absolute.startsWith(`${root}${sep}`)) fail(`path escapes repository: ${path}`)
+  return absolute
+}
+
+const regular644 = path => {
+  const entry = lstatSync(pathAtRoot(path))
+  if (!entry.isFile() || entry.isSymbolicLink() || (entry.mode & 0o777) !== 0o644) fail(`${path} must be a regular non-executable 100644 file`)
+}
+
+const changedPaths = () => {
+  const { BASE_SHA: base, HEAD_SHA: head } = process.env
+  if (!/^[0-9a-f]{40}$/iu.test(base ?? '') || !/^[0-9a-f]{40}$/iu.test(head ?? '')) fail('BASE_SHA and HEAD_SHA must be commit SHA-1 values')
+  const fields = execFileSync('git', ['diff', '--name-status', '--no-renames', '-z', base, head], { encoding: 'buffer' }).toString('utf8').split('\0').filter(Boolean)
+  if (!fields.length || fields.length % 2) fail('expected a non-empty name-status diff')
+  const paths = []
+  for (let index = 0; index < fields.length; index += 2) {
+    const [status, path] = [fields[index], fields[index + 1]]
+    if (!/^[AM]$/u.test(status)) fail(`unsupported changed entry ${status} ${path}`)
+    paths.push(path)
+  }
+  const contractChanges = paths.filter(path => contractSet.has(path))
+  if (contractChanges.length && (contractChanges.length !== contractSet.size || ![...contractSet].every(path => contractChanges.includes(path)))) {
+    fail('a generator or cover change must include the generator and all four covers in the same A/M diff')
+  }
+  return paths
+}
+
+const exactAttributes = (element, expected) => {
+  const actual = [...element.attributes].map(attribute => [attribute.name.toLowerCase(), attribute.value]).sort(([a], [b]) => a.localeCompare(b))
+  const wanted = Object.entries(expected).sort(([a], [b]) => a.localeCompare(b))
+  if (JSON.stringify(actual) !== JSON.stringify(wanted)) fail(`unexpected attributes on <${element.tagName.toLowerCase()}>`)
+}
+
+const validateSvg = path => {
+  regular644(path)
+  const source = readFileSync(pathAtRoot(path), 'utf8')
+  if (/<!\s*(?:doctype|entity)\b|<\?\s*xml-stylesheet\b/iu.test(source)) fail(`unsafe SVG declaration in ${path}`)
+  const document = new JSDOM(source, { contentType: 'image/svg+xml' }).window.document
+  if (document.documentElement?.localName !== 'svg' || document.querySelector('parsererror')) fail(`invalid SVG input ${path}`)
+  for (const element of document.querySelectorAll('*')) {
+    const tag = element.localName.toLowerCase()
+    if (['script', 'foreignobject', 'iframe', 'object', 'embed', 'style'].includes(tag)) fail(`active SVG element in ${path}`)
+    for (const attribute of element.attributes) {
+      const name = attribute.name.toLowerCase()
+      const value = attribute.value.trim()
+      if (name === 'xmlns' || name.startsWith('xmlns:')) continue
+      const safeEmbeddedImage = ['href', 'src'].includes(name) && /^data:image\/(?:png|jpeg);base64,[A-Za-z0-9+/]+={0,2}$/u.test(value)
+      if (safeEmbeddedImage) continue
+      if (name.startsWith('on') || /(?:javascript:|https?:|\/\/|@import)/iu.test(value)) fail(`unsafe SVG attribute in ${path}`)
+      if (['href', 'src'].includes(name) && !/^#[A-Za-z_][A-Za-z0-9_.:-]*$/u.test(value) && !/^data:image\/(?:png|jpeg);base64,[A-Za-z0-9+/]+={0,2}$/u.test(value)) fail(`external SVG input in ${path}`)
+      for (const reference of value.matchAll(/url\s*\(([^)]*)\)/giu)) if (!/^\s*#[A-Za-z_][A-Za-z0-9_.:-]*\s*$/u.test(reference[1])) fail(`external SVG reference in ${path}`)
+    }
+  }
+}
+
+const validateGenerator = () => {
+  regular644(generator)
+  const source = readFileSync(pathAtRoot(generator), 'utf8')
+  if (!/^<!doctype html>\s*/iu.test(source)) fail('generator must begin with the HTML doctype')
+  const document = new JSDOM(source, { runScripts: 'outside-only', resources: undefined }).window.document
+  if (document.doctype?.name.toLowerCase() !== 'html' || document.documentElement.lang !== 'en') fail('generator must have the expected HTML root')
+  const allowed = new Set(['html', 'head', 'meta', 'title', 'style', 'body', 'main', 'div', 'i', 'span', 'section', 'p', 'h1', 'svg', 'path', 'rect', 'circle', 'img', 'script'])
+  const allowedAttributes = {
+    html: new Set(['lang']), meta: new Set(['charset', 'name', 'content']), main: new Set(['id']),
+    div: new Set(['class', 'data-size', 'data-slot']), i: new Set(['class']), section: new Set(['class', 'data-copy', 'aria-label']),
+    p: new Set(['class']), svg: new Set(['viewbox', 'aria-hidden', 'class']), path: new Set(['d']),
+    rect: new Set(['x', 'y', 'width', 'height', 'rx']), circle: new Set(['cx', 'cy', 'r']), img: new Set(['src', 'alt'])
+  }
+  for (const element of document.querySelectorAll('*')) {
+    const tag = element.localName.toLowerCase()
+    if (!allowed.has(tag)) fail(`generator contains disallowed <${tag}>`)
+    for (const attribute of element.attributes) {
+      const name = attribute.name.toLowerCase()
+      const value = attribute.value.trim()
+      if (!allowedAttributes[tag]?.has(name)) fail(`generator contains unexpected ${name} attribute on <${tag}>`)
+      if (name.startsWith('on') || ['href', 'srcset', 'action', 'formaction'].includes(name) || /(?:javascript:|https?:|\/\/|data:)/iu.test(value)) fail(`generator contains an executable or network-capable attribute on <${tag}>`)
+    }
+  }
+  const head = document.head
+  const body = document.body
+  if (!head || !body || document.documentElement.children.length !== 2 || [...head.children].map(element => element.localName).join(',') !== 'meta,meta,title,style' || !document.querySelector('main#cover') || [...body.children].map(element => element.localName).join(',') !== 'main,script') fail('generator must retain its exact head/body/cover structure')
+  exactAttributes(head.children[0], { charset: 'UTF-8' })
+  exactAttributes(head.children[1], { name: 'viewport', content: 'width=device-width, initial-scale=1.0' })
+  if (head.children[2].textContent !== 'OneWorks Avatar README cover') fail('generator title changed')
+  exactAttributes(document.querySelector('main#cover'), { id: 'cover' })
+  const scripts = [...document.querySelectorAll('script')]
+  const styles = [...document.querySelectorAll('style')]
+  if (scripts.length !== 1 || scripts[0].attributes.length || hash(scripts[0].textContent) !== scriptDigest) fail('generator runtime contract changed')
+  if (styles.length !== 1 || styles[0].attributes.length || /@import|url\s*\(|expression\s*\(|behavior\s*:|-moz-binding|(?:https?:|\/\/|javascript:|data:)/iu.test(styles[0].textContent)) fail('generator stylesheet must be static and self-contained')
+  const images = [...document.querySelectorAll('img')]
+  if (!images.length) fail('generator must contain snapshot images')
+  const snapshotRoot = realpathSync(pathAtRoot('src/avatarPresetSnapshots'))
+  const inputs = new Set()
+  for (const image of images) {
+    exactAttributes(image, { src: image.getAttribute('src'), alt: image.getAttribute('alt') })
+    const sourcePath = image.getAttribute('src')
+    if (!sourcePath?.startsWith('../src/avatarPresetSnapshots/') || sourcePath.includes('..', 3) || extname(sourcePath).toLowerCase() !== '.svg') fail(`invalid generator snapshot path ${sourcePath}`)
+    const input = sourcePath.slice(3)
+    if (inputs.has(input)) fail(`duplicate generator snapshot ${input}`)
+    inputs.add(input)
+    regular644(input)
+    const resolved = realpathSync(pathAtRoot(input))
+    if (!resolved.startsWith(`${snapshotRoot}${sep}`)) fail(`snapshot escapes avatarPresetSnapshots: ${input}`)
+    validateSvg(input)
+  }
+}
+
+const parseJpeg = data => {
+  if (data.length < 4 || data[0] !== 0xff || data[1] !== 0xd8) fail('JPEG is missing its SOI marker')
+  let offset = 2
+  let components
+  let sawScan = false
+  const markerAt = () => {
+    if (data[offset] !== 0xff) fail('JPEG marker stream is malformed')
+    while (data[offset] === 0xff) offset += 1
+    if (offset >= data.length || data[offset] === 0x00) fail('JPEG marker stream is malformed')
+    return data[offset++]
+  }
+  const finish = () => {
+    if (!sawScan || components === undefined) fail('JPEG is missing a scan or supported frame')
+    if (offset !== data.length) fail('the first JPEG EOI must be the final two bytes')
+    return components
+  }
+  while (offset < data.length) {
+    const marker = markerAt()
+    if (marker === 0xd9) return finish()
+    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7)) fail('JPEG has an unexpected standalone marker')
+    if (offset + 2 > data.length) fail('JPEG segment is truncated')
+    const length = data.readUInt16BE(offset)
+    if (length < 2 || offset + length > data.length) fail('JPEG segment length is invalid')
+    if ([0xc0, 0xc1, 0xc2].includes(marker)) {
+      if (length < 8) fail('JPEG frame segment is invalid')
+      components = data[offset + 7]
+    }
+    offset += length
+    if (marker !== 0xda) continue
+    sawScan = true
+    while (offset < data.length) {
+      if (data[offset++] !== 0xff) continue
+      const markerStart = offset - 1
+      while (data[offset] === 0xff) offset += 1
+      if (offset >= data.length) fail('JPEG entropy stream is truncated')
+      const entropyMarker = data[offset++]
+      if (entropyMarker === 0x00 || (entropyMarker >= 0xd0 && entropyMarker <= 0xd7)) continue
+      if (entropyMarker === 0xd9) return finish()
+      // This is a real marker after the scan, not entropy. Re-enter the
+      // segment parser at its prefix so marker boundaries remain authoritative.
+      offset = markerStart
+      break
+    }
+  }
+  fail('JPEG is missing a terminal EOI marker')
+}
+
+const validateCovers = () => {
+  for (const cover of covers) {
+    regular644(cover)
+    const data = readFileSync(pathAtRoot(cover))
+    if (data.length < 100_000 || data.length > 500_000) fail(`${cover} is not a bounded JPEG`)
+    const components = parseJpeg(data)
+    let decoded
+    try { decoded = jpeg.decode(data, { useTArray: true, tolerantDecoding: false, maxResolutionInMP: 2 }) } catch { fail(`${cover} cannot be fully decoded`) }
+    if (decoded.width !== 1600 || decoded.height !== 900 || decoded.data.length !== 1600 * 900 * 4 || components !== 3) fail(`${cover} must decode as a 1600x900 three-component color JPEG`)
+    for (let index = 3; index < decoded.data.length; index += 4) if (decoded.data[index] !== 255) fail(`${cover} did not produce opaque RGB output`)
+  }
+}
+
+const validateReadme = (path, expected) => {
+  regular644(path)
+  const rendered = markdown.render(readFileSync(pathAtRoot(path), 'utf8'))
+  const document = new JSDOM(rendered, { runScripts: 'outside-only', resources: undefined }).window.document
+  const pictures = [...document.querySelectorAll('picture')]
+  if (pictures.length !== 1) fail(`${path} must render exactly one picture`)
+  const elements = [...pictures[0].children]
+  if (elements.map(element => element.localName).join(',') !== 'source,source,img') fail(`${path} picture must contain dark source, light source, then img`)
+  exactAttributes(elements[0], { media: '(prefers-color-scheme: dark)', srcset: expected.dark })
+  exactAttributes(elements[1], { media: '(prefers-color-scheme: light)', srcset: expected.light })
+  exactAttributes(elements[2], { alt: expected.alt, src: expected.light, width: '1600' })
+  const mentions = []
+  for (const element of document.querySelectorAll('[src], [srcset]')) for (const attribute of ['src', 'srcset']) {
+    const value = element.getAttribute(attribute)
+    if (value?.includes('avatar-cover-')) mentions.push({ element, attribute, value })
+  }
+  if (mentions.length !== 3 || new Set(mentions.map(mention => `${mention.attribute}:${mention.value}`)).size !== 3 || mentions.some(mention => !coverSet.has(mention.value))) fail(`${path} has duplicate, unexpected, or cross-language cover media`)
+}
+
+const changed = changedPaths()
+validateGenerator()
+validateCovers()
+validateReadme('README.md', { dark: covers[0], light: covers[1], alt: 'OneWorks Avatar — a growing gallery of geometric 3D avatars and pixel styles' })
+validateReadme('README.zh-Hans.md', { dark: covers[2], light: covers[3], alt: 'OneWorks Avatar——不断扩展的几何 3D 头像与像素风格' })
+console.log(`Validated README cover documentation assets across ${changed.length} changed path(s). JPEGs remain subject to normal PR visual review.`)