Upload 12 files

.gitattributes

@@ -1,35 +1,35 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,2 +1,2 @@
-__pycache__/
-*.pyc
+__pycache__/
+*.pyc

README.md

@@ -1,212 +1,212 @@
----
-title: MiniMax H3 Turbo LoRA
-emoji: 🎬
-colorFrom: purple
-colorTo: indigo
-sdk: gradio
-sdk_version: 6.20.0
-app_file: app.py
-pinned: true
-short_description: Video generation with a synchronized soundtrack
-suggested_hardware: zero-a10g
----
-
-# MiniMax-H3 — unquantized, split across two Spaces
-
-Joint video **and** soundtrack out of a single denoising pass, at **bfloat16 with no quantization anywhere**.
-
-This Space is the denoising half: the 61.73 GiB transformer and the two autoencoders. The 62.14 GiB Qwen3-VL
-conditioner runs in
-[`qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner), which this
-Space calls over the gradio API for every request. The weights are the public
-[`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3) diffusers checkpoint.
-
-## Why split
-
-MiniMax-H3 is 195.9 GiB in bfloat16 and a ZeroGPU Space is evicted at **150 GB of storage**. An unquantized single
-Space is therefore impossible, which is why quantized demos of it run NVFP4 or float8 weights. Cut the
-`MiniMaxH3Blocks` sequence at its `text_encoder` step and both halves fit unquantized:
-
-| Space | Subfolders | Download | Resident |
-|---|---|---|---|
-| [`qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner) | `text_encoder/` + `tokenizer/` + `processor/` | 66.7 GB | 62.15 GiB bf16 |
-| this one | `transformer/` + `vae/` + `audio_vae/` | 77.3 GB | 61.73 GiB bf16 + 10.43 GiB float32 |
-
-Besides the quality argument, unquantized weights are the ones AoTI can export; an NVFP4 checkpoint cannot be
-exported at all.
-
-## Studio frontend (gradio.Server)
-
-The UI is a custom single-page studio (`index.html`) served by [`gradio.Server`](https://www.gradio.app/docs/gradio/server):
-`@app.get("/")` serves the page, `@app.api(name="generate")` keeps the request on Gradio's queue (concurrency control,
-SSE, ZeroGPU booking, `gradio_client` compatibility — the API name and signature are unchanged), and the page talks
-to it with the `@gradio/client` JS package. `/status` and `/config` are plain FastAPI routes the page polls for
-readiness and the canvas table. Keyframe cover-crop / canvas fitting moved server-side into `generate`, so API
-callers get the same treatment the old upload event gave.
-
-## 4-step Turbo LoRA
-
-The transformer runs with [`larryvrh/MiniMax-H3-Turbo-Lora`](https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora)
-folded into its bf16 weights at startup (`h3_lora.py`), so the default is **6 sampling steps** instead of 28 
-card's comfort zone at the current checkpoint; 4 is the design point but softer). The larry fold mirrors the diffusers key
-conversion exactly (fused-QKV thirds, the `SwiGLU` gate/value swap, the shared AdaLN row layout); lightx keys are
-already diffusers-native. Both happen before the AoTI package is patched in, so compiled blocks carry the update too,
-and the low-rank factors stay resident so switching is an in-place unfold/fold through one bf16 rounding.
-`H3_LORA` selects the larry file (`off` skips it), `H3_LIGHTX=off` skips lightx, `H3_LORA_DEFAULT` picks which set
-starts folded, and `H3_LORA_STRENGTH` scales the larry update (the card's sharpness/artifact dial).
-
-## AoTI-compiled blocks
-
-With `H3_AOTI=1` the 50 repeated transformer blocks run from a compiled package,
-[`multimodalart/minimax-h3-aoti`](https://huggingface.co/multimodalart/minimax-h3-aoti)`:bf16/torch2.11/sm120/dynamic` — a single dynamic-sequence artifact that serves
-every canvas, duration and prompt length. It carries no weights (it reads each block's live ones), so patching it in
-is startup CPU work and costs no GPU time.
-
-It removes a near-constant ~0.5 s/step — 50 blocks' worth of kernel-launch overhead plus the norm / rotary / AdaLN
-epilogues around the matmuls — and cannot touch the matmuls themselves. So it pays best where the block is *not*
-compute bound, i.e. on the small canvases:
-
-| canvas (HxW) | eager s/step | AoTI s/step | faster |
-|---|---|---|---|
-| 768x1344 | 10.20 | 9.73 | +4.6% |
-| 640x1152 | 6.46 | 5.88 | +9.1% |
-| 544x960 | 4.02 | 3.58 | +11.0% |
-
-At 72.16 GiB of weights on a 95.0 GiB card there is no offloading in the request path at all, which is why an
-*unquantized* MiniMax-H3 is also the fastest one measured here: **10.6 s/step** against the 19–21 s/step the 4 bit
-Space pays, where the whole cost is the traffic auto-offload has to move.
-
-## How the split is expressed
-
-`MiniMaxH3Blocks` is a `SequentialPipelineBlocks` whose branches are picked per request — and per `workflow=` — from
-the inputs:
-
-```
-before_encode -> text_encoder -> vae_encoder -> denoise -> after_denoise -> decode
-```
-
-where `denoise` is itself `prepare_layout -> prepare_latents -> set_timesteps -> denoise`.
-
-`h3_split_blocks.py` subclasses it with the `text_encoder` step removed. Dropping the step drops the three
-components it declares, so `load_components` resolves `transformer` / `vae` / `audio_vae` / the two schedulers out of
-the shared `modular_model_index.json` and never fetches the conditioner — and `prompt_embeds` and `text_token_tags`
-become ordinary required inputs of the pipeline call:
-
-```py
-pipe = MiniMaxH3GeneratorBlocks().init_pipeline("MiniMaxAI/MiniMax-H3")
-pipe.load_components(dtype=torch.bfloat16)
-state = pipe(prompt_embeds=..., text_token_tags=..., height=768, width=1344, num_frames=124, num_inference_steps=30)
-```
-
-The wire format is exactly those two tensors — `(1, num_text_tokens, 5120)` bfloat16 and `(num_text_tokens,)` int64 —
-carried as one safetensors file with the resolved `height` / `width` / `num_frames` in its metadata header. A
-text-only request is 246 KB of it; one 768x1344 keyframe adds 1016 vision rows and takes it to 10.7 MB.
-
-The keyframe `resize` step runs on **both** halves. It owns no pretrained component (PIL and arithmetic) and it puts
-the keyframes onto the target canvas — which the conditioner needs to build its vision blocks and this Space needs to
-encode with the video VAE. It is deterministic, and the conditioner returns the plan it resolved so this Space pins
-the same canvas rather than re-deriving it. Two things that step no longer does, and that both halves therefore do
-themselves: EXIF-transposing a keyframe into upright RGB, and snapping `num_frames` to `17 * n + 5` — the frame count
-is resolved by the layout step, which lives on this side of the cut.
-
-## Nothing is paid for with GPU time
-
-The 77.3 GB download and the load happen at **startup**: `import spaces` at module top patches `torch.cuda` before
-any GPU is attached, so nothing about the load needs a card. The conditioner round trip is a network call on this
-Space's CPU. A `@spaces.GPU` call is therefore only the placement (once) and the denoise loop and the two decoders.
-
-### The 150 GB quota, not the 95 GiB card, is what rules out startup placement
-
-One thing does *not* happen at startup: the move onto the card. `spaces`' startup `torch.pack()` writes every
-startup-resident CUDA tensor to a **second copy on disk** and only deletes the downloaded originals afterwards
-(`Cleaned 62.13GB of tensor files ... after packing`, which is what keeps the conditioner half comfortable at
-66.7 GB). Packing 77.3 GB needs 154.6 GB at once, and this Space is evicted mid-pack:
-
-```
-ZeroGPU tensors packing:   0%|          | 0.00/77.3G
-OSError: [Errno 28] No space left on device      # os.posix_fallocate, spaces/zero/torch/packing.py
-```
-
-Unlinking the shards first does not rescue it. `.to("cuda")` under the startup patch does not release the
-memory-mapped safetensors, so nothing is freed — and the pack's own cleanup walks those still-open mappings and
-`lstat`s them, so a deleted blob becomes `FileNotFoundError: .../blobs/3d449... (deleted)`.
-
-Placement therefore happens on the **first GPU call**, `PIPE.to("cuda")` at the top of the `@spaces.GPU` function:
-about 10 s of PCIe once, then a no-op walk, and the denoise loop runs with everything resident and no offloading at
-all. It is the same trick the 4 bit Space uses, for the same reason.
-
-## Generation constraints
-
-Fixed by the checkpoint: 24 fps, a 768 pixel short edge, 5 to 15 s, `num_frames` snapped up to the next `17 * n + 5`,
-no CFG and no negative prompt (it is guidance-distilled, so every step is one forward pass).
-
-## Measured
-
-An `rtx-pro-6000` Job — the same silicon as the ZeroGPU pool (RTX PRO 6000 Blackwell, sm120, 95.0 GiB) — running
-exactly this blockset over the wire format, 1344x768, 124 frames, 30 steps, bfloat16, cuDNN attention, everything
-resident:
-
-| | |
-|---|---|
-| `load_components` (77.3 GB, warm Xet) | 43 s |
-| `.to("cuda")`, once | 10 s |
-| resident weights | 72.16 GiB |
-| denoise + decode | 317 s, **10.58 s/step** |
-| peak allocated / reserved | 78.54 / 85.37 GiB |
-| output | h264 1344x768 @ 24 fps, 5.167 s + stereo AAC @ 32 kHz |
-
-And on this Space itself, driven over `gradio_client`. Startup is 93 s — the 77.3 GB download and the load, with
-no placement and therefore no pack.
-
-| Request | Conditioner | Denoise + decode | Steady | Round trip |
-|---|---|---|---|---|
-| text only, 18 tokens | 7 s | 339 s | 10.53 s/step | 353 s |
-| one 768x1344 keyframe, 1034 tokens | 9 s | 370 s | 11.39 s/step | 386 s |
-
-The keyframe costs about 8% per step rather than a placement penalty: it puts 1016 vision rows in front of the
-prompt *and* 1016 conditioning rows in the packed sequence, and MiniMax-H3 attends over all of it every layer. The
-one-time `PIPE.to("cuda")` is inside the first row's 339 s and does not reappear in the second.
-
-## Space variables
-
-| Variable | Default | Meaning |
-|---|---|---|
-| `H3_MODEL_REPO` | `MiniMaxAI/MiniMax-H3` | The diffusers-layout checkpoint. Public. |
-| `H3_CONDITIONER` | `multimodalart/qwen3vl-conditioner` | The Space this one asks for embeddings. |
-| `H3_PLACEMENT` | `lazy` | `lazy` moves all 72.16 GiB onto the card on the first GPU call and leaves it there; `offload` hands placement to `ComponentsManager.enable_auto_cpu_offload` instead. |
-| `H3_ATTENTION` | `_native_cudnn` | cuDNN's fused kernel, 10–20% faster than the SDPA default and needs nothing installed. flash-attention 3 is sm90-only and this pool is sm120. |
-| `H3_GPU_DURATION` | `900` | Seconds per request; the pool applies a 1.5 duration factor. |
-| `H3_GPU_SIZE` | `xlarge` | ZeroGPU allocation size. `large` does not fit. |
-| `H3_LORA` | `minimax_h3_turbo_4step_ema_ckpt850.safetensors` | Turbo LoRA file folded into the transformer at startup. `off` disables. |
-| `H3_LORA_REPO` | `larryvrh/MiniMax-H3-Turbo-Lora` | Hub repo the LoRA is fetched from. |
-| `H3_LORA_STRENGTH` | `1.0` | Scales the larry LoRA delta (sharpness/artifact trade-off). |
-| `H3_LIGHTX` | `on` | Set to `off` to skip loading the lightx2v LoRA set. |
-| `H3_LORA_DEFAULT` | `larry` | Which loaded LoRA set starts folded (`larry` / `lightx`). |
-
-## Whose GPU quota pays
-
-Two cards are booked per request — this Space's denoise loop and the conditioner's forward — and both are billed to the
-requesting user, with nothing here arranging it: `gradio_client` attaches the caller's own `x-ip-token` to every
-outgoing call, reading it off gradio's `LocalContext` inside the event listener (`Client.send_data` ->
-`add_zero_gpu_headers`), and ZeroGPU charges the booking to whatever that token identifies.
-
-A caller with no token to forward — a `gradio_client` script rather than a browser — leaves the conditioner's booking
-attributed to this Space's pod IP and its small shared quota. An unattributed caller may book at most 120 credits at a
-time and an `xlarge` booking costs twice its seconds, so the conditioner books the encode (45 s) and a prompt upsample
-(60 s) as two separate calls, each within that ceiling.
-
-## Secrets
-
-None are required. Everything this Space downloads is public — the
-[`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3) checkpoint and the
-[`multimodalart/minimax-h3-aoti`](https://huggingface.co/multimodalart/minimax-h3-aoti) packages — and the conditioner
-is a public Space called on the requesting user's own ZeroGPU token, never on an org token.
-
-## Where diffusers comes from
-
-MiniMax-H3 is modular-only and not in a released `diffusers`, so `requirements.txt` installs it from the canonical
-pull request, [huggingface/diffusers#14371](https://github.com/huggingface/diffusers/pull/14371), pinned to the commit
-`665f5782` (`refs/pull/14371/head`) rather than to the moving `minimax-h3-refactor` branch.
-
-That PR is a WIP, so it needs re-pinning whenever it updates, and `h3_split_blocks.py` — which subclasses its block
-classes to cut the pipeline in two — has to be re-checked against the new head at the same time.
+---
+title: MiniMax H3 Turbo LoRA
+emoji: 🎬
+colorFrom: purple
+colorTo: indigo
+sdk: gradio
+sdk_version: 6.20.0
+app_file: app.py
+pinned: true
+short_description: Video generation with a synchronized soundtrack
+suggested_hardware: zero-a10g
+---
+
+# MiniMax-H3 — unquantized, split across two Spaces
+
+Joint video **and** soundtrack out of a single denoising pass, at **bfloat16 with no quantization anywhere**.
+
+This Space is the denoising half: the 61.73 GiB transformer and the two autoencoders. The 62.14 GiB Qwen3-VL
+conditioner runs in
+[`qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner), which this
+Space calls over the gradio API for every request. The weights are the public
+[`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3) diffusers checkpoint.
+
+## Why split
+
+MiniMax-H3 is 195.9 GiB in bfloat16 and a ZeroGPU Space is evicted at **150 GB of storage**. An unquantized single
+Space is therefore impossible, which is why quantized demos of it run NVFP4 or float8 weights. Cut the
+`MiniMaxH3Blocks` sequence at its `text_encoder` step and both halves fit unquantized:
+
+| Space | Subfolders | Download | Resident |
+|---|---|---|---|
+| [`qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner) | `text_encoder/` + `tokenizer/` + `processor/` | 66.7 GB | 62.15 GiB bf16 |
+| this one | `transformer/` + `vae/` + `audio_vae/` | 77.3 GB | 61.73 GiB bf16 + 10.43 GiB float32 |
+
+Besides the quality argument, unquantized weights are the ones AoTI can export; an NVFP4 checkpoint cannot be
+exported at all.
+
+## Studio frontend (gradio.Server)
+
+The UI is a custom single-page studio (`index.html`) served by [`gradio.Server`](https://www.gradio.app/docs/gradio/server):
+`@app.get("/")` serves the page, `@app.api(name="generate")` keeps the request on Gradio's queue (concurrency control,
+SSE, ZeroGPU booking, `gradio_client` compatibility — the API name and signature are unchanged), and the page talks
+to it with the `@gradio/client` JS package. `/status` and `/config` are plain FastAPI routes the page polls for
+readiness and the canvas table. Keyframe cover-crop / canvas fitting moved server-side into `generate`, so API
+callers get the same treatment the old upload event gave.
+
+## 4-step Turbo LoRA
+
+The transformer runs with [`larryvrh/MiniMax-H3-Turbo-Lora`](https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora)
+folded into its bf16 weights at startup (`h3_lora.py`), so the default is **6 sampling steps** instead of 28 
+card's comfort zone at the current checkpoint; 4 is the design point but softer). The larry fold mirrors the diffusers key
+conversion exactly (fused-QKV thirds, the `SwiGLU` gate/value swap, the shared AdaLN row layout); lightx keys are
+already diffusers-native. Both happen before the AoTI package is patched in, so compiled blocks carry the update too,
+and the low-rank factors stay resident so switching is an in-place unfold/fold through one bf16 rounding.
+`H3_LORA` selects the larry file (`off` skips it), `H3_LIGHTX=off` skips lightx, `H3_LORA_DEFAULT` picks which set
+starts folded, and `H3_LORA_STRENGTH` scales the larry update (the card's sharpness/artifact dial).
+
+## AoTI-compiled blocks
+
+With `H3_AOTI=1` the 50 repeated transformer blocks run from a compiled package,
+[`multimodalart/minimax-h3-aoti`](https://huggingface.co/multimodalart/minimax-h3-aoti)`:bf16/torch2.11/sm120/dynamic` — a single dynamic-sequence artifact that serves
+every canvas, duration and prompt length. It carries no weights (it reads each block's live ones), so patching it in
+is startup CPU work and costs no GPU time.
+
+It removes a near-constant ~0.5 s/step — 50 blocks' worth of kernel-launch overhead plus the norm / rotary / AdaLN
+epilogues around the matmuls — and cannot touch the matmuls themselves. So it pays best where the block is *not*
+compute bound, i.e. on the small canvases:
+
+| canvas (HxW) | eager s/step | AoTI s/step | faster |
+|---|---|---|---|
+| 768x1344 | 10.20 | 9.73 | +4.6% |
+| 640x1152 | 6.46 | 5.88 | +9.1% |
+| 544x960 | 4.02 | 3.58 | +11.0% |
+
+At 72.16 GiB of weights on a 95.0 GiB card there is no offloading in the request path at all, which is why an
+*unquantized* MiniMax-H3 is also the fastest one measured here: **10.6 s/step** against the 19–21 s/step the 4 bit
+Space pays, where the whole cost is the traffic auto-offload has to move.
+
+## How the split is expressed
+
+`MiniMaxH3Blocks` is a `SequentialPipelineBlocks` whose branches are picked per request — and per `workflow=` — from
+the inputs:
+
+```
+before_encode -> text_encoder -> vae_encoder -> denoise -> after_denoise -> decode
+```
+
+where `denoise` is itself `prepare_layout -> prepare_latents -> set_timesteps -> denoise`.
+
+`h3_split_blocks.py` subclasses it with the `text_encoder` step removed. Dropping the step drops the three
+components it declares, so `load_components` resolves `transformer` / `vae` / `audio_vae` / the two schedulers out of
+the shared `modular_model_index.json` and never fetches the conditioner — and `prompt_embeds` and `text_token_tags`
+become ordinary required inputs of the pipeline call:
+
+```py
+pipe = MiniMaxH3GeneratorBlocks().init_pipeline("MiniMaxAI/MiniMax-H3")
+pipe.load_components(dtype=torch.bfloat16)
+state = pipe(prompt_embeds=..., text_token_tags=..., height=768, width=1344, num_frames=124, num_inference_steps=30)
+```
+
+The wire format is exactly those two tensors — `(1, num_text_tokens, 5120)` bfloat16 and `(num_text_tokens,)` int64 —
+carried as one safetensors file with the resolved `height` / `width` / `num_frames` in its metadata header. A
+text-only request is 246 KB of it; one 768x1344 keyframe adds 1016 vision rows and takes it to 10.7 MB.
+
+The keyframe `resize` step runs on **both** halves. It owns no pretrained component (PIL and arithmetic) and it puts
+the keyframes onto the target canvas — which the conditioner needs to build its vision blocks and this Space needs to
+encode with the video VAE. It is deterministic, and the conditioner returns the plan it resolved so this Space pins
+the same canvas rather than re-deriving it. Two things that step no longer does, and that both halves therefore do
+themselves: EXIF-transposing a keyframe into upright RGB, and snapping `num_frames` to `17 * n + 5` — the frame count
+is resolved by the layout step, which lives on this side of the cut.
+
+## Nothing is paid for with GPU time
+
+The 77.3 GB download and the load happen at **startup**: `import spaces` at module top patches `torch.cuda` before
+any GPU is attached, so nothing about the load needs a card. The conditioner round trip is a network call on this
+Space's CPU. A `@spaces.GPU` call is therefore only the placement (once) and the denoise loop and the two decoders.
+
+### The 150 GB quota, not the 95 GiB card, is what rules out startup placement
+
+One thing does *not* happen at startup: the move onto the card. `spaces`' startup `torch.pack()` writes every
+startup-resident CUDA tensor to a **second copy on disk** and only deletes the downloaded originals afterwards
+(`Cleaned 62.13GB of tensor files ... after packing`, which is what keeps the conditioner half comfortable at
+66.7 GB). Packing 77.3 GB needs 154.6 GB at once, and this Space is evicted mid-pack:
+
+```
+ZeroGPU tensors packing:   0%|          | 0.00/77.3G
+OSError: [Errno 28] No space left on device      # os.posix_fallocate, spaces/zero/torch/packing.py
+```
+
+Unlinking the shards first does not rescue it. `.to("cuda")` under the startup patch does not release the
+memory-mapped safetensors, so nothing is freed — and the pack's own cleanup walks those still-open mappings and
+`lstat`s them, so a deleted blob becomes `FileNotFoundError: .../blobs/3d449... (deleted)`.
+
+Placement therefore happens on the **first GPU call**, `PIPE.to("cuda")` at the top of the `@spaces.GPU` function:
+about 10 s of PCIe once, then a no-op walk, and the denoise loop runs with everything resident and no offloading at
+all. It is the same trick the 4 bit Space uses, for the same reason.
+
+## Generation constraints
+
+Fixed by the checkpoint: 24 fps, a 768 pixel short edge, 5 to 15 s, `num_frames` snapped up to the next `17 * n + 5`,
+no CFG and no negative prompt (it is guidance-distilled, so every step is one forward pass).
+
+## Measured
+
+An `rtx-pro-6000` Job — the same silicon as the ZeroGPU pool (RTX PRO 6000 Blackwell, sm120, 95.0 GiB) — running
+exactly this blockset over the wire format, 1344x768, 124 frames, 30 steps, bfloat16, cuDNN attention, everything
+resident:
+
+| | |
+|---|---|
+| `load_components` (77.3 GB, warm Xet) | 43 s |
+| `.to("cuda")`, once | 10 s |
+| resident weights | 72.16 GiB |
+| denoise + decode | 317 s, **10.58 s/step** |
+| peak allocated / reserved | 78.54 / 85.37 GiB |
+| output | h264 1344x768 @ 24 fps, 5.167 s + stereo AAC @ 32 kHz |
+
+And on this Space itself, driven over `gradio_client`. Startup is 93 s — the 77.3 GB download and the load, with
+no placement and therefore no pack.
+
+| Request | Conditioner | Denoise + decode | Steady | Round trip |
+|---|---|---|---|---|
+| text only, 18 tokens | 7 s | 339 s | 10.53 s/step | 353 s |
+| one 768x1344 keyframe, 1034 tokens | 9 s | 370 s | 11.39 s/step | 386 s |
+
+The keyframe costs about 8% per step rather than a placement penalty: it puts 1016 vision rows in front of the
+prompt *and* 1016 conditioning rows in the packed sequence, and MiniMax-H3 attends over all of it every layer. The
+one-time `PIPE.to("cuda")` is inside the first row's 339 s and does not reappear in the second.
+
+## Space variables
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `H3_MODEL_REPO` | `MiniMaxAI/MiniMax-H3` | The diffusers-layout checkpoint. Public. |
+| `H3_CONDITIONER` | `multimodalart/qwen3vl-conditioner` | The Space this one asks for embeddings. |
+| `H3_PLACEMENT` | `lazy` | `lazy` moves all 72.16 GiB onto the card on the first GPU call and leaves it there; `offload` hands placement to `ComponentsManager.enable_auto_cpu_offload` instead. |
+| `H3_ATTENTION` | `_native_cudnn` | cuDNN's fused kernel, 10–20% faster than the SDPA default and needs nothing installed. flash-attention 3 is sm90-only and this pool is sm120. |
+| `H3_GPU_DURATION` | `900` | Seconds per request; the pool applies a 1.5 duration factor. |
+| `H3_GPU_SIZE` | `xlarge` | ZeroGPU allocation size. `large` does not fit. |
+| `H3_LORA` | `minimax_h3_turbo_4step_ema_ckpt850.safetensors` | Turbo LoRA file folded into the transformer at startup. `off` disables. |
+| `H3_LORA_REPO` | `larryvrh/MiniMax-H3-Turbo-Lora` | Hub repo the LoRA is fetched from. |
+| `H3_LORA_STRENGTH` | `1.0` | Scales the larry LoRA delta (sharpness/artifact trade-off). |
+| `H3_LIGHTX` | `on` | Set to `off` to skip loading the lightx2v LoRA set. |
+| `H3_LORA_DEFAULT` | `larry` | Which loaded LoRA set starts folded (`larry` / `lightx`). |
+
+## Whose GPU quota pays
+
+Two cards are booked per request — this Space's denoise loop and the conditioner's forward — and both are billed to the
+requesting user, with nothing here arranging it: `gradio_client` attaches the caller's own `x-ip-token` to every
+outgoing call, reading it off gradio's `LocalContext` inside the event listener (`Client.send_data` ->
+`add_zero_gpu_headers`), and ZeroGPU charges the booking to whatever that token identifies.
+
+A caller with no token to forward — a `gradio_client` script rather than a browser — leaves the conditioner's booking
+attributed to this Space's pod IP and its small shared quota. An unattributed caller may book at most 120 credits at a
+time and an `xlarge` booking costs twice its seconds, so the conditioner books the encode (45 s) and a prompt upsample
+(60 s) as two separate calls, each within that ceiling.
+
+## Secrets
+
+None are required. Everything this Space downloads is public — the
+[`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3) checkpoint and the
+[`multimodalart/minimax-h3-aoti`](https://huggingface.co/multimodalart/minimax-h3-aoti) packages — and the conditioner
+is a public Space called on the requesting user's own ZeroGPU token, never on an org token.
+
+## Where diffusers comes from
+
+MiniMax-H3 is modular-only and not in a released `diffusers`, so `requirements.txt` installs it from the canonical
+pull request, [huggingface/diffusers#14371](https://github.com/huggingface/diffusers/pull/14371), pinned to the commit
+`665f5782` (`refs/pull/14371/head`) rather than to the moving `minimax-h3-refactor` branch.
+
+That PR is a WIP, so it needs re-pinning whenever it updates, and `h3_split_blocks.py` — which subclasses its block
+classes to cut the pipeline in two — has to be re-checked against the new head at the same time.

app.py

@@ -1,445 +1,445 @@
-"""MiniMax-H3 `t2va` / `fl2va`, split deployment — the denoising half."""
-
-from __future__ import annotations
-
-import os
-import tempfile
-import time
-import traceback
-from functools import cache
-
-# Before anything that could initialize CUDA: `import spaces` patches `torch.cuda` so the 72 GiB load can happen at
-# startup rather than on GPU time.
-import spaces
-from fastapi.responses import HTMLResponse
-from gradio import Request, Server
-from gradio.data_classes import FileData
-
-MODEL_REPO = os.environ.get("H3_MODEL_REPO", "MiniMaxAI/MiniMax-H3")
-CONDITIONER_SPACE = os.environ.get("H3_CONDITIONER", "multimodalart/qwen3vl-conditioner")
-# `pack` places the transformer at startup, `lazy` moves everything on the first GPU call, `offload` hands placement to
-# `ComponentsManager.enable_auto_cpu_offload`.
-PLACEMENT = os.environ.get("H3_PLACEMENT", "pack").lower()
-# cuDNN's fused attention is 10-20% faster than the SDPA default on this pool and needs nothing installed.
-ATTENTION = os.environ.get("H3_ATTENTION", "_native_cudnn").lower()
-GPU_SIZE = os.environ.get("H3_GPU_SIZE", "xlarge")
-
-# Must stay identical to the conditioner's table: the *label* goes over the wire, so a canvas that half does not know
-# is rejected there and surfaces as a failure here.
-CANVASES = {
-    # 16:9
-    "960x544 · 16:9 fast": (544, 960),
-    "1024x576 · 16:9 fast": (576, 1024),
-    "1152x640 · 16:9": (640, 1152),
-    "1280x704 · 16:9": (704, 1280),
-    "1344x768 · 16:9 full": (768, 1344),
-    # 9:16
-    "544x960 · 9:16 fast": (960, 544),
-    "640x1152 · 9:16": (1152, 640),
-    "768x1344 · 9:16 full": (1344, 768),
-    # 1:1
-    "544x544 · 1:1 fast": (544, 544),
-    "768x768 · 1:1 full": (768, 768),
-    # 4:3 / 3:4
-    "768x576 · 4:3 fast": (576, 768),
-    "1024x768 · 4:3 full": (768, 1024),
-    "576x768 · 3:4 fast": (768, 576),
-    "768x1024 · 3:4 full": (1024, 768),
-    # 21:9
-    "1152x512 · 21:9 fast": (512, 1152),
-    "1536x672 · 21:9 full": (672, 1536),
-}
-DEFAULT_CANVAS = "960x544 · 16:9 fast"
-FPS, FRAMES_PER_CHUNK, LATENTS_PER_CHUNK = 24, 17, 5
-# It is the *snapped* frame count the ceiling has to hold for: 15 s is 360 frames, which rounds up to 362, i.e.
-# 15.083 s, and is refused.
-MIN_UI_DURATION, MAX_UI_DURATION = 2, 14
-
-
-def snap_frames(seconds: float) -> int:
-    """The frame count MiniMax-H3's video VAE can decode: the next `17 * n + 5` at 24 fps."""
-    frames = max(1, round(float(seconds) * FPS))
-    while frames % FRAMES_PER_CHUNK != LATENTS_PER_CHUNK:
-        frames += 1
-    return frames
-
-
-def lower_duration_floor(seconds: float = MIN_UI_DURATION) -> None:
-    """Let the pipeline generate below its 5 s floor. 56 frames (2.33 s) is fine on the released checkpoint."""
-    from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MiniMaxH3ModularPipeline
-
-    MiniMaxH3ModularPipeline.min_duration = property(lambda self: float(seconds))
-
-
-OUTPUT_DIR = os.path.join(tempfile.gettempdir(), "h3-outputs")
-
-PIPE = None
-MANAGER = None
-LOAD_ERROR: str | None = None
-LOADED_IN: float | None = None
-LORA_STATUS: str | None = None
-
-
-def status() -> str:
-    if LOAD_ERROR:
-        return LOAD_ERROR
-    if PIPE is None:
-        return f"Loading `{MODEL_REPO}` (transformer + VAEs, 77.3 GB). Watch the Space logs."
-    import h3_aoti
-
-    return (
-        f"Ready · transformer + VAEs **bfloat16, unquantized** · placement `{PLACEMENT}` · attention `{ATTENTION}` · "
-        f"{h3_aoti.status()} · {LORA_STATUS or 'no LoRA'} · loaded in {LOADED_IN:.0f}s · "
-        f"conditioner `{CONDITIONER_SPACE}`"
-    )
-
-
-def load_models() -> str | None:
-    """Load the denoising half at startup.
-    `MiniMaxH3GeneratorBlocks` declares `transformer`, `vae`, `audio_vae`, the two schedulers and `video_processor`,
-    so `load_components` fetches exactly those subfolders — `text_encoder/` and `transformer_ref/` are never touched.
-    Both autoencoders carry `_keep_in_fp32_modules` over every module and stay float32: a bfloat16 audio VAE decodes
-    the soundtrack roughly 20 dB too quiet.
-    """
-    global PIPE, MANAGER, LOAD_ERROR, LOADED_IN, LORA_STATUS
-
-    if PIPE is not None or LOAD_ERROR is not None:
-        return LOAD_ERROR
-
-    started = time.time()
-    try:
-        import torch
-        from diffusers import ComponentsManager
-
-        from h3_split_blocks import MiniMaxH3GeneratorBlocks
-
-        lower_duration_floor()
-        manager = ComponentsManager()
-        blocks = MiniMaxH3GeneratorBlocks()
-        print(f"[gen] loading {[c.name for c in blocks.expected_components]} from {MODEL_REPO} ...", flush=True)
-        pipe = blocks.init_pipeline(MODEL_REPO, components_manager=manager, collection="h3")
-        pipe.load_components(dtype=torch.bfloat16)
-
-        # Fold the 4-step Turbo LoRA into the bf16 weights before AoTI packages the blocks, so the compiled forward
-        # reads weights that already carry the update. `H3_LORA=off` disables.
-        import h3_lora
-
-        LORA_STATUS = h3_lora.apply_lora(pipe.transformer)
-        if LORA_STATUS:
-            print(f"[gen] {LORA_STATUS}", flush=True)
-
-        pipe.transformer.set_attention_backend(ATTENTION)
-
-        # Still startup, still free: an AoTI package carries no weights and opens its archive lazily inside the GPU
-        # worker. Off unless `H3_AOTI=1`.
-        import h3_aoti
-
-        h3_aoti.maybe_load(pipe.transformer)
-
-        if PLACEMENT == "pack":
-            # Scoped to the transformer. `spaces` packs every startup-resident CUDA tensor into a second on-disk copy,
-            # and packing all 77.3 GB busts the 150 GB storage quota; the 61.7 GB transformer alone fits. The ~10 GB of
-            # fp32 VAEs move on the first GPU call instead.
-            pipe.transformer.to("cuda")
-
-        if PLACEMENT == "offload":
-            manager.enable_auto_cpu_offload(device="cuda")
-            _arm_decode_hooks(pipe)
-
-        PIPE, MANAGER = pipe, manager
-        LOADED_IN = time.time() - started
-        print(f"[gen] ready in {LOADED_IN:.0f}s", flush=True)
-    except Exception as error:
-        traceback.print_exc()
-        LOAD_ERROR = f"**Loading `{MODEL_REPO}` failed** after {time.time() - started:.0f}s: `{type(error).__name__}: {error}`"
-    return LOAD_ERROR
-
-
-def _arm_decode_hooks(pipe):
-    """Make the offload hooks fire for the two VAEs.
-    `enable_auto_cpu_offload` wraps `forward`, and the decode blocks call `vae.decode(...)` directly, so the hook
-    never runs and the VAE is still on the host when the latents arrive on the card.
-    """
-    for name in ("vae", "audio_vae"):
-        module = getattr(pipe, name)
-        inner = module.decode
-
-        def armed(*args, _module=module, _decode=inner, **kwargs):
-            hook = getattr(_module, "_hf_hook", None)
-            if hook is not None:
-                hook.pre_forward(_module)
-            return _decode(*args, **kwargs)
-
-        module.decode = armed
-
-
-@cache
-def conditioner():
-    """The other half, over the gradio API. Used only when the caller's token could not be extracted; the booking is
-    then billed to this Space's pod IP and its small shared quota."""
-    from gradio_client import Client
-
-    return Client(CONDITIONER_SPACE)
-
-
-def conditioner_client(ip_token):
-    """A conditioner client billed to the caller. `LocalContext`-based token forwarding is not reliable in Server
-    mode, so the `x-ip-token` header is extracted from the incoming request and passed explicitly (per the gradio
-    ZeroGPU docs); a per-request Client is cheap next to a 45s encode."""
-    if not ip_token:
-        return conditioner()
-    from gradio_client import Client
-
-    return Client(CONDITIONER_SPACE, headers={"x-ip-token": ip_token})
-
-
-def encode_remote(prompt, image_path, last_image_path, canvas, num_frames, rewrite_prompt=False, ip_token=None):
-    """`/encode` on the conditioner Space: a safetensors file holding `prompt_embeds` + `text_token_tags`, with the
-    resolved `height` / `width` / `num_frames` in its metadata, plus the plan. `canvas` is the label."""
-    from gradio_client import handle_file
-    from safetensors import safe_open
-
-    path, plan = conditioner_client(ip_token).predict(
-        prompt=prompt,
-        image_path=handle_file(image_path) if image_path else None,
-        last_image_path=handle_file(last_image_path) if last_image_path else None,
-        canvas=canvas,
-        num_frames=num_frames,
-        rewrite_prompt=bool(rewrite_prompt),
-        api_name="/encode",
-    )
-    with safe_open(path, framework="pt") as handle:
-        metadata = handle.metadata()
-        return handle.get_tensor("prompt_embeds"), handle.get_tensor("text_token_tags"), metadata, plan
-
-
-# Seconds of GPU one request needs, from the packed video rows it is about to denoise: linear in the rows for the
-# matmuls, quadratic for the attention, against the AoTI block package this Space runs.
-_DUR_B, _DUR_C = 1.1745e-4, 3.8396e-9
-# The two resident decoders and the mux, which scale with the output rather than with the step count.
-_DECODE_BASE, _DECODE_PER_DEFAULT_CANVAS, _DEFAULT_CANVAS_PIXELS = 15, 15, 960 * 544 * 124
-# `pack` mode: only the ~10 GB of VAEs move on a cold worker.
-_PLACEMENT_ALLOWANCE, _PAD = 12, 10
-
-
-def get_duration(prompt_embeds, text_token_tags, image, last_image, height, width, num_frames, steps, seed, lora="larry", *a, **k):
-    height, width, num_frames, steps = int(height), int(width), int(num_frames), int(steps)
-    latent_frames = (num_frames - LATENTS_PER_CHUNK) // FRAMES_PER_CHUNK * LATENTS_PER_CHUNK + 2
-    patches = (height // 32) * (width // 32)
-    rows = latent_frames * patches + (int(image is not None) + int(last_image is not None)) * patches
-    denoise = steps * (_DUR_B * rows + _DUR_C * rows**2)
-    decode = _DECODE_BASE + _DECODE_PER_DEFAULT_CANVAS * (height * width * num_frames) / _DEFAULT_CANVAS_PIXELS
-    return max(60, int(denoise + decode) + _PLACEMENT_ALLOWANCE + _PAD)
-
-
-@spaces.GPU(duration=get_duration, size=GPU_SIZE)
-def _generate(prompt_embeds, text_token_tags, image, last_image, height, width, num_frames, steps, seed, lora="larry"):
-    """The only thing on GPU time: the packed-sequence denoise loop and the two decoders.
-    Only the three generated outputs come back — a `@spaces.GPU` return crosses a process boundary by pickling, and
-    the full `PipelineState` still holds the packed latents, the rotary grid and the row indices on the card.
-    """
-    import torch
-
-    import h3_lora
-
-    # Fold the requested LoRA in place (a no-op when the state already matches). AoTI blocks read the same
-    # live storage, so the compiled forward carries the switch too.
-    active_lora = h3_lora.set_active(PIPE.transformer, lora)
-
-    if PLACEMENT == "lazy":
-        PIPE.to("cuda")
-    elif PLACEMENT == "pack":
-        PIPE.vae.to("cuda")
-        PIPE.audio_vae.to("cuda")
-
-    state = PIPE(
-        prompt_embeds=prompt_embeds.to("cuda"),
-        text_token_tags=text_token_tags,
-        image=image,
-        last_image=last_image,
-        height=height,
-        width=width,
-        num_frames=num_frames,
-        num_inference_steps=int(steps),
-        generator=torch.Generator("cpu").manual_seed(int(seed)),
-    )
-    return state.get("videos")[0], state.get("audio")[0].cpu(), state.get("sampling_rate"), active_lora
-
-
-def _fit_keyframe(image_path, current_canvas):
-    """Cover-crop an uploaded keyframe to the closest supported aspect ratio and pick that ratio's smallest
-    (fastest) canvas, unless the caller already picked a matching ratio. Returns `(image_path, canvas_label)`."""
-    from PIL import Image as _Image
-
-    img = _Image.open(image_path)
-    aspect = img.width / img.height
-    fastest = {}
-    for label, (h, w) in CANVASES.items():
-        r = w / h
-        if r not in fastest or w * h < fastest[r][1][0] * fastest[r][1][1]:
-            fastest[r] = (label, (h, w))
-    ratio = min(fastest, key=lambda r: abs(r - aspect))
-    label, (h, w) = fastest[ratio]
-
-    cur_h, cur_w = CANVASES[current_canvas]
-    if abs(cur_w / cur_h - aspect) <= abs(ratio - aspect):
-        label = current_canvas
-        h, w = cur_h, cur_w
-
-    target = w / h
-    if abs(img.width / img.height - target) > 1e-3:
-        if img.width / img.height > target:
-            new_w = int(img.height * target)
-            left = (img.width - new_w) // 2
-            img = img.crop((left, 0, left + new_w, img.height))
-        else:
-            new_h = int(img.width / target)
-            top = (img.height - new_h) // 2
-            img = img.crop((0, top, img.width, top + new_h))
-        img.save(image_path)
-    return image_path, label
-
-
-def _resolve_lora(lora, use_lora) -> str:
-    """`lora` (`larry` / `lightx` / `off`) wins; the legacy `use_lora` bool maps onto `larry` / `off`."""
-    if isinstance(lora, str) and lora in ("larry", "lightx", "off"):
-        return lora
-    return "larry" if use_lora else "off"
-
-
-def generate(prompt, image_path=None, last_image_path=None, canvas=DEFAULT_CANVAS, duration=5, steps=6, seed=42, upsample=False, use_lora=True, lora="", ip_token=None):
-    """One request. `upsample`/`use_lora` keep their defaults so a positional API client that predates them is unaffected."""
-    if LOAD_ERROR:
-        raise Exception(LOAD_ERROR)
-    if PIPE is None:
-        raise Exception("The denoiser is still loading.")
-    if not prompt or not prompt.strip():
-        raise Exception("MiniMax-H3 always takes a prompt, keyframes or not.")
-    
-    from PIL import Image, ImageOps
-
-    from diffusers.utils import encode_video
-
-    lora = _resolve_lora(lora, use_lora)
-
-    # Server mode: keyframes arrive as FileData dicts, and the cover-crop / canvas-fit that used to be an upload
-    # event in the Blocks UI runs here instead, so API callers get the same treatment.
-    first = image_path["path"] if isinstance(image_path, dict) else image_path
-    last = last_image_path["path"] if isinstance(last_image_path, dict) else last_image_path
-    if first:
-        first, canvas = _fit_keyframe(first, canvas)
-    if last:
-        last, canvas = _fit_keyframe(last, canvas)
-
-    num_frames = snap_frames(duration)
-
-    conditioned = time.time()
-    prompt_embeds, text_token_tags, metadata, plan = encode_remote(
-        prompt, first, last, canvas, num_frames, rewrite_prompt=upsample, ip_token=ip_token
-    )
-    condition_seconds = time.time() - conditioned
-    height, width, num_frames = (int(metadata[key]) for key in ("height", "width", "num_frames"))
-    refined = plan.get("refined_prompt") or ""
-
-    def keyframe(path):
-        # The conditioning latents encoded here have to be of the image the conditioner looked at, which it prepares
-        # exactly this way.
-        return ImageOps.exif_transpose(Image.open(path)).convert("RGB") if path else None
-
-    started = time.time()
-    frames, audio, sampling_rate, active_lora = _generate(
-        prompt_embeds,
-        text_token_tags,
-        keyframe(first),
-        keyframe(last),
-        height,
-        width,
-        num_frames,
-        steps,
-        seed,
-        lora,
-    )
-    generate_seconds = time.time() - started
-
-    os.makedirs(OUTPUT_DIR, exist_ok=True)
-    path = os.path.join(OUTPUT_DIR, f"h3-{int(time.time() * 1000)}.mp4")
-    encode_video(frames, fps=FPS, output_path=path, audio=audio, audio_sample_rate=sampling_rate)
-
-    report = (
-        f"{width}x{height} · {num_frames} frames ({num_frames / FPS:.3f} s) · {int(steps)} steps · "
-        f"conditioner {condition_seconds:.0f}s ({plan['num_text_tokens']} tokens"
-        f"{', upsampled' if refined else ''}) · "
-        f"denoise + decode {generate_seconds:.0f}s ({generate_seconds / int(steps):.1f} s/step) · "
-        f"turbo LoRA {active_lora} · seed {int(seed)}"
-    )
-    print(f"[gen] {report}", flush=True)
-    return FileData(path=path), report, refined
-
-
-
-# ======================================================================
-# Server mode: Gradio's API engine (queue, SSE, concurrency, ZeroGPU,
-# gradio_client) under a fully custom studio frontend (index.html).
-# ======================================================================
-app = Server(title="MiniMax-H3 Studio")
-
-
-@app.api(name="generate")
-def _generate_api(prompt: str, image_path: FileData | None = None, last_image_path: FileData | None = None,
-                  canvas: str = DEFAULT_CANVAS, duration: float = 5, steps: int = 6, seed: float = 42,
-                  upsample: bool = False, use_lora: bool = True, lora: str = "", request: Request = None) -> tuple[FileData, str, str]:
-    """Generate a video with a synchronized soundtrack. Returns (video, report, refined prompt).
-    `lora` selects the turbo LoRA: `larry` (default), `lightx`, or `off`. The legacy `use_lora` bool still works
-    when `lora` is empty.
-    """
-    # `request` is injected by the event system, not an API input; its x-ip-token bills the conditioner to the caller.
-    ip_token = request.headers.get("x-ip-token") if request is not None else None
-    return generate(prompt, image_path, last_image_path, canvas, duration, steps, seed, upsample, use_lora, lora, ip_token=ip_token)
-
-
-@app.get("/status")
-def studio_status():
-    """Polled by the frontend: is the denoiser ready, and the human-readable status line."""
-    return {"ready": PIPE is not None and LOAD_ERROR is None, "status": status()}
-
-
-# NB: not `/config` — Gradio's own client-discovery route lives there and shadowing it breaks `@gradio/client`.
-@app.get("/studio-config")
-def studio_config():
-    """The canvas table and slider ranges, so the frontend never hardcodes a label the backend would reject."""
-    import h3_lora
-
-    state = getattr(PIPE.transformer, "_lora_state", None) if PIPE is not None else None
-    sets = state["sets"] if state else {}
-    return {
-        "canvases": list(CANVASES),
-        "default_canvas": DEFAULT_CANVAS,
-        "min_duration": MIN_UI_DURATION,
-        "max_duration": MAX_UI_DURATION,
-        # The LoRA dropdown: value -> {label, suggested steps}.
-        "loras": {
-            **{
-                name: {"label": spec["label"], "steps": {"larry": 6, "lightx": 4}.get(name, 6)}
-                for name, spec in sets.items()
-            },
-            "off": {"label": "off (base model)", "steps": 28},
-        },
-        "default_lora": state["active"] if state else "off",
-    }
-
-
-@app.get("/", response_class=HTMLResponse)
-def homepage():
-    with open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "index.html"), encoding="utf-8") as f:
-        return f.read()
-
-
-import ncii_guard
-
-ncii_guard.start()
-load_models()
-
-if __name__ == "__main__":
-    # allowed_paths: the /gradio_api/file= route only serves whitelisted directories.
-    app.launch(show_error=True, allowed_paths=[OUTPUT_DIR])
+"""MiniMax-H3 `t2va` / `fl2va`, split deployment — the denoising half."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+import traceback
+from functools import cache
+
+# Before anything that could initialize CUDA: `import spaces` patches `torch.cuda` so the 72 GiB load can happen at
+# startup rather than on GPU time.
+import spaces
+from fastapi.responses import HTMLResponse
+from gradio import Request, Server
+from gradio.data_classes import FileData
+
+MODEL_REPO = os.environ.get("H3_MODEL_REPO", "MiniMaxAI/MiniMax-H3")
+CONDITIONER_SPACE = os.environ.get("H3_CONDITIONER", "multimodalart/qwen3vl-conditioner")
+# `pack` places the transformer at startup, `lazy` moves everything on the first GPU call, `offload` hands placement to
+# `ComponentsManager.enable_auto_cpu_offload`.
+PLACEMENT = os.environ.get("H3_PLACEMENT", "pack").lower()
+# cuDNN's fused attention is 10-20% faster than the SDPA default on this pool and needs nothing installed.
+ATTENTION = os.environ.get("H3_ATTENTION", "_native_cudnn").lower()
+GPU_SIZE = os.environ.get("H3_GPU_SIZE", "xlarge")
+
+# Must stay identical to the conditioner's table: the *label* goes over the wire, so a canvas that half does not know
+# is rejected there and surfaces as a failure here.
+CANVASES = {
+    # 16:9
+    "960x544 · 16:9 fast": (544, 960),
+    "1024x576 · 16:9 fast": (576, 1024),
+    "1152x640 · 16:9": (640, 1152),
+    "1280x704 · 16:9": (704, 1280),
+    "1344x768 · 16:9 full": (768, 1344),
+    # 9:16
+    "544x960 · 9:16 fast": (960, 544),
+    "640x1152 · 9:16": (1152, 640),
+    "768x1344 · 9:16 full": (1344, 768),
+    # 1:1
+    "544x544 · 1:1 fast": (544, 544),
+    "768x768 · 1:1 full": (768, 768),
+    # 4:3 / 3:4
+    "768x576 · 4:3 fast": (576, 768),
+    "1024x768 · 4:3 full": (768, 1024),
+    "576x768 · 3:4 fast": (768, 576),
+    "768x1024 · 3:4 full": (1024, 768),
+    # 21:9
+    "1152x512 · 21:9 fast": (512, 1152),
+    "1536x672 · 21:9 full": (672, 1536),
+}
+DEFAULT_CANVAS = "960x544 · 16:9 fast"
+FPS, FRAMES_PER_CHUNK, LATENTS_PER_CHUNK = 24, 17, 5
+# It is the *snapped* frame count the ceiling has to hold for: 15 s is 360 frames, which rounds up to 362, i.e.
+# 15.083 s, and is refused.
+MIN_UI_DURATION, MAX_UI_DURATION = 2, 14
+
+
+def snap_frames(seconds: float) -> int:
+    """The frame count MiniMax-H3's video VAE can decode: the next `17 * n + 5` at 24 fps."""
+    frames = max(1, round(float(seconds) * FPS))
+    while frames % FRAMES_PER_CHUNK != LATENTS_PER_CHUNK:
+        frames += 1
+    return frames
+
+
+def lower_duration_floor(seconds: float = MIN_UI_DURATION) -> None:
+    """Let the pipeline generate below its 5 s floor. 56 frames (2.33 s) is fine on the released checkpoint."""
+    from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MiniMaxH3ModularPipeline
+
+    MiniMaxH3ModularPipeline.min_duration = property(lambda self: float(seconds))
+
+
+OUTPUT_DIR = os.path.join(tempfile.gettempdir(), "h3-outputs")
+
+PIPE = None
+MANAGER = None
+LOAD_ERROR: str | None = None
+LOADED_IN: float | None = None
+LORA_STATUS: str | None = None
+
+
+def status() -> str:
+    if LOAD_ERROR:
+        return LOAD_ERROR
+    if PIPE is None:
+        return f"Loading `{MODEL_REPO}` (transformer + VAEs, 77.3 GB). Watch the Space logs."
+    import h3_aoti
+
+    return (
+        f"Ready · transformer + VAEs **bfloat16, unquantized** · placement `{PLACEMENT}` · attention `{ATTENTION}` · "
+        f"{h3_aoti.status()} · {LORA_STATUS or 'no LoRA'} · loaded in {LOADED_IN:.0f}s · "
+        f"conditioner `{CONDITIONER_SPACE}`"
+    )
+
+
+def load_models() -> str | None:
+    """Load the denoising half at startup.
+    `MiniMaxH3GeneratorBlocks` declares `transformer`, `vae`, `audio_vae`, the two schedulers and `video_processor`,
+    so `load_components` fetches exactly those subfolders — `text_encoder/` and `transformer_ref/` are never touched.
+    Both autoencoders carry `_keep_in_fp32_modules` over every module and stay float32: a bfloat16 audio VAE decodes
+    the soundtrack roughly 20 dB too quiet.
+    """
+    global PIPE, MANAGER, LOAD_ERROR, LOADED_IN, LORA_STATUS
+
+    if PIPE is not None or LOAD_ERROR is not None:
+        return LOAD_ERROR
+
+    started = time.time()
+    try:
+        import torch
+        from diffusers import ComponentsManager
+
+        from h3_split_blocks import MiniMaxH3GeneratorBlocks
+
+        lower_duration_floor()
+        manager = ComponentsManager()
+        blocks = MiniMaxH3GeneratorBlocks()
+        print(f"[gen] loading {[c.name for c in blocks.expected_components]} from {MODEL_REPO} ...", flush=True)
+        pipe = blocks.init_pipeline(MODEL_REPO, components_manager=manager, collection="h3")
+        pipe.load_components(dtype=torch.bfloat16)
+
+        # Fold the 4-step Turbo LoRA into the bf16 weights before AoTI packages the blocks, so the compiled forward
+        # reads weights that already carry the update. `H3_LORA=off` disables.
+        import h3_lora
+
+        LORA_STATUS = h3_lora.apply_lora(pipe.transformer)
+        if LORA_STATUS:
+            print(f"[gen] {LORA_STATUS}", flush=True)
+
+        pipe.transformer.set_attention_backend(ATTENTION)
+
+        # Still startup, still free: an AoTI package carries no weights and opens its archive lazily inside the GPU
+        # worker. Off unless `H3_AOTI=1`.
+        import h3_aoti
+
+        h3_aoti.maybe_load(pipe.transformer)
+
+        if PLACEMENT == "pack":
+            # Scoped to the transformer. `spaces` packs every startup-resident CUDA tensor into a second on-disk copy,
+            # and packing all 77.3 GB busts the 150 GB storage quota; the 61.7 GB transformer alone fits. The ~10 GB of
+            # fp32 VAEs move on the first GPU call instead.
+            pipe.transformer.to("cuda")
+
+        if PLACEMENT == "offload":
+            manager.enable_auto_cpu_offload(device="cuda")
+            _arm_decode_hooks(pipe)
+
+        PIPE, MANAGER = pipe, manager
+        LOADED_IN = time.time() - started
+        print(f"[gen] ready in {LOADED_IN:.0f}s", flush=True)
+    except Exception as error:
+        traceback.print_exc()
+        LOAD_ERROR = f"**Loading `{MODEL_REPO}` failed** after {time.time() - started:.0f}s: `{type(error).__name__}: {error}`"
+    return LOAD_ERROR
+
+
+def _arm_decode_hooks(pipe):
+    """Make the offload hooks fire for the two VAEs.
+    `enable_auto_cpu_offload` wraps `forward`, and the decode blocks call `vae.decode(...)` directly, so the hook
+    never runs and the VAE is still on the host when the latents arrive on the card.
+    """
+    for name in ("vae", "audio_vae"):
+        module = getattr(pipe, name)
+        inner = module.decode
+
+        def armed(*args, _module=module, _decode=inner, **kwargs):
+            hook = getattr(_module, "_hf_hook", None)
+            if hook is not None:
+                hook.pre_forward(_module)
+            return _decode(*args, **kwargs)
+
+        module.decode = armed
+
+
+@cache
+def conditioner():
+    """The other half, over the gradio API. Used only when the caller's token could not be extracted; the booking is
+    then billed to this Space's pod IP and its small shared quota."""
+    from gradio_client import Client
+
+    return Client(CONDITIONER_SPACE)
+
+
+def conditioner_client(ip_token):
+    """A conditioner client billed to the caller. `LocalContext`-based token forwarding is not reliable in Server
+    mode, so the `x-ip-token` header is extracted from the incoming request and passed explicitly (per the gradio
+    ZeroGPU docs); a per-request Client is cheap next to a 45s encode."""
+    if not ip_token:
+        return conditioner()
+    from gradio_client import Client
+
+    return Client(CONDITIONER_SPACE, headers={"x-ip-token": ip_token})
+
+
+def encode_remote(prompt, image_path, last_image_path, canvas, num_frames, rewrite_prompt=False, ip_token=None):
+    """`/encode` on the conditioner Space: a safetensors file holding `prompt_embeds` + `text_token_tags`, with the
+    resolved `height` / `width` / `num_frames` in its metadata, plus the plan. `canvas` is the label."""
+    from gradio_client import handle_file
+    from safetensors import safe_open
+
+    path, plan = conditioner_client(ip_token).predict(
+        prompt=prompt,
+        image_path=handle_file(image_path) if image_path else None,
+        last_image_path=handle_file(last_image_path) if last_image_path else None,
+        canvas=canvas,
+        num_frames=num_frames,
+        rewrite_prompt=bool(rewrite_prompt),
+        api_name="/encode",
+    )
+    with safe_open(path, framework="pt") as handle:
+        metadata = handle.metadata()
+        return handle.get_tensor("prompt_embeds"), handle.get_tensor("text_token_tags"), metadata, plan
+
+
+# Seconds of GPU one request needs, from the packed video rows it is about to denoise: linear in the rows for the
+# matmuls, quadratic for the attention, against the AoTI block package this Space runs.
+_DUR_B, _DUR_C = 1.1745e-4, 3.8396e-9
+# The two resident decoders and the mux, which scale with the output rather than with the step count.
+_DECODE_BASE, _DECODE_PER_DEFAULT_CANVAS, _DEFAULT_CANVAS_PIXELS = 15, 15, 960 * 544 * 124
+# `pack` mode: only the ~10 GB of VAEs move on a cold worker.
+_PLACEMENT_ALLOWANCE, _PAD = 12, 10
+
+
+def get_duration(prompt_embeds, text_token_tags, image, last_image, height, width, num_frames, steps, seed, lora="larry", *a, **k):
+    height, width, num_frames, steps = int(height), int(width), int(num_frames), int(steps)
+    latent_frames = (num_frames - LATENTS_PER_CHUNK) // FRAMES_PER_CHUNK * LATENTS_PER_CHUNK + 2
+    patches = (height // 32) * (width // 32)
+    rows = latent_frames * patches + (int(image is not None) + int(last_image is not None)) * patches
+    denoise = steps * (_DUR_B * rows + _DUR_C * rows**2)
+    decode = _DECODE_BASE + _DECODE_PER_DEFAULT_CANVAS * (height * width * num_frames) / _DEFAULT_CANVAS_PIXELS
+    return max(60, int(denoise + decode) + _PLACEMENT_ALLOWANCE + _PAD)
+
+
+@spaces.GPU(duration=get_duration, size=GPU_SIZE)
+def _generate(prompt_embeds, text_token_tags, image, last_image, height, width, num_frames, steps, seed, lora="larry"):
+    """The only thing on GPU time: the packed-sequence denoise loop and the two decoders.
+    Only the three generated outputs come back — a `@spaces.GPU` return crosses a process boundary by pickling, and
+    the full `PipelineState` still holds the packed latents, the rotary grid and the row indices on the card.
+    """
+    import torch
+
+    import h3_lora
+
+    # Fold the requested LoRA in place (a no-op when the state already matches). AoTI blocks read the same
+    # live storage, so the compiled forward carries the switch too.
+    active_lora = h3_lora.set_active(PIPE.transformer, lora)
+
+    if PLACEMENT == "lazy":
+        PIPE.to("cuda")
+    elif PLACEMENT == "pack":
+        PIPE.vae.to("cuda")
+        PIPE.audio_vae.to("cuda")
+
+    state = PIPE(
+        prompt_embeds=prompt_embeds.to("cuda"),
+        text_token_tags=text_token_tags,
+        image=image,
+        last_image=last_image,
+        height=height,
+        width=width,
+        num_frames=num_frames,
+        num_inference_steps=int(steps),
+        generator=torch.Generator("cpu").manual_seed(int(seed)),
+    )
+    return state.get("videos")[0], state.get("audio")[0].cpu(), state.get("sampling_rate"), active_lora
+
+
+def _fit_keyframe(image_path, current_canvas):
+    """Cover-crop an uploaded keyframe to the closest supported aspect ratio and pick that ratio's smallest
+    (fastest) canvas, unless the caller already picked a matching ratio. Returns `(image_path, canvas_label)`."""
+    from PIL import Image as _Image
+
+    img = _Image.open(image_path)
+    aspect = img.width / img.height
+    fastest = {}
+    for label, (h, w) in CANVASES.items():
+        r = w / h
+        if r not in fastest or w * h < fastest[r][1][0] * fastest[r][1][1]:
+            fastest[r] = (label, (h, w))
+    ratio = min(fastest, key=lambda r: abs(r - aspect))
+    label, (h, w) = fastest[ratio]
+
+    cur_h, cur_w = CANVASES[current_canvas]
+    if abs(cur_w / cur_h - aspect) <= abs(ratio - aspect):
+        label = current_canvas
+        h, w = cur_h, cur_w
+
+    target = w / h
+    if abs(img.width / img.height - target) > 1e-3:
+        if img.width / img.height > target:
+            new_w = int(img.height * target)
+            left = (img.width - new_w) // 2
+            img = img.crop((left, 0, left + new_w, img.height))
+        else:
+            new_h = int(img.width / target)
+            top = (img.height - new_h) // 2
+            img = img.crop((0, top, img.width, top + new_h))
+        img.save(image_path)
+    return image_path, label
+
+
+def _resolve_lora(lora, use_lora) -> str:
+    """`lora` (`larry` / `lightx` / `off`) wins; the legacy `use_lora` bool maps onto `larry` / `off`."""
+    if isinstance(lora, str) and lora in ("larry", "lightx", "off"):
+        return lora
+    return "larry" if use_lora else "off"
+
+
+def generate(prompt, image_path=None, last_image_path=None, canvas=DEFAULT_CANVAS, duration=5, steps=6, seed=42, upsample=False, use_lora=True, lora="", ip_token=None):
+    """One request. `upsample`/`use_lora` keep their defaults so a positional API client that predates them is unaffected."""
+    if LOAD_ERROR:
+        raise Exception(LOAD_ERROR)
+    if PIPE is None:
+        raise Exception("The denoiser is still loading.")
+    if not prompt or not prompt.strip():
+        raise Exception("MiniMax-H3 always takes a prompt, keyframes or not.")
+    
+    from PIL import Image, ImageOps
+
+    from diffusers.utils import encode_video
+
+    lora = _resolve_lora(lora, use_lora)
+
+    # Server mode: keyframes arrive as FileData dicts, and the cover-crop / canvas-fit that used to be an upload
+    # event in the Blocks UI runs here instead, so API callers get the same treatment.
+    first = image_path["path"] if isinstance(image_path, dict) else image_path
+    last = last_image_path["path"] if isinstance(last_image_path, dict) else last_image_path
+    if first:
+        first, canvas = _fit_keyframe(first, canvas)
+    if last:
+        last, canvas = _fit_keyframe(last, canvas)
+
+    num_frames = snap_frames(duration)
+
+    conditioned = time.time()
+    prompt_embeds, text_token_tags, metadata, plan = encode_remote(
+        prompt, first, last, canvas, num_frames, rewrite_prompt=upsample, ip_token=ip_token
+    )
+    condition_seconds = time.time() - conditioned
+    height, width, num_frames = (int(metadata[key]) for key in ("height", "width", "num_frames"))
+    refined = plan.get("refined_prompt") or ""
+
+    def keyframe(path):
+        # The conditioning latents encoded here have to be of the image the conditioner looked at, which it prepares
+        # exactly this way.
+        return ImageOps.exif_transpose(Image.open(path)).convert("RGB") if path else None
+
+    started = time.time()
+    frames, audio, sampling_rate, active_lora = _generate(
+        prompt_embeds,
+        text_token_tags,
+        keyframe(first),
+        keyframe(last),
+        height,
+        width,
+        num_frames,
+        steps,
+        seed,
+        lora,
+    )
+    generate_seconds = time.time() - started
+
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+    path = os.path.join(OUTPUT_DIR, f"h3-{int(time.time() * 1000)}.mp4")
+    encode_video(frames, fps=FPS, output_path=path, audio=audio, audio_sample_rate=sampling_rate)
+
+    report = (
+        f"{width}x{height} · {num_frames} frames ({num_frames / FPS:.3f} s) · {int(steps)} steps · "
+        f"conditioner {condition_seconds:.0f}s ({plan['num_text_tokens']} tokens"
+        f"{', upsampled' if refined else ''}) · "
+        f"denoise + decode {generate_seconds:.0f}s ({generate_seconds / int(steps):.1f} s/step) · "
+        f"turbo LoRA {active_lora} · seed {int(seed)}"
+    )
+    print(f"[gen] {report}", flush=True)
+    return FileData(path=path), report, refined
+
+
+
+# ======================================================================
+# Server mode: Gradio's API engine (queue, SSE, concurrency, ZeroGPU,
+# gradio_client) under a fully custom studio frontend (index.html).
+# ======================================================================
+app = Server(title="MiniMax-H3 Studio")
+
+
+@app.api(name="generate")
+def _generate_api(prompt: str, image_path: FileData | None = None, last_image_path: FileData | None = None,
+                  canvas: str = DEFAULT_CANVAS, duration: float = 5, steps: int = 6, seed: float = 42,
+                  upsample: bool = False, use_lora: bool = True, lora: str = "", request: Request = None) -> tuple[FileData, str, str]:
+    """Generate a video with a synchronized soundtrack. Returns (video, report, refined prompt).
+    `lora` selects the turbo LoRA: `larry` (default), `lightx`, or `off`. The legacy `use_lora` bool still works
+    when `lora` is empty.
+    """
+    # `request` is injected by the event system, not an API input; its x-ip-token bills the conditioner to the caller.
+    ip_token = request.headers.get("x-ip-token") if request is not None else None
+    return generate(prompt, image_path, last_image_path, canvas, duration, steps, seed, upsample, use_lora, lora, ip_token=ip_token)
+
+
+@app.get("/status")
+def studio_status():
+    """Polled by the frontend: is the denoiser ready, and the human-readable status line."""
+    return {"ready": PIPE is not None and LOAD_ERROR is None, "status": status()}
+
+
+# NB: not `/config` — Gradio's own client-discovery route lives there and shadowing it breaks `@gradio/client`.
+@app.get("/studio-config")
+def studio_config():
+    """The canvas table and slider ranges, so the frontend never hardcodes a label the backend would reject."""
+    import h3_lora
+
+    state = getattr(PIPE.transformer, "_lora_state", None) if PIPE is not None else None
+    sets = state["sets"] if state else {}
+    return {
+        "canvases": list(CANVASES),
+        "default_canvas": DEFAULT_CANVAS,
+        "min_duration": MIN_UI_DURATION,
+        "max_duration": MAX_UI_DURATION,
+        # The LoRA dropdown: value -> {label, suggested steps}.
+        "loras": {
+            **{
+                name: {"label": spec["label"], "steps": {"larry": 6, "lightx": 4}.get(name, 6)}
+                for name, spec in sets.items()
+            },
+            "off": {"label": "off (base model)", "steps": 28},
+        },
+        "default_lora": state["active"] if state else "off",
+    }
+
+
+@app.get("/", response_class=HTMLResponse)
+def homepage():
+    with open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "index.html"), encoding="utf-8") as f:
+        return f.read()
+
+
+import ncii_guard
+
+ncii_guard.start()
+load_models()
+
+if __name__ == "__main__":
+    # allowed_paths: the /gradio_api/file= route only serves whitelisted directories.
+    app.launch(show_error=True, allowed_paths=[OUTPUT_DIR])
     app.launch(server_name="0.0.0.0", server_port=7860)

h3_aoti.py

@@ -1,307 +1,307 @@
-"""ZeroGPU AoTI for MiniMax-H3: one compiled `MiniMaxH3TransformerBlock` package, reused by all 50 blocks.
-
-Shared byte-identically by every MiniMax-H3 Space. A Space only calls `maybe_load()`; the rest is the build path.
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-AOTI = os.environ.get("H3_AOTI", "0") == "1"
-AOTI_REPO = os.environ.get("H3_AOTI_REPO", "multimodalart/minimax-h3-aoti")
-AOTI_REPO_TYPE = os.environ.get("H3_AOTI_REPO_TYPE", "model")
-# A package is valid for exactly one `<width>/torch<X.Y>/sm<cc>/<shape>`, and a mismatched one segfaults rather than
-# raising, so `maybe_load` refuses anything but this key.
-AOTI_KEY = os.environ.get("H3_AOTI_KEY", "bf16/torch2.11/sm120/dynamic")
-# `dynamic` is the sequence dimension: `build_packed_sequence` pads nothing, so `S` moves with the prompt as well as
-# the canvas and a static package would serve one prompt length.
-AOTI_SHAPE = os.environ.get("H3_AOTI_SHAPE", "dynamic")
-AOTI_DURATION = int(os.environ.get("H3_AOTI_DURATION", "1500"))
-
-# Where a step spends its time. `MiniMaxH3TokenRefinerBlock` is also repeated but runs a handful of text rows.
-BLOCK_CONTAINER = "transformer_blocks"
-
-# Height of the AdaLN table baked into the package. `temb` grows from 1 row (step 0, both streams at one noise level)
-# to 2 (from step 1, sigmas diverged), and the block gathers from `3 * rows`, so the row count is part of the compiled
-# shape and is pinned by padding on both sides of the compile. Must match the package's `H3_AOTI_TEMB_ROWS`.
-TEMB_ROWS = int(os.environ.get("H3_AOTI_TEMB_ROWS", "4"))
-
-_LOADED: set[int] = set()
-
-
-def pad_temb(temb, rows: int = TEMB_ROWS):
-    """Grow `temb` to exactly `rows` timestep rows by repeating its last one."""
-    present = temb.shape[0]
-    if present == rows:
-        return temb
-    if present > rows:
-        raise RuntimeError(
-            f"{present} distinct timesteps, but this AoTI package holds at most {rows}. "
-            f"Recompile with H3_AOTI_TEMB_ROWS>={present}."
-        )
-    import torch
-
-    return torch.cat([temb, temb[-1:].expand(rows - present, *temb.shape[1:])], dim=0)
-
-
-def width() -> str:
-    """Which transformer these artifacts belong to: `bf16`, `fp8`, `nvfp4`, ..."""
-    if explicit := os.environ.get("H3_WIDTH"):
-        return explicit.lower()
-    try:
-        import h3_core
-
-        return h3_core.WIDTH
-    except Exception:
-        return "bf16"
-
-
-def artifact_key() -> str | None:
-    """`<width>/torch<X.Y>/sm<cc>/<shape>` of the card this process is on, or `None` when there is no CUDA."""
-    try:
-        import torch
-
-        torch_version = ".".join(torch.__version__.split(".")[:2])
-        major, minor = torch.cuda.get_device_capability()
-    except Exception:
-        return None
-    return f"{width()}/torch{torch_version}/sm{major}{minor}/{AOTI_SHAPE}"
-
-
-def status() -> str:
-    return (
-        f"AoTI **on** · `{AOTI_REPO}` ({AOTI_REPO_TYPE}) · shape `{AOTI_SHAPE}`"
-        if AOTI
-        else "AoTI **off** (`H3_AOTI=1` to load compiled blocks)"
-    )
-
-
-def patch_blocks(transformer, package_dir) -> None:
-    """Point all 50 blocks at the one compiled package, binding each block's own weights on its first call.
-
-    `spaces.aoti_load_from_package_dir` with two changes. Weights are read on the first forward rather than at patch
-    time, because this runs at startup and `Module.to` later rebinds `param.data` to fresh CUDA tensors. And `temb` is
-    padded to the height the package was exported with — see `TEMB_ROWS`.
-    """
-    from spaces.zero.torch.aoti import LazyAOTIModel, _shallow_clone_module
-    from torch._functorch._aot_autograd.subclass_parametrization import unwrap_tensor_subclass_parameters
-
-    # `LazyAOTIModel` binds constants by name and silently keeps what it cannot match, which is a SIGSEGV rather than
-    # an error. The patch resolves anonymous names through the compile side's sidecar and raises if it still cannot.
-    try:
-        from spaces_constant_binding_patch import apply_spaces_constant_binding_patch
-
-        apply_spaces_constant_binding_patch()
-    except ImportError:
-        print("[h3-aoti] spaces_constant_binding_patch.py is missing; an unbindable constant would segfault", flush=True)
-
-    model = LazyAOTIModel(Path(package_dir) / "submodules" / BLOCK_CONTAINER / "package.pt2")
-
-    for block in getattr(transformer, BLOCK_CONTAINER):
-        bound: dict = {}
-
-        def forward(hidden_states, temb, *rest, _block=block, _bound=bound):
-            first = not _bound
-            if first:
-                clone = _shallow_clone_module(_block)
-                unwrap_tensor_subclass_parameters(clone)
-                _bound["weights"] = clone.state_dict()
-            return model(_bound["weights"], first, hidden_states, pad_temb(temb), *rest)
-
-        block.forward = forward
-    print(f"[h3-aoti] {len(getattr(transformer, BLOCK_CONTAINER))} blocks patched (temb padded to {TEMB_ROWS})", flush=True)
-
-
-def maybe_load(transformer) -> None:
-    """Patch the block stack with its compiled package, or leave it eager. Safe to call at **startup**.
-
-    Off unless `H3_AOTI=1`, and anything that does not line up — another card, another torch, no `spaces` AoTI
-    helpers, no published package — falls back to eager with one line rather than raising or segfaulting. Nothing here
-    touches a GPU: the download is CPU work and the `.pt2` is not opened until the first forward.
-    """
-    if not AOTI or id(transformer) in _LOADED:
-        return
-
-    key = artifact_key()
-    if key is None:
-        print("[h3-aoti] no CUDA device visible; running eager", flush=True)
-        return
-    if key != AOTI_KEY:
-        print(f"[h3-aoti] this card wants `{key}`, only `{AOTI_KEY}` is published; running eager", flush=True)
-        return
-
-    try:
-        from huggingface_hub import snapshot_download
-        from spaces.zero.torch.aoti import LazyAOTIModel  # noqa: F401
-    except Exception as error:
-        print(f"[h3-aoti] no AoTI loader here ({type(error).__name__}: {error}); running eager", flush=True)
-        return
-
-    print(f"[h3-aoti] loading {AOTI_REPO}:{key} ...", flush=True)
-    try:
-        local = snapshot_download(repo_id=AOTI_REPO, repo_type=AOTI_REPO_TYPE, allow_patterns=f"{key}/package/*")
-    except Exception as error:
-        print(f"[h3-aoti] {AOTI_REPO}:{key} unreachable ({type(error).__name__}: {error}); running eager", flush=True)
-        return
-    package_dir = Path(local) / key / "package"
-    if not package_dir.is_dir():
-        print(f"[h3-aoti] no package at `{AOTI_REPO}:{key}/package`; running eager", flush=True)
-        return
-
-    patch_blocks(transformer, package_dir)
-    _LOADED.add(id(transformer))
-    print(f"[h3-aoti] compiled blocks in place (temb padded to {TEMB_ROWS} rows)", flush=True)
-
-
-def export_block(pipe, height: int, width: int, num_frames: int, prompt: str):
-    """Capture one block call out of a real request and export it with a dynamic sequence dimension.
-
-    Runs on the GPU, after the transformer has been quantized and moved there: a package compiled for one
-    quantization mode is meaningless for another.
-    """
-    import torch
-    import spaces
-
-    import h3_core as h3
-
-    transformer = h3.transformer_of(pipe)
-    blocks = getattr(transformer, BLOCK_CONTAINER)
-
-    # Keep the widest `temb` over a short real run rather than `spaces.aoti_capture`'s first call, which is the
-    # 1-row one — see `TEMB_ROWS`.
-    original_forward = blocks[0].forward
-    widest = {"args": (), "kwargs": {}, "rows": -1}
-    seen = []
-
-    def recording(*args, **kwargs):
-        rows = int(args[1].shape[0]) if len(args) > 1 and hasattr(args[1], "shape") else -1
-        seen.append(rows)
-        if rows > widest["rows"]:
-            widest.update(args=args, kwargs=kwargs, rows=rows)
-        return original_forward(*args, **kwargs)
-
-    blocks[0].forward = recording
-    try:
-        pipe(
-            prompt=prompt,
-            height=height,
-            width=width,
-            num_frames=num_frames,
-            num_inference_steps=int(os.environ.get("H3_AOTI_CAPTURE_STEPS", "4")),
-            generator=torch.Generator("cpu").manual_seed(42),
-        )
-    finally:
-        blocks[0].forward = original_forward
-    call = type("Captured", (), widest)
-    if not call.args:
-        raise RuntimeError("Nothing was captured — the transformer block was never called.")
-    print(f"[h3-aoti] temb rows seen: {sorted(set(seen))}; exporting with {TEMB_ROWS} (padded)", flush=True)
-
-    # `block(hidden_states, temb, adaln_indices, rotary_emb, attention_mask)`, `attention_mask` being `None` for the
-    # padless sequences these pipelines build. Only the sequence is dynamic: `torch.export` specializes size-1
-    # dimensions unconditionally, so a `Dim` on `temb`'s rows cannot be expressed at all.
-    if AOTI_SHAPE == "dynamic":
-        sequence = torch.export.Dim("sequence", min=2048, max=262144)
-        dynamic_shapes = ({1: sequence}, None, {0: sequence}, ({0: sequence}, {0: sequence}), None)
-        dynamic_shapes = dynamic_shapes[: len(call.args)]
-    else:
-        dynamic_shapes = None
-
-    args = (call.args[0], pad_temb(call.args[1]), *call.args[2:])
-
-    # Export the **live** block, non-strict. A shallow clone under non-strict tracing lifts every weight twice — once
-    # named, once as an anonymous `CONSTANT_TENSOR` aliasing it — and the loader binds by name, so the compiled block
-    # dereferences constants nobody set. The clone is only for flattening tensor-subclass parameters, which inductor's
-    # constant handling cannot wrap back into a `Parameter`, and it needs `strict=True`.
-    from spaces.zero.torch.aoti import _shallow_clone_module
-    from torch._functorch._aot_autograd.subclass_parametrization import unwrap_tensor_subclass_parameters
-
-    subclassed = sorted({type(p).__name__ for p in blocks[0].parameters()} - {"Parameter"})
-    if subclassed:
-        block = _shallow_clone_module(blocks[0])
-        unwrap_tensor_subclass_parameters(block)
-        strict = True
-        print(f"[h3-aoti] tensor-subclass parameters {subclassed}: exporting a flattened clone, strict=True", flush=True)
-    else:
-        block = blocks[0]
-        strict = False
-        print("[h3-aoti] plain parameters: exporting the live block, non-strict", flush=True)
-
-    # `torch.export` only gives a lifted tensor a real FQN when it is a registered parameter or buffer; a plain
-    # attribute becomes an anonymous constant the loader can never match. Only ever on the clone, since this
-    # re-registers attributes and the live block is what the eager path runs.
-    if block is not blocks[0]:
-        try:
-            from spaces_constant_binding_patch import register_loose_tensors
-
-            if loose := register_loose_tensors(block):
-                print(f"[h3-aoti] re-registered {len(loose)} loose tensors as buffers: {loose[:6]}", flush=True)
-        except ImportError:
-            pass
-
-    print(f"[h3-aoti] exporting {type(blocks[0]).__name__}, shapes={AOTI_SHAPE}, strict={strict} ...", flush=True)
-    try:
-        exported = torch.export.export(block, args, call.kwargs or None, dynamic_shapes=dynamic_shapes, strict=strict)
-    except Exception as error:
-        if not strict:
-            raise
-        print(f"[h3-aoti] strict export failed ({type(error).__name__}: {error}); retrying non-strict", flush=True)
-        exported = torch.export.export(block, args, call.kwargs or None, dynamic_shapes=dynamic_shapes)
-
-    anonymous = [
-        spec.target for spec in exported.graph_signature.input_specs if spec.kind.name == "CONSTANT_TENSOR"
-    ]
-    if anonymous:
-        print(
-            f"[h3-aoti] WARNING {len(anonymous)} constants lifted anonymously: {anonymous[:6]}. The loader binds by "
-            f"name, so `compile_and_save` writes the alias sidecar and `patch_blocks` raises rather than segfaulting.",
-            flush=True,
-        )
-    return exported
-
-
-def compile_and_save(exported_program, destination: str | os.PathLike[str]) -> Path:
-    """Inductor-compile the exported block into `<destination>/package/submodules/transformer_blocks/package.pt2`.
-
-    That layout is what `aoti_load_from_package_dir` walks, resolving the submodule name to the transformer's
-    `transformer_blocks` `ModuleList` and patching every block in it with this one package.
-    """
-    import spaces
-
-    package_dir = Path(destination) / "package"
-    print("[h3-aoti] inductor compile (minutes) ...", flush=True)
-    spaces.aoti_compile_and_save(package_dir, exported_program, submodule=BLOCK_CONTAINER)
-
-    # The compiled artifact drops a constant's FQN when the export lifted it anonymously; the `ExportedProgram` still
-    # has the real names, so record the mapping for the loader while it is available.
-    try:
-        from spaces_constant_binding_patch import write_constant_aliases
-
-        if sidecar := write_constant_aliases(package_dir, exported_program, submodule=BLOCK_CONTAINER):
-            print(f"[h3-aoti] constant alias sidecar written: {sidecar.name}", flush=True)
-    except ImportError:
-        pass
-
-    files = sorted(str(path.relative_to(package_dir)) for path in package_dir.rglob("*") if path.is_file())
-    print(f"[h3-aoti] package written: {files}", flush=True)
-    return package_dir
-
-
-def upload(package_dir: str | os.PathLike[str], key: str) -> str:
-    """Push the package under its `<width>/torch<X.Y>/sm<cc>/<shape>` key. CPU work — never inside GPU time."""
-    from huggingface_hub import HfApi
-
-    token = os.environ.get("HF_TOKEN")
-    if not token:
-        raise RuntimeError("`HF_TOKEN` is needed to push the AoTI package.")
-    api = HfApi(token=token)
-    api.create_repo(repo_id=AOTI_REPO, repo_type=AOTI_REPO_TYPE, private=False, exist_ok=True)
-    api.upload_folder(
-        folder_path=str(package_dir),
-        path_in_repo=f"{key}/package",
-        repo_id=AOTI_REPO,
-        repo_type=AOTI_REPO_TYPE,
-        commit_message=f"AoTI package for {key}",
-    )
-    return f"https://huggingface.co/{'datasets/' if AOTI_REPO_TYPE == 'dataset' else ''}{AOTI_REPO}/tree/main/{key}"
+"""ZeroGPU AoTI for MiniMax-H3: one compiled `MiniMaxH3TransformerBlock` package, reused by all 50 blocks.
+
+Shared byte-identically by every MiniMax-H3 Space. A Space only calls `maybe_load()`; the rest is the build path.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+AOTI = os.environ.get("H3_AOTI", "0") == "1"
+AOTI_REPO = os.environ.get("H3_AOTI_REPO", "multimodalart/minimax-h3-aoti")
+AOTI_REPO_TYPE = os.environ.get("H3_AOTI_REPO_TYPE", "model")
+# A package is valid for exactly one `<width>/torch<X.Y>/sm<cc>/<shape>`, and a mismatched one segfaults rather than
+# raising, so `maybe_load` refuses anything but this key.
+AOTI_KEY = os.environ.get("H3_AOTI_KEY", "bf16/torch2.11/sm120/dynamic")
+# `dynamic` is the sequence dimension: `build_packed_sequence` pads nothing, so `S` moves with the prompt as well as
+# the canvas and a static package would serve one prompt length.
+AOTI_SHAPE = os.environ.get("H3_AOTI_SHAPE", "dynamic")
+AOTI_DURATION = int(os.environ.get("H3_AOTI_DURATION", "1500"))
+
+# Where a step spends its time. `MiniMaxH3TokenRefinerBlock` is also repeated but runs a handful of text rows.
+BLOCK_CONTAINER = "transformer_blocks"
+
+# Height of the AdaLN table baked into the package. `temb` grows from 1 row (step 0, both streams at one noise level)
+# to 2 (from step 1, sigmas diverged), and the block gathers from `3 * rows`, so the row count is part of the compiled
+# shape and is pinned by padding on both sides of the compile. Must match the package's `H3_AOTI_TEMB_ROWS`.
+TEMB_ROWS = int(os.environ.get("H3_AOTI_TEMB_ROWS", "4"))
+
+_LOADED: set[int] = set()
+
+
+def pad_temb(temb, rows: int = TEMB_ROWS):
+    """Grow `temb` to exactly `rows` timestep rows by repeating its last one."""
+    present = temb.shape[0]
+    if present == rows:
+        return temb
+    if present > rows:
+        raise RuntimeError(
+            f"{present} distinct timesteps, but this AoTI package holds at most {rows}. "
+            f"Recompile with H3_AOTI_TEMB_ROWS>={present}."
+        )
+    import torch
+
+    return torch.cat([temb, temb[-1:].expand(rows - present, *temb.shape[1:])], dim=0)
+
+
+def width() -> str:
+    """Which transformer these artifacts belong to: `bf16`, `fp8`, `nvfp4`, ..."""
+    if explicit := os.environ.get("H3_WIDTH"):
+        return explicit.lower()
+    try:
+        import h3_core
+
+        return h3_core.WIDTH
+    except Exception:
+        return "bf16"
+
+
+def artifact_key() -> str | None:
+    """`<width>/torch<X.Y>/sm<cc>/<shape>` of the card this process is on, or `None` when there is no CUDA."""
+    try:
+        import torch
+
+        torch_version = ".".join(torch.__version__.split(".")[:2])
+        major, minor = torch.cuda.get_device_capability()
+    except Exception:
+        return None
+    return f"{width()}/torch{torch_version}/sm{major}{minor}/{AOTI_SHAPE}"
+
+
+def status() -> str:
+    return (
+        f"AoTI **on** · `{AOTI_REPO}` ({AOTI_REPO_TYPE}) · shape `{AOTI_SHAPE}`"
+        if AOTI
+        else "AoTI **off** (`H3_AOTI=1` to load compiled blocks)"
+    )
+
+
+def patch_blocks(transformer, package_dir) -> None:
+    """Point all 50 blocks at the one compiled package, binding each block's own weights on its first call.
+
+    `spaces.aoti_load_from_package_dir` with two changes. Weights are read on the first forward rather than at patch
+    time, because this runs at startup and `Module.to` later rebinds `param.data` to fresh CUDA tensors. And `temb` is
+    padded to the height the package was exported with — see `TEMB_ROWS`.
+    """
+    from spaces.zero.torch.aoti import LazyAOTIModel, _shallow_clone_module
+    from torch._functorch._aot_autograd.subclass_parametrization import unwrap_tensor_subclass_parameters
+
+    # `LazyAOTIModel` binds constants by name and silently keeps what it cannot match, which is a SIGSEGV rather than
+    # an error. The patch resolves anonymous names through the compile side's sidecar and raises if it still cannot.
+    try:
+        from spaces_constant_binding_patch import apply_spaces_constant_binding_patch
+
+        apply_spaces_constant_binding_patch()
+    except ImportError:
+        print("[h3-aoti] spaces_constant_binding_patch.py is missing; an unbindable constant would segfault", flush=True)
+
+    model = LazyAOTIModel(Path(package_dir) / "submodules" / BLOCK_CONTAINER / "package.pt2")
+
+    for block in getattr(transformer, BLOCK_CONTAINER):
+        bound: dict = {}
+
+        def forward(hidden_states, temb, *rest, _block=block, _bound=bound):
+            first = not _bound
+            if first:
+                clone = _shallow_clone_module(_block)
+                unwrap_tensor_subclass_parameters(clone)
+                _bound["weights"] = clone.state_dict()
+            return model(_bound["weights"], first, hidden_states, pad_temb(temb), *rest)
+
+        block.forward = forward
+    print(f"[h3-aoti] {len(getattr(transformer, BLOCK_CONTAINER))} blocks patched (temb padded to {TEMB_ROWS})", flush=True)
+
+
+def maybe_load(transformer) -> None:
+    """Patch the block stack with its compiled package, or leave it eager. Safe to call at **startup**.
+
+    Off unless `H3_AOTI=1`, and anything that does not line up — another card, another torch, no `spaces` AoTI
+    helpers, no published package — falls back to eager with one line rather than raising or segfaulting. Nothing here
+    touches a GPU: the download is CPU work and the `.pt2` is not opened until the first forward.
+    """
+    if not AOTI or id(transformer) in _LOADED:
+        return
+
+    key = artifact_key()
+    if key is None:
+        print("[h3-aoti] no CUDA device visible; running eager", flush=True)
+        return
+    if key != AOTI_KEY:
+        print(f"[h3-aoti] this card wants `{key}`, only `{AOTI_KEY}` is published; running eager", flush=True)
+        return
+
+    try:
+        from huggingface_hub import snapshot_download
+        from spaces.zero.torch.aoti import LazyAOTIModel  # noqa: F401
+    except Exception as error:
+        print(f"[h3-aoti] no AoTI loader here ({type(error).__name__}: {error}); running eager", flush=True)
+        return
+
+    print(f"[h3-aoti] loading {AOTI_REPO}:{key} ...", flush=True)
+    try:
+        local = snapshot_download(repo_id=AOTI_REPO, repo_type=AOTI_REPO_TYPE, allow_patterns=f"{key}/package/*")
+    except Exception as error:
+        print(f"[h3-aoti] {AOTI_REPO}:{key} unreachable ({type(error).__name__}: {error}); running eager", flush=True)
+        return
+    package_dir = Path(local) / key / "package"
+    if not package_dir.is_dir():
+        print(f"[h3-aoti] no package at `{AOTI_REPO}:{key}/package`; running eager", flush=True)
+        return
+
+    patch_blocks(transformer, package_dir)
+    _LOADED.add(id(transformer))
+    print(f"[h3-aoti] compiled blocks in place (temb padded to {TEMB_ROWS} rows)", flush=True)
+
+
+def export_block(pipe, height: int, width: int, num_frames: int, prompt: str):
+    """Capture one block call out of a real request and export it with a dynamic sequence dimension.
+
+    Runs on the GPU, after the transformer has been quantized and moved there: a package compiled for one
+    quantization mode is meaningless for another.
+    """
+    import torch
+    import spaces
+
+    import h3_core as h3
+
+    transformer = h3.transformer_of(pipe)
+    blocks = getattr(transformer, BLOCK_CONTAINER)
+
+    # Keep the widest `temb` over a short real run rather than `spaces.aoti_capture`'s first call, which is the
+    # 1-row one — see `TEMB_ROWS`.
+    original_forward = blocks[0].forward
+    widest = {"args": (), "kwargs": {}, "rows": -1}
+    seen = []
+
+    def recording(*args, **kwargs):
+        rows = int(args[1].shape[0]) if len(args) > 1 and hasattr(args[1], "shape") else -1
+        seen.append(rows)
+        if rows > widest["rows"]:
+            widest.update(args=args, kwargs=kwargs, rows=rows)
+        return original_forward(*args, **kwargs)
+
+    blocks[0].forward = recording
+    try:
+        pipe(
+            prompt=prompt,
+            height=height,
+            width=width,
+            num_frames=num_frames,
+            num_inference_steps=int(os.environ.get("H3_AOTI_CAPTURE_STEPS", "4")),
+            generator=torch.Generator("cpu").manual_seed(42),
+        )
+    finally:
+        blocks[0].forward = original_forward
+    call = type("Captured", (), widest)
+    if not call.args:
+        raise RuntimeError("Nothing was captured — the transformer block was never called.")
+    print(f"[h3-aoti] temb rows seen: {sorted(set(seen))}; exporting with {TEMB_ROWS} (padded)", flush=True)
+
+    # `block(hidden_states, temb, adaln_indices, rotary_emb, attention_mask)`, `attention_mask` being `None` for the
+    # padless sequences these pipelines build. Only the sequence is dynamic: `torch.export` specializes size-1
+    # dimensions unconditionally, so a `Dim` on `temb`'s rows cannot be expressed at all.
+    if AOTI_SHAPE == "dynamic":
+        sequence = torch.export.Dim("sequence", min=2048, max=262144)
+        dynamic_shapes = ({1: sequence}, None, {0: sequence}, ({0: sequence}, {0: sequence}), None)
+        dynamic_shapes = dynamic_shapes[: len(call.args)]
+    else:
+        dynamic_shapes = None
+
+    args = (call.args[0], pad_temb(call.args[1]), *call.args[2:])
+
+    # Export the **live** block, non-strict. A shallow clone under non-strict tracing lifts every weight twice — once
+    # named, once as an anonymous `CONSTANT_TENSOR` aliasing it — and the loader binds by name, so the compiled block
+    # dereferences constants nobody set. The clone is only for flattening tensor-subclass parameters, which inductor's
+    # constant handling cannot wrap back into a `Parameter`, and it needs `strict=True`.
+    from spaces.zero.torch.aoti import _shallow_clone_module
+    from torch._functorch._aot_autograd.subclass_parametrization import unwrap_tensor_subclass_parameters
+
+    subclassed = sorted({type(p).__name__ for p in blocks[0].parameters()} - {"Parameter"})
+    if subclassed:
+        block = _shallow_clone_module(blocks[0])
+        unwrap_tensor_subclass_parameters(block)
+        strict = True
+        print(f"[h3-aoti] tensor-subclass parameters {subclassed}: exporting a flattened clone, strict=True", flush=True)
+    else:
+        block = blocks[0]
+        strict = False
+        print("[h3-aoti] plain parameters: exporting the live block, non-strict", flush=True)
+
+    # `torch.export` only gives a lifted tensor a real FQN when it is a registered parameter or buffer; a plain
+    # attribute becomes an anonymous constant the loader can never match. Only ever on the clone, since this
+    # re-registers attributes and the live block is what the eager path runs.
+    if block is not blocks[0]:
+        try:
+            from spaces_constant_binding_patch import register_loose_tensors
+
+            if loose := register_loose_tensors(block):
+                print(f"[h3-aoti] re-registered {len(loose)} loose tensors as buffers: {loose[:6]}", flush=True)
+        except ImportError:
+            pass
+
+    print(f"[h3-aoti] exporting {type(blocks[0]).__name__}, shapes={AOTI_SHAPE}, strict={strict} ...", flush=True)
+    try:
+        exported = torch.export.export(block, args, call.kwargs or None, dynamic_shapes=dynamic_shapes, strict=strict)
+    except Exception as error:
+        if not strict:
+            raise
+        print(f"[h3-aoti] strict export failed ({type(error).__name__}: {error}); retrying non-strict", flush=True)
+        exported = torch.export.export(block, args, call.kwargs or None, dynamic_shapes=dynamic_shapes)
+
+    anonymous = [
+        spec.target for spec in exported.graph_signature.input_specs if spec.kind.name == "CONSTANT_TENSOR"
+    ]
+    if anonymous:
+        print(
+            f"[h3-aoti] WARNING {len(anonymous)} constants lifted anonymously: {anonymous[:6]}. The loader binds by "
+            f"name, so `compile_and_save` writes the alias sidecar and `patch_blocks` raises rather than segfaulting.",
+            flush=True,
+        )
+    return exported
+
+
+def compile_and_save(exported_program, destination: str | os.PathLike[str]) -> Path:
+    """Inductor-compile the exported block into `<destination>/package/submodules/transformer_blocks/package.pt2`.
+
+    That layout is what `aoti_load_from_package_dir` walks, resolving the submodule name to the transformer's
+    `transformer_blocks` `ModuleList` and patching every block in it with this one package.
+    """
+    import spaces
+
+    package_dir = Path(destination) / "package"
+    print("[h3-aoti] inductor compile (minutes) ...", flush=True)
+    spaces.aoti_compile_and_save(package_dir, exported_program, submodule=BLOCK_CONTAINER)
+
+    # The compiled artifact drops a constant's FQN when the export lifted it anonymously; the `ExportedProgram` still
+    # has the real names, so record the mapping for the loader while it is available.
+    try:
+        from spaces_constant_binding_patch import write_constant_aliases
+
+        if sidecar := write_constant_aliases(package_dir, exported_program, submodule=BLOCK_CONTAINER):
+            print(f"[h3-aoti] constant alias sidecar written: {sidecar.name}", flush=True)
+    except ImportError:
+        pass
+
+    files = sorted(str(path.relative_to(package_dir)) for path in package_dir.rglob("*") if path.is_file())
+    print(f"[h3-aoti] package written: {files}", flush=True)
+    return package_dir
+
+
+def upload(package_dir: str | os.PathLike[str], key: str) -> str:
+    """Push the package under its `<width>/torch<X.Y>/sm<cc>/<shape>` key. CPU work — never inside GPU time."""
+    from huggingface_hub import HfApi
+
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        raise RuntimeError("`HF_TOKEN` is needed to push the AoTI package.")
+    api = HfApi(token=token)
+    api.create_repo(repo_id=AOTI_REPO, repo_type=AOTI_REPO_TYPE, private=False, exist_ok=True)
+    api.upload_folder(
+        folder_path=str(package_dir),
+        path_in_repo=f"{key}/package",
+        repo_id=AOTI_REPO,
+        repo_type=AOTI_REPO_TYPE,
+        commit_message=f"AoTI package for {key}",
+    )
+    return f"https://huggingface.co/{'datasets/' if AOTI_REPO_TYPE == 'dataset' else ''}{AOTI_REPO}/tree/main/{key}"

h3_lora.py

@@ -1,172 +1,172 @@
-"""Turbo LoRA support for the diffusers MiniMax-H3 transformer: two 4-step LoRAs, one fold mechanism.
-
-Both LoRAs are applied by folding `scale * (lora_B @ lora_A)` into the bf16 weights rather than as runtime wrappers,
-because the AoTI block package (`h3_aoti`) reads each block's live weights and a wrapper module would be invisible
-to it. Deltas are computed in float32 and round once on the way back into bf16. The low-rank factors of every loaded
-LoRA stay resident, so the active one can be switched per request (`set_active`) — unfold the old, fold the new, in
-place, through one bf16 rounding.
-
-The two supported LoRAs ship in different layouts:
-
-* `larry` (`larryvrh/MiniMax-H3-Turbo-Lora`) targets the *reference* (ComfyUI) module tree — `blocks.N.attn.qkv_proj`,
-  `blocks.N.mlp.fc1`, `token_refiner.blocks.N`, `final_layer.adaln_proj.linear` — with `alpha == rank` (scale 1).
-  Each delta gets the same transform the base weights got in the diffusers conversion
-  (`scripts/convert_minimax_h3_to_diffusers.py`, huggingface/diffusers#14371): fused-QKV row thirds onto
-  `attn.to_q/k/v`, the `SwiGLU` gate/value swap onto `ff.net.0.proj`, `fc2` -> `ff.net.2`,
-  `blocks.` -> `transformer_blocks.`, `token_refiner.blocks.` -> `token_refiner.refiner_blocks.`,
-  `final_layer.adaln_proj.linear` -> `norm_out.linear`. The row transforms are applied to `lora_B` directly
-  (rows of `B @ A` are rows of `B`), so no full delta is ever materialized at load.
-
-* `lightx` (`lightx2v/Minimax-h3-Turbo`) is a PEFT checkpoint against the diffusers tree itself —
-  `transformer_blocks.N.attn.to_q.lora_A.default.weight` and friends — rank 128, `alpha == 8`, so the fold scale is
-  `8 / 128 = 0.0625` (matching `set_adapters(weights=1.0)` in their inference script). Keys map name-for-name.
-
-`H3_LORA` selects the larry file (`off` skips loading it), `H3_LIGHTX=off` skips lightx, `H3_LORA_DEFAULT` picks
-which set starts folded, and `H3_LORA_STRENGTH` is the larry card's sharpness/artifact dial.
-"""
-
-from __future__ import annotations
-
-import os
-
-import torch
-
-LARRY_REPO = os.environ.get("H3_LORA_REPO", "larryvrh/MiniMax-H3-Turbo-Lora")
-# The recommended default per the model card: ckpt850 EMA (final checkpoint of the round, sharp at 4 steps).
-LARRY_FILE = os.environ.get("H3_LORA", "minimax_h3_turbo_4step_ema_ckpt850.safetensors")
-LIGHTX_REPO = os.environ.get("H3_LIGHTX_REPO", "lightx2v/Minimax-h3-Turbo")
-LIGHTX_FILE = os.environ.get("H3_LIGHTX_FILE", "minimax_h3_fl2v_turbo_4step_v0.1.safetensors")
-LIGHTX_ALPHA = 8
-# The card's sharpness/artifact dial for the larry LoRA: >1 against blurry ghosting/smear, <1 against grain.
-LARRY_STRENGTH = float(os.environ.get("H3_LORA_STRENGTH", "1.0"))
-DEFAULT_LORA = os.environ.get("H3_LORA_DEFAULT", "larry")
-
-
-def _larry_targets(name: str, b: torch.Tensor, inner_dim: int) -> list[tuple[str, torch.Tensor]]:
-    """Map one reference-tree base name and its `lora_B` onto diffusers parameter key + row-transformed B."""
-    if name.startswith("token_refiner.blocks."):
-        target = name.replace("token_refiner.blocks.", "token_refiner.refiner_blocks.", 1)
-    elif name.startswith("blocks."):
-        target = name.replace("blocks.", "transformer_blocks.", 1)
-    else:
-        target = name
-    target = target.replace("final_layer.adaln_proj.linear", "norm_out.linear")
-
-    if target.endswith(".attn.qkv_proj"):
-        prefix = target.removesuffix("qkv_proj")
-        return [
-            (f"{prefix}to_{kind}.weight", part.contiguous())
-            for kind, part in zip(("q", "k", "v"), b.split(inner_dim, dim=0))
-        ]
-    if target.endswith(".mlp.fc1"):
-        gate, value = b.chunk(2, dim=0)
-        return [(target.replace(".mlp.fc1", ".ff.net.0.proj") + ".weight", torch.cat([value, gate]).contiguous())]
-    if target.endswith(".mlp.fc2"):
-        return [(target.replace(".mlp.fc2", ".ff.net.2") + ".weight", b)]
-    if target.endswith(".attn.out_proj"):
-        return [(target.replace(".attn.out_proj", ".attn.to_out.0") + ".weight", b)]
-    # `adaln_proj.linear` (block-level and the final `norm_out.linear`): identical row layout on both sides.
-    return [(target + ".weight", b)]
-
-
-def _load_larry(inner_dim: int) -> dict:
-    from huggingface_hub import hf_hub_download
-    from safetensors.torch import load_file
-
-    lora = load_file(hf_hub_download(LARRY_REPO, LARRY_FILE))
-    bases = sorted({key.rsplit(".lora_", 1)[0] for key in lora})
-    entries = []
-    for name in bases:
-        a = lora[f"{name}.lora_A.weight"]
-        b = lora[f"{name}.lora_B.weight"]
-        entries.extend((key, a, b_part) for key, b_part in _larry_targets(name, b, inner_dim))
-    return {
-        "label": f"{LARRY_REPO}/{LARRY_FILE}",
-        "scale": LARRY_STRENGTH,  # alpha == rank, so the base scale is 1
-        "entries": entries,
-    }
-
-
-def _load_lightx() -> dict:
-    from huggingface_hub import hf_hub_download
-    from safetensors.torch import load_file
-
-    lora = load_file(hf_hub_download(LIGHTX_REPO, LIGHTX_FILE))
-    suffix_a, suffix_b = ".lora_A.default.weight", ".lora_B.default.weight"
-    bases = sorted({key[: -len(suffix_a)] for key in lora if key.endswith(suffix_a)})
-    ranks = {lora[f"{name}{suffix_a}"].shape[0] for name in bases}
-    if len(ranks) != 1:
-        raise ValueError(f"Mixed LoRA ranks in {LIGHTX_FILE}: {sorted(ranks)}")
-    entries = [(f"{name}.weight", lora[f"{name}{suffix_a}"], lora[f"{name}{suffix_b}"]) for name in bases]
-    return {
-        "label": f"{LIGHTX_REPO}/{LIGHTX_FILE}",
-        "scale": LIGHTX_ALPHA / ranks.pop(),
-        "entries": entries,
-    }
-
-
-def _apply(entries, params, sign: float) -> None:
-    for key, a, b in entries:
-        param = params.get(key)
-        if param is None:
-            raise KeyError(f"LoRA target `{key}` not found in the transformer")
-        delta = sign * (b.to(torch.float32) @ a.to(torch.float32))
-        param.data = (param.data.float() + delta.to(param.device)).to(param.dtype)
-
-
-def available() -> list[str]:
-    """The LoRA sets that were loaded at startup, plus `off`."""
-    state = getattr(_PIPE_TRANSFORMER, "_lora_state", None) if _PIPE_TRANSFORMER is not None else None
-    return sorted(state["sets"]) + ["off"] if state else ["off"]
-
-
-_PIPE_TRANSFORMER = None
-
-
-def apply_lora(transformer) -> str | None:
-    """Load every enabled LoRA set, fold the default one into `transformer`, and stash the factors for per-request
-    switching. Returns a status line, or `None` when everything is disabled."""
-    global _PIPE_TRANSFORMER
-    _PIPE_TRANSFORMER = transformer
-
-    inner_dim = transformer.config.num_attention_heads * transformer.config.attention_head_dim
-    sets = {}
-    if LARRY_FILE.lower() not in ("", "off", "none"):
-        sets["larry"] = _load_larry(inner_dim)
-    if os.environ.get("H3_LIGHTX", "on").lower() not in ("", "off", "none"):
-        sets["lightx"] = _load_lightx()
-    if not sets:
-        return None
-
-    active = DEFAULT_LORA if DEFAULT_LORA in sets else sorted(sets)[0]
-    params = dict(transformer.named_parameters())
-    _apply(sets[active]["entries"], params, sets[active]["scale"])
-    transformer._lora_state = {"active": active, "sets": sets}
-    return (
-        f"LoRAs loaded: "
-        + ", ".join(f"`{name}` ({spec['label']}, {len(spec['entries'])} weights)" for name, spec in sets.items())
-        + f" · active `{active}`"
-    )
-
-
-def set_active(transformer, name: str) -> str:
-    """Switch the folded LoRA in place. No-op when the state already matches. Returns the active set."""
-    state = getattr(transformer, "_lora_state", None)
-    if state is None:
-        return "off"
-    name = name if name in state["sets"] else "off"
-    if state["active"] == name:
-        return name
-    params = dict(transformer.named_parameters())
-    if state["active"] != "off":
-        old = state["sets"][state["active"]]
-        _apply(old["entries"], params, -old["scale"])
-    if name != "off":
-        _apply(state["sets"][name]["entries"], params, state["sets"][name]["scale"])
-    state["active"] = name
-    return name
-
-
-def set_enabled(transformer, enabled: bool) -> bool:
-    """Backwards-compatible boolean toggle over the default set."""
-    return set_active(transformer, DEFAULT_LORA if enabled else "off") != "off"
+"""Turbo LoRA support for the diffusers MiniMax-H3 transformer: two 4-step LoRAs, one fold mechanism.
+
+Both LoRAs are applied by folding `scale * (lora_B @ lora_A)` into the bf16 weights rather than as runtime wrappers,
+because the AoTI block package (`h3_aoti`) reads each block's live weights and a wrapper module would be invisible
+to it. Deltas are computed in float32 and round once on the way back into bf16. The low-rank factors of every loaded
+LoRA stay resident, so the active one can be switched per request (`set_active`) — unfold the old, fold the new, in
+place, through one bf16 rounding.
+
+The two supported LoRAs ship in different layouts:
+
+* `larry` (`larryvrh/MiniMax-H3-Turbo-Lora`) targets the *reference* (ComfyUI) module tree — `blocks.N.attn.qkv_proj`,
+  `blocks.N.mlp.fc1`, `token_refiner.blocks.N`, `final_layer.adaln_proj.linear` — with `alpha == rank` (scale 1).
+  Each delta gets the same transform the base weights got in the diffusers conversion
+  (`scripts/convert_minimax_h3_to_diffusers.py`, huggingface/diffusers#14371): fused-QKV row thirds onto
+  `attn.to_q/k/v`, the `SwiGLU` gate/value swap onto `ff.net.0.proj`, `fc2` -> `ff.net.2`,
+  `blocks.` -> `transformer_blocks.`, `token_refiner.blocks.` -> `token_refiner.refiner_blocks.`,
+  `final_layer.adaln_proj.linear` -> `norm_out.linear`. The row transforms are applied to `lora_B` directly
+  (rows of `B @ A` are rows of `B`), so no full delta is ever materialized at load.
+
+* `lightx` (`lightx2v/Minimax-h3-Turbo`) is a PEFT checkpoint against the diffusers tree itself —
+  `transformer_blocks.N.attn.to_q.lora_A.default.weight` and friends — rank 128, `alpha == 8`, so the fold scale is
+  `8 / 128 = 0.0625` (matching `set_adapters(weights=1.0)` in their inference script). Keys map name-for-name.
+
+`H3_LORA` selects the larry file (`off` skips loading it), `H3_LIGHTX=off` skips lightx, `H3_LORA_DEFAULT` picks
+which set starts folded, and `H3_LORA_STRENGTH` is the larry card's sharpness/artifact dial.
+"""
+
+from __future__ import annotations
+
+import os
+
+import torch
+
+LARRY_REPO = os.environ.get("H3_LORA_REPO", "larryvrh/MiniMax-H3-Turbo-Lora")
+# The recommended default per the model card: ckpt850 EMA (final checkpoint of the round, sharp at 4 steps).
+LARRY_FILE = os.environ.get("H3_LORA", "minimax_h3_turbo_4step_ema_ckpt850.safetensors")
+LIGHTX_REPO = os.environ.get("H3_LIGHTX_REPO", "lightx2v/Minimax-h3-Turbo")
+LIGHTX_FILE = os.environ.get("H3_LIGHTX_FILE", "minimax_h3_fl2v_turbo_4step_v0.1.safetensors")
+LIGHTX_ALPHA = 8
+# The card's sharpness/artifact dial for the larry LoRA: >1 against blurry ghosting/smear, <1 against grain.
+LARRY_STRENGTH = float(os.environ.get("H3_LORA_STRENGTH", "1.0"))
+DEFAULT_LORA = os.environ.get("H3_LORA_DEFAULT", "larry")
+
+
+def _larry_targets(name: str, b: torch.Tensor, inner_dim: int) -> list[tuple[str, torch.Tensor]]:
+    """Map one reference-tree base name and its `lora_B` onto diffusers parameter key + row-transformed B."""
+    if name.startswith("token_refiner.blocks."):
+        target = name.replace("token_refiner.blocks.", "token_refiner.refiner_blocks.", 1)
+    elif name.startswith("blocks."):
+        target = name.replace("blocks.", "transformer_blocks.", 1)
+    else:
+        target = name
+    target = target.replace("final_layer.adaln_proj.linear", "norm_out.linear")
+
+    if target.endswith(".attn.qkv_proj"):
+        prefix = target.removesuffix("qkv_proj")
+        return [
+            (f"{prefix}to_{kind}.weight", part.contiguous())
+            for kind, part in zip(("q", "k", "v"), b.split(inner_dim, dim=0))
+        ]
+    if target.endswith(".mlp.fc1"):
+        gate, value = b.chunk(2, dim=0)
+        return [(target.replace(".mlp.fc1", ".ff.net.0.proj") + ".weight", torch.cat([value, gate]).contiguous())]
+    if target.endswith(".mlp.fc2"):
+        return [(target.replace(".mlp.fc2", ".ff.net.2") + ".weight", b)]
+    if target.endswith(".attn.out_proj"):
+        return [(target.replace(".attn.out_proj", ".attn.to_out.0") + ".weight", b)]
+    # `adaln_proj.linear` (block-level and the final `norm_out.linear`): identical row layout on both sides.
+    return [(target + ".weight", b)]
+
+
+def _load_larry(inner_dim: int) -> dict:
+    from huggingface_hub import hf_hub_download
+    from safetensors.torch import load_file
+
+    lora = load_file(hf_hub_download(LARRY_REPO, LARRY_FILE))
+    bases = sorted({key.rsplit(".lora_", 1)[0] for key in lora})
+    entries = []
+    for name in bases:
+        a = lora[f"{name}.lora_A.weight"]
+        b = lora[f"{name}.lora_B.weight"]
+        entries.extend((key, a, b_part) for key, b_part in _larry_targets(name, b, inner_dim))
+    return {
+        "label": f"{LARRY_REPO}/{LARRY_FILE}",
+        "scale": LARRY_STRENGTH,  # alpha == rank, so the base scale is 1
+        "entries": entries,
+    }
+
+
+def _load_lightx() -> dict:
+    from huggingface_hub import hf_hub_download
+    from safetensors.torch import load_file
+
+    lora = load_file(hf_hub_download(LIGHTX_REPO, LIGHTX_FILE))
+    suffix_a, suffix_b = ".lora_A.default.weight", ".lora_B.default.weight"
+    bases = sorted({key[: -len(suffix_a)] for key in lora if key.endswith(suffix_a)})
+    ranks = {lora[f"{name}{suffix_a}"].shape[0] for name in bases}
+    if len(ranks) != 1:
+        raise ValueError(f"Mixed LoRA ranks in {LIGHTX_FILE}: {sorted(ranks)}")
+    entries = [(f"{name}.weight", lora[f"{name}{suffix_a}"], lora[f"{name}{suffix_b}"]) for name in bases]
+    return {
+        "label": f"{LIGHTX_REPO}/{LIGHTX_FILE}",
+        "scale": LIGHTX_ALPHA / ranks.pop(),
+        "entries": entries,
+    }
+
+
+def _apply(entries, params, sign: float) -> None:
+    for key, a, b in entries:
+        param = params.get(key)
+        if param is None:
+            raise KeyError(f"LoRA target `{key}` not found in the transformer")
+        delta = sign * (b.to(torch.float32) @ a.to(torch.float32))
+        param.data = (param.data.float() + delta.to(param.device)).to(param.dtype)
+
+
+def available() -> list[str]:
+    """The LoRA sets that were loaded at startup, plus `off`."""
+    state = getattr(_PIPE_TRANSFORMER, "_lora_state", None) if _PIPE_TRANSFORMER is not None else None
+    return sorted(state["sets"]) + ["off"] if state else ["off"]
+
+
+_PIPE_TRANSFORMER = None
+
+
+def apply_lora(transformer) -> str | None:
+    """Load every enabled LoRA set, fold the default one into `transformer`, and stash the factors for per-request
+    switching. Returns a status line, or `None` when everything is disabled."""
+    global _PIPE_TRANSFORMER
+    _PIPE_TRANSFORMER = transformer
+
+    inner_dim = transformer.config.num_attention_heads * transformer.config.attention_head_dim
+    sets = {}
+    if LARRY_FILE.lower() not in ("", "off", "none"):
+        sets["larry"] = _load_larry(inner_dim)
+    if os.environ.get("H3_LIGHTX", "on").lower() not in ("", "off", "none"):
+        sets["lightx"] = _load_lightx()
+    if not sets:
+        return None
+
+    active = DEFAULT_LORA if DEFAULT_LORA in sets else sorted(sets)[0]
+    params = dict(transformer.named_parameters())
+    _apply(sets[active]["entries"], params, sets[active]["scale"])
+    transformer._lora_state = {"active": active, "sets": sets}
+    return (
+        f"LoRAs loaded: "
+        + ", ".join(f"`{name}` ({spec['label']}, {len(spec['entries'])} weights)" for name, spec in sets.items())
+        + f" · active `{active}`"
+    )
+
+
+def set_active(transformer, name: str) -> str:
+    """Switch the folded LoRA in place. No-op when the state already matches. Returns the active set."""
+    state = getattr(transformer, "_lora_state", None)
+    if state is None:
+        return "off"
+    name = name if name in state["sets"] else "off"
+    if state["active"] == name:
+        return name
+    params = dict(transformer.named_parameters())
+    if state["active"] != "off":
+        old = state["sets"][state["active"]]
+        _apply(old["entries"], params, -old["scale"])
+    if name != "off":
+        _apply(state["sets"][name]["entries"], params, state["sets"][name]["scale"])
+    state["active"] = name
+    return name
+
+
+def set_enabled(transformer, enabled: bool) -> bool:
+    """Backwards-compatible boolean toggle over the default set."""
+    return set_active(transformer, DEFAULT_LORA if enabled else "off") != "off"

h3_split_blocks.py

@@ -1,147 +1,147 @@
-"""The halves of a **split** MiniMax-H3 deployment, for both of its checkpoint partitions.
-
-MiniMax-H3 is 195.9 GiB in bfloat16 and a ZeroGPU Space is evicted at 150 GB of storage, so `MiniMaxH3Blocks` is cut
-at its `text_encoder` step: the 62.14 GiB Qwen3-VL runs in the conditioner Space, everything else in a generator
-Space, and `prompt_embeds` + `text_token_tags` is the whole wire format between them.
-
-`resize` / `setup` run on **both** sides: they own no pretrained component, and each half needs the canvas and the
-prepared keyframes or normalized references. Both conditioner halves also return the resolved `height` / `width` /
-`num_frames`, which the generating half pins rather than re-deriving.
-
-Two things the blocks leave to the caller: a keyframe reaches them EXIF-transposed and in RGB, and the `t2va` / `fl2va`
-frame count is aligned to `17 * n + 5` before the call, since that arithmetic lives on the denoising side of the cut.
-"""
-
-from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
-from diffusers.modular_pipelines.minimax_h3.decoders import MiniMaxH3AfterDenoiseStep
-from diffusers.modular_pipelines.minimax_h3.encoders import (
-    MiniMaxH3Ref2VAReferenceEncoderStep,
-    MiniMaxH3Ref2VATextEncoderStep,
-    MiniMaxH3TextEncoderStep,
-)
-from diffusers.modular_pipelines.minimax_h3.modular_blocks_minimax_h3 import (
-    MiniMaxH3AutoKeyframeVaeEncoderStep,
-    MiniMaxH3AutoResizeStep,
-    MiniMaxH3CoreDenoiseStep,
-    MiniMaxH3DecodeStep,
-    MiniMaxH3Ref2VACoreDenoiseStep,
-    _generation_outputs,
-)
-from diffusers.modular_pipelines.modular_pipeline import SequentialPipelineBlocks
-from diffusers.modular_pipelines.modular_pipeline_utils import OutputParam
-
-
-def _wire_outputs(num_frames: bool = True) -> list[OutputParam]:
-    """The wire format of the split. `num_frames` is declared by the `ref2va` half alone, whose setup resolves one."""
-    return [
-        OutputParam.template("prompt_embeds"),
-        OutputParam("text_token_tags", description="The per-row modality tag of every row of `prompt_embeds`."),
-        OutputParam("height", type_hint=int, description="Resolved height of the generated video in pixels."),
-        OutputParam("width", type_hint=int, description="Resolved width of the generated video in pixels."),
-        *(
-            [OutputParam("num_frames", type_hint=int, description="Resolved number of frames, of the form 17 * n + 5.")]
-            if num_frames
-            else []
-        ),
-    ]
-
-
-class MiniMaxH3ConditionerBlocks(SequentialPipelineBlocks):
-    """The conditioner half of a split MiniMax-H3: the keyframes on the canvas plus the Qwen3-VL read at layer 50."""
-
-    model_name = "minimax-h3"
-    block_classes = [MiniMaxH3AutoResizeStep, MiniMaxH3TextEncoderStep]
-    block_names = ["resize", "text_encoder"]
-
-    @property
-    def description(self):
-        return (
-            "The conditioner half of a split MiniMax-H3 deployment: puts the keyframes onto the target canvas and "
-            "encodes MiniMax-H3's presentation of the request into the `prompt_embeds` / `text_token_tags` pair the "
-            "denoising half consumes. The frame count is the caller's to align."
-        )
-
-    @property
-    def outputs(self):
-        return _wire_outputs(num_frames=False)
-
-
-class MiniMaxH3GeneratorBlocks(SequentialPipelineBlocks):
-    """The denoising half of a split MiniMax-H3: `MiniMaxH3Blocks` with its `text_encoder` step removed."""
-
-    model_name = "minimax-h3"
-    block_classes = [
-        MiniMaxH3AutoResizeStep,
-        MiniMaxH3AutoKeyframeVaeEncoderStep,
-        MiniMaxH3CoreDenoiseStep,
-        MiniMaxH3AfterDenoiseStep,
-        MiniMaxH3DecodeStep,
-    ]
-    block_names = ["resize", "vae_encoder", "denoise", "after_denoise", "decode"]
-
-    @property
-    def description(self):
-        return (
-            "The denoising half of a split MiniMax-H3 deployment: the `t2va` / `fl2va` branch of `MiniMaxH3Blocks` "
-            "without its text-encoder step, so `prompt_embeds` and `text_token_tags` come in as inputs and the "
-            "62.14 GiB Qwen3-VL conditioner is never loaded here."
-        )
-
-    @property
-    def outputs(self):
-        return _generation_outputs()
-
-
-class MiniMaxH3Ref2VAConditionerBlocks(SequentialPipelineBlocks):
-    """The conditioner half of a split `ref2va`: the resolved plan plus the Qwen3-VL read at its 50th layer.
-
-    Component for component this is `MiniMaxH3ConditionerBlocks`, so one conditioner Space serves both partitions.
-    What differs is the presentation: `ref2va` prepends a label per reference and a vision block per image and per
-    merged video frame pair, so the references themselves have to reach this half.
-    """
-
-    model_name = "minimax-h3"
-    block_classes = [MiniMaxH3Ref2VASetupStep, MiniMaxH3Ref2VATextEncoderStep]
-    block_names = ["setup", "text_encoder"]
-
-    @property
-    def description(self):
-        return (
-            "The conditioner half of a split MiniMax-H3 `ref2va` deployment: resolves the request plan (canvas, frame "
-            "count, references normalized onto MiniMax-H3's own rates and resolutions) and encodes MiniMax-H3's "
-            "presentation of it into the `prompt_embeds` / `text_token_tags` pair the denoising half consumes."
-        )
-
-    @property
-    def outputs(self):
-        return _wire_outputs()
-
-
-class MiniMaxH3Ref2VAGeneratorBlocks(SequentialPipelineBlocks):
-    """The denoising half of a split `ref2va`: the `ref2va` branch with its `text_encoder` step removed.
-
-    `reference_encoder` stays here, next to the two autoencoders it runs: its output shapes are where every reference
-    block's geometry in the packed layout comes from.
-    """
-
-    model_name = "minimax-h3"
-    block_classes = [
-        MiniMaxH3Ref2VASetupStep,
-        MiniMaxH3Ref2VAReferenceEncoderStep,
-        MiniMaxH3Ref2VACoreDenoiseStep,
-        MiniMaxH3AfterDenoiseStep,
-        MiniMaxH3DecodeStep,
-    ]
-    block_names = ["setup", "reference_encoder", "denoise", "after_denoise", "decode"]
-
-    @property
-    def description(self):
-        return (
-            "The denoising half of a split MiniMax-H3 `ref2va` deployment: the `ref2va` branch of `MiniMaxH3Blocks` "
-            "without its text-encoder step, so `prompt_embeds` and `text_token_tags` come in as inputs and the "
-            "62.14 GiB Qwen3-VL conditioner is never loaded here. The transformer is the `transformer_ref` partition."
-        )
-
-    @property
-    def outputs(self):
-        return _generation_outputs()
+"""The halves of a **split** MiniMax-H3 deployment, for both of its checkpoint partitions.
+
+MiniMax-H3 is 195.9 GiB in bfloat16 and a ZeroGPU Space is evicted at 150 GB of storage, so `MiniMaxH3Blocks` is cut
+at its `text_encoder` step: the 62.14 GiB Qwen3-VL runs in the conditioner Space, everything else in a generator
+Space, and `prompt_embeds` + `text_token_tags` is the whole wire format between them.
+
+`resize` / `setup` run on **both** sides: they own no pretrained component, and each half needs the canvas and the
+prepared keyframes or normalized references. Both conditioner halves also return the resolved `height` / `width` /
+`num_frames`, which the generating half pins rather than re-deriving.
+
+Two things the blocks leave to the caller: a keyframe reaches them EXIF-transposed and in RGB, and the `t2va` / `fl2va`
+frame count is aligned to `17 * n + 5` before the call, since that arithmetic lives on the denoising side of the cut.
+"""
+
+from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
+from diffusers.modular_pipelines.minimax_h3.decoders import MiniMaxH3AfterDenoiseStep
+from diffusers.modular_pipelines.minimax_h3.encoders import (
+    MiniMaxH3Ref2VAReferenceEncoderStep,
+    MiniMaxH3Ref2VATextEncoderStep,
+    MiniMaxH3TextEncoderStep,
+)
+from diffusers.modular_pipelines.minimax_h3.modular_blocks_minimax_h3 import (
+    MiniMaxH3AutoKeyframeVaeEncoderStep,
+    MiniMaxH3AutoResizeStep,
+    MiniMaxH3CoreDenoiseStep,
+    MiniMaxH3DecodeStep,
+    MiniMaxH3Ref2VACoreDenoiseStep,
+    _generation_outputs,
+)
+from diffusers.modular_pipelines.modular_pipeline import SequentialPipelineBlocks
+from diffusers.modular_pipelines.modular_pipeline_utils import OutputParam
+
+
+def _wire_outputs(num_frames: bool = True) -> list[OutputParam]:
+    """The wire format of the split. `num_frames` is declared by the `ref2va` half alone, whose setup resolves one."""
+    return [
+        OutputParam.template("prompt_embeds"),
+        OutputParam("text_token_tags", description="The per-row modality tag of every row of `prompt_embeds`."),
+        OutputParam("height", type_hint=int, description="Resolved height of the generated video in pixels."),
+        OutputParam("width", type_hint=int, description="Resolved width of the generated video in pixels."),
+        *(
+            [OutputParam("num_frames", type_hint=int, description="Resolved number of frames, of the form 17 * n + 5.")]
+            if num_frames
+            else []
+        ),
+    ]
+
+
+class MiniMaxH3ConditionerBlocks(SequentialPipelineBlocks):
+    """The conditioner half of a split MiniMax-H3: the keyframes on the canvas plus the Qwen3-VL read at layer 50."""
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3AutoResizeStep, MiniMaxH3TextEncoderStep]
+    block_names = ["resize", "text_encoder"]
+
+    @property
+    def description(self):
+        return (
+            "The conditioner half of a split MiniMax-H3 deployment: puts the keyframes onto the target canvas and "
+            "encodes MiniMax-H3's presentation of the request into the `prompt_embeds` / `text_token_tags` pair the "
+            "denoising half consumes. The frame count is the caller's to align."
+        )
+
+    @property
+    def outputs(self):
+        return _wire_outputs(num_frames=False)
+
+
+class MiniMaxH3GeneratorBlocks(SequentialPipelineBlocks):
+    """The denoising half of a split MiniMax-H3: `MiniMaxH3Blocks` with its `text_encoder` step removed."""
+
+    model_name = "minimax-h3"
+    block_classes = [
+        MiniMaxH3AutoResizeStep,
+        MiniMaxH3AutoKeyframeVaeEncoderStep,
+        MiniMaxH3CoreDenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
+        MiniMaxH3DecodeStep,
+    ]
+    block_names = ["resize", "vae_encoder", "denoise", "after_denoise", "decode"]
+
+    @property
+    def description(self):
+        return (
+            "The denoising half of a split MiniMax-H3 deployment: the `t2va` / `fl2va` branch of `MiniMaxH3Blocks` "
+            "without its text-encoder step, so `prompt_embeds` and `text_token_tags` come in as inputs and the "
+            "62.14 GiB Qwen3-VL conditioner is never loaded here."
+        )
+
+    @property
+    def outputs(self):
+        return _generation_outputs()
+
+
+class MiniMaxH3Ref2VAConditionerBlocks(SequentialPipelineBlocks):
+    """The conditioner half of a split `ref2va`: the resolved plan plus the Qwen3-VL read at its 50th layer.
+
+    Component for component this is `MiniMaxH3ConditionerBlocks`, so one conditioner Space serves both partitions.
+    What differs is the presentation: `ref2va` prepends a label per reference and a vision block per image and per
+    merged video frame pair, so the references themselves have to reach this half.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3Ref2VASetupStep, MiniMaxH3Ref2VATextEncoderStep]
+    block_names = ["setup", "text_encoder"]
+
+    @property
+    def description(self):
+        return (
+            "The conditioner half of a split MiniMax-H3 `ref2va` deployment: resolves the request plan (canvas, frame "
+            "count, references normalized onto MiniMax-H3's own rates and resolutions) and encodes MiniMax-H3's "
+            "presentation of it into the `prompt_embeds` / `text_token_tags` pair the denoising half consumes."
+        )
+
+    @property
+    def outputs(self):
+        return _wire_outputs()
+
+
+class MiniMaxH3Ref2VAGeneratorBlocks(SequentialPipelineBlocks):
+    """The denoising half of a split `ref2va`: the `ref2va` branch with its `text_encoder` step removed.
+
+    `reference_encoder` stays here, next to the two autoencoders it runs: its output shapes are where every reference
+    block's geometry in the packed layout comes from.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [
+        MiniMaxH3Ref2VASetupStep,
+        MiniMaxH3Ref2VAReferenceEncoderStep,
+        MiniMaxH3Ref2VACoreDenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
+        MiniMaxH3DecodeStep,
+    ]
+    block_names = ["setup", "reference_encoder", "denoise", "after_denoise", "decode"]
+
+    @property
+    def description(self):
+        return (
+            "The denoising half of a split MiniMax-H3 `ref2va` deployment: the `ref2va` branch of `MiniMaxH3Blocks` "
+            "without its text-encoder step, so `prompt_embeds` and `text_token_tags` come in as inputs and the "
+            "62.14 GiB Qwen3-VL conditioner is never loaded here. The transformer is the `transformer_ref` partition."
+        )
+
+    @property
+    def outputs(self):
+        return _generation_outputs()

