super resolution example

.github/workflows/deploy-preview.yml

@@ -0,0 +1,76 @@
+# =============================================================================
+# Deploy Preview
+# =============================================================================
+#
+# PURPOSE:
+#   Generates a preview build of the documentation site for every pull request
+#   that touches docs/ files. This lets reviewers see exactly how content
+#   changes will look on the live site before merging.
+#
+# HOW IT WORKS:
+#   1. Checks out the PR branch
+#   2. Installs Node.js dependencies (with npm cache for speed)
+#   3. Builds the Docusaurus site (English-only for faster builds)
+#   4. Uploads the built HTML as a GitHub Actions artifact (kept for 7 days)
+#   5. Posts a comment on the PR informing reviewers that the preview is ready
+#
+# HOW TO USE THE PREVIEW:
+#   - Go to the Actions tab on the PR
+#   - Download the "docs-preview-<PR number>" artifact
+#   - Extract and open index.html locally, or serve with `npx serve`
+#
+# NOTE: NODE_OPTIONS is set to 8GB to prevent out-of-memory errors during
+# the Docusaurus webpack build, which can be memory-intensive with many pages.
+#
+# TRIGGERS: Pull requests that change docs/** files.
+# =============================================================================
+
+name: Deploy Preview
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+
+jobs:
+  # ---- Build English-only site and upload as downloadable artifact ----
+  deploy-preview:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install dependencies
+        working-directory: website
+        run: npm ci
+
+      - name: Build (English only for speed)
+        working-directory: website
+        env:
+          NODE_OPTIONS: --max_old_space_size=8192
+        run: npm run build -- --locale en
+
+      - name: Deploy to preview
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-preview-${{ github.event.pull_request.number }}
+          path: website/build
+          retention-days: 7
+
+      - name: Comment PR with preview info
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '📄 **Docs Preview** built successfully!\n\nDownload the preview artifact from the Actions tab to review locally.\n\n_Built from commit ${{ github.event.pull_request.head.sha }}_'
+            });

.github/workflows/docs-build.yml

@@ -0,0 +1,108 @@
+# =============================================================================
+# Docs Build & Deploy
+# =============================================================================
+#
+# PURPOSE:
+#   Builds the full Docusaurus documentation site and deploys it to GitHub
+#   Pages when changes land on the main branch. For pull requests, it builds
+#   the site to verify nothing is broken, but does not deploy.
+#
+# HOW IT WORKS (3 jobs):
+#
+#   1. build       - Installs dependencies, runs `npm run build` to produce
+#                    the static HTML/CSS/JS output in website/build/. This is
+#                    a full production build (all locales, all pages, SSG).
+#                    On pushes to main, uploads the build as a GitHub Pages
+#                    artifact for deployment.
+#
+#   2. deploy      - Only runs on pushes to main (not PRs). Takes the build
+#                    artifact from the previous job and deploys it to the
+#                    GitHub Pages environment. Requires pages:write and
+#                    id-token:write permissions.
+#
+#   3. pr-comment  - Only runs on PRs. Posts a success comment on the PR
+#                    to confirm the docs build passed.
+#
+# IMPORTANT: This workflow uses NODE_OPTIONS=--max_old_space_size=8192 to
+# give Node.js enough memory for the webpack build. Without this, builds
+# with many pages can fail with heap out-of-memory errors.
+#
+# TRIGGERS: push/PR to main or docs branch when docs/** files change.
+# =============================================================================
+
+name: Docs Build
+
+on:
+  push:
+    branches: [main, docs]
+    paths:
+      - 'docs/**'
+  pull_request:
+    branches: [main, docs]
+    paths:
+      - 'docs/**'
+
+env:
+  NODE_OPTIONS: --max_old_space_size=8192
+
+jobs:
+  # ---- Job 1: Build the Docusaurus site ----
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload pages artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/build
+
+  # ---- Job 2: Deploy to GitHub Pages (main branch only) ----
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  # ---- Job 3: Post build-success comment on PRs ----
+  pr-comment:
+    if: github.event_name == 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Comment on PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '✅ Docs build succeeded!'
+            })

.github/workflows/docs-lint.yml

@@ -0,0 +1,139 @@
+# =============================================================================
+# Docs Lint
+# =============================================================================
+#
+# PURPOSE:
+#   Runs quality and consistency checks on all documentation content whenever
+#   docs/, examples/, or website/ files change. This workflow is the first line
+#   of defense against prose errors, broken links, spelling mistakes, and
+#   documentation drift.
+#
+# WHAT IT CHECKS (5 parallel jobs):
+#
+#   1. prose-lint      - Runs Vale (https://vale.sh) to enforce a writing style
+#                        guide. Catches passive voice, jargon, inconsistent
+#                        terminology, etc. Config lives in website/.vale.ini.
+#
+#   2. spell-check     - Runs cspell to catch typos and unknown words.
+#                        Custom dictionary is in website/.cspell.json.
+#
+#   3. sync-check      - Verifies that auto-generated docs pages (in docs/)
+#                        are in sync with their source README.md files (in
+#                        examples/). Fails if someone edited a generated .mdx
+#                        without updating the source, or vice versa.
+#                        Fix: run `node website/scripts/sync-examples.mjs`
+#
+#   4. mdx-only-check  - Ensures all documentation files use .mdx extension,
+#                        not plain .md. MDX is required for Docusaurus features
+#                        like component imports and Tabs.
+#
+#   5. link-check      - Builds the full Docusaurus site, then runs Lychee
+#                        link checker against the HTML output to catch broken
+#                        internal and external links. Uploads a report artifact
+#                        on failure for easy debugging.
+#
+# TRIGGERS: push/PR to docs/**, examples/**, website/**, or manual dispatch.
+# =============================================================================
+
+name: Docs Lint
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+      - 'examples/**'
+      - 'website/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'examples/**'
+      - 'website/**'
+  workflow_dispatch:
+
+jobs:
+  # ---- Job 1: Writing style enforcement ----
+  prose-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Vale
+        uses: errata-ai/vale-action@v2
+        with:
+          files: docs/
+          vale_flags: --config=website/.vale.ini
+
+  # ---- Job 2: Typo and spelling detection ----
+  spell-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Spell check
+        uses: streetsidesoftware/cspell-action@v6
+        with:
+          files: docs/**
+          config: website/.cspell.json
+
+  # ---- Job 3: Ensure examples/ README.md files match docs/ .mdx files ----
+  sync-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Verify examples/docs sync
+        run: node website/scripts/sync-examples.mjs --check
+
+  # ---- Job 4: Enforce .mdx extension for all docs files ----
+  mdx-only-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Ensure no .md files in docs/
+        run: |
+          MD_FILES=$(find docs/ -name '*.md' -not -name 'README.md' -not -path '*/node_modules/*' | head -20)
+          if [ -n "$MD_FILES" ]; then
+            echo "ERROR: Found .md files in docs/ that should be .mdx:"
+            echo "$MD_FILES"
+            exit 1
+          fi
+
+  # ---- Job 5: Build site and check all links (internal + external) ----
+  link-check:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        run: npm run build
+
+      - name: Lychee link checker
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: '--config .lychee.toml --base website/build --no-progress website/build'
+          fail: true
+          output: ./lychee-report.md
+
+      - name: Upload link check report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: link-check-report
+          path: ./lychee-report.md