UI improvements, added live generation preview via latent linear probe

Update the moving Canter code on main. Preserve the existing v0001 checkpoint and add the small standalone latent RGB preview projection.

API.md

@@ -30,6 +30,7 @@ image = output.image
 | `config` | `CanterPipelineConfig()` | Inference and output settings. |
 | `initial_noise` | `None` | Optional float32 latent noise tensor with the configured batch and spatial shape. |
 | `progress` | `None` | Optional callback receiving completed and total solver updates. |
+| `preview` | `None` | Optional callback receiving asynchronous latent-RGB PIL images plus completed and total solver updates. |
 
 `CanterPipeline` loads the flow-matching denoiser and text tokenizer with the
 bundled
@@ -117,6 +118,32 @@ output = pipe("A portrait lit by a large north-facing window", config=config)
 Every output also contains the descending float32 solver schedule in
 `output.schedule`.
 
+## Live latent previews
+
+```python
+def show_preview(images, completed, total):
+    images[0].show()
+
+
+output = pipe(
+    "A lighthouse in a winter storm",
+    preview=show_preview,
+)
+```
+
+The bundled float32 linear projection maps the whitened 128-channel DINAC
+latent directly to RGB at one eighth of the requested image size. Every solver
+update is eligible by default. If the previous preview is still transferring,
+converting, or running the callback, the new update is dropped instead of
+blocking sampling. The callback receives this native one-eighth-size image;
+the web UI lets the browser scale it for display.
+
+Accepted previews perform only a 1×1 projection and pixel shuffle on CUDA.
+The small RGB result is copied non-blockingly into pinned host memory. CUDA
+event waiting, PIL conversion, and the application callback all run on a
+single background worker. Every step is eligible; the one-worker busy-drop
+policy supplies backpressure without a separate callback cap.
+
 ## Inference configuration
 
 ### Defaults
@@ -437,6 +464,7 @@ schedule = output.schedule
 | `config` | `CanterInferenceConfig()` | Latent inference settings. |
 | `initial_noise` | `None` | Optional float32 noise with shape `[batch, 128, height / 16, width / 16]`. |
 | `progress` | `None` | Optional callback receiving `(completed_updates, total_updates)`. |
+| `state_callback` | `None` | Optional synchronous callback receiving `(state, completed_updates, total_updates)` after every solver update. Prefer pipeline previews when full CUDA latent access is not required. |
 
 An empty or whitespace-only prompt uses the learned unconditional token without
 running the text encoder. Every prompt in a batch must be either blank or

README.md

@@ -99,6 +99,11 @@ python app.py --in-browser
 downloads the latest compatible DINAC-AE-D2 VAE.
 The interface appears immediately and reports model loading and pytorch dynamo compilation
 progress.
+During sampling, each output slot receives asynchronous previews from the
+bundled one-eighth-scale latent-RGB projection. Busy preview work is skipped,
+so the sampler never waits for browser publication. The native one-eighth-size
+preview is sent directly and scaled for display by the browser. The UI checkbox
+below the size preset disables previews.
 Downloaded PNG files contain the prompt, effective per-image settings, Canter
 code version, and numbered checkpoint release as JSON metadata.
 

RELEASES.md

@@ -6,6 +6,13 @@
 Checkpoint tags are immutable snapshots. The installed package supplies the
 inference code, so current code can load any compatible checkpoint tag without
 executing the Python files stored in that historical snapshot.
+The current package also supplies the small latent-RGB preview projection;
+preview behavior therefore follows the installed code rather than changing an
+older denoiser checkpoint tag.
+
+Canter `0.3.0` adds asynchronous native-resolution latent previews and the
+responsive preview grid. The browser scales previews for display; final
+decoded images remain full resolution.
 
 | Release | Date | Weight storage | Status |
 | --- | --- | --- | --- |

canter/__init__.py

@@ -30,8 +30,9 @@ from .pipeline import (
     CanterPipelineMetadata,
     CanterPipelineOutput,
 )
+from .preview import CanterPreviewCallback
 from .schedules import Schedule
-from .solvers import Solver, SolverProgress
+from .solvers import Solver, SolverProgress, SolverStateCallback
 from .text_encoder import CanterTextEncoder, TextBackboneOutput
 from .vae import CanterVae
 from .version import CANTER_VERSION, __version__
@@ -54,6 +55,7 @@ __all__ = [
     "CanterPipelineConfig",
     "CanterPipelineMetadata",
     "CanterPipelineOutput",
+    "CanterPreviewCallback",
     "CanterReleaseMetadata",
     "CanterTextEncoder",
     "CanterVae",
@@ -65,6 +67,7 @@ __all__ = [
     "Schedule",
     "Solver",
     "SolverProgress",
+    "SolverStateCallback",
     "TextAttentionBackend",
     "TextBackboneOutput",
     "WeightDType",

canter/inference.py

@@ -15,7 +15,13 @@ from torch.amp import autocast
 from .modeling_canter import CanterPath, PreparedText
 from .runtime import CANTER_AMP_DTYPE, validate_common_runtime
 from .schedules import Schedule, build_schedule
-from .solvers import LOGSNR_SOLVER_START_EPS, Solver, SolverProgress, solve
+from .solvers import (
+    LOGSNR_SOLVER_START_EPS,
+    Solver,
+    SolverProgress,
+    SolverStateCallback,
+    solve,
+)
 
 if TYPE_CHECKING:
     from .loading import CanterComponents
@@ -550,6 +556,7 @@ class CanterInferenceEngine:
         config: CanterInferenceConfig = _DEFAULT_INFERENCE_CONFIG,
         initial_noise: Tensor | None = None,
         progress: SolverProgress | None = None,
+        state_callback: SolverStateCallback | None = None,
     ) -> CanterLatentOutput:
         """Generate float32 Canter latents for one prompt or prompt batch."""
 
@@ -632,6 +639,7 @@ class CanterInferenceEngine:
                 euler_maruyama_multiplier=config.euler_maruyama_multiplier,
                 er_sde_noise_multiplier=config.er_sde_noise_multiplier,
                 progress=progress,
+                state_callback=state_callback,
             )
         return CanterLatentOutput(latents=latents, schedule=schedule)
 

canter/latent_rgb_preview.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0760245660c120a79ea536e3c77bb53f5230f22801874623c339ef58fc218866
+size 6832

canter/pipeline.py

@@ -24,11 +24,16 @@ from .loading import (
     CanterReleaseMetadata,
     WeightDType,
 )
+from .preview import (
+    LATENT_RGB_PREVIEW_FILENAME,
+    CanterPreviewCallback,
+    LatentRgbPreviewer,
+)
 from .vae import CanterVae
 from .version import CANTER_VERSION
 
 if TYPE_CHECKING:
-    from .solvers import SolverProgress
+    from .solvers import SolverProgress, SolverStateCallback
 
 
 class CanterOutputType(Enum):
@@ -100,12 +105,39 @@ class _LatentEngine(Protocol):
         config: CanterInferenceConfig,
         initial_noise: Tensor | None,
         progress: SolverProgress | None,
+        state_callback: SolverStateCallback | None,
     ) -> CanterLatentOutput:
         """Generate deterministic whitened Canter latents."""
 
         ...
 
 
+class _LatentPreviewer(Protocol):
+    """Asynchronous latent preview surface consumed by the pipeline."""
+
+    def try_submit(
+        self,
+        latents: Tensor,
+        *,
+        callback: CanterPreviewCallback,
+        completed: int,
+        total: int,
+    ) -> bool:
+        """Submit one preview if the worker is idle."""
+
+        ...
+
+    def raise_if_failed(self) -> None:
+        """Propagate one completed asynchronous failure."""
+
+        ...
+
+    def close(self) -> None:
+        """Finish preview work and release worker resources."""
+
+        ...
+
+
 _DEFAULT_PIPELINE_CONFIG = CanterPipelineConfig()
 
 
@@ -117,6 +149,7 @@ class CanterPipeline:
         engine: _LatentEngine,
         vae: CanterVae,
         metadata: CanterPipelineMetadata,
+        previewer: _LatentPreviewer,
     ) -> None:
         """Construct a pipeline from validated inference components."""
 
@@ -128,6 +161,7 @@ class CanterPipeline:
             raise ValueError("Pipeline metadata and DINAC-AE revision disagree.")
         self.engine = engine
         self.vae = vae
+        self.previewer = previewer
         self.metadata = metadata
         self.device = engine.device
 
@@ -177,6 +211,10 @@ class CanterPipeline:
             CanterInferenceEngine(components),
             resolved_vae,
             metadata,
+            LatentRgbPreviewer.from_file(
+                Path(__file__).with_name(LATENT_RGB_PREVIEW_FILENAME),
+                device=components.model.input_projection.weight.device,
+            ),
         )
 
     def __call__(
@@ -187,18 +225,23 @@ class CanterPipeline:
         config: CanterPipelineConfig = _DEFAULT_PIPELINE_CONFIG,
         initial_noise: Tensor | None = None,
         progress: SolverProgress | None = None,
+        preview: CanterPreviewCallback | None = None,
     ) -> CanterPipelineOutput:
         """Generate the configured output without recording gradients."""
 
         if not isinstance(config, CanterPipelineConfig):
             raise TypeError("config must be a CanterPipelineConfig.")
+        self.previewer.raise_if_failed()
+        state_callback = self._state_callback(preview)
         latent_output = self.engine.generate(
             prompts,
             negative_prompts=negative_prompts,
             config=config.inference,
             initial_noise=initial_noise,
             progress=progress,
+            state_callback=state_callback,
         )
