[docs]: replace config generator with native cookbook

Address review: flip ignoreBuildErrors true->false. The code type-checks clean (verified with next build).

.buildkite/pipeline.yml

@@ -68,6 +68,17 @@ steps:
             limit: 2
       agents:
         queue: "default"
+    - label: ":vertical_traffic_light: Golden-Gate Tests"
+      if: build.env("TEST_SCOPE") == "direct" && build.env("TEST_TYPE") == "golden_gate"
+      command: "timeout 90m .buildkite/scripts/pr_test.sh"
+      retry:
+        automatic:
+          - exit_status: 128
+            limit: 3
+          - exit_status: -1
+            limit: 2
+      agents:
+        queue: "default"
     - label: ":microscope: Unit Tests"
       if: build.env("TEST_SCOPE") == "direct" && build.env("TEST_TYPE") == "unit_test"
       command: "timeout 90m .buildkite/scripts/pr_test.sh"
@@ -404,7 +415,7 @@ steps:
                 - "pyproject.toml"
                 - "docker/Dockerfile"
               config:
-                command: "timeout 15m .buildkite/scripts/pr_test.sh"
+                command: "timeout 25m .buildkite/scripts/pr_test.sh"
                 label: ":test_tube: Training Tests"
                 env:
                   - TEST_TYPE=training
@@ -415,7 +426,7 @@ steps:
                 - "pyproject.toml"
                 - "docker/Dockerfile"
               config:
-                command: "timeout 15m .buildkite/scripts/pr_test.sh"
+                command: "timeout 25m .buildkite/scripts/pr_test.sh"
                 label: ":test_tube: Distillation DMD Tests"
                 env:
                   - TEST_TYPE=distillation_dmd

.buildkite/scripts/pr_test.sh

@@ -187,6 +187,10 @@ case "$TEST_TYPE" in
         log "Running transformer tests..."
         MODAL_COMMAND="$MODAL_ENV HF_API_KEY=$HF_API_KEY python3 -m modal run $MODAL_TEST_FILE::run_transformer_tests"
         ;;
+    "golden_gate")
+        log "Running golden-gate tests..."
+        MODAL_COMMAND="$MODAL_ENV HF_API_KEY=$HF_API_KEY python3 -m modal run $MODAL_TEST_FILE::run_golden_gate_tests"
+        ;;
     "ssim")
         log "Running SSIM tests..."
         SSIM_BOOTSTRAP_ARGS=$(ssim_bootstrap_args)

.github/workflows/ci-slash-commands.yml

@@ -129,7 +129,7 @@ jobs:
           set -euo pipefail
           TEST_NAME=$(echo "$COMMENT" | grep -oP '(?<=/test\s)\S+' | head -1 || true)
 
-          VALID="encoder vae transformer kernel unit dreamverse ssim training lora-inference lora-training lora-extraction distillation self-forcing vsa vmoba performance api train-framework eval full fastcheck pre-commit"
+          VALID="encoder vae transformer kernel unit dreamverse ssim golden-gate training lora-inference lora-training lora-extraction distillation self-forcing vsa vmoba performance api train-framework eval full fastcheck pre-commit"
           if [ -z "$TEST_NAME" ] || ! echo "$VALID" | grep -qw "$TEST_NAME"; then
             echo "Unknown test: '$TEST_NAME'. Valid: $VALID"
             exit 1