index.html

@@ -1,478 +1,478 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>MiniMax-H3 Studio</title>
-<style>
-  :root {
-    --bg: #0b0d10;
-    --panel: #12151a;
-    --panel-2: #171b21;
-    --edge: #23282f;
-    --edge-hi: #31383f;
-    --text: #e8eaed;
-    --dim: #9aa3ad;
-    --faint: #5c6670;
-    --accent: #f59e0b;
-    --accent-dim: #92610a;
-    --go: #22c55e;
-    --err: #ef4444;
-    --mono: "SF Mono", ui-monospace, Menlo, Consolas, monospace;
-  }
-  * { margin: 0; box-sizing: border-box; }
-  body {
-    background: var(--bg); color: var(--text);
-    font: 14px/1.5 -apple-system, "Segoe UI", Inter, Roboto, sans-serif;
-    height: 100vh; display: flex; flex-direction: column; overflow: hidden;
-  }
-
-  /* ---- top bar ---- */
-  header {
-    display: flex; align-items: center; gap: 14px;
-    padding: 0 18px; height: 52px; flex: none;
-    background: var(--panel); border-bottom: 1px solid var(--edge);
-  }
-  .logo { font-weight: 700; letter-spacing: .4px; font-size: 15px; }
-  .logo b { color: var(--accent); }
-  .logo span { color: var(--faint); font-weight: 400; margin-left: 8px; font-size: 12px; }
-  header .links { margin-left: auto; display: flex; gap: 14px; align-items: center; }
-  header a { color: var(--dim); text-decoration: none; font-size: 12px; }
-  header a:hover { color: var(--text); }
-  #status-pill {
-    display: flex; align-items: center; gap: 7px;
-    font: 11px var(--mono); color: var(--dim);
-    border: 1px solid var(--edge); border-radius: 99px; padding: 4px 12px;
-    max-width: 46vw; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
-  }
-  #status-dot { width: 8px; height: 8px; border-radius: 50%; background: var(--accent); flex: none; animation: pulse 1.2s infinite; }
-  #status-pill.ready #status-dot { background: var(--go); animation: none; }
-  #status-pill.error #status-dot { background: var(--err); animation: none; }
-  @keyframes pulse { 50% { opacity: .35; } }
-
-  main { flex: 1; display: flex; min-height: 0; }
-
-  /* ---- control deck ---- */
-  aside {
-    width: 340px; flex: none; overflow-y: auto;
-    background: var(--panel); border-right: 1px solid var(--edge);
-    padding: 16px; display: flex; flex-direction: column; gap: 14px;
-  }
-  .deck-label {
-    font: 10px var(--mono); letter-spacing: 1.5px; color: var(--faint);
-    text-transform: uppercase; margin-bottom: 6px;
-  }
-  textarea, select, input[type=number] {
-    width: 100%; background: var(--panel-2); color: var(--text);
-    border: 1px solid var(--edge); border-radius: 8px;
-    padding: 10px 12px; font: 13px/1.5 inherit; resize: vertical;
-  }
-  textarea:focus, select:focus, input:focus { outline: none; border-color: var(--accent-dim); }
-  textarea { min-height: 96px; }
-
-  .dropzone {
-    border: 1.5px dashed var(--edge-hi); border-radius: 8px;
-    min-height: 74px; display: flex; align-items: center; justify-content: center;
-    color: var(--faint); font-size: 12px; cursor: pointer; position: relative;
-    overflow: hidden; text-align: center; padding: 6px; transition: border-color .15s;
-  }
-  .dropzone:hover, .dropzone.drag { border-color: var(--accent); color: var(--dim); }
-  .dropzone img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
-  .dropzone .clear {
-    position: absolute; top: 4px; right: 6px; z-index: 2; color: #fff;
-    background: rgba(0,0,0,.6); border-radius: 4px; padding: 0 6px; font-size: 14px; display: none;
-  }
-  .dropzone.filled .clear { display: block; }
-  .frames-row { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
-
-  .check { display: flex; align-items: center; gap: 8px; color: var(--dim); font-size: 13px; cursor: pointer; }
-  .check input { accent-color: var(--accent); }
-
-  details { border: 1px solid var(--edge); border-radius: 8px; background: var(--panel-2); }
-  summary {
-    padding: 9px 12px; cursor: pointer; font: 11px var(--mono);
-    letter-spacing: 1px; color: var(--dim); text-transform: uppercase; user-select: none;
-  }
-  details .body { padding: 4px 12px 12px; display: flex; flex-direction: column; gap: 12px; }
-  .slider-row { display: flex; justify-content: space-between; font-size: 12px; color: var(--dim); margin-bottom: 2px; }
-  .slider-row output { font-family: var(--mono); color: var(--text); }
-  input[type=range] { width: 100%; accent-color: var(--accent); }
-
-  #run {
-    margin-top: auto; border: none; border-radius: 8px; padding: 13px;
-    background: var(--accent); color: #111; font: 700 14px inherit;
-    letter-spacing: .5px; cursor: pointer; transition: filter .15s, opacity .15s;
-  }
-  #run:hover:not(:disabled) { filter: brightness(1.1); }
-  #run:disabled { opacity: .45; cursor: not-allowed; }
-
-  /* ---- stage ---- */
-  section.stage { flex: 1; display: flex; flex-direction: column; min-width: 0; }
-  .monitor-wrap {
-    flex: 1; display: flex; align-items: center; justify-content: center;
-    padding: 22px; min-height: 0;
-    background: radial-gradient(ellipse at 50% 40%, #10141a 0%, var(--bg) 75%);
-  }
-  .monitor {
-    position: relative; max-width: 100%; max-height: 100%;
-    border: 1px solid var(--edge-hi); border-radius: 10px; overflow: hidden;
-    background: #000; box-shadow: 0 24px 70px rgba(0,0,0,.55);
-    display: flex; align-items: center; justify-content: center;
-  }
-  .monitor video { display: block; max-width: 100%; max-height: calc(100vh - 220px); }
-  .monitor .placeholder {
-    position: absolute; inset: 0; display: flex; flex-direction: column;
-    align-items: center; justify-content: center; gap: 10px; color: var(--faint);
-    font: 12px var(--mono); letter-spacing: 1px; text-align: center; padding: 20px;
-  }
-  .monitor .placeholder .rec { width: 46px; height: 46px; border: 1.5px solid var(--edge-hi); border-radius: 50%;
-    display: flex; align-items: center; justify-content: center; }
-  .monitor .placeholder .rec::after { content: ""; width: 14px; height: 14px; border-radius: 50%; background: var(--edge-hi); }
-  .monitor.hidden-video video { display: none; }
-
-  /* ---- transport / report bar ---- */
-  .transport {
-    flex: none; border-top: 1px solid var(--edge); background: var(--panel);
-    padding: 10px 18px; display: flex; align-items: center; gap: 16px;
-    font: 12px var(--mono); color: var(--dim); min-height: 44px;
-  }
-  #job-state { color: var(--accent); }
-  #job-state.done { color: var(--go); }
-  #job-state.failed { color: var(--err); }
-  #report { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; flex: 1; }
-  #elapsed { color: var(--faint); flex: none; }
-
-  #bar-track {
-    flex: none; width: 180px; height: 6px; border-radius: 3px;
-    background: var(--edge); overflow: hidden; position: relative;
-  }
-  #bar { height: 100%; width: 0%; border-radius: 3px; background: var(--accent); transition: width .4s linear; }
-  #bar.indeterminate { width: 40%; animation: slide 1.2s ease-in-out infinite; }
-  @keyframes slide { 0% { margin-left: -40%; } 100% { margin-left: 100%; } }
-
-  #refined-bar {
-    flex: none; display: none; border-top: 1px solid var(--edge);
-    background: var(--panel-2); padding: 10px 18px; font-size: 12px; color: var(--dim);
-    max-height: 110px; overflow-y: auto;
-  }
-  #refined-bar b { color: var(--faint); font: 10px var(--mono); letter-spacing: 1px; text-transform: uppercase; display: block; margin-bottom: 4px; }
-
-  .examples { display: flex; flex-direction: column; gap: 6px; }
-  .examples button {
-    text-align: left; background: var(--panel-2); border: 1px solid var(--edge);
-    color: var(--dim); border-radius: 6px; padding: 7px 10px; font-size: 12px; cursor: pointer;
-  }
-  .examples button:hover { color: var(--text); border-color: var(--edge-hi); }
-
-  @media (max-width: 860px) {
-    body { height: 100dvh; overflow: hidden; }
-    main { flex-direction: column; overflow-y: auto; -webkit-overflow-scrolling: touch; }
-
-    /* Stage first, controls below: the monitor is what a phone user came for. */
-    section.stage { order: -1; flex: none; }
-    .monitor-wrap { padding: 12px; }
-    .monitor video { max-height: 38vh; }
-    .monitor .placeholder { position: static; padding: 42px 16px; }
-
-    aside {
-      width: 100%; flex: none; overflow: visible;
-      border-right: none; border-top: 1px solid var(--edge);
-      padding: 14px 14px 90px; /* room for the sticky run button */
-    }
-    #run {
-      position: sticky; bottom: 12px; z-index: 5;
-      padding: 15px; font-size: 15px;
-      box-shadow: 0 8px 24px rgba(0,0,0,.5);
-    }
-
-    /* Touch targets + kill iOS auto-zoom on focus (needs >=16px). */
-    textarea, select, input[type=number] { font-size: 16px; }
-    .dropzone { min-height: 92px; }
-    .check { padding: 6px 0; }
-    summary { padding: 12px; }
-    input[type=range] { height: 28px; }
-
-    header { padding: 0 12px; gap: 10px; }
-    .logo span { display: none; }
-    #status-pill { max-width: 38vw; padding: 4px 9px; }
-    header .links a { display: none; }
-    header .links #status-pill { display: flex; }
-
-    .transport { flex-wrap: wrap; gap: 8px 12px; padding: 10px 12px; }
-    #bar-track { flex: 1 1 100%; order: -1; width: auto; height: 5px; }
-    #report { white-space: normal; flex: 1 1 60%; font-size: 11px; }
-    #refined-bar { max-height: 80px; }
-  }
-  @media (max-width: 400px) {
-    .frames-row { grid-template-columns: 1fr; }
-  }
-</style>
-</head>
-<body>
-
-<header>
-  <div class="logo">MiniMax-<b>H3</b> Studio<span>video + synchronized soundtrack · 4-step turbo</span></div>
-  <div class="links">
-    <div id="status-pill"><span id="status-dot"></span><span id="status-text">connecting…</span></div>
-    <a href="https://huggingface.co/MiniMaxAI/MiniMax-H3" target="_blank" rel="noopener">model</a>
-    <a href="https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora" target="_blank" rel="noopener">turbo lora</a>
-  </div>
-</header>
-
-<main>
-  <aside>
-    <div>
-      <div class="deck-label">Prompt</div>
-      <textarea id="prompt" spellcheck="false">A red fox trotting through a snowy pine forest at dawn, snow crunching underfoot</textarea>
-    </div>
-    <div>
-      <div class="deck-label">Turbo LoRA</div>
-      <select id="lora"></select>
-    </div>
-    <label class="check"><input type="checkbox" id="upsample"> Upsample prompt</label>
-
-    <div>
-      <div class="deck-label">Keyframes (optional)</div>
-      <div class="frames-row">
-        <div class="dropzone" id="dz-first">First frame<span class="clear">×</span></div>
-        <div class="dropzone" id="dz-last">Last frame<span class="clear">×</span></div>
-      </div>
-    </div>
-
-    <details open>
-      <summary>Shot settings</summary>
-      <div class="body">
-        <div>
-          <div class="deck-label">Canvas</div>
-          <select id="canvas"></select>
-        </div>
-        <div>
-          <div class="slider-row"><span>Duration</span><output id="duration-out">5 s</output></div>
-          <input type="range" id="duration" min="2" max="14" step="1" value="5">
-        </div>
-        <div>
-          <div class="slider-row"><span>Steps</span><output id="steps-out">6</output></div>
-          <input type="range" id="steps" min="2" max="40" step="1" value="6">
-        </div>
-        <div>
-          <div class="deck-label">Seed</div>
-          <input type="number" id="seed" value="42" step="1">
-        </div>
-      </div>
-    </details>
-
-    <div>
-      <div class="deck-label">Examples</div>
-      <div class="examples" id="examples"></div>
-    </div>
-
-    <button id="run">▶&nbsp; Generate</button>
-  </aside>
-
-  <section class="stage">
-    <div class="monitor-wrap">
-      <div class="monitor hidden-video" id="monitor">
-        <video id="video" controls playsinline></video>
-        <div class="placeholder" id="placeholder">
-          <div class="rec"></div>
-          <div>STANDBY — CUT A PROMPT AND ROLL</div>
-        </div>
-      </div>
-    </div>
-    <div id="refined-bar"><b>Upsampled prompt</b><span id="refined"></span></div>
-    <div class="transport">
-      <span id="job-state">IDLE</span>
-      <div id="bar-track"><div id="bar"></div></div>
-      <span id="report"></span>
-      <span id="elapsed"></span>
-    </div>
-  </section>
-</main>
-
-<input type="file" id="file-first" accept="image/*" hidden>
-<input type="file" id="file-last" accept="image/*" hidden>
-
-<script type="module">
-// @gradio/client is REQUIRED here (not plain fetch): it forwards the HF iframe auth headers that ZeroGPU
-// quota handling depends on — without them every booking lands on the pod IP's shared quota.
-import { Client, handle_file } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
-
-const $ = (id) => document.getElementById(id);
-const state = { first: null, last: null, busy: false, timer: null };
-
-/* ---- config + status ---- */
-fetch("/studio-config").then(r => r.json()).then(cfg => {
-  const sel = $("canvas");
-  for (const label of cfg.canvases) {
-    const o = document.createElement("option");
-    o.value = o.textContent = label;
-    if (label === cfg.default_canvas) o.selected = true;
-    sel.appendChild(o);
-  }
-  $("duration").min = cfg.min_duration; $("duration").max = cfg.max_duration;
-
-  const loraSel = $("lora");
-  for (const [value, spec] of Object.entries(cfg.loras || { larry: { label: "larry", steps: 6 } })) {
-    const o = document.createElement("option");
-    o.value = value;
-    o.textContent = value === "off" ? "off (base model)" : value;
-    o.title = spec.label;
-    if (value === cfg.default_lora) o.selected = true;
-    loraSel.appendChild(o);
-  }
-  // Each LoRA has a design point: suggest it on switch (the slider stays free).
-  loraSel.addEventListener("change", () => {
-    const spec = (cfg.loras || {})[loraSel.value];
-    if (spec && spec.steps) { $("steps").value = spec.steps; $("steps-out").textContent = spec.steps; }
-  });
-});
-
-async function pollStatus() {
-  try {
-    const s = await (await fetch("/status")).json();
-    const pill = $("status-pill");
-    $("status-text").textContent = s.status.replace(/[*`]/g, "");
-    pill.classList.toggle("ready", s.ready);
-    pill.classList.toggle("error", !s.ready && /failed/i.test(s.status));
-    if (s.ready) return;
-  } catch (e) { /* still booting */ }
-  setTimeout(pollStatus, 5000);
-}
-pollStatus();
-
-/* ---- sliders ---- */
-const bind = (id, fmt) => $(id).addEventListener("input", e => $(id + "-out").textContent = fmt(e.target.value));
-bind("duration", v => v + " s");
-bind("steps", v => v);
-
-/* ---- dropzones ---- */
-function wireDropzone(dzId, inputId, key) {
-  const dz = $(dzId), input = $(inputId);
-  const set = (file) => {
-    if (!file) return;
-    state[key] = file;
-    const img = document.createElement("img");
-    img.src = URL.createObjectURL(file);
-    dz.appendChild(img);
-    dz.classList.add("filled");
-  };
-  dz.addEventListener("click", (e) => {
-    if (e.target.classList.contains("clear")) {
-      state[key] = null; dz.classList.remove("filled");
-      dz.querySelector("img")?.remove(); input.value = "";
-    } else input.click();
-  });
-  input.addEventListener("change", () => set(input.files[0]));
-  dz.addEventListener("dragover", e => { e.preventDefault(); dz.classList.add("drag"); });
-  dz.addEventListener("dragleave", () => dz.classList.remove("drag"));
-  dz.addEventListener("drop", e => { e.preventDefault(); dz.classList.remove("drag"); set(e.dataTransfer.files[0]); });
-}
-wireDropzone("dz-first", "file-first", "first");
-wireDropzone("dz-last", "file-last", "last");
-
-/* ---- examples ---- */
-const EXAMPLES = [
-  ["A red fox trotting through a snowy pine forest at dawn, snow crunching underfoot", "1344x768 · 16:9 full"],
-  ["A busy night market, neon signs reflecting in puddles, sizzling street food", "768x1344 · 9:16 full"],
-  ["A cellist playing a slow melody in an empty concert hall", "768x768 · 1:1 full"],
-  ["Waves crashing against basalt cliffs at golden hour, gulls crying overhead", "1152x640 · 16:9"],
-];
-for (const [p, c] of EXAMPLES) {
-  const b = document.createElement("button");
-  b.textContent = p.length > 60 ? p.slice(0, 60) + "…" : p;
-  b.title = p;
-  b.onclick = () => { $("prompt").value = p; $("canvas").value = c; };
-  $("examples").appendChild(b);
-}
-
-/* ---- generate ---- */
-const client = await Client.connect(window.location.origin, { events: ["data", "status"] });
-
-function setJob(label, cls) {
-  const el = $("job-state");
-  el.textContent = label; el.className = cls || "";
-}
-
-function setBar(pct) {
-  const bar = $("bar");
-  if (pct === null) { bar.className = "indeterminate"; return; }
-  bar.className = "";
-  bar.style.width = Math.max(0, Math.min(100, pct)) + "%";
-}
-
-$("run").addEventListener("click", async () => {
-  if (state.busy) return;
-  const prompt = $("prompt").value.trim();
-  if (!prompt) { setJob("FAILED", "failed"); $("report").textContent = "a prompt is required"; return; }
-
-  state.busy = true;
-  $("run").disabled = true;
-  $("refined-bar").style.display = "none";
-  $("report").textContent = "";
-  setJob("ROLLING", "");
-  const t0 = Date.now();
-  state.timer = setInterval(() => $("elapsed").textContent = ((Date.now() - t0) / 1000).toFixed(0) + "s", 500);
-
-  try {
-    const submission = client.submit("/generate", {
-      prompt,
-      image_path: state.first ? handle_file(state.first) : null,
-      last_image_path: state.last ? handle_file(state.last) : null,
-      canvas: $("canvas").value,
-      duration: Number($("duration").value),
-      steps: Number($("steps").value),
-      seed: Number($("seed").value),
-      upsample: $("upsample").checked,
-      lora: $("lora").value,
-    });
-    let data = null;
-    for await (const msg of submission) {
-      if (msg.type === "status") {
-        if (msg.stage === "pending") {
-          setJob(msg.position != null ? `QUEUED #${msg.position + 1}` : "QUEUED");
-          setBar(null);
-        } else if (msg.stage === "generating") {
-          setJob("ROLLING");
-          // ETA comes from the queue's booking estimate; blend it with our own elapsed timer.
-          if (msg.eta != null && msg.eta > 0) {
-            const elapsed = (Date.now() - t0) / 1000;
-            setBar(100 * elapsed / (elapsed + msg.eta));
-          } else setBar(null);
-        } else if (msg.stage === "error") {
-          throw new Error(msg.message || "generation failed");
-        }
-      } else if (msg.type === "data") {
-        data = msg.data;
-      }
-    }
-    if (!data) throw new Error("the backend returned no data");
-    // Server mode returns the tuple as ONE Api output: unwrap [[video, report, refined]] too.
-    if (data.length === 1 && Array.isArray(data[0])) data = data[0];
-    const [video, report, refined] = data;
-    // FileData may carry only `path`; resolve those through Gradio's file route.
-    const videoUrl = (video && (video.url || (video.path && `/gradio_api/file=${video.path}`)))
-      || (typeof video === "string" && `/gradio_api/file=${video}`);
-    if (!videoUrl) throw new Error("the backend returned no video reference");
-    $("video").src = videoUrl;
-    $("monitor").classList.remove("hidden-video");
-    $("placeholder").style.display = "none";
-    $("report").textContent = report;
-    if (refined) {
-      $("refined").textContent = refined;
-      $("refined-bar").style.display = "block";
-    }
-    setJob("DONE", "done");
-    setBar(100);
-  } catch (e) {
-    setJob("FAILED", "failed");
-    setBar(0);
-    $("report").textContent = (e && e.message) ? e.message.slice(0, 300) : String(e);
-  } finally {
-    clearInterval(state.timer);
-    state.busy = false;
-    $("run").disabled = false;
-  }
-});
-</script>
-</body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>MiniMax-H3 Studio</title>
+<style>
+  :root {
+    --bg: #0b0d10;
+    --panel: #12151a;
+    --panel-2: #171b21;
+    --edge: #23282f;
+    --edge-hi: #31383f;
+    --text: #e8eaed;
+    --dim: #9aa3ad;
+    --faint: #5c6670;
+    --accent: #f59e0b;
+    --accent-dim: #92610a;
+    --go: #22c55e;
+    --err: #ef4444;
+    --mono: "SF Mono", ui-monospace, Menlo, Consolas, monospace;
+  }
+  * { margin: 0; box-sizing: border-box; }
+  body {
+    background: var(--bg); color: var(--text);
+    font: 14px/1.5 -apple-system, "Segoe UI", Inter, Roboto, sans-serif;
+    height: 100vh; display: flex; flex-direction: column; overflow: hidden;
+  }
+
+  /* ---- top bar ---- */
+  header {
+    display: flex; align-items: center; gap: 14px;
+    padding: 0 18px; height: 52px; flex: none;
+    background: var(--panel); border-bottom: 1px solid var(--edge);
+  }
+  .logo { font-weight: 700; letter-spacing: .4px; font-size: 15px; }
+  .logo b { color: var(--accent); }
+  .logo span { color: var(--faint); font-weight: 400; margin-left: 8px; font-size: 12px; }
+  header .links { margin-left: auto; display: flex; gap: 14px; align-items: center; }
+  header a { color: var(--dim); text-decoration: none; font-size: 12px; }
+  header a:hover { color: var(--text); }
+  #status-pill {
+    display: flex; align-items: center; gap: 7px;
+    font: 11px var(--mono); color: var(--dim);
+    border: 1px solid var(--edge); border-radius: 99px; padding: 4px 12px;
+    max-width: 46vw; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  }
+  #status-dot { width: 8px; height: 8px; border-radius: 50%; background: var(--accent); flex: none; animation: pulse 1.2s infinite; }
+  #status-pill.ready #status-dot { background: var(--go); animation: none; }
+  #status-pill.error #status-dot { background: var(--err); animation: none; }
+  @keyframes pulse { 50% { opacity: .35; } }
+
+  main { flex: 1; display: flex; min-height: 0; }
+
+  /* ---- control deck ---- */
+  aside {
+    width: 340px; flex: none; overflow-y: auto;
+    background: var(--panel); border-right: 1px solid var(--edge);
+    padding: 16px; display: flex; flex-direction: column; gap: 14px;
+  }
+  .deck-label {
+    font: 10px var(--mono); letter-spacing: 1.5px; color: var(--faint);
+    text-transform: uppercase; margin-bottom: 6px;
+  }
+  textarea, select, input[type=number] {
+    width: 100%; background: var(--panel-2); color: var(--text);
+    border: 1px solid var(--edge); border-radius: 8px;
+    padding: 10px 12px; font: 13px/1.5 inherit; resize: vertical;
+  }
+  textarea:focus, select:focus, input:focus { outline: none; border-color: var(--accent-dim); }
+  textarea { min-height: 96px; }
+
+  .dropzone {
+    border: 1.5px dashed var(--edge-hi); border-radius: 8px;
+    min-height: 74px; display: flex; align-items: center; justify-content: center;
+    color: var(--faint); font-size: 12px; cursor: pointer; position: relative;
+    overflow: hidden; text-align: center; padding: 6px; transition: border-color .15s;
+  }
+  .dropzone:hover, .dropzone.drag { border-color: var(--accent); color: var(--dim); }
+  .dropzone img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+  .dropzone .clear {
+    position: absolute; top: 4px; right: 6px; z-index: 2; color: #fff;
+    background: rgba(0,0,0,.6); border-radius: 4px; padding: 0 6px; font-size: 14px; display: none;
+  }
+  .dropzone.filled .clear { display: block; }
+  .frames-row { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+
+  .check { display: flex; align-items: center; gap: 8px; color: var(--dim); font-size: 13px; cursor: pointer; }
+  .check input { accent-color: var(--accent); }
+
+  details { border: 1px solid var(--edge); border-radius: 8px; background: var(--panel-2); }
+  summary {
+    padding: 9px 12px; cursor: pointer; font: 11px var(--mono);
+    letter-spacing: 1px; color: var(--dim); text-transform: uppercase; user-select: none;
+  }
+  details .body { padding: 4px 12px 12px; display: flex; flex-direction: column; gap: 12px; }
+  .slider-row { display: flex; justify-content: space-between; font-size: 12px; color: var(--dim); margin-bottom: 2px; }
+  .slider-row output { font-family: var(--mono); color: var(--text); }
+  input[type=range] { width: 100%; accent-color: var(--accent); }
+
+  #run {
+    margin-top: auto; border: none; border-radius: 8px; padding: 13px;
+    background: var(--accent); color: #111; font: 700 14px inherit;
+    letter-spacing: .5px; cursor: pointer; transition: filter .15s, opacity .15s;
+  }
+  #run:hover:not(:disabled) { filter: brightness(1.1); }
+  #run:disabled { opacity: .45; cursor: not-allowed; }
+
+  /* ---- stage ---- */
+  section.stage { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+  .monitor-wrap {
+    flex: 1; display: flex; align-items: center; justify-content: center;
+    padding: 22px; min-height: 0;
+    background: radial-gradient(ellipse at 50% 40%, #10141a 0%, var(--bg) 75%);
+  }
+  .monitor {
+    position: relative; max-width: 100%; max-height: 100%;
+    border: 1px solid var(--edge-hi); border-radius: 10px; overflow: hidden;
+    background: #000; box-shadow: 0 24px 70px rgba(0,0,0,.55);
+    display: flex; align-items: center; justify-content: center;
+  }
+  .monitor video { display: block; max-width: 100%; max-height: calc(100vh - 220px); }
+  .monitor .placeholder {
+    position: absolute; inset: 0; display: flex; flex-direction: column;
+    align-items: center; justify-content: center; gap: 10px; color: var(--faint);
+    font: 12px var(--mono); letter-spacing: 1px; text-align: center; padding: 20px;
+  }
+  .monitor .placeholder .rec { width: 46px; height: 46px; border: 1.5px solid var(--edge-hi); border-radius: 50%;
+    display: flex; align-items: center; justify-content: center; }
+  .monitor .placeholder .rec::after { content: ""; width: 14px; height: 14px; border-radius: 50%; background: var(--edge-hi); }
+  .monitor.hidden-video video { display: none; }
+
+  /* ---- transport / report bar ---- */
+  .transport {
+    flex: none; border-top: 1px solid var(--edge); background: var(--panel);
+    padding: 10px 18px; display: flex; align-items: center; gap: 16px;
+    font: 12px var(--mono); color: var(--dim); min-height: 44px;
+  }
+  #job-state { color: var(--accent); }
+  #job-state.done { color: var(--go); }
+  #job-state.failed { color: var(--err); }
+  #report { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; flex: 1; }
+  #elapsed { color: var(--faint); flex: none; }
+
+  #bar-track {
+    flex: none; width: 180px; height: 6px; border-radius: 3px;
+    background: var(--edge); overflow: hidden; position: relative;
+  }
+  #bar { height: 100%; width: 0%; border-radius: 3px; background: var(--accent); transition: width .4s linear; }
+  #bar.indeterminate { width: 40%; animation: slide 1.2s ease-in-out infinite; }
+  @keyframes slide { 0% { margin-left: -40%; } 100% { margin-left: 100%; } }
+
+  #refined-bar {
+    flex: none; display: none; border-top: 1px solid var(--edge);
+    background: var(--panel-2); padding: 10px 18px; font-size: 12px; color: var(--dim);
+    max-height: 110px; overflow-y: auto;
+  }
+  #refined-bar b { color: var(--faint); font: 10px var(--mono); letter-spacing: 1px; text-transform: uppercase; display: block; margin-bottom: 4px; }
+
+  .examples { display: flex; flex-direction: column; gap: 6px; }
+  .examples button {
+    text-align: left; background: var(--panel-2); border: 1px solid var(--edge);
+    color: var(--dim); border-radius: 6px; padding: 7px 10px; font-size: 12px; cursor: pointer;
+  }
+  .examples button:hover { color: var(--text); border-color: var(--edge-hi); }
+
+  @media (max-width: 860px) {
+    body { height: 100dvh; overflow: hidden; }
+    main { flex-direction: column; overflow-y: auto; -webkit-overflow-scrolling: touch; }
+
+    /* Stage first, controls below: the monitor is what a phone user came for. */
+    section.stage { order: -1; flex: none; }
+    .monitor-wrap { padding: 12px; }
+    .monitor video { max-height: 38vh; }
+    .monitor .placeholder { position: static; padding: 42px 16px; }
+
+    aside {
+      width: 100%; flex: none; overflow: visible;
+      border-right: none; border-top: 1px solid var(--edge);
+      padding: 14px 14px 90px; /* room for the sticky run button */
+    }
+    #run {
+      position: sticky; bottom: 12px; z-index: 5;
+      padding: 15px; font-size: 15px;
+      box-shadow: 0 8px 24px rgba(0,0,0,.5);
+    }
+
+    /* Touch targets + kill iOS auto-zoom on focus (needs >=16px). */
+    textarea, select, input[type=number] { font-size: 16px; }
+    .dropzone { min-height: 92px; }
+    .check { padding: 6px 0; }
+    summary { padding: 12px; }
+    input[type=range] { height: 28px; }
+
+    header { padding: 0 12px; gap: 10px; }
+    .logo span { display: none; }
+    #status-pill { max-width: 38vw; padding: 4px 9px; }
+    header .links a { display: none; }
+    header .links #status-pill { display: flex; }
+
+    .transport { flex-wrap: wrap; gap: 8px 12px; padding: 10px 12px; }
+    #bar-track { flex: 1 1 100%; order: -1; width: auto; height: 5px; }
+    #report { white-space: normal; flex: 1 1 60%; font-size: 11px; }
+    #refined-bar { max-height: 80px; }
+  }
+  @media (max-width: 400px) {
+    .frames-row { grid-template-columns: 1fr; }
+  }
+</style>
+</head>
+<body>
+
+<header>
+  <div class="logo">MiniMax-<b>H3</b> Studio<span>video + synchronized soundtrack · 4-step turbo</span></div>
+  <div class="links">
+    <div id="status-pill"><span id="status-dot"></span><span id="status-text">connecting…</span></div>
+    <a href="https://huggingface.co/MiniMaxAI/MiniMax-H3" target="_blank" rel="noopener">model</a>
+    <a href="https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora" target="_blank" rel="noopener">turbo lora</a>
+  </div>
+</header>
+
+<main>
+  <aside>
+    <div>
+      <div class="deck-label">Prompt</div>
+      <textarea id="prompt" spellcheck="false">A red fox trotting through a snowy pine forest at dawn, snow crunching underfoot</textarea>
+    </div>
+    <div>
+      <div class="deck-label">Turbo LoRA</div>
+      <select id="lora"></select>
+    </div>
+    <label class="check"><input type="checkbox" id="upsample"> Upsample prompt</label>
+
+    <div>
+      <div class="deck-label">Keyframes (optional)</div>
+      <div class="frames-row">
+        <div class="dropzone" id="dz-first">First frame<span class="clear">×</span></div>
+        <div class="dropzone" id="dz-last">Last frame<span class="clear">×</span></div>
+      </div>
+    </div>
+
+    <details open>
+      <summary>Shot settings</summary>
+      <div class="body">
+        <div>
+          <div class="deck-label">Canvas</div>
+          <select id="canvas"></select>
+        </div>
+        <div>
+          <div class="slider-row"><span>Duration</span><output id="duration-out">5 s</output></div>
+          <input type="range" id="duration" min="2" max="14" step="1" value="5">
+        </div>
+        <div>
+          <div class="slider-row"><span>Steps</span><output id="steps-out">6</output></div>
+          <input type="range" id="steps" min="2" max="40" step="1" value="6">
+        </div>
+        <div>
+          <div class="deck-label">Seed</div>
+          <input type="number" id="seed" value="42" step="1">
+        </div>
+      </div>
+    </details>
+
+    <div>
+      <div class="deck-label">Examples</div>
+      <div class="examples" id="examples"></div>
+    </div>
+
+    <button id="run">▶&nbsp; Generate</button>
+  </aside>
+
+  <section class="stage">
+    <div class="monitor-wrap">
+      <div class="monitor hidden-video" id="monitor">
+        <video id="video" controls playsinline></video>
+        <div class="placeholder" id="placeholder">
+          <div class="rec"></div>
+          <div>STANDBY — CUT A PROMPT AND ROLL</div>
+        </div>
+      </div>
+    </div>
+    <div id="refined-bar"><b>Upsampled prompt</b><span id="refined"></span></div>
+    <div class="transport">
+      <span id="job-state">IDLE</span>
+      <div id="bar-track"><div id="bar"></div></div>
+      <span id="report"></span>
+      <span id="elapsed"></span>
+    </div>
+  </section>
+</main>
+
+<input type="file" id="file-first" accept="image/*" hidden>
+<input type="file" id="file-last" accept="image/*" hidden>
+
+<script type="module">
+// @gradio/client is REQUIRED here (not plain fetch): it forwards the HF iframe auth headers that ZeroGPU
+// quota handling depends on — without them every booking lands on the pod IP's shared quota.
+import { Client, handle_file } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
+
+const $ = (id) => document.getElementById(id);
+const state = { first: null, last: null, busy: false, timer: null };
+
+/* ---- config + status ---- */
+fetch("/studio-config").then(r => r.json()).then(cfg => {
+  const sel = $("canvas");
+  for (const label of cfg.canvases) {
+    const o = document.createElement("option");
+    o.value = o.textContent = label;
+    if (label === cfg.default_canvas) o.selected = true;
+    sel.appendChild(o);
+  }
+  $("duration").min = cfg.min_duration; $("duration").max = cfg.max_duration;
+
+  const loraSel = $("lora");
+  for (const [value, spec] of Object.entries(cfg.loras || { larry: { label: "larry", steps: 6 } })) {
+    const o = document.createElement("option");
+    o.value = value;
+    o.textContent = value === "off" ? "off (base model)" : value;
+    o.title = spec.label;
+    if (value === cfg.default_lora) o.selected = true;
+    loraSel.appendChild(o);
+  }
+  // Each LoRA has a design point: suggest it on switch (the slider stays free).
+  loraSel.addEventListener("change", () => {
+    const spec = (cfg.loras || {})[loraSel.value];
+    if (spec && spec.steps) { $("steps").value = spec.steps; $("steps-out").textContent = spec.steps; }
+  });
+});
+
+async function pollStatus() {
+  try {
+    const s = await (await fetch("/status")).json();
+    const pill = $("status-pill");
+    $("status-text").textContent = s.status.replace(/[*`]/g, "");
+    pill.classList.toggle("ready", s.ready);
+    pill.classList.toggle("error", !s.ready && /failed/i.test(s.status));
+    if (s.ready) return;
+  } catch (e) { /* still booting */ }
+  setTimeout(pollStatus, 5000);
+}
+pollStatus();
+
+/* ---- sliders ---- */
+const bind = (id, fmt) => $(id).addEventListener("input", e => $(id + "-out").textContent = fmt(e.target.value));
+bind("duration", v => v + " s");
+bind("steps", v => v);
+
+/* ---- dropzones ---- */
+function wireDropzone(dzId, inputId, key) {
+  const dz = $(dzId), input = $(inputId);
+  const set = (file) => {
+    if (!file) return;
+    state[key] = file;
+    const img = document.createElement("img");
+    img.src = URL.createObjectURL(file);
+    dz.appendChild(img);
+    dz.classList.add("filled");
+  };
+  dz.addEventListener("click", (e) => {
+    if (e.target.classList.contains("clear")) {
+      state[key] = null; dz.classList.remove("filled");
+      dz.querySelector("img")?.remove(); input.value = "";
+    } else input.click();
+  });
+  input.addEventListener("change", () => set(input.files[0]));
+  dz.addEventListener("dragover", e => { e.preventDefault(); dz.classList.add("drag"); });
+  dz.addEventListener("dragleave", () => dz.classList.remove("drag"));
+  dz.addEventListener("drop", e => { e.preventDefault(); dz.classList.remove("drag"); set(e.dataTransfer.files[0]); });
+}
+wireDropzone("dz-first", "file-first", "first");
+wireDropzone("dz-last", "file-last", "last");
+
+/* ---- examples ---- */
+const EXAMPLES = [
+  ["A red fox trotting through a snowy pine forest at dawn, snow crunching underfoot", "1344x768 · 16:9 full"],
+  ["A busy night market, neon signs reflecting in puddles, sizzling street food", "768x1344 · 9:16 full"],
+  ["A cellist playing a slow melody in an empty concert hall", "768x768 · 1:1 full"],
+  ["Waves crashing against basalt cliffs at golden hour, gulls crying overhead", "1152x640 · 16:9"],
+];
+for (const [p, c] of EXAMPLES) {
+  const b = document.createElement("button");
+  b.textContent = p.length > 60 ? p.slice(0, 60) + "…" : p;
+  b.title = p;
+  b.onclick = () => { $("prompt").value = p; $("canvas").value = c; };
+  $("examples").appendChild(b);
+}
+
+/* ---- generate ---- */
+const client = await Client.connect(window.location.origin, { events: ["data", "status"] });
+
+function setJob(label, cls) {
+  const el = $("job-state");
+  el.textContent = label; el.className = cls || "";
+}
+
+function setBar(pct) {
+  const bar = $("bar");
+  if (pct === null) { bar.className = "indeterminate"; return; }
+  bar.className = "";
+  bar.style.width = Math.max(0, Math.min(100, pct)) + "%";
+}
+
+$("run").addEventListener("click", async () => {
+  if (state.busy) return;
+  const prompt = $("prompt").value.trim();
+  if (!prompt) { setJob("FAILED", "failed"); $("report").textContent = "a prompt is required"; return; }
+
+  state.busy = true;
+  $("run").disabled = true;
+  $("refined-bar").style.display = "none";
+  $("report").textContent = "";
+  setJob("ROLLING", "");
+  const t0 = Date.now();
+  state.timer = setInterval(() => $("elapsed").textContent = ((Date.now() - t0) / 1000).toFixed(0) + "s", 500);
+
+  try {
+    const submission = client.submit("/generate", {
+      prompt,
+      image_path: state.first ? handle_file(state.first) : null,
+      last_image_path: state.last ? handle_file(state.last) : null,
+      canvas: $("canvas").value,
+      duration: Number($("duration").value),
+      steps: Number($("steps").value),
+      seed: Number($("seed").value),
+      upsample: $("upsample").checked,
+      lora: $("lora").value,
+    });
+    let data = null;
+    for await (const msg of submission) {
+      if (msg.type === "status") {
+        if (msg.stage === "pending") {
+          setJob(msg.position != null ? `QUEUED #${msg.position + 1}` : "QUEUED");
+          setBar(null);
+        } else if (msg.stage === "generating") {
+          setJob("ROLLING");
+          // ETA comes from the queue's booking estimate; blend it with our own elapsed timer.
+          if (msg.eta != null && msg.eta > 0) {
+            const elapsed = (Date.now() - t0) / 1000;
+            setBar(100 * elapsed / (elapsed + msg.eta));
+          } else setBar(null);
+        } else if (msg.stage === "error") {
+          throw new Error(msg.message || "generation failed");
+        }
+      } else if (msg.type === "data") {
+        data = msg.data;
+      }
+    }
+    if (!data) throw new Error("the backend returned no data");
+    // Server mode returns the tuple as ONE Api output: unwrap [[video, report, refined]] too.
+    if (data.length === 1 && Array.isArray(data[0])) data = data[0];
+    const [video, report, refined] = data;
+    // FileData may carry only `path`; resolve those through Gradio's file route.
+    const videoUrl = (video && (video.url || (video.path && `/gradio_api/file=${video.path}`)))
+      || (typeof video === "string" && `/gradio_api/file=${video}`);
+    if (!videoUrl) throw new Error("the backend returned no video reference");
+    $("video").src = videoUrl;
+    $("monitor").classList.remove("hidden-video");
+    $("placeholder").style.display = "none";
+    $("report").textContent = report;
+    if (refined) {
+      $("refined").textContent = refined;
+      $("refined-bar").style.display = "block";
+    }
+    setJob("DONE", "done");
+    setBar(100);
+  } catch (e) {
+    setJob("FAILED", "failed");
+    setBar(0);
+    $("report").textContent = (e && e.message) ? e.message.slice(0, 300) : String(e);
+  } finally {
+    clearInterval(state.timer);
+    state.busy = false;
+    $("run").disabled = false;
+  }
+});
+</script>
+</body>
+</html>