+        self.previewer.raise_if_failed()
         match config.output_type:
             case CanterOutputType.LATENT:
                 return CanterPipelineOutput(
@@ -235,6 +278,32 @@ class CanterPipeline:
             case _ as unreachable:
                 raise RuntimeError(f"Unsupported output type: {unreachable}")
 
+    def close(self) -> None:
+        """Finish preview work before releasing pipeline resources."""
+
+        self.previewer.close()
+
+    def _state_callback(
+        self,
+        preview: CanterPreviewCallback | None,
+    ) -> SolverStateCallback | None:
+        """Build a non-blocking solver-state callback for one request."""
+
+        if preview is None:
+            return None
+
+        def submit(state: Tensor, completed: int, total: int) -> None:
+            """Drop busy updates and enqueue every eligible idle update."""
+
+            self.previewer.try_submit(
+                state,
+                callback=preview,
+                completed=completed,
+                total=total,
+            )
+
+        return submit
+
 
 def _validate_vae_selection(
     vae: CanterVae,

canter/preview.py

@@ -0,0 +1,270 @@
+"""Asynchronous DINAC latent-to-RGB previews for Canter inference."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+import torch
+import torch.nn.functional as F
+from PIL import Image
+from safetensors import safe_open
+from safetensors.torch import load_file
+from torch import Tensor
+
+LATENT_RGB_PREVIEW_FILENAME = "latent_rgb_preview.safetensors"
+LATENT_RGB_PREVIEW_FORMAT = "canter-latent-rgb-preview-v1"
+LATENT_RGB_PREVIEW_METADATA_KEY = "canter"
+_WEIGHT_KEY = "projection.weight"
+_BIAS_KEY = "projection.bias"
+_EXPECTED_LATENT_CHANNELS = 128
+_EXPECTED_RGB_CHANNELS = 3
+_EXPECTED_SPATIAL_EXPANSION = 2
+_LOGGER = logging.getLogger(__name__)
+
+
+class CanterPreviewCallback(Protocol):
+    """Consumer of one asynchronously rendered solver preview."""
+
+    def __call__(
+        self,
+        images: tuple[Image.Image, ...],
+        completed: int,
+        total: int,
+    ) -> None:
+        """Consume preview images for one completed solver update."""
+
+        ...
+
+
+@dataclass(frozen=True)
+class _PreviewWork:
+    """Inputs consumed by one asynchronous CPU preview job."""
+
+    host_rgb: Tensor
+    ready: torch.cuda.Event
+    callback: CanterPreviewCallback
+    completed: int
+    total: int
+
+
+class LatentRgbPreviewer:
+    """Project solver states on CUDA and finish previews on one CPU worker."""
+
+    def __init__(
+        self,
+        weight: Tensor,
+        bias: Tensor,
+        *,
+        device: torch.device,
+    ) -> None:
+        """Move the tiny projection to CUDA and initialize one-slot dispatch."""
+
+        if device.type != "cuda":
+            raise ValueError("Canter latent previews require a CUDA device.")
+        self._weight = weight.to(device=device, dtype=torch.float32)
+        self._bias = bias.to(device=device, dtype=torch.float32)
+        self.device = self._weight.device
+        self._executor = ThreadPoolExecutor(
+            max_workers=1,
+            thread_name_prefix="canter-preview",
+        )
+        self._lock = threading.Lock()
+        self._future: Future[None] | None = None
+        self._host_buffer: Tensor | None = None
+        self._closed = False
+
+    @classmethod
+    def from_file(
+        cls,
+        path: Path,
+        *,
+        device: torch.device,
+    ) -> LatentRgbPreviewer:
+        """Load one strict standalone latent-RGB Safetensors artifact."""
+
+        weight, bias = _load_projection_weights(path)
+        return cls(weight, bias, device=device)
+
+    def try_submit(
+        self,
+        latents: Tensor,
+        *,
+        callback: CanterPreviewCallback,
+        completed: int,
+        total: int,
+    ) -> bool:
+        """Submit a preview only when the prior CPU job has fully completed."""
+
+        with self._lock:
+            self._raise_completed_error_locked()
+            if self._closed:
+                raise RuntimeError("Canter latent previewer is closed.")
+            if self._future is not None:
+                return False
+            with (
+                torch.inference_mode(),
+                torch.autocast(device_type="cuda", enabled=False),
+            ):
+                projected = F.conv2d(latents.float(), self._weight, self._bias)
+                small_rgb = F.pixel_shuffle(
+                    projected,
+                    upscale_factor=_EXPECTED_SPATIAL_EXPANSION,
+                ).clamp(-1.0, 1.0)
+                host_buffer = self._host_buffer_for(small_rgb)
+                host_buffer.copy_(small_rgb, non_blocking=True)
+                ready = torch.cuda.Event()
+                ready.record(torch.cuda.current_stream(self.device))
+            self._future = self._executor.submit(
+                _finish_preview,
+                _PreviewWork(
+                    host_rgb=host_buffer,
+                    ready=ready,
+                    callback=callback,
+                    completed=completed,
+                    total=total,
+                ),
+            )
+            self._future.add_done_callback(_log_preview_failure)
+            return True
+
+    def raise_if_failed(self) -> None:
+        """Propagate a completed asynchronous preview failure without waiting."""
+
+        with self._lock:
+            self._raise_completed_error_locked()
+
+    def close(self) -> None:
+        """Finish accepted preview work and stop the worker."""
+
+        with self._lock:
+            self._closed = True
+        self._executor.shutdown(wait=True, cancel_futures=False)
+        self.raise_if_failed()
+
+    def _host_buffer_for(self, small_rgb: Tensor) -> Tensor:
+        """Return a shape-compatible pinned float32 host buffer."""
+
+        shape = tuple(int(dimension) for dimension in small_rgb.shape)
+        current = self._host_buffer
+        if current is None or tuple(current.shape) != shape:
+            current = torch.empty(
+                shape,
+                device="cpu",
+                dtype=torch.float32,
+                pin_memory=True,
+            )
+            self._host_buffer = current
+        return current
+
+    def _raise_completed_error_locked(self) -> None:
+        """Resolve and clear a completed worker future while holding the lock."""
+
+        future = self._future
+        if future is None or not future.done():
+            return
+        self._future = None
+        future.result()
+
+
+def _finish_preview(work: _PreviewWork) -> None:
+    """Wait off-thread, convert the native preview, and publish it."""
+
+    work.ready.synchronize()
+    with torch.inference_mode():
+        images = _to_pil_images(work.host_rgb)
+    work.callback(images, work.completed, work.total)
+
+
+def _to_pil_images(images: Tensor) -> tuple[Image.Image, ...]:
+    """Convert clamped CPU float32 BCHW images into RGB PIL images."""
+
+    pixels = (
+        images.add(1.0)
+        .mul(127.5)
+        .round()
+        .clamp(0.0, 255.0)
+        .to(torch.uint8)
+        .permute(0, 2, 3, 1)
+        .contiguous()
+        .numpy()
+    )
+    return tuple(Image.fromarray(image, mode="RGB") for image in pixels)
+
+
+def _load_projection_weights(path: Path) -> tuple[Tensor, Tensor]:
+    """Validate metadata and tensors from one preview artifact."""
+
+    metadata = _load_preview_metadata(path)
+    expected_metadata = {
+        "format": LATENT_RGB_PREVIEW_FORMAT,
+        "latent_channels": str(_EXPECTED_LATENT_CHANNELS),
+        "rgb_channels": str(_EXPECTED_RGB_CHANNELS),
+        "spatial_expansion_factor": str(_EXPECTED_SPATIAL_EXPANSION),
+        "target_downsample_factor": "8",
+    }
+    mismatches = {
+        key: (metadata.get(key), expected)
+        for key, expected in expected_metadata.items()
+        if metadata.get(key) != expected
+    }
+    if mismatches:
+        raise RuntimeError(
+            f"Latent preview Safetensors metadata is incompatible: {mismatches}."
+        )
+    tensors = load_file(path, device="cpu")
+    if set(tensors) != {_WEIGHT_KEY, _BIAS_KEY}:
+        raise RuntimeError(
+            "Latent preview Safetensors must contain only projection.weight "
+            "and projection.bias."
+        )
+    weight = tensors[_WEIGHT_KEY]
+    bias = tensors[_BIAS_KEY]
+    expected_weight_shape = (
+        _EXPECTED_RGB_CHANNELS * _EXPECTED_SPATIAL_EXPANSION**2,
+        _EXPECTED_LATENT_CHANNELS,
+        1,
+        1,
+    )
+    if tuple(weight.shape) != expected_weight_shape:
+        raise RuntimeError(
+            "Latent preview projection.weight has an incompatible shape: "
+            f"expected {expected_weight_shape}, got {tuple(weight.shape)}."
+        )
+    if tuple(bias.shape) != (expected_weight_shape[0],):
+        raise RuntimeError("Latent preview projection.bias has an incompatible shape.")
+    if weight.dtype is not torch.float32 or bias.dtype is not torch.float32:
+        raise RuntimeError("Latent preview projection weights must use float32.")
+    return weight.contiguous(), bias.contiguous()
+
+
+def _load_preview_metadata(path: Path) -> dict[str, str]:
+    """Load deterministic JSON metadata from one preview artifact."""
+
+    with safe_open(path, framework="pt", device="cpu") as file:
+        header = file.metadata()
+    if header is None or set(header) != {LATENT_RGB_PREVIEW_METADATA_KEY}:
+        raise RuntimeError("Latent preview Safetensors metadata is missing.")
+    value = json.loads(header[LATENT_RGB_PREVIEW_METADATA_KEY])
+    if not isinstance(value, dict) or any(
+        not isinstance(key, str) or not isinstance(item, str)
+        for key, item in value.items()
+    ):
+        raise TypeError("Latent preview metadata must map strings to strings.")
+    return value
+
+
+def _log_preview_failure(future: Future[None]) -> None:
+    """Log asynchronous callback failures immediately for console diagnosis."""
+
+    error = future.exception()
+    if error is not None:
+        _LOGGER.error(
+            "Asynchronous Canter preview failed",
+            exc_info=(type(error), error, error.__traceback__),
+        )

canter/solvers.py

@@ -46,12 +46,40 @@ class SolverProgress(Protocol):
         ...
 
 
+class SolverStateCallback(Protocol):
+    """Callback receiving the state after one completed solver update."""
+
+    def __call__(self, state: Tensor, completed: int, total: int) -> None:
+        """Observe one completed state update."""
+
+        ...
+
+
 def _ignore_progress(completed: int, total: int) -> None:
     """Discard solver progress for non-interactive inference."""
 
     del completed, total
 
 
+def _ignore_state(state: Tensor, completed: int, total: int) -> None:
+    """Discard solver states when no observer is configured."""
+
+    del state, completed, total
+
+
+def _report_update(
+    state: Tensor,
+    completed: int,
+    total: int,
+    progress: SolverProgress,
+    state_callback: SolverStateCallback,
+) -> None:
+    """Report one completed update before exposing its resulting state."""
+
+    progress(completed, total)
+    state_callback(state, completed, total)
+
+
 def _time_batch(time: Tensor, batch: int, device: torch.device) -> Tensor:
     """Expand one scalar schedule value to a float32 batch vector."""
 
@@ -80,6 +108,7 @@ def _euler(
     state: Tensor,
     schedule: Tensor,
     progress: SolverProgress,
+    state_callback: SolverStateCallback,
 ) -> Tensor:
     """Integrate one first-order Euler update."""
 
@@ -89,7 +118,7 @@ def _euler(
         time = _time_batch(schedule[index], batch, state.device)
         step = schedule[index + 1] - schedule[index]
         state = state + step * velocity(state, time, index)
-        progress(index + 1, intervals)
+        _report_update(state, index + 1, intervals, progress, state_callback)
     return state
 
 
@@ -110,6 +139,7 @@ def _euler_maruyama(
     generator: torch.Generator,
     multiplier: float,
     progress: SolverProgress,
+    state_callback: SolverStateCallback,
 ) -> Tensor:
     """Integrate the reverse SDE with an Euler-Maruyama update."""
 
@@ -129,7 +159,7 @@ def _euler_maruyama(
         terminal = index == intervals - 1 and next_value == 0.0
         if terminal:
             state = state - time_value * predicted
-            progress(index + 1, intervals)
+            _report_update(state, index + 1, intervals, progress, state_callback)
             continue
         drift = predicted - time.view((batch, 1, 1, 1)) * _score(
             state,
@@ -145,7 +175,7 @@ def _euler_maruyama(
         diffusion = 2.0 * time_value
         noise_scale = float(multiplier) * math.sqrt(diffusion) * math.sqrt(abs(step))
         state = state + step * drift + noise_scale * noise
-        progress(index + 1, intervals)
+        _report_update(state, index + 1, intervals, progress, state_callback)
     return state
 
 
@@ -200,6 +230,7 @@ def _dpmpp_2m(
     state: Tensor,
     schedule: Tensor,
     progress: SolverProgress,
+    state_callback: SolverStateCallback,
 ) -> Tensor:
     """Integrate with the flow-matching DPM++ 2M formulation."""
 
@@ -230,7 +261,7 @@ def _dpmpp_2m(
             )
         previous_denoised = denoised
         previous_lambda = lambdas[index]
-        progress(index + 1, intervals)
+        _report_update(state, index + 1, intervals, progress, state_callback)
     return state
 
 
@@ -347,6 +378,7 @@ def _er_sde(
     generator: torch.Generator,
     noise_multiplier: float,
     progress: SolverProgress,
+    state_callback: SolverStateCallback,
 ) -> Tensor:
     """Integrate with third-stage VP ER-SDE and Gauss-Legendre quadrature."""
 
@@ -383,7 +415,7 @@ def _er_sde(
                 noise_multiplier=float(noise_multiplier),
             )
         old_denoised = denoised
-        progress(index + 1, intervals)
+        _report_update(state, index + 1, intervals, progress, state_callback)
     return state
 
 
@@ -407,6 +439,7 @@ def _abm2(
     state: Tensor,
     schedule: Tensor,
     progress: SolverProgress,
+    state_callback: SolverStateCallback,
 ) -> Tensor:
     """Integrate with ABM2, including corrected-state reevaluation."""
 
@@ -424,7 +457,7 @@ def _abm2(
         _time_batch(schedule[1], batch, state.device),
         1,
     )
-    progress(1, intervals)
+    _report_update(state, 1, intervals, progress, state_callback)
     for index in range(1, intervals):
         previous_step = schedule[index] - schedule[index - 1]
         current_step = schedule[index + 1] - schedule[index]
@@ -450,7 +483,7 @@ def _abm2(
             _time_batch(schedule[index + 1], batch, state.device),
             index + 1,
         )
-        progress(index + 1, intervals)
+        _report_update(state, index + 1, intervals, progress, state_callback)
     return state
 
 
@@ -464,6 +497,7 @@ def solve(
     euler_maruyama_multiplier: float,
     er_sde_noise_multiplier: float = 1.0,
     progress: SolverProgress | None = None,
+    state_callback: SolverStateCallback | None = None,
 ) -> Tensor:
     """Integrate Canter velocity predictions over one validated schedule."""
 
@@ -477,9 +511,18 @@ def solve(
     if not math.isfinite(er_multiplier) or er_multiplier < 0.0:
         raise ValueError("er_sde_noise_multiplier must be finite and non-negative.")
     resolved_progress = _ignore_progress if progress is None else progress
+    resolved_state_callback = (
+        _ignore_state if state_callback is None else state_callback
+    )
     match solver:
         case Solver.EULER:
-            return _euler(velocity, initial_state, schedule, resolved_progress)
+            return _euler(
+                velocity,
+                initial_state,
+                schedule,
+                resolved_progress,
+                resolved_state_callback,
+            )
         case Solver.EULER_MARUYAMA:
             return _euler_maruyama(
                 velocity,
@@ -488,6 +531,7 @@ def solve(
                 generator=generator,
                 multiplier=em_multiplier,
                 progress=resolved_progress,
+                state_callback=resolved_state_callback,
             )
         case Solver.ER_SDE:
             return _er_sde(
@@ -497,6 +541,7 @@ def solve(
                 generator=generator,
                 noise_multiplier=er_multiplier,
                 progress=resolved_progress,
+                state_callback=resolved_state_callback,
             )
         case Solver.DPMPP_2M:
             return _dpmpp_2m(
@@ -504,6 +549,7 @@ def solve(
                 initial_state,
                 schedule,
                 resolved_progress,
+                resolved_state_callback,
             )
         case Solver.ABM2:
             return _abm2(
@@ -511,6 +557,7 @@ def solve(
                 initial_state,
                 schedule,
                 resolved_progress,
+                resolved_state_callback,
             )
         case _ as unreachable:
             raise RuntimeError(f"Unsupported Canter solver: {unreachable}")

canter/version.py

@@ -1,4 +1,4 @@
 """Single source of truth for the installable Canter code version."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 CANTER_VERSION = __version__

canter/webui.py

@@ -1,1822 +1,68 @@
-"""Dark Gradio application for the standalone Canter pipeline."""
+"""Public entry point for the standalone Canter web application."""
 
 from __future__ import annotations
 
 import argparse
-import json
-import math
-import secrets
-import threading
-import time
-from collections.abc import Callable, Generator, Mapping, Sequence
-from dataclasses import dataclass, replace
-from enum import Enum
-from hashlib import sha256
+import logging
+import os
+import shutil
+import tempfile
+from collections.abc import Sequence
 from pathlib import Path
-from typing import Protocol, TypeAlias, TypeVar
-
-import gradio as gr
-from PIL import Image
 
 from .blocks import TextAttentionBackend
-from .inference import (
-    CanterInferenceConfig,
-    CfgGuidance,
-    PdgCurve,
-    PdgGuidance,
-    PdgMode,
-)
 from .loading import WeightDType
-from .pipeline import (
-    CanterOutputType,
-    CanterPipeline,
-    CanterPipelineConfig,
-    CanterPipelineMetadata,
-    CanterPipelineOutput,
+from .webui_app import (
+    _CSS,
+    _DARK_HEAD,
+    SizePreset,
+    _theme,
+    apply_size_preset,
+    create_loading_web_app,
+    create_web_app,
+    image_grid_style,
+    image_grid_visibility,
+    prepare_image_grid,
+    schedule_log_snr_shift,
+)
+from .webui_runtime import (
+    CanterWebController,
+    CanterWebLaunchConfig,
+    _choice,
+    _integer,
+    build_web_request,
+    snap_image_dimension,
+    update_pdg_clean_scale,
+)
+
+__all__ = (
+    "CanterWebController",
+    "CanterWebLaunchConfig",
+    "SizePreset",
+    "apply_size_preset",
+    "build_web_request",
+    "create_loading_web_app",
+    "create_web_app",
+    "image_grid_style",
+    "image_grid_visibility",
+    "launch_web_app",
+    "main",
+    "parse_launch_config",
+    "prepare_image_grid",
+    "schedule_log_snr_shift",
+    "snap_image_dimension",
+    "update_pdg_clean_scale",
 )
-from .schedules import Schedule
-from .solvers import Solver, SolverProgress
 
 _DEFAULT_MODEL = "data-archetype/canter"
 _DEFAULT_SERVER_NAME = "0.0.0.0"
 _DEFAULT_SERVER_PORT = 7860
-_MAX_QUEUE_SIZE = 8
-_DEFAULT_IMAGE_COUNT = 4
-_MAX_IMAGE_COUNT = 4
-_MAX_SEED = 2**63 - 1
-_GPU_CONCURRENCY_ID = "canter-gpu"
-_IMAGE_SIZE_MULTIPLE = 32
-_PNG_METADATA_KEY = "canter"
-
-_DEFAULT_INFERENCE = CanterInferenceConfig()
-_SOLVERS = {value.value: value for value in Solver}
-_SCHEDULES = {value.value: value for value in Schedule}
-_PDG_MODES = {value.value: value for value in PdgMode if value is not PdgMode.NONE}
-_PDG_CURVES = {value.value: value for value in PdgCurve}
+_TEMP_DIRECTORY_PREFIX = "canter-gradio"
+_TEMP_DIRECTORY_MARKER = ".canter-owned-temp-directory"
+_LOG_FORMAT = "%(asctime)s %(levelname)s %(name)s: %(message)s"
 _WEIGHT_DTYPES = {value.value: value for value in WeightDType}
 _TEXT_BACKENDS = {value.value: value for value in TextAttentionBackend}
 
-_SOLVER_CHOICES = (
-    ("ABM2", Solver.ABM2.value),
-    ("DPM++ 2M", Solver.DPMPP_2M.value),
-    ("Euler-Maruyama", Solver.EULER_MARUYAMA.value),
-    ("ER-SDE", Solver.ER_SDE.value),
-    ("Euler", Solver.EULER.value),
-)
-_SCHEDULE_CHOICES = (
-    ("Beta (0.6, 0.6)", Schedule.BETA.value),
-    ("Linear", Schedule.LINEAR.value),
-)
-_PDG_MODE_CHOICES = (
-    ("Full path drop", PdgMode.FULL.value),
-    ("Three-quarter path", PdgMode.THREE_QUARTER.value),
-    ("Alternate: PDG first", PdgMode.ALTERNATE_PDG_FIRST.value),
-    ("Alternate: CFG first", PdgMode.ALTERNATE_CFG_FIRST.value),
-    ("Combined CFG + PDG", PdgMode.COMBINED_CFG_PDG.value),
-    ("PDG with alternating CFG", PdgMode.PDG_WITH_ALTERNATING_CFG.value),
-    ("CFG then PDG", PdgMode.CFG_TO_PDG.value),
-)
-_PDG_CURVE_CHOICES = (
-    ("Constant", PdgCurve.CONSTANT.value),
-    ("Linear", PdgCurve.LINEAR.value),
-    ("Power", PdgCurve.POWER.value),
-)
-_DEFAULT_PROMPT = (
-    "Wide angle photo of a weathered wooden boardwalk descending steeply from "
-    "rocky cliffs toward a rugged coastline. The boardwalk, constructed from "
-    "aged planks with visible cracks and moss growth, is bordered by rustic "
-    "wooden railings on both sides. Surrounding terrain features uneven, eroded "
-    "rock formations covered in patches of green vegetation and low-lying "
-    "shrubs. Below, a crescent-shaped sandy beach meets crashing waves of a "
-    "deep blue ocean under a stormy, overcast sky with dark clouds and hints "
-    "of distant sunlight breaking through. The horizon shows turbulent waves "
-    "colliding with rocky outcrops, creating white foam."
-)
-
-
-class SizePreset(Enum):
-    """UI presets that jointly select image shape and attention gain."""
-
-    DEFAULT_PORTRAIT = "default_portrait"
-    WIDE = "wide"
-    TALL_PORTRAIT = "tall_portrait"
-
-
-@dataclass(frozen=True)
-class _SizePresetValues:
-    """Concrete image controls selected by one size preset."""
-
-    width: int
-    height: int
-    self_attention_gain: float
-
-
-_SIZE_PRESETS = {value.value: value for value in SizePreset}
-_SIZE_PRESET_CHOICES = (
-    ("832 × 1216 · gain −0.03", SizePreset.DEFAULT_PORTRAIT.value),
-    ("1536 × 832 · gain −0.02", SizePreset.WIDE.value),
-    ("1024 × 1536 · gain −0.02", SizePreset.TALL_PORTRAIT.value),
-)
-_SIZE_PRESET_VALUES = {
-    SizePreset.DEFAULT_PORTRAIT: _SizePresetValues(832, 1216, -0.03),
-    SizePreset.WIDE: _SizePresetValues(1536, 832, -0.02),
-    SizePreset.TALL_PORTRAIT: _SizePresetValues(1024, 1536, -0.02),
-}
-
-_DARK_HEAD = """
-<script>
-localStorage.setItem("theme", "dark");
-document.documentElement.classList.add("dark");
-document.documentElement.style.colorScheme = "dark";
-</script>
-"""
-
-_CSS = """
-:root, body {
-    background: #09090b;
-}
-.gradio-container {
-    max-width: none !important;
-    width: 100% !important;
-    padding: 1rem !important;
-}
-#canter-title h1 {
-    font-size: 2.1rem;
-    letter-spacing: -0.04em;
-    margin-bottom: 0.15rem;
-}
-#canter-workspace {
-    align-items: flex-start !important;
-}
-#canter-controls {
-    max-width: 440px;
-    min-width: 360px;
-}
-#canter-results {
-    min-width: 0;
-}
-#canter-image-grid {
-    display: grid !important;
-    grid-template-columns: repeat(auto-fit, minmax(min(100%, 832px), 1fr));
-    align-items: start !important;
-    gap: 1rem !important;
-    overflow: visible !important;
-}
-#canter-image-grid > div {
-    min-width: 0 !important;
-}
-.canter-image-cell {
-    position: relative;
-}
-.canter-total-progress {
-    margin-bottom: 0.75rem;
-}
-.canter-total-progress:not(:has(.canter-progress-panel)) {
-    display: none !important;
-}
-.canter-image-progress {
-    position: absolute !important;
-    top: 0.75rem;
-    left: 0.75rem;
-    right: 0.75rem;
-    z-index: 10;
-    pointer-events: none;
-}
-.canter-image-progress:not(:has(.canter-progress-panel)) {
-    display: none !important;
-}
-.canter-progress-panel {
-    padding: 0.65rem 0.75rem;
-    color: #f4f4f5;
-    background: rgb(9 9 11 / 88%);
-    border: 1px solid #3f3f46;
-    border-radius: 0.35rem;
-    box-shadow: 0 0.25rem 1rem rgb(0 0 0 / 35%);
-    backdrop-filter: blur(0.35rem);
-}
-.canter-progress-label {
-    margin-bottom: 0.4rem;
-    font-size: 0.85rem;
-    font-weight: 600;
-}
-.canter-progress-row {
-    display: grid;
-    grid-template-columns: 2.5rem minmax(0, 1fr) 2.5rem;
-    align-items: center;
-    gap: 0.45rem;
-    font-size: 0.72rem;
-    color: #d4d4d8;
-}
-.canter-progress-track {
-    height: 0.35rem;
-    overflow: hidden;
-    background: #27272a;
-    border-radius: 999px;
-}
-.canter-progress-track > div {
-    height: 100%;
-    background: var(--primary-500);
-    border-radius: inherit;
-    transition: width 120ms linear;
-}
-.canter-output-image,
-.canter-output-image > div {
-    overflow: visible !important;
-}
-.canter-output-image img {
-    display: block !important;
-    width: auto !important;
-    max-width: 100% !important;
-    height: auto !important;
-    max-height: none !important;
-    object-fit: contain !important;
-    margin: 0 auto !important;
-}
-#canter-status {
-    color: #a1a1aa;
-}
-@media (max-width: 900px) {
-    #canter-controls {
-        max-width: none;
-        min-width: 0;
-    }
-}
-"""
-
-_Choice = TypeVar("_Choice")
-
-
-class _ImagePipeline(Protocol):
-    """Typed Canter surface used by the web controller and its tests."""
-
-    metadata: CanterPipelineMetadata
-
-    def __call__(
-        self,
-        prompts: str | Sequence[str],
-        *,
-        config: CanterPipelineConfig,
-        initial_noise: None,
-        progress: SolverProgress | None,
-    ) -> CanterPipelineOutput:
-        """Generate decoded images for one web request."""
-
-        ...
-
-
-@dataclass(frozen=True)
-class CanterWebRequest:
-    """Validated sequential image request and frozen base configuration."""
-
-    prompt: str
-    image_count: int
-    config: CanterPipelineConfig
-
-
-@dataclass(frozen=True)
-class CanterWebLaunchConfig:
-    """Process-level model and server configuration for the bundled application."""
-
-    model: str
-    revision: str | None
-    dtype: WeightDType
-    text_backend: TextAttentionBackend
-    device: str
-    cache_dir: Path | None
-    server_name: str
-    server_port: int
-    share: bool
-    in_browser: bool
-
-
-@dataclass(frozen=True)
-class _BasicInputs:
-    """Prompt and basic generation controls rendered above advanced settings."""
-
-    prompt: gr.Textbox
-    image_count: gr.Slider
-    size_preset: gr.Dropdown
-    width: gr.Number
-    height: gr.Number
-    seed: gr.Number
-
-
-@dataclass(frozen=True)
-class _WebInputs:
-    """Gradio components in the exact callback argument order."""
-
-    prompt: gr.Textbox
-    image_count: gr.Slider
-    width: gr.Number
-    height: gr.Number
-    seed: gr.Number
-    steps: gr.Slider
-    solver: gr.Dropdown
-    schedule: gr.Dropdown
-    log_snr_shift: gr.Slider
-    self_attention_gain: gr.Slider
-    euler_maruyama_multiplier: gr.Slider
-    cfg_enabled: gr.Checkbox
-    cfg_scale: gr.Slider
-    cfg_start_step: gr.Number
-    cfg_stop_step: gr.Textbox
-    pdg_enabled: gr.Checkbox
-    pdg_mode: gr.Dropdown
-    pdg_curve: gr.Dropdown
-    pdg_noisy_scale: gr.Slider
-    pdg_clean_scale: gr.Slider
-    pdg_power: gr.Slider
-    pdg_start_step: gr.Number
-    pdg_stop_step: gr.Textbox
-
-    def ordered(self) -> tuple[gr.Component, ...]:
-        """Return components in the order accepted by ``generate``."""
-
-        return (
-            self.prompt,
-            self.image_count,
-            self.width,
-            self.height,
-            self.seed,
-            self.steps,
-            self.solver,
-            self.schedule,
-            self.log_snr_shift,
-            self.self_attention_gain,
-            self.euler_maruyama_multiplier,
-            self.cfg_enabled,
-            self.cfg_scale,
-            self.cfg_start_step,
-            self.cfg_stop_step,
-            self.pdg_enabled,
-            self.pdg_mode,
-            self.pdg_curve,
-            self.pdg_noisy_scale,
-            self.pdg_clean_scale,
-            self.pdg_power,
-            self.pdg_start_step,
-            self.pdg_stop_step,
-        )
-
-
-@dataclass(frozen=True)
-class _WebOutputs:
-    """Image slots and status component in callback output order."""
-
-    images: tuple[gr.Image, gr.Image, gr.Image, gr.Image]
-    status: gr.Markdown
-    progress_timer: gr.Timer
-
-    def ordered(self) -> tuple[gr.Component, ...]:
-        """Return image, status, and progress-lifecycle callback outputs."""
-
-        return (*self.images, self.status, self.progress_timer)
-
-
-_ImageSlotUpdate: TypeAlias = Image.Image | dict[str, str] | None
-_GenerationUpdate: TypeAlias = tuple[
-    _ImageSlotUpdate,
-    _ImageSlotUpdate,
-    _ImageSlotUpdate,
-    _ImageSlotUpdate,
-    str,
-    dict[str, object],
-]
-
-
-class _GenerationStoppedError(RuntimeError):
-    """Cooperative-cancellation signal for one web generation."""
-
-
-@dataclass(frozen=True)
-class _WebProgressState:
-    """Current solver position for one browser generation request."""
-
-    image_index: int
-    image_count: int
-    completed_updates: int
-    total_updates: int
-
-
-@dataclass(frozen=True)
-class _WebGenerationState:
-    """Cancellation and progress state owned by one browser generation."""
-
-    stop_requested: threading.Event
-    progress: _WebProgressState
-
-
-class CanterWebController:
-    """Translate Gradio values into one deterministic pipeline invocation."""
-
-    def __init__(
-        self,
-        pipeline: _ImagePipeline | None,
-        *,
-        load_config: CanterWebLaunchConfig | None = None,
-    ) -> None:
-        """Retain a pipeline or the exact configuration needed to load it."""
-
-        if pipeline is None and load_config is None:
-            raise ValueError("A lazy Canter web controller requires load_config.")
-        if pipeline is not None and load_config is not None:
-            raise ValueError("Provide either pipeline or load_config, not both.")
-
-        self.pipeline = pipeline
-        self._load_config = load_config
-        self._load_lock = threading.Lock()
-        self._session_lock = threading.Lock()
-        self._generation_by_session: dict[str, _WebGenerationState] = {}
-
-    def load(self) -> tuple[str, str, dict[str, object], dict[str, object]]:
-        """Load once, then return ready-state UI updates for every browser session."""
-
-        pipeline = self._ensure_loaded()
-        return (
-            _model_summary(pipeline.metadata),
-            "Ready. The first request includes compiled graph warm-up.",
-            gr.update(interactive=True),
-            gr.update(interactive=True),
-        )
-
-    def request_stop(self, request: gr.Request | None = None) -> str:
-        """Cancel only the active generation owned by the requesting browser."""
-
-        session_hash = _session_hash(request)
-        with self._session_lock:
-            state = self._generation_by_session.get(session_hash)
-            if state is None:
-                return "No generation is currently active in this browser session."
-            state.stop_requested.set()
-        return "Stopping after the current solver step…"
-
-    def generate(  # noqa: PLR0917 - Gradio supplies the explicit form fields.
-        self,
-        prompt: str,
-        image_count: int | float,
-        width: int | float,
-        height: int | float,
-        seed: int | float,
-        steps: int | float,
-        solver: str,
-        schedule: str,
-        log_snr_shift: int | float,
-        self_attention_gain: int | float,
-        euler_maruyama_multiplier: int | float,
-        cfg_enabled: bool,
-        cfg_scale: int | float,
-        cfg_start_step: int | float,
-        cfg_stop_step: int | float | str | None,
-        pdg_enabled: bool,
-        pdg_mode: str,
-        pdg_curve: str,
-        pdg_noisy_scale: int | float,
-        pdg_clean_scale: int | float,
-        pdg_power: int | float,
-        pdg_start_step: int | float,
-        pdg_stop_step: int | float | str | None,
-        browser_request: gr.Request | None = None,
-    ) -> Generator[_GenerationUpdate, None, None]:
-        """Yield each batch-one image as soon as its decoding completes."""
-
-        session_hash = _session_hash(browser_request)
-        pipeline = self._ensure_loaded()
-        request = build_web_request(
-            prompt=prompt,
-            image_count=image_count,
-            width=width,
-            height=height,
-            seed=seed,
-            steps=steps,
-            solver=solver,
-            schedule=schedule,
-            log_snr_shift=log_snr_shift,
-            self_attention_gain=self_attention_gain,
-            euler_maruyama_multiplier=euler_maruyama_multiplier,
-            cfg_enabled=cfg_enabled,
-            cfg_scale=cfg_scale,
-            cfg_start_step=cfg_start_step,
-            cfg_stop_step=cfg_stop_step,
-            pdg_enabled=pdg_enabled,
-            pdg_mode=pdg_mode,
-            pdg_curve=pdg_curve,
-            pdg_noisy_scale=pdg_noisy_scale,
-            pdg_clean_scale=pdg_clean_scale,
-            pdg_power=pdg_power,
-            pdg_start_step=pdg_start_step,
-            pdg_stop_step=pdg_stop_step,
-        )
-        _log_generation_request(request)
-        started = time.perf_counter()
-        guidance = _pdg_status(request.config.inference)
-        stop_requested = self._begin_generation(
-            session_hash,
-            image_index=0,
-            image_count=request.image_count,
-            completed_updates=0,
-            total_updates=request.config.inference.steps,
-        )
-        try:
-            yield _generation_update(
-                _cleared_image_slots(),
-                f"Generating **{request.image_count} images** with batch size `1` · "
-                f"{guidance}…",
-                progress_active=True,
-            )
-            for image_index in range(request.image_count):
-                self._raise_if_stopped(stop_requested)
-                image_number = image_index + 1
-                self._set_progress(
-                    session_hash,
-                    image_index=image_index,
-                    image_count=request.image_count,
-                    completed_updates=0,
-                    total_updates=request.config.inference.steps,
-                )
-                image_config = _image_config(request, image_index)
-                output = pipeline(
-                    request.prompt,
-                    config=image_config,
-                    initial_noise=None,
-                    progress=_step_progress(
-                        stopped=stop_requested.is_set,
-                        update_web=lambda completed, total, index=image_index: (
-                            self._set_progress(
-                                session_hash,
-                                image_index=index,
-                                image_count=request.image_count,
-                                completed_updates=completed,
-                                total_updates=total,
-                            )
-                        ),
-                    ),
-                )
-                self._raise_if_stopped(stop_requested)
-                if output.images is None or len(output.images) != 1:
-                    raise RuntimeError(
-                        "Each batch-one Canter web invocation must return one PIL image."
-                    )
-                image = _attach_png_metadata(
-                    output.images[0],
-                    prompt=request.prompt,
-                    config=image_config,
-                    metadata=pipeline.metadata,
-                )
-                elapsed = time.perf_counter() - started
-                status = _generation_status(
-                    pipeline.metadata,
-                    request=request,
-                    elapsed=elapsed,
-                    completed=image_number,
-                )
-                yield _generation_update(
-                    _completed_image_slots(
-                        image=image,
-                        image_index=image_index,
-                        image_count=request.image_count,
-                    ),
-                    status,
-                    progress_active=None,
-                )
-        except _GenerationStoppedError:
-            yield _generation_update(
-                _preserved_image_slots(),
-                "Stopped. Ready for another request.",
-                progress_active=None,
-            )
-        finally:
-            self._finish_generation(session_hash, stop_requested)
-
-    def poll_progress(
-        self,
-        request: gr.Request | None = None,
-    ) -> tuple[str, str, str, str, str, dict[str, object]]:
-        """Return progress HTML and whether this session still needs polling."""
-
-        session_hash = _session_hash(request)
-        with self._session_lock:
-            generation = self._generation_by_session.get(session_hash)
-        state = None if generation is None else generation.progress
-        return (*_progress_html(state), gr.update(active=generation is not None))
-
-    def _raise_if_stopped(self, stop_requested: threading.Event) -> None:
-        """Abort at the next safe boundary after a web stop request."""
-
-        if stop_requested.is_set():
-            raise _GenerationStoppedError
-
-    def _begin_generation(
-        self,
-        session_hash: str,
-        *,
-        image_index: int,
-        image_count: int,
-        completed_updates: int,
-        total_updates: int,
-    ) -> threading.Event:
-        """Register and return cancellation state for a new browser generation."""
-
-        progress = _WebProgressState(
-            image_index=image_index,
-            image_count=image_count,
-            completed_updates=completed_updates,
-            total_updates=total_updates,
-        )
-        stop_requested = threading.Event()
-        state = _WebGenerationState(
-            stop_requested=stop_requested,
-            progress=progress,
-        )
-        with self._session_lock:
-            if session_hash in self._generation_by_session:
-                raise RuntimeError(
-                    "A browser session cannot run multiple Canter generations."
-                )
-            self._generation_by_session[session_hash] = state
-        return stop_requested
-
-    def _set_progress(
-        self,
-        session_hash: str,
-        *,
-        image_index: int,
-        image_count: int,
-        completed_updates: int,
-        total_updates: int,
-    ) -> None:
-        """Publish one solver position for the requesting browser session."""
-
-        progress = _WebProgressState(
-            image_index=image_index,
-            image_count=image_count,
-            completed_updates=completed_updates,
-            total_updates=total_updates,
-        )
-        with self._session_lock:
-            state = self._generation_by_session.get(session_hash)
-            if state is None:
-                raise RuntimeError(
-                    "Cannot update progress without an active generation."
-                )
-            self._generation_by_session[session_hash] = replace(
-                state,
-                progress=progress,
-            )
-
-    def _finish_generation(
-        self,
-        session_hash: str,
-        stop_requested: threading.Event,
-    ) -> None:
-        """Remove exactly the browser generation that has finished."""
-
-        with self._session_lock:
-            state = self._generation_by_session.get(session_hash)
-            if state is None or state.stop_requested is not stop_requested:
-                raise RuntimeError(
-                    "Canter browser generation state became inconsistent."
-                )
-            del self._generation_by_session[session_hash]
-
-    def _ensure_loaded(self) -> _ImagePipeline:
-        """Return the process pipeline, loading it exactly once when necessary."""
-
-        with self._load_lock:
-            if self.pipeline is None:
-                config = self._load_config
-                if config is None:
-                    raise RuntimeError(
-                        "Lazy Canter loading is missing its launch configuration."
-                    )
-                self.pipeline = load_web_pipeline(config)
-            return self.pipeline
-
-
-def _preserved_image_slots() -> tuple[
-    dict[str, str],
-    dict[str, str],
-    dict[str, str],
-    dict[str, str],
-]:
-    """Return four no-op updates that keep displayed images visible."""
-
-    return (gr.skip(), gr.skip(), gr.skip(), gr.skip())
-
-
-def _cleared_image_slots() -> tuple[None, None, None, None]:
-    """Clear all prior results before starting a new generation."""
-
-    return (None, None, None, None)
-
-
-def _completed_image_slots(
-    *,
-    image: Image.Image,
-    image_index: int,
-    image_count: int,
-) -> tuple[_ImageSlotUpdate, _ImageSlotUpdate, _ImageSlotUpdate, _ImageSlotUpdate]:
-    """Update only the new image and clear unused slots after the final image."""
-
-    updates: list[_ImageSlotUpdate] = list(_preserved_image_slots())
-    updates[image_index] = image
-    if image_index + 1 == image_count:
-        for unused_index in range(image_count, _MAX_IMAGE_COUNT):
-            updates[unused_index] = None
-    return (updates[0], updates[1], updates[2], updates[3])
-
-
-def _generation_update(
-    image_slots: Sequence[_ImageSlotUpdate],
-    status: str,
-    *,
-    progress_active: bool | None,
-) -> _GenerationUpdate:
-    """Return image, status, and timer updates expected by Gradio."""
-
-    if len(image_slots) != _MAX_IMAGE_COUNT:
-        raise ValueError(
-            f"Expected {_MAX_IMAGE_COUNT} web image slots, got {len(image_slots)}."
-        )
-    return (
-        image_slots[0],
-        image_slots[1],
-        image_slots[2],
-        image_slots[3],
-        status,
-        (gr.skip() if progress_active is None else gr.update(active=progress_active)),
-    )
-
-
-def _step_progress(
-    *,
-    stopped: Callable[[], bool],
-    update_web: Callable[[int, int], None],
-) -> SolverProgress:
-    """Create an exact solver-update reporter for one sequential image."""
-
-    def report(completed: int, total: int) -> None:
-        """Update the current image bar while retaining the total image bar."""
-
-        if stopped():
-            raise _GenerationStoppedError
-        update_web(completed, total)
-
-    return report
-
-
-def _session_hash(request: gr.Request | None) -> str:
-    """Return the required Gradio browser-session identifier."""
-
-    if request is None or request.session_hash is None or not request.session_hash:
-        raise ValueError("Web generation requires a Gradio browser session hash.")
-    return request.session_hash
-
-
-def _progress_html(
-    state: _WebProgressState | None,
-) -> tuple[str, str, str, str, str]:
-    """Render the total bar and the active image's solver overlay."""
-
-    slots = ["", "", "", ""]
-    if state is None:
-        return ("", slots[0], slots[1], slots[2], slots[3])
-    image_fraction = state.completed_updates / state.total_updates
-    total_fraction = (state.image_index + image_fraction) / state.image_count
-    image_percent = 100.0 * image_fraction
-    total_percent = 100.0 * total_fraction
-    total_html = f"""
-<div class="canter-progress-panel">
-  <div class="canter-progress-label">
-    Total progress · Image {state.image_index + 1}/{state.image_count}
-  </div>
-  <div class="canter-progress-row">
-    <span>Total</span>
-    <div class="canter-progress-track">
-      <div style="width: {total_percent:.2f}%"></div>
-    </div>
-    <span>{total_percent:.0f}%</span>
-  </div>
-</div>
-"""
-    slots[state.image_index] = f"""
-<div class="canter-progress-panel">
-  <div class="canter-progress-label">
-    Image {state.image_index + 1}/{state.image_count}
-    · {state.completed_updates}/{state.total_updates} updates
-  </div>
-  <div class="canter-progress-row">
-    <span>Image</span>
-    <div class="canter-progress-track">
-      <div style="width: {image_percent:.2f}%"></div>
-    </div>
-    <span>{image_percent:.0f}%</span>
-  </div>
-</div>
-"""
-    return (total_html, slots[0], slots[1], slots[2], slots[3])
-
-
-def _choice(
-    value: str | None,
-    choices: Mapping[str, _Choice],
-    name: str,
-) -> _Choice:
-    """Resolve one exact enum-backed form choice or fail with its field name."""
-
-    if value is None:
-        raise ValueError(f"{name} is required.")
-    selected = choices.get(value)
-    if selected is None:
-        raise ValueError(f"Unsupported {name}: {value!r}.")
-    return selected
-
-
-def _integer(
-    value: int | float | None,
-    name: str,
-    *,
-    minimum: int,
-    maximum: int | None,
-) -> int:
-    """Convert one integral form number and enforce its explicit bounds."""
-
-    if value is None or isinstance(value, bool):
-        raise TypeError(f"{name} must be an integer.")
-    number = float(value)
-    if not math.isfinite(number) or not number.is_integer():
-        raise ValueError(f"{name} must be a finite integer.")
-    result = int(number)
-    if result < minimum:
-        raise ValueError(f"{name} must be at least {minimum}.")
-    if maximum is not None and result > maximum:
-        raise ValueError(f"{name} must not exceed {maximum}.")
-    return result
-
-
-def _optional_integer(
-    value: int | float | str | None,
-    name: str,
-) -> int | None:
-    """Convert a blank solver stop field to ``None`` or validate an index."""
-
-    if value is None:
-        return None
-    if isinstance(value, str):
-        stripped = value.strip()
-        if not stripped:
-            return None
-        try:
-            numeric = float(stripped)
-        except ValueError as exc:
-            raise ValueError(f"{name} must be blank or a finite integer.") from exc
-        return _integer(numeric, name, minimum=0, maximum=None)
-    return _integer(value, name, minimum=0, maximum=None)
-
-
-def _number(value: int | float, name: str) -> float:
-    """Require one finite floating-point form value."""
-
-    if isinstance(value, bool):
-        raise TypeError(f"{name} must be a number.")
-    result = float(value)
-    if not math.isfinite(result):
-        raise ValueError(f"{name} must be finite.")
-    return result
-
-
-def _image_dimension(value: int | float | None, name: str) -> int:
-    """Snap one finite image dimension to the supported 32-pixel lattice."""
-
-    if value is None:
-        raise ValueError(f"{name} is required.")
-    number = _number(value, name)
-    if number < _IMAGE_SIZE_MULTIPLE:
-        raise ValueError(f"{name} must be at least {_IMAGE_SIZE_MULTIPLE}.")
-    return snap_image_dimension(number)
-
-
-def snap_image_dimension(value: int | float | None) -> int:
-    """Snap one browser image dimension to its nearest valid multiple."""
-
-    if value is None:
-        raise ValueError("image size is required.")
-    number = _number(value, "image size")
-    snapped = math.floor(
-        (max(number, _IMAGE_SIZE_MULTIPLE) + _IMAGE_SIZE_MULTIPLE / 2)
-        / _IMAGE_SIZE_MULTIPLE
-    )
-    return snapped * _IMAGE_SIZE_MULTIPLE
-
-
-def _validated_prompt(prompt: str) -> str:
-    """Return a string prompt without changing the user's text."""
-
-    if not isinstance(prompt, str):
-        raise TypeError("prompt must be a string.")
-    return prompt
-
-
-def _pdg_mode_uses_cfg(mode: PdgMode) -> bool:
-    """Return whether one public PDG mode consumes the CFG scale."""
-
-    match mode:
-        case (
-            PdgMode.ALTERNATE_PDG_FIRST
-            | PdgMode.ALTERNATE_CFG_FIRST
-            | PdgMode.COMBINED_CFG_PDG
-            | PdgMode.PDG_WITH_ALTERNATING_CFG
-            | PdgMode.CFG_TO_PDG
-        ):
-            return True
-        case PdgMode.FULL | PdgMode.THREE_QUARTER:
-            return False
-        case PdgMode.NONE:
-            raise ValueError("The enabled web PDG selection cannot use mode none.")
-        case _ as unreachable:
-            raise RuntimeError(f"Unsupported PDG mode: {unreachable}")
-
-
-def update_pdg_clean_scale(
-    curve: str,
-    noisy_scale: int | float,
-) -> dict[str, object]:
-    """Disable and synchronize the unused clean endpoint for constant PDG."""
-
-    resolved_curve = _choice(curve, _PDG_CURVES, "PDG curve")
-    match resolved_curve:
-        case PdgCurve.CONSTANT:
-            return gr.update(
-                value=_number(noisy_scale, "PDG noisy scale"),
-                interactive=False,
-            )
-        case PdgCurve.LINEAR | PdgCurve.POWER:
-            return gr.update(interactive=True)
-        case _ as unreachable:
-            raise RuntimeError(f"Unsupported PDG curve: {unreachable}")
-
-
-def build_web_request(
-    *,
-    prompt: str,
-    image_count: int | float,
-    width: int | float,
-    height: int | float,
-    seed: int | float,
-    steps: int | float,
-    solver: str,
-    schedule: str,
-    log_snr_shift: int | float,
-    self_attention_gain: int | float,
-    euler_maruyama_multiplier: int | float,
-    cfg_enabled: bool,
-    cfg_scale: int | float,
-    cfg_start_step: int | float,
-    cfg_stop_step: int | float | str | None,
-    pdg_enabled: bool,
-    pdg_mode: str,
-    pdg_curve: str,
-    pdg_noisy_scale: int | float,
-    pdg_clean_scale: int | float,
-    pdg_power: int | float,
-    pdg_start_step: int | float,
-    pdg_stop_step: int | float | str | None,
-) -> CanterWebRequest:
-    """Validate raw Gradio values and construct the frozen Canter dataclasses."""
-
-    resolved_pdg_mode = _choice(pdg_mode, _PDG_MODES, "PDG mode")
-    active_pdg_mode = resolved_pdg_mode if pdg_enabled else PdgMode.NONE
-    uses_cfg_scale = pdg_enabled and _pdg_mode_uses_cfg(resolved_pdg_mode)
-    resolved_cfg_scale = (
-        _number(cfg_scale, "CFG scale") if cfg_enabled or uses_cfg_scale else None
-    )
-    cfg = CfgGuidance(
-        enabled=cfg_enabled,
-        scale=resolved_cfg_scale,
-        start_step=_integer(
-            cfg_start_step,
-            "CFG start step",
-            minimum=0,
-            maximum=None,
-        ),
-        stop_step=_optional_integer(cfg_stop_step, "CFG stop step"),
-    )
-    resolved_pdg_curve = _choice(pdg_curve, _PDG_CURVES, "PDG curve")
-    resolved_pdg_noisy_scale = _number(pdg_noisy_scale, "PDG noisy scale")
-    resolved_pdg_clean_scale = (
-        resolved_pdg_noisy_scale
-        if resolved_pdg_curve is PdgCurve.CONSTANT
-        else _number(pdg_clean_scale, "PDG clean scale")
-    )
-    pdg = PdgGuidance(
-        enabled=pdg_enabled,
-        mode=active_pdg_mode,
-        curve=resolved_pdg_curve,
-        noisy_scale=resolved_pdg_noisy_scale,
-        clean_scale=resolved_pdg_clean_scale,
-        power=_number(pdg_power, "PDG power"),
-        start_step=_integer(
-            pdg_start_step,
-            "PDG start step",
-            minimum=0,
-            maximum=None,
-        ),
-        stop_step=_optional_integer(pdg_stop_step, "PDG stop step"),
-    )
-    resolved_image_count = _integer(
-        image_count,
-        "image count",
-        minimum=1,
-        maximum=_MAX_IMAGE_COUNT,
-    )
-    resolved_seed = _integer(
-        seed,
-        "seed",
-        minimum=0,
-        maximum=_MAX_SEED - resolved_image_count + 1,
-    )
-    inference = CanterInferenceConfig(
-        height=_image_dimension(height, "height"),
-        width=_image_dimension(width, "width"),
-        steps=_integer(steps, "steps", minimum=1, maximum=None),
-        solver=_choice(solver, _SOLVERS, "solver"),
-        schedule=_choice(schedule, _SCHEDULES, "schedule"),
-        log_snr_shift=_number(log_snr_shift, "log-SNR shift"),
-        cfg=cfg,
-        pdg=pdg,
-        self_attention_gain=_number(
-            self_attention_gain,
-            "self-attention gain",
-        ),
-        euler_maruyama_multiplier=_number(
-            euler_maruyama_multiplier,
-            "SDE noise multiplier",
-        ),
-        er_sde_noise_multiplier=_number(
-            euler_maruyama_multiplier,
-            "SDE noise multiplier",
-        ),
-        seed=resolved_seed,
-        generator=None,
-    )
-    return CanterWebRequest(
-        prompt=_validated_prompt(prompt),
-        image_count=resolved_image_count,
-        config=CanterPipelineConfig(
-            inference=inference,
-            output_type=CanterOutputType.PIL,
-        ),
-    )
-
-
-def _image_config(
-    request: CanterWebRequest,
-    image_index: int,
-) -> CanterPipelineConfig:
-    """Return a batch-one config using the next deterministic image seed."""
-
-    seed = request.config.inference.seed
-    if seed is None:
-        raise RuntimeError("A validated Canter web request must contain a seed.")
-    inference = replace(
-        request.config.inference,
-        seed=seed + image_index,
-        generator=None,
-    )
-    return replace(request.config, inference=inference)
-
-
-def _pdg_metadata(pdg: PdgGuidance) -> dict[str, object]:
-    """Return PDG fields in public API order."""
-
-    return {
-        "enabled": pdg.enabled,
-        "mode": pdg.mode.value,
-        "curve": pdg.curve.value,
-        "noisy_scale": pdg.noisy_scale,
-        "clean_scale": pdg.clean_scale,
-        "power": pdg.power,
-        "start_step": pdg.start_step,
-        "stop_step": pdg.stop_step,
-    }
-
-
-def _cfg_metadata(cfg: CfgGuidance) -> dict[str, object]:
-    """Return CFG fields in public API order."""
-
-    return {
-        "enabled": cfg.enabled,
-        "scale": cfg.scale,
-        "start_step": cfg.start_step,
-        "stop_step": cfg.stop_step,
-    }
-
-
-def _png_metadata_json(
-    *,
-    prompt: str,
-    config: CanterPipelineConfig,
-    metadata: CanterPipelineMetadata,
-) -> str:
-    """Serialize reproducible UI settings with primary inputs first."""
-
-    inference = config.inference
-    if inference.seed is None:
-        raise RuntimeError("PNG metadata requires the resolved per-image seed.")
-    payload: dict[str, object] = {
-        "prompt": prompt,
-        "seed": inference.seed,
-        "width": inference.width,
-        "height": inference.height,
-        "steps": inference.steps,
-        "solver": inference.solver.value,
-        "schedule": inference.schedule.value,
-        "pdg": _pdg_metadata(inference.pdg),
-        "cfg": _cfg_metadata(inference.cfg),
-        "self_attention_gain": inference.self_attention_gain,
-        "log_snr_shift": inference.log_snr_shift,
-        "euler_maruyama_multiplier": inference.euler_maruyama_multiplier,
-        "er_sde_noise_multiplier": inference.er_sde_noise_multiplier,
-        "code_version": metadata.code_version,
-        "release": metadata.canter.release,
-        "weight_dtype": metadata.canter.weight_dtype.value,
-    }
-    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
-
-
-def _attach_png_metadata(
-    image: Image.Image,
-    *,
-    prompt: str,
-    config: CanterPipelineConfig,
-    metadata: CanterPipelineMetadata,
-) -> Image.Image:
-    """Attach the ordered API query for Gradio's PNG encoder."""
-
-    image.info[_PNG_METADATA_KEY] = _png_metadata_json(
-        prompt=prompt,
-        config=config,
-        metadata=metadata,
-    )
-    return image
-
-
-def random_seed() -> int:
-    """Return a non-negative seed accepted by the Canter web form."""
-
-    return secrets.randbelow(_MAX_SEED + 1)
-
-
-def _model_summary(metadata: CanterPipelineMetadata) -> str:
-    """Render immutable model and decoder provenance above the controls."""
-
-    canter = metadata.canter
-    return (
-        f"**Canter checkpoint {canter.release}** · "
-        f"code `{metadata.code_version}` · "
-        f"{canter.weight_dtype.value} EMA weights  \n"
-        f"VAE `{metadata.vae_repository}` @ `{metadata.vae_revision[:12]}`"
-    )
-
-
-def _log_generation_request(request: CanterWebRequest) -> None:
-    """Print the exact effective controls consumed by one generation request."""
-
-    inference = request.config.inference
-    prompt_digest = sha256(request.prompt.encode("utf-8")).hexdigest()[:12]
-    print(
-        "Canter request | "
-        f"prompt_sha256={prompt_digest} | images={request.image_count} | "
-        f"size={inference.width}x{inference.height} | seed={inference.seed} | "
-        f"steps={inference.steps} | solver={inference.solver.value} | "
-        f"schedule={inference.schedule.value} | "
-        f"log_snr_shift={inference.log_snr_shift:g} | "
-        f"self_attention_gain={inference.self_attention_gain:g} | "
-        f"{_pdg_status(inference)} | cfg_enabled={inference.cfg.enabled} | "
-        f"cfg_scale={inference.cfg.scale}",
-        flush=True,
-    )
-
-
-def _pdg_status(inference: CanterInferenceConfig) -> str:
-    """Render the effective PDG request consumed by latent inference."""
-
-    pdg = inference.pdg
-    if not pdg.enabled:
-        return "PDG off"
-    stop = inference.steps - 1 if pdg.stop_step is None else pdg.stop_step
-    match pdg.curve:
-        case PdgCurve.CONSTANT:
-            scale = f"{float(pdg.noisy_scale):g}"
-        case PdgCurve.LINEAR:
-            scale = f"linear {float(pdg.noisy_scale):g}→{float(pdg.clean_scale):g}"
-        case PdgCurve.POWER:
-            scale = (
-                f"power {float(pdg.noisy_scale):g}→"
-                f"{float(pdg.clean_scale):g} (p={float(pdg.power):g})"
-            )
-        case _ as unreachable:
-            raise RuntimeError(f"Unsupported PDG curve: {unreachable}")
-    return f"PDG `{pdg.mode.value}` {scale}, updates {pdg.start_step}–{stop}"
-
-
-def _generation_status(
-    metadata: CanterPipelineMetadata,
-    *,
-    request: CanterWebRequest,
-    elapsed: float,
-    completed: int,
-) -> str:
-    """Render incremental timing and deterministic request provenance."""
-
-    inference = request.config.inference
-    image_word = "image" if completed == 1 else "images"
-    if inference.seed is None:
-        raise RuntimeError("A validated Canter web request must contain a seed.")
-    final_seed = inference.seed + completed - 1
-    seed_text = (
-        str(inference.seed) if completed == 1 else f"{inference.seed}–{final_seed}"
-    )
-    progress_text = (
-        f"Generated **{completed}/{request.image_count} {image_word}**"
-        if completed < request.image_count
-        else f"Generated **{completed} {image_word}**"
-    )
-    return (
-        f"{progress_text} in **{elapsed:.2f}s** · "
-        f"seeds `{seed_text}` · batch size `1` · "
-        f"{inference.width}×{inference.height} · "
-        f"{inference.steps} {inference.solver.value} updates · "
-        f"{_pdg_status(inference)} · "
-        f"Canter code `{metadata.code_version}` · "
-        f"checkpoint `{metadata.canter.release}`"
-    )
-
-
-def _prompt_input() -> gr.Textbox:
-    """Create the prompt control without rendering it yet."""
-
-    return gr.Textbox(
-        label="Prompt",
-        value=_DEFAULT_PROMPT,
-        lines=3,
-        placeholder="Describe the image you want to generate.",
-        render=False,
-    )
-
-
-def _basic_inputs(prompt: gr.Textbox) -> _BasicInputs:
-    """Render prompt, image-count, preset, shape, and seed controls."""
-
-    prompt.render()
-    image_count = gr.Slider(
-        minimum=1,
-        maximum=_MAX_IMAGE_COUNT,
-        value=_DEFAULT_IMAGE_COUNT,
-        step=1,
-        precision=0,
-        label="Images",
-        info="Generated sequentially with batch size 1.",
-    )
-    size_preset = gr.Dropdown(
-        choices=_SIZE_PRESET_CHOICES,
-        value=SizePreset.DEFAULT_PORTRAIT.value,
-        label="Size preset",
-        allow_custom_value=False,
-    )
-    with gr.Row():
-        width = gr.Number(
-            value=_DEFAULT_INFERENCE.width,
-            label="Width",
-            precision=0,
-            minimum=_IMAGE_SIZE_MULTIPLE,
-            step=_IMAGE_SIZE_MULTIPLE,
-        )
-        height = gr.Number(
-            value=_DEFAULT_INFERENCE.height,
-            label="Height",
-            precision=0,
-            minimum=_IMAGE_SIZE_MULTIPLE,
-            step=_IMAGE_SIZE_MULTIPLE,
-        )
-    seed = gr.Number(
-        value=_DEFAULT_INFERENCE.seed,
-        label="Seed",
-        precision=0,
-        minimum=0,
-        maximum=_MAX_SEED,
-    )
-    return _BasicInputs(
-        prompt=prompt,
-        image_count=image_count,
-        size_preset=size_preset,
-        width=width,
-        height=height,
-        seed=seed,
-    )
-
-
-def apply_size_preset(value: str | None) -> tuple[int, int, float]:
-    """Return width, height, and attention gain for one exact UI preset."""
-
-    preset = _choice(value, _SIZE_PRESETS, "size preset")
-    selected = _SIZE_PRESET_VALUES[preset]
-    return selected.width, selected.height, selected.self_attention_gain
-
-
-def schedule_log_snr_shift(value: str | None) -> float:
-    """Return the UI log-SNR preset associated with one schedule."""
-
-    schedule = _choice(value, _SCHEDULES, "schedule")
-    match schedule:
-        case Schedule.BETA:
-            return 0.0
-        case Schedule.LINEAR:
-            return -2.3
-        case _ as unreachable:
-            raise RuntimeError(f"Unsupported Canter schedule: {unreachable}")
-
-
-def _solver_inputs() -> tuple[
-    gr.Slider,
-    gr.Dropdown,
-    gr.Dropdown,
-    gr.Slider,
-    gr.Slider,
-    gr.Slider,
-]:
-    """Create solver, schedule, and model-gain controls."""
-
-    steps = gr.Slider(
-        minimum=1,
-        maximum=100,
-        value=_DEFAULT_INFERENCE.steps,
-        step=1,
-        precision=0,
-        label="Solver updates",
-    )
-    with gr.Row():
-        solver = gr.Dropdown(
-            choices=_SOLVER_CHOICES,
-            value=_DEFAULT_INFERENCE.solver.value,
-            label="Solver",
-            allow_custom_value=False,
-        )
-        schedule = gr.Dropdown(
-            choices=_SCHEDULE_CHOICES,
-            value=_DEFAULT_INFERENCE.schedule.value,
-            label="Schedule",
-            allow_custom_value=False,
-        )
-    log_snr_shift = gr.Slider(
-        minimum=-4.0,
-        maximum=4.0,
-        value=_DEFAULT_INFERENCE.log_snr_shift,
-        step=0.05,
-        label="Log-SNR shift",
-    )
-    self_attention_gain = gr.Slider(
-        minimum=-0.05,
-        maximum=0.02,
-        value=_DEFAULT_INFERENCE.self_attention_gain,
-        step=0.005,
-        label="Main self-attention gain",
-    )
-    euler_maruyama_multiplier = gr.Slider(
-        minimum=0.0,
-        maximum=2.0,
-        value=_DEFAULT_INFERENCE.euler_maruyama_multiplier,
-        step=0.05,
-        label="SDE noise multiplier",
-    )
-    return (
-        steps,
-        solver,
-        schedule,
-        log_snr_shift,
-        self_attention_gain,
-        euler_maruyama_multiplier,
-    )
-
-
-def _cfg_inputs() -> tuple[
-    gr.Checkbox,
-    gr.Slider,
-    gr.Number,
-    gr.Textbox,
-]:
-    """Create classifier-free guidance controls."""
-
-    enabled = gr.Checkbox(
-        value=_DEFAULT_INFERENCE.cfg.enabled,
-        label="Enable CFG",
-    )
-    scale = gr.Slider(
-        minimum=0.0,
-        maximum=10.0,
-        value=3.0,
-        step=0.05,
-        label="CFG scale",
-        info="Also used by CFG-dependent PDG modes.",
-    )
-    with gr.Row():
-        start = gr.Number(
-            value=_DEFAULT_INFERENCE.cfg.start_step,
-            label="CFG start",
-            precision=0,
-            minimum=0,
-        )
-        stop = gr.Textbox(
-            value="",
-            label="CFG stop",
-            info="Blank means the final solver update.",
-            placeholder="Final",
-            lines=1,
-        )
-    return enabled, scale, start, stop
-
-
-def _pdg_inputs() -> tuple[
-    gr.Checkbox,
-    gr.Dropdown,
-    gr.Dropdown,
-    gr.Slider,
-    gr.Slider,
-    gr.Slider,
-    gr.Number,
-    gr.Textbox,
-]:
-    """Create path-drop guidance and curve controls."""
-
-    enabled = gr.Checkbox(
-        value=_DEFAULT_INFERENCE.pdg.enabled,
-        label="Enable PDG",
-    )
-    with gr.Row():
-        mode = gr.Dropdown(
-            choices=_PDG_MODE_CHOICES,
-            value=_DEFAULT_INFERENCE.pdg.mode.value,
-            label="PDG mode",
-            allow_custom_value=False,
-        )
-        curve = gr.Dropdown(
-            choices=_PDG_CURVE_CHOICES,
-            value=_DEFAULT_INFERENCE.pdg.curve.value,
-            label="PDG curve",
-            allow_custom_value=False,
-        )
-    noisy_scale = gr.Slider(
-        minimum=0.0,
-        maximum=10.0,
-        value=_DEFAULT_INFERENCE.pdg.noisy_scale,
-        step=0.05,
-        label="PDG scale / noisy endpoint",
-    )
-    clean_scale = gr.Slider(
-        minimum=0.0,
-        maximum=10.0,
-        value=_DEFAULT_INFERENCE.pdg.clean_scale,
-        step=0.05,
-        label="PDG clean endpoint",
-        info="Endpoint used by linear and power curves.",
-        interactive=_DEFAULT_INFERENCE.pdg.curve is not PdgCurve.CONSTANT,
-    )
-    power = gr.Slider(
-        minimum=0.05,
-        maximum=10.0,
-        value=_DEFAULT_INFERENCE.pdg.power,
-        step=0.05,
-        label="PDG power",
-    )
-    with gr.Row():
-        start = gr.Number(
-            value=_DEFAULT_INFERENCE.pdg.start_step,
-            label="PDG start",
-            precision=0,
-            minimum=0,
-        )
-        stop = gr.Textbox(
-            value="",
-            label="PDG stop",
-            info="Blank means the final solver update.",
-            placeholder="Final",
-            lines=1,
-        )
-    return enabled, mode, curve, noisy_scale, clean_scale, power, start, stop
-
-
-def _create_inputs(
-    basic: _BasicInputs,
-) -> _WebInputs:
-    """Create advanced controls around an existing basic control group."""
-
-    gr.Markdown("### Solver")
-    (
-        steps,
-        solver,
-        schedule,
-        log_snr_shift,
-        self_attention_gain,
-        euler_maruyama_multiplier,
-    ) = _solver_inputs()
-    gr.Markdown("### Path-drop guidance")
-    (
-        pdg_enabled,
-        pdg_mode,
-        pdg_curve,
-        pdg_noisy_scale,
-        pdg_clean_scale,
-        pdg_power,
-        pdg_start,
-        pdg_stop,
-    ) = _pdg_inputs()
-    gr.Markdown("### Classifier-free guidance")
-    cfg_enabled, cfg_scale, cfg_start, cfg_stop = _cfg_inputs()
-    return _WebInputs(
-        prompt=basic.prompt,
-        image_count=basic.image_count,
-        width=basic.width,
-        height=basic.height,
-        seed=basic.seed,
-        steps=steps,
-        solver=solver,
-        schedule=schedule,
-        log_snr_shift=log_snr_shift,
-        self_attention_gain=self_attention_gain,
-        euler_maruyama_multiplier=euler_maruyama_multiplier,
-        cfg_enabled=cfg_enabled,
-        cfg_scale=cfg_scale,
-        cfg_start_step=cfg_start,
-        cfg_stop_step=cfg_stop,
-        pdg_enabled=pdg_enabled,
-        pdg_mode=pdg_mode,
-        pdg_curve=pdg_curve,
-        pdg_noisy_scale=pdg_noisy_scale,
-        pdg_clean_scale=pdg_clean_scale,
-        pdg_power=pdg_power,
-        pdg_start_step=pdg_start,
-        pdg_stop_step=pdg_stop,
-    )
-
-
-def _connect_generation(
-    controller: CanterWebController,
-    inputs: _WebInputs,
-    generate: gr.Button,
-    stop: gr.Button,
-    outputs: _WebOutputs,
-) -> None:
-    """Connect button and prompt submission to the serial GPU queue."""
-
-    generate.click(
-        fn=controller.generate,
-        inputs=inputs.ordered(),
-        outputs=outputs.ordered(),
-        api_name="generate",
-        api_description="Generate images with the loaded Canter release.",
-        show_progress="hidden",
-        concurrency_limit=1,
-        concurrency_id=_GPU_CONCURRENCY_ID,
-    )
-    inputs.prompt.submit(
-        fn=controller.generate,
-        inputs=inputs.ordered(),
-        outputs=outputs.ordered(),
-        api_name=None,
-        show_progress="hidden",
-        concurrency_limit=1,
-        concurrency_id=_GPU_CONCURRENCY_ID,
-        api_visibility="private",
-    )
-    stop.click(
-        fn=controller.request_stop,
-        inputs=None,
-        outputs=outputs.status,
-        queue=False,
-        api_name=None,
-        api_visibility="private",
-    )
-
-
-def _create_web_app(
-    controller: CanterWebController,
-    *,
-    model_status_text: str,
-    ready: bool,
-    load_config: CanterWebLaunchConfig | None,
-) -> gr.Blocks:
-    """Build the UI for either an already-loaded or lazy process pipeline."""
-
-    with gr.Blocks(title="Canter", fill_width=True) as application:
-        gr.Markdown("# Canter", elem_id="canter-title")
-        model_status = gr.Markdown(model_status_text, elem_id="canter-model-status")
-        with gr.Row(elem_id="canter-workspace"):
-            with gr.Column(scale=3, min_width=360, elem_id="canter-controls"):
-                prompt = _prompt_input()
-                basic = _basic_inputs(prompt)
-                with gr.Row():
-                    generate = gr.Button(
-                        "Generate",
-                        variant="primary",
-                        scale=3,
-                        interactive=ready,
-                    )
-                    stop = gr.Button(
-                        "Stop",
-                        variant="stop",
-                        scale=1,
-                        interactive=ready,
-                    )
-                    randomize = gr.Button("Random seed", variant="secondary", scale=1)
-                inputs = _create_inputs(basic)
-            with gr.Column(scale=8, min_width=640, elem_id="canter-results"):
-                status = gr.Markdown(
-                    (
-                        "Ready. The first request includes compiled graph warm-up."
-                        if ready
-                        else "Loading Canter weights and compiling the selected "
-                        "backend…"
-                    ),
-                    elem_id="canter-status",
-                )
-                total_progress = gr.HTML(
-                    "",
-                    container=False,
-                    elem_classes="canter-total-progress",
-                )
-                progress_outputs: list[gr.HTML] = []
-                image_outputs: list[gr.Image] = []
-                with gr.Row(elem_id="canter-image-grid"):
-                    for index in range(_MAX_IMAGE_COUNT):
-                        with gr.Column(
-                            min_width=0,
-                            elem_classes="canter-image-cell",
-                        ):
-                            progress_outputs.append(
-                                gr.HTML(
-                                    "",
-                                    container=False,
-                                    elem_classes="canter-image-progress",
-                                )
-                            )
-                            image_outputs.append(
-                                gr.Image(
-                                    label=f"Image {index + 1}",
-                                    format="png",
-                                    height=None,
-                                    width=None,
-                                    type="pil",
-                                    show_label=False,
-                                    buttons=["download", "fullscreen"],
-                                    container=False,
-                                    interactive=False,
-                                    elem_classes="canter-output-image",
-                                )
-                            )
-                progress_timer = gr.Timer(value=0.2, active=False)
-                outputs = _WebOutputs(
-                    images=(
-                        image_outputs[0],
-                        image_outputs[1],
-                        image_outputs[2],
-                        image_outputs[3],
-                    ),
-                    status=status,
-                    progress_timer=progress_timer,
-                )
-                progress_timer.tick(
-                    fn=controller.poll_progress,
-                    inputs=None,
-                    outputs=(
-                        total_progress,
-                        progress_outputs[0],
-                        progress_outputs[1],
-                        progress_outputs[2],
-                        progress_outputs[3],
-                        progress_timer,
-                    ),
-                    queue=False,
-                    show_progress="hidden",
-                    api_name=None,
-                    api_visibility="private",
-                )
-        randomize.click(
-            fn=random_seed,
-            inputs=None,
-            outputs=inputs.seed,
-            queue=False,
-            api_name=None,
-            api_visibility="private",
-        )
-        basic.size_preset.change(
-            fn=apply_size_preset,
-            inputs=basic.size_preset,
-            outputs=(
-                basic.width,
-                basic.height,
-                inputs.self_attention_gain,
-            ),
-            queue=False,
-            api_name=None,
-            api_visibility="private",
-        )
-        inputs.schedule.change(
-            fn=schedule_log_snr_shift,
-            inputs=inputs.schedule,
-            outputs=inputs.log_snr_shift,
-            queue=False,
-            api_name=None,
-            api_visibility="private",
-        )
-        for dimension in (basic.width, basic.height):
-            dimension.blur(
-                fn=snap_image_dimension,
-                inputs=dimension,
-                outputs=dimension,
-                queue=False,
-                api_name=None,
-                api_visibility="private",
-            )
-        inputs.pdg_curve.change(
-            fn=update_pdg_clean_scale,
-            inputs=(inputs.pdg_curve, inputs.pdg_noisy_scale),
-            outputs=inputs.pdg_clean_scale,
-            queue=False,
-            api_name=None,
-            api_visibility="private",
-        )
-        _connect_generation(controller, inputs, generate, stop, outputs)
-        if load_config is not None:
-            application.load(
-                fn=controller.load,
-                inputs=None,
-                outputs=(model_status, status, generate, stop),
-                show_progress="minimal",
-                show_progress_on=status,
-                concurrency_limit=1,
-                concurrency_id=_GPU_CONCURRENCY_ID,
-                api_name=None,
-                api_visibility="private",
-            )
-    application.queue(
-        max_size=_MAX_QUEUE_SIZE,
-        default_concurrency_limit=1,
-        api_open=False,
-    )
-    return application
-
-
-def create_web_app(pipeline: _ImagePipeline) -> gr.Blocks:
-    """Build the bundled application around one already-loaded pipeline."""
-
-    return _create_web_app(
-        CanterWebController(pipeline),
-        model_status_text=_model_summary(pipeline.metadata),
-        ready=True,
-        load_config=None,
-    )
-
-
-def create_loading_web_app(config: CanterWebLaunchConfig) -> gr.Blocks:
-    """Build an immediately visible UI that loads its process pipeline once."""
-
-    return _create_web_app(
-        CanterWebController(None, load_config=config),
-        model_status_text=(
-            f"Loading Canter `{config.dtype.value}` weights and compiling the "
-            f"`{config.text_backend.value}` backend…"
-        ),
-        ready=False,
-        load_config=config,
-    )
-
-
-def _theme() -> gr.themes.Base:
-    """Return Canter's compact charcoal-and-sky-blue dark theme."""
-
-    return gr.themes.Base(
-        primary_hue="sky",
-        secondary_hue="blue",
-        neutral_hue="zinc",
-        spacing_size="sm",
-        radius_size="sm",
-        text_size="md",
-        font=[
-            gr.themes.Font("Inter"),
-            gr.themes.Font("Segoe UI"),
-            gr.themes.Font("sans-serif"),
-        ],
-        font_mono=[
-            gr.themes.Font("IBM Plex Mono"),
-            gr.themes.Font("Consolas"),
-            gr.themes.Font("monospace"),
-        ],
-    ).set(
-        body_background_fill_dark="#09090b",
-        block_background_fill_dark="#111113",
-        block_border_color_dark="#27272a",
-        input_background_fill_dark="#18181b",
-    )
-
 
 def _argument_parser() -> argparse.ArgumentParser:
     """Create the command-line surface with the installed-package model default."""
@@ -1881,19 +127,28 @@ def parse_launch_config(
     )
 
 
-def load_web_pipeline(config: CanterWebLaunchConfig) -> CanterPipeline:
-    """Load and compile exactly one selected Canter backend for the web process."""
+def _prepare_canter_temp_directory(
+    base_directory: Path,
+    server_port: int,
+) -> Path:
+    """Replace one marked Canter cache directory and select it for Gradio."""
 
-    return CanterPipeline.from_pretrained(
-        config.model,
-        dtype=config.dtype,
-        text_backend=config.text_backend,
-        device=config.device,
-        revision=config.revision,
-        cache_dir=config.cache_dir,
-        compile_model=True,
-        vae=None,
-    )
+    directory = base_directory.resolve() / f"{_TEMP_DIRECTORY_PREFIX}-{server_port}"
+    marker = directory / _TEMP_DIRECTORY_MARKER
+    if directory.exists():
+        if not directory.is_dir():
+            raise NotADirectoryError(
+                f"Canter temporary path is not a directory: {directory}"
+            )
+        if not marker.is_file():
+            raise RuntimeError(
+                f"Refusing to clear an unmarked temporary directory: {directory}"
+            )
+        shutil.rmtree(directory)
+    directory.mkdir()
+    marker.write_text("Owned by the Canter web UI.\n", encoding="utf-8")
+    os.environ["GRADIO_TEMP_DIR"] = str(directory)
+    return directory
 
 
 def launch_web_app(
@@ -1901,6 +156,12 @@ def launch_web_app(
 ) -> None:
     """Serve the UI immediately and load Canter from its browser load event."""
 
+    logging.basicConfig(format=_LOG_FORMAT)
+    logging.getLogger(__package__).setLevel(logging.INFO)
+    _prepare_canter_temp_directory(
+        Path(tempfile.gettempdir()),
+        config.server_port,
+    )
     application = create_loading_web_app(config)
     application.launch(
         server_name=config.server_name,

canter/webui_app.py

@@ -0,0 +1,1281 @@
+"""Gradio component tree and callbacks for the bundled Canter web UI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+import gradio as gr
+
+from .inference import CanterInferenceConfig, PdgCurve, PdgMode
+from .schedules import Schedule
+from .solvers import Solver
+from .webui_runtime import (
+    _IMAGE_SIZE_MULTIPLE,
+    _MAX_IMAGE_COUNT,
+    _MAX_SEED,
+    _SCHEDULES,
+    CanterWebController,
+    CanterWebLaunchConfig,
+    _choice,
+    _cleared_image_slots,
+    _GenerationOutputUpdate,
+    _image_dimension,
+    _ImagePipeline,
+    _integer,
+    _model_summary,
+    _number,
+    _unloaded_model_status,
+    random_seed,
+    snap_image_dimension,
+    update_pdg_clean_scale,
+)
+
+_MAX_QUEUE_SIZE = 8
+_DEFAULT_IMAGE_COUNT = 4
+_GPU_CONCURRENCY_ID = "canter-gpu"
+
+_DEFAULT_INFERENCE = CanterInferenceConfig()
+_SOLVER_CHOICES = (
+    ("ABM2", Solver.ABM2.value),
+    ("DPM++ 2M", Solver.DPMPP_2M.value),
+    ("Euler-Maruyama", Solver.EULER_MARUYAMA.value),
+    ("ER-SDE", Solver.ER_SDE.value),
+    ("Euler", Solver.EULER.value),
+)
+_SCHEDULE_CHOICES = (
+    ("Beta (0.6, 0.6)", Schedule.BETA.value),
+    ("Linear", Schedule.LINEAR.value),
+)
+_PDG_MODE_CHOICES = (
+    ("Full path drop", PdgMode.FULL.value),
+    ("Three-quarter path", PdgMode.THREE_QUARTER.value),
+    ("Alternate: PDG first", PdgMode.ALTERNATE_PDG_FIRST.value),
+    ("Alternate: CFG first", PdgMode.ALTERNATE_CFG_FIRST.value),
+    ("Combined CFG + PDG", PdgMode.COMBINED_CFG_PDG.value),
+    ("PDG with alternating CFG", PdgMode.PDG_WITH_ALTERNATING_CFG.value),
+    ("CFG then PDG", PdgMode.CFG_TO_PDG.value),
+)
+_PDG_CURVE_CHOICES = (
+    ("Constant", PdgCurve.CONSTANT.value),
+    ("Linear", PdgCurve.LINEAR.value),
+    ("Power", PdgCurve.POWER.value),
+)
+_DEFAULT_PROMPT = (
+    "Wide angle photo of a weathered wooden boardwalk descending steeply from "
+    "rocky cliffs toward a rugged coastline. The boardwalk, constructed from "
+    "aged planks with visible cracks and moss growth, is bordered by rustic "
+    "wooden railings on both sides. Surrounding terrain features uneven, eroded "
+    "rock formations covered in patches of green vegetation and low-lying "
+    "shrubs. Below, a crescent-shaped sandy beach meets crashing waves of a "
+    "deep blue ocean under a stormy, overcast sky with dark clouds and hints "
+    "of distant sunlight breaking through. The horizon shows turbulent waves "
+    "colliding with rocky outcrops, creating white foam."
+)
+
+
+class SizePreset(Enum):
+    """UI presets that jointly select image shape and attention gain."""
+
+    DEFAULT_PORTRAIT = "default_portrait"
+    WIDE = "wide"
+    TALL_PORTRAIT = "tall_portrait"
+
+
+@dataclass(frozen=True)
+class _SizePresetValues:
+    """Concrete image controls selected by one size preset."""
+
+    width: int
+    height: int
+    self_attention_gain: float
+
+
+_SIZE_PRESETS = {value.value: value for value in SizePreset}
+_SIZE_PRESET_CHOICES = (
+    ("832 × 1216 · gain −0.03", SizePreset.DEFAULT_PORTRAIT.value),
+    ("1536 × 832 · gain −0.02", SizePreset.WIDE.value),
+    ("1024 × 1536 · gain −0.02", SizePreset.TALL_PORTRAIT.value),
+)
+_SIZE_PRESET_VALUES = {
+    SizePreset.DEFAULT_PORTRAIT: _SizePresetValues(832, 1216, -0.03),
+    SizePreset.WIDE: _SizePresetValues(1536, 832, -0.02),
+    SizePreset.TALL_PORTRAIT: _SizePresetValues(1024, 1536, -0.02),
+}
+
+_DARK_HEAD = """
+<script>
+localStorage.setItem("theme", "dark");
+document.documentElement.classList.add("dark");
+document.documentElement.style.colorScheme = "dark";
+const resizeCanterImages = () => {
+    const grid = document.querySelector("#canter-image-grid");
+    if (grid === null) {
+        return;
+    }
+    const margin = 16;
+    const documentTop = grid.getBoundingClientRect().top + window.scrollY;
+    const available = documentTop < window.innerHeight
+        ? window.innerHeight - documentTop - margin
+        : window.innerHeight - 2 * margin;
+    grid.style.setProperty(
+        "--canter-image-max-height",
+        `${Math.max(available, 1)}px`
+    );
+};
+new MutationObserver(() => requestAnimationFrame(resizeCanterImages)).observe(
+    document.documentElement,
+    {childList: true, subtree: true}
+);
+window.addEventListener("resize", resizeCanterImages);
+requestAnimationFrame(resizeCanterImages);
+document.addEventListener("click", (event) => {
+    const target = event.target;
+    if (!(target instanceof Element)) {
+        return;
+    }
+    const image = target.closest(".canter-output-image img");
+    if (image === null) {
+        return;
+    }
+    const component = image.closest(".canter-output-image");
+    if (component === null) {
+        throw new Error("Canter image component is missing.");
+    }
+    const button = component.querySelector(
+        'button[aria-label="Fullscreen"], '
+        + 'button[aria-label="Exit fullscreen mode"]'
+    );
+    if (button === null) {
+        throw new Error("Canter image fullscreen control is missing.");
+    }
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    button.click();
+});
+</script>
+"""
+
+_CSS = """
+:root, body {
+    background: #09090b;
+}
+.gradio-container {
+    max-width: none !important;
+    width: 100% !important;
+    padding: 1rem !important;
+}
+#canter-title h1 {
+    font-size: 2.1rem;
+    letter-spacing: -0.04em;
+    line-height: 1.05;
+    margin: 0;
+}
+#canter-header {
+    flex-wrap: nowrap !important;
+    align-items: center !important;
+    gap: 0.5rem !important;
+}
+#canter-title {
+    flex: 1 1 0 !important;
+    min-width: 0 !important;
+    overflow: visible !important;
+}
+.canter-header-action {
+    flex: 0 0 auto !important;
+    width: auto !important;
+    overflow: visible !important;
+}
+#canter-api-button {
+    margin-top: 0.75rem;
+}
+footer .show-api {
+    display: none !important;
+}
+#canter-workspace {
+    align-items: flex-start !important;
+}
+#canter-controls {
+    max-width: 440px;
+    min-width: 360px;
+}
+#canter-results {
+    min-width: 0;
+}
+#canter-image-grid {
+    display: grid !important;
+    grid-template-columns: repeat(
+        auto-fit,
+        minmax(min(100%, var(--canter-image-min-width, 640px)), 1fr)
+    );
+    align-items: start !important;
+    gap: 1rem !important;
+    height: auto !important;
+    max-height: none !important;
+    overflow: visible !important;
+}
+#canter-image-grid > div {
+    min-width: 0 !important;
+}
+.canter-image-cell {
+    position: relative;
+}
+.canter-total-progress {
+    margin-bottom: 0.75rem;
+}
+.canter-total-progress:not(:has(.canter-progress-panel)) {
+    display: none !important;
+}
+.canter-image-progress {
+    position: absolute !important;
+    top: 0.75rem;
+    left: 0.75rem;
+    right: 0.75rem;
+    z-index: 10;
+    pointer-events: none;
+}
+.canter-image-progress:not(:has(.canter-progress-panel)) {
+    display: none !important;
+}
+.canter-progress-panel {
+    padding: 0.65rem 0.75rem;
+    color: #f4f4f5;
+    background: rgb(9 9 11 / 88%);
+    border: 1px solid #3f3f46;
+    border-radius: 0.35rem;
+    box-shadow: 0 0.25rem 1rem rgb(0 0 0 / 35%);
+    backdrop-filter: blur(0.35rem);
+}
+.canter-progress-label {
+    margin-bottom: 0.4rem;
+    font-size: 0.85rem;
+    font-weight: 600;
+}
+.canter-progress-row {
+    display: grid;
+    grid-template-columns: 2.5rem minmax(0, 1fr) 2.5rem;
+    align-items: center;
+    gap: 0.45rem;
+    font-size: 0.72rem;
+    color: #d4d4d8;
+}
+.canter-progress-track {
+    height: 0.35rem;
+    overflow: hidden;
+    background: #27272a;
+    border-radius: 999px;
+}
+.canter-progress-track > div {
+    height: 100%;
+    background: var(--primary-500);
+    border-radius: inherit;
+    transition: width 120ms linear;
+}
+.canter-output-image,
+.canter-output-image > div {
+    height: auto !important;
+    max-height: none !important;
+    overflow: visible !important;
+}
+.canter-output-image img {
+    display: block !important;
+    width: 100% !important;
+    max-width: 100% !important;
+    height: auto !important;
+    max-height: none !important;
+    object-fit: contain !important;
+    margin: 0 auto !important;
+    cursor: zoom-in;
+}
+.canter-output-image:not(
+    :has(button[aria-label="Exit fullscreen mode"])
+) img {
+    max-height: var(
+        --canter-image-max-height,
+        calc(100dvh - 2rem)
+    ) !important;
+}
+.canter-output-image:not(
+    :has(button[aria-label="Exit fullscreen mode"])
+) > div > button > div {
+    width: min(
+        100%,
+        var(--canter-image-min-width, 640px)
+    ) !important;
+}
+.canter-output-image:has(button[aria-label="Exit fullscreen mode"]) img {
+    cursor: zoom-out;
+}
+.canter-output-image:has(button[aria-label="Exit fullscreen mode"]) {
+    box-sizing: border-box !important;
+    height: 100dvh !important;
+    max-height: 100dvh !important;
+    overflow: auto !important;
+    padding: 8px !important;
+}
+#canter-status {
+    color: #a1a1aa;
+}
+@media (max-width: 900px) {
+    #canter-controls {
+        max-width: none;
+        min-width: 0;
+    }
+}
+"""
+
+
+@dataclass(frozen=True)
+class _BasicInputs:
+    """Prompt and basic generation controls rendered above advanced settings."""
+
+    prompt: gr.Textbox
+    image_count: gr.Number
+    size_preset: gr.Dropdown
+    preview_enabled: gr.Checkbox
+    width: gr.Number
+    height: gr.Number
+    seed: gr.Number
+
+
+@dataclass(frozen=True)
+class _WebInputs:
+    """Gradio components in the exact callback argument order."""
+
+    prompt: gr.Textbox
+    image_count: gr.Number
+    size_preset: gr.Dropdown
+    preview_enabled: gr.Checkbox
+    width: gr.Number
+    height: gr.Number
+    seed: gr.Number
+    steps: gr.Slider
+    solver: gr.Dropdown
+    schedule: gr.Dropdown
+    log_snr_shift: gr.Slider
+    self_attention_gain: gr.Slider
+    euler_maruyama_multiplier: gr.Slider
+    cfg_enabled: gr.Checkbox
+    cfg_scale: gr.Slider
+    cfg_start_step: gr.Number
+    cfg_stop_step: gr.Textbox
+    pdg_enabled: gr.Checkbox
+    pdg_mode: gr.Dropdown
+    pdg_curve: gr.Dropdown
+    pdg_noisy_scale: gr.Slider
+    pdg_clean_scale: gr.Slider
+    pdg_power: gr.Slider
+    pdg_start_step: gr.Number
+    pdg_stop_step: gr.Textbox
+
+    def ordered(self) -> tuple[gr.Component, ...]:
+        """Return components in the order accepted by ``generate``."""
+
+        return (
+            self.prompt,
+            self.image_count,
+            self.width,
+            self.height,
+            self.seed,
+            self.steps,
+            self.solver,
+            self.schedule,
+            self.log_snr_shift,
+            self.self_attention_gain,
+            self.euler_maruyama_multiplier,
+            self.cfg_enabled,
+            self.cfg_scale,
+            self.cfg_start_step,
+            self.cfg_stop_step,
+            self.pdg_enabled,
+            self.pdg_mode,
+            self.pdg_curve,
+            self.pdg_noisy_scale,
+            self.pdg_clean_scale,
+            self.pdg_power,
+            self.pdg_start_step,
+            self.pdg_stop_step,
+            self.preview_enabled,
+        )
+
+
+@dataclass(frozen=True)
+class _WebOutputs:
+    """Image slots and status components in callback output order."""
+
+    image_containers: tuple[gr.Column, ...]
+    images: tuple[gr.Image, ...]
+    grid_style: gr.HTML
+    model_status: gr.Markdown
+    status: gr.Markdown
+    progress_timer: gr.Timer
+
+    def ordered(self) -> tuple[gr.Component, ...]:
+        """Return images, status, and progress-lifecycle callback outputs."""
+
+        return (*self.images, self.status, self.progress_timer)
+
+
+@dataclass(frozen=True)
+class _GenerationControls:
+    """Buttons controlling generation, cancellation, randomization, and API help."""
+
+    generate: gr.Button
+    stop: gr.Button
+    randomize: gr.Button
+    api: gr.Button
+
+
+def _prompt_input() -> gr.Textbox:
+    """Create the prompt control without rendering it yet."""
+
+    return gr.Textbox(
+        label="Prompt",
+        value=_DEFAULT_PROMPT,
+        lines=3,
+        placeholder="Describe the image you want to generate.",
+        render=False,
+    )
+
+
+def _basic_inputs(prompt: gr.Textbox) -> _BasicInputs:
+    """Render prompt, image-count, preset, shape, and seed controls."""
+
+    prompt.render()
+    image_count = gr.Number(
+        minimum=1,
+        maximum=_MAX_IMAGE_COUNT,
+        value=_DEFAULT_IMAGE_COUNT,
+        step=1,
+        precision=0,
+        label="Images",
+        info="Generated sequentially with batch size 1.",
+    )
+    size_preset = gr.Dropdown(
+        choices=_SIZE_PRESET_CHOICES,
+        value=SizePreset.DEFAULT_PORTRAIT.value,
+        label="Size preset",
+        allow_custom_value=False,
+    )
+    preview_enabled = gr.Checkbox(
+        value=True,
+        label="Preview generation",
+    )
+    with gr.Row():
+        width = gr.Number(
+            value=_DEFAULT_INFERENCE.width,
+            label="Width",
+            precision=0,
+            minimum=_IMAGE_SIZE_MULTIPLE,
+            step=_IMAGE_SIZE_MULTIPLE,
+        )
+        height = gr.Number(
+            value=_DEFAULT_INFERENCE.height,
+            label="Height",
+            precision=0,
+            minimum=_IMAGE_SIZE_MULTIPLE,
+            step=_IMAGE_SIZE_MULTIPLE,
+        )
+    seed = gr.Number(
+        value=_DEFAULT_INFERENCE.seed,
+        label="Seed",
+        precision=0,
+        minimum=0,
+        maximum=_MAX_SEED,
+    )
+    return _BasicInputs(
+        prompt=prompt,
+        image_count=image_count,
+        size_preset=size_preset,
+        preview_enabled=preview_enabled,
+        width=width,
+        height=height,
+        seed=seed,
+    )
+
+
+def image_grid_visibility(
+    image_count: int | float,
+) -> tuple[dict[str, object], ...]:
+    """Show exactly the requested number of fixed image-grid containers."""
+
+    resolved_count = _integer(
+        image_count,
+        "image count",
+        minimum=1,
+        maximum=_MAX_IMAGE_COUNT,
+    )
+    return tuple(
+        gr.update(visible=index < resolved_count) for index in range(_MAX_IMAGE_COUNT)
+    )
+
+
+def image_grid_style(width: int | float, height: int | float) -> str:
+    """Return responsive grid CSS using the requested image width."""
+
+    resolved_width = _image_dimension(width, "width")
+    _image_dimension(height, "height")
+    return (
+        "<style>"
+        "#canter-image-grid {"
+        f"--canter-image-min-width: {resolved_width}px;"
+        "}"
+        "</style>"
+    )
+
+
+def prepare_image_grid(
+    image_count: int | float,
+    width: int | float,
+    height: int | float,
+) -> tuple[dict[str, object] | str, ...]:
+    """Configure slot visibility and aspect-aware sizing before generation."""
+
+    return (
+        *image_grid_visibility(image_count),
+        image_grid_style(width, height),
+    )
+
+
+def apply_size_preset(value: str | None) -> tuple[int, int, float]:
+    """Return width, height, and attention gain for one exact UI preset."""
+
+    preset = _choice(value, _SIZE_PRESETS, "size preset")
+    selected = _SIZE_PRESET_VALUES[preset]
+    return selected.width, selected.height, selected.self_attention_gain
+
+
+def schedule_log_snr_shift(value: str | None) -> float:
+    """Return the UI log-SNR preset associated with one schedule."""
+
+    schedule = _choice(value, _SCHEDULES, "schedule")
+    match schedule:
+        case Schedule.BETA:
+            return 0.0
+        case Schedule.LINEAR:
+            return -2.3
+        case _ as unreachable:
+            raise RuntimeError(f"Unsupported Canter schedule: {unreachable}")
+
+
+def _solver_inputs() -> tuple[
+    gr.Slider,
+    gr.Dropdown,
+    gr.Dropdown,
+    gr.Slider,
+    gr.Slider,
+    gr.Slider,
+]:
+    """Create solver, schedule, and model-gain controls."""
+
+    steps = gr.Slider(
+        minimum=1,
+        maximum=100,
+        value=_DEFAULT_INFERENCE.steps,
+        step=1,
+        precision=0,
+        label="Solver updates",
+    )
+    with gr.Row():
+        solver = gr.Dropdown(
+            choices=_SOLVER_CHOICES,
+            value=_DEFAULT_INFERENCE.solver.value,
+            label="Solver",
+            allow_custom_value=False,
+        )
+        schedule = gr.Dropdown(
+            choices=_SCHEDULE_CHOICES,
+            value=_DEFAULT_INFERENCE.schedule.value,
+            label="Schedule",
+            allow_custom_value=False,
+        )
+    log_snr_shift = gr.Slider(
+        minimum=-4.0,
+        maximum=4.0,
+        value=_DEFAULT_INFERENCE.log_snr_shift,
+        step=0.05,
+        label="Log-SNR shift",
+    )
+    self_attention_gain = gr.Slider(
+        minimum=-0.05,
+        maximum=0.02,
+        value=_DEFAULT_INFERENCE.self_attention_gain,
+        step=0.005,
+        label="Main self-attention gain",
+    )
+    euler_maruyama_multiplier = gr.Slider(
+        minimum=0.0,
+        maximum=2.0,
+        value=_DEFAULT_INFERENCE.euler_maruyama_multiplier,
+        step=0.05,
+        label="SDE noise multiplier",
+    )
+    return (
+        steps,
+        solver,
+        schedule,
+        log_snr_shift,
+        self_attention_gain,
+        euler_maruyama_multiplier,
+    )
+
+
+def _cfg_inputs() -> tuple[
+    gr.Checkbox,
+    gr.Slider,
+    gr.Number,
+    gr.Textbox,
+]:
+    """Create classifier-free guidance controls."""
+
+    enabled = gr.Checkbox(
+        value=_DEFAULT_INFERENCE.cfg.enabled,
+        label="Enable CFG",
+    )
+    scale = gr.Slider(
+        minimum=0.0,
+        maximum=10.0,
+        value=3.0,
+        step=0.05,
+        label="CFG scale",
+        info="Also used by CFG-dependent PDG modes.",
+    )
+    with gr.Row():
+        start = gr.Number(
+            value=_DEFAULT_INFERENCE.cfg.start_step,
+            label="CFG start",
+            precision=0,
+            minimum=0,
+        )
+        stop = gr.Textbox(
+            value="",
+            label="CFG stop",
+            info="Blank means the final solver update.",
+            placeholder="Final",
+            lines=1,
+        )
+    return enabled, scale, start, stop
+
+
+def _pdg_inputs() -> tuple[
+    gr.Checkbox,
+    gr.Dropdown,
+    gr.Dropdown,
+    gr.Slider,
+    gr.Slider,
+    gr.Slider,
+    gr.Number,
+    gr.Textbox,
+]:
+    """Create path-drop guidance and curve controls."""
+
+    enabled = gr.Checkbox(
+        value=_DEFAULT_INFERENCE.pdg.enabled,
+        label="Enable PDG",
+    )
+    with gr.Row():
+        mode = gr.Dropdown(
+            choices=_PDG_MODE_CHOICES,
+            value=_DEFAULT_INFERENCE.pdg.mode.value,
+            label="PDG mode",
+            allow_custom_value=False,
+        )
+        curve = gr.Dropdown(
+            choices=_PDG_CURVE_CHOICES,
+            value=_DEFAULT_INFERENCE.pdg.curve.value,
+            label="PDG curve",
+            allow_custom_value=False,
+        )
+    noisy_scale = gr.Slider(
+        minimum=0.0,
+        maximum=10.0,
+        value=_DEFAULT_INFERENCE.pdg.noisy_scale,
+        step=0.05,
+        label="PDG scale / noisy endpoint",
+    )
+    clean_scale = gr.Slider(
+        minimum=0.0,
+        maximum=10.0,
+        value=_DEFAULT_INFERENCE.pdg.clean_scale,
+        step=0.05,
+        label="PDG clean endpoint",
+        info="Endpoint used by linear and power curves.",
+        interactive=_DEFAULT_INFERENCE.pdg.curve is not PdgCurve.CONSTANT,
+    )
+    power = gr.Slider(
+        minimum=0.05,
+        maximum=10.0,
+        value=_DEFAULT_INFERENCE.pdg.power,
+        step=0.05,
+        label="PDG power",
+    )
+    with gr.Row():
+        start = gr.Number(
+            value=_DEFAULT_INFERENCE.pdg.start_step,
+            label="PDG start",
+            precision=0,
+            minimum=0,
+        )
+        stop = gr.Textbox(
+            value="",
+            label="PDG stop",
+            info="Blank means the final solver update.",
+            placeholder="Final",
+            lines=1,
+        )
+    return enabled, mode, curve, noisy_scale, clean_scale, power, start, stop
+
+
+def _create_inputs(
+    basic: _BasicInputs,
+) -> _WebInputs:
+    """Create advanced controls around an existing basic control group."""
+
+    gr.Markdown("### Solver")
+    (
+        steps,
+        solver,
+        schedule,
+        log_snr_shift,
+        self_attention_gain,
+        euler_maruyama_multiplier,
+    ) = _solver_inputs()
+    gr.Markdown("### Path-drop guidance")
+    (
+        pdg_enabled,
+        pdg_mode,
+        pdg_curve,
+        pdg_noisy_scale,
+        pdg_clean_scale,
+        pdg_power,
+        pdg_start,
+        pdg_stop,
+    ) = _pdg_inputs()
+    gr.Markdown("### Classifier-free guidance")
+    cfg_enabled, cfg_scale, cfg_start, cfg_stop = _cfg_inputs()
+    return _WebInputs(
+        prompt=basic.prompt,
+        image_count=basic.image_count,
+        size_preset=basic.size_preset,
+        preview_enabled=basic.preview_enabled,
+        width=basic.width,
+        height=basic.height,
+        seed=basic.seed,
+        steps=steps,
+        solver=solver,
+        schedule=schedule,
+        log_snr_shift=log_snr_shift,
+        self_attention_gain=self_attention_gain,
+        euler_maruyama_multiplier=euler_maruyama_multiplier,
+        cfg_enabled=cfg_enabled,
+        cfg_scale=cfg_scale,
+        cfg_start_step=cfg_start,
+        cfg_stop_step=cfg_stop,
+        pdg_enabled=pdg_enabled,
+        pdg_mode=pdg_mode,
+        pdg_curve=pdg_curve,
+        pdg_noisy_scale=pdg_noisy_scale,
+        pdg_clean_scale=pdg_clean_scale,
+        pdg_power=pdg_power,
+        pdg_start_step=pdg_start,
+        pdg_stop_step=pdg_stop,
+    )
+
+
+def _connect_backend_unload(
+    controller: CanterWebController,
+    unload: gr.Button,
+    outputs: _WebOutputs,
+) -> None:
+    """Connect one-click global cancellation and backend cleanup."""
+
+    def begin_unload() -> tuple[_GenerationOutputUpdate, ...]:
+        """Stop active work and clear browser image slots immediately."""
+
+        status = controller.request_backend_unload()
+        return (
+            *_cleared_image_slots(),
+            status,
+            gr.update(interactive=False),
+        )
+
+    def finish_unload() -> tuple[str, str, dict[str, object]]:
+        """Release model resources while retaining generated temporary files."""
+
+        status = controller.unload_backend()
+        return (
+            status,
+            controller.model_status(),
+            gr.update(value="Unload model", interactive=True),
+        )
+
+    def unload_failed() -> tuple[str, dict[str, object]]:
+        """Keep generation blocked while allowing explicit cleanup retry."""
+
+        return (
+            "Unload failed. Retry cleanup or restart the server; generation "
+            "remains blocked.",
+            gr.update(value="Retry unload", interactive=True),
+        )
+
+    begin_event = unload.click(
+        fn=begin_unload,
+        inputs=None,
+        outputs=(
+            *outputs.images,
+            outputs.status,
+            unload,
+        ),
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    finish_event = begin_event.then(
+        fn=finish_unload,
+        inputs=None,
+        outputs=(
+            outputs.status,
+            outputs.model_status,
+            unload,
+        ),
+        concurrency_limit=1,
+        concurrency_id=_GPU_CONCURRENCY_ID,
+        api_name=None,
+        api_visibility="private",
+    )
+    finish_event.failure(
+        fn=unload_failed,
+        inputs=None,
+        outputs=(outputs.status, unload),
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+
+
+def _connect_generation(
+    controller: CanterWebController,
+    inputs: _WebInputs,
+    generate: gr.Button,
+    stop: gr.Button,
+    outputs: _WebOutputs,
+) -> None:
+    """Connect button and prompt submission to the serial GPU queue."""
+
+    generate_event = generate.click(
+        fn=prepare_image_grid,
+        inputs=(inputs.image_count, inputs.width, inputs.height),
+        outputs=(*outputs.image_containers, outputs.grid_style),
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    generation = generate_event.then(
+        fn=controller.generate,
+        inputs=inputs.ordered(),
+        outputs=outputs.ordered(),
+        api_name="generate",
+        api_description="Generate images with the loaded Canter release.",
+        show_progress="hidden",
+        concurrency_limit=1,
+        concurrency_id=_GPU_CONCURRENCY_ID,
+    )
+    generation.then(
+        fn=controller.model_status,
+        inputs=None,
+        outputs=outputs.model_status,
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    prompt_event = inputs.prompt.submit(
+        fn=prepare_image_grid,
+        inputs=(inputs.image_count, inputs.width, inputs.height),
+        outputs=(*outputs.image_containers, outputs.grid_style),
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    prompt_generation = prompt_event.then(
+        fn=controller.generate,
+        inputs=inputs.ordered(),
+        outputs=outputs.ordered(),
+        api_name=None,
+        show_progress="hidden",
+        concurrency_limit=1,
+        concurrency_id=_GPU_CONCURRENCY_ID,
+        api_visibility="private",
+    )
+    prompt_generation.then(
+        fn=controller.model_status,
+        inputs=None,
+        outputs=outputs.model_status,
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    stop.click(
+        fn=controller.request_stop,
+        inputs=None,
+        outputs=outputs.status,
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+
+
+def _create_header(
+    *,
+    model_status_text: str,
+    unload_supported: bool,
+    ready: bool,
+) -> tuple[gr.Button, gr.Markdown]:
+    """Create the title, one-click unload control, and model status."""
+
+    with gr.Row(elem_id="canter-header"):
+        gr.Markdown(
+            "# Canter",
+            elem_id="canter-title",
+            scale=1,
+            min_width=200,
+        )
+        unload = gr.Button(
+            "Unload model",
+            variant="secondary",
+            size="sm",
+            scale=0,
+            min_width=104,
+            visible=unload_supported,
+            interactive=ready,
+            elem_classes="canter-header-action",
+        )
+    model_status = gr.Markdown(model_status_text, elem_id="canter-model-status")
+    return unload, model_status
+
+
+def _create_result_outputs(
+    controller: CanterWebController,
+    model_status: gr.Markdown,
+    *,
+    ready: bool,
+) -> _WebOutputs:
+    """Create responsive image slots and their per-session progress polling."""
+
+    status = gr.Markdown(
+        (
+            "Ready. The first request includes compiled graph warm-up."
+            if ready
+            else "Loading Canter weights and compiling the selected backend…"
+        ),
+        elem_id="canter-status",
+    )
+    total_progress = gr.HTML(
+        "",
+        container=False,
+        elem_classes="canter-total-progress",
+    )
+    grid_style = gr.HTML(
+        image_grid_style(
+            _DEFAULT_INFERENCE.width,
+            _DEFAULT_INFERENCE.height,
+        ),
+        container=False,
+    )
+    progress_outputs: list[gr.HTML] = []
+    image_outputs: list[gr.Image] = []
+    image_containers: list[gr.Column] = []
+    with gr.Row(elem_id="canter-image-grid"):
+        for index in range(_MAX_IMAGE_COUNT):
+            with gr.Column(
+                min_width=0,
+                visible=index < _DEFAULT_IMAGE_COUNT,
+                elem_classes="canter-image-cell",
+            ) as image_container:
+                image_containers.append(image_container)
+                progress_outputs.append(
+                    gr.HTML(
+                        "",
+                        container=False,
+                        elem_classes="canter-image-progress",
+                    )
+                )
+                image_outputs.append(
+                    gr.Image(
+                        label=f"Image {index + 1}",
+                        format="png",
+                        height=None,
+                        width=None,
+                        type="pil",
+                        show_label=False,
+                        buttons=["download", "fullscreen"],
+                        container=False,
+                        interactive=False,
+                        elem_classes="canter-output-image",
+                    )
+                )
+    progress_timer = gr.Timer(value=0.2, active=False)
+    outputs = _WebOutputs(
+        image_containers=tuple(image_containers),
+        images=tuple(image_outputs),
+        grid_style=grid_style,
+        model_status=model_status,
+        status=status,
+        progress_timer=progress_timer,
+    )
+    progress_timer.tick(
+        fn=controller.poll_progress,
+        inputs=None,
+        outputs=(
+            *image_outputs,
+            total_progress,
+            *progress_outputs,
+            progress_timer,
+        ),
+        queue=False,
+        show_progress="hidden",
+        api_name=None,
+        api_visibility="private",
+    )
+    return outputs
+
+
+def _create_workspace(
+    controller: CanterWebController,
+    model_status: gr.Markdown,
+    *,
+    ready: bool,
+) -> tuple[_WebInputs, _GenerationControls, _WebOutputs]:
+    """Create the controls column and responsive results column."""
+
+    with gr.Row(elem_id="canter-workspace"):
+        with gr.Column(scale=3, min_width=360, elem_id="canter-controls"):
+            prompt = _prompt_input()
+            basic = _basic_inputs(prompt)
+            with gr.Row():
+                generate = gr.Button(
+                    "Generate",
+                    variant="primary",
+                    scale=3,
+                    interactive=ready,
+                )
+                stop = gr.Button(
+                    "Stop",
+                    variant="stop",
+                    scale=1,
+                    interactive=ready,
+                )
+                randomize = gr.Button("Random seed", variant="secondary", scale=1)
+            inputs = _create_inputs(basic)
+            api = gr.Button(
+                "Use via API",
+                variant="secondary",
+                elem_id="canter-api-button",
+            )
+        with gr.Column(scale=8, min_width=640, elem_id="canter-results"):
+            outputs = _create_result_outputs(
+                controller,
+                model_status,
+                ready=ready,
+            )
+    controls = _GenerationControls(
+        generate=generate,
+        stop=stop,
+        randomize=randomize,
+        api=api,
+    )
+    return inputs, controls, outputs
+
+
+def _connect_control_callbacks(
+    inputs: _WebInputs,
+    controls: _GenerationControls,
+    outputs: _WebOutputs,
+) -> None:
+    """Connect form-only callbacks that do not invoke the model."""
+
+    controls.randomize.click(
+        fn=random_seed,
+        inputs=None,
+        outputs=inputs.seed,
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    size_preset_event = inputs.size_preset.change(
+        fn=apply_size_preset,
+        inputs=inputs.size_preset,
+        outputs=(
+            inputs.width,
+            inputs.height,
+            inputs.self_attention_gain,
+        ),
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    size_preset_event.then(
+        fn=image_grid_style,
+        inputs=(inputs.width, inputs.height),
+        outputs=outputs.grid_style,
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    inputs.schedule.change(
+        fn=schedule_log_snr_shift,
+        inputs=inputs.schedule,
+        outputs=inputs.log_snr_shift,
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    for dimension in (inputs.width, inputs.height):
+        dimension_event = dimension.blur(
+            fn=snap_image_dimension,
+            inputs=dimension,
+            outputs=dimension,
+            queue=False,
+            api_name=None,
+            api_visibility="private",
+        )
+        dimension_event.then(
+            fn=image_grid_style,
+            inputs=(inputs.width, inputs.height),
+            outputs=outputs.grid_style,
+            queue=False,
+            api_name=None,
+            api_visibility="private",
+        )
+    inputs.pdg_curve.change(
+        fn=update_pdg_clean_scale,
+        inputs=(inputs.pdg_curve, inputs.pdg_noisy_scale),
+        outputs=inputs.pdg_clean_scale,
+        queue=False,
+        api_name=None,
+        api_visibility="private",
+    )
+    controls.api.click(
+        fn=None,
+        inputs=None,
+        outputs=None,
+        queue=False,
+        js=(
+            "() => {"
+            "const button = document.querySelector('footer button.show-api');"
+            "if (button === null) {"
+            "throw new Error('Gradio API footer control is missing.');"
+            "}"
+            "button.click();"
+            "}"
+        ),
+        api_name=None,
+        api_visibility="private",
+    )
+
+
+def _create_web_app(
+    controller: CanterWebController,
+    *,
+    model_status_text: str,
+    ready: bool,
+    load_config: CanterWebLaunchConfig | None,
+) -> gr.Blocks:
+    """Build the UI for either an already-loaded or lazy process pipeline."""
+
+    with gr.Blocks(title="Canter", fill_width=True) as application:
+        unload, model_status = _create_header(
+            model_status_text=model_status_text,
+            unload_supported=load_config is not None,
+            ready=ready,
+        )
+        inputs, controls, outputs = _create_workspace(
+            controller,
+            model_status,
+            ready=ready,
+        )
+        _connect_control_callbacks(inputs, controls, outputs)
+        _connect_generation(
+            controller,
+            inputs,
+            controls.generate,
+            controls.stop,
+            outputs,
+        )
+        if load_config is not None:
+            _connect_backend_unload(controller, unload, outputs)
+            application.load(
+                fn=controller.load,
+                inputs=None,
+                outputs=(
+                    model_status,
+                    outputs.status,
+                    controls.generate,
+                    controls.stop,
+                    unload,
+                ),
+                show_progress="minimal",
+                show_progress_on=outputs.status,
+                concurrency_limit=1,
+                concurrency_id=_GPU_CONCURRENCY_ID,
+                api_name=None,
+                api_visibility="private",
+            )
+    application.queue(
+        max_size=_MAX_QUEUE_SIZE,
+        default_concurrency_limit=1,
+        api_open=False,
+    )
+    return application
+
+
+def create_web_app(pipeline: _ImagePipeline) -> gr.Blocks:
+    """Build the bundled application around one already-loaded pipeline."""
+
+    return _create_web_app(
+        CanterWebController(pipeline),
+        model_status_text=_model_summary(pipeline.metadata),
+        ready=True,
+        load_config=None,
+    )
+
+
+def create_loading_web_app(config: CanterWebLaunchConfig) -> gr.Blocks:
+    """Build an immediately visible UI that loads its process pipeline once."""
+
+    return _create_web_app(
+        CanterWebController(None, load_config=config),
+        model_status_text=(
+            f"Loading Canter `{config.dtype.value}` weights and compiling the "
+            f"`{config.text_backend.value}` backend…"
+        ),
+        ready=False,
+        load_config=config,
+    )
+
+
+def _theme() -> gr.themes.Base:
+    """Return Canter's compact charcoal-and-sky-blue dark theme."""
+
+    return gr.themes.Base(
+        primary_hue="sky",
+        secondary_hue="blue",
+        neutral_hue="zinc",
+        spacing_size="sm",
+        radius_size="sm",
+        text_size="md",
+        font=[
+            gr.themes.Font("Inter"),
+            gr.themes.Font("Segoe UI"),
+            gr.themes.Font("sans-serif"),
+        ],
+        font_mono=[
+            gr.themes.Font("IBM Plex Mono"),
+            gr.themes.Font("Consolas"),
+            gr.themes.Font("monospace"),
+        ],
+    ).set(
+        body_background_fill_dark="#09090b",
+        block_background_fill_dark="#111113",
+        block_border_color_dark="#27272a",
+        input_background_fill_dark="#18181b",
+    )