@@ -138,7 +138,7 @@ jobs:
           declare -A MAP=(
             [encoder]=encoder [vae]=vae [transformer]=transformer
             [kernel]=kernel_tests [unit]=unit_test [dreamverse]=dreamverse_app
-            [ssim]=ssim [training]=training
+            [ssim]=ssim [golden-gate]=golden_gate [training]=training
             [lora-inference]=inference_lora [lora-training]=training_lora
             [lora-extraction]=lora_extraction
             [distillation]=distillation_dmd [self-forcing]=self_forcing

.github/workflows/infra-build-image.yml

@@ -13,16 +13,23 @@ on:
         required: false
         default: false
         type: boolean
-  # Auto-rebuild the CUDA images when their Dockerfile changes on main. The CUDA
-  # matrix is the only lane that builds from docker/Dockerfile, so a path-scoped
-  # push trigger is a sufficient change detector on its own -- no separate
-  # detect-changes/paths-filter job is needed now that there is a single
-  # in-scope Dockerfile. Dreamverse (apps/dreamverse/docker/Dockerfile) and the
-  # rocm Dockerfile stay manual-dispatch only.
+  # Auto-rebuild the CUDA images when a repository-controlled image input
+  # changes on main. This includes the trusted SM89 kernel artifact's source,
+  # metadata/key helper, ABI dependency metadata, and build orchestration.
+  # Dreamverse (apps/dreamverse/docker/Dockerfile) and the ROCm Dockerfile stay
+  # manual-dispatch only.
   push:
     branches: [main]
     paths:
+      - '.dockerignore'
+      - '.github/workflows/_template-build-image.yml'
+      - '.github/workflows/infra-build-image.yml'
+      - '.gitmodules'
       - 'docker/Dockerfile'
+      - 'docker/uv-excludes'
+      - 'fastvideo-kernel/**'
+      - 'fastvideo/tests/modal/kernel_build_cache.py'
+      - 'pyproject.toml'
 
 
 permissions:
@@ -50,7 +57,7 @@ jobs:
   # 2.8.3 comes from the architecture-specific prebuilt releases.
   build-cuda-images:
     # Runs on a manual dispatch when build_cuda_matrix is set, or automatically
-    # on a push that changed docker/Dockerfile (inputs are null on push). The
+    # on an in-scope main push (inputs are null on push). The
     # repository guard keeps fork syncs from auto-building; manual dispatch
     # still works in forks.
     if: ${{ (github.event_name == 'push' && github.repository == 'hao-ai-lab/FastVideo') || github.event.inputs.build_cuda_matrix == 'true' }}

.github/workflows/infra-docs.yml

@@ -6,6 +6,7 @@ on:
     paths:
       - 'docs/**'
       - 'examples/**'
+      - 'scripts/inference/**'
       - 'mkdocs.yml'
       - 'requirements-mkdocs.in'
       - 'requirements-mkdocs.txt'
@@ -16,6 +17,7 @@ on:
     paths:
       - 'docs/**'
       - 'examples/**'
+      - 'scripts/inference/**'
       - 'mkdocs.yml'
       - 'requirements-mkdocs.in'
       - 'requirements-mkdocs.txt'

.gitignore

@@ -6,7 +6,7 @@ results/
 wandb/
 *.ipynb
 *.jpg
-!examples/dataset/lingbotworld2/image.jpg
+!examples/datasets/lingbotworld2/image.jpg
 *.safetensors
 *.mp4
 *.png
@@ -75,6 +75,7 @@ docs/distillation/examples/
 *.pkl
 
 # Reference videos (negations must come after the catch-all on line below)
+!fastvideo/tests/nightly/reference_video_*.mp4
 
 # Static images
 !docs/assets/images/**/*.png

README.md

@@ -33,7 +33,7 @@ FastVideo has the following features:
   - [Sparse distillation](https://hao-ai-lab.github.io/blogs/fastvideo_post_training/) to achieve >50x denoising speedup
   - Scalable training with FSDP2, sequence parallelism, and selective activation checkpointing.
   - Causal distillation through Self-Forcing
-  - See this [page](https://hao-ai-lab.github.io/FastVideo/training/overview/) for full list of supported models and recipes.
+  - See this [page](https://hao-ai-lab.github.io/FastVideo/training/overview/) for the supported training workflows, and the [support matrix](https://hao-ai-lab.github.io/FastVideo/inference/support_matrix/) for supported models.
 - State-of-the-art performance optimizations for inference
   - Sequence Parallelism for distributed inference
   - Multiple state-of-the-art attention backends

apps/fastvideo_studio/e2e/create-job.spec.ts

@@ -13,10 +13,9 @@ test.describe('create inference job', () => {
   test('creates a T2V job and shows it in the queue', async ({ page }) => {
     await page.goto('/inference');
 
-    // The "Create Job" button reveals a workload menu on hover; wait for the
-    // T2V item to become visible before clicking so the CSS hover transition
-    // can't race the click.
-    await page.getByRole('button', { name: /create job/i }).hover();
+    // The trigger opens a real menu on click, so this path works for touch,
+    // mouse, and keyboard users.
+    await page.getByRole('button', { name: /create job/i }).click();
     const t2vItem = page.getByRole('menuitem', { name: /T2V/i });
     await expect(t2vItem).toBeVisible();
     await t2vItem.click();

apps/fastvideo_studio/e2e/gallery.spec.ts

@@ -4,7 +4,7 @@ import { API_BASE, skipWithoutMock } from './helpers';
 
 /**
  * Gallery page: the seeded completed inference job surfaces as a media tile
- * (an <article> wrapping a <video>) captioned with its prompt.
+ * with playback controls or an explicit media-error fallback.
  */
 test.describe('gallery', () => {
   skipWithoutMock();
@@ -30,12 +30,15 @@ test.describe('gallery', () => {
       page.getByRole('heading', { level: 1, name: 'Gallery' }),
     ).toBeVisible();
 
-    // The completed job renders as an <article> containing a <video> tile.
-    const tile = page
-      .locator('article')
-      .filter({ has: page.locator('video') });
-    await expect(tile.first()).toBeVisible();
+    const tile = page.locator('article').filter({ hasText: completed!.prompt });
+    await expect(tile).toBeVisible();
+    await expect(
+      tile.locator('video').or(tile.getByText('Preview unavailable')),
+    ).toBeVisible();
 
-    await expect(page.getByText(completed!.prompt)).toBeVisible();
+    const video = tile.locator('video');
+    if (await video.isVisible()) {
+      await expect(video).toHaveAttribute('controls', '');
+    }
   });
 });

apps/fastvideo_studio/e2e/shell.spec.ts

@@ -42,6 +42,74 @@ test.describe('app shell', () => {
       await expect(
         page.getByRole('heading', { level: 1, name: section.title }),
       ).toBeVisible();
+      await expect(page.getByRole('main')).toHaveCount(1);
     }
   });
+
+  test('keeps navigation and content usable at responsive breakpoints', async ({
+    page,
+  }) => {
+    for (const width of [320, 375, 414, 768]) {
+      await page.setViewportSize({ width, height: 800 });
+      await page.goto('/inference');
+
+      const main = page.getByRole('main');
+      await expect(main).toBeVisible();
+      await expect(
+        page.getByRole('button', { name: /Create Job/i }),
+      ).toBeVisible();
+
+      const initialBox = await main.boundingBox();
+      expect(initialBox?.x).toBe(width < 768 ? 0 : 220);
+      expect(initialBox?.width).toBe(width < 768 ? width : width - 220);
+
+      const navigation = page.getByRole('navigation', {
+        name: 'Primary navigation',
+      });
+      if (width < 768) {
+        await expect(
+          page.getByRole('button', { name: 'Open navigation' }),
+        ).toBeVisible();
+        await page.getByRole('button', { name: 'Open navigation' }).click();
+      }
+      await expect(navigation).toBeVisible();
+      await navigation.getByRole('link', { name: 'Datasets' }).click();
+
+      await expect(page).toHaveURL(/\/datasets$/);
+      expect(
+        await page.evaluate(
+          () => document.documentElement.scrollWidth <= window.innerWidth,
+        ),
+      ).toBe(true);
+    }
+  });
+
+  test('uses full-width detail drawers on mobile', async ({ page }) => {
+    await page.setViewportSize({ width: 320, height: 800 });
+    await page.goto('/inference');
+
+    await page
+      .locator('article button[aria-pressed="false"]')
+      .first()
+      .click();
+    const jobDrawer = page.getByRole('dialog', { name: 'Job details' });
+    await expect(jobDrawer).toBeVisible();
+    expect(await jobDrawer.boundingBox()).toMatchObject({ x: 0, width: 320 });
+    await jobDrawer.getByRole('button', { name: 'Close' }).click();
+
+    await page.goto('/datasets');
+    await page
+      .locator('article button[aria-pressed="false"]')
+      .first()
+      .click();
+
+    const datasetDrawer = page.getByRole('dialog', {
+      name: /dataset details$/,
+    });
+    await expect(datasetDrawer).toBeVisible();
+    expect(await datasetDrawer.boundingBox()).toMatchObject({
+      x: 0,
+      width: 320,
+    });
+  });
 });

apps/fastvideo_studio/package-lock.json

@@ -9,6 +9,7 @@
 			"version": "0.1.0",
 			"dependencies": {
 				"@radix-ui/react-dialog": "^1.1.0",
+				"@radix-ui/react-dropdown-menu": "^2.1.24",
 				"@radix-ui/react-label": "^2.1.8",
 				"@radix-ui/react-scroll-area": "^1.2.10",
 				"@radix-ui/react-select": "^2.2.6",
@@ -1936,6 +1937,183 @@
 				}
 			}
 		},
+		"node_modules/@radix-ui/react-dropdown-menu": {
+			"version": "2.1.24",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-dropdown-menu/-/react-dropdown-menu-2.1.24.tgz",
+			"integrity": "sha512-geq8l2rJkxvkXsT9RMgtUE3P8pITFpTsvYpbySi1IH4fZEABD/Gp85myayFgxk0ktljGMJnCbeFkyTusvSvv7g==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/primitive": "1.1.7",
+				"@radix-ui/react-compose-refs": "1.1.5",
+				"@radix-ui/react-context": "1.2.2",
+				"@radix-ui/react-id": "1.1.4",
+				"@radix-ui/react-menu": "2.1.24",
+				"@radix-ui/react-primitive": "2.1.10",
+				"@radix-ui/react-use-controllable-state": "1.2.6"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/primitive": {
+			"version": "1.1.7",
+			"resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.7.tgz",
+			"integrity": "sha512-rqWnm76nYT8HoNNqEjpgJ7Pw/DrBj5iBTrmEPo6HTX5+VJyBNOqTdv4g89G63HuR5g0AaENoAcH7Is5fF2kZ8Q==",
+			"license": "MIT"
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-compose-refs": {
+			"version": "1.1.5",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.5.tgz",
+			"integrity": "sha512-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-context": {
+			"version": "1.2.2",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.2.2.tgz",
+			"integrity": "sha512-RHCUGwKHDr0hDGg4X7ma4JG4/+12qxw8rkh5QKdDldlCvtja6nUx1Ef/8HVrJze81lEsgLQlqjzjGNHantgnQA==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-id": {
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.1.4.tgz",
+			"integrity": "sha512-TMQp2llA+RYn7JcjnrMnz7wN4pcVttPZnRZo52PLQsoLVKzNlVwUeHmfePgTgRluXFvlD3GD5g5MOVVTJCO0qA==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-primitive": {
+			"version": "2.1.10",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.10.tgz",
+			"integrity": "sha512-MucOnzh6hR5mid6VpkbglRAMYMjKLqRnGBbjXkzjK52fuQDd1qbkx78a5P40mkcnVXJdEVxm26E9OPAiUq7nBg==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-slot": "1.3.3"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-slot": {
+			"version": "1.3.3",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.3.3.tgz",
+			"integrity": "sha512-qx7oqnYbxnK9kYI9m317qmFmEgo6ywqWvbTogdj7cL9p3/yx4M48p7Rnw5z3H890cL/ow/EeWJsuTykeZVXP5Q==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-compose-refs": "1.1.5"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-use-controllable-state": {
+			"version": "1.2.6",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.6.tgz",
+			"integrity": "sha512-uEQJGT97ZA/TgP/Hydw47lHu+/vQj6z/0jA+WeTbK1o9Rx45GImjpD0tc3W5ad3D6XTSR6e1yEO0FvGq6WQfVQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/primitive": "1.1.7",
+				"@radix-ui/react-use-effect-event": "0.0.5",
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-use-effect-event": {
+			"version": "0.0.5",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-effect-event/-/react-use-effect-event-0.0.5.tgz",
+			"integrity": "sha512-7cshFL8HGS/7HEiHH+9kL9HBwp2sa9yX18Knwek6KYWmXwM7pegMgta2AXMQKI+rq3JnfSj9x8wYqFMTdG1Jgg==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-dropdown-menu/node_modules/@radix-ui/react-use-layout-effect": {
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.4.tgz",
+			"integrity": "sha512-K20DkRkUwDnxEYMBPcg3Y6voLkEy5p5QQmszZgLngKKiC7dzBR/aEuK3w1qlx2JWDUNH6FluahYdgR3BP+QbYw==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
 		"node_modules/@radix-ui/react-focus-guards": {
 			"version": "1.1.4",
 			"resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.1.4.tgz",
@@ -2017,6 +2195,494 @@
 				}
 			}
 		},
+		"node_modules/@radix-ui/react-menu": {
+			"version": "2.1.24",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-menu/-/react-menu-2.1.24.tgz",
+			"integrity": "sha512-uW7RVuU6Lp/ZtfeY4b3kL32zccgEWvPv1+cf17ubYzHa9cL8AHokmk36cG/XEiH/smbQvumnieXX9j/e9RqJWA==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/primitive": "1.1.7",
+				"@radix-ui/react-collection": "1.1.15",
+				"@radix-ui/react-compose-refs": "1.1.5",
+				"@radix-ui/react-context": "1.2.2",
+				"@radix-ui/react-direction": "1.1.4",
+				"@radix-ui/react-dismissable-layer": "1.1.19",
+				"@radix-ui/react-focus-guards": "1.1.6",
+				"@radix-ui/react-focus-scope": "1.1.16",
+				"@radix-ui/react-id": "1.1.4",
+				"@radix-ui/react-popper": "1.3.7",
+				"@radix-ui/react-portal": "1.1.17",
+				"@radix-ui/react-presence": "1.1.10",
+				"@radix-ui/react-primitive": "2.1.10",
+				"@radix-ui/react-roving-focus": "1.1.19",
+				"@radix-ui/react-slot": "1.3.3",
+				"@radix-ui/react-use-callback-ref": "1.1.4",
+				"aria-hidden": "^1.2.4",
+				"react-remove-scroll": "^2.7.2"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/primitive": {
+			"version": "1.1.7",
+			"resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.7.tgz",
+			"integrity": "sha512-rqWnm76nYT8HoNNqEjpgJ7Pw/DrBj5iBTrmEPo6HTX5+VJyBNOqTdv4g89G63HuR5g0AaENoAcH7Is5fF2kZ8Q==",
+			"license": "MIT"
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-arrow": {
+			"version": "1.1.15",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-arrow/-/react-arrow-1.1.15.tgz",
+			"integrity": "sha512-v4zggRcjadnI+ClKDuijlQEW4tw3NoaeHc/PwpKnLoLLKNUG4InLegkstooLcRIUWCs+8L22dGURCVuFfOKfnA==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-primitive": "2.1.10"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-collection": {
+			"version": "1.1.15",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-collection/-/react-collection-1.1.15.tgz",
+			"integrity": "sha512-9W+B9NPF0NaaPh/1NJd3+KqsnlLqU9H7T2rvww+fp+T/evVXdNAyYcnfRQZFOjkR1ajQp3yORlqnI8soawLvNA==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-compose-refs": "1.1.5",
+				"@radix-ui/react-context": "1.2.2",
+				"@radix-ui/react-primitive": "2.1.10",
+				"@radix-ui/react-slot": "1.3.3"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-compose-refs": {
+			"version": "1.1.5",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.5.tgz",
+			"integrity": "sha512-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-context": {
+			"version": "1.2.2",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.2.2.tgz",
+			"integrity": "sha512-RHCUGwKHDr0hDGg4X7ma4JG4/+12qxw8rkh5QKdDldlCvtja6nUx1Ef/8HVrJze81lEsgLQlqjzjGNHantgnQA==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-direction": {
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-direction/-/react-direction-1.1.4.tgz",
+			"integrity": "sha512-5pzg4FGQNpExhnhT2zlrP1wZFaYCd1K0nYWoFAdcYoYK868IEigqMX3B3f8yIoRlAhAeDWciLI6ZdCKHF9P4Vg==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-dismissable-layer": {
+			"version": "1.1.19",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.1.19.tgz",
+			"integrity": "sha512-8g4pfOL9HoKKLWGiypT+dphVqjFfmcXO5GBnhsG6zI+lxAx/8feQpr+1LSN8Re3hiZ+XkLNS4O9ztK11/LzQ6w==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/primitive": "1.1.7",
+				"@radix-ui/react-compose-refs": "1.1.5",
+				"@radix-ui/react-primitive": "2.1.10",
+				"@radix-ui/react-use-callback-ref": "1.1.4",
+				"@radix-ui/react-use-effect-event": "0.0.5"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-focus-guards": {
+			"version": "1.1.6",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.1.6.tgz",
+			"integrity": "sha512-RNOJjfZMTyBM6xYmV3IVGXkPjIhcBAuv48POevAXwrGJhkWZ9p1rFoIS1JFooPuT193AZmRsCPhpoVJxx6OPoQ==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-focus-scope": {
+			"version": "1.1.16",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.1.16.tgz",
+			"integrity": "sha512-wmRZ2WWLvmt6KHy2rNPOdPUjwq5xOHY02+m+udwJTn0aNIox/rkskAvJTyTLGhPK6KgrUjlJUJpgmx/+wFiFIQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-compose-refs": "1.1.5",
+				"@radix-ui/react-primitive": "2.1.10",
+				"@radix-ui/react-use-callback-ref": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-id": {
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.1.4.tgz",
+			"integrity": "sha512-TMQp2llA+RYn7JcjnrMnz7wN4pcVttPZnRZo52PLQsoLVKzNlVwUeHmfePgTgRluXFvlD3GD5g5MOVVTJCO0qA==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-popper": {
+			"version": "1.3.7",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.3.7.tgz",
+			"integrity": "sha512-UsJrrd7w4wuKKTdvd/DNERVlwSlUcyXzjhyDwBk+3aPOsCjOY6ZSbxuw8E6lZTjjfP8Cpd0J8VVkrYUWyGYXyg==",
+			"license": "MIT",
+			"dependencies": {
+				"@floating-ui/react-dom": "^2.0.0",
+				"@radix-ui/react-arrow": "1.1.15",
+				"@radix-ui/react-compose-refs": "1.1.5",
+				"@radix-ui/react-context": "1.2.2",
+				"@radix-ui/react-primitive": "2.1.10",
+				"@radix-ui/react-use-callback-ref": "1.1.4",
+				"@radix-ui/react-use-layout-effect": "1.1.4",
+				"@radix-ui/react-use-rect": "1.1.4",
+				"@radix-ui/react-use-size": "1.1.4",
+				"@radix-ui/rect": "1.1.3"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-portal": {
+			"version": "1.1.17",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.1.17.tgz",
+			"integrity": "sha512-vKQLcWypUnwZVvfV7UkGahH2g6ySe8M8R+zYBwPrv5byZ9QAW6cQVvNKo7GgmD+p8aYb6D9JBuvy8/WhOno2wQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-primitive": "2.1.10",
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-presence": {
+			"version": "1.1.10",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.10.tgz",
+			"integrity": "sha512-3wyzCQ6+ubRA+D4uv9m95JYLXxmOHp05qjrkjeA7uKHHtjpPggQzc6DAb0URl7j67oR0K2foO4ip27TiX037Bw==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-primitive": {
+			"version": "2.1.10",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.10.tgz",
+			"integrity": "sha512-MucOnzh6hR5mid6VpkbglRAMYMjKLqRnGBbjXkzjK52fuQDd1qbkx78a5P40mkcnVXJdEVxm26E9OPAiUq7nBg==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-slot": "1.3.3"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-roving-focus": {
+			"version": "1.1.19",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.1.19.tgz",
+			"integrity": "sha512-V9jI6hDjT7l3jsCQD9bLNvDLM3tH/gdbOTp7Tefp3hbbgCGQoK7tUvrWiRlcoBHIZ809ElXwNQwVo0B98LuTXQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/primitive": "1.1.7",
+				"@radix-ui/react-collection": "1.1.15",
+				"@radix-ui/react-compose-refs": "1.1.5",
+				"@radix-ui/react-context": "1.2.2",
+				"@radix-ui/react-direction": "1.1.4",
+				"@radix-ui/react-id": "1.1.4",
+				"@radix-ui/react-primitive": "2.1.10",
+				"@radix-ui/react-use-callback-ref": "1.1.4",
+				"@radix-ui/react-use-controllable-state": "1.2.6",
+				"@radix-ui/react-use-is-hydrated": "0.1.3",
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"@types/react-dom": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+				"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				},
+				"@types/react-dom": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-slot": {
+			"version": "1.3.3",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.3.3.tgz",
+			"integrity": "sha512-qx7oqnYbxnK9kYI9m317qmFmEgo6ywqWvbTogdj7cL9p3/yx4M48p7Rnw5z3H890cL/ow/EeWJsuTykeZVXP5Q==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-compose-refs": "1.1.5"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-use-callback-ref": {
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.4.tgz",
+			"integrity": "sha512-R6OUY2e2fA6Yn6s+VSx5KBV6Nx8LQEhu+cz7LCej18rQ1HLyg9PSC9jP/ZNx0o6FAIK9c0F1kHylzSxKsdlkrQ==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-use-controllable-state": {
+			"version": "1.2.6",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.6.tgz",
+			"integrity": "sha512-uEQJGT97ZA/TgP/Hydw47lHu+/vQj6z/0jA+WeTbK1o9Rx45GImjpD0tc3W5ad3D6XTSR6e1yEO0FvGq6WQfVQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/primitive": "1.1.7",
+				"@radix-ui/react-use-effect-event": "0.0.5",
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-use-effect-event": {
+			"version": "0.0.5",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-effect-event/-/react-use-effect-event-0.0.5.tgz",
+			"integrity": "sha512-7cshFL8HGS/7HEiHH+9kL9HBwp2sa9yX18Knwek6KYWmXwM7pegMgta2AXMQKI+rq3JnfSj9x8wYqFMTdG1Jgg==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-use-layout-effect": {
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.4.tgz",
+			"integrity": "sha512-K20DkRkUwDnxEYMBPcg3Y6voLkEy5p5QQmszZgLngKKiC7dzBR/aEuK3w1qlx2JWDUNH6FluahYdgR3BP+QbYw==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-use-rect": {
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-rect/-/react-use-rect-1.1.4.tgz",
+			"integrity": "sha512-cSOCh6JlkmfjLyNcLiu2nB4v+nm+dkZ+Q5KHWk/soo4U7ZLiEQFKHK9/YmtBHjfCEaU43IBKQOc4/uJmCaiCTQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/rect": "1.1.3"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/react-use-size": {
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-size/-/react-use-size-1.1.4.tgz",
+			"integrity": "sha512-D3anSY15EJoxrihpsXI6SMrmmonnQtR2ni7arO+Lfdg3O95b9hNXxONk8jA5C8ANdF/h5HMAxejgs8PWJ6rlhw==",
+			"license": "MIT",
+			"dependencies": {
+				"@radix-ui/react-use-layout-effect": "1.1.4"
+			},
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@radix-ui/react-menu/node_modules/@radix-ui/rect": {
+			"version": "1.1.3",
+			"resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.1.3.tgz",
+			"integrity": "sha512-JtyZR+mqgBibTo8xea3B6ZRmzZiM/YeVBtUkas6zMuXjAlfIFIW2FgqeM9eLyvEaYX66vr6DJMK+4U6LV0KhNw==",
+			"license": "MIT"
+		},
 		"node_modules/@radix-ui/react-popper": {
 			"version": "1.3.2",
 			"resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.3.2.tgz",
@@ -2410,6 +3076,21 @@
 				}
 			}
 		},
+		"node_modules/@radix-ui/react-use-is-hydrated": {
+			"version": "0.1.3",
+			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-is-hydrated/-/react-use-is-hydrated-0.1.3.tgz",
+			"integrity": "sha512-umO/aJ+82CpOnhDZUTbILCQf7kU/g0iv+oGs/Q8jw7IkhWBzaEP4sA268PhFAJTFetbwp3ICc6ktpI4TqtxcIw==",
+			"license": "MIT",
+			"peerDependencies": {
+				"@types/react": "*",
+				"react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+			},
+			"peerDependenciesMeta": {
+				"@types/react": {
+					"optional": true
+				}
+			}
+		},
 		"node_modules/@radix-ui/react-use-layout-effect": {
 			"version": "1.1.2",
 			"resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.2.tgz",

apps/fastvideo_studio/package.json

@@ -18,6 +18,7 @@
 	},
 	"dependencies": {
 		"@radix-ui/react-dialog": "^1.1.0",
+		"@radix-ui/react-dropdown-menu": "^2.1.24",
 		"@radix-ui/react-label": "^2.1.8",
 		"@radix-ui/react-scroll-area": "^1.2.10",
 		"@radix-ui/react-select": "^2.2.6",

apps/fastvideo_studio/src/app/datasets/page.test.tsx

@@ -0,0 +1,64 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { HeaderActionsProvider } from '@/components/shell/HeaderActionsContext';
+import { getDatasets, type Dataset } from '@/lib/api';
+
+import DatasetsPage from './page';
+
+vi.mock('@/lib/api', () => ({
+  getDatasets: vi.fn(),
+}));
+
+vi.mock('@/components/datasets/AddDatasetButton', () => ({
+  default: () => null,
+}));
+
+vi.mock('@/components/datasets/CreateDatasetModal', () => ({
+  default: () => null,
+}));
+
+vi.mock('@/components/datasets/DatasetCard', () => ({
+  default: ({ dataset }: { dataset: Dataset }) => <div>{dataset.name}</div>,
+}));
+
+function renderPage() {
+  return render(
+    <HeaderActionsProvider>
+      <DatasetsPage />
+    </HeaderActionsProvider>,
+  );
+}
+
+describe('DatasetsPage', () => {
+  it('shows loading content before the initial request settles', async () => {
+    let resolveDatasets: (datasets: Dataset[]) => void = () => {};
+    vi.mocked(getDatasets).mockReturnValue(
+      new Promise<Dataset[]>((resolve) => {
+        resolveDatasets = resolve;
+      }),
+    );
+
+    renderPage();
+    expect(screen.getByLabelText('Loading datasets')).toBeInTheDocument();
+    expect(screen.queryByText('No datasets yet.')).not.toBeInTheDocument();
+
+    act(() => resolveDatasets([]));
+    expect(await screen.findByText('No datasets yet.')).toBeInTheDocument();
+  });
+
+  it('shows API failures separately from an empty list and retries', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.mocked(getDatasets).mockRejectedValueOnce(new Error('network down'));
+
+    renderPage();
+    expect(
+      await screen.findByText(/Could not load datasets from the Studio API/),
+    ).toBeInTheDocument();
+    expect(screen.queryByText('No datasets yet.')).not.toBeInTheDocument();
+
+    vi.mocked(getDatasets).mockResolvedValueOnce([]);
+    fireEvent.click(screen.getByRole('button', { name: 'Try Again' }));
+    expect(await screen.findByText('No datasets yet.')).toBeInTheDocument();
+  });
+});

apps/fastvideo_studio/src/app/datasets/page.tsx

@@ -1,12 +1,14 @@
 'use client';
 
 import * as React from 'react';
+import { AlertTriangle } from 'lucide-react';
 
 import AddDatasetButton from '@/components/datasets/AddDatasetButton';
 import CreateDatasetModal from '@/components/datasets/CreateDatasetModal';
 import DatasetCard from '@/components/datasets/DatasetCard';
 import { HeaderActions } from '@/components/shell/HeaderActionsContext';
 import { Card } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
 import { useStore } from '@/hooks/useStore';
 import { getDatasets } from '@/lib/api';
 import type { Dataset } from '@/lib/api';
@@ -21,18 +23,28 @@ import {
 
 export default function DatasetsPage() {
   const [datasets, setDatasets] = React.useState<Dataset[]>([]);
+  const [isInitialLoading, setIsInitialLoading] = React.useState(true);
   const [error, setError] = React.useState<string | null>(null);
   const { open } = useStore(createDatasetModalStore);
+  const fetchSequence = React.useRef(0);
 
   const fetchDatasets = React.useCallback(async () => {
+    const sequence = ++fetchSequence.current;
     try {
-      setDatasets(await getDatasets());
-      setError(null);
+      const next = await getDatasets();
+      if (sequence === fetchSequence.current) {
+        setDatasets(next);
+        setError(null);
+      }
     } catch (err) {
       console.error('Failed to fetch datasets:', err);
-      // Distinguish an API outage from a genuinely empty list, so the user
-      // isn't told they have no datasets when the server is unreachable.
-      setError(err instanceof Error ? err.message : 'Failed to load datasets');
+      if (sequence === fetchSequence.current) {
+        setError(
+          'Could not load datasets from the Studio API. Check the server and try again.',
+        );
+      }
+    } finally {
+      if (sequence === fetchSequence.current) setIsInitialLoading(false);
     }
   }, []);
 
@@ -50,28 +62,67 @@ export default function DatasetsPage() {
       <HeaderActions>
         <AddDatasetButton />
       </HeaderActions>
-      <main className="mx-auto flex w-full max-w-[850px] flex-col gap-6 px-4 pb-12">
+      <div className="mx-auto flex w-full max-w-[850px] flex-col gap-6 px-4 pb-12">
         <Card className="p-6">
-          <div>
-            {error ? (
-              <p className="py-8 text-center text-destructive">{error}</p>
-            ) : datasets.length === 0 ? (
-              <p className="py-8 text-center text-muted-foreground">
-                No datasets yet.
-              </p>
-            ) : (
-              datasets.map((ds) => (
-                <DatasetCard
-                  key={ds.id}
-                  dataset={ds}
-                  onUpdated={fetchDatasets}
-                  onSelect={() => handleSelectDataset(ds)}
+          <div aria-busy={isInitialLoading}>
+            {isInitialLoading ? (
+              <div
+                aria-label="Loading datasets"
+                className="flex flex-col gap-3 py-2"
+              >
+                {[0, 1, 2].map((item) => (
+                  <div
+                    key={item}
+                    className="h-24 animate-pulse rounded-lg border border-border bg-muted/50"
+                  />
+                ))}
+              </div>
+            ) : error && datasets.length === 0 ? (
+              <div
+                role="alert"
+                className="flex flex-col items-center gap-3 py-8 text-center"
+              >
+                <AlertTriangle
+                  className="size-6 text-destructive"
+                  aria-hidden
                 />
-              ))
+                <p className="max-w-md text-sm text-muted-foreground">
+                  {error}
+                </p>
+                <Button type="button" variant="outline" onClick={fetchDatasets}>
+                  Try Again
+                </Button>
+              </div>
+            ) : (
+              <>
+                {error && (
+                  <p
+                    role="status"
+                    className="mb-3 rounded-lg border border-amber-500/50 bg-amber-500/10 px-3 py-2 text-sm text-foreground"
+                  >
+                    Dataset updates are temporarily unavailable. Showing the
+                    most recent results.
+                  </p>
+                )}
+                {datasets.length === 0 ? (
+                  <p className="py-8 text-center text-muted-foreground">
+                    No datasets yet.
+                  </p>
+                ) : (
+                  datasets.map((ds) => (
+                    <DatasetCard
+                      key={ds.id}
+                      dataset={ds}
+                      onUpdated={fetchDatasets}
+                      onSelect={() => handleSelectDataset(ds)}
+                    />
+                  ))
+                )}
+              </>
             )}
           </div>
         </Card>
-      </main>
+      </div>
       <CreateDatasetModal
         isOpen={open}
         onClose={() => setCreateDatasetModalOpen(false)}

apps/fastvideo_studio/src/app/gallery/page.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 
 import GalleryPage from './page';
@@ -43,6 +43,22 @@ describe('GalleryPage', () => {
     expect(getJobsList).toHaveBeenCalledWith('inference');
   });
 
+  it('provides video controls and a visible fallback when media fails', async () => {
+    vi.mocked(getJobsList).mockResolvedValue([makeJob()]);
+    renderGallery();
+
+    const video = await screen.findByLabelText(
+      'Generated video: a cat surfing a wave',
+    );
+    expect(video).toHaveAttribute('controls');
+
+    fireEvent.error(video);
+    expect(screen.getByText('Preview unavailable')).toBeInTheDocument();
+    expect(
+      screen.getByText('The generated file could not be loaded.'),
+    ).toBeInTheDocument();
+  });
+
   it('shows the empty state when no completed videos exist', async () => {
     vi.mocked(getJobsList).mockResolvedValue([
       makeJob({ status: 'running', output_path: null }),

apps/fastvideo_studio/src/app/gallery/page.tsx

@@ -1,8 +1,9 @@
 'use client';
 
-import { Loader2 } from 'lucide-react';
+import { AlertTriangle, ImageOff, Loader2 } from 'lucide-react';
 import { useEffect, useState } from 'react';
 
+import { Button } from '@/components/ui/button';
 import { Card } from '@/components/ui/card';
 import { getJobVideoUrl, getJobsList } from '@/lib/api';
 import type { Job } from '@/lib/types';
@@ -11,11 +12,61 @@ function isImage(job: Job): boolean {
   return job.output_path?.toLowerCase().endsWith('.png') ?? false;
 }
 
+function GalleryMedia({ job }: { job: Job }) {
+  const [failed, setFailed] = useState(false);
+
+  if (failed) {
+    return (
+      <div
+        role="status"
+        className="flex h-full flex-col items-center justify-center gap-2 px-4 text-center text-muted-foreground"
+      >
+        <ImageOff className="size-7" aria-hidden />
+        <span className="text-sm font-medium">Preview unavailable</span>
+        <span className="text-xs">
+          The generated file could not be loaded.
+        </span>
+      </div>
+    );
+  }
+
+  if (isImage(job)) {
+    return (
+      // eslint-disable-next-line @next/next/no-img-element
+      <img
+        src={getJobVideoUrl(job.id)}
+        alt={job.prompt}
+        className="block h-full w-full object-contain"
+        loading="lazy"
+        onError={() => setFailed(true)}
+      />
+    );
+  }
+
+  return (
+    <video
+      src={getJobVideoUrl(job.id)}
+      aria-label={
+        job.prompt ? `Generated video: ${job.prompt}` : 'Generated video'
+      }
+      className="block h-full w-full object-contain"
+      controls
+      muted
+      loop
+      playsInline
+      preload="metadata"
+      onError={() => setFailed(true)}
+    />
+  );
+}
+
 export default function GalleryPage() {
   const [jobs, setJobs] = useState<Job[]>([]);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
 
+  const [reloadKey, setReloadKey] = useState(0);
+
   useEffect(() => {
     let cancelled = false;
     async function load() {
@@ -40,7 +91,13 @@ export default function GalleryPage() {
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [reloadKey]);
+
+  function retry() {
+    setError(null);
+    setIsLoading(true);
+    setReloadKey((k) => k + 1);
+  }
 
   const galleryJobs = jobs.filter(
     (j) =>
@@ -64,7 +121,16 @@ export default function GalleryPage() {
             <span>Loading gallery…</span>
           </div>
         ) : error ? (
-          <p className="py-8 text-destructive">{error}</p>
+          <div
+            role="alert"
+            className="flex flex-col items-center gap-3 py-8 text-center"
+          >
+            <AlertTriangle className="size-6 text-destructive" aria-hidden />
+            <p className="max-w-md text-sm text-muted-foreground">{error}</p>
+            <Button type="button" variant="outline" onClick={retry}>
+              Try Again
+            </Button>
+          </div>
         ) : galleryJobs.length === 0 ? (
           <p className="py-8 text-center text-muted-foreground">
             No completed videos yet
@@ -77,24 +143,7 @@ export default function GalleryPage() {
                 className="flex flex-col overflow-hidden rounded-lg border border-border bg-background"
               >
                 <div className="relative aspect-video overflow-hidden bg-muted">
-                  {isImage(job) ? (
-                    // eslint-disable-next-line @next/next/no-img-element
-                    <img
-                      src={getJobVideoUrl(job.id)}
-                      alt={job.prompt}
-                      className="block h-full w-full object-contain"
-                      loading="lazy"
-                    />
-                  ) : (
-                    <video
-                      src={getJobVideoUrl(job.id)}
-                      className="block h-full w-full object-contain"
-                      muted
-                      loop
-                      playsInline
-                      preload="metadata"
-                    />
-                  )}
+                  <GalleryMedia job={job} />
                 </div>
                 <p
                   className="line-clamp-3 border-t border-border px-4 py-3 text-sm text-muted-foreground"

apps/fastvideo_studio/src/app/globals.css

@@ -41,7 +41,7 @@
 
 	--border: #e2e8f0;
 	--input: #cbd5e1;
-	--ring: #94a3b8;
+	--ring: #1d4ed8;
 
 	--radius: 0.5rem;
 }
@@ -77,7 +77,7 @@
 
 	--border: #334155;
 	--input: #334155;
-	--ring: #cbd5e1;
+	--ring: #7dd3fc;
 }
 
 @theme inline {
@@ -125,6 +125,7 @@
 html,
 body {
 	min-height: 100%;
+	overflow-x: clip;
 }
 
 html {
@@ -163,6 +164,22 @@ a {
 	color: inherit;
 }
 
+:where(
+	a,
+	button,
+	input,
+	textarea,
+	select,
+	summary,
+	[role="button"],
+	[role="menuitem"],
+	[role="slider"],
+	[tabindex]
+):focus-visible {
+	outline: 3px solid var(--ring) !important;
+	outline-offset: 2px !important;
+}
+
 summary {
 	list-style: none;
 }

apps/fastvideo_studio/src/app/globals.test.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const css = readFileSync(join(process.cwd(), 'src/app/globals.css'), 'utf8');
+
+function token(block: string, name: string): string {
+  const match = block.match(new RegExp(`--${name}:\\s*(#[0-9a-fA-F]{6})`));
+  if (!match) throw new Error(`Missing --${name} token`);
+  return match[1];
+}
+
+function luminance(hex: string): number {
+  const channels = hex
+    .slice(1)
+    .match(/.{2}/g)!
+    .map((channel) => parseInt(channel, 16) / 255)
+    .map((channel) =>
+      channel <= 0.04045
+        ? channel / 12.92
+        : ((channel + 0.055) / 1.055) ** 2.4,
+    );
+  return (
+    0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2]
+  );
+}
+
+function contrast(first: string, second: string): number {
+  const firstLuminance = luminance(first);
+  const secondLuminance = luminance(second);
+  return (
+    (Math.max(firstLuminance, secondLuminance) + 0.05) /
+    (Math.min(firstLuminance, secondLuminance) + 0.05)
+  );
+}
+
+describe('global focus styles', () => {
+  it('keeps focus tokens above 3:1 against both page themes', () => {
+    const light = css.match(/:root\s*{([\s\S]*?)\n}/)?.[1] ?? '';
+    const dark = css.match(/\.dark\s*{([\s\S]*?)\n}/)?.[1] ?? '';
+
+    expect(contrast(token(light, 'ring'), token(light, 'background'))).toBeGreaterThanOrEqual(
+      3,
+    );
+    expect(contrast(token(dark, 'ring'), token(dark, 'background'))).toBeGreaterThanOrEqual(
+      3,
+    );
+  });
+
+  it('applies a non-animated three-pixel outline to focus-visible controls', () => {
+    expect(css).toContain('):focus-visible {');
+    expect(css).toContain('outline: 3px solid var(--ring) !important;');
+    expect(css).toContain('outline-offset: 2px !important;');
+  });
+});

apps/fastvideo_studio/src/app/gpus/page.tsx

@@ -4,8 +4,8 @@ import GpuGrid from '@/components/system/GpuGrid';
 
 export default function GpusPage() {
   return (
-    <main className="mx-auto flex w-full max-w-[1100px] flex-col gap-6 px-4 pb-12 pt-6">
+    <div className="mx-auto flex w-full max-w-[1100px] flex-col gap-6 px-4 pb-12 pt-6">
       <GpuGrid />
-    </main>
+    </div>
   );
 }

apps/fastvideo_studio/src/app/settings/page.test.tsx

@@ -52,6 +52,20 @@ describe('Settings page', () => {
     expect(updateOption).toHaveBeenCalledWith('numFrames', expect.any(Number));
   });
 
+  it('gives every slider an accessible name', () => {
+    renderPage();
+
+    const sliders = screen.getAllByRole('slider');
+    expect(sliders).toHaveLength(11);
+    for (const slider of sliders) {
+      expect(slider).toHaveAccessibleName();
+    }
+    expect(screen.getByRole('slider', { name: 'Frames' })).toBeInTheDocument();
+    expect(
+      screen.getByRole('slider', { name: 'Guidance Scale' }),
+    ).toBeInTheDocument();
+  });
+
   it('calls resetToDefaults when Reset to Defaults is clicked', () => {
     renderPage();
     fireEvent.click(screen.getByRole('button', { name: 'Reset to Defaults' }));

apps/fastvideo_studio/src/components/datasets/DatasetCard.test.tsx

@@ -25,6 +25,16 @@ beforeEach(() => {
 });
 
 describe('DatasetCard', () => {
+  it('keeps selection and delete buttons as semantic siblings', () => {
+    render(<DatasetCard dataset={dataset} onUpdated={() => {}} />);
+
+    const selectButton = screen.getByRole('button', { pressed: false });
+    const deleteButton = screen.getByRole('button', { name: 'Delete' });
+
+    expect(selectButton).toHaveTextContent('My Dataset');
+    expect(selectButton).not.toContainElement(deleteButton);
+  });
+
   it('renders the name, file count and human-readable size', () => {
     render(<DatasetCard dataset={dataset} onUpdated={() => {}} />);
     expect(screen.getByText('My Dataset')).toBeInTheDocument();
@@ -71,7 +81,7 @@ describe('DatasetCard', () => {
     expect(onSelect).not.toHaveBeenCalled();
   });
 
-  it('selects on keyboard activation of the card body but not of the Delete button', () => {
+  it('keeps the selection and delete actions separate', () => {
     const onSelect = vi.fn();
     render(
       <DatasetCard dataset={dataset} onUpdated={() => {}} onSelect={onSelect} />,
@@ -83,8 +93,12 @@ describe('DatasetCard', () => {
     });
     expect(onSelect).not.toHaveBeenCalled();
 
-    // Activating the card body itself does select.
-    fireEvent.keyDown(screen.getByText('My Dataset'), { key: 'Enter' });
+    // Activating the dedicated selection button selects the dataset.
+    fireEvent.click(
+      screen.getByRole('button', {
+        name: /My Dataset.*3 files.*2.0 KB/,
+      }),
+    );
     expect(onSelect).toHaveBeenCalledTimes(1);
   });
 

apps/fastvideo_studio/src/components/datasets/DatasetCard.tsx

@@ -55,43 +55,33 @@ export default function DatasetCard({
     }
   }
 
-  function handleKeyDown(e: React.KeyboardEvent) {
-    if ((e.target as HTMLElement).closest('button')) return;
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      onSelect();
-    }
-  }
-
   return (
-    <div
+    <article
       className={cn(
-        'mb-3 flex cursor-pointer flex-col gap-[0.6rem] rounded-lg border border-border bg-background px-[1.15rem] py-4',
+        'mb-3 flex items-start gap-3 rounded-lg border border-border bg-background px-[1.15rem] py-4',
         isSelected && 'border-accent-blue bg-accent-blue/5',
       )}
-      onClick={(e) => {
-        if ((e.target as HTMLElement).closest('button')) return;
-        onSelect();
-      }}
-      onKeyDown={handleKeyDown}
-      role="button"
-      tabIndex={0}
     >
-      <div className="flex flex-wrap items-center justify-between gap-2">
+      <button
+        type="button"
+        aria-pressed={isSelected}
+        onClick={onSelect}
+        className="flex min-w-0 flex-1 cursor-pointer flex-col gap-[0.6rem] rounded-md text-left"
+      >
         <span className="text-[0.95rem] font-semibold">{dataset.name}</span>
-        <Button
-          type="button"
-          variant="destructive"
-          size="sm"
-          onClick={handleDelete}
-          disabled={isLoading}
-        >
-          Delete
-        </Button>
-      </div>
-      <div className="text-sm text-muted-foreground">
-        {fileCount} {fileCount === 1 ? 'file' : 'files'} · {sizeLabel}
-      </div>
-    </div>
+        <span className="text-sm text-muted-foreground">
+          {fileCount} {fileCount === 1 ? 'file' : 'files'} · {sizeLabel}
+        </span>
+      </button>
+      <Button
+        type="button"
+        variant="destructive"
+        size="sm"
+        onClick={handleDelete}
+        disabled={isLoading}
+      >
+        Delete
+      </Button>
+    </article>
   );
 }

apps/fastvideo_studio/src/components/datasets/DatasetSidebar.test.tsx

@@ -6,6 +6,9 @@ import * as api from '@/lib/api';
 import type { Dataset } from '@/lib/api';
 
 vi.mock('@/lib/api');
+vi.mock('sonner', () => ({
+  toast: { error: vi.fn() },
+}));
 
 const mockedApi = vi.mocked(api);
 
@@ -27,6 +30,27 @@ beforeEach(() => {
 });
 
 describe('DatasetSidebar', () => {
+  it('fills the mobile viewport without reserving main-content width', async () => {
+    const onWidthChange = vi.fn();
+
+    render(
+      <DatasetSidebar
+        dataset={dataset}
+        isMobile
+        onClose={() => {}}
+        onWidthChange={onWidthChange}
+      />,
+    );
+
+    const drawer = screen.getByRole('dialog', {
+      name: 'My Dataset dataset details',
+    });
+    expect(drawer).toHaveStyle({ width: '100%', maxWidth: 'none' });
+    expect(drawer).toHaveAttribute('aria-modal', 'true');
+    expect(drawer).toHaveFocus();
+    expect(onWidthChange).toHaveBeenCalledWith(0);
+  });
+
   it('lists dataset files after loading', async () => {
     render(<DatasetSidebar dataset={dataset} onClose={() => {}} />);
 
@@ -43,6 +67,16 @@ describe('DatasetSidebar', () => {
     expect(mockedApi.getDatasetMediaUrl).toHaveBeenCalledWith('ds-1', 'b.mp4');
   });
 
+  it('shows a fallback when a dataset preview cannot load', async () => {
+    render(<DatasetSidebar dataset={dataset} onClose={() => {}} />);
+
+    const preview = await screen.findByLabelText('Preview of a.mp4');
+    fireEvent.error(preview);
+
+    expect(screen.getByText('Preview unavailable')).toBeInTheDocument();
+    expect(screen.queryByLabelText('Preview of a.mp4')).not.toBeInTheDocument();
+  });
+
   it('debounces caption save by 500ms', async () => {
     render(<DatasetSidebar dataset={dataset} onClose={() => {}} />);
     const textarea = await screen.findByDisplayValue('cap a');
@@ -99,6 +133,39 @@ describe('DatasetSidebar', () => {
     }
   });
 
+  it('shows a failed save and lets the user retry it', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    mockedApi.updateDatasetCaption
+      .mockRejectedValueOnce(new Error('network down'))
+      .mockResolvedValueOnce(undefined);
+    render(<DatasetSidebar dataset={dataset} onClose={() => {}} />);
+    const textarea = await screen.findByDisplayValue('cap a');
+
+    vi.useFakeTimers();
+    try {
+      fireEvent.change(textarea, { target: { value: 'needs retry' } });
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(500);
+      });
+
+      expect(screen.getByText(/Not saved/)).toBeInTheDocument();
+      fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
+      await act(async () => {
+        await Promise.resolve();
+      });
+
+      expect(mockedApi.updateDatasetCaption).toHaveBeenCalledTimes(2);
+      expect(mockedApi.updateDatasetCaption).toHaveBeenLastCalledWith(
+        'ds-1',
+        'a.mp4',
+        'needs retry',
+      );
+      expect(screen.getByText('Saved')).toBeInTheDocument();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('debounces per file: editing another caption does not cancel a pending save', async () => {
     render(<DatasetSidebar dataset={dataset} onClose={() => {}} />);
     await screen.findByDisplayValue('cap a');

apps/fastvideo_studio/src/components/datasets/DatasetSidebar.tsx

@@ -1,7 +1,8 @@
 'use client';
 
 import * as React from 'react';
-import { X } from 'lucide-react';
+import { ImageOff, X } from 'lucide-react';
+import { toast } from 'sonner';
 
 import DownloadCaptions from '@/components/datasets/DownloadCaptions';
 import { Textarea } from '@/components/ui/textarea';
@@ -13,12 +14,14 @@ import {
   type Dataset,
 } from '@/lib/api';
 import { cn } from '@/lib/utils';
+import { useDrawerFocus } from '@/hooks/useDrawerFocus';
 
 const SIDEBAR_MIN_WIDTH = 320;
 const SIDEBAR_MAX_WIDTH = 900;
 const INITIAL_PAGE_SIZE = 24;
 const PAGE_SIZE = 24;
 const SCROLL_THRESHOLD = 200;
+type CaptionSaveState = 'idle' | 'saving' | 'saved' | 'error';
 
 // Memoized so a caption keystroke re-renders only the edited card, not every
 // visible <video> in the grid (visibleCount grows unbounded with scrolling).
@@ -27,54 +30,101 @@ const DatasetFileCard = React.memo(function DatasetFileCard({
   mediaUrl,
   caption,
   thumbLoaded,
+  saveState,
   onCaptionChange,
+  onCaptionRetry,
   onThumbLoaded,
 }: {
   fileName: string;
   mediaUrl: string;
   caption: string;
   thumbLoaded: boolean;
+  saveState: CaptionSaveState;
   onCaptionChange: (fileName: string, value: string) => void;
+  onCaptionRetry: (fileName: string, value: string) => void;
   onThumbLoaded: (fileName: string) => void;
 }) {
+  const [mediaFailed, setMediaFailed] = React.useState(false);
+
+  React.useEffect(() => {
+    setMediaFailed(false);
+  }, [mediaUrl]);
+
   return (
     <div className="relative flex flex-col overflow-hidden rounded-lg border border-border bg-background">
-      {!thumbLoaded && (
+      {!thumbLoaded && !mediaFailed && (
         <div className="pointer-events-none absolute inset-0 flex items-center justify-center bg-background/70">
           <div className="h-6 w-6 animate-spin rounded-full border-2 border-muted-foreground/40 border-t-accent-blue" />
         </div>
       )}
-      {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
-      <video
-        src={mediaUrl}
-        className="aspect-video w-full bg-border object-cover"
-        muted
-        autoPlay
-        loop
-        playsInline
-        onLoadedData={() => onThumbLoaded(fileName)}
-        onError={() => onThumbLoaded(fileName)}
-      />
+      {mediaFailed ? (
+        <div
+          role="status"
+          className="flex aspect-video w-full flex-col items-center justify-center gap-1 bg-muted px-2 text-center text-muted-foreground"
+        >
+          <ImageOff className="size-5" aria-hidden />
+          <span className="text-xs">Preview unavailable</span>
+        </div>
+      ) : (
+        // eslint-disable-next-line jsx-a11y/media-has-caption
+        <video
+          src={mediaUrl}
+          aria-label={`Preview of ${fileName}`}
+          className="aspect-video w-full bg-border object-cover"
+          muted
+          autoPlay
+          loop
+          playsInline
+          onLoadedData={() => onThumbLoaded(fileName)}
+          onError={() => {
+            setMediaFailed(true);
+            onThumbLoaded(fileName);
+          }}
+        />
+      )}
       <Textarea
+        aria-label={`Caption for ${fileName}`}
         value={caption}
         onChange={(e) => onCaptionChange(fileName, e.target.value)}
         placeholder="Caption"
         rows={2}
         className="min-h-[2.5rem] resize-y rounded-none border-0 bg-transparent p-1.5 text-xs shadow-none focus-visible:border-transparent focus-visible:ring-0"
       />
+      <div
+        aria-live="polite"
+        className="flex min-h-6 items-center px-1.5 pb-1 text-[0.7rem] text-muted-foreground"
+      >
+        {saveState === 'saving' && <span>Saving…</span>}
+        {saveState === 'saved' && <span>Saved</span>}
+        {saveState === 'error' && (
+          <span role="alert" className="text-destructive">
+            Not saved.{' '}
+            <button
+              type="button"
+              onClick={() => onCaptionRetry(fileName, caption)}
+              className="inline-flex min-h-11 items-center font-medium underline underline-offset-2"
+            >
+              Retry
+            </button>
+          </span>
+        )}
+      </div>
     </div>
   );
 });
 
 export default function DatasetSidebar({
   dataset,
+  isMobile = false,
   onClose,
   onWidthChange,
 }: {
   dataset: Dataset;
+  isMobile?: boolean;
   onClose: () => void;
   onWidthChange?: (w: number) => void;
 }) {
+  const drawerRef = useDrawerFocus<HTMLElement>(isMobile);
   const [width, setWidth] = React.useState(400);
   const [isDragging, setIsDragging] = React.useState(false);
   const [fileNames, setFileNames] = React.useState<string[]>([]);
@@ -84,17 +134,21 @@ export default function DatasetSidebar({
   const [thumbLoaded, setThumbLoaded] = React.useState<
     Record<string, boolean>
   >({});
+  const [captionSaveStates, setCaptionSaveStates] = React.useState<
+    Record<string, CaptionSaveState>
+  >({});
 
   // Pending debounced caption saves, keyed per file so editing one caption
   // can't cancel another file's pending save.
   const pendingSaves = React.useRef(
     new Map<string, { timer: ReturnType<typeof setTimeout>; save: () => void }>(),
   );
+  const captionVersions = React.useRef(new Map<string, number>());
   const scrollRef = React.useRef<HTMLDivElement>(null);
 
   React.useEffect(() => {
-    onWidthChange?.(width);
-  }, [width, onWidthChange]);
+    onWidthChange?.(isMobile ? 0 : width);
+  }, [isMobile, width, onWidthChange]);
 
   React.useEffect(() => {
     let cancelled = false;
@@ -106,6 +160,8 @@ export default function DatasetSidebar({
         setCaptions(data.captions);
         setVisibleCount(INITIAL_PAGE_SIZE);
         setThumbLoaded({});
+        setCaptionSaveStates({});
+        captionVersions.current.clear();
       })
       .catch((err) => console.error('Failed to load dataset files:', err))
       .finally(() => {
@@ -138,23 +194,51 @@ export default function DatasetSidebar({
   });
 
   const datasetId = dataset.id;
+  const persistCaption = React.useCallback(
+    (fileName: string, value: string, version: number) => {
+      setCaptionSaveStates((prev) => ({ ...prev, [fileName]: 'saving' }));
+      void updateDatasetCaption(datasetId, fileName, value)
+        .then(() => {
+          if (captionVersions.current.get(fileName) !== version) return;
+          setCaptionSaveStates((prev) => ({ ...prev, [fileName]: 'saved' }));
+        })
+        .catch((error) => {
+          if (captionVersions.current.get(fileName) !== version) return;
+          console.error('Failed to save caption:', error);
+          setCaptionSaveStates((prev) => ({ ...prev, [fileName]: 'error' }));
+          toast.error('Caption was not saved', {
+            description: `${fileName}: check the Studio API, then retry.`,
+          });
+        });
+    },
+    [datasetId],
+  );
+
   const handleCaptionChange = React.useCallback(
     (fileName: string, value: string) => {
       setCaptions((prev) => ({ ...prev, [fileName]: value }));
+      setCaptionSaveStates((prev) => ({ ...prev, [fileName]: 'idle' }));
       const pending = pendingSaves.current.get(fileName);
       if (pending) clearTimeout(pending.timer);
-      const save = () => {
-        updateDatasetCaption(datasetId, fileName, value).catch((err) =>
-          console.error('Failed to save caption:', err),
-        );
-      };
+      const version = (captionVersions.current.get(fileName) ?? 0) + 1;
+      captionVersions.current.set(fileName, version);
+      const save = () => persistCaption(fileName, value, version);
       const timer = setTimeout(() => {
         pendingSaves.current.delete(fileName);
         save();
       }, 500);
       pendingSaves.current.set(fileName, { timer, save });
     },
-    [datasetId],
+    [persistCaption],
+  );
+
+  const handleCaptionRetry = React.useCallback(
+    (fileName: string, value: string) => {
+      const version = (captionVersions.current.get(fileName) ?? 0) + 1;
+      captionVersions.current.set(fileName, version);
+      persistCaption(fileName, value, version);
+    },
+    [persistCaption],
   );
 
   function handleScroll() {
@@ -189,8 +273,16 @@ export default function DatasetSidebar({
 
   return (
     <aside
-      className="fixed bottom-0 right-0 top-[var(--header-height)] z-50 flex max-h-[calc(100vh-var(--header-height))] min-w-[320px] shrink-0 flex-col border-l border-border bg-card"
-      style={{ width, maxWidth: SIDEBAR_MAX_WIDTH }}
+      ref={drawerRef}
+      tabIndex={-1}
+      role="dialog"
+      aria-label={`${dataset.name} dataset details`}
+      aria-modal={isMobile || undefined}
+      className="fixed bottom-0 right-0 top-[var(--header-height)] z-50 flex max-h-[calc(100dvh-var(--header-height))] min-w-0 shrink-0 flex-col border-l border-border bg-card md:min-w-[320px]"
+      style={{
+        width: isMobile ? '100%' : width,
+        maxWidth: isMobile ? 'none' : SIDEBAR_MAX_WIDTH,
+      }}
     >
       <div className="flex shrink-0 items-center justify-between border-b border-border px-5 py-4">
         <h2 className="m-0 min-w-0 truncate text-base font-semibold text-foreground">
@@ -203,7 +295,7 @@ export default function DatasetSidebar({
             onClick={onClose}
             title="Close"
             aria-label="Close"
-            className="flex items-center justify-center rounded-lg p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+            className="flex size-11 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
           >
             <X className="h-[18px] w-[18px]" />
           </button>
@@ -231,7 +323,9 @@ export default function DatasetSidebar({
                   mediaUrl={getDatasetMediaUrl(dataset.id, fileName)}
                   caption={captions[fileName] ?? ''}
                   thumbLoaded={!!thumbLoaded[fileName]}
+                  saveState={captionSaveStates[fileName] ?? 'idle'}
                   onCaptionChange={handleCaptionChange}
+                  onCaptionRetry={handleCaptionRetry}
                   onThumbLoaded={markThumbLoaded}
                 />
               ))}
@@ -240,14 +334,14 @@ export default function DatasetSidebar({
         </div>
       </div>
 
-      <div
+      {!isMobile && <div
         role="presentation"
         onMouseDown={onMouseDown}
         className={cn(
           'absolute bottom-0 left-0 top-0 z-[1] w-1.5 cursor-col-resize hover:bg-accent-blue/25',
           isDragging && 'bg-accent-blue/25',
         )}
-      />
+      />}
     </aside>
   );
 }

apps/fastvideo_studio/src/components/datasets/DownloadCaptions.tsx

@@ -6,7 +6,7 @@ import { Button } from '@/components/ui/button';
 import { downloadBlob } from '@/lib/utils';
 
 const MENU_ITEM =
-  'block w-full cursor-pointer px-4 py-2 text-left text-sm font-medium text-foreground transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-50';
+  'block min-h-11 w-full cursor-pointer px-4 py-2 text-left text-sm font-medium text-foreground transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-50';
 
 export default function DownloadCaptions({
   fileNames,

apps/fastvideo_studio/src/components/jobs/CreateJobButton.test.tsx

@@ -0,0 +1,53 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import CreateJobButton from './CreateJobButton';
+
+vi.mock('./CreateJobModal', () => ({
+  default: ({
+    isOpen,
+    workloadType,
+  }: {
+    isOpen: boolean;
+    workloadType: string;
+  }) =>
+    isOpen ? (
+      <div role="dialog" data-workload-type={workloadType}>
+        Create job form
+      </div>
+    ) : null,
+}));
+
+describe('CreateJobButton', () => {
+  it('opens the workload menu on click and selects an item', async () => {
+    const user = userEvent.setup();
+    render(<CreateJobButton jobType="inference" />);
+
+    await user.click(screen.getByRole('button', { name: 'Create Job' }));
+    await user.click(screen.getByRole('menuitem', { name: /I2V/i }));
+
+    expect(screen.getByRole('dialog')).toHaveAttribute(
+      'data-workload-type',
+      'i2v',
+    );
+  });
+
+  it('opens and operates the workload menu from the keyboard', async () => {
+    const user = userEvent.setup();
+    render(<CreateJobButton jobType="inference" />);
+
+    const trigger = screen.getByRole('button', { name: 'Create Job' });
+    trigger.focus();
+    await user.keyboard('{Enter}');
+
+    const firstItem = await screen.findByRole('menuitem', { name: /T2V/i });
+    expect(firstItem).toHaveFocus();
+    await user.keyboard('{Enter}');
+
+    expect(screen.getByRole('dialog')).toHaveAttribute(
+      'data-workload-type',
+      't2v',
+    );
+  });
+});

apps/fastvideo_studio/src/components/jobs/CreateJobButton.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { ChevronDown } from 'lucide-react';
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
 
 import CreateJobModal from '@/components/jobs/CreateJobModal';
 import { Button } from '@/components/ui/button';
@@ -33,31 +34,35 @@ export default function CreateJobButton({ jobType }: CreateJobButtonProps) {
 
   return (
     <>
-      <div className="group relative inline-block">
-        <Button type="button" className="gap-1.5">
-          Create Job
-          <ChevronDown className="size-3.5 opacity-85" aria-hidden />
-        </Button>
-        <div
-          role="menu"
-          className="invisible absolute right-0 top-full z-[200] mt-1 min-w-full -translate-y-1 rounded-lg border border-border bg-popover py-1 opacity-0 shadow-lg transition-all duration-150 group-hover:visible group-hover:translate-y-0 group-hover:opacity-100"
-        >
-          {options.map((opt) => (
-            <button
-              key={opt.type}
-              type="button"
-              role="menuitem"
-              onClick={() => openModal(opt.type)}
-              className="block w-full whitespace-nowrap px-4 py-2 text-left text-sm font-medium text-popover-foreground transition-colors hover:bg-secondary"
-            >
-              {opt.label}
-              <span className="mt-0.5 block text-xs font-normal text-muted-foreground">
-                {opt.desc}
-              </span>
-            </button>
-          ))}
-        </div>
-      </div>
+      <DropdownMenu.Root>
+        <DropdownMenu.Trigger asChild>
+          <Button type="button" className="gap-1.5">
+            Create Job
+            <ChevronDown className="size-3.5 opacity-85" aria-hidden />
+          </Button>
+        </DropdownMenu.Trigger>
+        <DropdownMenu.Portal>
+          <DropdownMenu.Content
+            align="end"
+            sideOffset={4}
+            collisionPadding={8}
+            className="z-[200] min-w-48 overflow-hidden rounded-lg border border-border bg-popover py-1 text-popover-foreground shadow-lg"
+          >
+            {options.map((opt) => (
+              <DropdownMenu.Item
+                key={opt.type}
+                onSelect={() => openModal(opt.type)}
+                className="flex min-h-11 cursor-pointer select-none flex-col justify-center px-4 py-2 text-left text-sm font-medium outline-none data-[highlighted]:bg-secondary"
+              >
+                {opt.label}
+                <span className="mt-0.5 block text-xs font-normal text-muted-foreground">
+                  {opt.desc}
+                </span>
+              </DropdownMenu.Item>
+            ))}
+          </DropdownMenu.Content>
+        </DropdownMenu.Portal>
+      </DropdownMenu.Root>
       <CreateJobModal
         isOpen={modalOpen}
         onClose={() => setModalOpen(false)}

apps/fastvideo_studio/src/components/jobs/CreateJobModal.test.tsx

@@ -50,6 +50,57 @@ function renderModal(
 }
 
 describe('CreateJobModal', () => {
+  it('shows a model loading error instead of an empty model list', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.mocked(getModels).mockRejectedValueOnce(new Error('network down'));
+
+    renderModal();
+
+    expect(
+      await screen.findByText(/Models could not be loaded/),
+    ).toBeInTheDocument();
+    expect(screen.getByLabelText('Model')).toHaveAttribute(
+      'aria-invalid',
+      'true',
+    );
+  });
+
+  it('keeps the form open and reports job creation failures', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.mocked(createJob).mockRejectedValueOnce(new Error('API rejected job'));
+    const user = userEvent.setup();
+    const { onClose, onSuccess } = renderModal();
+
+    await screen.findByRole('option', { name: 'Wan T2V (wan/t2v-1.3b)' });
+    await user.type(screen.getByLabelText('Prompt'), 'a careful test prompt');
+    await user.click(screen.getByRole('button', { name: 'Create Job' }));
+
+    expect(
+      await screen.findByText(/API rejected job.*then try again/),
+    ).toBeInTheDocument();
+    expect(onSuccess).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('reports image upload failures next to the file input', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.mocked(uploadImage).mockRejectedValueOnce(new Error('Upload failed'));
+    const user = userEvent.setup();
+    renderModal({ workloadType: 'i2v' });
+
+    await screen.findByRole('option', { name: 'Wan T2V (wan/t2v-1.3b)' });
+    const input = screen.getByLabelText('Image');
+    await user.upload(
+      input,
+      new File(['image'], 'input.png', { type: 'image/png' }),
+    );
+
+    expect(
+      await screen.findByText(/Upload failed.*Choose the image again/),
+    ).toBeInTheDocument();
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+  });
+
   it('renders the form fields for an inference job', async () => {
     renderModal();
 

apps/fastvideo_studio/src/components/jobs/CreateJobModal.tsx

@@ -103,6 +103,17 @@ export default function CreateJobModal({
   const [fakeScoreModelPath, setFakeScoreModelPath] = React.useState('');
   const [isSubmitting, setIsSubmitting] = React.useState(false);
   const [isLoadingModels, setIsLoadingModels] = React.useState(false);
+  const [isLoadingDatasets, setIsLoadingDatasets] = React.useState(false);
+  const [modelLoadError, setModelLoadError] = React.useState<string | null>(
+    null,
+  );
+  const [datasetLoadError, setDatasetLoadError] = React.useState<string | null>(
+    null,
+  );
+  const [imageUploadError, setImageUploadError] = React.useState<string | null>(
+    null,
+  );
+  const [submitError, setSubmitError] = React.useState<string | null>(null);
   const imageInputRef = React.useRef<HTMLInputElement>(null);
 
   // Seed field values from the persisted default options each time the modal
@@ -144,6 +155,10 @@ export default function CreateJobModal({
     setImageFileName('');
     setSelectedDatasetId('');
     setSelectedValidationDatasetId('');
+    setModelLoadError(null);
+    setDatasetLoadError(null);
+    setImageUploadError(null);
+    setSubmitError(null);
     if (workloadType === 'dmd_t2v') {
       setDmdUseVsa(false);
       setDmdVsaSparsity(0.8);
@@ -162,6 +177,7 @@ export default function CreateJobModal({
     // can't overwrite the current workload's model list/selection.
     let stale = false;
     setIsLoadingModels(true);
+    setModelLoadError(null);
     getModels(inferenceWorkload)
       .then((list) => {
         if (stale) return;
@@ -180,7 +196,13 @@ export default function CreateJobModal({
         }
       })
       .catch((e) => {
-        if (!stale) console.error('Failed to load models:', e);
+        if (stale) return;
+        console.error('Failed to load models:', e);
+        setModels([]);
+        setModelId('');
+        setModelLoadError(
+          'Models could not be loaded. Check the Studio API and reopen this form to try again.',
+        );
       })
       .finally(() => {
         if (!stale) setIsLoadingModels(false);
@@ -193,11 +215,22 @@ export default function CreateJobModal({
   // Training jobs need a dataset; load the ready datasets when relevant.
   React.useEffect(() => {
     if (isOpen && !isInference) {
+      setIsLoadingDatasets(true);
+      setDatasetLoadError(null);
       getDatasets()
         .then(setReadyDatasets)
-        .catch(() => setReadyDatasets([]));
+        .catch((error) => {
+          console.error('Failed to load datasets:', error);
+          setReadyDatasets([]);
+          setDatasetLoadError(
+            'Datasets could not be loaded. Check the Studio API and reopen this form to try again.',
+          );
+        })
+        .finally(() => setIsLoadingDatasets(false));
     } else {
       setReadyDatasets([]);
+      setIsLoadingDatasets(false);
+      setDatasetLoadError(null);
     }
   }, [isOpen, isInference]);
 
@@ -206,16 +239,24 @@ export default function CreateJobModal({
     if (!file) {
       setImagePath('');
       setImageFileName('');
+      setImageUploadError(null);
       return;
     }
     setIsUploadingImage(true);
     setImageFileName(file.name);
+    setImageUploadError(null);
     try {
       const { path } = await uploadImage(file);
       setImagePath(path);
-    } catch {
+    } catch (error) {
+      console.error('Failed to upload image:', error);
       setImagePath('');
       setImageFileName('');
+      setImageUploadError(
+        error instanceof Error
+          ? `${error.message}. Choose the image again to retry.`
+          : 'The image could not be uploaded. Choose it again to retry.',
+      );
     } finally {
       setIsUploadingImage(false);
     }
@@ -224,6 +265,7 @@ export default function CreateJobModal({
   function clearImage() {
     setImagePath('');
     setImageFileName('');
+    setImageUploadError(null);
     if (imageInputRef.current) imageInputRef.current.value = '';
   }
 
@@ -239,6 +281,7 @@ export default function CreateJobModal({
       workloadType === 'lora_t2v' ? 'lora' : jobType
     ) as JobType;
     setIsSubmitting(true);
+    setSubmitError(null);
     try {
       const payload: CreateJobRequest = {
         model_id: modelId,
@@ -296,6 +339,11 @@ export default function CreateJobModal({
       onClose();
     } catch (err) {
       console.error('Failed to create job:', err);
+      setSubmitError(
+        err instanceof Error
+          ? `${err.message}. Check the form and Studio API, then try again.`
+          : 'The job could not be created. Check the form and Studio API, then try again.',
+      );
     } finally {
       setIsSubmitting(false);
     }
@@ -343,7 +391,11 @@ export default function CreateJobModal({
               value={modelId}
               onChange={(e) => setModelId(e.target.value)}
               required
-              disabled={isSubmitting || isLoadingModels}
+              aria-describedby={
+                modelLoadError ? 'modal-model-error' : undefined
+              }
+              aria-invalid={modelLoadError ? true : undefined}
+              disabled={isSubmitting || isLoadingModels || !!modelLoadError}
             >
               <option value="" disabled>
                 {isLoadingModels
@@ -358,6 +410,15 @@ export default function CreateJobModal({
                 </option>
               ))}
             </NativeSelect>
+            {modelLoadError && (
+              <p
+                id="modal-model-error"
+                role="alert"
+                className="text-sm text-destructive"
+              >
+                {modelLoadError}
+              </p>
+            )}
           </FieldRow>
 
           {isInference && workloadType === 'i2v' && (
@@ -369,6 +430,10 @@ export default function CreateJobModal({
                 accept=".png,.jpg,.jpeg,.webp,.bmp"
                 onChange={handleImageChange}
                 disabled={isSubmitting || isUploadingImage}
+                aria-describedby={
+                  imageUploadError ? 'modal-image-error' : undefined
+                }
+                aria-invalid={imageUploadError ? true : undefined}
                 required
                 className="h-auto py-2 file:mr-3 file:cursor-pointer file:rounded-md file:border-0 file:bg-secondary file:px-2 file:py-1 file:text-sm file:text-secondary-foreground"
               />
@@ -385,6 +450,15 @@ export default function CreateJobModal({
                   </button>
                 </span>
               )}
+              {imageUploadError && (
+                <p
+                  id="modal-image-error"
+                  role="alert"
+                  className="text-sm text-destructive"
+                >
+                  {imageUploadError}
+                </p>
+              )}
             </FieldRow>
           )}
 
@@ -432,12 +506,22 @@ export default function CreateJobModal({
                     id="modal-dataset"
                     value={selectedDatasetId}
                     onChange={(e) => setSelectedDatasetId(e.target.value)}
-                    disabled={isSubmitting}
+                    aria-describedby={
+                      datasetLoadError ? 'modal-dataset-error' : undefined
+                    }
+                    aria-invalid={datasetLoadError ? true : undefined}
+                    disabled={
+                      isSubmitting || isLoadingDatasets || !!datasetLoadError
+                    }
                   >
                     <option value="" disabled>
-                      {readyDatasets.length === 0
-                        ? 'No datasets (add in Datasets tab)'
-                        : 'Select a dataset…'}
+                      {isLoadingDatasets
+                        ? 'Loading datasets…'
+                        : datasetLoadError
+                          ? 'Datasets unavailable'
+                          : readyDatasets.length === 0
+                            ? 'No datasets (add in Datasets tab)'
+                            : 'Select a dataset…'}
                     </option>
                     {readyDatasets.map((d) => (
                       <option key={d.id} value={d.id}>
@@ -445,6 +529,15 @@ export default function CreateJobModal({
                       </option>
                     ))}
                   </NativeSelect>
+                  {datasetLoadError && (
+                    <p
+                      id="modal-dataset-error"
+                      role="alert"
+                      className="text-sm text-destructive"
+                    >
+                      {datasetLoadError}
+                    </p>
+                  )}
                 </FieldRow>
                 <FieldRow
                   htmlFor="modal-validation-dataset"
@@ -457,7 +550,9 @@ export default function CreateJobModal({
                     onChange={(e) =>
                       setSelectedValidationDatasetId(e.target.value)
                     }
-                    disabled={isSubmitting}
+                    disabled={
+                      isSubmitting || isLoadingDatasets || !!datasetLoadError
+                    }
                   >
                     <option value="">None</option>
                     {readyDatasets.map((d) => (
@@ -811,9 +906,22 @@ export default function CreateJobModal({
             </details>
           )}
 
-          <div>
-            <Button type="submit" disabled={isSubmitting}>
-              {isSubmitting ? 'Creating...' : 'Create Job'}
+          <div className="flex flex-col items-start gap-2">
+            {submitError && (
+              <p role="alert" className="text-sm text-destructive">
+                {submitError}
+              </p>
+            )}
+            <Button
+              type="submit"
+              disabled={
+                isSubmitting ||
+                isUploadingImage ||
+                !!modelLoadError ||
+                !!datasetLoadError
+              }
+            >
+              {isSubmitting ? 'Creating…' : 'Create Job'}
             </Button>
           </div>
         </form>

apps/fastvideo_studio/src/components/jobs/JobCard.test.tsx

@@ -20,6 +20,14 @@ vi.mock('@/lib/api', () => ({
   downloadJobVideo: vi.fn(),
 }));
 
+vi.mock('@/lib/utils', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/lib/utils')>();
+  return {
+    ...actual,
+    downloadBlob: vi.fn(),
+  };
+});
+
 const makeJob = (overrides: Partial<Job> = {}): Job =>
   makeBaseJob({
     model_id: 'Wan2.1-T2V',
@@ -46,6 +54,16 @@ beforeEach(() => {
 });
 
 describe('JobCard', () => {
+  it('keeps selection and job action buttons as semantic siblings', () => {
+    render(<JobCard job={makeJob()} />);
+
+    const selectButton = screen.getByRole('button', { pressed: false });
+    const deleteButton = screen.getByRole('button', { name: 'Delete' });
+
+    expect(selectButton).toHaveTextContent('Wan2.1-T2V');
+    expect(selectButton).not.toContainElement(deleteButton);
+  });
+
   it('renders the model, prompt, status and inference meta', () => {
     render(<JobCard job={makeJob()} />);
     expect(screen.getByText('Wan2.1-T2V')).toBeInTheDocument();

apps/fastvideo_studio/src/components/jobs/JobCard.tsx

@@ -119,18 +119,10 @@ export default function JobCard({ job, onJobUpdated }: JobCardProps) {
     }
   }
 
-  function handleSelectJob(e: React.MouseEvent | React.KeyboardEvent) {
-    if ((e.target as HTMLElement).closest('button')) return;
+  function handleSelectJob() {
     setActiveJobId(isSelected ? null : job.id);
   }
 
-  function handleKeyDown(e: React.KeyboardEvent) {
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      handleSelectJob(e);
-    }
-  }
-
   async function handleDownloadVideo(e: React.MouseEvent) {
     e.preventDefault();
     e.stopPropagation();
@@ -148,11 +140,7 @@ export default function JobCard({ job, onJobUpdated }: JobCardProps) {
   }
 
   return (
-    <div
-      role="button"
-      tabIndex={0}
-      onClick={handleSelectJob}
-      onKeyDown={handleKeyDown}
+    <article
       className={cn(
         'mb-3 flex cursor-pointer flex-col gap-2.5 rounded-lg border bg-background p-4 transition-colors last:mb-0',
         isSelected
@@ -160,35 +148,42 @@ export default function JobCard({ job, onJobUpdated }: JobCardProps) {
           : 'border-border hover:border-muted-foreground/40',
       )}
     >
-      <div className="flex flex-wrap items-center justify-between gap-2">
-        <span className="text-[0.95rem] font-semibold text-foreground">
-          {job.model_id}
-        </span>
-        <Badge variant={BADGE_VARIANTS[job.status] ?? 'secondary'}>
-          {job.status}
-        </Badge>
-      </div>
-      <p className="max-w-full overflow-hidden text-ellipsis whitespace-nowrap text-sm text-muted-foreground">
-        {job.prompt}
-      </p>
-      <div className="flex flex-wrap items-center gap-4 text-xs text-muted-foreground">
-        {job.job_type === 'inference' ? (
-          <>
-            <span>{job.num_frames} frames</span>
-            <span>
-              {job.height}×{job.width}
-            </span>
-          </>
-        ) : (
-          <span>{job.workload_type?.replace(/_/g, ' ') ?? job.job_type}</span>
-        )}
-        {elapsedTime && (
-          <span className="inline-flex items-center gap-1">
-            <Timer className="size-3.5" aria-hidden />
-            {elapsedTime}
+      <button
+        type="button"
+        aria-pressed={isSelected}
+        onClick={handleSelectJob}
+        className="flex w-full flex-col gap-2.5 rounded-md text-left"
+      >
+        <span className="flex flex-wrap items-center justify-between gap-2">
+          <span className="text-[0.95rem] font-semibold text-foreground">
+            {job.model_id}
           </span>
-        )}
-      </div>
+          <Badge variant={BADGE_VARIANTS[job.status] ?? 'secondary'}>
+            {job.status}
+          </Badge>
+        </span>
+        <span className="max-w-full overflow-hidden text-ellipsis whitespace-nowrap text-sm text-muted-foreground">
+          {job.prompt}
+        </span>
+        <span className="flex flex-wrap items-center gap-4 text-xs text-muted-foreground">
+          {job.job_type === 'inference' ? (
+            <>
+              <span>{job.num_frames} frames</span>
+              <span>
+                {job.height}×{job.width}
+              </span>
+            </>
+          ) : (
+            <span>{job.workload_type?.replace(/_/g, ' ') ?? job.job_type}</span>
+          )}
+          {elapsedTime && (
+            <span className="inline-flex items-center gap-1">
+              <Timer className="size-3.5" aria-hidden />
+              {elapsedTime}
+            </span>
+          )}
+        </span>
+      </button>
       <div className="flex flex-wrap items-center gap-1.5">
         {job.status === 'running' ? (
           <Button
@@ -240,6 +235,6 @@ export default function JobCard({ job, onJobUpdated }: JobCardProps) {
           Delete
         </Button>
       </div>
-    </div>
+    </article>
   );
 }

apps/fastvideo_studio/src/components/jobs/JobDetailsSidebar.test.tsx

@@ -19,6 +19,32 @@ const makeJob = (overrides: Partial<Job> = {}): Job =>
   });
 
 describe('JobDetailsSidebar', () => {
+  it('fills the mobile viewport without reserving main-content width', async () => {
+    vi.mocked(getJobLogs).mockResolvedValue({
+      lines: [],
+      total: 0,
+      progress: 0,
+      progress_msg: '',
+      phase: '',
+    });
+    const onWidthChange = vi.fn();
+
+    render(
+      <JobDetailsSidebar
+        job={makeJob({ status: 'completed' })}
+        isMobile
+        onClose={vi.fn()}
+        onWidthChange={onWidthChange}
+      />,
+    );
+
+    const drawer = screen.getByRole('dialog', { name: 'Job details' });
+    expect(drawer).toHaveStyle({ width: '100%', maxWidth: 'none' });
+    expect(drawer).toHaveAttribute('aria-modal', 'true');
+    expect(drawer).toHaveFocus();
+    expect(onWidthChange).toHaveBeenCalledWith(0);
+  });
+
   it('renders log lines streamed from the job log poll', async () => {
     vi.mocked(getJobLogs).mockResolvedValue({
       lines: ['boot sequence started', 'loading model weights'],

apps/fastvideo_studio/src/components/jobs/JobDetailsSidebar.tsx

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { X } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
+import { useDrawerFocus } from '@/hooks/useDrawerFocus';
 import { useResizable } from '@/hooks/useResizable';
 import { downloadJobLog, getJobLogs } from '@/lib/api';
 import type { Job } from '@/lib/types';
@@ -15,13 +16,16 @@ const POLL_INTERVAL_MS = 2000;
 
 export default function JobDetailsSidebar({
   job,
+  isMobile = false,
   onClose,
   onWidthChange,
 }: {
   job: Job;
+  isMobile?: boolean;
   onClose: () => void;
   onWidthChange?: (w: number) => void;
 }) {
+  const drawerRef = useDrawerFocus<HTMLElement>(isMobile);
   const [width, setWidth] = React.useState(360);
   const [isDragging, setIsDragging] = React.useState(false);
   const [isLoading, setIsLoading] = React.useState(false);
@@ -53,8 +57,8 @@ export default function JobDetailsSidebar({
   });
 
   React.useEffect(() => {
-    onWidthChange?.(width);
-  }, [width, onWidthChange]);
+    onWidthChange?.(isMobile ? 0 : width);
+  }, [isMobile, width, onWidthChange]);
 
   // Auto-scroll the console to the bottom whenever new lines land. Runs after
   // commit so scrollHeight reflects the freshly-rendered output.
@@ -137,8 +141,16 @@ export default function JobDetailsSidebar({
 
   return (
     <aside
-      className="fixed bottom-0 right-0 top-[var(--header-height)] z-50 flex max-h-[calc(100vh-var(--header-height))] min-w-[280px] shrink-0 flex-col border-l border-border bg-card"
-      style={{ width, maxWidth: SIDEBAR_MAX_WIDTH }}
+      ref={drawerRef}
+      tabIndex={-1}
+      role="dialog"
+      aria-label="Job details"
+      aria-modal={isMobile || undefined}
+      className="fixed bottom-0 right-0 top-[var(--header-height)] z-50 flex max-h-[calc(100dvh-var(--header-height))] min-w-0 shrink-0 flex-col border-l border-border bg-card md:min-w-[280px]"
+      style={{
+        width: isMobile ? '100%' : width,
+        maxWidth: isMobile ? 'none' : SIDEBAR_MAX_WIDTH,
+      }}
     >
       <div className="flex items-center justify-between border-b border-border px-5 py-4">
         <h2 className="m-0 text-base font-semibold text-foreground">
@@ -195,14 +207,14 @@ export default function JobDetailsSidebar({
         </pre>
       </div>
 
-      <div
+      {!isMobile && <div
         role="presentation"
         onMouseDown={onMouseDown}
         className={cn(
           'absolute bottom-0 left-0 top-0 z-[1] w-1.5 cursor-col-resize hover:bg-accent-blue/25',
           isDragging && 'bg-accent-blue/25',
         )}
-      />
+      />}
     </aside>
   );
 }

apps/fastvideo_studio/src/components/jobs/JobQueue.test.tsx

@@ -1,4 +1,4 @@
-import { act, render, screen, waitFor } from '@testing-library/react';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import JobQueue from '@/components/jobs/JobQueue';
@@ -37,6 +37,46 @@ beforeEach(() => {
 });
 
 describe('JobQueue', () => {
+  it('shows a loading placeholder before the initial request settles', async () => {
+    let resolveJobs: (jobs: Job[]) => void = () => {};
+    vi.mocked(getJobsList).mockReturnValue(
+      new Promise<Job[]>((resolve) => {
+        resolveJobs = resolve;
+      }),
+    );
+
+    render(<JobQueue jobType="inference" />);
+
+    expect(screen.getByLabelText('Loading jobs')).toBeInTheDocument();
+    expect(
+      screen.queryByText('No inference jobs yet. Create one above.'),
+    ).not.toBeInTheDocument();
+
+    act(() => resolveJobs([]));
+    expect(
+      await screen.findByText('No inference jobs yet. Create one above.'),
+    ).toBeInTheDocument();
+  });
+
+  it('shows request failures separately from an empty queue and retries', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.mocked(getJobsList).mockRejectedValueOnce(new Error('network down'));
+    render(<JobQueue jobType="inference" />);
+
+    expect(
+      await screen.findByText(/Could not load jobs from the Studio API/),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText('No inference jobs yet. Create one above.'),
+    ).not.toBeInTheDocument();
+
+    vi.mocked(getJobsList).mockResolvedValueOnce([]);
+    fireEvent.click(screen.getByRole('button', { name: 'Try Again' }));
+    expect(
+      await screen.findByText('No inference jobs yet. Create one above.'),
+    ).toBeInTheDocument();
+  });
+
   it('shows an empty placeholder and fetches for the single job type', async () => {
     render(<JobQueue jobType="inference" />);
     expect(

apps/fastvideo_studio/src/components/jobs/JobQueue.tsx

@@ -1,8 +1,10 @@
 'use client';
 
 import * as React from 'react';
+import { AlertTriangle } from 'lucide-react';
 
 import JobCard from '@/components/jobs/JobCard';
+import { Button } from '@/components/ui/button';
 import { useStore } from '@/hooks/useStore';
 import { getJobsList } from '@/lib/api';
 import type { Job, JobType } from '@/lib/types';
@@ -32,6 +34,8 @@ function jobsShallowEqual(a: Job | null, b: Job | null): boolean {
 
 export default function JobQueue({ jobType, jobTypesForList }: JobQueueProps) {
   const [jobs, setJobs] = React.useState<Job[]>([]);
+  const [isInitialLoading, setIsInitialLoading] = React.useState(true);
+  const [error, setError] = React.useState<string | null>(null);
   const { nonce } = useStore(jobsRefreshStore);
   const { activeJobId } = useStore(activeJobStore);
 
@@ -71,11 +75,22 @@ export default function JobQueue({ jobType, jobTypesForList }: JobQueueProps) {
               new Date(a.created_at ?? 0).getTime(),
           );
       }
-      if (seq === fetchSeq.current) setJobs(next);
+      if (seq === fetchSeq.current) {
+        setJobs(next);
+        setError(null);
+      }
     } catch (e) {
       console.error('Failed to fetch jobs:', e);
+      if (seq === fetchSeq.current) {
+        setError(
+          'Could not load jobs from the Studio API. Check the server and try again.',
+        );
+      }
     } finally {
-      if (seq === fetchSeq.current) inFlight.current = false;
+      if (seq === fetchSeq.current) {
+        inFlight.current = false;
+        setIsInitialLoading(false);
+      }
     }
   }, [typesKey]);
 
@@ -122,20 +137,59 @@ export default function JobQueue({ jobType, jobTypesForList }: JobQueueProps) {
   const multiType = typesToFetch.length > 1;
 
   return (
-    <main className="mx-auto flex w-full max-w-[850px] flex-col gap-6 px-4 pb-12">
+    <div className="mx-auto flex w-full max-w-[850px] flex-col gap-6 px-4 pb-12">
       <section className="p-6">
-        <div>
-          {jobs.length === 0 ? (
+        <div aria-busy={isInitialLoading}>
+          {isInitialLoading ? (
+            <div
+              aria-label="Loading jobs"
+              className="flex flex-col gap-3 py-2"
+            >
+              {[0, 1, 2].map((item) => (
+                <div
+                  key={item}
+                  className="h-32 animate-pulse rounded-lg border border-border bg-muted/50"
+                />
+              ))}
+            </div>
+          ) : error && jobs.length === 0 ? (
+            <div
+              role="alert"
+              className="flex flex-col items-center gap-3 py-8 text-center"
+            >
+              <AlertTriangle
+                className="size-6 text-destructive"
+                aria-hidden
+              />
+              <p className="max-w-md text-sm text-muted-foreground">{error}</p>
+              <Button type="button" variant="outline" onClick={fetchJobs}>
+                Try Again
+              </Button>
+            </div>
+          ) : (
+            <>
+              {error && (
+                <p
+                  role="status"
+                  className="mb-3 rounded-lg border border-amber-500/50 bg-amber-500/10 px-3 py-2 text-sm text-foreground"
+                >
+                  Job updates are temporarily unavailable. Showing the most
+                  recent results.
+                </p>
+              )}
+              {jobs.length === 0 ? (
             <p className="py-8 text-center text-muted-foreground">
               No {multiType ? 'jobs' : `${jobType} jobs`} yet. Create one above.
             </p>
-          ) : (
-            jobs.map((job) => (
-              <JobCard key={job.id} job={job} onJobUpdated={fetchJobs} />
-            ))
+              ) : (
+                jobs.map((job) => (
+                  <JobCard key={job.id} job={job} onJobUpdated={fetchJobs} />
+                ))
+              )}
+            </>
           )}
         </div>
       </section>
-    </main>
+    </div>
   );
 }

apps/fastvideo_studio/src/components/shell/AppShell.tsx

@@ -9,6 +9,7 @@ import { HeaderActionsProvider } from '@/components/shell/HeaderActionsContext';
 import PrimarySidebar from '@/components/shell/PrimarySidebar';
 import JobDetailsSidebar from '@/components/jobs/JobDetailsSidebar';
 import { Toaster } from '@/components/ui/sonner';
+import { useMediaQuery } from '@/hooks/useMediaQuery';
 import { useStore } from '@/hooks/useStore';
 import {
   activeDatasetStore,
@@ -23,46 +24,80 @@ export function AppShell({ children }: { children: React.ReactNode }) {
   const pathname = usePathname();
   const { activeJob } = useStore(activeJobStore);
   const { activeDataset } = useStore(activeDatasetStore);
+  const isMobile = useMediaQuery('(max-width: 767px)');
 
   const [primaryWidth, setPrimaryWidth] = React.useState(220);
   const [secondaryWidth, setSecondaryWidth] = React.useState(0);
+  const [primaryOpen, setPrimaryOpen] = React.useState(false);
 
   const jobSidebarOpen = JOB_ROUTES.includes(pathname) && activeJob != null;
   const datasetSidebarOpen =
     pathname === '/datasets' && activeDataset != null;
   const secondaryOpen = jobSidebarOpen || datasetSidebarOpen;
+  // Mobile detail drawers claim aria-modal, so everything behind them must
+  // actually be inert — the platform enforces what the ARIA claims.
+  const drawerModal = isMobile && secondaryOpen;
 
   React.useEffect(() => {
     initDefaultOptions();
   }, []);
 
+  React.useEffect(() => {
+    setPrimaryOpen(false);
+  }, [pathname]);
+
   React.useEffect(() => {
     function handleKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape' && !document.querySelector('[data-modal]')) {
-        if (activeJobStore.get().activeJob) setActiveJobId(null);
-        if (activeDatasetStore.get().activeDataset) setActiveDatasetId(null);
+      if (e.key !== 'Escape' || document.querySelector('[data-modal]')) return;
+      if (primaryOpen) {
+        setPrimaryOpen(false);
+        return;
       }
+      if (activeJobStore.get().activeJob) setActiveJobId(null);
+      if (activeDatasetStore.get().activeDataset) setActiveDatasetId(null);
     }
     document.addEventListener('keydown', handleKeyDown);
     return () => document.removeEventListener('keydown', handleKeyDown);
-  }, []);
+  }, [primaryOpen]);
 
   return (
     <HeaderActionsProvider>
-      <Header />
+      <div
+        style={{ display: 'contents' }}
+        inert={drawerModal ? true : undefined}
+      >
+        <Header
+          navigationOpen={primaryOpen}
+          onNavigationToggle={() => setPrimaryOpen((open) => !open)}
+        />
+      </div>
       <div
         className="flex overflow-hidden"
         style={{
           marginTop: 'var(--header-height)',
-          height: 'calc(100vh - var(--header-height))',
+          height: 'calc(100dvh - var(--header-height))',
         }}
       >
-        <PrimarySidebar onWidthChange={setPrimaryWidth} />
+        <PrimarySidebar
+          isMobile={isMobile}
+          mobileOpen={primaryOpen}
+          onMobileClose={() => setPrimaryOpen(false)}
+          onWidthChange={setPrimaryWidth}
+        />
+        {primaryOpen && (
+          <button
+            type="button"
+            aria-label="Close navigation"
+            onClick={() => setPrimaryOpen(false)}
+            className="fixed inset-x-0 bottom-0 top-[var(--header-height)] z-40 bg-black/55 md:hidden"
+          />
+        )}
         <main
           className="flex min-w-0 flex-1 flex-col overflow-auto"
+          inert={drawerModal ? true : undefined}
           style={{
-            marginLeft: primaryWidth,
-            marginRight: secondaryOpen ? secondaryWidth : 0,
+            marginLeft: isMobile ? 0 : primaryWidth,
+            marginRight: isMobile || !secondaryOpen ? 0 : secondaryWidth,
           }}
         >
           {children}
@@ -70,6 +105,7 @@ export function AppShell({ children }: { children: React.ReactNode }) {
         {jobSidebarOpen && activeJob && (
           <JobDetailsSidebar
             job={activeJob}
+            isMobile={isMobile}
             onClose={() => setActiveJobId(null)}
             onWidthChange={setSecondaryWidth}
           />
@@ -77,6 +113,7 @@ export function AppShell({ children }: { children: React.ReactNode }) {
         {datasetSidebarOpen && activeDataset && (
           <DatasetSidebar
             dataset={activeDataset}
+            isMobile={isMobile}
             onClose={() => setActiveDatasetId(null)}
             onWidthChange={setSecondaryWidth}
           />

apps/fastvideo_studio/src/components/shell/Header.tsx

@@ -1,8 +1,10 @@
 'use client';
 
+import { Menu, X } from 'lucide-react';
 import { usePathname } from 'next/navigation';
 
 import { useHeaderActions } from '@/components/shell/HeaderActionsContext';
+import { Button } from '@/components/ui/button';
 import { ThemeToggle } from '@/components/ui/theme-toggle';
 
 const TAB_TITLES: Record<string, string> = {
@@ -15,25 +17,47 @@ const TAB_TITLES: Record<string, string> = {
   '/settings': 'Settings',
 };
 
-export default function Header() {
+export default function Header({
+  navigationOpen,
+  onNavigationToggle,
+}: {
+  navigationOpen: boolean;
+  onNavigationToggle: () => void;
+}) {
   const pathname = usePathname();
   const { actions } = useHeaderActions();
   const title = TAB_TITLES[pathname] ?? 'FastVideo';
 
   return (
-    <header className="fixed inset-x-0 top-0 z-[100] flex h-[var(--header-height)] items-center gap-6 border-b border-border bg-background/80 px-6 backdrop-blur">
+    <header className="fixed inset-x-0 top-0 z-[100] flex h-[var(--header-height)] items-center gap-2 border-b border-border bg-background/80 px-2 backdrop-blur sm:px-4 md:gap-6 md:px-6">
+      <Button
+        type="button"
+        variant="outline"
+        size="icon"
+        aria-label={navigationOpen ? 'Close navigation' : 'Open navigation'}
+        aria-controls="primary-navigation"
+        aria-expanded={navigationOpen}
+        onClick={onNavigationToggle}
+        className="shrink-0 md:hidden"
+      >
+        {navigationOpen ? (
+          <X className="size-5" aria-hidden />
+        ) : (
+          <Menu className="size-5" aria-hidden />
+        )}
+      </Button>
       {/* eslint-disable-next-line @next/next/no-img-element */}
       <img
         src="/logo.svg"
         alt="FastVideo Logo"
         width={100}
         height={42}
-        className="block h-[42px] w-[100px]"
+        className="hidden h-[42px] w-[78px] shrink-0 object-contain min-[361px]:block md:w-[100px]"
       />
-      <h1 className="m-0 flex-1 text-xl font-semibold tracking-tight">
+      <h1 className="sr-only m-0 flex-1 text-xl font-semibold tracking-tight md:not-sr-only">
         {title}
       </h1>
-      <div className="flex items-center gap-3">
+      <div className="ml-auto flex min-w-0 items-center gap-2 md:gap-3">
         {actions}
         <ThemeToggle />
       </div>

apps/fastvideo_studio/src/components/shell/PrimarySidebar.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import * as React from 'react';
+import { X } from 'lucide-react';
 import Link from 'next/link';
 import { usePathname } from 'next/navigation';
 
@@ -19,12 +20,18 @@ const JOB_ROUTES = [
 ] as const;
 
 const TAB_BASE =
-  'block px-5 py-[0.65rem] text-left text-sm text-muted-foreground transition-colors hover:bg-accent/60 hover:text-foreground';
+  'block min-h-11 px-5 py-[0.65rem] text-left text-sm text-muted-foreground transition-colors hover:bg-accent/60 hover:text-foreground';
 const TAB_ACTIVE = 'bg-accent-blue/10 font-medium text-accent-blue';
 
 export default function PrimarySidebar({
+  isMobile,
+  mobileOpen,
+  onMobileClose,
   onWidthChange,
 }: {
+  isMobile: boolean;
+  mobileOpen: boolean;
+  onMobileClose: () => void;
   onWidthChange?: (w: number) => void;
 }) {
   const pathname = usePathname();
@@ -38,8 +45,8 @@ export default function PrimarySidebar({
   const isJobsActive = JOB_ROUTES.some((r) => pathname === r.href);
 
   React.useEffect(() => {
-    onWidthChange?.(layoutWidth);
-  }, [layoutWidth, onWidthChange]);
+    onWidthChange?.(isMobile ? 0 : layoutWidth);
+  }, [isMobile, layoutWidth, onWidthChange]);
 
   React.useEffect(() => {
     if (JOB_ROUTES.some((r) => pathname === r.href)) {
@@ -58,11 +65,37 @@ export default function PrimarySidebar({
 
   return (
     <aside
-      className="fixed bottom-0 left-0 top-[var(--header-height)] z-50 flex max-h-[calc(100vh-var(--header-height))] shrink-0 flex-col border-r border-border bg-card"
-      style={{ width: effectiveWidth }}
+      id="primary-navigation"
+      aria-hidden={isMobile && !mobileOpen}
+      inert={isMobile && !mobileOpen ? true : undefined}
+      className={cn(
+        'fixed bottom-0 left-0 top-[var(--header-height)] z-50 flex max-h-[calc(100dvh-var(--header-height))] shrink-0 flex-col border-r border-border bg-card transition-transform duration-200 md:translate-x-0',
+        mobileOpen ? 'translate-x-0' : '-translate-x-full',
+      )}
+      style={{
+        width: isMobile
+          ? 'min(18rem, calc(100vw - 3rem))'
+          : effectiveWidth,
+      }}
     >
+      {isMobile && (
+        <div className="flex h-14 items-center justify-between border-b border-border px-4">
+          <span className="text-sm font-semibold">Navigation</span>
+          <button
+            type="button"
+            onClick={onMobileClose}
+            aria-label="Close navigation"
+            className="flex size-11 items-center justify-center rounded-lg text-muted-foreground hover:bg-accent hover:text-foreground"
+          >
+            <X className="size-5" aria-hidden />
+          </button>
+        </div>
+      )}
       {!isCollapsed && (
-        <nav className="flex flex-col py-2">
+        <nav
+          aria-label="Primary navigation"
+          className="flex flex-col overflow-y-auto py-2"
+        >
           <div className="flex flex-col">
             <button
               type="button"
@@ -95,6 +128,8 @@ export default function PrimarySidebar({
                   <Link
                     key={route.href}
                     href={route.href}
+                    aria-current={pathname === route.href ? 'page' : undefined}
+                    onClick={onMobileClose}
                     className={cn(
                       TAB_BASE,
                       'px-4 py-2 text-[0.85rem]',
@@ -109,24 +144,32 @@ export default function PrimarySidebar({
           </div>
           <Link
             href="/datasets"
+            aria-current={pathname === '/datasets' ? 'page' : undefined}
+            onClick={onMobileClose}
             className={cn(TAB_BASE, pathname === '/datasets' && TAB_ACTIVE)}
           >
             Datasets
           </Link>
           <Link
             href="/gallery"
+            aria-current={pathname === '/gallery' ? 'page' : undefined}
+            onClick={onMobileClose}
             className={cn(TAB_BASE, pathname === '/gallery' && TAB_ACTIVE)}
           >
             Gallery
           </Link>
           <Link
             href="/gpus"
+            aria-current={pathname === '/gpus' ? 'page' : undefined}
+            onClick={onMobileClose}
             className={cn(TAB_BASE, pathname === '/gpus' && TAB_ACTIVE)}
           >
             GPUs
           </Link>
           <Link
             href="/settings"
+            aria-current={pathname === '/settings' ? 'page' : undefined}
+            onClick={onMobileClose}
             className={cn(TAB_BASE, pathname === '/settings' && TAB_ACTIVE)}
           >
             Settings
@@ -134,7 +177,7 @@ export default function PrimarySidebar({
         </nav>
       )}
 
-      <div
+      {!isMobile && <div
         className={cn(
           'absolute bottom-0 p-2',
           isCollapsed ? '-right-[60px] top-0' : 'right-0',
@@ -145,8 +188,7 @@ export default function PrimarySidebar({
           onClick={() => setIsCollapsed((v) => !v)}
           title={isCollapsed ? 'Expand sidebar' : 'Collapse sidebar'}
           className={cn(
-            'flex items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-accent hover:text-foreground',
-            isCollapsed ? 'p-3' : 'p-2',
+            'flex size-11 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-accent hover:text-foreground',
           )}
         >
           <svg
@@ -159,9 +201,9 @@ export default function PrimarySidebar({
             <path d={isCollapsed ? 'M9 18l6-6-6-6' : 'M15 18l-6-6 6-6'} />
           </svg>
         </button>
-      </div>
+      </div>}
 
-      {!isCollapsed && (
+      {!isMobile && !isCollapsed && (
         <div
           role="presentation"
           onMouseDown={onMouseDown}

apps/fastvideo_studio/src/components/system/GpuGrid.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import GpuGrid from './GpuGrid';
@@ -73,4 +73,30 @@ describe('GpuGrid', () => {
       await screen.findByText(/Could not reach the API server/),
     ).toBeInTheDocument();
   });
+
+  it('keeps the last snapshot visible and warns when a refresh fails', async () => {
+    vi.useFakeTimers();
+    try {
+      vi.mocked(getGpus)
+        .mockResolvedValueOnce(SNAPSHOT)
+        .mockRejectedValueOnce(new Error('network down'));
+
+      render(<GpuGrid />);
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(0);
+      });
+      expect(screen.getAllByText('NVIDIA B200')).toHaveLength(2);
+
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(3000);
+      });
+
+      expect(
+        screen.getByText(/values below may be stale/),
+      ).toBeInTheDocument();
+      expect(screen.getAllByText('NVIDIA B200')).toHaveLength(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });

apps/fastvideo_studio/src/components/system/GpuGrid.tsx

@@ -1,7 +1,9 @@
 'use client';
 
 import * as React from 'react';
+import { AlertTriangle } from 'lucide-react';
 
+import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
 import { getGpus, type GpuInfo, type GpuSnapshot } from '@/lib/api';
 import { cn } from '@/lib/utils';
@@ -97,7 +99,8 @@ function GpuCard({ gpu }: { gpu: GpuInfo }) {
 
 export default function GpuGrid() {
   const [snapshot, setSnapshot] = React.useState<GpuSnapshot | null>(null);
-  const [fetchError, setFetchError] = React.useState(false);
+  const [fetchError, setFetchError] = React.useState<string | null>(null);
+  const [retryToken, setRetryToken] = React.useState(0);
 
   React.useEffect(() => {
     let mounted = true;
@@ -110,10 +113,14 @@ export default function GpuGrid() {
         const next = await getGpus();
         if (mounted) {
           setSnapshot(next);
-          setFetchError(false);
+          setFetchError(null);
         }
       } catch {
-        if (mounted) setFetchError(true);
+        if (mounted) {
+          setFetchError(
+            'GPU status could not be refreshed. The values below may be stale.',
+          );
+        }
       } finally {
         inFlight = false;
       }
@@ -125,14 +132,27 @@ export default function GpuGrid() {
       mounted = false;
       clearInterval(interval);
     };
-  }, []);
+  }, [retryToken]);
 
   if (fetchError && !snapshot) {
     return (
-      <p className="py-8 text-center text-muted-foreground">
-        Could not reach the API server. GPU status needs the studio API server
-        running.
-      </p>
+      <div
+        role="alert"
+        className="flex flex-col items-center gap-3 py-8 text-center"
+      >
+        <AlertTriangle className="size-6 text-destructive" aria-hidden />
+        <p className="text-muted-foreground">
+          Could not reach the API server. GPU status needs the Studio API server
+          running.
+        </p>
+        <Button
+          type="button"
+          variant="outline"
+          onClick={() => setRetryToken((token) => token + 1)}
+        >
+          Try Again
+        </Button>
+      </div>
     );
   }
   if (!snapshot) {
@@ -150,9 +170,22 @@ export default function GpuGrid() {
   return (
     <div className="flex flex-col gap-4">
       {fetchError && (
-        <p className="rounded-md border border-amber-500/40 bg-amber-500/10 px-3 py-2 text-sm text-amber-600 dark:text-amber-400">
-          Lost contact with the API server — showing the last known values.
-        </p>
+        <div
+          role="status"
+          aria-live="polite"
+          className="flex flex-wrap items-center gap-3 rounded-lg border border-amber-500/50 bg-amber-500/10 px-3 py-2 text-sm"
+        >
+          <AlertTriangle className="size-4 text-amber-600" aria-hidden />
+          <span className="min-w-0 flex-1">{fetchError}</span>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            onClick={() => setRetryToken((token) => token + 1)}
+          >
+            Refresh Now
+          </Button>
+        </div>
       )}
       <div className="grid gap-4 [grid-template-columns:repeat(auto-fill,minmax(280px,1fr))]">
         {snapshot.gpus.map((gpu) => (

apps/fastvideo_studio/src/components/ui/accessibility.test.tsx

@@ -0,0 +1,48 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { Button } from './button';
+import { Input } from './input';
+import { NativeSelect } from './native-select';
+import { Slider } from './slider';
+import { Switch } from './switch';
+
+describe('shared control accessibility', () => {
+  it('keeps button, input, and select targets at least 44px tall', () => {
+    render(
+      <>
+        <Button size="sm">Small action</Button>
+        <Input aria-label="Text value" />
+        <NativeSelect aria-label="Choice" defaultValue="one">
+          <option value="one">One</option>
+        </NativeSelect>
+      </>,
+    );
+
+    expect(screen.getByRole('button', { name: 'Small action' })).toHaveClass(
+      'h-11',
+    );
+    expect(screen.getByRole('textbox', { name: 'Text value' })).toHaveClass(
+      'h-11',
+    );
+    expect(screen.getByRole('combobox', { name: 'Choice' })).toHaveClass(
+      'h-11',
+    );
+  });
+
+  it('uses 44px switch and slider interaction surfaces', () => {
+    render(
+      <>
+        <Switch aria-label="Enabled" />
+        <Slider aria-label="Amount" defaultValue={[50]} />
+      </>,
+    );
+
+    expect(screen.getByRole('switch', { name: 'Enabled' })).toHaveClass(
+      'size-11',
+    );
+    expect(screen.getByRole('slider', { name: 'Amount' })).toHaveClass(
+      'size-11',
+    );
+  });
+});

apps/fastvideo_studio/src/components/ui/badge.tsx

@@ -29,11 +29,12 @@ const badgeVariants = cva(
 );
 
 export interface BadgeProps
-  extends React.HTMLAttributes<HTMLDivElement>,
+  extends React.HTMLAttributes<HTMLSpanElement>,
     VariantProps<typeof badgeVariants> {}
 
+// A span (phrasing content), so badges stay valid inside buttons and links.
 function Badge({ className, variant, ...props }: BadgeProps) {
-  return <div className={cn(badgeVariants({ variant }), className)} {...props} />;
+  return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
 }
 
 export { Badge, badgeVariants };

apps/fastvideo_studio/src/components/ui/button.tsx

@@ -7,7 +7,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "@/lib/utils";
 
 const buttonVariants = cva(
-	"inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-xl border !text-sm !font-semibold transition-colors duration-150 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400/40 disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50",
+	"inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-xl border !text-sm !font-semibold transition-colors duration-150 disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50",
 	{
 		variants: {
 			variant: {
@@ -18,11 +18,11 @@ const buttonVariants = cva(
 				destructive: "border-rose-500/60 bg-rose-600/90 text-white hover:bg-rose-500",
 			},
 			size: {
-				default: "h-10 px-4 py-2",
-				sm: "h-9 rounded-lg px-3 !text-xs",
-				lg: "h-11 px-5 !text-sm",
-				icon: "size-10",
-				"icon-sm": "size-8",
+				default: "h-11 px-4 py-2",
+				sm: "h-11 rounded-lg px-3 !text-xs",
+				lg: "h-12 px-5 !text-sm",
+				icon: "size-11",
+				"icon-sm": "size-11",
 			},
 		},
 		defaultVariants: {

apps/fastvideo_studio/src/components/ui/dialog.tsx

@@ -42,7 +42,7 @@ const DialogContent = React.forwardRef<
       {...props}
     >
       {children}
-      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-lg p-1 text-muted-foreground opacity-70 transition-opacity hover:bg-secondary hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-sky-400/40 disabled:pointer-events-none">
+      <DialogPrimitive.Close className="absolute right-2 top-2 flex size-11 items-center justify-center rounded-lg text-muted-foreground opacity-70 transition-opacity hover:bg-secondary hover:opacity-100 disabled:pointer-events-none sm:right-4 sm:top-4">
         <X className="h-4 w-4" />
         <span className="sr-only">Close</span>
       </DialogPrimitive.Close>

apps/fastvideo_studio/src/components/ui/input.tsx

@@ -9,7 +9,7 @@ const Input = React.forwardRef<HTMLInputElement, React.ComponentProps<"input">>(
 		<input
 			type={type}
 			className={cn(
-				"flex h-10 w-full rounded-xl border border-input bg-card/60 px-3 py-2 text-sm text-foreground shadow-sm backdrop-blur-md transition-colors placeholder:text-muted-foreground focus-visible:border-sky-400/70 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400/25 disabled:cursor-not-allowed disabled:opacity-50",
+				"flex h-11 w-full rounded-xl border border-input bg-card/60 px-3 py-2 text-sm text-foreground shadow-sm backdrop-blur-md transition-colors placeholder:text-muted-foreground focus-visible:border-ring disabled:cursor-not-allowed disabled:opacity-50",
 				className,
 			)}
 			ref={ref}

apps/fastvideo_studio/src/components/ui/native-select.tsx

@@ -11,7 +11,7 @@ const NativeSelect = React.forwardRef<
   <select
     ref={ref}
     className={cn(
-      'flex h-10 w-full appearance-none rounded-xl border border-input bg-card px-3 py-2 text-sm text-foreground shadow-sm transition-colors focus-visible:border-sky-400/70 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400/25 disabled:cursor-not-allowed disabled:opacity-50',
+      'flex h-11 w-full appearance-none rounded-xl border border-input bg-card px-3 py-2 text-sm text-foreground shadow-sm transition-colors focus-visible:border-ring disabled:cursor-not-allowed disabled:opacity-50',
       className,
     )}
     {...props}

apps/fastvideo_studio/src/components/ui/select.tsx

@@ -17,7 +17,7 @@ const SelectTrigger = React.forwardRef<
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      'flex h-10 w-full items-center justify-between gap-2 rounded-xl border border-input bg-card px-3 py-2 text-sm text-foreground shadow-sm outline-none transition-colors placeholder:text-muted-foreground focus:border-sky-400/70 focus:ring-2 focus:ring-sky-400/25 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
+      'flex h-11 w-full items-center justify-between gap-2 rounded-xl border border-input bg-card px-3 py-2 text-sm text-foreground shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:border-ring disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1',
       className,
     )}
     {...props}
@@ -117,7 +117,7 @@ const SelectItem = React.forwardRef<
   <SelectPrimitive.Item
     ref={ref}
     className={cn(
-      'relative flex w-full cursor-default select-none items-center rounded-xl py-2 pl-8 pr-3 text-sm text-foreground outline-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground',
+      'relative flex min-h-11 w-full cursor-default select-none items-center rounded-xl py-2 pl-8 pr-3 text-sm text-foreground outline-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground',
       className,
     )}
     {...props}

apps/fastvideo_studio/src/components/ui/slider.tsx

@@ -8,21 +8,39 @@ import { cn } from '@/lib/utils';
 const Slider = React.forwardRef<
   React.ElementRef<typeof SliderPrimitive.Root>,
   React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>
->(({ className, ...props }, ref) => (
-  <SliderPrimitive.Root
-    ref={ref}
-    className={cn(
-      'relative flex w-full touch-none select-none items-center',
+>(
+  (
+    {
       className,
-    )}
-    {...props}
-  >
-    <SliderPrimitive.Track className="relative h-1.5 w-full grow overflow-hidden rounded-full bg-border">
-      <SliderPrimitive.Range className="absolute h-full bg-accent-blue" />
-    </SliderPrimitive.Track>
-    <SliderPrimitive.Thumb className="block h-4 w-4 rounded-full border-2 border-accent-blue bg-accent-blue shadow transition-colors hover:border-accent-blue/80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400/40 disabled:pointer-events-none disabled:opacity-50" />
-  </SliderPrimitive.Root>
-));
+      id,
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      'aria-describedby': ariaDescribedBy,
+      ...props
+    },
+    ref,
+  ) => (
+    <SliderPrimitive.Root
+      ref={ref}
+      className={cn(
+        'relative flex h-11 w-full touch-none select-none items-center',
+        className,
+      )}
+      {...props}
+    >
+      <SliderPrimitive.Track className="relative h-1.5 w-full grow overflow-hidden rounded-full bg-border">
+        <SliderPrimitive.Range className="absolute h-full bg-accent-blue" />
+      </SliderPrimitive.Track>
+      <SliderPrimitive.Thumb
+        id={id}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
+        className="relative block size-11 rounded-full bg-transparent after:absolute after:left-1/2 after:top-1/2 after:size-4 after:-translate-x-1/2 after:-translate-y-1/2 after:rounded-full after:border-2 after:border-accent-blue after:bg-accent-blue after:shadow after:content-[''] hover:after:border-accent-blue/80 disabled:pointer-events-none disabled:opacity-50"
+      />
+    </SliderPrimitive.Root>
+  ),
+);
 Slider.displayName = SliderPrimitive.Root.displayName;
 
 export { Slider };

apps/fastvideo_studio/src/components/ui/switch.tsx

@@ -12,14 +12,14 @@ const Switch = React.forwardRef<
   <SwitchPrimitives.Root
     ref={ref}
     className={cn(
-      'peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-border transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400/40 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-accent-blue data-[state=checked]:bg-accent-blue data-[state=unchecked]:bg-background',
+      'peer relative inline-flex size-11 shrink-0 cursor-pointer items-center justify-center rounded-xl bg-transparent transition-colors before:absolute before:h-5 before:w-9 before:rounded-full before:border before:border-border before:bg-background data-[state=checked]:before:border-accent-blue data-[state=checked]:before:bg-accent-blue disabled:cursor-not-allowed disabled:opacity-50',
       className,
     )}
     {...props}
   >
     <SwitchPrimitives.Thumb
       className={cn(
-        'pointer-events-none block h-3.5 w-3.5 rounded-full bg-muted-foreground shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-4 data-[state=checked]:bg-white data-[state=unchecked]:translate-x-0.5',
+        'pointer-events-none absolute left-1.5 top-[15px] z-[1] block h-3.5 w-3.5 rounded-full bg-muted-foreground shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-4 data-[state=checked]:bg-white',
       )}
     />
   </SwitchPrimitives.Root>

apps/fastvideo_studio/src/components/ui/tabs.tsx

@@ -29,7 +29,7 @@ const TabsTrigger = React.forwardRef<
   <TabsPrimitive.Trigger
     ref={ref}
     className={cn(
-      'inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400/40 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-card data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+      'inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium text-muted-foreground transition-colors hover:text-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-card data-[state=active]:text-foreground data-[state=active]:shadow-sm',
       className,
     )}
     {...props}

apps/fastvideo_studio/src/components/ui/textarea.tsx

@@ -8,7 +8,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, React.ComponentProps<"tex
 	return (
 		<textarea
 			className={cn(
-				"flex min-h-24 w-full resize-y rounded-xl border border-input bg-card px-3 py-2 text-sm text-foreground shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:border-sky-400/70 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sky-400/25 disabled:cursor-not-allowed disabled:opacity-50",
+				"flex min-h-24 w-full resize-y rounded-xl border border-input bg-card px-3 py-2 text-sm text-foreground shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:border-ring disabled:cursor-not-allowed disabled:opacity-50",
 				className,
 			)}
 			ref={ref}

apps/fastvideo_studio/src/hooks/useDrawerFocus.ts

@@ -0,0 +1,23 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Move focus into a drawer when it opens as a modal (mobile), and hand it
+ * back to the previously focused element on close. Pairs with `inert` on
+ * the background content — together they make `aria-modal` truthful.
+ */
+export function useDrawerFocus<T extends HTMLElement>(active: boolean) {
+  const ref = React.useRef<T | null>(null);
+
+  React.useEffect(() => {
+    if (!active) return;
+    const previous = document.activeElement;
+    ref.current?.focus();
+    return () => {
+      if (previous instanceof HTMLElement) previous.focus();
+    };
+  }, [active]);
+
+  return ref;
+}

apps/fastvideo_studio/src/hooks/useMediaQuery.ts

@@ -0,0 +1,18 @@
+'use client';
+
+import * as React from 'react';
+
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = React.useState(false);
+
+  React.useEffect(() => {
+    const mediaQuery = window.matchMedia(query);
+    const updateMatch = () => setMatches(mediaQuery.matches);
+
+    updateMatch();
+    mediaQuery.addEventListener('change', updateMatch);
+    return () => mediaQuery.removeEventListener('change', updateMatch);
+  }, [query]);
+
+  return matches;
+}

docker/Dockerfile

@@ -186,15 +186,40 @@ RUN --mount=type=cache,target=/opt/uv/cache \
 
 COPY . .
 
-# Install FastVideo Unified Kernel exactly once. build.sh initializes only its
-# CUTLASS/ThunderKittens submodules, then compiles for TORCH_CUDA_ARCH_LIST
-# (default Hopper sm_90a) without requiring a live GPU.
+# Build immutable FastVideo kernel wheels for the published image. The requested
+# architecture remains installed for normal image users; amd64 images also carry
+# an SM89 artifact so the predominant L40S Modal lanes can reuse it exactly.
+ARG FASTVIDEO_KERNEL_PREBUILT_DIR=/opt/fastvideo-kernel-prebuilt
 RUN --mount=type=cache,target=/opt/uv/cache \
     source $HOME/.local/bin/env && \
     source /opt/venv/bin/activate && \
+    default_arch="${TORCH_CUDA_ARCH_LIST}" && \
+    default_wheel_dir="${FASTVIDEO_KERNEL_PREBUILT_DIR}/${default_arch}" && \
+    export TORCH_CUDA_ARCH_LIST="${default_arch}" && \
     cd fastvideo-kernel && \
-    CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL} \
-    TORCH_CUDA_ARCH_LIST=${TORCH_CUDA_ARCH_LIST} ./build.sh
+    CMAKE_ARGS= CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL} \
+    ./build.sh --wheel-dir "${default_wheel_dir}" && \
+    cd /FastVideo && \
+    CMAKE_ARGS= python fastvideo/tests/modal/kernel_build_cache.py write-build-info \
+        --wheel-dir "${default_wheel_dir}" \
+        --output "${default_wheel_dir}/metadata.json" && \
+    if [[ "${TARGETARCH:-amd64}" == "amd64" && "${default_arch}" != "8.9" ]]; then \
+        export TORCH_CUDA_ARCH_LIST=8.9 && \
+        l40s_wheel_dir="${FASTVIDEO_KERNEL_PREBUILT_DIR}/8.9" && \
+        cd /FastVideo/fastvideo-kernel && \
+        CMAKE_ARGS= CMAKE_BUILD_PARALLEL_LEVEL=${CMAKE_BUILD_PARALLEL_LEVEL} \
+        ./build.sh --wheel-dir "${l40s_wheel_dir}" && \
+        cd /FastVideo && \
+        CMAKE_ARGS= python fastvideo/tests/modal/kernel_build_cache.py write-build-info \
+            --wheel-dir "${l40s_wheel_dir}" \
+            --output "${l40s_wheel_dir}/metadata.json"; \
+    fi && \
+    export TORCH_CUDA_ARCH_LIST="${default_arch}" && \
+    default_wheel="$(find "${default_wheel_dir}" -maxdepth 1 -type f \
+        \( -name 'fastvideo_kernel-*.whl' -o -name 'fastvideo-kernel-*.whl' \) \
+        | sort | tail -n 1)" && \
+    uv pip install "${default_wheel}" \
+        --reinstall-package fastvideo-kernel --no-deps
 
 # Install FastVideo itself (editable) now that the source is present, and set up
 # shell configuration. Dependencies and the local kernel are already installed,

docs/assets/cookbook-recipes.json

@@ -0,0 +1,52 @@
+{
+  "recipes": [
+    {
+      "id": "fastwan21-t2v",
+      "task": "Text to video",
+      "label": "FastWan2.1 1.3B (distilled + VSA)",
+      "model": "FastVideo/FastWan2.1-T2V-1.3B-Diffusers",
+      "source": "scripts/inference/inference_wan_VSA_DMD_1_3B.yaml",
+      "command": "FASTVIDEO_ATTENTION_BACKEND=VIDEO_SPARSE_ATTN fastvideo generate --config scripts/inference/inference_wan_VSA_DMD_1_3B.yaml"
+    },
+    {
+      "id": "wan22-t2v",
+      "task": "Text to video",
+      "label": "Wan2.2 A14B",
+      "model": "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
+      "source": "examples/inference/basic/basic_wan2_2.py",
+      "command": "python examples/inference/basic/basic_wan2_2.py"
+    },
+    {
+      "id": "wan21-i2v",
+      "task": "Image to video",
+      "label": "Wan2.1 14B 480P",
+      "model": "Wan-AI/Wan2.1-I2V-14B-480P-Diffusers",
+      "source": "scripts/inference/inference_wan_i2v.yaml",
+      "command": "fastvideo generate --config scripts/inference/inference_wan_i2v.yaml"
+    },
+    {
+      "id": "turbowan22-i2v",
+      "task": "Image to video",
+      "label": "TurboWan2.2 A14B",
+      "model": "loayrashid/TurboWan2.2-I2V-A14B-Diffusers",
+      "source": "examples/inference/basic/basic_turbodiffusion_i2v.py",
+      "command": "python examples/inference/basic/basic_turbodiffusion_i2v.py"
+    },
+    {
+      "id": "wan22-ti2v",
+      "task": "Text or image to video",
+      "label": "Wan2.2 TI2V 5B",
+      "model": "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
+      "source": "examples/inference/basic/basic_wan2_2_ti2v.py",
+      "command": "python examples/inference/basic/basic_wan2_2_ti2v.py"
+    },
+    {
+      "id": "matrix-game-2",
+      "task": "Interactive world",
+      "label": "Matrix Game 2.0",
+      "model": "FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers",
+      "source": "examples/inference/basic/basic_matrixgame2.py",
+      "command": "python examples/inference/basic/basic_matrixgame2.py"
+    }
+  ]
+}

docs/assets/cookbook.js

@@ -0,0 +1,60 @@
+(() => {
+  let recipesPromise;
+
+  const loadRecipes = (url) => {
+    recipesPromise ||= fetch(url).then((response) => {
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      return response.json();
+    });
+    return recipesPromise;
+  };
+
+  const init = () => {
+    document.querySelectorAll("[data-cookbook]").forEach(async (root) => {
+      if (root.dataset.initialized) return;
+      root.dataset.initialized = "true";
+
+      const select = root.querySelector("[data-cookbook-recipe]");
+      const model = root.querySelector("[data-cookbook-model]");
+      const source = root.querySelector("[data-cookbook-source]");
+      const command = root.querySelector("[data-cookbook-command]");
+      const status = root.querySelector("[data-cookbook-status]");
+
+      try {
+        const { recipes } = await loadRecipes(root.dataset.recipes);
+        const byId = new Map(recipes.map((recipe) => [recipe.id, recipe]));
+        const groups = new Map();
+
+        select.replaceChildren();
+        recipes.forEach((recipe) => {
+          if (!groups.has(recipe.task)) {
+            const group = document.createElement("optgroup");
+            group.label = recipe.task;
+            groups.set(recipe.task, group);
+            select.append(group);
+          }
+          groups.get(recipe.task).append(new Option(recipe.label, recipe.id));
+        });
+
+        const render = () => {
+          const recipe = byId.get(select.value);
+          model.textContent = recipe.model;
+          source.textContent = recipe.source;
+          source.href = `https://github.com/hao-ai-lab/FastVideo/blob/main/${recipe.source}`;
+          command.textContent = recipe.command;
+          status.textContent = `${recipe.label} selected.`;
+        };
+
+        select.addEventListener("change", render);
+        select.disabled = false;
+        render();
+      } catch (error) {
+        status.textContent = "Recipes could not be loaded. Use the examples link below.";
+        console.error("Failed to load FastVideo cookbook recipes", error);
+      }
+    });
+  };
+
+  if (window.document$) window.document$.subscribe(init);
+  else document.addEventListener("DOMContentLoaded", init);
+})();

docs/assets/custom.css

@@ -42,6 +42,46 @@ img {
     margin: 0 auto;
 }
 
+.cookbook-picker {
+    padding: 1rem;
+    border: 0.05rem solid var(--md-default-fg-color--lightest);
+    border-radius: 0.2rem;
+}
+
+.cookbook-picker select {
+    width: 100%;
+    padding: 0.6rem;
+    color: var(--md-default-fg-color);
+    background: var(--md-default-bg-color);
+    border: 0.05rem solid var(--md-default-fg-color--lighter);
+    border-radius: 0.2rem;
+}
+
+.cookbook-picker dl {
+    display: grid;
+    grid-template-columns: max-content 1fr;
+    gap: 0.25rem 1rem;
+}
+
+.cookbook-picker dt {
+    font-weight: 700;
+}
+
+.cookbook-picker dd {
+    margin: 0;
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+
+.cookbook-picker__status {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+}
+
 .md-typeset .copy-page-button.md-button {
     float: right;
     margin: 0 0 1rem 1rem;

docs/contributing/ci_architecture.md

@@ -269,16 +269,26 @@ The docs job:
 ### Docker Images
 
 `.github/workflows/infra-build-image.yml` supports manual `workflow_dispatch`
-runs and automatically rebuilds the CUDA matrix when `docker/Dockerfile`
-changes on `main` in the canonical repository. Manual runs let maintainers
-choose which image families to build. The `fastvideo-dev` matrix builds Python
-3.12 images for CUDA 12.6 and CUDA 13 on native `amd64` and `arm64` runners,
-then publishes one multi-platform manifest per CUDA version. CUDA 12.6 owns the
-`py3.12-latest` and global `latest` tags, as well as the explicit
-`py3.12-cuda12.6.3-latest` alias. CUDA 13 is published under the explicit
-`py3.12-cuda13.0.0-latest` tag. This publication policy does not change the
-unparameterized `docker/Dockerfile` build defaults, which remain CUDA 13 and
-`cu130`.
+runs and automatically rebuilds the CUDA matrix when a repository-controlled
+image input changes on `main` in the canonical repository. Those inputs include
+the CUDA Dockerfile and reusable workflow, dependency metadata, Docker context
+policy, `fastvideo-kernel/**`, and the kernel artifact metadata/key helper.
+Manual runs let maintainers choose which image families to build. The
+`fastvideo-dev` matrix builds Python 3.12 images for CUDA 12.6 and CUDA 13 on
+native `amd64` and `arm64` runners, then publishes one multi-platform manifest
+per CUDA version. CUDA 12.6 owns the `py3.12-latest` and global `latest` tags, as
+well as the explicit `py3.12-cuda12.6.3-latest` alias. CUDA 13 is published under
+the explicit `py3.12-cuda13.0.0-latest` tag. This publication policy does not
+change the unparameterized `docker/Dockerfile` build defaults, which remain CUDA
+13 and `cu130`.
+
+Published amd64 development images keep their configured Hopper kernel wheel
+installed and also carry an immutable SM89 wheel under
+`/opt/fastvideo-kernel-prebuilt`. Modal PR and SSIM jobs select the exact
+source, ABI, and GPU-architecture match from that directory, so L40S jobs reuse
+the trusted image artifact while kernel-changing PRs still build locally. Once
+a kernel or artifact-key change reaches `main`, the image workflow republishes
+the matching trusted artifact before later jobs consume the updated image tag.
 
 The optional Dreamverse matrix builds backend and UI images for CUDA 12.6 and
 CUDA 13 on `amd64`. Dreamverse remains `amd64`-only because its FA4 dependency

docs/cookbook/index.md

@@ -0,0 +1,44 @@
+# Inference Cookbook
+
+Choose a complete recipe maintained in the FastVideo repository. Each command
+runs its checked-in source directly, so coupled model, GPU, offload, and
+attention settings do not drift into unsupported combinations.
+
+The commands expect a local clone:
+
+```bash
+git clone https://github.com/hao-ai-lab/FastVideo.git
+cd FastVideo
+```
+
+<div class="cookbook-picker" data-cookbook data-recipes="../assets/cookbook-recipes.json">
+  <label for="cookbook-recipe"><strong>Recipe</strong></label>
+  <select id="cookbook-recipe" data-cookbook-recipe disabled>
+    <option>Loading recipes…</option>
+  </select>
+  <dl>
+    <dt>Model</dt>
+    <dd data-cookbook-model>Loading…</dd>
+    <dt>Source</dt>
+    <dd><a data-cookbook-source href="../inference/examples/basic/">Browse maintained examples</a></dd>
+  </dl>
+  <pre><code class="language-bash" data-cookbook-command>Loading…</code></pre>
+  <p class="cookbook-picker__status" role="status" aria-live="polite" data-cookbook-status></p>
+  <noscript>
+    JavaScript is needed for the recipe picker. Browse the
+    <a href="../inference/examples/examples_inference_index/">inference examples</a>
+    instead.
+  </noscript>
+</div>
+
+## Customize a recipe
+
+Start from the checked-in source, then change only the settings your model
+supports:
+
+- [Configuration](../inference/configuration.md) covers the Python and CLI
+  config surfaces.
+- [Optimizations](../inference/optimizations.md) covers attention backends,
+  compilation, and memory tradeoffs.
+- [Support matrix](../inference/support_matrix.md) lists supported models and
+  optimizations.

docs/design/inference_schema_parity_inventory.yaml

@@ -76,6 +76,7 @@ surfaces:
       lora_target_modules: "Legacy LoRA configuration surface pending dedicated component API."
       output_type: "Legacy output formatting surface pending GenerationResult cleanup."
       VSA_sparsity: "Model-specific inference optimization not yet represented in the typed public schema."
+      attention_backend: "Process-wide default attention-backend request applied per component at load time; kernel-selection knob not yet represented in the typed public schema."
       moba_config_path: "Model-specific MoBA optimization surface not yet represented in the typed public schema."
       master_port: "Executor/bootstrap compatibility field; not part of the canonical inference schema."
       refine_transformer_path: "Generic stage-2 refine transformer override; no typed equivalent yet."
@@ -444,7 +445,11 @@ surfaces:
     moved:
       image_path: request.inputs.image_path
       pil_image: request.inputs.pil_image
+      last_image: request.inputs.last_image
+      references: request.inputs.references
       video_path: request.inputs.video_path
+      latents: request.inputs.latents
+      audio_latents: request.inputs.audio_latents
       mouse_cond: request.inputs.mouse_cond
       keyboard_cond: request.inputs.keyboard_cond
       grid_sizes: request.inputs.grid_sizes
@@ -524,7 +529,6 @@ surfaces:
       inpaint_mask: request.extensions.stable_audio.inpaint_mask
     internal_only:
       data_type: "Derived from the request shape and not a public input."
-      latents: "Pre-generated diffusion latents supplied by parity/debug harnesses; not a public input."
 
   sampling_param_extensions: {}
 

docs/generate_examples.py

@@ -2,6 +2,7 @@
 # adapted from vllm: https://github.com/vllm-project/vllm/blob/v0.7.3/docs/source/generate_examples.py
 
 import itertools
+import json
 import os
 import re
 from dataclasses import dataclass, field
@@ -19,6 +20,40 @@ GENERATED_DOC_PREFIXES = (
     "training/examples/",
     "distillation/examples/",
 )
+COOKBOOK_DATA = ROOT_DIR / "docs/assets/cookbook-recipes.json"
+COOKBOOK_SOURCE_ROOTS = (
+    ROOT_DIR / "examples/inference",
+    ROOT_DIR / "scripts/inference",
+)
+
+
+def validate_cookbook() -> None:
+    """Keep cookbook entries tied to checked-in runnable sources."""
+    recipes = json.loads(COOKBOOK_DATA.read_text(encoding="utf-8")).get("recipes")
+    if not isinstance(recipes, list) or not recipes:
+        raise ValueError(f"{COOKBOOK_DATA}: recipes must be a non-empty list")
+
+    seen: set[str] = set()
+    for recipe in recipes:
+        required = ("id", "task", "label", "model", "source", "command")
+        missing = {key for key in required if not recipe.get(key)}
+        if missing:
+            raise ValueError(f"Cookbook recipe is missing: {', '.join(sorted(missing))}")
+        if recipe["id"] in seen:
+            raise ValueError(f"Duplicate cookbook recipe id: {recipe['id']}")
+        seen.add(recipe["id"])
+
+        source = (ROOT_DIR / recipe["source"]).resolve()
+        if not any(source.is_relative_to(root.resolve()) for root in COOKBOOK_SOURCE_ROOTS):
+            raise ValueError(f"Cookbook source is outside an approved directory: {recipe['source']}")
+        if not source.is_file():
+            raise ValueError(f"Cookbook source does not exist: {recipe['source']}")
+
+        source_text = source.read_text(encoding="utf-8")
+        if recipe["model"] not in source_text:
+            raise ValueError(f"Cookbook model is not present in {recipe['source']}: {recipe['model']}")
+        if recipe["source"] not in recipe["command"]:
+            raise ValueError(f"Cookbook command does not invoke its source: {recipe['id']}")
 
 
 def fix_case(text: str) -> str:
@@ -536,6 +571,7 @@ def on_pre_build(config, **kwargs):
     MkDocs hook to generate examples before building the documentation.
     This function is called automatically by MkDocs' native hook system.
     """
+    validate_cookbook()
     print("Generating example documentation...")
     generate_examples(generate_main_index=True)
     print("Example documentation generated successfully!")
@@ -549,6 +585,7 @@ def on_page_context(context, page, **kwargs):
 
 
 if __name__ == "__main__":
+    validate_cookbook()
     print("Generating example documentation...")
     generate_examples(generate_main_index=True)
     print("Example documentation generated successfully!")

docs/getting_started/installation.md

@@ -5,6 +5,7 @@ FastVideo supports the following hardware platforms:
 
 - [NVIDIA CUDA](installation/gpu.md)
 - [NVIDIA DGX Spark / GB10 (ARM64 + CUDA 13)](installation/spark.md)
+  ([performance & tuning](installation/spark_performance.md))
 - [Apple silicon](installation/mps.md)
 
 ## Quick Installation
@@ -54,14 +55,17 @@ UV_TORCH_BACKEND=cu126 uv pip install -e .
 uv pip install flash-attn --no-build-isolation -v
 ```
 
-## Hardware Requirements
+## Requirements
 
+- **Python**: 3.10-3.12 is the tested and recommended range (the commands
+  above pin 3.12)
 - **NVIDIA GPUs**: CUDA 12.6+ with compute capability 7.0+
 - **Apple Silicon**: macOS 14.0+ with M1/M2/M3/M4 chips
 - **CPU**: x86_64 architecture (for CPU-only inference)
 
 ## Next Steps
 
-- [Quick Start Guide](quick_start.md) - Get started with your first video generation
+- [Quick Start](quick_start.md) - Generate your first video
+- [Inference Cookbook](../cookbook/index.md) - Choose a maintained recipe
 - [Configuration](../inference/configuration.md) - Learn about configuration options
-- [Examples](../inference/examples/examples_inference_index.md) - Explore example scripts and notebooks
+- [Examples](../inference/examples/examples_inference_index.md) - Explore scripts and notebooks

docs/getting_started/installation/gpu.md

@@ -134,4 +134,4 @@ If you're planning to contribute to FastVideo please see the following page:
 
 If you encounter any issues during installation, please open an issue on our [GitHub repository](https://github.com/hao-ai-lab/FastVideo).
 
-You can also join our [Slack community](https://join.slack.com/t/fastvideo/shared_invite/zt-38u6p1jqe-yDI1QJOCEnbtkLoaI5bjZQ) for additional support.
+You can also join our [Slack community](https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ) for additional support.

docs/getting_started/installation/mps.md

@@ -100,4 +100,4 @@ If you're planning to contribute to FastVideo please see the following page:
 
 If you encounter any issues during installation, please open an issue on our [GitHub repository](https://github.com/hao-ai-lab/FastVideo).
 
-You can also join our [Slack community](https://join.slack.com/t/fastvideo/shared_invite/zt-38u6p1jqe-yDI1QJOCEnbtkLoaI5bjZQ) for additional support.
+You can also join our [Slack community](https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ) for additional support.

docs/getting_started/installation/spark.md

@@ -134,9 +134,16 @@ uv pip install "https://github.com/mjun0812/flash-attention-prebuild-wheels/rele
 
 If you hit other issues, please open an issue on our
 [GitHub repository](https://github.com/hao-ai-lab/FastVideo). You can also join
-our [Slack community](https://join.slack.com/t/fastvideo/shared_invite/zt-38u6p1jqe-yDI1QJOCEnbtkLoaI5bjZQ)
+our [Slack community](https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ)
 for additional support.
 
+## Next: performance & tuning
+
+Installed and verified? See [DGX Spark: Performance & Tuning](spark_performance.md)
+for which models are practical on the GB10, what makes them faster, and what
+won't help on this hardware (and why) — so you don't spend a night tuning knobs
+that can't move here.
+
 ## Development Environment Setup
 
 If you're planning to contribute to FastVideo please see the

docs/getting_started/installation/spark_performance.md

@@ -0,0 +1,195 @@
+# DGX Spark (GB10): Performance & Tuning
+
+You have FastVideo [installed on a DGX Spark](spark.md) — this page is what to
+run next. It covers **which models are practical on the GB10, what actually
+makes them faster, and what won't help (and why)**, so you don't burn a night
+tuning knobs that can't move on this hardware.
+
+!!! tip "TL;DR"
+    - **Use distilled few-step models** (e.g. `FastVideo/FastWan2.1-T2V-1.3B-Diffusers`).
+      They run in ~40 s/video. Full-step models are 12–47 min on the GB10.
+    - On few-step models, **VAE decode is the bottleneck**, not attention — it's
+      bandwidth-bound on the Spark's unified memory.
+    - **bf16 VAE decode** is the real, lossless lever (FastVideo already turns it
+      on for Wan). **FlashAttention, linear quantization, and `torch.compile` of
+      the VAE give little or nothing here** — see the table below.
+    - Heavy runs can make the box unreachable — run generations with VAE tiling on
+      and `nice -n 19`. See [Running safely](#running-safely-dont-lock-the-box).
+
+## The hardware reality (this explains everything below)
+
+The GB10 pairs a Blackwell GPU (`sm_121`) with **128 GB of unified LPDDR5X memory
+(~270 GB/s) shared between CPU and GPU**. That bandwidth is roughly **10× below a
+datacenter GPU's HBM**. Two consequences drive every tuning decision:
+
+1. **Memory-bandwidth-bound stages hurt disproportionately.** VAE decode moves a
+   lot of data and becomes the dominant cost on short (few-step) generations.
+2. **Compute-bound stages scale with step count.** Full-step diffusion (50+
+   steps) is denoise-bound and simply takes a long time here.
+
+## Use distilled few-step models
+
+The single biggest lever on the GB10 is **model choice**. A 3-step distilled
+model is ~18× faster than the full-step version of the same architecture:
+
+| Model | Steps | Time / video | Bottleneck |
+|---|---|---|---|
+| FastWan2.1-T2V-1.3B (distilled) | 3 | **~40 s** | VAE decode |
+| Wan2.1-T2V-1.3B (full-step) | 50 | ~12 min | denoise |
+| Cosmos-Predict2.5-2B (full-step) | 51 | ~47 min | denoise |
+| LTX2.3-distilled (+audio) | 8 | ~6 min | mixed |
+
+The bottleneck flips from decode to denoise at around **4 steps**. Below that,
+you're paying mostly for VAE decode; above it, mostly for the denoising loop.
+
+!!! note "Few-step timings are noisy — measure in-process"
+    On a 3-step run, one-time per-process startup (Triton autotune, allocator
+    warmup) dominates and never amortizes, so single-run totals wobble ~±30%.
+    Compare levers **back-to-back in one process or as medians**, never as two
+    separate single runs. The [reproduction script](#reproduce-these-numbers)
+    does this for you.
+
+## bf16 VAE decode — the real lever (already on for Wan)
+
+Because few-step generation is decode-bound, VAE decode precision is where the
+time is. Decoding in **bf16 instead of fp32 is essentially lossless** (MS-SSIM
+~0.9999 vs fp32 on the identical latent) and ~1.14× faster — worth roughly
+5–7% end-to-end on a decode-bound few-step model.
+
+**FastVideo already defaults Wan's decode to bf16** (`vae_decode_precision="bf16"`,
+with encode kept at fp32), so for the recommended Wan/FastWan models there's
+nothing to set. If you run a model that still defaults to an fp32 decode, set the
+decode-only override yourself:
+
+```python
+from fastvideo.configs.pipelines.base import PipelineConfig
+
+pipeline_config = PipelineConfig.from_pretrained(model_id)
+pipeline_config.vae_decode_precision = "bf16"   # decode-only; leaves encode precision alone
+```
+
+Decode is output-only, so lowering its precision is safe. (Encode seeds the
+denoising trajectory for I2V/causal models, so that stays at the pipeline's
+default — don't lower `vae_precision` blindly for those.)
+
+## Memory: one unified 128 GB pool
+
+The GB10 has **no separate VRAM** — CPU and GPU share one 128 GB LPDDR5X pool
+(~118 GB usable). Two practical consequences:
+
+- **`nvidia-smi` reports memory as `[N/A]`** on the GB10, and the system "used"
+  figure conflates CPU + GPU + cache, so it's only a soft upper bound — treat the
+  whole 128 GB as one shared budget. For a per-run figure, use FastVideo's own
+  `peak_memory_mb` (reported on the generation result and by the performance
+  benchmark), which is measured inside the worker that runs the model.
+- **The 128 GB is a *working-set* ceiling, not storage** — the model cache lives
+  on the NVMe (3.7 TB, ample). What has to fit in 128 GB is the weights,
+  activations, and KV cache — and, critically, the **VAE decode buffers**, which
+  is why tiling matters
+  (an untiled high-res decode can spike the pool into swap and lock the box).
+
+The recommended few-step models are comfortable here: their weights are small
+(1.3–2 B) and few-step generation keeps activations modest — a Wan2.1-1.3B
+few-step generation peaks at **~8.4 GB** (measured), a small fraction of the pool.
+The pressure comes from **decode resolution/frames**, not the model — a
+1080p×121-frame untiled decode is what pushes the pool toward its ceiling, which
+is why VAE tiling stays
+on by default.
+
+## What helps vs. what doesn't on the GB10
+
+The honest summary — most "obvious" GPU optimizations don't move the needle on
+this hardware, for reasons specific to it:
+
+| Lever | Effect on the GB10 | Use it? |
+|---|---|---|
+| Distilled few-step model | ~18× vs full-step | ✅ **the primary lever** |
+| bf16 VAE decode | ~1.14×, lossless; ~5–7% e2e on few-step | ✅ default for Wan |
+| VSA (video sparse attention) | works out of the box (Triton kernel auto-selects on `sm_121`) | ✅ automatic |
+| Building FlashAttention | **no speedup** — Torch SDPA already hits an efficient flash kernel on `sm_121`, and FA2 ties it | ❌ not worth building |
+| `torch.compile` of the VAE decode | recompile storm (per-frame varying shapes) → ~1.1× | ❌ dead end |
+| Linear (fp8 / nvfp4) quantization on long-sequence models (e.g. Cosmos) | ~nothing — see below | ❌ wrong lever here |
+| FP4 attention (`ATTN_QAT_INFER`) | works on `sm_121` (runtime allowlist landed in #1647; kernel build is #1598); helps, but needs a QAT-trained checkpoint | ⚠️ opt-in — see below |
+| FP4 linear on short-sequence models (LTX2) | up to −24% denoise at 1080p (#1594) | ⚠️ model/resolution-dependent |
+
+### Why linear quantization is the wrong lever on long-sequence models
+
+Quantizing the linear (GEMM) layers is a natural first instinct, but on a
+long-sequence video model it buys almost nothing on the GB10. A video-DiT denoise
+step is dominated by **O(N²) attention** at these sequence lengths (tens of
+thousands of tokens); the linear layers are a small single-digit fraction of the
+work. Quantizing them faster leaves the attention-bound total essentially
+unchanged — measured at ~1% on Cosmos-2.5, i.e. noise, and full-step CFG models
+also lose quality to per-step quantization error.
+
+The same mechanism **does** help on **short-sequence** models: LTX2's aggressive
+VAE compression gives it short attention sequences, so FP4 linear reaches −24%
+there (#1594). The rule: **on the GB10, the lever that matters is attention
+(sparse or FP4), not the linear layers** — unless the model has short sequences.
+
+### FP4 on the GB10 (opt-in)
+
+Block-scaled FP4 works on `sm_121` under CUDA 13:
+
+- **FP4 attention** (`FASTVIDEO_ATTENTION_BACKEND=ATTN_QAT_INFER`, #1598) is
+  numerically correct on the GB10 and ~6% faster end-to-end generation, but it only preserves
+  quality on a **quantization-aware-distilled checkpoint** (e.g.
+  `FastVideo/FastWan-QAD-1.3B`) — stock weights aren't trained to tolerate it.
+- **FP4 linear** helps only where sequences are short (LTX2, above).
+
+The [`qad_fp4_ab.py`](#reproduce-these-numbers) harness reproduces the FP4
+attention A/B on the QAD checkpoint.
+
+## Running safely (don't lock the box)
+
+The GB10 is easy to make **unreachable** — a heavy build or an untiled high-res
+decode starves the ~20 ARM cores and unified memory, `sshd` can't get cycles, and
+you're locked out at *"Connection timed out during banner exchange"* until the box
+is power-cycled. To avoid it:
+
+- **Inference:** keep **VAE tiling on** (the default), use sane resolution/frames,
+  and run under `nice -n 19`:
+
+  ```bash
+  nice -n 19 nohup python your_script.py > run.log 2>&1 &
+  ```
+
+- **Builds** (flash-attn, kernel): `nice -n 19`, `MAX_JOBS=2`, `nohup`. Never a
+  bare foreground high-parallelism build.
+- Leave `*_cpu_offload` at the example defaults — "CPU" offload is the *same*
+  unified RAM on the GB10, so the win is tiling + sane resolution, not offloading.
+
+## Gotchas specific to the GB10
+
+A few things that surprise people on this box (beyond the memory notes above):
+
+- **Don't force `TORCH_SDPA` on a VSA checkpoint** (FastWan, LTX2.3-distilled).
+  The SDPA path builds a model without the gate weights the checkpoint carries and
+  fails to load. Run the model natively — VSA auto-routes to its Triton kernel on
+  `sm_121`.
+- **Few-step timings are noisy run-to-run** (~±30%) — one-time startup dominates a
+  3-step run. Compare in-process / as medians, never two separate single runs (the
+  benchmark script does this).
+- **`nvidia-smi` shows `[N/A]` for memory** — see [Memory](#memory-one-unified-128-gb-pool).
+- **Cosmos-2.5** uses a Qwen2.5-VL text encoder; make sure you're on a FastVideo
+  build recent enough to include its `transformers`-compatibility handling before
+  running it.
+
+## Reproduce these numbers
+
+Two scripts under `examples/inference/optimizations/` reproduce the claims on
+your own GB10:
+
+```bash
+# Headline: few-step generation timing (median) + the bf16-vs-fp32 decode A/B.
+# FASTVIDEO_STAGE_LOGGING=1 also prints the denoise / decode / text split.
+FASTVIDEO_STAGE_LOGGING=1 nice -n 19 \
+    python examples/inference/optimizations/spark_benchmark.py
+
+# FP4 attention quality/speed A/B on the QAD checkpoint (one arm per run).
+QAD_LINEAR=0 FASTVIDEO_ATTENTION_BACKEND=ATTN_QAT_INFER nice -n 19 \
+    python examples/inference/optimizations/qad_fp4_ab.py
+```
+
+See also the [Optimizations](../../inference/optimizations.md) reference for the
+full list of attention backends and quantization options.

docs/getting_started/quick_start.md

@@ -23,61 +23,21 @@ Also optionally install flash-attn:
 uv pip install flash-attn --no-build-isolation -v
 ```
 
-## Basic Usage
+## Choose a maintained recipe
 
-### Text-to-Video Generation
+The cookbook selects complete, checked-in recipes instead of mixing model,
+parallelism, offload, and attention settings independently.
 
-```python
-from fastvideo import VideoGenerator
+[Open the inference cookbook](../cookbook/index.md){ .md-button .md-button--primary }
 
-def main():
-    # Create a video generator with a pre-trained model
-    generator = VideoGenerator.from_pretrained(
-        "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
-        num_gpus=1,  # Adjust based on your hardware
-    )
-
-    # Define a prompt for your video
-    prompt = "A curious raccoon peers through a vibrant field of yellow sunflowers, its eyes wide with interest."
-
-    # Generate the video
-    video = generator.generate_video(
-        prompt,
-        output_path="my_videos/",  # Controls where videos are saved
-        save_video=True
-    )
-
-if __name__ == '__main__':
-    main()
-```
-
-### Image-to-Video Generation
-
-```python
-from fastvideo import VideoGenerator, SamplingParam
-
-def main():
-    # Create the generator
-    model_name = "Wan-AI/Wan2.1-I2V-14B-480P-Diffusers"
-    generator = VideoGenerator.from_pretrained(model_name, num_gpus=1)
-
-    # Set up parameters with an initial image
-    sampling_param = SamplingParam.from_pretrained(model_name)
-    sampling_param.image_path = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
-    sampling_param.num_frames = 107
-
-    # Generate video based on the image
-    prompt = "A photograph coming to life with gentle movement"
-    generator.generate_video(prompt, sampling_param=sampling_param,
-                             output_path="my_videos/",
-                             save_video=True)
-
-if __name__ == '__main__':
-    main()
-```
+!!! tip "Need more control?"
+    Start from a maintained recipe, then use the
+    [configuration](../inference/configuration.md) and
+    [optimization](../inference/optimizations.md) guides for supported changes.
 
 ## Next Steps
 
+- [Inference Cookbook](../cookbook/index.md) - Choose a maintained recipe
 - [Installation Guide](installation.md) - Detailed installation instructions
 - [Configuration](../inference/configuration.md) - Learn about configuration options
 - [Examples](../inference/examples/examples_inference_index.md) - Explore more

docs/index.md

@@ -5,7 +5,7 @@
 </div>
 
 <div style="text-align: center;">
-<strong>FastVideo is a unified inference and post-training framework for accelerated video generation.</strong>
+<strong>FastVideo is a unified post-training and real-time inference framework for accelerated video generation.</strong>
 </div>
 
 <div style="text-align: center;">
@@ -25,14 +25,23 @@ FastVideo is an inference and post-training framework for diffusion models. It f
 
 FastVideo has the following features:
 
+- End-to-end post-training support for bidirectional and autoregressive models
+  - Full finetuning and LoRA [finetuning](training/finetune.md) for state-of-the-art open video DiTs
+  - [Data preprocessing pipeline](training/data_preprocess.md) for video, image, and text data
+  - [Distribution Matching Distillation (DMD2)](distillation/dmd.md) stepwise distillation
+  - Sparse attention with [Video Sparse Attention](attention/vsa/index.md)
+  - [Sparse distillation](https://hao-ai-lab.github.io/blogs/fastvideo_post_training/) to achieve >50x denoising speedup
+  - [Attn-QAT training](training/attn_qat.md) for quantization-aware post-training
+  - Causal distillation through Self-Forcing
+  - Scalable training with FSDP2, sequence parallelism, and selective activation checkpointing
+  - See the [training overview](training/overview.md) for the full training workflow
 - State-of-the-art performance optimizations for inference
-  - [Sliding Tile Attention](attention/sta/index.md)
-  - [Sage Attention](https://arxiv.org/abs/2410.02367)
-- E2E post-training support
-  - Data preprocessing pipeline for video data
-  - [Sparse distillation](https://hao-ai-lab.github.io/blogs/fastvideo_post_training/) for Wan2.1 and Wan2.2 using [Video Sparse Attention](https://arxiv.org/pdf/2505.13389) and [Distribution Matching Distillation](https://tianweiy.github.io/dmd2/)
-  - Support full finetuning and LoRA finetuning for state-of-the-art open video DiTs.
-  - Scalable training with FSDP2, sequence parallelism, and selective activation checkpointing, with near linear scaling to 64 GPUs.
+  - Sequence parallelism for distributed inference
+  - Multiple state-of-the-art [attention backends](attention/index.md)
+  - User-friendly [CLI](inference/cli.md) and Python API
+  - See the [support matrix](inference/support_matrix.md) for supported models and [optimizations](inference/optimizations.md) for the full list
+- Realtime video generation and editing
+  - [Dreamverse](https://github.com/hao-ai-lab/FastVideo/tree/main/apps/dreamverse): stream and "vibe direct" video in realtime ([live demo](https://dreamverse.fastvideo.org/))
 
 ## Documentation
 

docs/inference/add_pipeline.md

@@ -11,7 +11,7 @@ This guide explains how to implement a custom diffusion pipeline in FastVideo, l
 4. **Register Your Pipeline** - Make it discoverable by the framework
 5. **Configure Your Pipeline** - (Coming soon)
 
-Need help? Join our [Slack community](https://join.slack.com/t/fastvideo/shared_invite/zt-38u6p1jqe-yDI1QJOCEnbtkLoaI5bjZQ).
+Need help? Join our [Slack community](https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ).
 
 ## Step 1: Pipeline Modules
 

docs/inference/inference_quick_start.md

@@ -4,10 +4,11 @@ This page contains step-by-step instructions to get you quickly started with vid
 
 ## Requirements
 
-- **OS**: Linux (Tested on Ubuntu 22.04+)
+- **OS**: Linux (tested on Ubuntu 22.04+), or macOS on Apple silicon via the
+  [MPS installation guide](../getting_started/installation/mps.md)
 - **Python**: 3.10-3.12
-- **CUDA**: 12.6 or 13.0
-- **GPU**: At least one NVIDIA GPU
+- **CUDA**: 12.6 or 13.0 (NVIDIA GPUs)
+- **GPU**: At least one NVIDIA GPU, or an Apple silicon chip with MPS
 
 ## Installation
 
@@ -134,5 +135,4 @@ If the generated video doesn't match your prompt:
 - Learn about [Advanced Inference Configurations](configuration.md)
 - Learn about using [Optimizations](optimizations.md)
 - See [Examples](examples/examples_inference_index.md) for more usage scenarios
-- Join our [Community Discord](https://discord.gg/JA7cksDz86).
-- Join our [Community Slack](https://join.slack.com/t/fastvideo/shared_invite/zt-38u6p1jqe-yDI1QJOCEnbtkLoaI5bjZQ).
+- Join our [Community Slack](https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ).

docs/inference/optimizations.md

@@ -3,6 +3,12 @@
 
 This page describes the various options for speeding up generation times in FastVideo.
 
+!!! note "On a DGX Spark (GB10)?"
+    Several options on this page behave differently on the GB10's unified-memory
+    hardware — some give little or nothing there. See
+    [DGX Spark: Performance & Tuning](../getting_started/installation/spark_performance.md)
+    for what actually helps on that platform and why.
+
 ## Table of Contents
 
 - Optimized Attention Backends
@@ -119,6 +125,22 @@ pip install "nvidia-cutlass-dsl>=4.5.2" apache-tvm-ffi flashinfer-python
 The `--no-deps` flag prevents upgrading torch/torchvision. Use the supported
 PyTorch 2.12.0 and CUDA 13 environment for this kernel.
 
+Branch-to-`nvidia-cutlass-dsl` compatibility (the fork tracks the CuTe DSL API
+surface closely):
+
+| fork branch | cutlass-dsl | notes |
+|---|---|---|
+| `fp4` | `==4.4.2` (+ `nvidia-cutlass-dsl-libs-base==4.4.2`) | validated set on GB200: `quack-kernels==0.4.1`, `flashinfer-python==0.6.8`, `CUTE_DSL_ENABLE_TVM_FFI=1`, `FASTVIDEO_FA4=1` |
+| `fix/cutlass-dsl-4.5` | `>=4.5.2` | carries the `cute.core.ThrMma` -> `cute.ThrMma` fix |
+| any | 4.6-era | unsupported: `cute.make_fragment` was removed at module level; fails at CuTe JIT trace |
+
+`FASTVIDEO_FA4=1` is required alongside the fork: it ships no compiled
+FlashAttention-2, so dense attention paths raise ImportError without the FA4
+opt-in. The same kernel also serves `ATTN_QAT_INFER` on sm_100a/sm_103a
+(datacenter Blackwell) — the selection log's receipt line
+(`ATTN_QAT_INFER resolved: ...`) records the arch, kernel, and quantization
+mode that actually bound.
+
 #### Usage
 
 Enable FP4 attention via the `--nvfp4_fa4` flag:

docs/inference/support_matrix.md

@@ -13,6 +13,97 @@ For the canonical, code-level list of model IDs recognized by
     We do this because we believe VSA is strictly better than STA for the
     actively maintained `main` inference path.
 
+## Registered Model IDs
+
+Every Hugging Face model ID registered in `fastvideo/registry.py` on `main`
+(commit `8d89f30d`), grouped by family. Any ID below can
+be passed to `VideoGenerator.from_pretrained(...)`; FastVideo resolves the
+matching pipeline and sampling defaults. The **Family** column is a
+documentation grouping: it follows each registration's declared `model_family`,
+except `black-forest-labs/FLUX.1-dev`, which declares none and is listed under
+`flux` for readability. The **Workloads** column shows each
+registration's declared `workload_types`; `—` means the entry is registered
+without a UI workload option but is still loadable by ID. The **Example**
+column links a runnable script in `examples/inference/basic/` where one exists.
+
+| Family | HuggingFace Model ID | Workloads | Example |
+|--------|----------------------|-----------|---------|
+| cosmos | `nvidia/Cosmos-Predict2-2B-Video2World` | T2V | — |
+| cosmos25 | `KyleShao/Cosmos-Predict2.5-2B-Diffusers` | T2V | [basic_cosmos2_5_t2w.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_cosmos2_5_t2w.py) |
+| cosmos25 | `nvidia/Cosmos-Predict2.5-14B` | T2V | [basic_cosmos2_5_t2w.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_cosmos2_5_t2w.py) |
+| dreamx_world | `FastVideo/DreamX-World-5B-Cam-Diffusers` | I2V | [basic_dreamx_world.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_dreamx_world.py) |
+| dreamx_world | `FastVideo/DreamX-World-5B-Diffusers` | I2V | [basic_dreamx_world.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_dreamx_world.py) |
+| flux | `black-forest-labs/FLUX.1-dev` | T2I | [basic_flux_dev.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_flux_dev.py) |
+| flux2 | `black-forest-labs/FLUX.2-klein-4B`<br>`black-forest-labs/FLUX.2-klein-9B` | T2I | [basic_flux2_klein.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_flux2_klein.py) |
+| flux2 | `black-forest-labs/FLUX.2-dev` | T2I | [basic_flux2.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_flux2.py) |
+| gamecraft | `FastVideo/HunyuanGameCraft-Diffusers` | I2V | [basic_gamecraft.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_gamecraft.py) |
+| gen3c | `FastVideo/GEN3C-Cosmos-7B-Diffusers` | T2V | [basic_gen3c.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_gen3c.py) |
+| glm_image | `zai-org/GLM-Image` | T2I | [basic_glm_image.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_glm_image.py) |
+| hunyuan | `hunyuanvideo-community/HunyuanVideo` | T2V | — |
+| hunyuan | `FastVideo/FastHunyuan-diffusers` | T2V | — |
+| hunyuan15 | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v` | T2V | [basic_hy15.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_hy15.py) |
+| hunyuan15 | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_i2v_step_distilled` | I2V | [basic_hy15.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_hy15.py) |
+| hunyuan15 | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v` | T2V | [basic_hy15.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_hy15.py) |
+| hunyuan15 | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_i2v_distilled` | I2V | [basic_hy15.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_hy15.py) |
+| hunyuan15 | `weizhou03/HunyuanVideo-1.5-Diffusers-1080p`<br>`weizhou03/HunyuanVideo-1.5-Diffusers-1080p-2SR` | — | [basic_hy15_1080p.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_hy15_1080p.py) |
+| hyworld | `FastVideo/HY-WorldPlay-Bidirectional-Diffusers` | — | [basic_hyworld.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_hyworld.py) |
+| kandinsky5 | `kandinskylab/Kandinsky-5.0-T2V-Lite-sft-5s-Diffusers` | T2V | [basic_kandinsky5_t2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_kandinsky5_t2v.py) |
+| kandinsky5 | `kandinskylab/Kandinsky-5.0-T2V-Pro-sft-5s-Diffusers` | T2V | [basic_kandinsky5_t2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_kandinsky5_t2v.py) |
+| kandinsky5 | `kandinskylab/Kandinsky-5.0-T2V-Lite-distilled16steps-5s-Diffusers` | T2V | [basic_kandinsky5_t2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_kandinsky5_t2v.py) |
+| kandinsky5 | `kandinskylab/Kandinsky-5.0-T2V-Pro-distilled-5s-Diffusers` | T2V | [basic_kandinsky5_t2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_kandinsky5_t2v.py) |
+| kandinsky5 | `kandinskylab/Kandinsky-5.0-I2V-Lite-5s-Diffusers` | I2V | [basic_kandinsky5_i2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_kandinsky5_i2v.py) |
+| kandinsky5 | `kandinskylab/Kandinsky-5.0-I2V-Pro-sft-5s-Diffusers` | I2V | [basic_kandinsky5_i2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_kandinsky5_i2v.py) |
+| kandinsky5 | `kandinskylab/Kandinsky-5.0-I2V-Pro-distilled-5s-Diffusers` | I2V | [basic_kandinsky5_i2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_kandinsky5_i2v.py) |
+| lingbot_video | `FastVideo/LingBot-Video-MoE-30B-A3B-Diffusers` | T2V | [basic_lingbot_video.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_lingbot_video.py) |
+| lingbot_video | `FastVideo/LingBot-Video-Dense-1.3B-Diffusers` | T2V | [basic_lingbot_video.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_lingbot_video.py) |
+| lingbotworld | `FastVideo/LingBot-World-Base-Cam-Diffusers` | I2V | [basic_lingbotworld_base_cam.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_lingbotworld_base_cam.py) |
+| lingbotworld2 | `robbyant/lingbot-world-v2-14b-causal-fast` | I2V | [basic_lingbotworld2_causal_fast.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_lingbotworld2_causal_fast.py) |
+| longcat | `FastVideo/LongCat-Video-T2V-Diffusers` | T2V | [basic_longcat_t2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_longcat_t2v.py) |
+| longcat | `FastVideo/LongCat-Video-I2V-Diffusers` | I2V | [basic_longcat_i2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_longcat_i2v.py) |
+| longcat | `FastVideo/LongCat-Video-VC-Diffusers` | — | [basic_longcat_vc.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_longcat_vc.py) |
+| ltx2 | `FastVideo/LTX2-Distilled-Diffusers`<br>`FastVideo/LTX2.3-Distilled-Diffusers`<br>`FastVideo/LTX-2.3-Distilled-Diffusers` | T2V | [basic_ltx2_distilled.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_ltx2_distilled.py) |
+| ltx2 | `Lightricks/LTX-2.3`<br>`FastVideo/LTX2.3-base`<br>`FastVideo/LTX2.3-Diffusers` | T2V | [basic_ltx2.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_ltx2.py) |
+| ltx2 | `Lightricks/LTX-2`<br>`FastVideo/LTX2-base`<br>`FastVideo/LTX2-Diffusers` | T2V | [basic_ltx2.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_ltx2.py) |
+| matrixgame | `FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers`<br>`FastVideo/Matrix-Game-2.0-GTA-Distilled-Diffusers`<br>`FastVideo/Matrix-Game-2.0-TempleRun-Distilled-Diffusers`<br>`FastVideo/Matrix-Game-2.0-Base-Diffusers`<br>`FastVideo/Matrix-Game-2.0-GTA-Diffusers`<br>`FastVideo/Matrix-Game-2.0-TempleRun-Diffusers`<br>`mignonjia/mg_longtuning_distilled_zelda`<br>`mignonjia/mg_sf_distilled_zelda_1k_steps`<br>`mignonjia/mg_sf_distilled_zelda`<br>`mignonjia/mg_causal_zelda`<br>`mignonjia/mg_bidirectional_zelda` | I2V | [basic_matrixgame2.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_matrixgame2.py) |
+| matrixgame | `FastVideo/Matrix-Game-3.0-Base-Distilled-Diffusers` | I2V | [basic_matrixgame3.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_matrixgame3.py) |
+| minimax_h3 | `MiniMaxAI/MiniMax-H3` | T2V, I2V | [T2VA](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_minimax_h3_t2v.py)<br>[FL2VA](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_minimax_h3_fl2va.py)<br>[Ref2VA](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_minimax_h3_ref2va.py) |
+| sd35 | `stabilityai/stable-diffusion-3.5-medium` | T2I | [basic_sd35_t2i.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_sd35_t2i.py) |
+| stable_audio | `FastVideo/stable-audio-open-1.0-Diffusers` | T2V | [basic_stable_audio.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_stable_audio.py) |
+| stable_audio | `FastVideo/stable-audio-open-small-Diffusers` | T2V | [basic_stable_audio_small.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_stable_audio_small.py) |
+| turbodiffusion | `loayrashid/TurboWan2.1-T2V-1.3B-Diffusers` | T2V | [basic_turbodiffusion.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_turbodiffusion.py) |
+| turbodiffusion | `loayrashid/TurboWan2.1-T2V-14B-Diffusers` | T2V | [basic_turbodiffusion_14b.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_turbodiffusion_14b.py) |
+| turbodiffusion | `loayrashid/TurboWan2.2-I2V-A14B-Diffusers` | I2V | [basic_turbodiffusion_i2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_turbodiffusion_i2v.py) |
+| wan | `Wan-AI/Wan2.1-T2V-1.3B-Diffusers` | T2V | [basic.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic.py) |
+| wan | `Wan-AI/Wan2.1-T2V-14B-Diffusers`<br>`FastVideo/Wan2.1-VSA-T2V-14B-720P-Diffusers` | T2V | — |
+| wan | `Wan-AI/Wan2.1-I2V-14B-480P-Diffusers` | I2V | — |
+| wan | `Wan-AI/Wan2.1-I2V-14B-720P-Diffusers` | I2V | — |
+| wan | `weizhou03/Wan2.1-Fun-1.3B-InP-Diffusers` | I2V | — |
+| wan | `IRMChen/Wan2.1-Fun-1.3B-Control-Diffusers` | — | [basic_wan2_2_Fun.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_wan2_2_Fun.py) |
+| wan | `FastVideo/FastWan2.1-T2V-1.3B-Diffusers`<br>`FastVideo/FastWan2.1-T2V-14B-480P-Diffusers` | T2V | [basic_dmd.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_dmd.py) |
+| wan | `Wan-AI/Wan2.2-TI2V-5B-Diffusers` | T2V, I2V | [basic_wan2_2_ti2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_wan2_2_ti2v.py) |
+| wan | `FastVideo/FastWan2.2-TI2V-5B-FullAttn-Diffusers`<br>`FastVideo/FastWan2.2-TI2V-5B-Diffusers` | T2V, I2V | [basic_dmd.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_dmd.py) |
+| wan | `decart-ai/Lucy-Edit-Dev`<br>`decart-ai/Lucy-Edit-1.1-Dev` | — | [basic_lucy_edit.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_lucy_edit.py) |
+| wan | `Wan-AI/Wan2.2-T2V-A14B-Diffusers` | T2V | [basic_wan2_2.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_wan2_2.py) |
+| wan | `Wan-AI/Wan2.2-I2V-A14B-Diffusers` | I2V | [basic_wan2_2_i2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_wan2_2_i2v.py) |
+| wan | `wlsaidhi/SFWan2.1-T2V-1.3B-Diffusers` | T2V | [basic_self_forcing_causal.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_self_forcing_causal.py) |
+| wan | `rand0nmr/SFWan2.2-T2V-A14B-Diffusers` | T2V | [basic_self_forcing_causal_wan2_2_t2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_self_forcing_causal_wan2_2_t2v.py) |
+| wan | `FastVideo/SFWan2.2-I2V-A14B-Preview-Diffusers` | I2V | [basic_self_forcing_causal_wan2_2_i2v.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_self_forcing_causal_wan2_2_i2v.py) |
+| zimage | `Tongyi-MAI/Z-Image-Turbo` | T2I | [basic_zimage.py](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_zimage.py) |
+
+**Note (stable_audio)**: the Stable Audio Open pipelines generate audio
+(`StableAudioT2AConfig` / `StableAudioOpenSmallConfig`); they are registered
+under the generic T2V workload option in the registry.
+
+**Note (MiniMax H3)**: T2VA, FL2VA, and Ref2VA all generate video with stereo
+audio. Use the Ref2VA example when passing ordered image, video, or audio
+references.
+
+**Note (Wan-VACE)**: not currently supported — no VACE pipeline or registered
+model ID exists on `main`
+([#1435](https://github.com/hao-ai-lab/FastVideo/issues/1435)). The closest
+supported path is the Wan2.1-Fun control pipeline
+(`IRMChen/Wan2.1-Fun-1.3B-Control-Diffusers`).
+
 The symbols used have the following meanings:
 
 - ✅ = Full compatibility
@@ -25,6 +116,9 @@ The `HuggingFace Model ID` can be passed directly to
 `from_pretrained()`. FastVideo then uses model-specific default settings for
 pipeline initialization and sampling.
 
+Registered models absent from this table have not been validated against these
+optimizations: absence means **untested**, not incompatible.
+
 <style>
   /* Target tables in this section */
   #models-x-optimization + p + table {
@@ -56,7 +150,7 @@ pipeline initialization and sampling.
 | Model Name | HuggingFace Model ID | Resolutions | TeaCache | Sliding Tile Attn (Legacy Branch) | Sage Attn | VSA | BSA |
 |------------|---------------------|-------------|----------|-------------------|-----------|-----|-----|
 | FastWan2.1 T2V 1.3B | `FastVideo/FastWan2.1-T2V-1.3B-Diffusers` | 480P | ⭕ | ⭕ | ⭕ | ✅ | ⭕ |
-| FastWan2.2 TI2V 5B Full Attn* | `FastVideo/FastWan2.2-TI2V-5B-FullAttn-Diffusers` | 720P | ⭕ | ⭕ | ⭕ | ✅ | ⭕ |
+| FastWan2.2 TI2V 5B Full Attn | `FastVideo/FastWan2.2-TI2V-5B-FullAttn-Diffusers` | 720P | ⭕ | ⭕ | ⭕ | ✅ | ⭕ |
 | Wan2.2 TI2V 5B | `Wan-AI/Wan2.2-TI2V-5B-Diffusers` | 720P | ⭕ | ⭕ | ✅ | ⭕ | ⭕ |
 | DreamX-World 5B Cam | `FastVideo/DreamX-World-5B-Cam-Diffusers` | 480P | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
 | DreamX-World 5B AR | `FastVideo/DreamX-World-5B-Diffusers` | 704px1280p | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
@@ -65,14 +159,14 @@ pipeline initialization and sampling.
 | Wan2.2 I2V A14B | `Wan-AI/Wan2.2-I2V-A14B-Diffusers` | 480P<br>720P | ❌ | ❌ | ✅ | ⭕ | ⭕ |
 | HunyuanVideo | `hunyuanvideo-community/HunyuanVideo` | 720px1280p<br>544px960p | ❌ | ✅ | ✅ | ⭕ | ⭕ |
 | FastHunyuan | `FastVideo/FastHunyuan-diffusers` | 720px1280p<br>544px960p | ❌ | ✅ | ✅ | ⭕ | ⭕ |
-| Wan2.1 T2V 1.3B | `Wan-AI/Wan2.1-T2V-1.3B-Diffusers` | 480P | ✅ | ✅* | ✅ | ⭕ | ⭕ |
-| Wan2.1 T2V 14B | `Wan-AI/Wan2.1-T2V-14B-Diffusers` | 480P, 720P | ✅ | ✅* | ✅ | ⭕ | ⭕ |
-| Wan2.1 I2V 480P | `Wan-AI/Wan2.1-I2V-14B-480P-Diffusers` | 480P | ✅ | ✅* | ✅ | ⭕ | ⭕ |
+| Wan2.1 T2V 1.3B | `Wan-AI/Wan2.1-T2V-1.3B-Diffusers` | 480P | ✅ | ✅ | ✅ | ⭕ | ⭕ |
+| Wan2.1 T2V 14B | `Wan-AI/Wan2.1-T2V-14B-Diffusers` | 480P, 720P | ✅ | ✅ | ✅ | ⭕ | ⭕ |
+| Wan2.1 I2V 480P | `Wan-AI/Wan2.1-I2V-14B-480P-Diffusers` | 480P | ✅ | ✅ | ✅ | ⭕ | ⭕ |
 | Wan2.1 I2V 720P | `Wan-AI/Wan2.1-I2V-14B-720P-Diffusers` | 720P | ✅ | ✅ | ✅ | ⭕ | ⭕ |
 | TurboWan2.1 T2V 1.3B | `loayrashid/TurboWan2.1-T2V-1.3B-Diffusers` | 480P | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
 | TurboWan2.1 T2V 14B | `loayrashid/TurboWan2.1-T2V-14B-Diffusers` | 480P, 720P | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
 | TurboWan2.2 I2V A14B | `loayrashid/TurboWan2.2-I2V-A14B-Diffusers` | 480P<br>720P | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
-| LongCat T2V 13.6B | See note** | 480P<br>720P | ❌ | ❌ | ❌ | ⭕ | ✅ |
+| LongCat T2V 13.6B | `FastVideo/LongCat-Video-T2V-Diffusers` | 480P<br>720P | ❌ | ❌ | ❌ | ⭕ | ✅ |
 | Matrix Game 2.0 Base Distilled | `FastVideo/Matrix-Game-2.0-Base-Distilled-Diffusers` | 352x640 | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
 | Matrix Game 2.0 GTA Distilled | `FastVideo/Matrix-Game-2.0-GTA-Distilled-Diffusers` | 352x640 | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
 | Matrix Game 2.0 TempleRun Distilled | `FastVideo/Matrix-Game-2.0-TempleRun-Distilled-Diffusers` | 352x640 | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ |
@@ -98,6 +192,21 @@ resolve default pipeline and sampling configuration for it.
 `FastVideo/GEN3C-Cosmos-7B-Diffusers`) or convert locally with
 `scripts/checkpoint_conversion/convert_gen3c_to_fastvideo.py`.
 
+## Hardware and OS
+
+Per the installation guides:
+
+- **NVIDIA GPU (x86_64)** — CUDA 12.6 or 13.0; see the
+  [GPU install guide](../getting_started/installation/gpu.md).
+- **NVIDIA DGX Spark (GB10, aarch64)** — CUDA 13, from-source kernel build; see
+  the [DGX Spark install guide](../getting_started/installation/spark.md).
+- **Apple silicon (MPS)** — macOS 14 or newer; see the
+  [MPS install guide](../getting_started/installation/mps.md) and
+  [`basic_mps.py`](https://github.com/hao-ai-lab/FastVideo/blob/main/examples/inference/basic/basic_mps.py).
+
+Optimization-specific hardware constraints (e.g. STA requiring Hopper) are
+listed under [Special requirements](#special-requirements).
+
 ## Special requirements
 
 ### Sliding Tile Attention

docs/training/attn_qat.md

@@ -49,7 +49,7 @@ configuration reference.
 Download the published preprocessed dataset:
 
 ```bash
-bash examples/training/finetune/wan_t2v_1.3B/mixkit/download_mixkit_data.sh
+bash examples/datasets/mixkit/download_dataset.sh
 ```
 
 ## Stage 1: supervised Attn-QAT fine-tuning

docs/training/finetune.md

@@ -182,7 +182,7 @@ Ready-to-run training scripts are available for multiple models:
 
 Each example includes:
 
-- `download_dataset.sh` — download sample data
+- a README pointing at the matching download script under `examples/datasets/`
 - `preprocess_*.sh` — run preprocessing
 - `finetune_*.sh` — full finetune launcher
 - `finetune_*_lora.sh` — LoRA finetune launcher

docs/training/overview.md

@@ -48,7 +48,7 @@ For the complete two-stage Wan2.1 MixKit quantization-aware workflow, see
 
 Each example includes:
 
-- `download_dataset.sh` — download sample data
+- a README pointing at the matching download script under `examples/datasets/`
 - `preprocess_*.sh` — run preprocessing
 - `finetune_*.sh` — launch training (full finetune or LoRA)
 - `validation.json` — validation prompts for checkpoints

docs/training/train_infra.md

@@ -212,6 +212,29 @@ pipeline:
   flow_shift: 8
 ```
 
+Registered transformer linear-quantization configs can also be selected by
+name. For example, the LTX-2 NVFP4-QAT recipe applies real FP4 forward GEMMs
+with a straight-through-estimator backward to its deployment-targeted
+attention/FFN projections:
+
+```yaml
+pipeline:
+  dit_config:
+    quant_config: nvfp4_qat_train
+```
+
+The LTX-2 recipe in
+`examples/train/configs/overfit_ltx2_t2v_nvfp4_qat.yaml` combines that linear
+configuration with `models.student.attention_backend: ATTN_QAT_TRAIN` for
+video-attention forward/backward. On sm120, its validation callback temporarily
+switches those layers to `ATTN_QAT_INFER`.
+On GB200, set `callbacks.validation.attn_qat_infer: false` to keep validation on
+the train-time QAT backend; the inference kernel is sm120-only.
+
+User-adaptable LTX-2 fine-tuning recipes (full, LoRA, and NVFP4 QAT) live in
+`examples/train/configs/fine_tuning/ltx2/`, alongside the other model
+families under `examples/train/configs/fine_tuning/`.
+
 ---
 
 ## Training Methods

docs/utilities/debugging.md

@@ -77,7 +77,9 @@ If forcing a backend fails, verify optional dependencies are installed:
 - `SAGE_ATTN`: SageAttention package
 - `SAGE_ATTN_THREE`: upstream `sageattn3` package
 - `ATTN_QAT_INFER`: `fastvideo-kernel` checkout/source install that exposes
-  `attn_qat_infer`
+  `attn_qat_infer`, AND a consumer-Blackwell (sm_120/sm_121) GPU -- on any
+  other device the backend reports unavailable (even if a CUDA 13 wheel
+  bundles the extension) and selection falls back to FlashAttention
 - `ATTN_QAT_TRAIN`: `fastvideo-kernel`; its runtime-JIT Triton implementation
   selects an optimized route on SM100, joins the quantized and STE P@V paths on
   SM120, and retains the previous route for unsupported configurations. See

examples/datasets/mixkit/download_dataset.sh

@@ -3,10 +3,11 @@
 #
 # This is the MixKit subset already VAE-encoded (Wan2.1-T2V-1.3B) and text-embedded
 # into Parquet shards, so it can be fed straight to training with no further
-# preprocessing. To build the Parquet from raw videos yourself, see README.md.
+# preprocessing. To build the Parquet from raw videos yourself, see
+# examples/training/finetune/wan_t2v_1.3B/mixkit/README.md.
 #
 # Usage (run from the repo root):
-#   bash examples/training/finetune/wan_t2v_1.3B/mixkit/download_mixkit_data.sh [DATA_ROOT]
+#   bash examples/datasets/mixkit/download_dataset.sh [DATA_ROOT]
 set -euo pipefail
 
 DATA_ROOT=${1:-data/HD-Mixkit-Finetune-Wan}

examples/datasets/wan-syn/download_dataset_480p.sh

@@ -1,3 +1,3 @@
 #!/bin/bash
-mkdir -p data
+# Wan-Syn 480P dataset (77x448x832, 600k clips).
 python scripts/huggingface/download_hf.py --repo_id "FastVideo/Wan-Syn_77x448x832_600k" --local_dir "data/Wan-Syn_77x448x832_600k" --repo_type "dataset"

examples/datasets/wan-syn/download_dataset_720p.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+# Wan-Syn 720P dataset (77x768x1280, 250k clips).
+python scripts/huggingface/download_hf.py --repo_id "FastVideo/Wan-Syn_77x768x1280_250k" --local_dir "data/Wan-Syn_77x768x1280_250k" --repo_type "dataset"

examples/distill/SFWan2.1-T2V/README.md

@@ -5,7 +5,7 @@ These scripts demonstrate self-forcing distillation (SFwan) for the causal Wan2.
 ## Run the recipe
 1. Download the preprocessed text-video dataset:
    ```bash
-   bash examples/distill/SFWan2.1-T2V/download_dataset.sh
+   bash examples/datasets/crush-smol/download_dataset.sh
    ```
 2. (Optional) Regenerate parquet shards locally:
    ```bash

examples/distill/SFWan2.1-T2V/download_dataset.sh

@@ -1,3 +0,0 @@
-#!/bin/bash
-
-python scripts/huggingface/download_hf.py --repo_id "wlsaidhi/crush-smol-merged" --local_dir "data/crush-smol" --repo_type "dataset"

examples/distill/Wan2.1-T2V/Wan-Syn-Data-480P/README.md

@@ -9,7 +9,7 @@ uv pip install vsa
 
 ### 1. Download dataset:
 ```bash
-bash examples/distill/Wan2.1-T2V/Wan-Syn-Data-480P/download_dataset.sh
+bash examples/datasets/wan-syn/download_dataset_480p.sh
 ```
 
 ### 2. Configure and run distillation:

examples/distill/Wan2.2-TI2V-5B-Diffusers/crush_smol/README.md

@@ -9,7 +9,7 @@ uv pip install vsa
 
 ### 1. Download dataset:
 ```bash
-bash examples/distill/Wan2.2-TI2V-5B-Diffusers/crush_smol/download_dataset.sh
+bash examples/datasets/crush-smol/download_dataset.sh
 ```
 
 ### 2. Configure and run distillation:

examples/distill/Wan2.2-TI2V-5B-Diffusers/crush_smol/download_dataset.sh

@@ -1,3 +0,0 @@
-#!/bin/bash
-
-python scripts/huggingface/download_hf.py --repo_id "wlsaidhi/crush-smol-merged" --local_dir "data/crush-smol" --repo_type "dataset"

examples/inference/basic/basic_ltx2_distilled_fast_profile.py

@@ -191,6 +191,22 @@ def main() -> None:
     print(f"Using refine upsampler: {refine_upsampler_path}")
 
     pipeline_config = PipelineConfig.from_pretrained(model_root)
+    # LTX-2 NVFP4 deploy contract (train==deploy surface):
+    #   * Linears: NVFP4 block-scaled GEMMs (per-16 E2M1 + E4M3 SFs) on every
+    #     arch, via flashinfer.
+    #   * ATTN_QAT_INFER attention differs per arch: sm_120a/sm_121a use the
+    #     fastvideo-kernel CUTLASS (SageAttention3-FP4) scheme that
+    #     ATTN_QAT_TRAIN simulates; sm_100a (GB200) / sm_103a (GB300) use the
+    #     FP4 FA4 kernel (flash-attention-fp4) with per-16 block-scaled NVFP4
+    #     Q/K and BF16 P/V -- a train-sim mismatch that is gated by MS-SSIM
+    #     measurement, not assumed equal. The selection receipt is logged at
+    #     backend resolution ("ATTN_QAT_INFER resolved: ...").
+    # Original-weight retention: the default purges the always-FP4 layers'
+    # bf16 originals after conversion. Refine-only layers (the cross-modal
+    # AV projections) always keep theirs: the base stage profile runs them
+    # dense by deployment contract -- in the two-stage fast profile AND the
+    # distilled single-stage deploy. retain_original_weights=True keeps
+    # everything (debugging).
     pipeline_config.dit_config.quant_config = NVFP4Config()
     OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
     torch_compile_kwargs = {

examples/inference/basic/basic_minimax_h3_fl2va.py

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Generate synchronized video/audio from a first frame with MiniMax H3."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from PIL import Image
+
+from fastvideo import VideoGenerator
+from fastvideo.api import (
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    InputConfig,
+    OffloadConfig,
+    OutputConfig,
+    ParallelismConfig,
+    SamplingConfig,
+)
+from fastvideo.pipelines.basic.minimax_h3.packing import resolve_canvas_size
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--model-path", default="MiniMaxAI/MiniMax-H3")
+    parser.add_argument("--image", required=True, help="First-frame image path.")
+    parser.add_argument("--last-image", help="Optional last-frame image path.")
+    parser.add_argument("--output", default="outputs/minimax_h3_fl2va")
+    parser.add_argument("--prompt", required=True)
+    parser.add_argument("--num-frames", type=int, default=192, help="192 frames is exactly 8 seconds at 24 fps.")
+    parser.add_argument("--steps", type=int, default=50)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--num-gpus", type=int, default=4)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    first_image = Image.open(args.image).convert("RGB")
+    last_image = Image.open(args.last_image).convert("RGB") if args.last_image else None
+    height, width = resolve_canvas_size(*first_image.size)
+    output_dir = Path(args.output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=args.model_path,
+            engine=EngineConfig(
+                num_gpus=args.num_gpus,
+                use_fsdp_inference=args.num_gpus > 1,
+                parallelism=ParallelismConfig(tp_size=1, sp_size=args.num_gpus),
+                offload=OffloadConfig(
+                    dit=False,
+                    dit_layerwise=False,
+                    text_encoder=True,
+                    vae=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+        ))
+    try:
+        result = generator.generate(
+            GenerationRequest(
+                prompt=args.prompt,
+                negative_prompt="",
+                inputs=InputConfig(pil_image=first_image, last_image=last_image),
+                sampling=SamplingConfig(
+                    height=height,
+                    width=width,
+                    num_frames=args.num_frames,
+                    fps=24,
+                    num_inference_steps=args.steps,
+                    guidance_scale=1.0,
+                    batch_cfg=False,
+                    seed=args.seed,
+                ),
+                output=OutputConfig(
+                    output_path=str(output_dir / "minimax_h3_fl2va.mp4"),
+                    save_video=True,
+                    return_frames=False,
+                ),
+            ))
+        print(f"Output written to: {result.video_path}")
+    finally:
+        generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_minimax_h3_ref2va.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Generate synchronized video/audio from ordered references with MiniMax H3."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from fastvideo import VideoGenerator
+from fastvideo.api import (
+    ComponentConfig,
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    InputConfig,
+    OffloadConfig,
+    OutputConfig,
+    ParallelismConfig,
+    PipelineSelection,
+    SamplingConfig,
+)
+from fastvideo.pipelines.basic.minimax_h3 import MiniMaxH3Reference
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--model-path", default="MiniMaxAI/MiniMax-H3")
+    parser.add_argument("--reference-video", required=True)
+    parser.add_argument("--reference-audio", help="Optional additional audio reference.")
+    parser.add_argument("--output", default="outputs/minimax_h3_ref2va")
+    parser.add_argument("--prompt", required=True)
+    parser.add_argument("--height", type=int, default=768)
+    parser.add_argument("--width", type=int, default=1344)
+    parser.add_argument("--num-frames", type=int, default=124)
+    parser.add_argument("--steps", type=int, default=50)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--num-gpus", type=int, default=4)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    references = [MiniMaxH3Reference(source=args.reference_video, media_type="video")]
+    if args.reference_audio:
+        references.append(MiniMaxH3Reference(source=args.reference_audio, media_type="audio"))
+    output_dir = Path(args.output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=args.model_path,
+            engine=EngineConfig(
+                num_gpus=args.num_gpus,
+                use_fsdp_inference=args.num_gpus > 1,
+                parallelism=ParallelismConfig(tp_size=1, sp_size=args.num_gpus),
+                offload=OffloadConfig(
+                    dit=False,
+                    dit_layerwise=False,
+                    text_encoder=True,
+                    vae=True,
+                    pin_cpu_memory=False,
+                ),
+            ),
+            pipeline=PipelineSelection(
+                workload_type="i2v",
+                components=ComponentConfig(override_pipeline_cls_name="MiniMaxH3Ref2VAModularPipeline"),
+            ),
+        ))
+    try:
+        result = generator.generate(
+            GenerationRequest(
+                prompt=args.prompt,
+                negative_prompt="",
+                inputs=InputConfig(references=references),
+                sampling=SamplingConfig(
+                    height=args.height,
+                    width=args.width,
+                    num_frames=args.num_frames,
+                    fps=24,
+                    num_inference_steps=args.steps,
+                    guidance_scale=1.0,
+                    batch_cfg=False,
+                    seed=args.seed,
+                ),
+                output=OutputConfig(
+                    output_path=str(output_dir / "minimax_h3_ref2va.mp4"),
+                    save_video=True,
+                    return_frames=False,
+                ),
+            ))
+        print(f"Output written to: {result.video_path}")
+    finally:
+        generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_minimax_h3_t2v.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Generate video and audio from text with MiniMax H3."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from fastvideo import VideoGenerator
+from fastvideo.api import (
+    CompileConfig,
+    EngineConfig,
+    GenerationRequest,
+    GeneratorConfig,
+    OffloadConfig,
+    OutputConfig,
+    ParallelismConfig,
+    SamplingConfig,
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--model-path", default="MiniMaxAI/MiniMax-H3")
+    parser.add_argument("--prompt", required=True)
+    parser.add_argument("--output", default="outputs/minimax_h3_t2v")
+    parser.add_argument("--height", type=int, default=768)
+    parser.add_argument("--width", type=int, default=1344)
+    parser.add_argument("--num-frames", type=int, default=124)
+    parser.add_argument("--steps", type=int, default=50)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--num-gpus", type=int, default=4)
+    parser.add_argument("--torch-compile", action="store_true",
+                        help="torch.compile the DiT transformer path")
+    parser.add_argument("--compile-mode", default=None,
+                        help='torch.compile mode, e.g. "reduce-overhead" for CUDA graphs')
+    parser.add_argument("--repeats", type=int, default=1,
+                        help="generate N times; with --torch-compile the first run pays "
+                             "compilation, so steady-state is the last repeat")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    output_dir = Path(args.output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    generator = VideoGenerator.from_config(
+        GeneratorConfig(
+            model_path=args.model_path,
+            engine=EngineConfig(
+                num_gpus=args.num_gpus,
+                use_fsdp_inference=args.num_gpus > 1,
+                parallelism=ParallelismConfig(tp_size=1, sp_size=args.num_gpus),
+                offload=OffloadConfig(
+                    dit=False,
+                    dit_layerwise=False,
+                    text_encoder=True,
+                    vae=True,
+                    pin_cpu_memory=False,
+                ),
+                compile=CompileConfig(
+                    enabled=args.torch_compile,
+                    mode=args.compile_mode,
+                ),
+            ),
+        ))
+    try:
+        request = GenerationRequest(
+                prompt=args.prompt,
+                negative_prompt="",
+                sampling=SamplingConfig(
+                    height=args.height,
+                    width=args.width,
+                    num_frames=args.num_frames,
+                    fps=24,
+                    num_inference_steps=args.steps,
+                    guidance_scale=1.0,
+                    batch_cfg=False,
+                    seed=args.seed,
+                ),
+                output=OutputConfig(
+                    output_path=str(output_dir / "minimax_h3_t2v.mp4"),
+                    save_video=True,
+                    return_frames=False,
+                ),
+            )
+        result = generator.generate(request)
+        print(f"Output written to: {result.video_path}")
+        if result.generation_time is not None:
+            # machine-readable: benchmark harnesses parse this line to separate
+            # generation from model-load time (last occurrence = steady state)
+            print(f"Generation time: {result.generation_time:.2f}s")
+        for _ in range(args.repeats - 1):
+            result = generator.generate(request)
+            if result.generation_time is not None:
+                print(f"Generation time: {result.generation_time:.2f}s")
+    finally:
+        generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/gradio/local/gradio_local_demo_ltx2_3/README.md

@@ -6,10 +6,6 @@ original single-file version to make each concern independently reviewable.
 The folder name matches the sibling `gradio_local_demo*.py` demos in this
 directory so both flat and packaged demos read consistently.
 
-> **Status: draft.** This package is structurally in place but will not run
-> against the current upstream `fastvideo` package. See *Blocking prereqs*
-> below.
-
 ## Layout
 
 | File | Purpose |
@@ -38,27 +34,21 @@ python -m gradio_local_demo_ltx2_3 --port 7860
 GPU requirement: a single FP4-capable GPU (B200 or comparable) for the
 "real-time 1080p" speed claim. Lower tiers will still run but slower.
 
-## Blocking prereqs (why this draft PR cannot be merged yet)
+## Upstream surfaces the demo relies on
 
-The upstream `fastvideo` package is missing three pieces that the demo
-currently depends on verbatim. Each needs its own upstreaming PR before this
-demo can actually boot:
+Everything the demo needs ships in the upstream `fastvideo` package:
 
-1. **`fastvideo.layers.quantization.fp4_config.FP4Config`** — the demo sets
-   `pipeline_config.dit_config.quant_config = FP4Config()` in `app.py`.
-   Upstream only ships `absmax_fp8.py` and `base_config.py` under
-   `fastvideo/layers/quantization/`.
-2. **LTX-2.3 refine / image-conditioning kwargs on `VideoGenerator`** —
-   `ltx2_refine_enabled`, `ltx2_refine_upsampler_path`, `ltx2_refine_lora_path`,
-   `ltx2_refine_num_inference_steps`, `ltx2_refine_guidance_scale`,
-   `ltx2_refine_add_noise`, `ltx2_images`, `ltx2_image_crf`. Upstream
-   `fastvideo/fastvideo_args.py` currently wires only `ltx2_vae_tiling`.
-   The backing stages (`ltx2_refine.py`, `ltx2_i2v_conditioning.py`) are
-   also missing from `fastvideo/pipelines/stages/`.
-3. **`fastvideo.configs.sample.base.SamplingParam`** — the import path used
-   by this demo. Upstream moved sampling params to
-   `fastvideo.api.sampling_param`. A re-export shim at the old path, or an
-   import update here once the other two prereqs land, will resolve it.
+- **`fastvideo.layers.quantization.nvfp4_config.NVFP4Config`** — the demo sets
+  `pipeline_config.dit_config.quant_config = NVFP4Config()` in `app.py` (same
+  pattern as `examples/inference/basic/basic_ltx2_distilled_fast_profile.py`).
+- **LTX-2.3 refine kwargs on `VideoGenerator`** — `ltx2_refine_enabled`,
+  `ltx2_refine_upsampler_path`, `ltx2_refine_lora_path`,
+  `ltx2_refine_num_inference_steps`, `ltx2_refine_guidance_scale`,
+  `ltx2_refine_add_noise`, and `ltx2_vae_tiling` are wired in
+  `fastvideo/fastvideo_args.py`, backed by
+  `fastvideo/pipelines/basic/ltx2/stages/ltx2_refine.py`.
+- **`SamplingParam`** — imported from the public `fastvideo` package root
+  (`fastvideo.api.sampling_param` under the hood).
 
 ## Environment variables
 

examples/inference/gradio/local/gradio_local_demo_ltx2_3/app.py

@@ -4,10 +4,10 @@ from pathlib import Path
 
 import gradio as gr
 
+from fastvideo import SamplingParam
 from fastvideo.configs.pipelines.base import PipelineConfig
-from fastvideo.configs.sample.base import SamplingParam
 from fastvideo.entrypoints.video_generator import VideoGenerator
-from fastvideo.layers.quantization.fp4_config import FP4Config
+from fastvideo.layers.quantization.nvfp4_config import NVFP4Config
 from fastvideo.utils import maybe_download_model
 
 from .config import (
@@ -44,7 +44,7 @@ def main():
         resolved_model_path = Path(model_root)
 
         pipeline_config = PipelineConfig.from_pretrained(str(resolved_model_path))
-        pipeline_config.dit_config.quant_config = FP4Config()
+        pipeline_config.dit_config.quant_config = NVFP4Config()
         refine_upsampler_path = resolve_refine_upsampler_path(resolved_model_path)
         print(f"Using refine upsampler: {refine_upsampler_path}")
 

examples/inference/gradio/local/gradio_local_demo_ltx2_3/config.py

@@ -4,7 +4,7 @@ from pathlib import Path
 import torch
 import torch._inductor.config
 
-from fastvideo.configs.sample.base import SamplingParam
+from fastvideo import SamplingParam
 
 LOCAL_DEMO_DIR = Path(__file__).resolve().parent
 CLASSIFIER_DIR = Path(

examples/inference/gradio/local/gradio_local_demo_ltx2_3/ui.py

@@ -5,7 +5,7 @@ from copy import deepcopy
 
 import gradio as gr
 
-from fastvideo.configs.sample.base import SamplingParam
+from fastvideo import SamplingParam
 from fastvideo.entrypoints.video_generator import VideoGenerator
 
 from .config import (