ncii_guard.py

@@ -1,90 +1,90 @@
-"""The NCII prompt guard, in its own process.
-
-[`hfmlsoc/ncii-light-guard-v01`](https://huggingface.co/hfmlsoc/ncii-light-guard-v01) is a 270M CPU text
-classifier scoring the NCII risk of an edit prompt. It cannot live in the main process: with it loaded there,
-every subsequent `@spaces.GPU` worker dies at `worker_init` with `RuntimeError: No CUDA GPUs are available` —
-the fork inherits whatever CUDA driver state the classifier's torch activity left behind, and a factory reboot
-does not clear it. It cannot be a `multiprocessing.spawn` child either: spawn re-imports the parent's main
-module, and on a Space that main module is `app.py` — the child would re-run the whole startup, `start()`
-included. So the classifier runs this file as a plain subprocess — a fresh interpreter that never sees `spaces`
-— and answers over stdin/stdout, one JSON object per line.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import select
-import subprocess
-import sys
-import threading
-
-GUARD_REPO = "hfmlsoc/ncii-light-guard-v01"
-
-_lock = threading.Lock()
-_process: subprocess.Popen | None = None
-
-
-def _read(timeout: float) -> dict:
-    readable, _, _ = select.select([_process.stdout], [], [], timeout)
-    if not readable:
-        raise TimeoutError(f"the guard did not answer within {timeout}s")
-    line = _process.stdout.readline()
-    if not line:
-        raise EOFError("the guard process died")
-    return json.loads(line)
-
-
-def _spawn() -> None:
-    global _process
-    _process = subprocess.Popen(
-        [sys.executable, os.path.abspath(__file__)],
-        stdin=subprocess.PIPE,
-        stdout=subprocess.PIPE,
-        text=True,
-        bufsize=1,
-    )
-    # Generous: a cold cache downloads the checkpoint first.
-    assert _read(300.0) == {"status": "ready"}
-
-
-def start() -> None:
-    """Launch the worker and block until its model is up. Called once at startup; `classify` revives it if it dies."""
-    with _lock:
-        _spawn()
-
-
-def classify(prompt: str, timeout: float = 60.0) -> dict:
-    """`{'label': 'safe' | 'ncii', 'score': ...}` for one prompt, replacing a dead or wedged worker once."""
-    with _lock:
-        for attempt in (0, 1):
-            try:
-                if _process is None or _process.poll() is not None:
-                    _spawn()
-                _process.stdin.write(json.dumps({"prompt": prompt}) + "\n")
-                _process.stdin.flush()
-                return _read(timeout)
-            except Exception:
-                if attempt:
-                    raise
-                if _process is not None and _process.poll() is None:
-                    _process.kill()
-
-
-def _serve() -> None:
-    """The child: plain torch on CPU. The protocol keeps the real stdout to itself — everything else
-    (download progress, warnings) is pushed over to stderr so it cannot corrupt a reply."""
-    protocol = os.fdopen(os.dup(1), "w", buffering=1)
-    os.dup2(2, 1)
-
-    from transformers import pipeline
-
-    classifier = pipeline("text-classification", model=GUARD_REPO, device="cpu")
-    protocol.write(json.dumps({"status": "ready"}) + "\n")
-    for line in sys.stdin:
-        result = classifier(json.loads(line)["prompt"], truncation=True)[0]
-        protocol.write(json.dumps({"label": result["label"], "score": float(result["score"])}) + "\n")
-
-
-if __name__ == "__main__":
-    _serve()
+"""The NCII prompt guard, in its own process.
+
+[`hfmlsoc/ncii-light-guard-v01`](https://huggingface.co/hfmlsoc/ncii-light-guard-v01) is a 270M CPU text
+classifier scoring the NCII risk of an edit prompt. It cannot live in the main process: with it loaded there,
+every subsequent `@spaces.GPU` worker dies at `worker_init` with `RuntimeError: No CUDA GPUs are available` —
+the fork inherits whatever CUDA driver state the classifier's torch activity left behind, and a factory reboot
+does not clear it. It cannot be a `multiprocessing.spawn` child either: spawn re-imports the parent's main
+module, and on a Space that main module is `app.py` — the child would re-run the whole startup, `start()`
+included. So the classifier runs this file as a plain subprocess — a fresh interpreter that never sees `spaces`
+— and answers over stdin/stdout, one JSON object per line.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import select
+import subprocess
+import sys
+import threading
+
+GUARD_REPO = "hfmlsoc/ncii-light-guard-v01"
+
+_lock = threading.Lock()
+_process: subprocess.Popen | None = None
+
+
+def _read(timeout: float) -> dict:
+    readable, _, _ = select.select([_process.stdout], [], [], timeout)
+    if not readable:
+        raise TimeoutError(f"the guard did not answer within {timeout}s")
+    line = _process.stdout.readline()
+    if not line:
+        raise EOFError("the guard process died")
+    return json.loads(line)
+
+
+def _spawn() -> None:
+    global _process
+    _process = subprocess.Popen(
+        [sys.executable, os.path.abspath(__file__)],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+    # Generous: a cold cache downloads the checkpoint first.
+    assert _read(300.0) == {"status": "ready"}
+
+
+def start() -> None:
+    """Launch the worker and block until its model is up. Called once at startup; `classify` revives it if it dies."""
+    with _lock:
+        _spawn()
+
+
+def classify(prompt: str, timeout: float = 60.0) -> dict:
+    """`{'label': 'safe' | 'ncii', 'score': ...}` for one prompt, replacing a dead or wedged worker once."""
+    with _lock:
+        for attempt in (0, 1):
+            try:
+                if _process is None or _process.poll() is not None:
+                    _spawn()
+                _process.stdin.write(json.dumps({"prompt": prompt}) + "\n")
+                _process.stdin.flush()
+                return _read(timeout)
+            except Exception:
+                if attempt:
+                    raise
+                if _process is not None and _process.poll() is None:
+                    _process.kill()
+
+
+def _serve() -> None:
+    """The child: plain torch on CPU. The protocol keeps the real stdout to itself — everything else
+    (download progress, warnings) is pushed over to stderr so it cannot corrupt a reply."""
+    protocol = os.fdopen(os.dup(1), "w", buffering=1)
+    os.dup2(2, 1)
+
+    from transformers import pipeline
+
+    classifier = pipeline("text-classification", model=GUARD_REPO, device="cpu")
+    protocol.write(json.dumps({"status": "ready"}) + "\n")
+    for line in sys.stdin:
+        result = classifier(json.loads(line)["prompt"], truncation=True)[0]
+        protocol.write(json.dumps({"label": result["label"], "score": float(result["score"])}) + "\n")
+
+
+if __name__ == "__main__":
+    _serve()

packages.txt

@@ -1 +1 @@
-ffmpeg
+ffmpeg

requirements.txt

@@ -1,26 +1,26 @@
-# `diffusers` is installed from the canonical MiniMax-H3 pull request,
-# https://github.com/huggingface/diffusers/pull/14371 ("Minimax h3 follow up (review & refactor)"), pinned to a
-# **commit** rather than to its `minimax-h3-refactor` branch: the PR is a WIP and its head moves, and this Space's
-# blocks subclass its block classes. Re-pin — and re-check `h3_split_blocks.py` against the block names of the new
-# head — whenever the PR updates.
-#
-#   665f578278365ea4a3318cb8c9b66ce6c01204b9 = refs/pull/14371/head at the time of this deploy
---extra-index-url https://download.pytorch.org/whl/cu130
-diffusers @ git+https://github.com/huggingface/diffusers.git@665f578278365ea4a3318cb8c9b66ce6c01204b9
-torch==2.11.0
-torchvision==0.26.0
-# The Qwen3-VL processor decides the vision patch count, so a different minor changes the conditioning.
-transformers==5.8.0
-accelerate==1.14.0
-# diffusers pins <2.
-huggingface-hub==1.24.0
-gradio==6.20.0
-spaces==0.51.1
-# No `kernels` pin on purpose: the Hub attention backends want `kernels>=0.12.3`, and that version breaks
-# transformers 5.8.0 at import.
-# PyAV muxes the generated soundtrack onto the frames (`encode_video`).
-av
-pillow
-numpy
-requests
-safetensors>=0.8.0
+# `diffusers` is installed from the canonical MiniMax-H3 pull request,
+# https://github.com/huggingface/diffusers/pull/14371 ("Minimax h3 follow up (review & refactor)"), pinned to a
+# **commit** rather than to its `minimax-h3-refactor` branch: the PR is a WIP and its head moves, and this Space's
+# blocks subclass its block classes. Re-pin — and re-check `h3_split_blocks.py` against the block names of the new
+# head — whenever the PR updates.
+#
+#   665f578278365ea4a3318cb8c9b66ce6c01204b9 = refs/pull/14371/head at the time of this deploy
+--extra-index-url https://download.pytorch.org/whl/cu130
+diffusers @ git+https://github.com/huggingface/diffusers.git@665f578278365ea4a3318cb8c9b66ce6c01204b9
+torch==2.11.0
+torchvision==0.26.0
+# The Qwen3-VL processor decides the vision patch count, so a different minor changes the conditioning.
+transformers==5.8.0
+accelerate==1.14.0
+# diffusers pins <2.
+huggingface-hub==1.24.0
+gradio==6.20.0
+# Hugging Face Spaces supplies its own spaces version during the build; do not pin it here.
+# No `kernels` pin on purpose: the Hub attention backends want `kernels>=0.12.3`, and that version breaks
+# transformers 5.8.0 at import.
+# PyAV muxes the generated soundtrack onto the frames (`encode_video`).
+av
+pillow
+numpy
+requests
+safetensors>=0.8.0

spaces_constant_binding_patch.py

@@ -1,202 +1,202 @@
-"""Bind AoTI constants that `torch.export` lifted anonymously.
-
-`spaces.zero.torch.aoti.LazyAOTIModel` binds a package's constants by intersecting the module's `state_dict()` with
-`compiled_model.get_constant_fqns()`, and keeps whatever it cannot match. `torch.export` only gives a lifted tensor a
-real FQN when it was a registered parameter or buffer; anything else is named `_tensor_constant<N>`, which no
-`state_dict()` can contain, so the compiled model runs against constants nobody set — a SIGSEGV rather than an error.
-
-`write_constant_aliases` records the real names on the compile side; `apply_spaces_constant_binding_patch` uses that
-sidecar on the load side, falls back to matching by dtype+shape, and raises if the binding is still not total.
-"""
-
-from __future__ import annotations
-
-import io
-import json
-import re
-import zipfile
-from pathlib import Path
-
-import torch
-
-ALIASES_FILENAME = "constant_aliases.json"
-
-_DTYPES = {
-    "float32": torch.float32, "float64": torch.float64, "float16": torch.float16,
-    "bfloat16": torch.bfloat16, "float8_e4m3fn": torch.float8_e4m3fn,
-    "float8_e5m2": torch.float8_e5m2, "float8_e4m3fnuz": torch.float8_e4m3fnuz,
-    "float8_e5m2fnuz": torch.float8_e5m2fnuz, "int8": torch.int8, "uint8": torch.uint8,
-    "int16": torch.int16, "int32": torch.int32, "int64": torch.int64, "bool": torch.bool,
-}
-
-
-# --------------------------------------------------------------------------- compile side
-
-
-def register_loose_tensors(module: torch.nn.Module, prefix: str = "") -> list[str]:
-    """Re-register plain tensor attributes as buffers so `torch.export` gives them real FQNs.
-
-    Run on the shallow clone, right before `torch.export.export`. Returns the names it re-registered.
-    """
-    registered = []
-    for name, value in list(vars(module).items()):
-        if not isinstance(value, torch.Tensor) or name.startswith("_"):
-            continue
-        if name in module._parameters or name in module._buffers:
-            continue
-        object.__delattr__(module, name)
-        module.register_buffer(name, value, persistent=True)
-        registered.append(f"{prefix}{name}")
-    for child_name, child in module.named_children():
-        registered += register_loose_tensors(child, f"{prefix}{child_name}.")
-    return registered
-
-
-def constant_aliases_from_exported_program(exported_program) -> dict[str, str]:
-    """`{'_tensor_constant<N>': '<real dotted fqn>'}` for every anonymously lifted constant.
-
-    AOT Inductor numbers its slots in the order the `CONSTANT_TENSOR` inputs appear in the graph signature, which
-    still carries each one's real FQN.
-    """
-    targets = [
-        spec.target
-        for spec in exported_program.graph_signature.input_specs
-        if spec.kind.name == "CONSTANT_TENSOR"
-    ]
-    return {f"_tensor_constant{index}": target for index, target in enumerate(targets)}
-
-
-def write_constant_aliases(package_dir, exported_program, submodule: str | None = None) -> Path | None:
-    """Drop the alias sidecar next to the `package.pt2` `aoti_compile_and_save` just wrote."""
-    aliases = constant_aliases_from_exported_program(exported_program)
-    if not aliases:
-        return None
-    subdir = Path(package_dir) / ("submodules/" + submodule if submodule else "root")
-    path = subdir / ALIASES_FILENAME
-    path.write_text(json.dumps(aliases, indent=2))
-    return path
-
-
-# --------------------------------------------------------------------------- load side
-
-
-def _package_constants_info(archive_file) -> list[dict]:
-    """Read `constants_info_` (dtype, shape, in slot order) out of a `.pt2`'s wrapper source."""
-    if isinstance(archive_file, (str, Path)):
-        handle: object = str(archive_file)
-    else:
-        position = archive_file.tell()
-        archive_file.seek(0)
-        handle = io.BytesIO(archive_file.read())
-        archive_file.seek(position)
-    with zipfile.ZipFile(handle) as archive:  # pyright: ignore[reportArgumentType]
-        names = [n for n in archive.namelist() if n.endswith(".wrapper.cpp")]
-        if not names:
-            return []
-        source = archive.read(names[0]).decode()
-    info: dict[int, dict] = {}
-    for match in re.finditer(r"constants_info_\[(\d+)\]\.(\w+) = ([^;]+);", source):
-        index, field, value = int(match.group(1)), match.group(2), match.group(3).strip()
-        entry = info.setdefault(index, {})
-        if field == "dtype":
-            entry["dtype"] = _DTYPES.get(value.replace("cached_torch_dtype_", ""))
-        elif field == "shape":
-            entry["shape"] = tuple(int(x) for x in re.findall(r"-?\d+", value))
-        elif field in ("name", "original_fqn"):
-            entry[field] = value.strip('"')
-    return [info[index] for index in sorted(info)]
-
-
-def resolve_constant_map(
-    archive_file,
-    constant_fqns,
-    weights: dict[str, torch.Tensor],
-    aliases=None,
-    allow_shape_fallback: bool = False,
-):
-    """Map every compiled constant FQN onto one of `weights`, or report what is left over."""
-    constant_map = {name: weights[name] for name in constant_fqns if name in weights}
-    missing = [name for name in constant_fqns if name not in constant_map]
-    if not missing:
-        return constant_map, []
-
-    aliases = aliases or {}
-    for name in list(missing):
-        target = aliases.get(name)
-        if target is not None and target in weights:
-            constant_map[name] = weights[target]
-            missing.remove(name)
-    if not missing or not allow_shape_fallback:
-        return constant_map, missing
-
-    # Match by dtype+shape against the unclaimed `state_dict()` entries, preserving each side's own order inside a
-    # (dtype, shape) group. `get_constant_fqns()` returns slots lexicographically (`_tensor_constant10` before
-    # `_tensor_constant2`), so the package's own `constants_info_` index is the only correct order to walk them in.
-    info = _package_constants_info(archive_file)
-    by_name = {entry.get("name"): entry for entry in info}
-    slot_index = {entry.get("name"): index for index, entry in enumerate(info)}
-    taken = {id(tensor) for tensor in constant_map.values()}
-    buckets: dict[tuple, list[torch.Tensor]] = {}
-    for tensor in weights.values():
-        if id(tensor) not in taken:
-            buckets.setdefault((tensor.dtype, tuple(tensor.shape)), []).append(tensor)
-    for name in sorted(list(missing), key=lambda n: slot_index.get(n, 1 << 30)):
-        entry = by_name.get(name)
-        if entry is None or entry.get("dtype") is None:
-            continue
-        bucket = buckets.get((entry["dtype"], entry["shape"]))
-        if bucket:
-            constant_map[name] = bucket.pop(0)
-            missing.remove(name)
-    return constant_map, missing
-
-
-def apply_spaces_constant_binding_patch(strict: bool = True, allow_shape_fallback: bool = False):
-    """Make `spaces`' AoTI loader bind anonymous constants, and fail loudly if it still cannot.
-
-    Call once, before any `spaces.aoti_*` loading. Idempotent.
-    """
-    from spaces.zero.torch import aoti as spaces_aoti
-
-    if getattr(spaces_aoti.LazyAOTIModel, "_constant_binding_patched", False):
-        return
-
-    original_call = spaces_aoti.LazyAOTIModel.__call__
-
-    def patched_call(self, weights, check_full_update, *args, **kwargs):
-        compiled_model = self.compiled_model.get()
-        if compiled_model is None:
-            with spaces_aoti._register_aoti_cleanup():
-                compiled_model = torch._inductor.aoti_load_package(self.archive_file)
-            self.compiled_model.set(compiled_model)
-        loaded = self.loaded_weights.get()
-        if loaded is None or loaded is not weights:
-            fqns = compiled_model.get_constant_fqns()
-            aliases = getattr(self, "_constant_aliases", None)
-            if aliases is None:
-                aliases = {}
-                if isinstance(self.archive_file, (str, Path)):
-                    sidecar = Path(self.archive_file).with_name(ALIASES_FILENAME)
-                    if sidecar.is_file():
-                        aliases = json.loads(sidecar.read_text())
-                self._constant_aliases = aliases
-            constant_map, missing = resolve_constant_map(
-                self.archive_file, fqns, weights, aliases, allow_shape_fallback
-            )
-            if missing and strict:
-                raise RuntimeError(
-                    f"{len(missing)} of {len(fqns)} AoTI constants could not be bound to the module's "
-                    f"state_dict: {missing[:8]}. Anonymous `_tensor_constant*` names mean the export saw "
-                    f"plain tensor attributes rather than registered parameters or buffers. Register them "
-                    f"(or write a {ALIASES_FILENAME} sidecar at compile time) — binding them partially "
-                    f"would leave the compiled model dereferencing unset constants."
-                )
-            compiled_model.load_constants(
-                constant_map, check_full_update=check_full_update and not missing, user_managed=True
-            )
-            self.loaded_weights.set(weights)
-        return compiled_model(*args, **kwargs)
-
-    spaces_aoti.LazyAOTIModel.__call__ = patched_call
-    spaces_aoti.LazyAOTIModel._constant_binding_patched = True
-    spaces_aoti.LazyAOTIModel._original_call = original_call
+"""Bind AoTI constants that `torch.export` lifted anonymously.
+
+`spaces.zero.torch.aoti.LazyAOTIModel` binds a package's constants by intersecting the module's `state_dict()` with
+`compiled_model.get_constant_fqns()`, and keeps whatever it cannot match. `torch.export` only gives a lifted tensor a
+real FQN when it was a registered parameter or buffer; anything else is named `_tensor_constant<N>`, which no
+`state_dict()` can contain, so the compiled model runs against constants nobody set — a SIGSEGV rather than an error.
+
+`write_constant_aliases` records the real names on the compile side; `apply_spaces_constant_binding_patch` uses that
+sidecar on the load side, falls back to matching by dtype+shape, and raises if the binding is still not total.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import re
+import zipfile
+from pathlib import Path
+
+import torch
+
+ALIASES_FILENAME = "constant_aliases.json"
+
+_DTYPES = {
+    "float32": torch.float32, "float64": torch.float64, "float16": torch.float16,
+    "bfloat16": torch.bfloat16, "float8_e4m3fn": torch.float8_e4m3fn,
+    "float8_e5m2": torch.float8_e5m2, "float8_e4m3fnuz": torch.float8_e4m3fnuz,
+    "float8_e5m2fnuz": torch.float8_e5m2fnuz, "int8": torch.int8, "uint8": torch.uint8,
+    "int16": torch.int16, "int32": torch.int32, "int64": torch.int64, "bool": torch.bool,
+}
+
+
+# --------------------------------------------------------------------------- compile side
+
+
+def register_loose_tensors(module: torch.nn.Module, prefix: str = "") -> list[str]:
+    """Re-register plain tensor attributes as buffers so `torch.export` gives them real FQNs.
+
+    Run on the shallow clone, right before `torch.export.export`. Returns the names it re-registered.
+    """
+    registered = []
+    for name, value in list(vars(module).items()):
+        if not isinstance(value, torch.Tensor) or name.startswith("_"):
+            continue
+        if name in module._parameters or name in module._buffers:
+            continue
+        object.__delattr__(module, name)
+        module.register_buffer(name, value, persistent=True)
+        registered.append(f"{prefix}{name}")
+    for child_name, child in module.named_children():
+        registered += register_loose_tensors(child, f"{prefix}{child_name}.")
+    return registered
+
+
+def constant_aliases_from_exported_program(exported_program) -> dict[str, str]:
+    """`{'_tensor_constant<N>': '<real dotted fqn>'}` for every anonymously lifted constant.
+
+    AOT Inductor numbers its slots in the order the `CONSTANT_TENSOR` inputs appear in the graph signature, which
+    still carries each one's real FQN.
+    """
+    targets = [
+        spec.target
+        for spec in exported_program.graph_signature.input_specs
+        if spec.kind.name == "CONSTANT_TENSOR"
+    ]
+    return {f"_tensor_constant{index}": target for index, target in enumerate(targets)}
+
+
+def write_constant_aliases(package_dir, exported_program, submodule: str | None = None) -> Path | None:
+    """Drop the alias sidecar next to the `package.pt2` `aoti_compile_and_save` just wrote."""
+    aliases = constant_aliases_from_exported_program(exported_program)
+    if not aliases:
+        return None
+    subdir = Path(package_dir) / ("submodules/" + submodule if submodule else "root")
+    path = subdir / ALIASES_FILENAME
+    path.write_text(json.dumps(aliases, indent=2))
+    return path
+
+
+# --------------------------------------------------------------------------- load side
+
+
+def _package_constants_info(archive_file) -> list[dict]:
+    """Read `constants_info_` (dtype, shape, in slot order) out of a `.pt2`'s wrapper source."""
+    if isinstance(archive_file, (str, Path)):
+        handle: object = str(archive_file)
+    else:
+        position = archive_file.tell()
+        archive_file.seek(0)
+        handle = io.BytesIO(archive_file.read())
+        archive_file.seek(position)
+    with zipfile.ZipFile(handle) as archive:  # pyright: ignore[reportArgumentType]
+        names = [n for n in archive.namelist() if n.endswith(".wrapper.cpp")]
+        if not names:
+            return []
+        source = archive.read(names[0]).decode()
+    info: dict[int, dict] = {}
+    for match in re.finditer(r"constants_info_\[(\d+)\]\.(\w+) = ([^;]+);", source):
+        index, field, value = int(match.group(1)), match.group(2), match.group(3).strip()
+        entry = info.setdefault(index, {})
+        if field == "dtype":
+            entry["dtype"] = _DTYPES.get(value.replace("cached_torch_dtype_", ""))
+        elif field == "shape":
+            entry["shape"] = tuple(int(x) for x in re.findall(r"-?\d+", value))
+        elif field in ("name", "original_fqn"):
+            entry[field] = value.strip('"')
+    return [info[index] for index in sorted(info)]
+
+
+def resolve_constant_map(
+    archive_file,
+    constant_fqns,
+    weights: dict[str, torch.Tensor],
+    aliases=None,
+    allow_shape_fallback: bool = False,
+):
+    """Map every compiled constant FQN onto one of `weights`, or report what is left over."""
+    constant_map = {name: weights[name] for name in constant_fqns if name in weights}
+    missing = [name for name in constant_fqns if name not in constant_map]
+    if not missing:
+        return constant_map, []
+
+    aliases = aliases or {}
+    for name in list(missing):
+        target = aliases.get(name)
+        if target is not None and target in weights:
+            constant_map[name] = weights[target]
+            missing.remove(name)
+    if not missing or not allow_shape_fallback:
+        return constant_map, missing
+
+    # Match by dtype+shape against the unclaimed `state_dict()` entries, preserving each side's own order inside a
+    # (dtype, shape) group. `get_constant_fqns()` returns slots lexicographically (`_tensor_constant10` before
+    # `_tensor_constant2`), so the package's own `constants_info_` index is the only correct order to walk them in.
+    info = _package_constants_info(archive_file)
+    by_name = {entry.get("name"): entry for entry in info}
+    slot_index = {entry.get("name"): index for index, entry in enumerate(info)}
+    taken = {id(tensor) for tensor in constant_map.values()}
+    buckets: dict[tuple, list[torch.Tensor]] = {}
+    for tensor in weights.values():
+        if id(tensor) not in taken:
+            buckets.setdefault((tensor.dtype, tuple(tensor.shape)), []).append(tensor)
+    for name in sorted(list(missing), key=lambda n: slot_index.get(n, 1 << 30)):
+        entry = by_name.get(name)
+        if entry is None or entry.get("dtype") is None:
+            continue
+        bucket = buckets.get((entry["dtype"], entry["shape"]))
+        if bucket:
+            constant_map[name] = bucket.pop(0)
+            missing.remove(name)
+    return constant_map, missing
+
+
+def apply_spaces_constant_binding_patch(strict: bool = True, allow_shape_fallback: bool = False):
+    """Make `spaces`' AoTI loader bind anonymous constants, and fail loudly if it still cannot.
+
+    Call once, before any `spaces.aoti_*` loading. Idempotent.
+    """
+    from spaces.zero.torch import aoti as spaces_aoti
+
+    if getattr(spaces_aoti.LazyAOTIModel, "_constant_binding_patched", False):
+        return
+
+    original_call = spaces_aoti.LazyAOTIModel.__call__
+
+    def patched_call(self, weights, check_full_update, *args, **kwargs):
+        compiled_model = self.compiled_model.get()
+        if compiled_model is None:
+            with spaces_aoti._register_aoti_cleanup():
+                compiled_model = torch._inductor.aoti_load_package(self.archive_file)
+            self.compiled_model.set(compiled_model)
+        loaded = self.loaded_weights.get()
+        if loaded is None or loaded is not weights:
+            fqns = compiled_model.get_constant_fqns()
+            aliases = getattr(self, "_constant_aliases", None)
+            if aliases is None:
+                aliases = {}
+                if isinstance(self.archive_file, (str, Path)):
+                    sidecar = Path(self.archive_file).with_name(ALIASES_FILENAME)
+                    if sidecar.is_file():
+                        aliases = json.loads(sidecar.read_text())
+                self._constant_aliases = aliases
+            constant_map, missing = resolve_constant_map(
+                self.archive_file, fqns, weights, aliases, allow_shape_fallback
+            )
+            if missing and strict:
+                raise RuntimeError(
+                    f"{len(missing)} of {len(fqns)} AoTI constants could not be bound to the module's "
+                    f"state_dict: {missing[:8]}. Anonymous `_tensor_constant*` names mean the export saw "
+                    f"plain tensor attributes rather than registered parameters or buffers. Register them "
+                    f"(or write a {ALIASES_FILENAME} sidecar at compile time) — binding them partially "
+                    f"would leave the compiled model dereferencing unset constants."
+                )
+            compiled_model.load_constants(
+                constant_map, check_full_update=check_full_update and not missing, user_managed=True
+            )
+            self.loaded_weights.set(weights)
+        return compiled_model(*args, **kwargs)
+
+    spaces_aoti.LazyAOTIModel.__call__ = patched_call
+    spaces_aoti.LazyAOTIModel._constant_binding_patched = True
+    spaces_aoti.LazyAOTIModel._original_call = original_call