canter/webui_runtime.py

@@ -0,0 +1,1171 @@
+"""Generation runtime and model lifecycle for the bundled Canter web UI."""
+
+from __future__ import annotations
+
+import gc
+import json
+import logging
+import math
+import secrets
+import threading
+import time
+from collections.abc import Callable, Generator, Mapping, Sequence
+from dataclasses import dataclass, replace
+from hashlib import sha256
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, TypeAlias, TypeVar
+
+import gradio as gr
+import torch
+from PIL import Image
+
+from .inference import (
+    CanterInferenceConfig,
+    CfgGuidance,
+    PdgCurve,
+    PdgGuidance,
+    PdgMode,
+)
+from .pipeline import (
+    CanterOutputType,
+    CanterPipeline,
+    CanterPipelineConfig,
+    CanterPipelineMetadata,
+    CanterPipelineOutput,
+)
+from .schedules import Schedule
+from .solvers import Solver, SolverProgress
+
+if TYPE_CHECKING:
+    from .blocks import TextAttentionBackend
+    from .loading import WeightDType
+    from .preview import CanterPreviewCallback
+
+_MAX_IMAGE_COUNT = 50
+_MAX_SEED = 2**63 - 1
+_IMAGE_SIZE_MULTIPLE = 32
+_PNG_METADATA_KEY = "canter"
+_LOGGER = logging.getLogger(__name__)
+
+_SOLVERS = {value.value: value for value in Solver}
+_SCHEDULES = {value.value: value for value in Schedule}
+_PDG_MODES = {value.value: value for value in PdgMode if value is not PdgMode.NONE}
+_PDG_CURVES = {value.value: value for value in PdgCurve}
+
+_Choice = TypeVar("_Choice")
+
+
+class _ImagePipeline(Protocol):
+    """Typed Canter surface used by the web controller and its tests."""
+
+    metadata: CanterPipelineMetadata
+
+    def __call__(
+        self,
+        prompts: str | Sequence[str],
+        *,
+        config: CanterPipelineConfig,
+        initial_noise: None,
+        progress: SolverProgress | None,
+        preview: CanterPreviewCallback | None,
+    ) -> CanterPipelineOutput:
+        """Generate decoded images for one web request."""
+
+        ...
+
+    def close(self) -> None:
+        """Finish background work before backend unload."""
+
+        ...
+
+
+@dataclass(frozen=True)
+class CanterWebRequest:
+    """Validated sequential image request and frozen base configuration."""
+
+    prompt: str
+    image_count: int
+    config: CanterPipelineConfig
+
+
+@dataclass(frozen=True)
+class CanterWebLaunchConfig:
+    """Process-level model and server configuration for the bundled application."""
+
+    model: str
+    revision: str | None
+    dtype: WeightDType
+    text_backend: TextAttentionBackend
+    device: str
+    cache_dir: Path | None
+    server_name: str
+    server_port: int
+    share: bool
+    in_browser: bool
+
+
+_ImageSlotUpdate: TypeAlias = Image.Image | dict[str, str] | None
+_GenerationOutputUpdate: TypeAlias = _ImageSlotUpdate | str | dict[str, object]
+_GenerationUpdate: TypeAlias = tuple[_GenerationOutputUpdate, ...]
+
+
+class _GenerationStoppedError(RuntimeError):
+    """Cooperative-cancellation signal for one web generation."""
+
+
+@dataclass(frozen=True)
+class _WebProgressState:
+    """Current solver position for one browser generation request."""
+
+    image_index: int
+    image_count: int
+    completed_updates: int
+    total_updates: int
+
+
+@dataclass(frozen=True)
+class _WebPreview:
+    """Newest unconsumed preview for one output image slot."""
+
+    image_index: int
+    image: Image.Image
+
+
+@dataclass(frozen=True)
+class _WebGenerationState:
+    """Cancellation and progress state owned by one browser generation."""
+
+    stop_requested: threading.Event
+    progress: _WebProgressState
+    preview_image_index: int | None
+    pending_preview: _WebPreview | None
+
+
+class CanterWebController:
+    """Translate Gradio values into one deterministic pipeline invocation."""
+
+    def __init__(
+        self,
+        pipeline: _ImagePipeline | None,
+        *,
+        load_config: CanterWebLaunchConfig | None = None,
+    ) -> None:
+        """Retain a pipeline or the exact configuration needed to load it."""
+
+        if pipeline is None and load_config is None:
+            raise ValueError("A lazy Canter web controller requires load_config.")
+        if pipeline is not None and load_config is not None:
+            raise ValueError("Provide either pipeline or load_config, not both.")
+
+        self.pipeline = pipeline
+        self._load_config = load_config
+        self._load_lock = threading.Lock()
+        self._session_lock = threading.Lock()
+        self._generation_by_session: dict[str, _WebGenerationState] = {}
+        self._explicitly_unloaded = False
+        self._unload_pending = False
+
+    def load(
+        self,
+    ) -> tuple[str, str, dict[str, object], dict[str, object], dict[str, object]]:
+        """Load initially without undoing an explicit backend unload."""
+
+        with self._load_lock:
+            if self._explicitly_unloaded:
+                unloaded = _unloaded_model_status()
+                return (
+                    unloaded,
+                    unloaded,
+                    gr.update(interactive=True),
+                    gr.update(interactive=True),
+                    gr.update(interactive=True),
+                )
+            pipeline = self._load_pipeline_locked()
+        return (
+            _model_summary(pipeline.metadata),
+            "Ready. The first request includes compiled graph warm-up.",
+            gr.update(interactive=True),
+            gr.update(interactive=True),
+            gr.update(interactive=True),
+        )
+
+    def request_stop(self, request: gr.Request | None = None) -> str:
+        """Cancel only the active generation owned by the requesting browser."""
+
+        session_hash = _session_hash(request)
+        with self._session_lock:
+            state = self._generation_by_session.get(session_hash)
+            if state is None:
+                return "No generation is currently active in this browser session."
+            state.stop_requested.set()
+        return "Stopping after the current solver step…"
+
+    def request_backend_unload(self) -> str:
+        """Stop every active request and block new loads until cleanup completes."""
+
+        with self._load_lock:
+            self._unload_pending = True
+        with self._session_lock:
+            active_states = tuple(self._generation_by_session.values())
+            for state in active_states:
+                state.stop_requested.set()
+        active_count = len(active_states)
+        _LOGGER.info(
+            "Canter backend unload requested | active_requests=%d",
+            active_count,
+        )
+        if active_count == 0:
+            return "Unloading Canter and clearing generated images…"
+        request_word = "request" if active_count == 1 else "requests"
+        return (
+            f"Stopping **{active_count} active {request_word}** at the next solver "
+            "boundary, then unloading Canter…"
+        )
+
+    def unload_backend(self) -> str:
+        """Release the reloadable pipeline and flush compiler and CUDA caches."""
+
+        with self._load_lock:
+            with self._session_lock:
+                active_count = len(self._generation_by_session)
+            if active_count != 0:
+                raise RuntimeError(
+                    "Cannot unload Canter while generation state remains active."
+                )
+            if self._load_config is None:
+                raise RuntimeError(
+                    "This embedded Canter pipeline has no reload configuration."
+                )
+            pipeline = self.pipeline
+            self.pipeline = None
+            self._explicitly_unloaded = True
+            if pipeline is not None:
+                pipeline.close()
+            del pipeline
+            try:
+                torch.compiler.reset()
+                gc.collect()
+                torch.cuda.empty_cache()
+            except (OSError, RuntimeError):
+                _LOGGER.exception("Canter backend unload cleanup failed")
+                raise
+            self._unload_pending = False
+        _LOGGER.info("Canter backend unloaded")
+        return "Canter is unloaded. The next generation will reload and compile it."
+
+    def model_status(self) -> str:
+        """Return the current process-wide model residency state."""
+
+        with self._load_lock:
+            if self.pipeline is None:
+                return _unloaded_model_status()
+            return _model_summary(self.pipeline.metadata)
+
+    def generate(  # noqa: PLR0917 - Gradio supplies the explicit form fields.
+        self,
+        prompt: str,
+        image_count: int | float,
+        width: int | float,
+        height: int | float,
+        seed: int | float,
+        steps: int | float,
+        solver: str,
+        schedule: str,
+        log_snr_shift: int | float,
+        self_attention_gain: int | float,
+        euler_maruyama_multiplier: int | float,
+        cfg_enabled: bool,
+        cfg_scale: int | float,
+        cfg_start_step: int | float,
+        cfg_stop_step: int | float | str | None,
+        pdg_enabled: bool,
+        pdg_mode: str,
+        pdg_curve: str,
+        pdg_noisy_scale: int | float,
+        pdg_clean_scale: int | float,
+        pdg_power: int | float,
+        pdg_start_step: int | float,
+        pdg_stop_step: int | float | str | None,
+        preview_enabled: bool,
+        browser_request: gr.Request | None = None,
+    ) -> Generator[_GenerationUpdate, None, None]:
+        """Yield each batch-one image as soon as its decoding completes."""
+
+        session_hash = _session_hash(browser_request)
+        request = build_web_request(
+            prompt=prompt,
+            image_count=image_count,
+            width=width,
+            height=height,
+            seed=seed,
+            steps=steps,
+            solver=solver,
+            schedule=schedule,
+            log_snr_shift=log_snr_shift,
+            self_attention_gain=self_attention_gain,
+            euler_maruyama_multiplier=euler_maruyama_multiplier,
+            cfg_enabled=cfg_enabled,
+            cfg_scale=cfg_scale,
+            cfg_start_step=cfg_start_step,
+            cfg_stop_step=cfg_stop_step,
+            pdg_enabled=pdg_enabled,
+            pdg_mode=pdg_mode,
+            pdg_curve=pdg_curve,
+            pdg_noisy_scale=pdg_noisy_scale,
+            pdg_clean_scale=pdg_clean_scale,
+            pdg_power=pdg_power,
+            pdg_start_step=pdg_start_step,
+            pdg_stop_step=pdg_stop_step,
+        )
+        _log_generation_request(request)
+        pipeline = self._ensure_loaded()
+        started = time.perf_counter()
+        guidance = _pdg_status(request.config.inference)
+        stop_requested = self._begin_generation(
+            session_hash,
+            image_index=0,
+            image_count=request.image_count,
+            completed_updates=0,
+            total_updates=request.config.inference.steps,
+        )
+        try:
+            yield _generation_update(
+                _cleared_image_slots(),
+                f"Generating **{request.image_count} images** with batch size `1` · "
+                f"{guidance}…",
+                progress_active=True,
+            )
+            for image_index in range(request.image_count):
+                self._raise_if_stopped(stop_requested)
+                image_number = image_index + 1
+                self._set_preview_target(
+                    session_hash,
+                    stop_requested=stop_requested,
+                    target=image_index if preview_enabled else None,
+                )
+                self._set_progress(
+                    session_hash,
+                    image_index=image_index,
+                    image_count=request.image_count,
+                    completed_updates=0,
+                    total_updates=request.config.inference.steps,
+                )
+                image_config = _image_config(request, image_index)
+                output = pipeline(
+                    request.prompt,
+                    config=image_config,
+                    initial_noise=None,
+                    progress=_step_progress(
+                        stopped=stop_requested.is_set,
+                        update_web=lambda completed, total, index=image_index: (
+                            self._set_progress(
+                                session_hash,
+                                image_index=index,
+                                image_count=request.image_count,
+                                completed_updates=completed,
+                                total_updates=total,
+                            )
+                        ),
+                    ),
+                    preview=(
+                        (
+                            lambda images, completed, total, index=image_index: (
+                                self._publish_preview(
+                                    session_hash,
+                                    stop_requested=stop_requested,
+                                    image_index=index,
+                                    images=images,
+                                )
+                            )
+                        )
+                        if preview_enabled
+                        else None
+                    ),
+                )
+                self._set_preview_target(
+                    session_hash,
+                    stop_requested=stop_requested,
+                    target=None,
+                )
+                self._raise_if_stopped(stop_requested)
+                if output.images is None or len(output.images) != 1:
+                    raise RuntimeError(
+                        "Each batch-one Canter web invocation must return one PIL image."
+                    )
+                image = _attach_png_metadata(
+                    output.images[0],
+                    prompt=request.prompt,
+                    config=image_config,
+                    metadata=pipeline.metadata,
+                )
+                elapsed = time.perf_counter() - started
+                status = _generation_status(
+                    pipeline.metadata,
+                    request=request,
+                    elapsed=elapsed,
+                    completed=image_number,
+                )
+                yield _generation_update(
+                    _completed_image_slots(
+                        image=image,
+                        image_index=image_index,
+                    ),
+                    status,
+                    progress_active=None,
+                )
+        except _GenerationStoppedError:
+            yield _generation_update(
+                _preserved_image_slots(),
+                "Stopped. Ready for another request.",
+                progress_active=None,
+            )
+        finally:
+            self._finish_generation(session_hash, stop_requested)
+
+    def poll_progress(
+        self,
+        request: gr.Request | None = None,
+    ) -> tuple[_GenerationOutputUpdate, ...]:
+        """Consume one newest preview, progress HTML, and polling lifecycle."""
+
+        session_hash = _session_hash(request)
+        with self._session_lock:
+            generation = self._generation_by_session.get(session_hash)
+            if generation is not None and generation.pending_preview is not None:
+                pending = generation.pending_preview
+                self._generation_by_session[session_hash] = replace(
+                    generation,
+                    pending_preview=None,
+                )
+            else:
+                pending = None
+        state = None if generation is None else generation.progress
+        image_updates = (
+            _preserved_image_slots()
+            if pending is None
+            else _completed_image_slots(
+                image=pending.image,
+                image_index=pending.image_index,
+            )
+        )
+        return (
+            *image_updates,
+            *_progress_html(state),
+            gr.update(active=generation is not None),
+        )
+
+    def _raise_if_stopped(self, stop_requested: threading.Event) -> None:
+        """Abort at the next safe boundary after a web stop request."""
+
+        if stop_requested.is_set():
+            raise _GenerationStoppedError
+
+    def _begin_generation(
+        self,
+        session_hash: str,
+        *,
+        image_index: int,
+        image_count: int,
+        completed_updates: int,
+        total_updates: int,
+    ) -> threading.Event:
+        """Register and return cancellation state for a new browser generation."""
+
+        progress = _WebProgressState(
+            image_index=image_index,
+            image_count=image_count,
+            completed_updates=completed_updates,
+            total_updates=total_updates,
+        )
+        stop_requested = threading.Event()
+        state = _WebGenerationState(
+            stop_requested=stop_requested,
+            progress=progress,
+            preview_image_index=image_index,
+            pending_preview=None,
+        )
+        with self._session_lock:
+            if session_hash in self._generation_by_session:
+                raise RuntimeError(
+                    "A browser session cannot run multiple Canter generations."
+                )
+            self._generation_by_session[session_hash] = state
+        return stop_requested
+
+    def _set_progress(
+        self,
+        session_hash: str,
+        *,
+        image_index: int,
+        image_count: int,
+        completed_updates: int,
+        total_updates: int,
+    ) -> None:
+        """Publish one solver position for the requesting browser session."""
+
+        progress = _WebProgressState(
+            image_index=image_index,
+            image_count=image_count,
+            completed_updates=completed_updates,
+            total_updates=total_updates,
+        )
+        with self._session_lock:
+            state = self._generation_by_session.get(session_hash)
+            if state is None:
+                raise RuntimeError(
+                    "Cannot update progress without an active generation."
+                )
+            self._generation_by_session[session_hash] = replace(
+                state,
+                progress=progress,
+            )
+
+    def _set_preview_target(
+        self,
+        session_hash: str,
+        *,
+        stop_requested: threading.Event,
+        target: int | None,
+    ) -> None:
+        """Select one image for previews, or reject late previews with None."""
+
+        with self._session_lock:
+            state = self._generation_by_session.get(session_hash)
+            if state is None or state.stop_requested is not stop_requested:
+                raise RuntimeError("Cannot update preview for an inactive generation.")
+            self._generation_by_session[session_hash] = replace(
+                state,
+                preview_image_index=target,
+                pending_preview=None,
+            )
+
+    def _publish_preview(
+        self,
+        session_hash: str,
+        *,
+        stop_requested: threading.Event,
+        image_index: int,
+        images: tuple[Image.Image, ...],
+    ) -> None:
+        """Publish only the newest preview for the still-active image."""
+
+        pending = _WebPreview(image_index=image_index, image=images[0])
+        with self._session_lock:
+            state = self._generation_by_session.get(session_hash)
+            if (
+                state is None
+                or state.stop_requested is not stop_requested
+                or state.preview_image_index != image_index
+            ):
+                return
+            self._generation_by_session[session_hash] = replace(
+                state,
+                pending_preview=pending,
+            )
+
+    def _finish_generation(
+        self,
+        session_hash: str,
+        stop_requested: threading.Event,
+    ) -> None:
+        """Remove exactly the browser generation that has finished."""
+
+        with self._session_lock:
+            state = self._generation_by_session.get(session_hash)
+            if state is None or state.stop_requested is not stop_requested:
+                raise RuntimeError(
+                    "Canter browser generation state became inconsistent."
+                )
+            del self._generation_by_session[session_hash]
+
+    def _ensure_loaded(self) -> _ImagePipeline:
+        """Return the process pipeline, loading it exactly once when necessary."""
+
+        with self._load_lock:
+            if self._unload_pending:
+                raise RuntimeError("Canter backend unload is still in progress.")
+            return self._load_pipeline_locked()
+
+    def _load_pipeline_locked(self) -> _ImagePipeline:
+        """Load under the lifecycle lock and return the resident pipeline."""
+
+        if self.pipeline is None:
+            config = self._load_config
+            if config is None:
+                raise RuntimeError(
+                    "Lazy Canter loading is missing its launch configuration."
+                )
+            self.pipeline = load_web_pipeline(config)
+        self._explicitly_unloaded = False
+        return self.pipeline
+
+
+def _preserved_image_slots() -> tuple[dict[str, str], ...]:
+    """Return no-op updates that retain every displayed image."""
+
+    return tuple(gr.skip() for _ in range(_MAX_IMAGE_COUNT))
+
+
+def _cleared_image_slots() -> tuple[None, ...]:
+    """Clear every image before one new sequential generation."""
+
+    return (None,) * _MAX_IMAGE_COUNT
+
+
+def _completed_image_slots(
+    *,
+    image: Image.Image,
+    image_index: int,
+) -> tuple[_ImageSlotUpdate, ...]:
+    """Update exactly one newly completed image in the fixed output boundary."""
+
+    updates: list[_ImageSlotUpdate] = list(_preserved_image_slots())
+    updates[image_index] = image
+    return tuple(updates)
+
+
+def _generation_update(
+    images: Sequence[_ImageSlotUpdate],
+    status: str,
+    *,
+    progress_active: bool | None,
+) -> _GenerationUpdate:
+    """Return image, status, and timer updates expected by Gradio."""
+
+    if len(images) != _MAX_IMAGE_COUNT:
+        raise ValueError(
+            f"Expected {_MAX_IMAGE_COUNT} web image slots, got {len(images)}."
+        )
+    return (
+        *images,
+        status,
+        (gr.skip() if progress_active is None else gr.update(active=progress_active)),
+    )
+
+
+def _step_progress(
+    *,
+    stopped: Callable[[], bool],
+    update_web: Callable[[int, int], None],
+) -> SolverProgress:
+    """Create an exact solver-update reporter for one sequential image."""
+
+    def report(completed: int, total: int) -> None:
+        """Update the current image bar while retaining the total image bar."""
+
+        if stopped():
+            raise _GenerationStoppedError
+        update_web(completed, total)
+
+    return report
+
+
+def _session_hash(request: gr.Request | None) -> str:
+    """Return the required Gradio browser-session identifier."""
+
+    if request is None or request.session_hash is None or not request.session_hash:
+        raise ValueError("Web generation requires a Gradio browser session hash.")
+    return request.session_hash
+
+
+def _progress_html(
+    state: _WebProgressState | None,
+) -> tuple[str, ...]:
+    """Render total progress and the active image's solver overlay."""
+
+    slots = [""] * _MAX_IMAGE_COUNT
+    if state is None:
+        return ("", *slots)
+    image_fraction = state.completed_updates / state.total_updates
+    total_fraction = (state.image_index + image_fraction) / state.image_count
+    image_percent = 100.0 * image_fraction
+    total_percent = 100.0 * total_fraction
+    total_html = f"""
+<div class="canter-progress-panel">
+  <div class="canter-progress-label">
+    Total progress · Image {state.image_index + 1}/{state.image_count}
+  </div>
+  <div class="canter-progress-row">
+    <span>Total</span>
+    <div class="canter-progress-track">
+      <div style="width: {total_percent:.2f}%"></div>
+    </div>
+    <span>{total_percent:.0f}%</span>
+  </div>
+</div>
+"""
+    slots[state.image_index] = f"""
+<div class="canter-progress-panel">
+  <div class="canter-progress-label">
+    Image {state.image_index + 1}/{state.image_count}
+    · {state.completed_updates}/{state.total_updates} updates
+  </div>
+  <div class="canter-progress-row">
+    <span>Image</span>
+    <div class="canter-progress-track">
+      <div style="width: {image_percent:.2f}%"></div>
+    </div>
+    <span>{image_percent:.0f}%</span>
+  </div>
+</div>
+"""
+    return (total_html, *slots)
+
+
+def _choice(
+    value: str | None,
+    choices: Mapping[str, _Choice],
+    name: str,
+) -> _Choice:
+    """Resolve one exact enum-backed form choice or fail with its field name."""
+
+    if value is None:
+        raise ValueError(f"{name} is required.")
+    selected = choices.get(value)
+    if selected is None:
+        raise ValueError(f"Unsupported {name}: {value!r}.")
+    return selected
+
+
+def _integer(
+    value: int | float | None,
+    name: str,
+    *,
+    minimum: int,
+    maximum: int | None,
+) -> int:
+    """Convert one integral form number and enforce its explicit bounds."""
+
+    if value is None or isinstance(value, bool):
+        raise TypeError(f"{name} must be an integer.")
+    number = float(value)
+    if not math.isfinite(number) or not number.is_integer():
+        raise ValueError(f"{name} must be a finite integer.")
+    result = int(number)
+    if result < minimum:
+        raise ValueError(f"{name} must be at least {minimum}.")
+    if maximum is not None and result > maximum:
+        raise ValueError(f"{name} must not exceed {maximum}.")
+    return result
+
+
+def _optional_integer(
+    value: int | float | str | None,
+    name: str,
+) -> int | None:
+    """Convert a blank solver stop field to ``None`` or validate an index."""
+
+    if value is None:
+        return None
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return None
+        try:
+            numeric = float(stripped)
+        except ValueError as exc:
+            raise ValueError(f"{name} must be blank or a finite integer.") from exc
+        return _integer(numeric, name, minimum=0, maximum=None)
+    return _integer(value, name, minimum=0, maximum=None)
+
+
+def _number(value: int | float, name: str) -> float:
+    """Require one finite floating-point form value."""
+
+    if isinstance(value, bool):
+        raise TypeError(f"{name} must be a number.")
+    result = float(value)
+    if not math.isfinite(result):
+        raise ValueError(f"{name} must be finite.")
+    return result
+
+
+def _image_dimension(value: int | float | None, name: str) -> int:
+    """Snap one finite image dimension to the supported 32-pixel lattice."""
+
+    if value is None:
+        raise ValueError(f"{name} is required.")
+    number = _number(value, name)
+    if number < _IMAGE_SIZE_MULTIPLE:
+        raise ValueError(f"{name} must be at least {_IMAGE_SIZE_MULTIPLE}.")
+    return snap_image_dimension(number)
+
+
+def snap_image_dimension(value: int | float | None) -> int:
+    """Snap one browser image dimension to its nearest valid multiple."""
+
+    if value is None:
+        raise ValueError("image size is required.")
+    number = _number(value, "image size")
+    snapped = math.floor(
+        (max(number, _IMAGE_SIZE_MULTIPLE) + _IMAGE_SIZE_MULTIPLE / 2)
+        / _IMAGE_SIZE_MULTIPLE
+    )
+    return snapped * _IMAGE_SIZE_MULTIPLE
+
+
+def _validated_prompt(prompt: str) -> str:
+    """Return a string prompt without changing the user's text."""
+
+    if not isinstance(prompt, str):
+        raise TypeError("prompt must be a string.")
+    return prompt
+
+
+def _pdg_mode_uses_cfg(mode: PdgMode) -> bool:
+    """Return whether one public PDG mode consumes the CFG scale."""
+
+    match mode:
+        case (
+            PdgMode.ALTERNATE_PDG_FIRST
+            | PdgMode.ALTERNATE_CFG_FIRST
+            | PdgMode.COMBINED_CFG_PDG
+            | PdgMode.PDG_WITH_ALTERNATING_CFG
+            | PdgMode.CFG_TO_PDG
+        ):
+            return True
+        case PdgMode.FULL | PdgMode.THREE_QUARTER:
+            return False
+        case PdgMode.NONE:
+            raise ValueError("The enabled web PDG selection cannot use mode none.")
+        case _ as unreachable:
+            raise RuntimeError(f"Unsupported PDG mode: {unreachable}")
+
+
+def update_pdg_clean_scale(
+    curve: str,
+    noisy_scale: int | float,
+) -> dict[str, object]:
+    """Disable and synchronize the unused clean endpoint for constant PDG."""
+
+    resolved_curve = _choice(curve, _PDG_CURVES, "PDG curve")
+    match resolved_curve:
+        case PdgCurve.CONSTANT:
+            return gr.update(
+                value=_number(noisy_scale, "PDG noisy scale"),
+                interactive=False,
+            )
+        case PdgCurve.LINEAR | PdgCurve.POWER:
+            return gr.update(interactive=True)
+        case _ as unreachable:
+            raise RuntimeError(f"Unsupported PDG curve: {unreachable}")
+
+
+def build_web_request(
+    *,
+    prompt: str,
+    image_count: int | float,
+    width: int | float,
+    height: int | float,
+    seed: int | float,
+    steps: int | float,
+    solver: str,
+    schedule: str,
+    log_snr_shift: int | float,
+    self_attention_gain: int | float,
+    euler_maruyama_multiplier: int | float,
+    cfg_enabled: bool,
+    cfg_scale: int | float,
+    cfg_start_step: int | float,
+    cfg_stop_step: int | float | str | None,
+    pdg_enabled: bool,
+    pdg_mode: str,
+    pdg_curve: str,
+    pdg_noisy_scale: int | float,
+    pdg_clean_scale: int | float,
+    pdg_power: int | float,
+    pdg_start_step: int | float,
+    pdg_stop_step: int | float | str | None,
+) -> CanterWebRequest:
+    """Validate raw Gradio values and construct the frozen Canter dataclasses."""
+
+    resolved_pdg_mode = _choice(pdg_mode, _PDG_MODES, "PDG mode")
+    active_pdg_mode = resolved_pdg_mode if pdg_enabled else PdgMode.NONE
+    uses_cfg_scale = pdg_enabled and _pdg_mode_uses_cfg(resolved_pdg_mode)
+    resolved_cfg_scale = (
+        _number(cfg_scale, "CFG scale") if cfg_enabled or uses_cfg_scale else None
+    )
+    cfg = CfgGuidance(
+        enabled=cfg_enabled,
+        scale=resolved_cfg_scale,
+        start_step=_integer(
+            cfg_start_step,
+            "CFG start step",
+            minimum=0,
+            maximum=None,
+        ),
+        stop_step=_optional_integer(cfg_stop_step, "CFG stop step"),
+    )
+    resolved_pdg_curve = _choice(pdg_curve, _PDG_CURVES, "PDG curve")
+    resolved_pdg_noisy_scale = _number(pdg_noisy_scale, "PDG noisy scale")
+    resolved_pdg_clean_scale = (
+        resolved_pdg_noisy_scale
+        if resolved_pdg_curve is PdgCurve.CONSTANT
+        else _number(pdg_clean_scale, "PDG clean scale")
+    )
+    pdg = PdgGuidance(
+        enabled=pdg_enabled,
+        mode=active_pdg_mode,
+        curve=resolved_pdg_curve,
+        noisy_scale=resolved_pdg_noisy_scale,
+        clean_scale=resolved_pdg_clean_scale,
+        power=_number(pdg_power, "PDG power"),
+        start_step=_integer(
+            pdg_start_step,
+            "PDG start step",
+            minimum=0,
+            maximum=None,
+        ),
+        stop_step=_optional_integer(pdg_stop_step, "PDG stop step"),
+    )
+    resolved_image_count = _integer(
+        image_count,
+        "image count",
+        minimum=1,
+        maximum=_MAX_IMAGE_COUNT,
+    )
+    resolved_seed = _integer(
+        seed,
+        "seed",
+        minimum=0,
+        maximum=_MAX_SEED - resolved_image_count + 1,
+    )
+    inference = CanterInferenceConfig(
+        height=_image_dimension(height, "height"),
+        width=_image_dimension(width, "width"),
+        steps=_integer(steps, "steps", minimum=1, maximum=None),
+        solver=_choice(solver, _SOLVERS, "solver"),
+        schedule=_choice(schedule, _SCHEDULES, "schedule"),
+        log_snr_shift=_number(log_snr_shift, "log-SNR shift"),
+        cfg=cfg,
+        pdg=pdg,
+        self_attention_gain=_number(
+            self_attention_gain,
+            "self-attention gain",
+        ),
+        euler_maruyama_multiplier=_number(
+            euler_maruyama_multiplier,
+            "SDE noise multiplier",
+        ),
+        er_sde_noise_multiplier=_number(
+            euler_maruyama_multiplier,
+            "SDE noise multiplier",
+        ),
+        seed=resolved_seed,
+        generator=None,
+    )
+    return CanterWebRequest(
+        prompt=_validated_prompt(prompt),
+        image_count=resolved_image_count,
+        config=CanterPipelineConfig(
+            inference=inference,
+            output_type=CanterOutputType.PIL,
+        ),
+    )
+
+
+def _image_config(
+    request: CanterWebRequest,
+    image_index: int,
+) -> CanterPipelineConfig:
+    """Return a batch-one config using the next deterministic image seed."""
+
+    seed = request.config.inference.seed
+    if seed is None:
+        raise RuntimeError("A validated Canter web request must contain a seed.")
+    inference = replace(
+        request.config.inference,
+        seed=seed + image_index,
+        generator=None,
+    )
+    return replace(request.config, inference=inference)
+
+
+def _pdg_metadata(pdg: PdgGuidance) -> dict[str, object]:
+    """Return PDG fields in public API order."""
+
+    return {
+        "enabled": pdg.enabled,
+        "mode": pdg.mode.value,
+        "curve": pdg.curve.value,
+        "noisy_scale": pdg.noisy_scale,
+        "clean_scale": pdg.clean_scale,
+        "power": pdg.power,
+        "start_step": pdg.start_step,
+        "stop_step": pdg.stop_step,
+    }
+
+
+def _cfg_metadata(cfg: CfgGuidance) -> dict[str, object]:
+    """Return CFG fields in public API order."""
+
+    return {
+        "enabled": cfg.enabled,
+        "scale": cfg.scale,
+        "start_step": cfg.start_step,
+        "stop_step": cfg.stop_step,
+    }
+
+
+def _png_metadata_json(
+    *,
+    prompt: str,
+    config: CanterPipelineConfig,
+    metadata: CanterPipelineMetadata,
+) -> str:
+    """Serialize reproducible UI settings with primary inputs first."""
+
+    inference = config.inference
+    if inference.seed is None:
+        raise RuntimeError("PNG metadata requires the resolved per-image seed.")
+    payload: dict[str, object] = {
+        "prompt": prompt,
+        "seed": inference.seed,
+        "width": inference.width,
+        "height": inference.height,
+        "steps": inference.steps,
+        "solver": inference.solver.value,
+        "schedule": inference.schedule.value,
+        "pdg": _pdg_metadata(inference.pdg),
+        "cfg": _cfg_metadata(inference.cfg),
+        "self_attention_gain": inference.self_attention_gain,
+        "log_snr_shift": inference.log_snr_shift,
+        "euler_maruyama_multiplier": inference.euler_maruyama_multiplier,
+        "er_sde_noise_multiplier": inference.er_sde_noise_multiplier,
+        "code_version": metadata.code_version,
+        "release": metadata.canter.release,
+        "weight_dtype": metadata.canter.weight_dtype.value,
+    }
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+def _attach_png_metadata(
+    image: Image.Image,
+    *,
+    prompt: str,
+    config: CanterPipelineConfig,
+    metadata: CanterPipelineMetadata,
+) -> Image.Image:
+    """Attach the ordered API query for Gradio's PNG encoder."""
+
+    image.info[_PNG_METADATA_KEY] = _png_metadata_json(
+        prompt=prompt,
+        config=config,
+        metadata=metadata,
+    )
+    return image
+
+
+def random_seed() -> int:
+    """Return a non-negative seed accepted by the Canter web form."""
+
+    return secrets.randbelow(_MAX_SEED + 1)
+
+
+def _model_summary(metadata: CanterPipelineMetadata) -> str:
+    """Render immutable model and decoder provenance above the controls."""
+
+    canter = metadata.canter
+    return (
+        f"**Canter checkpoint {canter.release}** · "
+        f"code `{metadata.code_version}` · "
+        f"{canter.weight_dtype.value} EMA weights  \n"
+        f"VAE `{metadata.vae_repository}` @ `{metadata.vae_revision[:12]}`"
+    )
+
+
+def _unloaded_model_status() -> str:
+    """Render the explicit lazy-reload state above the controls."""
+
+    return (
+        "**Canter model unloaded** · CUDA and compiler caches cleared  \n"
+        "The next generation will reload and compile the selected checkpoint."
+    )
+
+
+def _log_generation_request(request: CanterWebRequest) -> None:
+    """Log the exact effective controls consumed by one generation request."""
+
+    inference = request.config.inference
+    prompt_digest = sha256(request.prompt.encode("utf-8")).hexdigest()[:12]
+    _LOGGER.info(
+        "Canter request | "
+        f"prompt_sha256={prompt_digest} | images={request.image_count} | "
+        f"size={inference.width}x{inference.height} | seed={inference.seed} | "
+        f"steps={inference.steps} | solver={inference.solver.value} | "
+        f"schedule={inference.schedule.value} | "
+        f"log_snr_shift={inference.log_snr_shift:g} | "
+        f"self_attention_gain={inference.self_attention_gain:g} | "
+        f"{_pdg_status(inference)} | cfg_enabled={inference.cfg.enabled} | "
+        f"cfg_scale={inference.cfg.scale}",
+    )
+
+
+def _pdg_status(inference: CanterInferenceConfig) -> str:
+    """Render the effective PDG request consumed by latent inference."""
+
+    pdg = inference.pdg
+    if not pdg.enabled:
+        return "PDG off"
+    stop = inference.steps - 1 if pdg.stop_step is None else pdg.stop_step
+    match pdg.curve:
+        case PdgCurve.CONSTANT:
+            scale = f"{float(pdg.noisy_scale):g}"
+        case PdgCurve.LINEAR:
+            scale = f"linear {float(pdg.noisy_scale):g}→{float(pdg.clean_scale):g}"
+        case PdgCurve.POWER:
+            scale = (
+                f"power {float(pdg.noisy_scale):g}→"
+                f"{float(pdg.clean_scale):g} (p={float(pdg.power):g})"
+            )
+        case _ as unreachable:
+            raise RuntimeError(f"Unsupported PDG curve: {unreachable}")
+    return f"PDG `{pdg.mode.value}` {scale}, updates {pdg.start_step}–{stop}"
+
+
+def _generation_status(
+    metadata: CanterPipelineMetadata,
+    *,
+    request: CanterWebRequest,
+    elapsed: float,
+    completed: int,
+) -> str:
+    """Render incremental timing and deterministic request provenance."""
+
+    inference = request.config.inference
+    image_word = "image" if completed == 1 else "images"
+    if inference.seed is None:
+        raise RuntimeError("A validated Canter web request must contain a seed.")
+    final_seed = inference.seed + completed - 1
+    seed_text = (
+        str(inference.seed) if completed == 1 else f"{inference.seed}–{final_seed}"
+    )
+    progress_text = (
+        f"Generated **{completed}/{request.image_count} {image_word}**"
+        if completed < request.image_count
+        else f"Generated **{completed} {image_word}**"
+    )
+    return (
+        f"{progress_text} in **{elapsed:.2f}s** · "
+        f"seeds `{seed_text}` · batch size `1` · "
+        f"{inference.width}×{inference.height} · "
+        f"{inference.steps} {inference.solver.value} updates · "
+        f"{_pdg_status(inference)} · "
+        f"Canter code `{metadata.code_version}` · "
+        f"checkpoint `{metadata.canter.release}`"
+    )
+
+
+def load_web_pipeline(config: CanterWebLaunchConfig) -> CanterPipeline:
+    """Load and compile exactly one selected Canter backend for the web process."""
+
+    return CanterPipeline.from_pretrained(
+        config.model,
+        dtype=config.dtype,
+        text_backend=config.text_backend,
+        device=config.device,
+        revision=config.revision,
+        cache_dir=config.cache_dir,
+        compile_model=True,
+        vae=None,
+    )

release.json

@@ -2,6 +2,11 @@
   "dtype": "bfloat16",
   "exporter_sha256": "df8a6cf46d78b38d8297b0c75a76c1eaaf859bb55ec3375a623dc4804d5571d1",
   "exporter_source_commit": "e75e83d792f45eb82e60e022500edead452be79a",
+  "latent_rgb_preview_source_checkpoint_sha256": "f42fd1af65010acba63582288d1802e054ab1cde4c3226dc02494c882cdea78e",
+  "latent_rgb_preview_source_config_sha256": "8aff4041a12fe2165442867299f82e14853c2f71d9c94b6705e67521d6c042fb",
+  "latent_rgb_preview_source_run_hash": "553803c53a59848a",
+  "latent_rgb_preview_source_run_id": "625",
+  "latent_rgb_preview_source_step": 5600,
   "license": "MG-BY-SA-2.0",
   "parameter_count": 2061680772,
   "parity_result_ids": [

weights_manifest.json

@@ -6207,6 +6207,35 @@
     ],
     "total_size": 4132975120
   },
+  "latent_rgb_preview": {
+    "filename": "canter/latent_rgb_preview.safetensors",
+    "parameter_count": 1548,
+    "tensor_count": 2,
+    "tensors": [
+      {
+        "dtype": "float32",
+        "name": "projection.bias",
+        "nbytes": 48,
+        "numel": 12,
+        "shape": [
+          12
+        ]
+      },
+      {
+        "dtype": "float32",
+        "name": "projection.weight",
+        "nbytes": 6144,
+        "numel": 1536,
+        "shape": [
+          12,
+          128,
+          1,
+          1
+        ]
+      }
+    ],
+    "total_size": 6192
+  },
   "text_encoder": {
     "parameter_count": 283161600,
     "tensor_count": 217,