From 5c09dabd7d4d22eb6d74d6ae53853601de9b57f0 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 20 Oct 2026 06:10:01 +0000
Subject: [PATCH 01/52] Unload idle ComfyUI models before a picture or the
 prompt model

A video already unloads ComfyUI's own idle models before it starts. Pictures and the prompt model did not, and the picture budget did not count them, so a native workflow's model could keep a picture out of memory until ComfyUI was restarted. Both now send ComfyUI's own unload command first (only when a native model is loaded and no native prompt is running), keep the idle video engine during that unload, and the picture budget counts that memory. Picture failure reports record what was unloaded.
---
 freevideo_engine/comfy_residency.py    | 60 +++++++++++++++++++++++++-
 freevideo_engine/image_gen/failure.py  |  6 +++
 freevideo_engine/image_gen/service.py  | 22 +++++++++-
 freevideo_engine/prompt_vlm/service.py |  3 ++
 4 files changed, 89 insertions(+), 2 deletions(-)

diff --git a/freevideo_engine/comfy_residency.py b/freevideo_engine/comfy_residency.py
index b2ee8158..aa329952 100644
--- a/freevideo_engine/comfy_residency.py
+++ b/freevideo_engine/comfy_residency.py
@@ -2,10 +2,14 @@
 from contextlib import contextmanager
 from functools import wraps
 import threading
+import time
 
 from .resident_process import OWNER
 
 _local = threading.local()
+# Set while release_native() waits: ComfyUI's prompt thread runs that unload, so the thread-local
+# keep_engine_cache() cannot reach it. Our own unload frees native models only, as a video's does.
+_releasing = threading.Event()
 
 
 @contextmanager
@@ -18,6 +22,60 @@ def keep_engine_cache():
         _local.keep = old
 
 
+def _native():
+    """ComfyUI's memory manager in this process, or None outside ComfyUI."""
+    import sys
+    memory = sys.modules.get('comfy.model_management')
+    return memory if memory is not None and getattr(memory, 'current_loaded_models', None) is not None else None
+
+
+def _prompt_running(server):
+    try:
+        return bool(server.prompt_queue.get_current_queue()[0])
+    except (AttributeError, TypeError, IndexError):
+        return True
+
+
+def native_reclaimable(server):
+    """GPU bytes that ComfyUI's own idle models hold in this process; release_native() returns them.
+
+    0 when nothing is loaded, or while a prompt is running (its models are in use)."""
+    memory = _native()
+    if memory is None or not memory.current_loaded_models or server is None or _prompt_running(server):
+        return 0
+    try:
+        import torch
+        return int(torch.cuda.memory_reserved(memory.get_torch_device()))
+    except Exception:
+        return 0
+
+
+def release_native(server, *, timeout=10.):
+    """Before an image or prompt-model worker starts, unload ComfyUI's own idle models, as a video does.
+
+    ComfyUI's prompt worker does it between prompts, through the same unload command its own
+    "free memory" button sends. Nothing happens when no native model is loaded, or while a prompt
+    is running (its models are in use). Returns what was released."""
+    memory = _native()
+    if memory is None or not memory.current_loaded_models or server is None or _prompt_running(server):
+        return None
+    import torch
+    device = memory.get_torch_device()
+    before = dict(models=len(memory.current_loaded_models), reserved_bytes=int(torch.cuda.memory_reserved(device)))
+    _releasing.set()
+    try:
+        server.prompt_queue.set_flag('unload_models', True)
+        deadline = time.monotonic() + timeout
+        while memory.current_loaded_models and time.monotonic() < deadline:
+            time.sleep(.05)
+    finally:
+        _releasing.clear()
+    if not memory.current_loaded_models:
+        memory.soft_empty_cache()
+    return dict(before, released=not memory.current_loaded_models,
+                reserved_after_bytes=int(torch.cuda.memory_reserved(device)))
+
+
 def install(memory):
     if getattr(memory.free_memory, '_freevideo_resident_cooperation', False) is True:
         return
@@ -28,7 +86,7 @@ def free_memory(memory_required, device, *args, **kwargs):
         # FreeVideo's own handoff releases native Comfy models only. Other
         # nodes, and Comfy's explicit unload command, can reclaim our idle
         # process before choosing a lower-memory native loading strategy.
-        if (not getattr(_local, 'keep', False) and not OWNER.active and
+        if (not getattr(_local, 'keep', False) and not _releasing.is_set() and not OWNER.active and
                 OWNER.process is not None and OWNER.process.poll() is None):
             if device is None or memory_required > memory.get_free_memory(device):
                 OWNER.release('comfy_model')
diff --git a/freevideo_engine/image_gen/failure.py b/freevideo_engine/image_gen/failure.py
index 9055e01b..6aeb6ef9 100644
--- a/freevideo_engine/image_gen/failure.py
+++ b/freevideo_engine/image_gen/failure.py
@@ -199,6 +199,8 @@ def __init__(self, action, value):
         self.plan = None
         self.pack = None
         self.start_memory = None
+        # ComfyUI's own models this request unloaded before its worker started (comfy_residency.release_native).
+        self.native_release = None
         self.update_request(value)
 
     def note_start(self):
@@ -301,6 +303,10 @@ def service(self, video_busy, worker_restarts, error):
         service = dict(video_busy=bool(video_busy), worker_restarts=worker_restarts)
         if self.start_memory:
             service['memory_at_request_start'] = clean_sample(self.start_memory)
+        released = self.native_release
+        if isinstance(released, dict):
+            service['comfy_models_released'] = {key: released[key] for key in
+                ('models', 'reserved_bytes', 'reserved_after_bytes', 'released') if type(released.get(key)) in (int, bool)}
         # Numbers and fixed words only, taken by the service when it saw the worker end.
         reading = clean_reading(getattr(error, 'exit_reading', None))
         if reading:
diff --git a/freevideo_engine/image_gen/service.py b/freevideo_engine/image_gen/service.py
index a7b9e681..034baecb 100644
--- a/freevideo_engine/image_gen/service.py
+++ b/freevideo_engine/image_gen/service.py
@@ -4,6 +4,7 @@
 from collections import OrderedDict
 from copy import deepcopy
 import json
+import logging
 import math
 import os
 from pathlib import Path
@@ -36,6 +37,15 @@
                             'invalid_media', 'invalid_points', 'too_many_images'))
 
 
+def comfy_server():
+    """ComfyUI's server in this process, or None (tests, the engine's own command line)."""
+    try:
+        from server import PromptServer
+        return PromptServer.instance
+    except (ImportError, AttributeError):
+        return None
+
+
 class WorkerIdleExit(RuntimeError):
     """The worker closed itself after its idle timeout before it answered anything."""
 
@@ -658,6 +668,9 @@ def memory_budget(self, machine):
         from ..background_compile import COMPILE
         from ..gpu_budget import open_bounded
         from ..resident_process import OWNER
+        from ..comfy_residency import native_reclaimable
+        # ComfyUI's own idle models in this process: work() unloads them before the worker starts.
+        native = native_reclaimable(comfy_server())
 
         def read():
             gpu = Gpu(machine.get('gpu_uuid'))
@@ -681,7 +694,7 @@ def read():
                     # The worker still checks live capacity before inference.
                     return total
                 credit = sum(size for pid, size in rows.items() if pid in owned)
-                return min(total, total - used + credit)
+                return min(total, total - used + credit + native)
             finally:
                 gpu.close()
 
@@ -878,6 +891,13 @@ def work(self, root, machine):
                 raise BlockingIOError('busy_video')
             resident_process.OWNER.stop_prewarm()
             IDLE.stop()
+            from ..comfy_residency import release_native
+            released = release_native(comfy_server())
+            if released is not None:
+                logging.info('[FreeVideo] Unloaded ComfyUI models before the picture: %s', released)
+                with self.mutex:
+                    if self.context is not None:
+                        self.context.native_release = released
             with runtime_lock(Path(root) / 'engine.lock', inherit=False) as descriptor:
                 try:
                     if self.session_stop.is_set():
diff --git a/freevideo_engine/prompt_vlm/service.py b/freevideo_engine/prompt_vlm/service.py
index b8f6bee0..c5cbec57 100644
--- a/freevideo_engine/prompt_vlm/service.py
+++ b/freevideo_engine/prompt_vlm/service.py
@@ -402,6 +402,9 @@ def work(self, root, machine, action, value):
                 OWNER.stop_prewarm()
                 from ..encoder_prewarm import IDLE
                 IDLE.stop()
+                from ..comfy_residency import release_native
+                from ..image_gen.service import comfy_server
+                release_native(comfy_server())
             with runtime_lock(Path(root) / 'engine.lock', inherit=False) as descriptor:
                 self.check()
                 if action == 'install':

From fd0d907e2afd5cf3a99fd19f52980abc54fb7815 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 19:18:07 +0000
Subject: [PATCH 02/52] Keep pictures and prompt rewrites going when the
 ComfyUI unload fails

The early unload of idle ComfyUI models only frees memory ahead of time; the
request's own memory check still decides. An exception there is now logged and
the request continues.
---
 freevideo_engine/image_gen/service.py  | 6 +++++-
 freevideo_engine/prompt_vlm/service.py | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/freevideo_engine/image_gen/service.py b/freevideo_engine/image_gen/service.py
index 034baecb..3ff148ff 100644
--- a/freevideo_engine/image_gen/service.py
+++ b/freevideo_engine/image_gen/service.py
@@ -892,7 +892,11 @@ def work(self, root, machine):
             resident_process.OWNER.stop_prewarm()
             IDLE.stop()
             from ..comfy_residency import release_native
-            released = release_native(comfy_server())
+            try:
+                released = release_native(comfy_server())
+            except Exception:  # only frees memory early; the picture's own budget still decides
+                logging.warning('[FreeVideo] Could not unload ComfyUI models before the picture', exc_info=True)
+                released = None
             if released is not None:
                 logging.info('[FreeVideo] Unloaded ComfyUI models before the picture: %s', released)
                 with self.mutex:
diff --git a/freevideo_engine/prompt_vlm/service.py b/freevideo_engine/prompt_vlm/service.py
index c5cbec57..423248fa 100644
--- a/freevideo_engine/prompt_vlm/service.py
+++ b/freevideo_engine/prompt_vlm/service.py
@@ -1,6 +1,7 @@
 """Optional rewrite and ask jobs; prompts, questions and answers stay in memory, never in job reports."""
 import atexit
 import json
+import logging
 import os
 from pathlib import Path
 import queue
@@ -404,7 +405,10 @@ def work(self, root, machine, action, value):
                 IDLE.stop()
                 from ..comfy_residency import release_native
                 from ..image_gen.service import comfy_server
-                release_native(comfy_server())
+                try:
+                    release_native(comfy_server())
+                except Exception:  # only frees memory early; the load's own free-memory check still decides
+                    logging.warning('[FreeVideo] Could not unload ComfyUI models before the prompt model', exc_info=True)
             with runtime_lock(Path(root) / 'engine.lock', inherit=False) as descriptor:
                 self.check()
                 if action == 'install':

From 84044039f9c4cf28109fb10e4e2962e38e5f4e09 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 21 Oct 2026 02:27:55 +0000
Subject: [PATCH 03/52] Keep the decoder's converted streamed layers in RAM
 between clips when memory allows

---
 freevideo_engine/decode.py           |  3 +-
 freevideo_engine/offload.py          |  8 +++
 freevideo_engine/streamed_weights.py | 79 +++++++++++++++++++++++++++-
 3 files changed, 88 insertions(+), 2 deletions(-)

diff --git a/freevideo_engine/decode.py b/freevideo_engine/decode.py
index 7ed5a3e5..3f2ca806 100644
--- a/freevideo_engine/decode.py
+++ b/freevideo_engine/decode.py
@@ -72,7 +72,8 @@ def phase(name):
             from .streamed_weights import SafetensorLayers
             weight_source = SafetensorLayers((Path(base)/'vae').glob('*.safetensors'),
                 [f'decoder.transformer_blocks.{index}.' for index in range(count, layers)],
-                intermediate_dtype=torch.float32 if linear_compute_cache else None)
+                intermediate_dtype=torch.float32 if linear_compute_cache else None,
+                keep_converted=True)
         vae, compute_cache_metrics = load_video_decoder(base, resident_blocks=count, weight_source=weight_source,
                                                        linear_fp16=linear_compute_cache)
     vae.eval().requires_grad_(False)
diff --git a/freevideo_engine/offload.py b/freevideo_engine/offload.py
index 085db769..335ab91b 100644
--- a/freevideo_engine/offload.py
+++ b/freevideo_engine/offload.py
@@ -905,6 +905,11 @@ def stats(self):
                 'host_view_hits': getattr(self.weight_source, 'host_view_hits', 0) - self.host_view_hits_start,
                 'host_view_hit_bytes': getattr(self.weight_source, 'host_view_hit_bytes', 0) - self.host_view_hit_bytes_start,
                 'host_view_released': getattr(self.weight_source, 'host_view_released', 0),
+                # Converted layers kept in RAM for the clips still to come.
+                'converted_layer_count': len(getattr(self.weight_source, 'converted', None) or {}),
+                'converted_bytes': getattr(self.weight_source, 'converted_bytes', 0),
+                'converted_hits': getattr(self.weight_source, 'converted_hits', 0),
+                'converted_refused': getattr(self.weight_source, 'converted_refused', 0),
                 # Direct reads kept in the file cache between steps and those passing through.
                 'cache_kept_layer_count': len(getattr(self.weight_source, 'cache_kept', None) or {}),
                 'cache_kept_bytes': getattr(self.weight_source, 'cache_kept_bytes', 0),
@@ -950,6 +955,9 @@ def close(self):
         self.cached.clear()
         self.cache_candidates.clear()
         self.slots.clear()
+        release = getattr(self.weight_source, 'release_converted', None)
+        if release is not None:
+            release()
         self.closed = True
 
     def __enter__(self):
diff --git a/freevideo_engine/streamed_weights.py b/freevideo_engine/streamed_weights.py
index af23e448..36e172f0 100644
--- a/freevideo_engine/streamed_weights.py
+++ b/freevideo_engine/streamed_weights.py
@@ -383,6 +383,43 @@ def _low_page_priority(enabled):
             swap(previous)
 
 
+# Converted decoder layers are private copies and charge commit, but they stand
+# in for the clean file pages the streamed reads would otherwise keep cycling
+# through the standby list, so the floor left to the rest of the system is
+# smaller than for views. Admission is re-checked at every layer.
+CONVERTED_RESERVE = int(1.5 * 2**30)
+
+
+def _cgroup_headroom(mount='/sys/fs/cgroup', membership='/proc/self/cgroup'):
+    """Room left under this process's cgroup v2 memory limit, or None without one.
+
+    Private copies count against the limit while clean file pages do not, so
+    only anonymous, shared and kernel memory is taken as used.
+    """
+    try:
+        root = Path(mount)
+        for line in Path(membership).read_text(encoding='utf-8').splitlines():
+            if line.startswith('0::'):
+                root = root / line[3:].lstrip('/')
+        limit = (root / 'memory.max').read_text(encoding='utf-8').strip()
+        if limit == 'max':
+            return None
+        stat = dict(row.split() for row in (root / 'memory.stat').read_text(encoding='utf-8').splitlines())
+        return int(limit) - sum(int(stat.get(name, 0)) for name in ('anon', 'shmem', 'kernel'))
+    except (OSError, ValueError):
+        return None
+
+
+def converted_fits(size, reserve=CONVERTED_RESERVE):
+    """Whether one more converted layer may stay in RAM as a private copy."""
+    from .system import system_memory
+    available = system_memory()['available_bytes']
+    headroom = _cgroup_headroom()
+    if headroom is not None:
+        available = min(available, headroom)
+    return available - size >= reserve
+
+
 def host_view_fits(size, reserve=HOST_VIEW_RESERVE):
     """Whether one more layer may stay in RAM as a read-only file view.
 
@@ -399,11 +436,20 @@ def host_view_fits(size, reserve=HOST_VIEW_RESERVE):
 
 class SafetensorLayers:
     def __init__(self, paths, prefixes, *, intermediate_dtype=None, direct_read=None, host_views=False,
-                 host_view_reserve=HOST_VIEW_RESERVE):
+                 host_view_reserve=HOST_VIEW_RESERVE, keep_converted=False):
         from .system import windows
         self.direct_read = windows() if direct_read is None else direct_read
         self.prefixes = tuple(prefixes)
         self.intermediate_dtype = intermediate_dtype
+        # Layers converted from their checkpoint dtype (the decoder's FP16
+        # Linear values) kept for the layers' next uses. A tile decode streams
+        # the same layers once per clip; converting reads the whole FP32 layer
+        # each time, from disk once the file cache cannot hold them.
+        self.keep_converted = keep_converted and intermediate_dtype is not None
+        self.converted = {}
+        self.converted_bytes = 0
+        self.converted_hits = 0
+        self.converted_refused = 0
         self.files = {}
         self.handle_files = {}
         self.keys = {}
@@ -701,6 +747,25 @@ def placeholders(self, index, path):
                             else torch.empty(shape, dtype=dtype))
         return tensors
 
+    def _keep_converted(self, index, tensors, shared):
+        """Keep this layer's converted tensors if RAM has room, as private copies."""
+        size = sum(value.numel() * value.element_size() for value in tensors.values())
+        with self.cache_lock:
+            if index in self.converted:
+                return
+            if not converted_fits(size):
+                self.converted_refused += 1
+                return
+            # A tensor that needed no conversion may still map the checkpoint.
+            self.converted[index] = {name: value.clone() if name in shared else value
+                                     for name, value in tensors.items()}
+            self.converted_bytes += size
+
+    def release_converted(self):
+        with self.cache_lock:
+            self.converted.clear()
+            self.converted_bytes = 0
+
     def adopt(self, index):
         """Keep a layer that loading just read as views, so its first pass reads no disk.
 
@@ -812,8 +877,16 @@ def read_ahead(self, layouts, pinned):
     @contextmanager
     def layer(self, index, layout):
         from contextlib import ExitStack
+        with self.cache_lock:
+            kept = self.converted.get(index)
+            if kept is not None:
+                self.converted_hits += 1
+        if kept is not None:
+            yield dict(kept)
+            return
         prefix = self.prefixes[index]
         tensors = {}
+        shared = set()
         paths = {self.keys[prefix + name] for _, name, *_ in layout}
         for path in paths:
             self.check(path)
@@ -831,6 +904,10 @@ def layer(self, index, layout):
                     if self.intermediate_dtype is not None:
                         tensor = tensor.to(dtype=self.intermediate_dtype)
                     tensors[name] = tensor.to(dtype=dtype)
+                    if tensors[name] is tensor:
+                        shared.add(name)
+                if self.keep_converted:
+                    self._keep_converted(index, tensors, shared)
                 yield tensors
         finally:
             tensors.clear()

From ae1214165d1bb856e29c0d7e0204ef400e19b511 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 21 Oct 2026 03:11:50 +0000
Subject: [PATCH 04/52] Eight attention heads for the Windows small first pass
 up to 12 s

---
 freevideo_engine/policy.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/freevideo_engine/policy.py b/freevideo_engine/policy.py
index d7ea6248..d11c80c0 100644
--- a/freevideo_engine/policy.py
+++ b/freevideo_engine/policy.py
@@ -98,6 +98,12 @@
 # allocator retry and no sample over the local budget.
 WINDOWS_SMALL_HEAD8_TOKENS = 18144 + 4 * 1008
 WINDOWS_SMALL_HEAD8_FRAMES = 243
+# The same interval for Ada and Blackwell reaches 12.25 s (294 frames): the
+# 672x384x277 first pass of a 1344x768 11.5 s request measured head 4/8 at
+# 22.3/15.5, 19.7/17.6 and 21.6/17.4 s per warm step on an RTX PRO 6000 held to
+# an 8 GB laptop's 6.96 GB budget, 3.50 and 3.87 GiB reserved, no allocator
+# retry. Ampere and the int8 paths keep 243.
+WINDOWS_SMALL_HEAD8_LONG_FRAMES = 294
 # Int8 without LoRA reaches full resolution at the same frame count. With the
 # Windows allocator (no expandable segments; its four-head workspace measured
 # 6.15 GiB against 6.18 natively on Windows at the same placement),
@@ -1208,7 +1214,7 @@ def held(group):
         # by moving attention outputs to the host just to widen the group.
         windows_small_head8 = (desktop and not ampere and legs == ['sage2', 'sage2']
                               and effective_tokens is not None
-                              and canvas['frames'] <= WINDOWS_SMALL_HEAD8_FRAMES
+                              and canvas['frames'] <= WINDOWS_SMALL_HEAD8_LONG_FRAMES
                               and effective_tokens <= WINDOWS_SMALL_HEAD8_TOKENS)
         windows_int8_full = (desktop and not lora and legs == ['sage2', 'sage2']
                              and effective_tokens is not None

From d6fc6e6d4779de540566ecbfd65136719fc9a164 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sun, 25 Oct 2026 01:49:31 +0000
Subject: [PATCH 05/52] Keep eight heads on the small first pass for requests
 without LoRA, and bound the decoder cache

Keep the small-first-pass eight-head extension to requests without LoRA, bound the decoder cache by the request RAM budget.

The Windows small first pass takes eight heads up to 12.25 s only when no LoRA is loaded; LoRA requests keep the 243-frame limit. Correct the comment on which paths keep 243.

The decoder's converted-layer cache now also stays inside the request's own RAM budget and reads cgroup limits through the shared hardware helper, so it can neither trip an explicit budget nor raise the peak later plans treat as demonstrated.

Narrow the recorded capability table tolerance to the two moved entries. Add tests for cache release, consumer errors, concurrent first use and re-admission.
---
 freevideo_engine/decode.py           | 15 ++++++++++--
 freevideo_engine/policy.py           |  7 ++++--
 freevideo_engine/streamed_weights.py | 34 +++++++++-------------------
 freevideo_engine/worker.py           |  3 ++-
 4 files changed, 31 insertions(+), 28 deletions(-)

diff --git a/freevideo_engine/decode.py b/freevideo_engine/decode.py
index 3f2ca806..d3c94316 100644
--- a/freevideo_engine/decode.py
+++ b/freevideo_engine/decode.py
@@ -26,7 +26,7 @@ def decode_to_file(latents, audio_latents, out_path, *, base, offload=False, pre
                    preload=False, pin_weights=False, artifacts_dir=None, phase_callback=None,
                    stream_output=False, stream_weights=False, resident_blocks=0, model_cache=None,
                    linear_compute_cache=False, continuation=None, audio_lead_in_callback=None, output_size=None,
-                   hide_tail_frames=0):
+                   hide_tail_frames=0, ram_budget_bytes=None):
     from .continuation import validate_hide_tail
     validate_hide_tail(hide_tail_frames)
     def phase(name):
@@ -70,10 +70,21 @@ def phase(name):
         count = resident_blocks if offload else layers
         if stream_weights:
             from .streamed_weights import SafetensorLayers
+            room = None
+            if ram_budget_bytes is not None:
+                # Converted layers are private memory: keep them inside the request's own
+                # working-memory budget, so they can neither trip an explicit budget nor
+                # lift the peak that later plans take as demonstrated.
+                def room():
+                    import os
+                    from .ram import ProcessMemory
+                    from .system import memory_sample
+                    used = memory_sample(ProcessMemory().sample(os.getpid()))
+                    return ram_budget_bytes - used if type(used) is int and used >= 0 else None
             weight_source = SafetensorLayers((Path(base)/'vae').glob('*.safetensors'),
                 [f'decoder.transformer_blocks.{index}.' for index in range(count, layers)],
                 intermediate_dtype=torch.float32 if linear_compute_cache else None,
-                keep_converted=True)
+                keep_converted=True, converted_room=room)
         vae, compute_cache_metrics = load_video_decoder(base, resident_blocks=count, weight_source=weight_source,
                                                        linear_fp16=linear_compute_cache)
     vae.eval().requires_grad_(False)
diff --git a/freevideo_engine/policy.py b/freevideo_engine/policy.py
index d11c80c0..b1cb74e6 100644
--- a/freevideo_engine/policy.py
+++ b/freevideo_engine/policy.py
@@ -102,7 +102,9 @@
 # 672x384x277 first pass of a 1344x768 11.5 s request measured head 4/8 at
 # 22.3/15.5, 19.7/17.6 and 21.6/17.4 s per warm step on an RTX PRO 6000 held to
 # an 8 GB laptop's 6.96 GB budget, 3.50 and 3.87 GiB reserved, no allocator
-# retry. Ampere and the int8 paths keep 243.
+# retry, all without LoRA. Requests with LoRA, Ampere FP8 and the two Windows
+# int8 paths above the small canvas (windows_int8_full, windows_int8_staged_head8)
+# keep 243.
 WINDOWS_SMALL_HEAD8_LONG_FRAMES = 294
 # Int8 without LoRA reaches full resolution at the same frame count. With the
 # Windows allocator (no expandable segments; its four-head workspace measured
@@ -1214,7 +1216,8 @@ def held(group):
         # by moving attention outputs to the host just to widen the group.
         windows_small_head8 = (desktop and not ampere and legs == ['sage2', 'sage2']
                               and effective_tokens is not None
-                              and canvas['frames'] <= WINDOWS_SMALL_HEAD8_LONG_FRAMES
+                              and (canvas['frames'] <= WINDOWS_SMALL_HEAD8_FRAMES
+                                   or (not lora and canvas['frames'] <= WINDOWS_SMALL_HEAD8_LONG_FRAMES))
                               and effective_tokens <= WINDOWS_SMALL_HEAD8_TOKENS)
         windows_int8_full = (desktop and not lora and legs == ['sage2', 'sage2']
                              and effective_tokens is not None
diff --git a/freevideo_engine/streamed_weights.py b/freevideo_engine/streamed_weights.py
index 36e172f0..2748e892 100644
--- a/freevideo_engine/streamed_weights.py
+++ b/freevideo_engine/streamed_weights.py
@@ -390,31 +390,17 @@ def _low_page_priority(enabled):
 CONVERTED_RESERVE = int(1.5 * 2**30)
 
 
-def _cgroup_headroom(mount='/sys/fs/cgroup', membership='/proc/self/cgroup'):
-    """Room left under this process's cgroup v2 memory limit, or None without one.
+def converted_fits(size, reserve=CONVERTED_RESERVE, room=None):
+    """Whether one more converted layer may stay in RAM as a private copy.
 
-    Private copies count against the limit while clean file pages do not, so
-    only anonymous, shared and kernel memory is taken as used.
+    ``room`` is what the request's own RAM budget still allows, when it has one.
     """
-    try:
-        root = Path(mount)
-        for line in Path(membership).read_text(encoding='utf-8').splitlines():
-            if line.startswith('0::'):
-                root = root / line[3:].lstrip('/')
-        limit = (root / 'memory.max').read_text(encoding='utf-8').strip()
-        if limit == 'max':
-            return None
-        stat = dict(row.split() for row in (root / 'memory.stat').read_text(encoding='utf-8').splitlines())
-        return int(limit) - sum(int(stat.get(name, 0)) for name in ('anon', 'shmem', 'kernel'))
-    except (OSError, ValueError):
-        return None
-
-
-def converted_fits(size, reserve=CONVERTED_RESERVE):
-    """Whether one more converted layer may stay in RAM as a private copy."""
+    from .hardware import cgroup_memory
     from .system import system_memory
+    if room is not None and room < size:
+        return False
     available = system_memory()['available_bytes']
-    headroom = _cgroup_headroom()
+    headroom = cgroup_memory()['reclaimable_available_bytes']
     if headroom is not None:
         available = min(available, headroom)
     return available - size >= reserve
@@ -436,7 +422,7 @@ def host_view_fits(size, reserve=HOST_VIEW_RESERVE):
 
 class SafetensorLayers:
     def __init__(self, paths, prefixes, *, intermediate_dtype=None, direct_read=None, host_views=False,
-                 host_view_reserve=HOST_VIEW_RESERVE, keep_converted=False):
+                 host_view_reserve=HOST_VIEW_RESERVE, keep_converted=False, converted_room=None):
         from .system import windows
         self.direct_read = windows() if direct_read is None else direct_read
         self.prefixes = tuple(prefixes)
@@ -446,6 +432,7 @@ def __init__(self, paths, prefixes, *, intermediate_dtype=None, direct_read=None
         # the same layers once per clip; converting reads the whole FP32 layer
         # each time, from disk once the file cache cannot hold them.
         self.keep_converted = keep_converted and intermediate_dtype is not None
+        self.converted_room = converted_room
         self.converted = {}
         self.converted_bytes = 0
         self.converted_hits = 0
@@ -753,7 +740,8 @@ def _keep_converted(self, index, tensors, shared):
         with self.cache_lock:
             if index in self.converted:
                 return
-            if not converted_fits(size):
+            room = self.converted_room() if self.converted_room is not None else None
+            if (self.converted_room is not None and room is None) or not converted_fits(size, room=room):
                 self.converted_refused += 1
                 return
             # A tensor that needed no conversion may still map the checkpoint.
diff --git a/freevideo_engine/worker.py b/freevideo_engine/worker.py
index 9b6950fe..ac812592 100644
--- a/freevideo_engine/worker.py
+++ b/freevideo_engine/worker.py
@@ -659,7 +659,8 @@ def keep_audio_lead_in(value):
                                      **({'continuation': continuation} if continuation is not None else {}),
                                      **({'audio_lead_in_callback': keep_audio_lead_in}
                                         if continuation is not None and continuation_data is not None else {}),
-                                     model_cache=resident, phase_callback=decode_phase, output_size=output_size, **decoder))
+                                     model_cache=resident, phase_callback=decode_phase, output_size=output_size,
+                                     ram_budget_bytes=request.get('ram_budget_bytes'), **decoder))
         if continuable and continuation_data is not None:
             if continuation is not None:
                 # Every continuation of a film carries its first frame on, used or not: a later

From c622ae1e247b9a69f6d0e00acbd60ef278815a48 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sun, 25 Oct 2026 23:48:33 +0000
Subject: [PATCH 06/52] Keep converted decoder layers across requests in the
 resident process

A resident process now holds the converted decoder layers in a store that outlives one decode, so the next request reads no layer from disk. The store belongs to one checkpoint identity, and is released when host memory is short, when models are made room for, and on clear.
---
 freevideo_engine/decode.py           |  3 +-
 freevideo_engine/resident_models.py  |  8 ++++++
 freevideo_engine/streamed_weights.py | 43 +++++++++++++++++++++++++++-
 3 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/freevideo_engine/decode.py b/freevideo_engine/decode.py
index d3c94316..50832b08 100644
--- a/freevideo_engine/decode.py
+++ b/freevideo_engine/decode.py
@@ -84,7 +84,8 @@ def room():
             weight_source = SafetensorLayers((Path(base)/'vae').glob('*.safetensors'),
                 [f'decoder.transformer_blocks.{index}.' for index in range(count, layers)],
                 intermediate_dtype=torch.float32 if linear_compute_cache else None,
-                keep_converted=True, converted_room=room)
+                keep_converted=True, converted_room=room,
+                converted_store=getattr(model_cache, 'converted_store', None))
         vae, compute_cache_metrics = load_video_decoder(base, resident_blocks=count, weight_source=weight_source,
                                                        linear_fp16=linear_compute_cache)
     vae.eval().requires_grad_(False)
diff --git a/freevideo_engine/resident_models.py b/freevideo_engine/resident_models.py
index ac675357..185f01cc 100644
--- a/freevideo_engine/resident_models.py
+++ b/freevideo_engine/resident_models.py
@@ -152,6 +152,9 @@ def __init__(self):
         self.gpu_reserve = 0
         self.ram_budget = None
         self.decisions = []
+        from .streamed_weights import ConvertedStore
+        # Converted decoder layers streamed from the checkpoint; rebuilt on demand.
+        self.converted_store = ConvertedStore()
         # Set by a request that can read the whole device: bytes no process
         # holds, and the growth reserve that request keeps out of them. The
         # planning budget already excludes that reserve; the device reading
@@ -241,6 +244,7 @@ def declined(why):
         return True
 
     def clear(self, reason='Request failed or session configuration changed'):
+        self.converted_store.clear()
         for role in list(self.entries):
             self.drop(role, reason)
         gc.collect()
@@ -271,6 +275,8 @@ def settle(self, pinned=0):
         a retained copy left no room to pin and sampling took 95 s instead of
         38 s. Otherwise the engine goes as it did with one worker per request.
         """
+        if not self.ram_fits(8*GiB + int(pinned)):
+            self.converted_store.clear()
         for role in ('engine', 'encoder'):
             if role in self.entries and not self.ram_fits(8*GiB + int(pinned)):
                 self.drop(role, 'Retained weights leave no host room for the next request')
@@ -331,6 +337,8 @@ def available():
                 room = min(room, max(0, ceiling - torch.cuda.memory_allocated() - reserve))
             return room
         before = available()
+        if not self.ram_fits(ram_need):
+            self.converted_store.clear()
         # Once conditioning is ready the current video cannot use the encoder
         # again. Reclaim its speculative weights before a VAE needed later in
         # this very request, regardless of how recently preloading touched it.
diff --git a/freevideo_engine/streamed_weights.py b/freevideo_engine/streamed_weights.py
index 2748e892..92437a74 100644
--- a/freevideo_engine/streamed_weights.py
+++ b/freevideo_engine/streamed_weights.py
@@ -420,10 +420,41 @@ def host_view_fits(size, reserve=HOST_VIEW_RESERVE):
     return available - size >= reserve
 
 
+class ConvertedStore:
+    """Converted decoder layers that outlive one decode, for a resident process.
+
+    Entries belong to one checkpoint identity; a different one empties the store.
+    """
+
+    def __init__(self):
+        self.identity = None
+        self.layers = {}
+        self.lock = threading.Lock()
+
+    def bind(self, identity):
+        with self.lock:
+            if identity != self.identity:
+                self.layers = {}
+                self.identity = identity
+            return self.layers
+
+    def size(self):
+        with self.lock:
+            return sum(value.numel() * value.element_size()
+                       for tensors in list(self.layers.values()) for value in tensors.values())
+
+    def clear(self):
+        with self.lock:
+            self.layers.clear()
+            self.identity = None
+
+
 class SafetensorLayers:
     def __init__(self, paths, prefixes, *, intermediate_dtype=None, direct_read=None, host_views=False,
-                 host_view_reserve=HOST_VIEW_RESERVE, keep_converted=False, converted_room=None):
+                 host_view_reserve=HOST_VIEW_RESERVE, keep_converted=False, converted_room=None,
+                 converted_store=None):
         from .system import windows
+        self.converted_store = None
         self.direct_read = windows() if direct_read is None else direct_read
         self.prefixes = tuple(prefixes)
         self.intermediate_dtype = intermediate_dtype
@@ -494,6 +525,14 @@ def __init__(self, paths, prefixes, *, intermediate_dtype=None, direct_read=None
                         self.byte_ranges[key] = (8 + length + start, end - start,
                                                 spec['dtype'], tuple(spec['shape']))
             self.check(path)
+        if converted_store is not None and self.keep_converted:
+            # A resident process keeps the layers for its next request; they are
+            # served only while the checkpoint files, layers and dtype are unchanged.
+            self.converted = converted_store.bind(
+                (tuple(sorted((str(path), identity) for path, identity in self.files.items())),
+                 self.prefixes, str(self.intermediate_dtype)))
+            self.converted_bytes = converted_store.size()
+            self.converted_store = converted_store
 
     @staticmethod
     def identity(path):
@@ -750,6 +789,8 @@ def _keep_converted(self, index, tensors, shared):
             self.converted_bytes += size
 
     def release_converted(self):
+        if self.converted_store is not None:
+            return  # owned by the resident process, which releases it under memory pressure
         with self.cache_lock:
             self.converted.clear()
             self.converted_bytes = 0

From 9e426633be2cf76ce6866d5e1bd0b02169ce340a Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 19:26:12 +0000
Subject: [PATCH 07/52] Continued parts may be five seconds, with fewer parts
 per video

A part that continues a video is now at least 5 s instead of 10 s. The
planner still prefers continuing parts of 10 s or longer and falls back to
parts of 5 s or longer only when the length or this device's single-run
limit leaves no other way, so lengths such as 15-19 s and 29 s are no
longer refused as unsplittable and devices that cannot make 10 s at once
can continue videos.

A video with a continuing part shorter than 10 s has at most 4 parts; with
the first-frame reference, or when every continuing part is 10 s or
longer, it keeps 8. The planner, chain store, runner, ComfyUI chain node,
Agent and editor all read these numbers from one shared file
(web/chain_rules.js), and the runner and Agent refuse a video with too
many short parts with a matching error code.

Editor:
- A new continuation starts at 5 s on Mac and on devices that
cannot make 10 s at once, and at 10 s otherwise; dragging a video's end
continues it by at least 5 s.
- Requests the backend would refuse (too many parts, too many short
parts, parts too short) are blocked before they are sent, with the
same message.
- The model gains a setter for a continuation's length that moves later
planned parts with it and checks the whole video against the limits.

The tutorial, how-to page, Agent guide and Agent documentation describe
the new limits.
---
 ...77\347\224\250\350\257\264\346\230\216.md" |   2 +-
 freevideo_engine/agent/drama.py               |   8 +-
 freevideo_engine/agent/editor_runtime.py      |   2 +-
 freevideo_engine/agent/errors.py              |   3 +
 freevideo_engine/agent/guide.py               |  17 +--
 freevideo_engine/agent/jobs.py                |  46 +++++---
 freevideo_engine/agent/mcp.py                 |   2 +-
 freevideo_engine/agent/productions.py         |   2 +-
 freevideo_engine/chain_plan.py                | 109 +++++++++++++-----
 freevideo_engine/chain_runner.py              |  90 ++++++++++-----
 freevideo_engine/chain_store.py               |   4 +-
 freevideo_engine/comfy_chain.py               |  15 ++-
 web/chain_rules.js                            |   1 +
 web/editor.js                                 |  30 +++--
 web/editor_genbar.js                          |   2 +-
 web/editor_model.js                           | 108 +++++++++++++++--
 web/editor_store.js                           |  14 ++-
 web/editor_tracks.js                          |   7 +-
 web/health.js                                 |   2 +-
 web/howto.js                                  |   3 +-
 web/length_plan.js                            |   2 +-
 web/tutorial_book_content.js                  |   8 +-
 22 files changed, 350 insertions(+), 127 deletions(-)
 create mode 100644 web/chain_rules.js

diff --git "a/docs/zh-CN/\344\275\277\347\224\250\350\257\264\346\230\216.md" "b/docs/zh-CN/\344\275\277\347\224\250\350\257\264\346\230\216.md"
index 03fb88e0..dcc7dfd2 100644
--- "a/docs/zh-CN/\344\275\277\347\224\250\350\257\264\346\230\216.md"
+++ "b/docs/zh-CN/\344\275\277\347\224\250\350\257\264\346\230\216.md"
@@ -46,7 +46,7 @@
 
 ### 限制
 
-- 两种做法一样，一条视频最多 8 段（第一段加 7 次接着生成）；创作面板里时长最多填 60 秒。接续的每一段至少 10 秒，整条约 110 秒。剪辑视图里逐段生成同样适用。段数越多，衔接处越容易出现变化，适合切换镜头处，可直接切镜头，用对应的参考图开始新的一段。
+- 两种做法一样，一条视频最多 8 段（第一段加 7 次接着生成），有短于 10 秒的段时最多 4 段；创作面板里时长最多填 60 秒。接续的每一段至少 5 秒，每段都是 10 秒以上时整条约 110 秒。剪辑视图里逐段生成同样适用。段数越多，衔接处越容易出现变化，适合切换镜头处，可直接切镜头，用对应的参考图开始新的一段。
 - 接着生成使用轻量档，需要 NVIDIA 显卡或 Mac，也不能和“继续二采”同时使用。
 - 单次生成的最长时长随画幅和显卡而不同，在创作面板的“可生成范围”中可查看各尺寸的最长时长和预计用时。
 - 分段生成同样需要 NVIDIA 显卡或 Mac。
diff --git a/freevideo_engine/agent/drama.py b/freevideo_engine/agent/drama.py
index a34f83ed..ac0b32b9 100644
--- a/freevideo_engine/agent/drama.py
+++ b/freevideo_engine/agent/drama.py
@@ -20,7 +20,7 @@
 import time
 
 from . import spec as specs
-from ..chain_plan import MIN_PART_SECONDS
+from ..chain_plan import CONTINUE_SECONDS
 
 EXAMPLE = {
     'title': '末班车', 'name': 'the-last-train', 'aspect': '9:16', 'quality': 'light',
@@ -451,9 +451,9 @@ def intent(play, shot):
 
 
 def shot_seconds(play, shot):
-    """A shot says its length; else the film does; else 6 s, and 10 s for a shot that continues the one before
-    (a part that continues another video is at least 10 s)."""
-    return shot.get('seconds', play.get('seconds', MIN_PART_SECONDS if shot.get('continue') else 6))
+    """A shot says its length; else the film does; else 6 s, and CONTINUE_SECONDS for a shot that continues the
+    one before (a full continuing part, which keeps the video to the full number of parts)."""
+    return shot.get('seconds', play.get('seconds', CONTINUE_SECONDS if shot.get('continue') else 6))
 
 
 def shot_job(play, shot, index, ref):
diff --git a/freevideo_engine/agent/editor_runtime.py b/freevideo_engine/agent/editor_runtime.py
index b8bbf755..456783fb 100644
--- a/freevideo_engine/agent/editor_runtime.py
+++ b/freevideo_engine/agent/editor_runtime.py
@@ -16,7 +16,7 @@
 # Definition order only; evaluation starts at editor_actions like the page's
 # import does. editor_model and editor_text_model import each other: the
 # module still loading is reached only through a namespace import.
-MODULES = ('editor_picture_fields', 'editor_transport_model', 'editor_audio_model', 'editor_speed_model',
+MODULES = ('chain_rules', 'editor_picture_fields', 'editor_transport_model', 'editor_audio_model', 'editor_speed_model',
            'editor_text_model', 'editor_model', 'editor_room', 'editor_actions', 'editor_generation', 'sampling_effort',
            'chain_support', 'editor_store')
 TIME_LIMIT = 5.0
diff --git a/freevideo_engine/agent/errors.py b/freevideo_engine/agent/errors.py
index dd4dccc4..32303046 100644
--- a/freevideo_engine/agent/errors.py
+++ b/freevideo_engine/agent/errors.py
@@ -67,6 +67,7 @@
     'chain_missing': (409, True, 'The saved chain receipt is unavailable.', 'Restore the chain receipt and retry resume, or submit a new job.'),
     'join_failed': (409, True, 'The generated blocks could not be joined; completed blocks are retained.', 'POST /freevideo/agent/v1/jobs/{id}/resume to retry joining the completed blocks.'),
     'chain_too_long': (422, False, 'One continuous shot can have up to 8 parts. Make it shorter.', 'Submit a new job with a smaller seconds, or cut to a new shot with a new job without continue_from; continue_from counts the parts of the video it continues.'),
+    'chain_short_parts': (422, False, 'With a part shorter than 10 seconds, this video can have up to 4 parts. Make each part at least 10 seconds long, or use fewer parts.', 'Submit a new job whose continuing parts are at least 10 seconds, with fewer parts, or with first_frame_reference true; continue_from counts the parts of the video it continues.'),
     'chain_rejected': (409, False, 'The continuous backend rejected this generation.', 'Read GET /freevideo/agent/v1/capabilities and submit a supported generation request.'),
     'invalid_wait': (422, False, 'wait must be a finite nonnegative number of seconds.', 'Use wait=0 or wait=25; larger valid values are clamped to 25 seconds.'),
     'invalid_resume': (422, False, 'resume accepts an empty object or an optional ref only.', 'Send {} or {"ref":"resume-1"}; submit a new job to change generation parameters.'),
@@ -302,6 +303,7 @@ def safe_details(value):
     'invalid_dimensions': '图片尺寸超出了支持的范围',
     'too_many_images': '参考图片数量超过了支持的范围',
     'chain_too_long': '接续后的视频超过了支持的段数',
+    'chain_short_parts': '有短于 10 秒的段时，接续后的视频超过了支持的段数',
     'chain_rejected': '生成服务无法使用这组参数',
     'generation_failed': '生成没有完成',
     'internal_error': '没有完成',
@@ -350,6 +352,7 @@ def safe_details(value):
     'invalid_dimensions': 'The picture size is outside the supported range',
     'too_many_images': 'There are more reference pictures than supported',
     'chain_too_long': 'The continued video has more parts than supported',
+    'chain_short_parts': 'With a part shorter than 10 seconds, the continued video has more parts than supported',
     'chain_rejected': 'The generation service cannot use these settings',
     'generation_failed': 'Generation did not finish',
     'internal_error': 'Did not finish',
diff --git a/freevideo_engine/agent/guide.py b/freevideo_engine/agent/guide.py
index 2a4268da..a61ea514 100644
--- a/freevideo_engine/agent/guide.py
+++ b/freevideo_engine/agent/guide.py
@@ -99,7 +99,7 @@
     'timing': [
         'Single-block frames are 24 fps on a 17n+5 grid (6 s -> 6.583 s, 10 s -> 10.125 s). '
         'Under 30 s defaults to one generation when the device supports this size and quality; unknown limits use 15 s. '
-        'Otherwise it uses as few parts as possible, each at least 10 s; how many depends on how long this computer can generate in one run, and the parts continue and join automatically. '
+        'Otherwise it uses as few parts as possible, each continuing part 10 s or longer where the length allows and never under 5 s; how many depends on how long this computer can generate in one run, and the parts continue and join automatically. '
         'Multiple blocks or continue_from need two-pass text generation: quality "light" or "medium" '
         'or sampling.two_pass=true and no preview. Their only media is media.references with at most 3 pictures, '
         'which every continuing part also sees (keeps the same people); first_frame_reference then gives way to them. '
@@ -250,9 +250,10 @@
     'Cut by default. Wherever the film can change shot, make the new shot from the reference pictures it should '
     'have (cast cards, scene pictures) instead of continuing the previous video. Continue a video only for a '
     'long take that cannot be cut, an action that must stay unbroken, or sound that must stay unbroken, and '
-    'continuing again and again is not recommended. One video has at most 8 parts (the first and 7 '
-    'continuations), each continued part at least 10 seconds, about 110 seconds in all; filling that is not '
-    'recommended. Past it, cut to a new shot.',
+    'continuing again and again is not recommended. Each continued part is at least 5 seconds. One video has at '
+    'most 8 parts (the first and 7 continuations, about 110 seconds in all) when every continued part is at '
+    'least 10 seconds; with a continued part shorter than 10 seconds it has at most 4 parts, unless '
+    'first_frame_reference is true. Filling that is not recommended. Past it, cut to a new shot.',
     'A question is not a request. When the user asks about progress or status ("is it working?", "what happened?") '
     'answer it in one sentence from what you know or from the job and white-model status, and start nothing; never '
     'use a question as a prompt. When a row carries "whitebox", the user was starting a white-model scene that is '
@@ -287,7 +288,8 @@
     '先用 people（角色图和各自的位置）做出首帧，再用它生成视频。',
     '默认切镜头。能切镜头的地方就切：新镜头直接用对应的参考图（人物卡、场景图）生成，不接上一段视频。'
     '只有不能切镜的长镜头、必须连贯的动作、必须连贯的声音，才接着上一段生成，而且不建议一段接一段地连续接。'
-    '一条视频最多 8 段（第一段加 7 次接着生成），接着生成的每一段至少 10 秒，总长约 110 秒；不建议接满，超过就切镜头。',
+    '接着生成的每一段至少 5 秒。每段都不短于 10 秒时，一条视频最多 8 段（第一段加 7 次接着生成，总长约 110 秒）；'
+    '有短于 10 秒的段时最多 4 段，first_frame_reference 为 true 时除外。不建议接满，超过就切镜头。',
     '问话不是要求。用户问进度或状态（“在做吗”“怎么了”）时，用一句话照实回答，依据是你所知道的、任务和白模的状态，'
     '什么都不要开始；不要把问句当提示词。某条 inbox 带有 whitebox 时，说明用户刚启动了白模场景，'
     '它还在准备或已经失败：照实说是哪一种，再等用户回话。',
@@ -573,8 +575,9 @@ def connection_text(value):
     'before uploading. Unknown fields are rejected and every batch is validated before it is recorded.',
     'POST /plan gives the length supported for the current size and quality. Without continuation, only a '
     'single block can run; unknown device limits use 15 s. Multiple blocks return continuation_unavailable.',
-    'One video has at most 8 parts (60 s in one request). continue_from counts the parts of the video it '
-    'continues; plan and submit refuse a longer one and name the longest seconds that still fits.',
+    'One video has at most 8 parts (60 s in one request), or 4 when a continued part is shorter than 10 s and '
+    'first_frame_reference is not true. continue_from counts the parts of the video it continues; plan and '
+    'submit refuse a longer one and name the longest seconds that still fits.',
     'features in the status reply names what this installation offers; false means not usable now (for example '
     'chain.auto while continuation is false), and a missing name means not offered here.',
 ]
diff --git a/freevideo_engine/agent/jobs.py b/freevideo_engine/agent/jobs.py
index 73da1fd6..80bd5db2 100644
--- a/freevideo_engine/agent/jobs.py
+++ b/freevideo_engine/agent/jobs.py
@@ -187,7 +187,7 @@ def part_prompt_problems(spec, prefix=''):
 
 
 def _continued_part_problem(seconds, chain):
-    """True when a video that continues another has a part the backend refuses, or is under 10 s.
+    """True when a video that continues another has a part the backend refuses, or is under MIN_PART_SECONDS.
 
     The backend compares each part's node input frames (overlap included); a part that
     continues is also at least MIN_PART_SECONDS long.
@@ -232,8 +232,8 @@ def parts_problems(spec, runner, prefix='', *, editor=None, work=None, planned=N
     """
     if spec['kind'] != 'generate' or spec.get('refine_from'):
         return []
-    from ..chain_plan import MIN_PART_SECONDS, PlanError, plan
-    from ..chain_runner import ChainTooLong
+    from ..chain_plan import MIN_PART_SECONDS, PlanError, parts_limit, plan
+    from ..chain_runner import ChainShortPartsTooMany, ChainTooLong
     from ..chain_store import reference
     continued, frames = bool(spec.get('continue_from')), single_frame_limit(spec)
     if editor is None:
@@ -246,40 +246,50 @@ def parts_problems(spec, runner, prefix='', *, editor=None, work=None, planned=N
             return [length_problem(spec['seconds'], continued, prefix, minimum=MIN_PART_SECONDS, frames=frames)]
     if runner is None:
         return []
-    limit = runner.max_parts
-    count = lambda seconds: len(plan(seconds, max_frames=frames, continued=continued)['blocks'])
+    # A video with a continuing part shorter than full_part_frames has fewer parts, unless every part sees the first frame.
+    limit, full = runner.max_parts, runner.full_part_frames
+    short_limit = parts_limit(True, spec.get('first_frame_reference') is True, limit)
+
+    def short_blocks(blocks):
+        return any(block['frames'] < full for index, block in enumerate(blocks) if index or continued)
     try:
         with runner.lock:
             if editor is not None:
-                rows = [dict(id=b['id'], after=reference(b.get('after')), before=reference(b.get('before')))
-                        for b in editor['blocks']]
-                earlier, needed = 0, max(runner._depths(dict(id=None, blocks=rows)).values())
+                rows = [dict(id=b['id'], after=reference(b.get('after')), before=reference(b.get('before')),
+                             inputs=dict(frames=b['frames'])) for b in editor['blocks']]
+                lineage = runner._lineage(dict(id=None, blocks=rows)).values()
+                earlier, needed = 0, max(parts for parts, _ in lineage)
+                short = max((parts for parts, flag in lineage if flag), default=0)
             else:
                 # A source the backend has no record of counts as one part, as it does there.
-                earlier = (runner._work_parts(work, ()) if work else planned or 1) if continued else 0
+                earlier, made_short = ((runner._work_lineage(work, ()) if work else (planned or 1, False))
+                                       if continued else (0, False))
                 needed = earlier + len(chain['blocks'])
+                short = needed if made_short or short_blocks(chain['blocks']) else 0
     except (ValueError, KeyError, TypeError):
         return []  # Not a chain the backend accepts; it says why when the chain is created.
-    if needed <= limit:
+    if needed <= limit and short <= short_limit:
         return []
+    error = ChainTooLong(needed, limit) if needed > limit else ChainShortPartsTooMany(short, short_limit)
     if editor is not None:
-        problem, got = schema.diagnostic(prefix + '/target', 'a range that takes at most %d parts' % limit, None), '%d parts' % needed
+        problem, got = schema.diagnostic(prefix + '/target', 'a range that takes at most %d parts' % error.limit, None), '%d parts' % error.parts
     else:
         # A length the planner refuses does not fit; a part that continues a video is at least MIN_PART_SECONDS.
-        def parts(seconds):
+        def fits(seconds):
             try:
-                return count(seconds)
+                blocks = plan(seconds, max_frames=frames, continued=continued)['blocks']
             except ValueError:
-                return limit + 1
+                return False
+            return earlier + len(blocks) <= (short_limit if made_short or short_blocks(blocks) else limit)
         shortest = MIN_PART_SECONDS if continued else 2
-        fit = next((s for s in range(int(spec['seconds']), shortest - 1, -1) if earlier + parts(s) <= limit), None)
+        fit = next((s for s in range(int(spec['seconds']), shortest - 1, -1) if fits(s)), None)
         if fit is None:
-            problem = schema.diagnostic(prefix + '/continue_from', 'a video of fewer than %d parts' % limit, None)
+            problem = schema.diagnostic(prefix + '/continue_from', 'a video of fewer than %d parts' % error.limit, None)
             got = 'a video of %d parts' % earlier
         else:
             problem, got = schema.diagnostic(prefix + '/seconds', 'at most %d' % fit, spec['seconds']), None
     message = problem['message'] if got is None else problem['message'].replace('received None', 'received ' + got)
-    return [dict(problem, got=got or problem['got'], message='%s %s' % (ChainTooLong(needed, limit), message))]
+    return [dict(problem, got=got or problem['got'], message='%s %s' % (error, message))]
 
 
 def continuation_unavailable():
@@ -1635,7 +1645,7 @@ def start_chain(self, row, *, payload=None, resume=False):
             except ChainTooLong as error:
                 # Submit and plan refuse this up front; a source that was still being made can only be counted here.
                 row['resume_pending'] = False
-                self.finish(row, 'failed', error=errors.build('chain_too_long', validation=True, message=str(error)))
+                self.finish(row, 'failed', error=errors.build(error.code, validation=True, message=str(error)))
                 return
             except (PlanError, ChainPartTooShort) as error:
                 row['resume_pending'] = False
diff --git a/freevideo_engine/agent/mcp.py b/freevideo_engine/agent/mcp.py
index ff1f1815..ee5836aa 100644
--- a/freevideo_engine/agent/mcp.py
+++ b/freevideo_engine/agent/mcp.py
@@ -49,7 +49,7 @@ def tool_list():
         dict(name='freevideo_prompt_guide', title='H3 prompt guide', description='How to write prompts: sections, shots and cuts, camera motion, dialogue, references, short-drama tips, and a full example.', annotations=read),
         dict(name='freevideo_schema', title='Job JSON Schemas', description='JSON Schemas of every job kind and of image edit recipes.', annotations=read),
         dict(name='freevideo_plan', title='Plan a job', description="Validate a job without running it: actual frames/seconds, sampling passes, warnings and a time estimate from this computer's history. Same fields as freevideo_generate.", annotations=read),
-        dict(name='freevideo_generate', title='Generate a video', description='Generate one video from an H3 prompt, up to 60 seconds. Under 30 s defaults to one generation if the device supports this size and quality; unknown limits use 15 s. Otherwise the video is cut into as few parts as possible, each at least 10 s, and how many parts depends on how long this computer can generate in one run; the parts continue and join automatically. Prefer a new shot with its reference pictures wherever the film can cut; continue only a take, action or sound that must stay unbroken. Use this for any single video, also after freevideo_enhance_prompt; the drama tools are only for a film of several separately chosen shots. Optionally from first/last frames or references (files, local paths, or frames of earlier jobs). Returns the job; with wait, its result (video path and URL).', annotations=write),
+        dict(name='freevideo_generate', title='Generate a video', description='Generate one video from an H3 prompt, up to 60 seconds. Under 30 s defaults to one generation if the device supports this size and quality; unknown limits use 15 s. Otherwise the video is cut into as few parts as possible, each continuing part 10 s or longer where the length allows and never under 5 s, and how many parts depends on how long this computer can generate in one run; the parts continue and join automatically. Prefer a new shot with its reference pictures wherever the film can cut; continue only a take, action or sound that must stay unbroken. Use this for any single video, also after freevideo_enhance_prompt; the drama tools are only for a film of several separately chosen shots. Optionally from first/last frames or references (files, local paths, or frames of earlier jobs). Returns the job; with wait, its result (video path and URL).', annotations=write),
         dict(name='freevideo_generate_image', title='Generate a picture', description='Generate a picture from a prompt; with images, change or combine input pictures; with people, make a first frame with them near the places you say, in the scene from scene_image or the prompt. The result is an input file to use as a first frame, as a reference, or in images again.', annotations=write),
         dict(name='freevideo_submit_batch', title='Submit a storyboard', description='Submit several jobs at once. Each row is a job object with "kind" (generate default, assemble, vlm, enhance, image) and an optional "ref"; later rows use "@ref" wherever a job id is expected (from_job, after, clips, refine_from). FreeVideo runs them in dependency order.', annotations=write),
         dict(name='freevideo_job', title='Job status', description='Status, progress, result or error of a job.', annotations=read),
diff --git a/freevideo_engine/agent/productions.py b/freevideo_engine/agent/productions.py
index 6ee2c115..68345481 100644
--- a/freevideo_engine/agent/productions.py
+++ b/freevideo_engine/agent/productions.py
@@ -347,7 +347,7 @@ def _material(self, state, *, local=True):
                 continue
             if continued or shot['continues']:
                 # The same length rule as at submission, with this computer's single-run limit rather than the
-                # 15 s default: a shot that cannot be cut into parts of at least 10 s is refused here instead of
+                # 15 s default: a shot that cannot be cut into parts of at least 5 s is refused here instead of
                 # starting a film in which that shot never gets a job. A shot not yet submitted carries no parent.
                 try:
                     pinned = spec.normalize(dict(item, continue_from=dict(from_job=placeholder)), port=self.jobs.port)
diff --git a/freevideo_engine/chain_plan.py b/freevideo_engine/chain_plan.py
index 5eb36f56..13289ecf 100644
--- a/freevideo_engine/chain_plan.py
+++ b/freevideo_engine/chain_plan.py
@@ -5,20 +5,47 @@
 cannot do at once, are cut into blocks that continue one another. A block
 length given explicitly also cuts a video under 30 s.
 """
+import json
 import math
+from pathlib import Path
 
 from .geometry import geometry
 
 FPS, UNIT, OVERLAP = 24, 17, 22
 SINGLE_SECONDS, BLOCK_SECONDS, SHORTEST_BLOCK = 30, 15, 5
-# A part that continues another is at least this long (the first part is not held to it).
-MIN_PART_SECONDS = 10
-MIN_PART_FRAMES = geometry(seconds=MIN_PART_SECONDS)['frames']
+# The limits on continuing parts, shared with the page (web/chain_rules.js: one JSON object) so that both apply
+# the same numbers.
+RULES = json.loads((Path(__file__).resolve().parents[1] / 'web' / 'chain_rules.js').read_text(encoding='utf-8')
+                   .partition('=')[2].strip().removesuffix(';'))
+# A part that continues another is at least MIN_PART_SECONDS (the first part is not held to it). A video with a
+# continuing part shorter than FULL_PART_SECONDS has at most SHORT_MAX_PARTS parts, or MAX_PARTS with the
+# first-frame reference; every other video has at most MAX_PARTS.
+MIN_PART_SECONDS, FULL_PART_SECONDS = RULES['min_part_seconds'], RULES['full_part_seconds']
+MAX_PARTS, SHORT_MAX_PARTS = RULES['max_parts'], RULES['short_max_parts']
+# The length a new continuation starts with, and its length on devices that cannot continue with a full part.
+CONTINUE_SECONDS, SHORT_CONTINUE_SECONDS = RULES['continue_seconds'], RULES['short_continue_seconds']
+
+
+def part_frames(seconds):
+    """The fewest frames a continuing block of `seconds` whole seconds asks for. Each block takes the shortest step
+    that reaches its whole second, so a block after another may ask for up to UNIT - 1 frames fewer than the same
+    length on its own (5 s alone is 158 frames, after another part 141)."""
+    return OVERLAP + UNIT * math.ceil((FPS * seconds - (UNIT - 1)) / UNIT)
+
+
+# Continuing blocks below MIN_PART_FRAMES are too short; below FULL_PART_FRAMES they are short parts.
+MIN_PART_FRAMES, FULL_PART_FRAMES = part_frames(MIN_PART_SECONDS), part_frames(FULL_PART_SECONDS)
 SHORTEST_FIRST = 2  # whole seconds: what the first part keeps when the continuing parts take the rest
 MAX_SECONDS = 7200
 MAX_BLOCKS = MAX_SECONDS // SHORTEST_BLOCK
 
 
+def parts_limit(short, first_frame=False, max_parts=MAX_PARTS):
+    """The most parts one video may have: fewer when one of its continuing parts is short, unless every
+    continuing part also sees the first frame."""
+    return max_parts if not short or first_frame else min(max_parts, SHORT_MAX_PARTS)
+
+
 class PlanError(ValueError):
     def __init__(self, code, message):
         super().__init__(message)
@@ -35,14 +62,41 @@ def _first_frames(seconds):
     return geometry(seconds=seconds)['frames']
 
 
-def plan(seconds, single=False, max_frames=None, single_limit_seconds=None, block_seconds=None, continued=False, max_parts=None):
+def _lengths(total, first, following, least, continued):
+    """Part lengths in seconds with every continuing part from `least` to `following` seconds, or None."""
+    if first < (least if continued else SHORTEST_BLOCK) or following < least:
+        return None
+    # The part that starts a new video is not held to `least`; a rest too short for the continuing parts is
+    # taken from that part.
+    rest = total if continued else total - min(first, total)
+    count = math.ceil(round(rest, 6) / following) if rest > 0 else 0
+    rest = max(rest, least * count)
+    whole = math.ceil(round(rest, 6))
+    if continued and round(rest - total, 6) > 0 or not continued and total - whole < SHORTEST_FIRST:
+        return None
+    if count > MAX_BLOCKS:
+        raise PlanError('too_long', 'This length needs too many blocks')
+    lengths = [whole // count + (index < whole % count) for index in range(count)]
+    if continued:
+        lengths[0] = round(lengths[0] - (whole - total), 6)  # a fractional request keeps its length in the first part
+    else:
+        lengths.insert(0, round(total - whole, 6))
+    return lengths
+
+
+def plan(seconds, single=False, max_frames=None, single_limit_seconds=None, block_seconds=None, continued=False,
+         max_parts=None, first_frame=False):
     """`max_frames`: the most frames this device generates at once for the current settings (unknown: 15 s).
 
     `continued`: the video goes on from a saved one, so its first block too spends OVERLAP frames on what
     came before and adds only the rest.
 
-    `max_parts`: the most parts one video may have. A new video that needs more is refused here, before anything
-    is submitted; a continued one adds to parts this planner does not know, so the server checks it on submission.
+    `max_parts`: the most parts one video may have; `first_frame`: every continuing part also sees the first
+    frame, which keeps that limit when a part is short. A video that needs more parts is refused here, before
+    anything is submitted; a continued one adds to parts this planner does not know, so it counts one for them
+    and the server checks the rest on submission.
+
+    Continuing parts are FULL_PART_SECONDS or longer whenever the length allows it, else at least MIN_PART_SECONDS.
     """
     _number(seconds, 'Length')
     if type(single) is not bool:
@@ -88,32 +142,31 @@ def plan(seconds, single=False, max_frames=None, single_limit_seconds=None, bloc
             return alone  # a block this short cannot continue another: a short video stays one generation
         raise PlanError('block_too_short', 'A block that continues another is at least %d s long' % MIN_PART_SECONDS)
     first, following = min(block, head), min(block, following)
-    shortest = MIN_PART_SECONDS if continued else SHORTEST_BLOCK
-    if first < shortest or following < MIN_PART_SECONDS:
-        if fits and seconds < SINGLE_SECONDS:
-            return alone  # a requested block length never makes a part this device cannot do
-        raise PlanError('device_limit', 'This device cannot generate this length at this size')
     # Under 30 s the length stays as asked (it may be fractional); from 30 s it is whole seconds already.
     total = seconds
-    # Every part that continues another is at least MIN_PART_SECONDS and at most `following`. The part that
-    # starts a new video is not held to it; a rest too short for the continuing parts is taken from that part.
-    rest = total if continued else total - min(first, total)
-    count = math.ceil(round(rest, 6) / following) if rest > 0 else 0
-    rest = max(rest, MIN_PART_SECONDS * count)
-    whole = math.ceil(round(rest, 6))
-    if continued and whole > math.ceil(round(total, 6)) or not continued and total - whole < SHORTEST_FIRST:
+    lengths = None
+    for least in (FULL_PART_SECONDS, MIN_PART_SECONDS):
+        if least < FULL_PART_SECONDS and block >= FULL_PART_SECONDS and fits and seconds < SINGLE_SECONDS:
+            break  # a video that fits at once stays one generation rather than take short parts
+        lengths = _lengths(total, first, following, least, continued)
+        if lengths is not None:
+            break
+    if lengths is None:
         if fits and seconds < SINGLE_SECONDS:
-            return alone
+            return alone  # a requested block length never makes a part this device cannot do
+        if first < (MIN_PART_SECONDS if continued else SHORTEST_BLOCK) or following < MIN_PART_SECONDS:
+            raise PlanError('device_limit', 'This device cannot generate this length at this size')
         raise PlanError('length_not_splittable', 'This length cannot be cut into parts of the requested length')
-    if count > MAX_BLOCKS:
-        raise PlanError('too_long', 'This length needs too many blocks')
-    if max_parts is not None and not continued and count + 1 > max_parts:
-        raise PlanError('too_many_parts', 'One continuous shot can have up to %d parts. Make it shorter.' % max_parts)
-    lengths = [whole // count + (index < whole % count) for index in range(count)]
-    if continued:
-        lengths[0] = round(lengths[0] - (whole - total), 6)  # a fractional request keeps its length in the first part
-    else:
-        lengths.insert(0, round(total - whole, 6))
+    if max_parts is not None:
+        parts = len(lengths) + continued  # a continued video has at least one part before these
+        short = any(length < FULL_PART_SECONDS for length in lengths[0 if continued else 1:])
+        allowed = parts_limit(short, first_frame, max_parts)
+        if parts > allowed and allowed < max_parts:
+            raise PlanError('too_many_short_parts', 'With a part shorter than %d seconds, this video can have up to '
+                            '%d parts. Make each part at least %d seconds long, or use fewer parts.'
+                            % (FULL_PART_SECONDS, allowed, FULL_PART_SECONDS))
+        if parts > allowed:
+            raise PlanError('too_many_parts', 'One continuous shot can have up to %d parts. Make it shorter.' % max_parts)
     frames_all = int(round(FPS * total))
     blocks, shown = [], 0
     for index, length in enumerate(lengths):
diff --git a/freevideo_engine/chain_runner.py b/freevideo_engine/chain_runner.py
index 37439109..485078b1 100644
--- a/freevideo_engine/chain_runner.py
+++ b/freevideo_engine/chain_runner.py
@@ -27,6 +27,18 @@ def __init__(self, parts, limit):
         self.message_zh = '一个连续镜头最多 %d 段，请缩短。' % limit
 
 
+class ChainShortPartsTooMany(ChainTooLong):
+    """A video with a short continuing part, continued through more parts than such a video may have."""
+    code = 'chain_short_parts'
+
+    def __init__(self, parts, limit):
+        full = chain_plan.FULL_PART_SECONDS
+        ValueError.__init__(self, 'With a part shorter than %d seconds, this video can have up to %d parts. '
+                            'Make each part at least %d seconds long, or use fewer parts.' % (full, limit, full))
+        self.parts, self.limit = parts, limit
+        self.message_zh = '有短于 %d 秒的段时，这条视频最多 %d 段。请把每段加长到至少 %d 秒，或减少段数。' % (full, limit, full)
+
+
 class ChainPartTooShort(ValueError):
     """A continuing part shorter than a continued video may have."""
     code = 'chain_part_too_short'
@@ -34,7 +46,7 @@ class ChainPartTooShort(ValueError):
     def __init__(self, seconds, limit):
         super().__init__('Each continued part must be at least %d seconds. Make it longer.' % limit)
         self.seconds, self.limit = seconds, limit
-        self.message_zh = '接着生成的每一段至少 %d 秒，请加长一些。' % limit
+        self.message_zh = '接着生成的每一段至少 %d 秒，请加长这一段。' % limit
 
 
 def _work_key(path):
@@ -69,11 +81,15 @@ def node_prompt(prompt, node):
 
 class ChainRunner:
     def __init__(self, store_dir, host, clock=time.monotonic, wall=time.time, estimate=None, poll=0.5, inputs=None,
-                 max_parts=None, min_part_frames=None, seeds=None):
+                 max_parts=None, min_part_frames=None, seeds=None, full_part_frames=None):
         self.store_dir, self.host = store_dir, host
         self.seeds = seeds or random.SystemRandom()
         self.max_parts = max_parts or store.MAX_PARTS
         self.min_part_frames = chain_plan.MIN_PART_FRAMES if min_part_frames is None else min_part_frames
+        # Continuing parts below this are short and hold their video to fewer parts. A runner given a lower
+        # shortest part (a test host) lowers this with it unless it is given too.
+        self.full_part_frames = (full_part_frames if full_part_frames is not None else chain_plan.FULL_PART_FRAMES
+                                 if min_part_frames is None else min(min_part_frames, chain_plan.FULL_PART_FRAMES))
         self.clock, self.wall, self.estimate, self.poll = clock, wall, estimate, poll
         self.inputs = inputs or host.inputs
         self.lock = threading.RLock()
@@ -219,33 +235,45 @@ def _depths(self, record, seen=()):
         """Parts each block of `record` continues through, itself included (a block with no source is the
         first part). A source that is an existing video counts the parts that video was made of, as far
         as this runner's records know them; one they do not know counts as one part."""
+        return {name: parts for name, (parts, _) in self._lineage(record, seen).items()}
+
+    def _lineage(self, record, seen=()):
+        """For each block of `record`: its parts as `_depths` counts them, and whether any continuing part
+        among them is short."""
         rows = {row['id']: row for row in record['blocks']}
-        depth, pending = {}, list(rows)
+        lineage, pending = {}, list(rows)
         while pending:
             rest = []
             for identity in pending:
                 row = rows[identity]
                 sources = [row[key] for key in ('after', 'before') if row[key] is not None]
-                if any(isinstance(value, str) and value not in depth for value in sources):
+                if any(isinstance(value, str) and value not in lineage for value in sources):
                     rest.append(identity)
                     continue
-                depth[identity] = 1 + sum(depth[value] if isinstance(value, str)
-                                          else self._source_parts(value, seen + (record['id'],))
-                                          for value in sources)
+                found = [lineage[value] if isinstance(value, str) else self._source_lineage(value, seen + (record['id'],))
+                         for value in sources]
+                short = bool(sources) and row['inputs']['frames'] < self.full_part_frames
+                lineage[identity] = (1 + sum(parts for parts, _ in found), short or any(flag for _, flag in found))
             if len(rest) == len(pending):
                 raise ValueError('Block references cannot contain a cycle or self reference')
             pending = rest
-        return depth
+        return lineage
 
     def _source_parts(self, value, seen):
+        return self._source_lineage(value, seen)[0]
+
+    def _source_lineage(self, value, seen):
         if 'chain' not in value:
-            return self._work_parts(value['work'], seen)
+            return self._work_lineage(value['work'], seen)
         self._referenced_block(value)
         if value['chain'] in seen:
             raise ValueError('Chain references cannot contain a cycle')
-        return self._depths(self.records[value['chain']], seen)[value['block']]
+        return self._lineage(self.records[value['chain']], seen)[value['block']]
 
     def _work_parts(self, work, seen):
+        return self._work_lineage(work, seen)[0]
+
+    def _work_lineage(self, work, seen):
         key = _work_key(work)
         for record in list(self.records.values()):
             if record['id'] in seen:
@@ -255,9 +283,27 @@ def _work_parts(self, work, seen):
             else:
                 names = [row['id'] for row in record['blocks'] if row['output'] and _work_key(row['output']) == key]
             if names:
-                depth = self._depths(record, seen)
-                return max(depth[name] for name in names)
-        return 1
+                lineage = self._lineage(record, seen)
+                return max(lineage[name][0] for name in names), any(lineage[name][1] for name in names)
+        return 1, False
+
+    def _check_parts(self, record):
+        """Refuses, before anything is written or queued, a chain with a continuing part too short or a video
+        continued through too many parts."""
+        short = [row['inputs']['frames'] for row in record['blocks']
+                 if (row['after'] is not None or row['before'] is not None)
+                 and row['inputs']['frames'] < self.min_part_frames]
+        if short:
+            raise ChainPartTooShort(min(short) / chain_plan.FPS, chain_plan.MIN_PART_SECONDS)
+        lineage = self._lineage(record).values()
+        parts = max(parts for parts, _ in lineage)
+        if parts > self.max_parts:
+            raise ChainTooLong(parts, self.max_parts)
+        inputs = record['snapshot']['prompt'][record['node']].get('inputs') or {}
+        limit = chain_plan.parts_limit(True, inputs.get('first_frame_reference') is True, self.max_parts)
+        parts = max((parts for parts, flag in lineage if flag), default=0)
+        if parts > limit:
+            raise ChainShortPartsTooMany(parts, limit)
 
     def create(self, payload):
         from .lora_triggers import apply_chain_triggers
@@ -265,14 +311,7 @@ def create(self, payload):
         apply_chain_triggers(record)
         with self.lock:
             # Before anything is written or queued: a refused chain leaves every record and file as it was.
-            short = [row['inputs']['frames'] for row in record['blocks']
-                     if (row['after'] is not None or row['before'] is not None)
-                     and row['inputs']['frames'] < self.min_part_frames]
-            if short:
-                raise ChainPartTooShort(min(short) / chain_plan.FPS, chain_plan.MIN_PART_SECONDS)
-            parts = max(self._depths(record).values())
-            if parts > self.max_parts:
-                raise ChainTooLong(parts, self.max_parts)
+            self._check_parts(record)
             record['created'] = self.wall()
             self._save(record)
             self.records[record['id']] = record
@@ -410,14 +449,7 @@ def redo(self, chain_id, block_id, text=None, client_id=None):
                 except Exception:
                     raise ValueError('Text must be at most 20000 characters with LoRA triggers') from None
                 record['blocks'][start['index']]['inputs']['text'] = probe['blocks'][0]['inputs']['text']
-            short = [row['inputs']['frames'] for row in record['blocks']
-                     if (row['after'] is not None or row['before'] is not None)
-                     and row['inputs']['frames'] < self.min_part_frames]
-            if short:
-                raise ChainPartTooShort(min(short) / chain_plan.FPS, chain_plan.MIN_PART_SECONDS)
-            parts = max(self._depths(record).values())
-            if parts > self.max_parts:
-                raise ChainTooLong(parts, self.max_parts)
+            self._check_parts(record)
             # The kept seams are repaired with the sound the original chain kept for them. Copies left by
             # a failed save have no record, so the next start prunes them.
             try:
diff --git a/freevideo_engine/chain_store.py b/freevideo_engine/chain_store.py
index d7e536f4..7dd23902 100644
--- a/freevideo_engine/chain_store.py
+++ b/freevideo_engine/chain_store.py
@@ -26,8 +26,8 @@
     'unavailable': 'Splitting is not available here, so every part used the whole description.',
     'failed': 'Splitting the description failed, so every part used the whole description.',
 }
-# Parts one video may be continued through: the first part and seven continuations.
-MAX_PARTS = 8
+# Parts one video may be continued through: the first part and seven continuations (fewer with a short part).
+MAX_PARTS = chain_plan.MAX_PARTS
 
 
 def reference(value, queue=False):
diff --git a/freevideo_engine/comfy_chain.py b/freevideo_engine/comfy_chain.py
index aa4b5cb2..1b99620d 100644
--- a/freevideo_engine/comfy_chain.py
+++ b/freevideo_engine/comfy_chain.py
@@ -5,6 +5,7 @@
 import math
 import os
 from pathlib import Path, PurePosixPath
+import platform
 import ssl
 import time
 from urllib import error, request
@@ -248,6 +249,14 @@ def continuation_supported():
     return supported()[0]
 
 
+def continue_seconds():
+    """The length a new continuation starts with where this device sets it: short parts on Apple silicon, where
+    a full part takes long and often does not fit; None elsewhere, where the page goes by the measured limits."""
+    if platform.system() == 'Darwin' and platform.machine().lower() in ('arm64', 'aarch64'):
+        return chain_plan.SHORT_CONTINUE_SECONDS
+    return None
+
+
 def continuation_available():
     return 'after' in continuation_directions() and continuation_supported()
 
@@ -333,7 +342,8 @@ async def plan(request):
             value = await body(request)
             result = chain_plan.plan(
                 value.get('seconds'), value.get('single', False), value.get('max_frames'),
-                value.get('single_limit_seconds'), value.get('block_seconds'), max_parts=runner.max_parts)
+                value.get('single_limit_seconds'), value.get('block_seconds'), max_parts=runner.max_parts,
+                first_frame=value.get('first_frame_reference') is True)
             if not result['single'] and not continuation_supported():
                 # A device that cannot continue a video has one block to give: never a plan in parts.
                 raise chain_plan.PlanError('device_limit', 'This device cannot generate this length at this size')
@@ -376,7 +386,8 @@ def asking(request):
 
     @server.routes.get('/freevideo/chains')
     async def listing(request):
-        value = {'chains': runner.list(asking(request)), 'continuation': continuation_available()}
+        value = {'chains': runner.list(asking(request)), 'continuation': continuation_available(),
+                 'continue_seconds': continue_seconds()}
         if fake:
             value['fake'] = True
         return response(value)
diff --git a/web/chain_rules.js b/web/chain_rules.js
new file mode 100644
index 00000000..b0575bfe
--- /dev/null
+++ b/web/chain_rules.js
@@ -0,0 +1 @@
+export const CHAIN_RULES = {"min_part_seconds": 5, "full_part_seconds": 10, "max_parts": 8, "short_max_parts": 4, "continue_seconds": 10, "short_continue_seconds": 5};
diff --git a/web/editor.js b/web/editor.js
index eb1fdd1c..9b345a1f 100644
--- a/web/editor.js
+++ b/web/editor.js
@@ -43,6 +43,15 @@ const editorStyles = Promise.all(['result_actions.css', 'editor.css', 'editor_ex
 }));
 const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
 const language = () => new URLSearchParams(location.search).get('freevideo_lang') || navigator.language;
+// The engine's limits on continuing parts, refused before a generation starts; the engine says the same.
+export const PARTS_LIMIT_CODES = ['chain_too_long', 'chain_part_too_short', 'chain_short_parts'];
+export function partsLimitText(code, t = en => en, limit = null) {
+    const {followSeconds: least, fullSeconds: full, maxParts, shortMaxParts} = model.RULES;
+    if (code === 'chain_part_too_short') return t(`Each continued part must be at least ${least} seconds. Make it longer.`, `接着生成的每一段至少 ${least} 秒，请加长这一段。`);
+    if (code === 'chain_short_parts') { const most = limit ?? shortMaxParts; return t(`With a part shorter than ${full} seconds, this video can have up to ${most} parts. Make each part at least ${full} seconds long, or use fewer parts.`,
+        `有短于 ${full} 秒的段时，这条视频最多 ${most} 段。请把每段加长到至少 ${full} 秒，或减少段数。`); }
+    return t(`One continuous shot can have up to ${limit ?? maxParts} parts. Make it shorter.`, `一个连续镜头最多 ${limit ?? maxParts} 段，请缩短。`);
+}
 // Shared by error() and actions.reasonText: one sentence naming the failed step.
 export function editorErrorText(value, t = en => en) {
     if (isNetworkTypeError(value) || isNetworkTypeError(value?.detail)) return connectionLostText(t);
@@ -61,8 +70,10 @@ export function editorErrorText(value, t = en => en) {
     if (code === 'gpu_memory' || /out of memory|cuda.*memory|显存不足|显存不够/i.test(raw))
         return t(`${stage}: not enough GPU memory.`, `${stage}时显存不足。`);
     const known = {
-        chain_part_too_short: t('Each continued part needs at least 10 seconds.', '接续的每段至少 10 秒。'),
-        chain_too_long: t('One continuous shot can have up to 8 parts.', '一个连续镜头最多 8 段。'),
+        chain_part_too_short: t(`Each continued part needs at least ${model.RULES.followSeconds} seconds.`, `接续的每段至少 ${model.RULES.followSeconds} 秒。`),
+        chain_short_parts: t(`With a part shorter than ${model.RULES.fullSeconds} seconds, one video can have up to ${model.RULES.shortMaxParts} parts.`,
+            `有短于 ${model.RULES.fullSeconds} 秒的段时，一条视频最多 ${model.RULES.shortMaxParts} 段。`),
+        chain_too_long: t(`One continuous shot can have up to ${model.RULES.maxParts} parts.`, `一个连续镜头最多 ${model.RULES.maxParts} 段。`),
         too_long: t('This part is longer than the maximum length. Shorten it and try again.', '这一段超过了最长时长，请缩短后再试。'),
         missing_node: t('Generation is not ready. Restart FreeVideo.', '生成功能没有就绪，请重新启动 FreeVideo。'),
         chain_missing: t('Generation could not start. Choose "Generate" again.', '生成没能开始，请再点“生成”。'),
@@ -305,10 +316,9 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         }
         if (['audio_prepare', 'speed_pending', 'speed_locked', 'speed'].includes(code)) return {ok: false, reason: code};
         if (code === 'unsupported') { genbar?.update(null); return; }
-        if (['chain_too_long', 'chain_part_too_short'].includes(code)) {
+        if (PARTS_LIMIT_CODES.includes(code)) {
             const [en, zh] = (value.said || []).map(text => typeof text === 'string' && text ? text.slice(0, 200) : null);
-            const text = code === 'chain_too_long' ? t(en || 'One continuous shot can have up to 8 parts. Make it shorter.', zh || '一个连续镜头最多 8 段，请缩短。')
-                : t(en || 'Each continued part must be at least 10 seconds. Make it longer.', zh || '接着生成的每一段至少 10 秒，请加长一些。');
+            const text = en && zh ? t(en, zh) : partsLimitText(code, t, Number.isInteger(value.limit) ? value.limit : null);
             out(text); return {ok: false, reason: code, say: text};
         }
         if (['busy', 'locked', 'text', 'audio_full', 'overlap', 'range', 'no_audio'].includes(code)) {
@@ -490,7 +500,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 // Each part goes with its own description, as written while it waited.
                 const texts = Object.fromEntries(clips.map(clip => [clip.id, clip.text.trim() || entry.text]));
                 try { await actions.generate({text: texts[clips[0].id], texts, selection}); }
-                catch (value) { const reason = error(value, 'generate'); if (reason && !['chain_too_long', 'chain_part_too_short'].includes(reason.reason)) genbar?.say(reason.say); }
+                catch (value) { const reason = error(value, 'generate'); if (reason && !PARTS_LIMIT_CODES.includes(reason.reason)) genbar?.say(reason.say); }
             }
         } finally { startingHeld = false; }
     }
@@ -929,6 +939,9 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 submittedSelection = shown && state.selection === chosen ? state.select({kind: 'clip', ids}) : state.selection; await completeSources();
                 const paths = Object.fromEntries([...store.sources].map(([key, value]) => [key, value.path]));
                 const request = model.generationRequest(prepared, ids, {text: texts ? undefined : text, paths, queue: true});
+                // What the engine would refuse for its continuing parts is said here, before anything is sent.
+                const problem = model.partsProblem(prepared, ids);
+                if (problem) throw Object.assign(new Error(problem.code), {code: problem.code, limit: problem.limit});
                 const beforeKeys = model.generationBefore(prepared, ids), sizes = new Map(store.sources);
                 for (const key of beforeKeys.filter(key => key?.startsWith('chain:'))) {
                     const job = await store.chain(key.split(':')[1]);
@@ -973,7 +986,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 if (epoch === projectEpoch) {
                     if (ids.length) state.settle(record => model.settle(record, ids, 'draft'));
                     // A length limit is the user's to change and is said once in the notice; there is nothing to report.
-                    if (!['chain_too_long', 'chain_part_too_short'].includes(value?.code)) {
+                    if (!PARTS_LIMIT_CODES.includes(value?.code)) {
                         failures.submission(value, frozen, text); submissionFailure = JSON.stringify(state.selection);
                     }
                     genbar?.update(null);
@@ -1523,7 +1536,8 @@ export function openEditor({api, app, from = null, panel = {}, components: given
                 if (after.length || !clip.extend || !clip.source || store.sources.get(sourceKey(clip.source))?.missing) return true;
                 if (!store.generationAvailable) return false;
                 const spare = Math.min(...model.pair(state.record, clip.id).map(member => member.length - member.in - member.frames));
-                tracks.extendClip(clip.id, spare + model.continuedSeconds(0, capability.maxFollowSeconds) * model.FPS, {silent: true});
+                tracks.extendClip(clip.id, spare + model.defaultContinueSeconds(capability.maxFollowSeconds,
+                    {short: store.continueSeconds != null && store.continueSeconds < model.RULES.fullSeconds}) * model.FPS, {silent: true});
                 return true;
             };
             await store.generationReady();
diff --git a/web/editor_genbar.js b/web/editor_genbar.js
index 823e22bc..1e4a5b12 100644
--- a/web/editor_genbar.js
+++ b/web/editor_genbar.js
@@ -247,7 +247,7 @@ export function createEditorGenbar(host, {state, t, actions, text = ''}) {
         }
         // A specific reason is said once; the planning limits are already shown above.
         catch (error) { const result = actions.error(error, 'generate'); reason = result?.say || '';
-            if (result?.say && !['chain_too_long', 'chain_part_too_short'].includes(result.reason)) say(result.say, false, ['Editor generation', '剪辑器生成']);
+            if (result?.say && !['chain_too_long', 'chain_part_too_short', 'chain_short_parts'].includes(result.reason)) say(result.say, false, ['Editor generation', '剪辑器生成']);
             else if (!result && !note.textContent) { reason = t('Could not start. Try again.', '没能开始，请重试。'); say(reason, false, ['Editor generation', '剪辑器生成']); } }
         finally { pressing.delete(key); render(); }
         return reason;
diff --git a/web/editor_model.js b/web/editor_model.js
index dbd62237..8439c36f 100644
--- a/web/editor_model.js
+++ b/web/editor_model.js
@@ -4,12 +4,18 @@ import {pictureFields, pictureEditor} from './editor_picture_fields.js';
 import {markerFields} from './editor_transport_model.js';
 import {audioClipFields, audioTrackFields, normalizeAudioEdits, splitAudioFields} from './editor_audio_model.js';
 import {speedRange, parseSpeedData, validateSpeedPair, sourceFrame, speedEdited, trimSpeed, splitSpeed, connectSpeedOperations} from './editor_speed_model.js';
+import {CHAIN_RULES} from './chain_rules.js';
 export const VERSION = 1;
 export const FPS = 24;
-// followSeconds mirrors chain_plan.MIN_PART_SECONDS: a part that continues another is at least this long.
-export const RULES = Object.freeze({maxSeconds: 15, singleSeconds: 30, minSeconds: 2, tailSeconds: 5, followSeconds: 10,
+// The continuing-part limits are chain_plan's (web/chain_rules.js): a part that continues another is at least
+// followSeconds long; a video with a continuing part shorter than fullSeconds has at most shortMaxParts parts unless
+// every part sees the first frame, any other at most maxParts. A new continuation starts at continueSeconds, or at
+// shortContinueSeconds where a full part is too much for the device.
+export const RULES = Object.freeze({maxSeconds: 15, singleSeconds: 30, minSeconds: 2, tailSeconds: 5,
+    followSeconds: CHAIN_RULES.min_part_seconds, fullSeconds: CHAIN_RULES.full_part_seconds,
+    continueSeconds: CHAIN_RULES.continue_seconds, shortContinueSeconds: CHAIN_RULES.short_continue_seconds,
     step: 17, first: 5, overlap: 22,
-    maxTracks: 3, maxClips: 500, maxText: 8000, maxParts: 8});
+    maxTracks: 3, maxClips: 500, maxText: 8000, maxParts: CHAIN_RULES.max_parts, shortMaxParts: CHAIN_RULES.short_max_parts});
 // Slice and bound user text by Unicode code points, never UTF-16 halves.
 export const truncateText = (text, limit) => Array.from(text).slice(0, limit).join('');
 export const copyName = (name, suffix) => truncateText(name, RULES.maxText - Array.from(suffix).length) + suffix;
@@ -634,6 +640,12 @@ export const setPictureSize = (record, width, height, size_mode = 'fixed') => fi
 export const setPicture = pictureEditor({copy, trackBy, check, pictureFit, finish});
 export const setPictureFit = (record, id, fit) => setPicture(record, id, {fit: pictureFit(fit)});
 
+// The fewest frames a continuing part of `seconds` whole seconds asks for (chain_plan.part_frames): below
+// MIN_PART_FRAMES a continuing part is too short, below FULL_PART_FRAMES it is a short part.
+const partFrames = seconds => RULES.overlap + RULES.step * Math.ceil((FPS * seconds - (RULES.step - 1)) / RULES.step);
+export const MIN_PART_FRAMES = partFrames(RULES.followSeconds), FULL_PART_FRAMES = partFrames(RULES.fullSeconds);
+// The most parts one video may have (chain_plan.parts_limit).
+export const partsLimit = (short, firstFrame = false) => short && !firstFrame ? Math.min(RULES.maxParts, RULES.shortMaxParts) : RULES.maxParts;
 // The shortest a part that continues another may be; a device that cannot make a part that long keeps the general minimum.
 const followLeast = maxFollowSeconds => maxFollowSeconds >= RULES.followSeconds ? RULES.followSeconds : RULES.minSeconds;
 // A length to continue by, in whole seconds, raised to one that parts of followSeconds..maxFollowSeconds can add up to.
@@ -643,6 +655,12 @@ export function continuedSeconds(seconds, maxFollowSeconds = RULES.maxSeconds) {
     const length = Math.max(least, Math.round(seconds));
     return Math.max(length, Math.ceil(length / follow) * least);
 }
+// The length a new continuation starts with: a full part, or a short one where the device cannot make a full part
+// or `short` asks for it.
+export function defaultContinueSeconds(maxFollowSeconds = RULES.maxSeconds, {short = false} = {}) {
+    const full = !short && maxFollowSeconds >= RULES.fullSeconds;
+    return continuedSeconds(full ? RULES.continueSeconds : RULES.shortContinueSeconds, maxFollowSeconds);
+}
 function segmentLengths(frames, maxSeconds = RULES.maxSeconds, maxFollowSeconds = maxSeconds, continues = false) {
     check(typeof maxSeconds === 'number' && Number.isFinite(maxSeconds) && maxSeconds >= RULES.minSeconds, 'range');
     check(typeof maxFollowSeconds === 'number' && Number.isFinite(maxFollowSeconds) && maxFollowSeconds >= RULES.minSeconds, 'range');
@@ -652,13 +670,15 @@ function segmentLengths(frames, maxSeconds = RULES.maxSeconds, maxFollowSeconds
     // half a minute or more, or beyond the device, goes in parts of a quarter minute.
     if (!continues && left < RULES.singleSeconds * FPS && left <= Math.floor(maxSeconds) * FPS) return [left];
     check(left <= RULES.maxClips * max, 'range');
-    // Every part after the first continues the one before it and is at least followSeconds long, as chain_plan lays
-    // them out: the parts after the first share what is left evenly, and a rest too short for them comes off the first.
-    if (follow >= RULES.followSeconds * FPS) {
-        const seconds = continues ? continuedSeconds(left / FPS, follow / FPS) : left / FPS;
+    // Every part after the first continues the one before it, as chain_plan lays them out: the parts after the first
+    // share what is left evenly, and a rest too short for them comes off the first. They are fullSeconds or longer
+    // whenever the length allows it, else at least followSeconds.
+    const seconds = continues && follow >= RULES.followSeconds * FPS ? continuedSeconds(left / FPS, follow / FPS) : left / FPS;
+    for (const least of [RULES.fullSeconds, RULES.followSeconds]) {
+        if (follow < least * FPS) continue;
         const head = continues ? 0 : Math.min(max / FPS, seconds), rest = seconds - head, count = Math.ceil(rest / (follow / FPS));
-        const shared = Math.max(rest, RULES.followSeconds * count);
-        if (continues || seconds - shared >= RULES.minSeconds) {
+        const shared = Math.max(rest, least * count);
+        if (continues ? shared === rest : seconds - shared >= RULES.minSeconds) {
             check(count <= RULES.maxClips, 'range');
             const result = continues ? [] : [(seconds - shared) * FPS];
             for (let i = 0; i < count; i++) result.push((Math.floor(shared / count) + (i < shared % count ? 1 : 0)) * FPS);
@@ -718,12 +738,14 @@ export function continuesBefore(record, id) {
 }
 // The lengths one range is generated in, as planRange lays them out on empty tracks.
 export const partLengths = (frames, {maxSeconds = RULES.maxSeconds, maxFollowSeconds = maxSeconds, continues = false} = {}) => segmentLengths(frames, maxSeconds, maxFollowSeconds, continues);
-// One video is generated in at most RULES.maxParts parts: the longest range that still fits.
-export function maxRangeFrames(record, {continues = false, maxSeconds = RULES.maxSeconds, maxFollowSeconds = maxSeconds}) {
+// One video is generated in at most partsLimit parts: the longest range that still fits. A device whose continuing
+// parts are all short has the short-part limit.
+export function maxRangeFrames(record, {continues = false, maxSeconds = RULES.maxSeconds, maxFollowSeconds = maxSeconds, firstFrame = false}) {
     const before = continues;
     const follow = Math.floor(Math.min(RULES.maxSeconds, maxFollowSeconds)) * FPS;
+    const parts = partsLimit(follow < RULES.fullSeconds * FPS, firstFrame);
     // The part being continued is the first of them.
-    return before ? (RULES.maxParts - 1) * follow : Math.floor(Math.min(RULES.maxSeconds, maxSeconds)) * FPS + (RULES.maxParts - 1) * follow;
+    return before ? (parts - 1) * follow : Math.floor(Math.min(RULES.maxSeconds, maxSeconds)) * FPS + (parts - 1) * follow;
 }
 // Manual boundaries use device limits, not the automatic fifteen-second preference.
 export function rangeParts(record, {start, frames, parts, continues, maxSeconds = RULES.maxSeconds, maxFollowSeconds = maxSeconds}) {
@@ -1041,6 +1063,68 @@ export function generationRequest(record, ids, {text, paths = {}, queue = false}
     }
     return frozen({blocks, plan});
 }
+// Whether a part made before a request is a short continuing part: what the engine kept of it is its new frames.
+const madeShort = clip => (clip.source ? clip.length : clip.frames) + RULES.overlap < FULL_PART_FRAMES;
+// The parts the finished or queued part `clip` was continued through on the timeline, itself included, and whether
+// a continuing part among them is short.
+function madeLineage(record, clip) {
+    let parts = 1, short = false;
+    for (let before = partBefore(record, clip), seen = new Set([clip.id]); before && !seen.has(before.id); before = partBefore(record, before)) {
+        short = short || madeShort(clip); parts += 1; seen.add(before.id); clip = before;
+    }
+    return {parts, short};
+}
+// What the engine refuses in a generation request (chain_runner checks the same before anything runs): a continuing
+// part shorter than followSeconds, a video continued through more than maxParts parts, or one with a short
+// continuing part through more than partsLimit allows. Parts made before the request count as the timeline shows
+// them. Returns {code, parts, limit} for the first problem, or null.
+export function partsProblem(record, ids, {firstFrame = record.settings?.first_frame_reference === true} = {}) {
+    const rows = generationPlan(record, generationClips(record, ids));
+    if (rows.some(row => row.before && row.request_frames < MIN_PART_FRAMES)) return {code: 'chain_part_too_short', parts: null, limit: RULES.followSeconds};
+    const lineage = new Map();
+    for (const row of rows) {
+        const previous = !row.before ? {parts: 0, short: false} : lineage.get(row.before.id) ?? madeLineage(record, row.before);
+        lineage.set(row.clip.id, {parts: previous.parts + 1, short: previous.short || !!row.before && row.request_frames < FULL_PART_FRAMES});
+    }
+    const values = [...lineage.values()], parts = Math.max(...values.map(value => value.parts));
+    if (parts > RULES.maxParts) return {code: 'chain_too_long', parts, limit: RULES.maxParts};
+    const limit = partsLimit(true, firstFrame), short = Math.max(0, ...values.filter(value => value.short).map(value => value.parts));
+    return short > limit ? {code: 'chain_short_parts', parts: short, limit} : null;
+}
+// Sets the continuation draft `id` (a planned part that continues the one before it) to `seconds` whole seconds,
+// keeping its start; the drafts that continue it move with its end. Refused with 'range' for a length a continuing
+// part cannot have on this device or where there is no room, and with the engine's code (partsProblem) where the
+// new length would make the video one the engine refuses.
+export function setContinuationSeconds(record, id, seconds, {maxSeconds = RULES.maxSeconds, maxFollowSeconds = maxSeconds, firstFrame} = {}) {
+    const members = pair(record, id); check(members.length, 'missing'); busy(members);
+    check(members.every(clip => clip.pending && !clip.source), 'unsupported');
+    const video = members.find(clip => trackOf(record, clip.id).id === 'v1');
+    check(!!video && !!partBefore(record, video), 'unsupported');
+    check(Number.isInteger(seconds) && seconds >= followLeast(maxFollowSeconds)
+        && seconds <= Math.floor(Math.min(RULES.maxSeconds, maxFollowSeconds)), 'range');
+    const delta = seconds * FPS - video.frames;
+    if (!delta) return record;
+    const run = [video];
+    for (let next; (next = trackBy(record, 'v1').clips.find(clip => clip.pending && !clip.source && continuing(clip, run.at(-1)))); ) run.push(next);
+    const moving = run.flatMap(clip => pair(record, clip.id)); busy(moving);
+    const moved = new Set(moving.map(clip => clip.id));
+    let next = copy(record); detachAttempt(next, [...moved]);
+    for (const clip of moving) {
+        const changed = find(next, clip.id);
+        if (pair(record, video.id).some(member => member.id === clip.id)) { changed.frames = changed.length = seconds * FPS; clearPlan(changed); }
+        else { changed.start += delta; clearPlan(changed); }
+        // Nothing else on the track may be under the part's new span.
+        check(!trackOf(next, clip.id).clips.some(other => !moved.has(other.id) && overlaps(other, changed.start, changed.frames)), 'range');
+    }
+    next = finish(next);
+    // The drafts it continues are generated with it, so the whole video is checked.
+    const earlier = [];
+    for (let before = partBefore(record, video); before && before.pending === 'draft' && !before.source && !earlier.includes(before); before = partBefore(record, before)) earlier.unshift(before);
+    const ids = [...earlier, ...run].map(clip => clip.id), options = firstFrame === undefined ? {} : {firstFrame};
+    const problem = partsProblem(next, ids, options);
+    if (problem && problem.code !== partsProblem(record, ids, options)?.code) throw Object.assign(new EditError(problem.code), {parts: problem.parts, limit: problem.limit});
+    return next;
+}
 function update(record, ids, change) {
     const next = copy(record), selected = linkedIds(next, ids);
     for (const clip of all(next)) if (selected.has(clip.id)) change(clip);
diff --git a/web/editor_store.js b/web/editor_store.js
index f3ab5744..9590f9bd 100644
--- a/web/editor_store.js
+++ b/web/editor_store.js
@@ -176,6 +176,8 @@ export function mediaURL(api, value) {
 export function createEditorStore(api, {t = en => en, notify = () => {}, onGenerationReady = () => {}, onGenerationChecking = () => {}, clock = clockDefault, pollMs = 2000, standIn: injected = null} = {}) {
     const sources = new Map(), sourceReads = new Map(), watchers = new Set(), pollers = new Set(), once = new Set();
     let recovered = null, capabilityPoll = null;
+    // The length a new continuation starts with where the engine names one (a device that continues in short parts).
+    let continueSeconds = null;
     let generationAvailable = false, generationGone = false, generationProbe = null, generationRetry = null, generationAttempts = 0, generationStalled = false, generationAsking = false;
     let disposed = false; const uploads = new Set();
     const session = holdSession();
@@ -260,6 +262,7 @@ export function createEditorStore(api, {t = en => en, notify = () => {}, onGener
             memoryProjects.delete(id);
             if (activeProject === id) { activeProject = null; clock.clearTimeout(sessionTimer); sessionTimer = null; }
         },
+        get continueSeconds() { return standIn ? standIn.continueSeconds ?? null : continueSeconds; },
         get generationAvailable() { return standIn ? standIn.generationAvailable ?? true : generationAvailable; },
         // The server said for certain it cannot generate (not just a missed answer that is asked again).
         get generationGone() { return !standIn && generationGone; },
@@ -292,8 +295,13 @@ export function createEditorStore(api, {t = en => en, notify = () => {}, onGener
                 try {
                     // true: present; false: no such route; null: no usable answer.
                     answer = await Promise.race([Promise.resolve().then(() => request('/freevideo/chains', {signal: controller.signal}))
-                        .then(async response => response.status === 404 ? false
-                            : response.ok && Array.isArray((await response.json())?.chains) ? true : null)
+                        .then(async response => {
+                            if (response.status === 404) return false;
+                            if (!response.ok) return null;
+                            const body = await response.json();
+                            if (Number.isInteger(body?.continue_seconds) && body.continue_seconds > 0) continueSeconds = body.continue_seconds;
+                            return Array.isArray(body?.chains) ? true : null;
+                        })
                         .catch(() => null), timeout]);
                 } finally { probe.dispose(); generationProbe = null; generationAsking = false; }
                 if (disposed || generationGone) return false;
@@ -473,7 +481,7 @@ export function createEditorStore(api, {t = en => en, notify = () => {}, onGener
             if (!response.ok) {
                 // The server's own sentence for a video with too many parts, or a continued part too short, is shown as it is.
                 const body = await response.json().catch(() => null);
-                if (['chain_too_long', 'chain_part_too_short'].includes(body?.code)) throw Object.assign(new Error(body.code), {code: body.code, said: [body.error, body.error_zh]});
+                if (['chain_too_long', 'chain_part_too_short', 'chain_short_parts'].includes(body?.code)) throw Object.assign(new Error(body.code), {code: body.code, said: [body.error, body.error_zh]});
                 throw Object.assign(new Error(typeof body?.error === 'string' ? body.error : body?.message || `HTTP ${response.status}`),
                     {status: response.status, reason: body?.reason || body?.code, response: body});
             }
diff --git a/web/editor_tracks.js b/web/editor_tracks.js
index 6f80e2e3..0006e5db 100644
--- a/web/editor_tracks.js
+++ b/web/editor_tracks.js
@@ -85,7 +85,8 @@ export function edgeParameters(clip, edge, frame, points, zoom, {canExtend = tru
     if (edge === 'end' && canExtend && clip.extend && snapped.frame > sourceEnd) {
         // What continues a video is at least followSeconds long; the preview already shows the raised length.
         const wanted = Math.round((snapped.frame - sourceEnd) / model.FPS), seconds = model.continuedSeconds(wanted, maxFollowSeconds);
-        return {kind: 'extend', frame: sourceEnd, frames: seconds * model.FPS, guide: snapped.guide, raised: seconds !== wanted};
+        return {kind: 'extend', frame: sourceEnd, frames: seconds * model.FPS, guide: snapped.guide, raised: seconds !== wanted,
+            least: wanted < model.RULES.followSeconds && seconds >= model.RULES.followSeconds};
     }
     return {kind: 'trim', edge, frame: snapped.frame, guide: snapped.guide};
 }
@@ -959,7 +960,9 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
         else if (result.kind === 'extend') {
             const frames = result.frame - finished.clip.start - finished.clip.frames + result.frames;
             if (extendClip(finished.id, frames) && result.raised) {
-                actions.notify?.(t(`Extended to ${result.frames / model.FPS} s.`, `已补到 ${result.frames / model.FPS} 秒。`));
+                const least = model.RULES.followSeconds;
+                actions.notify?.(result.least ? t(`Each continued part needs at least ${least} seconds.`, `接着生成的每一段至少 ${least} 秒。`)
+                    : t(`Extended to ${result.frames / model.FPS} s.`, `已补到 ${result.frames / model.FPS} 秒。`));
             }
         } else attempt(t('Trim', '裁短'), record => model.trim(record, finished.id, finished.edge, result.frame));
         renderSelection();
diff --git a/web/health.js b/web/health.js
index ad011fe8..c511e8d0 100644
--- a/web/health.js
+++ b/web/health.js
@@ -13,7 +13,7 @@ const t = (en, zh) => cn ? zh : en;
 // launcher.js removes this flag during setup; read it before that.
 const launchVisit = query.get('freevideo') === 'launch';
 // Every script this folder ships; a test keeps the list in step with web/*.js.
-export const MODULES = ['chat_data.js', 'phone_model.js', 'phone.js', 'lan_access.js', 'qrcodegen.js', 'agent_activity.js', 'agent_connect.js', 'agent_session.js', 'autopilot.js', 'autopilot_chat.js', 'chat_attachments.js', 'autopilot_conversations.js', 'browser_extension.js', 'caret_rect.js', 'chain_support.js', 'capability_view.js', 'cast_generate.js', 'cast_mention.js', 'cast_overlay.js', 'cast_source.js', 'compatibility.js', 'entry_showcase.js', 'error_panel.js', 'first_run_guide.js', 'fonts.js', 'freevideo.js', 'generation_progress.js',
+export const MODULES = ['chat_data.js', 'phone_model.js', 'phone.js', 'lan_access.js', 'qrcodegen.js', 'agent_activity.js', 'agent_connect.js', 'agent_session.js', 'autopilot.js', 'autopilot_chat.js', 'chat_attachments.js', 'autopilot_conversations.js', 'browser_extension.js', 'caret_rect.js', 'chain_support.js', 'chain_rules.js', 'capability_view.js', 'cast_generate.js', 'cast_mention.js', 'cast_overlay.js', 'cast_source.js', 'compatibility.js', 'entry_showcase.js', 'error_panel.js', 'first_run_guide.js', 'fonts.js', 'freevideo.js', 'generation_progress.js',
     'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
     'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js',
diff --git a/web/howto.js b/web/howto.js
index a291e927..86c2e98d 100644
--- a/web/howto.js
+++ b/web/howto.js
@@ -35,7 +35,8 @@ const HOWTOS = [
                 zh: '填写更长的时长，会自动分段生成。'},
             {id: 'generate', anchor: '[data-fv-guide="generate"]', en: 'Choose "Generate video".', zh: '点“生成视频”。'},
             {id: 'extend', anchor: '.fv-action-extend', image: 'extend-button',
-                en: 'Choose "Extend" on a finished video to continue it.', zh: '在生成好的视频上点“接着生成”，继续下一段。'},
+                en: 'Choose "Extend" on a finished video to continue it. Each continued part is at least 5 seconds; with a part shorter than 10 seconds, one video has at most 4 parts.',
+                zh: '在生成好的视频上点“接着生成”，继续下一段。接着生成的每一段至少 5 秒；有短于 10 秒的段时，一条视频最多 4 段。'},
             {id: 'longer', anchor: '[data-view="editor"]', en: 'Parts can also be added one by one in "Edit".', zh: '也可在“剪辑视图”中逐段接续。'}]},
     {id: 'editor-extend-refs', view: 'editor', title: ['Add reference images when extending in Edit', '在剪辑视图延长时加参考图'],
         steps: [
diff --git a/web/length_plan.js b/web/length_plan.js
index 525405c5..d1b28ea5 100644
--- a/web/length_plan.js
+++ b/web/length_plan.js
@@ -32,7 +32,7 @@ export function readLengthPlan(reply) {
 
 export function classifyPlanError(reply) {
     if (reply?.code === 'device_limit') return 'continuation_unavailable';
-    if (reply?.code === 'too_long' || reply?.code === 'too_many_parts') return 'too_long';
+    if (reply?.code === 'too_long' || ['too_many_parts', 'too_many_short_parts'].includes(reply?.code)) return 'too_long';
     if (['block_too_long', 'block_too_short', 'too_short', 'invalid'].includes(reply?.code)) return 'other';
     const value = reply?.error;
     const message = reply?.code || (typeof value === 'string' ? value : value?.code || value?.message || '');
diff --git a/web/tutorial_book_content.js b/web/tutorial_book_content.js
index 5d5d901e..6735bbc8 100644
--- a/web/tutorial_book_content.js
+++ b/web/tutorial_book_content.js
@@ -33,8 +33,8 @@ export const TUTORIAL_CHAPTERS = [
             en: ['Enter a longer duration. It is made in parts automatically. "Available sizes and lengths" shows how long each size can be and about how long it takes.', 'Choose "Generate video".', 'Choose "Extend" on a finished video to continue it.', 'Parts can also be added one by one in "Edit".'],
         },
         limits: {
-            zh: ['一个连续镜头最多 8 段，创作面板中时长最长 60 秒；分镜剧本可在剪辑视图中逐个镜头添加，或用 AI 全自动。', '分段生成和接着生成需要 NVIDIA 显卡或 Mac。', '段数越多，衔接处越容易出现变化；适合切换镜头处，可直接开始新的一段。'],
-            en: ['One continuous shot has at most 8 parts, and the creation panel accepts up to 60 seconds. For a storyboard, add shots one by one in Edit, or use Autopilot.', 'Generating in parts and Extend need an NVIDIA graphics card or a Mac.', 'The more parts are joined, the more the joins may change. Where a cut fits, cut to a new shot and start a fresh part.'],
+            zh: ['接着生成的每一段至少 5 秒。一个连续镜头最多 8 段，有短于 10 秒的段时最多 4 段；创作面板中时长最长 60 秒；分镜剧本可在剪辑视图中逐个镜头添加，或用 AI 全自动。', '分段生成和接着生成需要 NVIDIA 显卡或 Mac。', '段数越多，衔接处越容易出现变化；适合切换镜头处，可直接开始新的一段。'],
+            en: ['Each continued part is at least 5 seconds. One continuous shot has at most 8 parts, or 4 when a part is shorter than 10 seconds, and the creation panel accepts up to 60 seconds. For a storyboard, add shots one by one in Edit, or use Autopilot.', 'Generating in parts and Extend need an NVIDIA graphics card or a Mac.', 'The more parts are joined, the more the joins may change. Where a cut fits, cut to a new shot and start a fresh part.'],
         },
     },
     {
@@ -51,8 +51,8 @@ export const TUTORIAL_CHAPTERS = [
             en: ['Select the part to continue.', 'Click + next to the prompt to upload or generate images, up to 3.', 'Describe it, then choose "Generate".'],
         },
         limits: {
-            zh: ['接续生成最多使用 3 张参考图，不使用首帧和尾帧。', '剪辑视图只能添加图片；参考视频和音频在创作面板的“素材”中添加。', '同样最多 8 段；需要 NVIDIA 显卡或 Mac。'],
-            en: ['A part that continues the previous one uses up to 3 reference images and no first or last frames.', 'Edit takes images only. Add reference videos and audio under "Media" in the creation panel.', 'The same 8-part limit applies. An NVIDIA graphics card or a Mac is required.'],
+            zh: ['接续生成最多使用 3 张参考图，不使用首帧和尾帧。', '剪辑视图只能添加图片；参考视频和音频在创作面板的“素材”中添加。', '段数限制相同；需要 NVIDIA 显卡或 Mac。'],
+            en: ['A part that continues the previous one uses up to 3 reference images and no first or last frames.', 'Edit takes images only. Add reference videos and audio under "Media" in the creation panel.', 'The same part limits apply. An NVIDIA graphics card or a Mac is required.'],
         },
     },
 ];

From 4682ec3149aad174134f22934bcc87710045c373 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 21:07:23 +0000
Subject: [PATCH 08/52] Editor: one wording for continued-part limits, and say
 the lengthened length

- The shortest continued part reads the same everywhere: "Each continued
part must be at least 5 seconds."
- Dragging a continued part longer says its new length in tenths of a
second, and adds the shortest-part rule when it was raised to that.
- The parts limit with short parts names one continuous shot, in the
editor, the planner, the chain runner and the Agent errors alike.
---
 freevideo_engine/agent/errors.py |  2 +-
 freevideo_engine/chain_plan.py   |  4 ++--
 freevideo_engine/chain_runner.py |  6 +++---
 web/editor.js                    | 10 +++++-----
 web/editor_tracks.js             |  8 +++++---
 5 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/freevideo_engine/agent/errors.py b/freevideo_engine/agent/errors.py
index 32303046..59974fad 100644
--- a/freevideo_engine/agent/errors.py
+++ b/freevideo_engine/agent/errors.py
@@ -67,7 +67,7 @@
     'chain_missing': (409, True, 'The saved chain receipt is unavailable.', 'Restore the chain receipt and retry resume, or submit a new job.'),
     'join_failed': (409, True, 'The generated blocks could not be joined; completed blocks are retained.', 'POST /freevideo/agent/v1/jobs/{id}/resume to retry joining the completed blocks.'),
     'chain_too_long': (422, False, 'One continuous shot can have up to 8 parts. Make it shorter.', 'Submit a new job with a smaller seconds, or cut to a new shot with a new job without continue_from; continue_from counts the parts of the video it continues.'),
-    'chain_short_parts': (422, False, 'With a part shorter than 10 seconds, this video can have up to 4 parts. Make each part at least 10 seconds long, or use fewer parts.', 'Submit a new job whose continuing parts are at least 10 seconds, with fewer parts, or with first_frame_reference true; continue_from counts the parts of the video it continues.'),
+    'chain_short_parts': (422, False, 'With a part shorter than 10 seconds, one continuous shot can have up to 4 parts. Make every part at least 10 seconds long, or use fewer parts.', 'Submit a new job whose continuing parts are at least 10 seconds, with fewer parts, or with first_frame_reference true; continue_from counts the parts of the video it continues.'),
     'chain_rejected': (409, False, 'The continuous backend rejected this generation.', 'Read GET /freevideo/agent/v1/capabilities and submit a supported generation request.'),
     'invalid_wait': (422, False, 'wait must be a finite nonnegative number of seconds.', 'Use wait=0 or wait=25; larger valid values are clamped to 25 seconds.'),
     'invalid_resume': (422, False, 'resume accepts an empty object or an optional ref only.', 'Send {} or {"ref":"resume-1"}; submit a new job to change generation parameters.'),
diff --git a/freevideo_engine/chain_plan.py b/freevideo_engine/chain_plan.py
index 13289ecf..dfbc0281 100644
--- a/freevideo_engine/chain_plan.py
+++ b/freevideo_engine/chain_plan.py
@@ -162,8 +162,8 @@ def plan(seconds, single=False, max_frames=None, single_limit_seconds=None, bloc
         short = any(length < FULL_PART_SECONDS for length in lengths[0 if continued else 1:])
         allowed = parts_limit(short, first_frame, max_parts)
         if parts > allowed and allowed < max_parts:
-            raise PlanError('too_many_short_parts', 'With a part shorter than %d seconds, this video can have up to '
-                            '%d parts. Make each part at least %d seconds long, or use fewer parts.'
+            raise PlanError('too_many_short_parts', 'With a part shorter than %d seconds, one continuous shot can have up to '
+                            '%d parts. Make every part at least %d seconds long, or use fewer parts.'
                             % (FULL_PART_SECONDS, allowed, FULL_PART_SECONDS))
         if parts > allowed:
             raise PlanError('too_many_parts', 'One continuous shot can have up to %d parts. Make it shorter.' % max_parts)
diff --git a/freevideo_engine/chain_runner.py b/freevideo_engine/chain_runner.py
index 485078b1..ad3ce625 100644
--- a/freevideo_engine/chain_runner.py
+++ b/freevideo_engine/chain_runner.py
@@ -33,10 +33,10 @@ class ChainShortPartsTooMany(ChainTooLong):
 
     def __init__(self, parts, limit):
         full = chain_plan.FULL_PART_SECONDS
-        ValueError.__init__(self, 'With a part shorter than %d seconds, this video can have up to %d parts. '
-                            'Make each part at least %d seconds long, or use fewer parts.' % (full, limit, full))
+        ValueError.__init__(self, 'With a part shorter than %d seconds, one continuous shot can have up to %d parts. '
+                            'Make every part at least %d seconds long, or use fewer parts.' % (full, limit, full))
         self.parts, self.limit = parts, limit
-        self.message_zh = '有短于 %d 秒的段时，这条视频最多 %d 段。请把每段加长到至少 %d 秒，或减少段数。' % (full, limit, full)
+        self.message_zh = '有短于 %d 秒的段时，一个连续镜头最多 %d 段。请把每段加长到至少 %d 秒，或减少段数。' % (full, limit, full)
 
 
 class ChainPartTooShort(ValueError):
diff --git a/web/editor.js b/web/editor.js
index 9b345a1f..bac41e14 100644
--- a/web/editor.js
+++ b/web/editor.js
@@ -48,8 +48,8 @@ export const PARTS_LIMIT_CODES = ['chain_too_long', 'chain_part_too_short', 'cha
 export function partsLimitText(code, t = en => en, limit = null) {
     const {followSeconds: least, fullSeconds: full, maxParts, shortMaxParts} = model.RULES;
     if (code === 'chain_part_too_short') return t(`Each continued part must be at least ${least} seconds. Make it longer.`, `接着生成的每一段至少 ${least} 秒，请加长这一段。`);
-    if (code === 'chain_short_parts') { const most = limit ?? shortMaxParts; return t(`With a part shorter than ${full} seconds, this video can have up to ${most} parts. Make each part at least ${full} seconds long, or use fewer parts.`,
-        `有短于 ${full} 秒的段时，这条视频最多 ${most} 段。请把每段加长到至少 ${full} 秒，或减少段数。`); }
+    if (code === 'chain_short_parts') { const most = limit ?? shortMaxParts; return t(`With a part shorter than ${full} seconds, one continuous shot can have up to ${most} parts. Make every part at least ${full} seconds long, or use fewer parts.`,
+        `有短于 ${full} 秒的段时，一个连续镜头最多 ${most} 段。请把每段加长到至少 ${full} 秒，或减少段数。`); }
     return t(`One continuous shot can have up to ${limit ?? maxParts} parts. Make it shorter.`, `一个连续镜头最多 ${limit ?? maxParts} 段，请缩短。`);
 }
 // Shared by error() and actions.reasonText: one sentence naming the failed step.
@@ -70,9 +70,9 @@ export function editorErrorText(value, t = en => en) {
     if (code === 'gpu_memory' || /out of memory|cuda.*memory|显存不足|显存不够/i.test(raw))
         return t(`${stage}: not enough GPU memory.`, `${stage}时显存不足。`);
     const known = {
-        chain_part_too_short: t(`Each continued part needs at least ${model.RULES.followSeconds} seconds.`, `接续的每段至少 ${model.RULES.followSeconds} 秒。`),
-        chain_short_parts: t(`With a part shorter than ${model.RULES.fullSeconds} seconds, one video can have up to ${model.RULES.shortMaxParts} parts.`,
-            `有短于 ${model.RULES.fullSeconds} 秒的段时，一条视频最多 ${model.RULES.shortMaxParts} 段。`),
+        chain_part_too_short: t(`Each continued part must be at least ${model.RULES.followSeconds} seconds.`, `接着生成的每一段至少 ${model.RULES.followSeconds} 秒。`),
+        chain_short_parts: t(`With a part shorter than ${model.RULES.fullSeconds} seconds, one continuous shot can have up to ${model.RULES.shortMaxParts} parts.`,
+            `有短于 ${model.RULES.fullSeconds} 秒的段时，一个连续镜头最多 ${model.RULES.shortMaxParts} 段。`),
         chain_too_long: t(`One continuous shot can have up to ${model.RULES.maxParts} parts.`, `一个连续镜头最多 ${model.RULES.maxParts} 段。`),
         too_long: t('This part is longer than the maximum length. Shorten it and try again.', '这一段超过了最长时长，请缩短后再试。'),
         missing_node: t('Generation is not ready. Restart FreeVideo.', '生成功能没有就绪，请重新启动 FreeVideo。'),
diff --git a/web/editor_tracks.js b/web/editor_tracks.js
index 0006e5db..703bb896 100644
--- a/web/editor_tracks.js
+++ b/web/editor_tracks.js
@@ -10,6 +10,7 @@ import {createSelectionGestures, isMultiple, isTyping} from './editor_select.js'
 import {createTrackMenu} from './editor_menu.js';
 import {transportSnapPoints, setSnapping as setTransportSnapping} from './editor_transport_model.js';
 import {attachAudioTracks} from './editor_audio.js';
+import {seconds as secondsText} from './editor_audio_notes.js';
 import {renderSpeedBadge} from './editor_speed.js';
 import {speedEdited} from './editor_speed_model.js';
 
@@ -960,9 +961,10 @@ export function createTracks(host, {state, sources = {}, t = en => en, actions =
         else if (result.kind === 'extend') {
             const frames = result.frame - finished.clip.start - finished.clip.frames + result.frames;
             if (extendClip(finished.id, frames) && result.raised) {
-                const least = model.RULES.followSeconds;
-                actions.notify?.(result.least ? t(`Each continued part needs at least ${least} seconds.`, `接着生成的每一段至少 ${least} 秒。`)
-                    : t(`Extended to ${result.frames / model.FPS} s.`, `已补到 ${result.frames / model.FPS} 秒。`));
+                // Say the new length (tenths, rounded down like other durations) so the change is visible.
+                const least = model.RULES.followSeconds, length = secondsText(result.frames, model.FPS);
+                actions.notify?.(result.least ? t(`Lengthened to ${length} s. Each continued part must be at least ${least} seconds.`, `已加长到 ${length} 秒。接着生成的每一段至少 ${least} 秒。`)
+                    : t(`Lengthened to ${length} s.`, `已加长到 ${length} 秒。`));
             }
         } else attempt(t('Trim', '裁短'), record => model.trim(record, finished.id, finished.edge, result.frame));
         renderSelection();

From b13c9d71b1d1b04ffde58be5fa3acac3070c64bd Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 17:33:57 +0000
Subject: [PATCH 09/52] Judge pinned dependency checkouts by content and
 replace stale ones safely

Dependency checkouts are now compared by file content only. Every Git
check runs with core.filemode and core.autocrlf turned off for that
command, so a copy, restore or drive that changes permission bits, or a
global line-ending setting, no longer makes a pinned checkout look
edited. With a sparse checkout, the status check covers only the sparse
paths, so a file that appears outside them is ignored. The deep-path
Windows branch uses the same settings.

Git now reads the repository in the dependency folder itself: discovery
stops at its parent folder and inherited GIT_DIR-style variables are
dropped, so a folder that lost .git/refs no longer reports the HEAD of an
enclosing repository. Reading HEAD from the file follows a symbolic
reference to its commit, through the loose ref or packed-refs.

When a dependency folder that FreeVideo created in its vendor folder
(same sparse patterns, or no or the same origin) holds a different
version or changed content, the fresh copy is cloned and verified first.
The old folder is then renamed to <name>.replaced-<time> and kept, and
the new copy takes its place. If a rename fails, the old folder is left
or put back in place and the error says so. Only the latest set-aside
folder is kept, and only folders FreeVideo marked itself are removed.
Folders FreeVideo did not create, such as a ComfyUI the user works in,
are never replaced.

Otherwise the error names the folder and says what differs: an
unreadable version, a different version, the files with changed content,
and how many files differ only in permissions.
---
 freevideo_engine/network.py | 265 +++++++++++++++++++++++++++++++++---
 1 file changed, 246 insertions(+), 19 deletions(-)

diff --git a/freevideo_engine/network.py b/freevideo_engine/network.py
index b17120c7..3b69d059 100644
--- a/freevideo_engine/network.py
+++ b/freevideo_engine/network.py
@@ -1323,22 +1323,90 @@ def relocate(source, destination):
     remove_tree(source)
 
 
+# Checks compare content only: a copy, restore or drive that changes permission
+# bits, or a global line-ending setting, must not make a pinned checkout look
+# edited. These settings apply to that one Git command and are never stored.
+CONTENT_ONLY = ('-c', 'core.filemode=false', '-c', 'core.autocrlf=false')
+
+
+def checkout_environment(path, env):
+    """Git environment that reads the repository at `path` itself, never one around it."""
+    env = dict(os.environ if env is None else env)
+    for name in ('GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY'):
+        env.pop(name, None)
+    # Without its own .git/refs (a backup that drops empty folders), Git would
+    # otherwise climb to an enclosing repository and report that one's HEAD.
+    env['GIT_CEILING_DIRECTORIES'] = os.path.dirname(os.path.abspath(str(path)))
+    return env
+
+
+def sparse_pathspecs(patterns):
+    """Pathspecs equal to anchored, literal sparse patterns, or None when they cannot be expressed."""
+    specs = []
+    for pattern in patterns:
+        pattern = pattern.strip()
+        if not pattern or pattern.startswith('#'):
+            continue
+        if not pattern.startswith('/') or any(c in pattern for c in '!*?[\\'):
+            return None
+        name = pattern.strip('/')
+        if not name:
+            return None
+        specs.append(':(top,literal)' + name)
+    return specs or None
+
+
+def sparse_enabled(path, git, env):
+    value = config_value(path, 'core.sparseCheckout', git, env) or ''
+    return value.lower() in ('true', 'yes', 'on', '1')
+
+
+def sparse_patterns(path, git, env):
+    """The sparse checkout patterns the checkout at `path` uses, or None."""
+    if not sparse_enabled(path, git, env):
+        return None
+    try:
+        text = io_path(Path(path) / '.git' / 'info' / 'sparse-checkout').read_text(encoding='utf-8')
+    except OSError:
+        return None
+    return [line.strip() for line in text.splitlines() if line.strip()]
+
+
+def checkout_status(path, git, env, hidden, *, filemode=False):
+    """`git status` lines for tracked files, limited to the sparse checkout when there is one.
+
+    Git 2.37 and newer report a file that appears at a path outside the sparse
+    patterns; such a file is not part of what FreeVideo uses.
+    """
+    specs = sparse_pathspecs(sparse_patterns(path, git, env) or [])
+    settings = CONTENT_ONLY if not filemode else ('-c', 'core.filemode=true', '-c', 'core.autocrlf=false')
+    return subprocess_output.output_external([git, '-c', 'core.longpaths=true', '-C', str(path), *settings,
+                                              'status', '--porcelain', '--untracked-files=no',
+                                              *(['--', *specs] if specs else [])], env=env, **hidden)
+
+
 def repository_state(path, git, env, revision='HEAD', **options):
-    """What `revision` is and what local changes the checkout at `path` has."""
+    """What `revision` is and what content changes the checkout at `path` has."""
     path = Path(path)
     prefix = [git, '-c', 'core.longpaths=true']
     hidden = dict(hidden_console(), **options)
     if not git_folder_too_deep(path):
-        head = subprocess_output.output_external([*prefix, '-C', str(path), 'rev-parse', revision], env=env, **hidden).strip()
-        dirty = subprocess_output.output_external([*prefix, '-C', str(path), 'status', '--porcelain', '--untracked-files=no'], env=env, **hidden)
+        env = checkout_environment(path, env)
+        # A folder Git cannot read is reported by the caller, not as Git's own message in the log.
+        hidden.setdefault('stderr', subprocess.PIPE)
+        head = subprocess_output.output_external([*prefix, '-C', str(path), *CONTENT_ONLY, 'rev-parse', revision],
+                                                 env=env, **hidden).strip()
+        dirty = checkout_status(path, git, env, hidden)
         return head, dirty
     # Name the repository instead of entering it. If Git cannot read it this
     # way, HEAD is read from the file and local changes cannot be checked.
     git_dir = '--git-dir=' + str(path / '.git')
     folder = tempfile.gettempdir()
     try:
-        head = subprocess_output.output_external([*prefix, git_dir, 'rev-parse', revision], cwd=folder, env=env, **hidden).strip()
-        dirty = subprocess_output.output_external([*prefix, git_dir, 'diff-index', '--cached', '--name-only', 'HEAD'], cwd=folder, env=env, **hidden)
+        head = subprocess_output.output_external([*prefix, git_dir, *CONTENT_ONLY, 'rev-parse', revision],
+                                                 cwd=folder, env=env, **hidden).strip()
+        dirty = subprocess_output.output_external([*prefix, git_dir, *CONTENT_ONLY, 'diff-index', '--cached',
+                                                   '--name-only', 'HEAD'], cwd=folder, env=env, **hidden)
     except (subprocess.CalledProcessError, OSError):
         # Git also refuses a --git-dir this long, so read what is asked from the files.
         head = stored_head(path)
@@ -1351,8 +1419,29 @@ def repository_state(path, git, env, revision='HEAD', **options):
     return head, dirty
 
 
+def stored_reference(path, name):
+    """The commit a reference such as refs/heads/main names, from its file or packed-refs, or None."""
+    try:
+        return io_path(path / '.git' / name).read_text(encoding='utf-8').strip()
+    except OSError:
+        pass
+    try:
+        packed = io_path(path / '.git' / 'packed-refs').read_text(encoding='utf-8')
+    except OSError:
+        return None
+    for line in packed.splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1] == name and not line.startswith(('#', '^')):
+            return parts[0]
+    return None
+
+
 def stored_head(path):
-    return io_path(path / '.git' / 'HEAD').read_text(encoding='utf-8').strip()
+    """The commit .git/HEAD names, following a symbolic reference such as `ref: refs/heads/main`."""
+    head = io_path(path / '.git' / 'HEAD').read_text(encoding='utf-8').strip()
+    if head.startswith('ref:'):
+        return stored_reference(path, head.split(None, 1)[1].strip()) or head
+    return head
 
 
 def stored_tree(path, commit):
@@ -1360,10 +1449,9 @@ def stored_tree(path, commit):
     import zlib
     try:
         if commit.startswith('ref:'):
-            name = commit.split(None, 1)[1]
-            commit = io_path(path / '.git' / name).read_text(encoding='utf-8').strip()
+            commit = stored_reference(path, commit.split(None, 1)[1].strip())
         raw = zlib.decompress(io_path(path / '.git' / 'objects' / commit[:2] / commit[2:]).read_bytes())
-    except (OSError, ValueError, IndexError, zlib.error):
+    except (OSError, ValueError, IndexError, TypeError, zlib.error):
         return None
     header, _, body = raw.partition(b'\0')
     first = body.split(b'\n', 1)[0]
@@ -1372,14 +1460,140 @@ def stored_tree(path, commit):
     return None
 
 
+def status_paths(lines):
+    return [line[3:].split(' -> ')[-1] for line in (lines or '').splitlines() if len(line) > 3]
+
+
+def config_value(path, key, git, env):
+    """A value from the checkout's own config file (readable even where Git cannot open the repository)."""
+    try:
+        result = subprocess_output.run_external(
+            [git, 'config', '--file', str(Path(path) / '.git' / 'config'), '--get', key], env=env,
+            stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=30, **hidden_console())
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def same_source(first, second):
+    def normal(url):
+        url = url.strip().rstrip('/')
+        return url[:-4] if url.endswith('.git') else url
+    return normal(first) == normal(second)
+
+
+def owned_checkout(target, url, sparse, git, env):
+    """Whether `target` is a checkout FreeVideo made itself and may set aside.
+
+    Only dependency folders directly in a FreeVideo `vendor` folder qualify, and
+    only when the checkout is set up as clone() leaves it: the same sparse
+    patterns, or (without them) no origin or the same origin. A ComfyUI the user
+    works in is never replaced: its custom nodes and models live inside it.
+    """
+    target = Path(target)
+    if target.parent.name != 'vendor' or not io_path(target / '.git').is_dir():
+        return False
+    enabled = sparse_enabled(target, git, env)
+    if sparse:
+        try:
+            patterns = io_path(target / '.git' / 'info' / 'sparse-checkout').read_text(encoding='utf-8').split()
+        except OSError:
+            return False
+        return enabled and patterns == [p.strip() for p in sparse]
+    origin = config_value(target, 'remote.origin.url', git, env)
+    return not enabled and (origin is None or same_source(origin, url))
+
+
+def mismatch_message(target, git, env, head, commit, dirty):
+    """A specific description of how an existing checkout differs, naming only its folder and files."""
+    details = []
+    if head is None:
+        details.append('Its version could not be read.')
+    elif head != commit:
+        details.append('It holds a different version.')
+    changed = status_paths(dirty)
+    if changed:
+        shown = ', '.join(changed[:8]) + (' and %d more' % (len(changed) - 8) if len(changed) > 8 else '')
+        details.append('Files with changed content (%d): %s.' % (len(changed), shown))
+    if head is not None:
+        try:
+            with_modes = status_paths(checkout_status(target, git, checkout_environment(target, env),
+                                                      dict(hidden_console(), timeout=60), filemode=True))
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, OSError):
+            with_modes = []
+        modes = [name for name in with_modes if name not in set(changed)]
+        if modes:
+            details.append('%d other file(s) differ only in permissions, which is accepted.' % len(modes))
+    return ('A dependency folder differs from the version FreeVideo needs: %s. %s '
+            'Rename or move this folder, then retry installation; FreeVideo then downloads a fresh copy.'
+            % (target, ' '.join(details)))
+
+
+REPLACED_MARKER = 'freevideo-replaced'
+
+
+def set_aside(target):
+    """Rename an outdated checkout to `<name>.replaced-<time>` beside it; return the new path."""
+    old = target.with_name('%s.replaced-%s' % (target.name, time.strftime('%Y%m%d-%H%M%S')))
+    if io_path(old).exists():
+        old = old.with_name('%s-%d' % (old.name, time.time_ns()))
+    try:
+        io_path(target).rename(io_path(old))
+    except OSError as error:
+        raise ValueError('FreeVideo could not update the dependency folder %s because another program is using '
+                         'files in it. Close programs that use this folder, then retry installation. '
+                         'The folder was left unchanged.' % target) from error
+    try:
+        io_path(old / '.git' / REPLACED_MARKER).write_text(target.name + '\n', encoding='utf-8')
+    except OSError:
+        pass  # Without the marker the folder is never removed automatically.
+    return old
+
+
+def remove_earlier_replaced(target, keep):
+    """Remove older folders set_aside() made for `target`; never another folder."""
+    pattern = re.compile(re.escape(target.name) + r'\.replaced-\d{8}-\d{6}(-\d+)?')
+    for path in io_path(target.parent).glob(target.name + '.replaced-*'):
+        if (path.name == keep.name or not pattern.fullmatch(path.name) or path.is_symlink()
+                or not (path / '.git' / REPLACED_MARKER).is_file()):
+            continue
+        try:
+            remove_tree(path)
+        except OSError:
+            pass  # Held by another program; a later replacement tries again.
+
+
 def clone(target, url, commit, *, sparse=None, run=None, network=None, env=None):
-    """Fetch only the pinned commit, atomically; never reset existing checkouts."""
+    """Fetch only the pinned commit, atomically; never reset existing checkouts.
+
+    An existing checkout at the pinned commit with unchanged content is used
+    as it is. One FreeVideo made itself in its `vendor` folder that holds
+    another version or changed content is replaced by a fresh verified
+    download; the old folder is kept beside it as `<name>.replaced-<time>`.
+    Any other differing folder is reported, never changed.
+    """
     target = Path(target)
     network = installed_plan(env) if network is None else network
     env = proxy_environment(env)
     env.update(GIT_TERMINAL_PROMPT='0', GIT_HTTP_LOW_SPEED_LIMIT='1024', GIT_HTTP_LOW_SPEED_TIME='20')
     git = env.get('FREEVIDEO_GIT') or 'git'
-    version = git_version(git, env) if not io_path(target).exists() else None
+    replacing = False
+    if io_path(target).exists():
+        if not io_path(target / '.git').exists():
+            raise ValueError('Existing dependency is not a Git checkout of the pinned source: ' + str(target))
+        try:
+            head, dirty = repository_state(target, git, env)
+        except (subprocess.CalledProcessError, OSError):
+            head, dirty = None, ''  # Git cannot read it as a repository of its own.
+        if head == commit and not dirty:
+            return target
+        if not owned_checkout(target, url, sparse, git, env):
+            raise ValueError(mismatch_message(target, git, env, head, commit, dirty))
+        replacing = True
+        event(network, category='git', file=target.name, action='replace-planned', commit=commit,
+              reason='unreadable' if head is None else 'other-version' if head != commit else 'changed-content',
+              changed_files=len(status_paths(dirty)))
+    version = git_version(git, env) if replacing or not io_path(target).exists() else None
     if version and version < MIN_GIT:
         raise RuntimeError(old_git_message(version))
     def execute(label, command):
@@ -1389,13 +1603,6 @@ def execute(label, command):
         result = subprocess_output.run_external(list(map(str, command)), env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, **hidden_console())
         if result.returncode:
             raise RuntimeError(result.stdout[-2500:])
-    if io_path(target).exists():
-        if not io_path(target / '.git').exists():
-            raise ValueError('Existing dependency is not a Git checkout of the pinned source: ' + str(target))
-        head, dirty = repository_state(target, git, env)
-        if head != commit or dirty:
-            raise ValueError('Existing dependency differs from the pinned clean source: ' + str(target))
-        return target
     io_path(target.parent).mkdir(parents=True, exist_ok=True)
     candidates = urls(dict(network, sources=dict(network.get('sources', {}), github=network.get('sources', {}).get('git', [{'id': 'official'}]))), 'github', url, env)
     configured_env = env
@@ -1441,7 +1648,27 @@ def execute(label, command):
                 raise ValueError('Downloaded source did not match its pinned commit')
             if scratch:
                 relocate(work, temporary)
-            io_path(temporary).rename(io_path(target))
+            old = set_aside(target) if replacing else None
+            try:
+                io_path(temporary).rename(io_path(target))
+            except OSError as error:
+                if old is None:
+                    raise
+                try:
+                    io_path(old).rename(io_path(target))
+                except OSError:
+                    raise ValueError('FreeVideo could not put the new copy of %s in place, and the previous files '
+                                     'are kept in %s. Close programs that use these folders, then retry '
+                                     'installation.' % (target, old)) from error
+                try:
+                    io_path(target / '.git' / REPLACED_MARKER).unlink()
+                except OSError:
+                    pass
+                raise ValueError('FreeVideo could not put the new copy of %s in place. Close programs that use '
+                                 'this folder, then retry installation. The folder was left unchanged.' % target) from error
+            if old is not None:
+                event(network, category='git', file=target.name, action='replaced', commit=commit, kept=old.name)
+                remove_earlier_replaced(target, old)
             source_health(network, 'git', name, True)
             route_health(network, 'git', name, route)
             event(network, category='git', source=name, route=route, file=target.name, action='verified', commit=commit)

From b300f1fb4af145baf6e9e27f484be95b66d61d58 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 17:38:06 +0000
Subject: [PATCH 10/52] Word dependency folder errors plainly and tolerate an
 unlistable folder

The mismatch message ends with one instruction, counts files that differ
only in permissions in singular or plural, and says they do not block
installation. A failed rename no longer names a guessed cause, and the
recovery message says where the previous files are now. Cleanup of
earlier set-aside folders skips a parent folder that cannot be listed.
---
 freevideo_engine/network.py | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/freevideo_engine/network.py b/freevideo_engine/network.py
index 3b69d059..369186f4 100644
--- a/freevideo_engine/network.py
+++ b/freevideo_engine/network.py
@@ -1523,9 +1523,11 @@ def mismatch_message(target, git, env, head, commit, dirty):
             with_modes = []
         modes = [name for name in with_modes if name not in set(changed)]
         if modes:
-            details.append('%d other file(s) differ only in permissions, which is accepted.' % len(modes))
+            details.append('1 other file differs only in permissions, which does not block installation.'
+                           if len(modes) == 1 else
+                           '%d other files differ only in permissions, which do not block installation.' % len(modes))
     return ('A dependency folder differs from the version FreeVideo needs: %s. %s '
-            'Rename or move this folder, then retry installation; FreeVideo then downloads a fresh copy.'
+            'Rename or move this folder, then retry installation. FreeVideo will download a fresh copy.'
             % (target, ' '.join(details)))
 
 
@@ -1540,9 +1542,8 @@ def set_aside(target):
     try:
         io_path(target).rename(io_path(old))
     except OSError as error:
-        raise ValueError('FreeVideo could not update the dependency folder %s because another program is using '
-                         'files in it. Close programs that use this folder, then retry installation. '
-                         'The folder was left unchanged.' % target) from error
+        raise ValueError('FreeVideo could not rename the dependency folder %s to replace it. Close programs that '
+                         'use this folder, then retry installation. The folder was left unchanged.' % target) from error
     try:
         io_path(old / '.git' / REPLACED_MARKER).write_text(target.name + '\n', encoding='utf-8')
     except OSError:
@@ -1553,7 +1554,11 @@ def set_aside(target):
 def remove_earlier_replaced(target, keep):
     """Remove older folders set_aside() made for `target`; never another folder."""
     pattern = re.compile(re.escape(target.name) + r'\.replaced-\d{8}-\d{6}(-\d+)?')
-    for path in io_path(target.parent).glob(target.name + '.replaced-*'):
+    try:
+        candidates = list(io_path(target.parent).glob(target.name + '.replaced-*'))
+    except OSError:
+        return  # The folder cannot be listed now; a later replacement tries again.
+    for path in candidates:
         if (path.name == keep.name or not pattern.fullmatch(path.name) or path.is_symlink()
                 or not (path / '.git' / REPLACED_MARKER).is_file()):
             continue
@@ -1658,7 +1663,7 @@ def execute(label, command):
                     io_path(old).rename(io_path(target))
                 except OSError:
                     raise ValueError('FreeVideo could not put the new copy of %s in place, and the previous files '
-                                     'are kept in %s. Close programs that use these folders, then retry '
+                                     'are now in %s. Close programs that use these folders, then retry '
                                      'installation.' % (target, old)) from error
                 try:
                     io_path(target / '.git' / REPLACED_MARKER).unlink()

From 3194f11455cf404bca56ef6ab56d5947b8dbab7d Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 20:25:17 +0000
Subject: [PATCH 11/52] Report a dependency folder too deep for Git as a long
 path

On Windows, Git reads a dependency checkout's settings from .git\config by its ordinary path. When that path is past the limit, Git cannot tell whether FreeVideo made the folder, and a fresh copy in the same place could not be read either. Such a folder in the vendor folder is now reported before anything is downloaded or renamed: the error names the folder, says its path is too long for Git to read, and asks to install FreeVideo in a folder with a shorter path, such as D:\FreeVideo. The folder is left unchanged. The failure card shows this as the existing long-path card with the folder named, in English and Chinese.

A folder whose settings Git can read is judged as before, even when Git refuses the deep folder itself, so a real version difference is still reported as one.
---
 freevideo_engine/failure_details.py |  8 +++++++-
 freevideo_engine/network.py         | 19 +++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/freevideo_engine/failure_details.py b/freevideo_engine/failure_details.py
index 6797aeee..177a4e03 100644
--- a/freevideo_engine/failure_details.py
+++ b/freevideo_engine/failure_details.py
@@ -586,7 +586,7 @@ def launcher_failure(value, *, zh=False, other_disk=False, disk_name='', can_rep
          ('A video is still generating', '还有视频正在生成'),
          ('The update is installed. Click Connect again after the job finishes to restart ComfyUI with it.',
           '更新已装好。等当前任务完成后点“重新连接”，ComfyUI 会重启并使用新版。')),
-        (r'WinError 206|The filename or extension is too long', 'path-too-long',
+        (r'WinError 206|The filename or extension is too long|is too long for Git to read', 'path-too-long',
          ("The installation folder's path is too long", '安装文件夹的路径太长'),
          ('Install FreeVideo in a folder with a shorter path, such as D:\\FreeVideo, then click "Retry installation".',
           '请把 FreeVideo 安装到路径较短的文件夹，例如 D:\\FreeVideo，然后点击“重试安装”。')),
@@ -677,6 +677,12 @@ def launcher_failure(value, *, zh=False, other_disk=False, disk_name='', can_rep
                     model, capability = found.groups()
                     detail = ('检测到：%s，计算能力 %s' if zh else 'Detected: %s, compute capability %s') % (model, capability)
                     return dict(title=title[zh], detail=detail + '\n' + action[zh], action='', kind=kind)
+            if kind == 'path-too-long':
+                # A dependency folder Git cannot read is named, above the same next step.
+                found = re.search(r'The path of the dependency folder (.+?) is too long for Git to read', text)
+                if found:
+                    detail = ('文件夹：%s' if zh else 'Folder: %s') % found[1]
+                    return dict(title=title[zh], detail=detail + '\n' + action[zh], action='', kind=kind)
             return dict(title=title[zh], detail=detail, action=action[zh], kind=kind)
     # Validation messages are already actionable. Show the cause, not a stack
     # trace or a guessed hardware diagnosis, and leave long details expandable.
diff --git a/freevideo_engine/network.py b/freevideo_engine/network.py
index 369186f4..cb811cad 100644
--- a/freevideo_engine/network.py
+++ b/freevideo_engine/network.py
@@ -1531,6 +1531,23 @@ def mismatch_message(target, git, env, head, commit, dirty):
             % (target, ' '.join(details)))
 
 
+# Git reads a checkout's settings from .git\config by its ordinary path, even in
+# the deep-folder branch above. Past the path limit it cannot tell whether
+# FreeVideo made the folder, and a new copy in the same place could not be read
+# either, so such a folder is reported before anything is renamed.
+GIT_SETTINGS_SUFFIX = '\\.git\\config'
+
+
+def git_settings_out_of_reach(path):
+    return is_windows() and path_chars(plain(path)) + len(GIT_SETTINGS_SUFFIX) > GIT_PATH_LIMIT
+
+
+def path_too_long_message(target):
+    return ('The path of the dependency folder %s is too long for Git to read. Install FreeVideo in a folder '
+            'with a shorter path, such as D:\\FreeVideo, then click "Retry installation". '
+            'The folder was left unchanged.' % plain(target))
+
+
 REPLACED_MARKER = 'freevideo-replaced'
 
 
@@ -1592,6 +1609,8 @@ def clone(target, url, commit, *, sparse=None, run=None, network=None, env=None)
             head, dirty = None, ''  # Git cannot read it as a repository of its own.
         if head == commit and not dirty:
             return target
+        if target.parent.name == 'vendor' and git_settings_out_of_reach(target):
+            raise ValueError(path_too_long_message(target))
         if not owned_checkout(target, url, sparse, git, env):
             raise ValueError(mismatch_message(target, git, env, head, commit, dirty))
         replacing = True

From 1f96a89533d1d52bdc44c54ed6cdf589b6e58a04 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sat, 24 Oct 2026 23:36:51 +0000
Subject: [PATCH 12/52] Let only a missing encoder stop the pre-encoding check

Let only a missing encoder stop the pre-encoding check, and keep other machine settings when prefetch restores readiness.
---
 freevideo_engine/encode_worker.py      | 50 +-----------------
 freevideo_engine/encoder_checkpoint.py | 70 ++++++++++++++++++++++++++
 freevideo_engine/failure_details.py    | 14 ++++--
 freevideo_engine/generate.py           |  8 +++
 freevideo_engine/model_repair.py       | 15 ++++++
 freevideo_engine/provision.py          | 46 ++++++++++++++---
 web/error_panel.js                     |  3 +-
 7 files changed, 147 insertions(+), 59 deletions(-)

diff --git a/freevideo_engine/encode_worker.py b/freevideo_engine/encode_worker.py
index a8c0c37e..1ea774db 100644
--- a/freevideo_engine/encode_worker.py
+++ b/freevideo_engine/encode_worker.py
@@ -8,59 +8,11 @@
 import json
 import os
 from pathlib import Path
-import stat
 import sys
 import time
 from .monitoring import save
 from .processes import worker_signals
-
-PACKAGE = Path(__file__).resolve().parent
-
-
-def resolve_encoder(folder_paths, name):
-    files = json.loads((PACKAGE / 'model_files.json').read_text(encoding='utf-8'))
-    expected = next((row['bytes'] for row in files if row['file'] == 'text_encoders/' + name), None)
-    path = None
-    copies = {}
-    if expected is not None:
-        folders = folder_paths.get_folder_paths('text_encoders')
-        models_dir = getattr(folder_paths, 'models_dir', None)
-        if models_dir is not None:
-            models_dir = os.path.normcase(os.path.realpath(models_dir))
-            freevideo, bundled = [], []
-            # FreeVideo paths stay preferred after a resident worker registers them.
-            for folder in folders:
-                resolved = os.path.normcase(os.path.realpath(folder))
-                try:
-                    in_models = os.path.commonpath([models_dir, resolved]) == models_dir
-                except ValueError:
-                    in_models = False  # Different Windows drives cannot share a model root.
-                (bundled if in_models else freevideo).append(folder)
-            folders = freevideo + bundled
-        for folder in folders:
-            candidate = os.path.realpath(os.path.join(folder, name))
-            if candidate in copies:
-                continue
-            try:
-                info = Path(candidate).stat()
-            except OSError:
-                continue
-            if not stat.S_ISREG(info.st_mode):
-                continue
-            copies[candidate] = info.st_size
-            if path is None and info.st_size == expected:
-                path = candidate
-    if path is None:
-        path = folder_paths.get_full_path_or_raise('text_encoders', name)
-    checkpoint = dict(state='read_only_mmap' if sys.platform == 'win32' else 'native_mmap',
-                      bytes=Path(path).stat().st_size)
-    if expected is not None:
-        checkpoint.update(expected_bytes=expected, tested_size=checkpoint['bytes'] == expected)
-        selected = os.path.realpath(path)
-        mismatched = sum(size != expected for candidate, size in copies.items() if candidate != selected)
-        if mismatched:
-            checkpoint['mismatched_copies'] = mismatched
-    return path, checkpoint
+from .encoder_checkpoint import resolve_encoder
 
 
 def encoder_on_gpu(clip):
diff --git a/freevideo_engine/encoder_checkpoint.py b/freevideo_engine/encoder_checkpoint.py
index 0e9bf9ec..90b64040 100644
--- a/freevideo_engine/encoder_checkpoint.py
+++ b/freevideo_engine/encoder_checkpoint.py
@@ -3,12 +3,82 @@
 import math
 import mmap
 import os
+from pathlib import Path
+import stat
 import struct
 import sys
 import warnings
 import weakref
 
 
+PACKAGE = Path(__file__).resolve().parent
+
+
+def resolve_encoder(folder_paths, name):
+    files = json.loads((PACKAGE / 'model_files.json').read_text(encoding='utf-8'))
+    expected = next((row['bytes'] for row in files if row['file'] == 'text_encoders/' + name), None)
+    path = None
+    copies = {}
+    if expected is not None:
+        folders = folder_paths.get_folder_paths('text_encoders')
+        models_dir = getattr(folder_paths, 'models_dir', None)
+        if models_dir is not None:
+            models_dir = os.path.normcase(os.path.realpath(models_dir))
+            freevideo, bundled = [], []
+            # FreeVideo paths stay preferred after a resident worker registers them.
+            for folder in folders:
+                resolved = os.path.normcase(os.path.realpath(folder))
+                try:
+                    in_models = os.path.commonpath([models_dir, resolved]) == models_dir
+                except ValueError:
+                    in_models = False  # Different Windows drives cannot share a model root.
+                (bundled if in_models else freevideo).append(folder)
+            folders = freevideo + bundled
+        for folder in folders:
+            candidate = os.path.realpath(os.path.join(folder, name))
+            if candidate in copies:
+                continue
+            try:
+                info = Path(candidate).stat()
+            except OSError:
+                continue
+            if not stat.S_ISREG(info.st_mode):
+                continue
+            copies[candidate] = info.st_size
+            if path is None and info.st_size == expected:
+                path = candidate
+    if path is None:
+        path = folder_paths.get_full_path_or_raise('text_encoders', name)
+    checkpoint = dict(state='read_only_mmap' if sys.platform == 'win32' else 'native_mmap',
+                      bytes=Path(path).stat().st_size)
+    if expected is not None:
+        checkpoint.update(expected_bytes=expected, tested_size=checkpoint['bytes'] == expected)
+        selected = os.path.realpath(path)
+        mismatched = sum(size != expected for candidate, size in copies.items() if candidate != selected)
+        if mismatched:
+            checkpoint['mismatched_copies'] = mismatched
+    return path, checkpoint
+
+
+def preflight_encoder(root, name, model_paths=None):
+    """Use the worker's native path configuration without importing its tensor runtime."""
+    previous = list(sys.path)
+    sys.path.insert(0, str(Path(root).resolve()))
+    try:
+        import folder_paths
+        from utils.extra_config import load_extra_path_config
+        if model_paths:
+            load_extra_path_config(str(model_paths))
+        try:
+            return resolve_encoder(folder_paths, name)
+        except FileNotFoundError as error:
+            raise FileNotFoundError(
+                "ENCODER_MODEL_MISSING: Model in folder 'text_encoders' with filename '%s' not found. "
+                'Please repair the installation. 请修复安装。' % name) from error
+    finally:
+        sys.path[:] = previous
+
+
 def read_only_state_dict(path, dtypes):
     """Only for immutable inference weights; tensors retain their mapping.
 
diff --git a/freevideo_engine/failure_details.py b/freevideo_engine/failure_details.py
index 177a4e03..14b8531a 100644
--- a/freevideo_engine/failure_details.py
+++ b/freevideo_engine/failure_details.py
@@ -878,6 +878,11 @@ def _mac_run(report, run, redactor):
     return 'Run: ' + '; '.join(parts)
 
 
+def missing_encoder(text):
+    return re.search(r"ENCODER_MODEL_MISSING:|Model in folder ['\"]text_encoders['\"] "
+                     r"with filename ['\"][^\r\n]+?['\"] not found\.", text, re.I) is not None
+
+
 def generation_failure(run, exit_code=None, *, repair=None):
     """Surface the cause, including a child traceback, even without a report.
 
@@ -967,11 +972,14 @@ def generation_failure(run, exit_code=None, *, repair=None):
     promoted = bool(causes) and causes[-1] not in known
     if promoted:
         lines.insert(1, 'Cause: ' + causes[-1][:300])
+    encoder_missing = missing_encoder('\n'.join(lines))
+    if encoder_missing:
+        lines.insert(1, 'ENCODER_MODEL_MISSING: The encoder model file is missing. ' + REPAIR_MARK)
     if len(lines) == 1:
         lines.append('The worker ended without a readable error report.')
     summary = _mac_run(report, run, redactor)
     if summary:
-        lines.insert(2 if promoted else 1, summary)
+        lines.insert(1 + bool(promoted) + bool(encoder_missing), summary)
     lines.append('\nRetained outputs: ' + str(run))
     # The table failure can be in a retained child log rather than the report.
     # Keep its numeric metadata ahead of technical output for all interactive callers.
@@ -983,9 +991,9 @@ def generation_failure(run, exit_code=None, *, repair=None):
         card = sampling_table_failure(marker)
         first, _, rest = value.partition('\n')
         value = '\n'.join((first, marker, card['title'], card['detail'], rest))
-    if explained:
+    if explained or encoder_missing:
         from .runtime_libraries import REINSTALL
-        value = value.replace(REPAIR_MARK, repair or REINSTALL, 1)
+        value = value.replace(REPAIR_MARK, repair or REINSTALL)
     value = re.sub(r'\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\))', '', value)
     value = re.sub(r'[\x00-\x08\x0b-\x1f\x7f]', '', value)
     return value
diff --git a/freevideo_engine/generate.py b/freevideo_engine/generate.py
index 3355497f..2da7746a 100644
--- a/freevideo_engine/generate.py
+++ b/freevideo_engine/generate.py
@@ -20,6 +20,7 @@
 from .locking import runtime_lock, LOCK_ENV
 from .paths import vdn_root, comfy_root
 from .monitoring import save
+from .encoder_checkpoint import preflight_encoder
 from . import tuning
 from . import processes
 from .system import (inference_headroom, inference_memory_sample, inference_environment, memory_sample,
@@ -800,6 +801,13 @@ def interrupted(signum, frame):
                     for trimmed in cached.get('reference_trims') or []:
                         print(json.dumps(dict(event='reference_trimmed', **trimmed)), flush=True)
                 else:
+                    try:
+                        preflight_encoder(args.comfy_root or comfy_root(), args.encoder, encoding['model_paths'])
+                    except Exception as error:
+                        # Only a missing encoder stops the run; the worker stays the judge of anything else.
+                        if str(error).startswith('ENCODER_MODEL_MISSING:'):
+                            raise
+                        print(json.dumps(dict(event='encoder_preflight_skipped', error=repr(error)[:300])), flush=True)
                     encoder_env = dict(env, PYTHONPATH=str(repo))
                     print(json.dumps({'event': 'encoding_start'}), flush=True)
                     encoder_attempt = history.begin(resource_identity, {'encoder': args.encoder},
diff --git a/freevideo_engine/model_repair.py b/freevideo_engine/model_repair.py
index c0b84f01..97382730 100644
--- a/freevideo_engine/model_repair.py
+++ b/freevideo_engine/model_repair.py
@@ -242,3 +242,18 @@ def retain(root, path, approved):
         del values[str(path)]
         save(Path(root) / 'logs/model-mismatches.json', values)
     return target
+
+
+def restore(root, path, retained, approved, prior=None):
+    """Undo retention after a failed download, preserving any newly present target."""
+    if os.path.lexists(path):
+        return
+    check(retained, approved)
+    try:
+        rename_noreplace(retained, path)
+    except FileExistsError:
+        return
+    if prior is not None and same_identity(identity(path), prior):
+        values = read(root)
+        values[str(path)] = prior
+        save(Path(root) / 'logs/model-mismatches.json', values)
diff --git a/freevideo_engine/provision.py b/freevideo_engine/provision.py
index 86d6d0b1..ac65ae42 100644
--- a/freevideo_engine/provision.py
+++ b/freevideo_engine/provision.py
@@ -61,6 +61,20 @@ def verified(path, row, stamps, *, mode='auto', hf_directory=None, producer_rece
 
 
 def models(plan):
+    retained = []
+    try:
+        _models(plan, retained)
+    except BaseException as error:
+        # All download/verifier threads have stopped before names are restored.
+        for root, path, kept, approved, prior in reversed(retained):
+            try:
+                model_repair.restore(root, path, kept, approved, prior)
+            except (OSError, ValueError) as rollback_error:
+                error.add_note('Could not restore retained model %s: %s' % (path, rollback_error))
+        raise
+
+
+def _models(plan, retained):
     # Use the same canonical spelling as compact_sources/ownership, including
     # Windows 8.3 temporary-directory aliases. Keep managed_model's link and
     # ownership checks intact; a different spelling must not lose the receipt.
@@ -109,9 +123,11 @@ def emit(event, **details):
         from .install_disk import check_models
         check_models(local_files + missing, replacements=replacements)
     for name, approved in replacements.items():
-        retained = model_repair.retain(root, Path(name), approved)
+        prior = model_repair.read(root).get(name)
+        kept = model_repair.retain(root, Path(name), approved)
+        retained.append((root, Path(name), kept, approved, prior))
         stamps.pop(name, None)
-        emit('model_retained', file=name, keep_as=approved['keep_as'], retained=str(retained), bytes=approved['bytes'])
+        emit('model_retained', file=name, keep_as=approved['keep_as'], retained=str(kept), bytes=approved['bytes'])
     stopped = threading.Event()
     failures = []
     ready = [0]
@@ -474,9 +490,10 @@ def prefetch(plan, out):
     """Fetch the prepared format an installation is about to switch to, beside the one in use.
 
     Generation keeps running on the installed model: only the setup lease is
-    held (no concurrent setup run), machine.json and prepared-cache.json are
-    not touched, and nothing is removed. The setup run that switches afterwards
-    finds every file present and verified.
+    held (no concurrent setup run). A shared encoder replacement clears readiness
+    while it runs and restores it once it ends with the files back in place;
+    otherwise machine.json and prepared-cache.json are not touched.
+    The setup run that switches afterwards finds every file present and verified.
     """
     from .prepared_model import files as prepared_files
     root = Path(plan['root']).expanduser().resolve()
@@ -489,7 +506,24 @@ def prefetch(plan, out):
     if Path(machine['cache']).resolve() == Path(prepared['cache']).resolve():
         raise ValueError('This prepared model is already in use')
     with runtime_lock(root / 'setup.lock', inherit=False):
-        models(plan)
+        encoder_repair = any(Path(row['path']).resolve().is_relative_to(Path(plan['encoder_dir']).resolve())
+                             for row in plan.get('replace_models', []))
+        def readiness(value):
+            # Change only the flag: the file may have been updated since it was read.
+            current = json.loads((root / 'machine.json').read_text(encoding='utf-8'))
+            save(root / 'machine.json', dict(current, ready=value))
+        if encoder_repair:
+            readiness(False)
+        try:
+            models(plan)
+        except BaseException as error:
+            # models() restored every retained file unless it says otherwise.
+            if encoder_repair and not any(note.startswith('Could not restore')
+                                          for note in getattr(error, '__notes__', ())):
+                readiness(True)
+            raise
+        if encoder_repair:
+            readiness(True)
     directory = Path(prepared['directory'])
     rows = prepared_files(prepared)
     present = [row for row in rows if (directory / row['file']).is_file()
diff --git a/web/error_panel.js b/web/error_panel.js
index c3cd3f2b..ac8efa2a 100644
--- a/web/error_panel.js
+++ b/web/error_panel.js
@@ -415,7 +415,8 @@ export function failureAdvice(value, t, known = knownError(value)) {
         return row('output-folder', ['The output folder cannot be written to', '输出目录不可写'],
             ['The video could not be saved.', '视频没能保存。'],
             ['Check that the output folder can be written to, then retry.', '请检查输出文件夹的写入权限后重试。']);
-    if (/manifest\.json/i.test(text) && /No such file|FileNotFoundError|\[Errno 2\]/i.test(text))
+    if (/ENCODER_MODEL_MISSING:|Model in folder ['"]text_encoders['"] with filename ['"][^\r\n]+?['"] not found\./i.test(text)
+            || /manifest\.json/i.test(text) && /No such file|FileNotFoundError|\[Errno 2\]/i.test(text))
         return row('model-files', ['The model is not fully installed', '模型没有装全'],
             ['Some of the model files FreeVideo needs are missing.', 'FreeVideo 需要的部分模型文件缺失。'],
             repairAction());

From d216e98fc4432754e7c84e7caac1cc8e1bf501ec Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sat, 24 Oct 2026 01:18:06 +0000
Subject: [PATCH 13/52] Ship the agent skill with the install-skill command

Ship the agent skill with the install-skill command; payload is .txt files the published launcher accepts and install writes SKILL.md and references/*.md
---
 MANIFEST.in                                   |  1 +
 freevideo_engine/agent/cli.py                 |  7 ++++
 .../agent/skill/freevideo/SKILL.txt           | 38 +++++++++++++++++++
 .../agent/skill/freevideo/references/edit.txt | 11 ++++++
 .../agent/skill/freevideo/references/film.txt | 12 ++++++
 .../skill/freevideo/references/image.txt      |  6 +++
 freevideo_engine/agent/skill_install.py       | 31 +++++++++++++++
 pyproject.toml                                |  2 +-
 8 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 freevideo_engine/agent/skill/freevideo/SKILL.txt
 create mode 100644 freevideo_engine/agent/skill/freevideo/references/edit.txt
 create mode 100644 freevideo_engine/agent/skill/freevideo/references/film.txt
 create mode 100644 freevideo_engine/agent/skill/freevideo/references/image.txt
 create mode 100644 freevideo_engine/agent/skill_install.py

diff --git a/MANIFEST.in b/MANIFEST.in
index 3b2bfbcd..d5944a9b 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -11,6 +11,7 @@ recursive-include web/fonts *.woff2
 recursive-include web/tutorial *.webp *.mp4
 recursive-include freevideo_engine/assets *.png *.ico
 recursive-include freevideo_engine/launcher *.qml
+recursive-include freevideo_engine/agent/skill *.txt
 recursive-include freevideo_engine/launcher/licenses *.txt
 recursive-include freevideo_engine/licenses *.txt
 recursive-include constraints *.txt
diff --git a/freevideo_engine/agent/cli.py b/freevideo_engine/agent/cli.py
index 793729b4..d32dc749 100644
--- a/freevideo_engine/agent/cli.py
+++ b/freevideo_engine/agent/cli.py
@@ -47,6 +47,8 @@ def build_parser():
     commands.add_parser('status', help='Readiness, limits, LoRAs, VLM and queue')
     commands.add_parser('guide', help='How to write H3 prompts')
     commands.add_parser('schema', help='JSON Schemas of jobs')
+    command = commands.add_parser('install-skill', help='Copy the FreeVideo skill where Codex, Gemini CLI, Cursor and Claude Code read skills')
+    command.add_argument('--target', choices=('agents', 'claude'), action='append', help='Default: both')
     command = commands.add_parser('capabilities', help='Read the studio capability cache')
     schema.cli_arguments(command, schema.contracts()['GET', '/capabilities']['query'])
     command = commands.add_parser('asset', help='Download a saved library video or thumbnail over HTTP')
@@ -179,6 +181,11 @@ def source(value):
         return {'from_job': value} if JOB_ID.fullmatch(value) else {'library': value} if LIBRARY_ID.fullmatch(value) \
             else {'path': str(Path(value).resolve())} if Path(value).exists() else {'file': value}
 
+    if args.command == 'install-skill':
+        from . import skill_install
+        print(json.dumps({'installed': skill_install.install(tuple(args.target or ('agents', 'claude')))}, indent=2))
+        return 0
+
     try:
         client = Client(args.url, root=args.root, name='freevideo-cli')
         if args.command in EXTRA_COMMANDS:
diff --git a/freevideo_engine/agent/skill/freevideo/SKILL.txt b/freevideo_engine/agent/skill/freevideo/SKILL.txt
new file mode 100644
index 00000000..bf1211f1
--- /dev/null
+++ b/freevideo_engine/agent/skill/freevideo/SKILL.txt
@@ -0,0 +1,38 @@
+---
+name: freevideo
+description: Make videos with the user's local FreeVideo through its MCP tools or the `freevideo agent` command line. Use when the user asks to generate or continue a video, edit a picture, cut a timeline or make a multi-shot film in FreeVideo.
+---
+
+# FreeVideo
+
+FreeVideo runs on the user's own computer. Everything below goes through its MCP server (tools named `freevideo_*`) or the same operations from a shell: `./freevideo agent <command>` (Windows: `freevideo.cmd agent`).
+
+## Before anything else
+
+1. Call `freevideo_status`. If it is not ready, tell the user what is missing; do not retry in a loop.
+2. Read `freevideo_prompt_guide` once before writing a prompt. Prompts are English sections; dialogue and on-screen text stay in the user's language.
+3. Call `freevideo_plan` with the job you intend to run. It returns the real frame count, the number of parts and a time estimate for this computer. Tell the user the estimate before a long run.
+4. The user sees the same work in the FreeVideo window. A tool may answer `needs_confirmation`: wait for the user (`freevideo_wait` without an id), then repeat the identical call once approved. If the user declines, stop and say so; do not retry with a changed reference.
+
+## Pick the right task
+
+- One video, up to 60 seconds: `freevideo_generate`. Longer than the device can do in one run is cut into parts and joined automatically.
+- Start from or end on a picture: pass it as first or last frame. Make the picture first with `freevideo_generate_image`.
+- A film of several shots to choose between: the `freevideo_drama_*` tools. See `references/film.md`.
+- Existing footage on a timeline: the editing project tools. See `references/edit.md`.
+- A picture to change: `freevideo_edit_image` for a quick change, the `freevideo_image_*` tools for layered edits. See `references/image.md`.
+- Several independent jobs: `freevideo_submit_batch`.
+
+## Running jobs
+
+- A job takes minutes. Call `freevideo_wait` with the job id; it returns after at most 25 seconds. If the job is still active, call it again with the same id. Never submit the same job twice.
+- A failed or interrupted generation is continued with `freevideo_resume`; only unfinished parts run.
+- `freevideo_cancel` only for a job you started and the user wants stopped.
+- Look at a result before reporting it: `freevideo_look` (a frame or a contact sheet).
+- Report what you made with the saved-video id (`freevideo_library`), not a local path.
+
+## Rules
+
+- Do not start a second generation while one for the same request is running; the computer has one GPU.
+- Never claim a video is good without looking at it.
+- Keep your own chat short; the user is watching progress in FreeVideo.
diff --git a/freevideo_engine/agent/skill/freevideo/references/edit.txt b/freevideo_engine/agent/skill/freevideo/references/edit.txt
new file mode 100644
index 00000000..18dfcf41
--- /dev/null
+++ b/freevideo_engine/agent/skill/freevideo/references/edit.txt
@@ -0,0 +1,11 @@
+# Editing projects
+
+Projects are the timelines shared with the FreeVideo editor page.
+
+1. `freevideo_projects` lists them; `freevideo_project_create` starts an empty one.
+2. Footage from the user's disk: `freevideo_import_media`, then poll `freevideo_imports` until `ready` (`failed` is final). Insert the returned `import:<id>` source.
+3. Always `freevideo_project_read` first. Edits carry the revision and clip ids you just read. On a `project_changed` error, read again and recompute; do not retry the old edit.
+4. `freevideo_editor_operations` applies 1 to 64 edits atomically. Prefer it to `freevideo_project_write`, which replaces the whole timeline.
+5. `freevideo_project_generate` makes new picture and sound for selected clips or a frame range, as the Generate button does.
+6. Subtitles: `freevideo_project_listen` with mode `align` times lines you give, `transcribe` writes down what is said.
+7. `freevideo_export` renders one saved revision to MP4 in the saved videos. Wait for the returned job.
diff --git a/freevideo_engine/agent/skill/freevideo/references/film.txt b/freevideo_engine/agent/skill/freevideo/references/film.txt
new file mode 100644
index 00000000..e2a2f758
--- /dev/null
+++ b/freevideo_engine/agent/skill/freevideo/references/film.txt
@@ -0,0 +1,12 @@
+# Films of several shots
+
+Use this only when the film needs separately chosen shots. A single video of up to 60 seconds is one `freevideo_generate` job.
+
+1. Reuse or make cast cards: `freevideo_cast_list` first (reuse a matching card), then `freevideo_cast_create`; `freevideo_cast_generate` makes reference pictures when the user gave none.
+2. `freevideo_drama_plan` previews the shots without starting.
+3. `freevideo_drama_start` creates the durable film. Read it with `freevideo_drama_get` (use `since` and `wait`).
+4. For each shot whose takes are done: `freevideo_drama_sheet` shows timed frames and the previous chosen last frame. Look, then `freevideo_drama_choose`. A continuation can only start after the previous shot is chosen.
+5. A take that missed: `freevideo_drama_reshoot` with a short note on what to change, then review the sheet again.
+6. When every shot is chosen: `freevideo_drama_finish`, then read the film until its output is ready.
+
+Only the user may pause or resume a film. If it is paused, stop acting and long-wait.
diff --git a/freevideo_engine/agent/skill/freevideo/references/image.txt b/freevideo_engine/agent/skill/freevideo/references/image.txt
new file mode 100644
index 00000000..775e9f2c
--- /dev/null
+++ b/freevideo_engine/agent/skill/freevideo/references/image.txt
@@ -0,0 +1,6 @@
+# Pictures
+
+- Quick change (crop, rotate, flip, pad, adjust, text, shapes, overlays, remove burned-in captions): `freevideo_edit_image`. The result is a new input file usable as a first frame or reference.
+- Layered edits like the image editor page: `freevideo_image_create` opens a session, `freevideo_image_read` gives the document and revision, `freevideo_image_operations` applies 1 to 64 edits atomically, `freevideo_image_render` makes a PNG input file. Read the revision and layer ids before each edit; on `image_changed` read again.
+- A new picture from a prompt, or combining input pictures, or a first frame with cast members: `freevideo_generate_image`.
+- Check the result with `freevideo_look` before using it.
diff --git a/freevideo_engine/agent/skill_install.py b/freevideo_engine/agent/skill_install.py
new file mode 100644
index 00000000..d36d7847
--- /dev/null
+++ b/freevideo_engine/agent/skill_install.py
@@ -0,0 +1,31 @@
+"""Copy the bundled FreeVideo skill folder where Agents that support SKILL.md look for it."""
+from pathlib import Path
+import shutil
+
+SOURCE = Path(__file__).resolve().parent / 'skill' / 'freevideo'
+# Codex, Gemini CLI and Cursor read ~/.agents/skills; Claude Code reads ~/.claude/skills.
+TARGETS = {'agents': ('.agents', 'skills'), 'claude': ('.claude', 'skills')}
+
+
+def target_dir(target, home=None):
+    return Path(home or Path.home()).joinpath(*TARGETS[target]) / 'freevideo'
+
+
+def install(targets=('agents', 'claude'), home=None):
+    """Replace the installed copy (only our own freevideo folder) and return the paths written."""
+    written = []
+    for target in targets:
+        destination = target_dir(target, home)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        staging = destination.with_name('.freevideo-installing')
+        shutil.rmtree(staging, ignore_errors=True)
+        for source in SOURCE.rglob('*.txt'):
+            # Stored as .txt so the update payload only carries file types every launcher accepts; agents read .md.
+            copy = staging / source.relative_to(SOURCE).with_suffix('.md')
+            copy.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(source, copy)
+        if destination.exists():
+            shutil.rmtree(destination)
+        staging.rename(destination)
+        written.append(str(destination))
+    return written
diff --git a/pyproject.toml b/pyproject.toml
index 0fbe352f..fe22466f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,4 +36,4 @@ include = ["freevideo_engine*"]
 [tool.setuptools.package-data]
 "freevideo_engine.prompt_vlm" = ["model.json"]
 "freevideo_engine.image_gen" = ["image_models.json", "licenses/NOTICE.txt"]
-freevideo_engine = ["stage_estimate_params.json", "build-version.txt", "build-identity.json", "release_notes.json", "dependencies.json", "model_files.json", "model_shares.json", "prepared_models.json", "macos_reference_catalog.json", "superseded_tables.json", "bootstrap_versions.json", "curl_windows.json", "git_linux.json", "git_macos.json", "gcc_linux.json", "uv_downloads.json", "torch_downloads.json", "test_prompts.json", "windows_bootstrap.ps1", "assets/*.png", "assets/*.ico", "launcher/*.qml", "launcher/licenses/*.txt", "licenses/*.txt", "licenses/runtime/*.txt", "subtitle_pack.json", "frame_preview_weights.json"]
+freevideo_engine = ["stage_estimate_params.json", "build-version.txt", "build-identity.json", "release_notes.json", "dependencies.json", "model_files.json", "model_shares.json", "prepared_models.json", "macos_reference_catalog.json", "superseded_tables.json", "bootstrap_versions.json", "curl_windows.json", "git_linux.json", "git_macos.json", "gcc_linux.json", "uv_downloads.json", "torch_downloads.json", "test_prompts.json", "windows_bootstrap.ps1", "assets/*.png", "assets/*.ico", "launcher/*.qml", "launcher/licenses/*.txt", "licenses/*.txt", "licenses/runtime/*.txt", "subtitle_pack.json", "frame_preview_weights.json", "agent/skill/freevideo/*.txt", "agent/skill/freevideo/references/*.txt"]

From 280fef6a06c3047f0c02a4ee127238d290db500f Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sun, 25 Oct 2026 05:29:29 +0000
Subject: [PATCH 14/52] install-skill runs without loading the image libraries

install-skill runs without loading the image libraries, so a deep Windows folder can install the agent skill.
---
 freevideo_engine/agent/cli.py | 38 +++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/freevideo_engine/agent/cli.py b/freevideo_engine/agent/cli.py
index d32dc749..473135f3 100644
--- a/freevideo_engine/agent/cli.py
+++ b/freevideo_engine/agent/cli.py
@@ -16,10 +16,11 @@
 import sys
 
 from .client import ApiError, Client
-from . import schema, spec, errors
+from . import errors
 
 
 def read(path):
+    from . import schema
     text = sys.stdin.read() if path == '-' else Path(path).read_text(encoding='utf-8')
     value = json.loads(text)
     schema.validate({'type': 'object'}, value)
@@ -40,6 +41,7 @@ def error(self, message):
 
 
 def build_parser():
+    from . import schema
     parser = Parser(prog='./freevideo agent', description='Drive FreeVideo through its agent API.')
     parser.add_argument('--root', type=Path)
     parser.add_argument('--url')
@@ -161,10 +163,39 @@ def build_parser():
     return parser
 
 
+def install_skill(argv):
+    """Run `install-skill` without the job schemas, whose import loads the image libraries (numpy, Pillow).
+
+    A deep installation folder on Windows cannot load those libraries by their full path, and copying
+    the skill needs none of them. None where the command line is anything else."""
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument('--root', type=Path)
+    parser.add_argument('--url')
+    parser.add_argument('command', nargs='?')
+    known, rest = parser.parse_known_args(argv)
+    if known.command != 'install-skill':
+        return None
+    parser = argparse.ArgumentParser(add_help=False, exit_on_error=False)
+    parser.add_argument('--target', choices=('agents', 'claude'), action='append')
+    try:
+        args, extra = parser.parse_known_args(rest)
+    except argparse.ArgumentError:
+        return None
+    if extra:
+        return None
+    from . import skill_install
+    print(json.dumps({'installed': skill_install.install(tuple(args.target or ('agents', 'claude')))}, indent=2))
+    return 0
+
+
 def main(argv=None):
     for stream in (sys.stdin, sys.stdout):
         if hasattr(stream, 'reconfigure'):
             stream.reconfigure(encoding='utf-8')
+    done = install_skill(sys.argv[1:] if argv is None else argv)
+    if done is not None:
+        return done
+    from . import schema, spec
     parser = build_parser()
     args = parser.parse_args(argv)
     values = vars(args)
@@ -181,11 +212,6 @@ def source(value):
         return {'from_job': value} if JOB_ID.fullmatch(value) else {'library': value} if LIBRARY_ID.fullmatch(value) \
             else {'path': str(Path(value).resolve())} if Path(value).exists() else {'file': value}
 
-    if args.command == 'install-skill':
-        from . import skill_install
-        print(json.dumps({'installed': skill_install.install(tuple(args.target or ('agents', 'claude')))}, indent=2))
-        return 0
-
     try:
         client = Client(args.url, root=args.root, name='freevideo-cli')
         if args.command in EXTRA_COMMANDS:

From d282995b0e5c81d30c4089d08bd341233a03261a Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sun, 25 Oct 2026 08:18:06 +0000
Subject: [PATCH 15/52] install-skill stages in a fresh folder beside the
 destination

install-skill stages in a fresh folder beside the destination and never writes through a leftover staging link.
---
 freevideo_engine/agent/skill_install.py | 26 +++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/freevideo_engine/agent/skill_install.py b/freevideo_engine/agent/skill_install.py
index d36d7847..36885222 100644
--- a/freevideo_engine/agent/skill_install.py
+++ b/freevideo_engine/agent/skill_install.py
@@ -1,6 +1,7 @@
 """Copy the bundled FreeVideo skill folder where Agents that support SKILL.md look for it."""
 from pathlib import Path
 import shutil
+import tempfile
 
 SOURCE = Path(__file__).resolve().parent / 'skill' / 'freevideo'
 # Codex, Gemini CLI and Cursor read ~/.agents/skills; Claude Code reads ~/.claude/skills.
@@ -17,15 +18,20 @@ def install(targets=('agents', 'claude'), home=None):
     for target in targets:
         destination = target_dir(target, home)
         destination.parent.mkdir(parents=True, exist_ok=True)
-        staging = destination.with_name('.freevideo-installing')
-        shutil.rmtree(staging, ignore_errors=True)
-        for source in SOURCE.rglob('*.txt'):
-            # Stored as .txt so the update payload only carries file types every launcher accepts; agents read .md.
-            copy = staging / source.relative_to(SOURCE).with_suffix('.md')
-            copy.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copyfile(source, copy)
-        if destination.exists():
-            shutil.rmtree(destination)
-        staging.rename(destination)
+        # A fresh folder made exclusively beside the destination: a leftover or a link with a fixed name is never written through.
+        staging = Path(tempfile.mkdtemp(prefix='.freevideo-installing-', dir=destination.parent))
+        try:
+            for source in SOURCE.rglob('*.txt'):
+                # Stored as .txt so the update payload only carries file types every launcher accepts; agents read .md.
+                copy = staging / source.relative_to(SOURCE).with_suffix('.md')
+                copy.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copyfile(source, copy)
+            if destination.is_symlink():
+                destination.unlink()
+            elif destination.exists():
+                shutil.rmtree(destination)
+            staging.rename(destination)
+        finally:
+            shutil.rmtree(staging, ignore_errors=True)
         written.append(str(destination))
     return written

From 11a778bb8adb0d65f54608122ca392fdc31fedc6 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 23:24:03 +0000
Subject: [PATCH 16/52] install-skill keeps the installed skill folder readable
 by other users

install-skill keeps the installed skill folder readable by other users after staging in a private temporary folder.
---
 freevideo_engine/agent/skill_install.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/freevideo_engine/agent/skill_install.py b/freevideo_engine/agent/skill_install.py
index 36885222..c68ed439 100644
--- a/freevideo_engine/agent/skill_install.py
+++ b/freevideo_engine/agent/skill_install.py
@@ -30,6 +30,7 @@ def install(targets=('agents', 'claude'), home=None):
                 destination.unlink()
             elif destination.exists():
                 shutil.rmtree(destination)
+            staging.chmod(0o755)  # mkdtemp creates 0700; the installed folder keeps the usual readable mode
             staging.rename(destination)
         finally:
             shutil.rmtree(staging, ignore_errors=True)

From e6af26da0b33571d5149a1989647a02386afe1ad Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Thu, 22 Oct 2026 01:47:56 +0000
Subject: [PATCH 17/52] Support guide clips with character reference images

A reference video can be marked as a guide with "guide": true. It is packed as a silent clip that shares the target time origin, so a source clip can drive the motion while a reference image supplies the character. Guides are validated, enter the cache key, skip soundtrack extraction and prompt-model video input, and are applied in both sampling passes and refinement. Keyframes combined with references are converted into guide references instead of being refused. Requests without a guide are unchanged.
---
 freevideo_engine/capabilities.py       |  8 ++++-
 freevideo_engine/comfy_assets.py       |  7 +++-
 freevideo_engine/guide_layout.py       | 46 ++++++++++++++++++++++++++
 freevideo_engine/media_conditioning.py | 34 ++++++++++++++++---
 freevideo_engine/media_encoding.py     | 13 +++++---
 freevideo_engine/media_request.py      | 30 +++++++++++++++--
 freevideo_engine/reference_sampler.py  | 10 +++---
 freevideo_engine/refine.py             |  6 ++--
 freevideo_engine/sampling_assets.py    |  2 +-
 freevideo_engine/tuning.py             |  2 +-
 10 files changed, 138 insertions(+), 20 deletions(-)
 create mode 100644 freevideo_engine/guide_layout.py

diff --git a/freevideo_engine/capabilities.py b/freevideo_engine/capabilities.py
index e7323281..a2c027d2 100644
--- a/freevideo_engine/capabilities.py
+++ b/freevideo_engine/capabilities.py
@@ -55,7 +55,7 @@ def normalize_references(task, references=None):
         kind = row.get('kind')
         allowed = {'kind', 'seconds'} if kind == 'audio' else {'kind', 'width', 'height'}
         if kind == 'video':
-            allowed |= {'seconds', 'audio_seconds'}
+            allowed |= {'seconds', 'audio_seconds', 'guide'}
         if kind not in ('image', 'video', 'audio') or set(row) - allowed:
             raise ValueError('Unsupported reference metadata.')
         width = height = seconds = audio = None
@@ -71,6 +71,12 @@ def normalize_references(task, references=None):
                 raise ValueError('Reference audio is empty after normalization.')
             if kind == 'video' and math.ceil(min(seconds, 15.) * 24) < 22:
                 raise ValueError('The reference video needs at least 22 normalized frames.')
+        if 'guide' in row:
+            # A guide clip is packed as a silent video reference (same rows and
+            # patches; only the time coordinates differ), so it keeps the plain
+            # video tuple and history matching counts it as reference video tokens.
+            if type(row['guide']) is not bool or 'audio_seconds' in row:
+                raise ValueError('A guide clip is a silent video reference.')
         if 'audio_seconds' in row:
             audio = row['audio_seconds']
             if not positive(audio):
diff --git a/freevideo_engine/comfy_assets.py b/freevideo_engine/comfy_assets.py
index 8d4f8a7a..0ed3b95c 100644
--- a/freevideo_engine/comfy_assets.py
+++ b/freevideo_engine/comfy_assets.py
@@ -75,7 +75,7 @@ def resolve_assets(serialized, input_directory):
     root = Path(input_directory).resolve()
     result = {}
     for row in rows:
-        if not isinstance(row, dict) or set(row) - {'file', 'role', 'enabled', 'cast', 'early_steps', 'sound'}:
+        if not isinstance(row, dict) or set(row) - {'file', 'role', 'enabled', 'cast', 'early_steps', 'sound', 'guide'}:
             raise ValueError('Invalid media item')
         # The character an @ mention added the row for; a continued part keeps one picture per character.
         if 'cast' in row and (set(row['cast'] if isinstance(row['cast'], dict) else ('?',)) != {'id'}
@@ -117,6 +117,11 @@ def resolve_assets(serialized, input_directory):
                 validate_sound(dict(row, kind=kind))
                 if not row['sound']:
                     reference['sound'] = False
+            if 'guide' in row:
+                from .media_request import validate_guide
+                validate_guide(dict(row, kind=kind))
+                if row['guide']:
+                    reference['guide'] = True
             result.setdefault('references', []).append(reference)
         else:
             raise ValueError('Media role must be first, last or reference')
diff --git a/freevideo_engine/guide_layout.py b/freevideo_engine/guide_layout.py
new file mode 100644
index 00000000..d7b2be51
--- /dev/null
+++ b/freevideo_engine/guide_layout.py
@@ -0,0 +1,46 @@
+"""Guide layout: a guide clip shares the generated clip's time origin.
+
+The native H3 AddGuide node packs [text | guide rows | references | target] with the guide rows
+at time origin cursor + 5/3 * frame_index, the same origin as the target rows. The Ref2VA layout
+builder gives every video reference its own time slot instead. This wrapper builds the ordinary
+Ref2VA layout with the guides as the LAST references, then rewinds the target rows' time
+coordinate by the slot the first guide occupied so that guides and target share one origin.
+Guides after the first are moved onto the same origin, and a guide with a frame index is offset
+by 5/3 per frame (the native frame-to-time rescale).
+
+Requests without a guide return the builder's layout object unchanged.
+"""
+
+FRAME_RESCALE = 5. / 3.
+
+
+def build(builder, text_token_tags, references, condition_latents, audio_conditions, *args):
+    layout = builder(text_token_tags, references, condition_latents, audio_conditions, *args)
+    guides = [i for i, ref in enumerate(references) if getattr(ref, 'guide', False)]
+    if not guides:
+        return layout
+    count = len(guides)
+    if guides != list(range(len(references) - count, len(references))):
+        raise ValueError('Guide clips must come after all other references')
+    positions, tags, video_ids, audio_ids, text_ids, rows, audio_rows = layout
+    patch_h, patch_w = args[-4][1], args[-4][2]
+    # Guides are silent, so their latents are the last `count` entries of condition_latents.
+    sizes = []
+    for latent in condition_latents[-count:]:
+        sizes.append(latent.shape[2] * (latent.shape[3] // patch_h) * (latent.shape[4] // patch_w))
+    end = rows
+    spans = []
+    for n in reversed(sizes):
+        spans.append(video_ids[:end][-n:])
+        end -= n
+    spans.reverse()
+    audio_start = int(audio_ids[audio_rows:].min())
+    first = float(positions[int(spans[0][0]), 0])
+    shift = float(positions[int(video_ids[rows]), 0]) - first
+    positions[audio_start:, 0] -= shift
+    for span, reference in zip(spans, references[-count:]):
+        offset = first - float(positions[int(span[0]), 0])
+        index = getattr(reference, 'guide_index', 0)
+        if offset or index:
+            positions[span, 0] += offset + FRAME_RESCALE * index
+    return positions, tags, video_ids, audio_ids, text_ids, rows, audio_rows
diff --git a/freevideo_engine/media_conditioning.py b/freevideo_engine/media_conditioning.py
index 09e60cb6..2a067f28 100644
--- a/freevideo_engine/media_conditioning.py
+++ b/freevideo_engine/media_conditioning.py
@@ -98,9 +98,22 @@ def _describe(value, width, height, frames):
         raise ValueError('Ref2VA needs reference latents and no keyframe anchors')
     # Reuse the shared prompt/token validation without pretending references are anchors.
     to_cache([[prompt[None], {'minimax_token_tags': tags}]], task='ref2va')
-    video_rows = audio_rows = 0
+    video_rows = audio_rows = seen_rows = 0
+    guides = 0
     for ref in refs:
         kind = ref.get('kind')
+        if ref.get('guide'):
+            # A guide is an ordinary silent video latent whose rows only differ in
+            # time coordinates (guide_layout), so the shape checks below apply
+            # unchanged. It must come after the other references and has no audio.
+            if kind not in ('image', 'video') or ref.get('audio_latent') is not None or 'early_steps' in ref:
+                raise ValueError('A guide must be a silent video or still with no early_steps')
+            guides += 1
+            index = ref.get('guide_index', 0)
+            if type(index) is not int or not 0 <= index < frames:
+                raise ValueError('Guide frame index is outside the clip')
+        elif guides:
+            raise ValueError('Guide references must come after all other references')
         if 'early_steps' in ref:
             from .media_request import validate_early_steps
             validate_early_steps(ref)
@@ -111,12 +124,16 @@ def _describe(value, width, height, frames):
             if latent.shape[2] < 1 or any(n < 2 or n % 2 for n in latent.shape[-2:]):
                 raise ValueError('Reference latent dimensions must fit H3 patches')
             video_rows += math.prod(latent.shape[2:]) // 4
+            if not ref.get('guide'):
+                seen_rows += math.prod(latent.shape[2:]) // 4
         if kind == 'audio' or ref.get('audio_latent') is not None:
             audio = _tensor(ref.get('audio_latent'), (None, 32), 'reference audio rows')
             if audio.shape[0] % 2:
                 raise ValueError('Reference audio must contain both channels')
             audio_rows += audio.shape[0]
-    if video_rows and not bool((tags == 0).any()):
+    # Guide rows are never shown to the vision-language encoder, so only the
+    # other visual references need jointly encoded vision tokens.
+    if seen_rows and not bool((tags == 0).any()):
         raise ValueError('Visual references need jointly encoded vision tokens')
     task = 'ref2va_av' if video_rows and audio_rows else 'ref2va_audio' if audio_rows else 'ref2va'
     value['task'] = task
@@ -134,11 +151,19 @@ def from_comfy(conditioning, width, height, frames):
     if unknown:
         raise ValueError('Unsupported conditioning modifiers: ' + ', '.join(sorted(unknown)))
     keyframes, refs = extra.get('minimax_keyframes', []), extra.get('minimax_refs', [])
-    if keyframes and refs:
-        raise ValueError('Combined keyframe/reference conditioning is not an official VDN layout')
     anchors = []
+    guides = []
     for item in keyframes:
         index = item.get('resolved_frame_index')
+        if refs:
+            # Keyframes next to references are packed as guides that share the clip's
+            # time origin (same as the native AddGuide node), so any in-clip index
+            # is a valid position; the latent shape guard in describe() still applies.
+            if type(index) is not int or not 0 <= index < frames:
+                raise ValueError('Guide frame index is outside the clip')
+            guides.append(dict(kind='video', guide=True, guide_index=index,
+                               latent=_tensor(item.get('latent'), (1, 24, None, None, None), 'guide video')))
+            continue
         if index not in (0, frames - 1):
             raise ValueError('Only first and last keyframe anchors are supported')
         anchors.append('first' if index == 0 else 'last')
@@ -160,4 +185,5 @@ def from_comfy(conditioning, width, height, frames):
                 audio = _tensor(row.get('audio_latent'), (1, 32, 2, None), 'native reference audio')
                 ref['audio_latent'] = audio[0].permute(1, 2, 0).reshape(-1, 32).contiguous()
             value['references'].append(ref)
+        value['references'].extend(guides)
     return value, describe(value, width, height, frames)
diff --git a/freevideo_engine/media_encoding.py b/freevideo_engine/media_encoding.py
index 4544a681..cacccd8e 100644
--- a/freevideo_engine/media_encoding.py
+++ b/freevideo_engine/media_encoding.py
@@ -135,6 +135,8 @@ def prepare(media, canvas, directory):
         ref = {'kind': kind}
         if 'early_steps' in row:
             ref['early_steps'] = row['early_steps']
+        if row.get('guide'):
+            ref['guide'] = True
         numbers[kind] += 1
         longer, length, used = False, None, limit / 24.
         target = directory / ('reference-%02d.npy' % index)
@@ -183,7 +185,7 @@ def prepare(media, canvas, directory):
                 ref.update(pixels=str(target), frames=count, normalized_fps=24)
                 used = count / 24.
                 # The clip's own sound is a reference too, unless the request turned it off.
-                soundtrack, longer_audio, _ = (None, False, None) if row.get('sound') is False else \
+                soundtrack, longer_audio, _ = (None, False, None) if row.get('sound') is False or row.get('guide') else \
                     _audio(path, directory / ('reference-%02d-audio.npy' % index), limit / 24.)
                 longer = longer or longer_audio
                 if soundtrack:
@@ -191,7 +193,10 @@ def prepare(media, canvas, directory):
                     ref_items.append({'type': 'audio'})
                 selected = list(range(0, count, 12))
                 sampled = torch.from_numpy(np.array(pixels[selected])).float().div_(255)
-                ref_items.append({'type': 'video', 'data': sampled, 'timestamps': [i / 2. for i in range(len(selected))]})
+                if not row.get('guide'):
+                    # A guide only supplies motion latents; it is not described to the
+                    # vision-language encoder, like the native AddGuide node.
+                    ref_items.append({'type': 'video', 'data': sampled, 'timestamps': [i / 2. for i in range(len(selected))]})
                 del pixels
         else:
             ref['audio'], longer, length = _audio(path, target, limit / 24.)
@@ -212,7 +217,7 @@ def reference_options(normalized, options, step):
     """Filter whole references, including a video's optional audio presentation."""
     items, offset = [], 0
     for row in normalized:
-        count = 1 + int(row['kind'] == 'video' and bool(row.get('audio')))
+        count = 0 if row.get('guide') else 1 + int(row['kind'] == 'video' and bool(row.get('audio')))
         if 'early_steps' not in row or step < row['early_steps']:
             items.extend(options['minimax_ref_items'][offset:offset + count])
         offset += count
@@ -289,7 +294,7 @@ def encode_latents(normalized, value, base, canvas, *, resident=None, device='cu
     if torch.device(device).type not in ('cuda', 'mps'):
         raise ValueError('Media encoding requires a CUDA or MPS device')
     empty_cache = torch.mps.empty_cache if torch.device(device).type == 'mps' else torch.cuda.empty_cache
-    refs = [{key: row[key] for key in ('kind', 'early_steps') if key in row} for row in normalized]
+    refs = [{key: row[key] for key in ('kind', 'early_steps', 'guide') if key in row} for row in normalized]
     keys, cache, hits = {}, None, set()
     if cache_root and any(row.get('pixels') for row in normalized):
         # The same picture or clip with another prompt reuses its latent and may skip loading the encoder.
diff --git a/freevideo_engine/media_request.py b/freevideo_engine/media_request.py
index be8d0ec2..f28aa6db 100644
--- a/freevideo_engine/media_request.py
+++ b/freevideo_engine/media_request.py
@@ -55,7 +55,7 @@ def file_info(name):
                 raise ValueError('Invalid ' + field + ' entry')
             if field != 'references' and 'early_steps' in entry:
                 raise ValueError('early_steps is only allowed on video references')
-            allowed = {'path', 'kind', 'early_steps', 'sound'} if field == 'references' else {'path', 'strength', 'alpha'}
+            allowed = {'path', 'kind', 'early_steps', 'sound', 'guide'} if field == 'references' else {'path', 'strength', 'alpha'}
             if set(entry) - allowed:
                 raise ValueError('Unknown ' + field + ' fields')
             row = file_info(entry.get('path'))
@@ -70,6 +70,12 @@ def file_info(name):
                     validate_sound(entry)
                     if not entry['sound']:
                         row['sound'] = False
+                if 'guide' in entry:
+                    validate_guide(entry)
+                    # A false marker is not stored, so requests without a guide
+                    # keep exactly the same rows and cache key as before.
+                    if entry['guide']:
+                        row['guide'] = True
             else:
                 if Path(row['path']).suffix.lower() != '.safetensors':
                     raise ValueError('LoRA requires safetensors; pickle adapters are not loaded')
@@ -81,7 +87,13 @@ def file_info(name):
                     row[name] = number
             result[field].append(row)
     if result['references'] and any(result.get(k) for k in ('first', 'last')):
-        raise ValueError('Reference and keyframe layouts cannot be mixed; use separate requests')
+        raise ValueError('Reference and first/last keyframe layouts cannot be mixed in one request; '
+                         'mark the clip that carries the motion with "guide": true instead')
+    guides = [row for row in result['references'] if row.get('guide')]
+    if len(guides) > 1:
+        raise ValueError('At most one guide clip per request')
+    # The packed layout needs the guide after the other references.
+    result['references'].sort(key=lambda row: bool(row.get('guide')))
     if value.get('conditioning_info') is not None:
         info = value['conditioning_info']
         if not isinstance(info, dict) or info.get('task') not in TASKS:
@@ -114,6 +126,20 @@ def validate_sound(row):
         raise ValueError('Video reference sound must be true or false')
 
 
+def validate_guide(row):
+    """A guide is a video reference that shares the generated clip's time origin.
+
+    It is encoded like a silent video reference, so it cannot carry its own
+    audio or a delayed start.
+    """
+    if row.get('kind') != 'video':
+        raise ValueError('guide is only allowed on video references')
+    if type(row['guide']) is not bool:
+        raise ValueError('Video reference guide must be true or false')
+    if row['guide'] and 'early_steps' in row:
+        raise ValueError('A guide clip cannot use early_steps')
+
+
 def reference_stages(media):
     """Active references at each boundary; zero-step inputs never reach an encoder."""
     refs = media.get('references', [])
diff --git a/freevideo_engine/reference_sampler.py b/freevideo_engine/reference_sampler.py
index 6a011f70..30c2fee5 100644
--- a/freevideo_engine/reference_sampler.py
+++ b/freevideo_engine/reference_sampler.py
@@ -20,7 +20,7 @@
 from src.inference.render import KEYFRAME_NOISE_AUG
 from src.models.hybrid_transform import iter_hybrids, set_layout
 
-from . import step_grid
+from . import guide_layout, step_grid
 
 # Rebound per Engine request by sampler_for_canvas.
 LATENT_H, LATENT_W = 48, 84
@@ -45,14 +45,15 @@ def generate_latents(transformer, prompt_embeds, text_token_tags, num_frames, nu
         raise ValueError('Ref2VA requires references')
     condition_latents = [row['latent'].to(device) for row in refs if row['kind'] in ('image', 'video')]
     audio_conditions = [row['audio_latent'].to(device) for row in refs if row.get('audio_latent') is not None]
-    references = [SimpleNamespace(kind=row['kind'], has_audio=row.get('audio_latent') is not None) for row in refs]
+    references = [SimpleNamespace(kind=row['kind'], has_audio=row.get('audio_latent') is not None,
+                                  guide=bool(row.get('guide')), guide_index=row.get('guide_index', 0)) for row in refs]
     patch = tuple(transformer.config.patch_size)                    # (1, 2, 2)
     channels = transformer.config.in_channels                       # 24
     frame_h, frame_w = LATENT_H // patch[1], LATENT_W // patch[2]
 
     def make_layout(text_token_tags, references, condition_latents, audio_conditions):
         position_ids, token_tags, video_indices, audio_indices, text_indices, num_condition_rows, num_audio_condition_rows = (
-            MiniMaxH3Ref2VAPrepareLayoutStep.build_ref2va_packed_sequence(
+            guide_layout.build(MiniMaxH3Ref2VAPrepareLayoutStep.build_ref2va_packed_sequence,
                 text_token_tags, references, condition_latents, audio_conditions, num_latent_frames, LATENT_H, LATENT_W, num_audio_latents,
                 patch, AUDIO_CHANNELS, AUDIO_TAG, VIDEO_TAG,
             )
@@ -134,7 +135,8 @@ def synchronize():
             generated_audio = audio_rows[num_audio_condition_rows:]
             keep_video = [i for i, row in enumerate(visual_refs) if row.get('early_steps', step + 1) > step]
             keep_audio = [i for i, row in enumerate(audio_refs) if row.get('early_steps', step + 1) > step]
-            references = [SimpleNamespace(kind=row['kind'], has_audio=row.get('audio_latent') is not None)
+            references = [SimpleNamespace(kind=row['kind'], has_audio=row.get('audio_latent') is not None,
+                                          guide=bool(row.get('guide')), guide_index=row.get('guide_index', 0))
                           for row in value.get('references', [])]
             prompt_embeds = value['prompt_embeds'].to(device=device, dtype=prompt_embeds.dtype)
             previous_audio_condition_rows = num_audio_condition_rows
diff --git a/freevideo_engine/refine.py b/freevideo_engine/refine.py
index ee9373d7..f535d3f6 100644
--- a/freevideo_engine/refine.py
+++ b/freevideo_engine/refine.py
@@ -61,8 +61,10 @@ def generate_latents(transformer, prompt_embeds, text_token_tags, num_frames, nu
         refs = conditions
         condition_latents = [row['latent'].to(device) for row in refs if row['kind'] in ('image', 'video')]
         audio_conditions = [row['audio_latent'].to(device) for row in refs if row.get('audio_latent') is not None]
-        references = [SimpleNamespace(kind=row['kind'], has_audio=row.get('audio_latent') is not None) for row in refs]
-        layout = MiniMaxH3Ref2VAPrepareLayoutStep.build_ref2va_packed_sequence(
+        references = [SimpleNamespace(kind=row['kind'], has_audio=row.get('audio_latent') is not None,
+                                      guide=bool(row.get('guide')), guide_index=row.get('guide_index', 0)) for row in refs]
+        from . import guide_layout
+        layout = guide_layout.build(MiniMaxH3Ref2VAPrepareLayoutStep.build_ref2va_packed_sequence,
             text_token_tags, references, condition_latents, audio_conditions,
             latent_frames, LATENT_H, LATENT_W, audio_frames, patch, AUDIO_CHANNELS, AUDIO_TAG, VIDEO_TAG)
     else:
diff --git a/freevideo_engine/sampling_assets.py b/freevideo_engine/sampling_assets.py
index 0f96f9ad..4911f5a0 100644
--- a/freevideo_engine/sampling_assets.py
+++ b/freevideo_engine/sampling_assets.py
@@ -187,7 +187,7 @@ def engine_task(media, base=None):
     for ref in media.get('references', []):
         visual |= ref['kind'] in ('image', 'video')
         audio |= ref['kind'] == 'audio'
-        if ref['kind'] == 'video' and not audio and ref.get('sound') is not False:
+        if ref['kind'] == 'video' and not audio and ref.get('sound') is not False and not ref.get('guide'):
             path = Path(ref['path'])
             if base is not None and not path.is_absolute():
                 path = Path(base) / path
diff --git a/freevideo_engine/tuning.py b/freevideo_engine/tuning.py
index dc206593..8c6f9a60 100644
--- a/freevideo_engine/tuning.py
+++ b/freevideo_engine/tuning.py
@@ -22,7 +22,7 @@
 
 SCHEMA = 1
 COMPUTE_FILES = ('activation_staging.py', 'residual.py', 'adaln.py', 'adaln_assets.py', 'attention.py', 'blocks.py',
-                 'keyframes.py', 'media_request.py', 'media_conditioning.py', 'media_encoding.py', 'reference_sampler.py', 'lora_cache.py',
+                 'keyframes.py', 'guide_layout.py', 'media_request.py', 'media_conditioning.py', 'media_encoding.py', 'reference_sampler.py', 'lora_cache.py',
                  'conditioning.py', 'decode.py', 'decode_prefetch.py', 'resident_models.py', 'decode_stream.py', 'streamed_weights.py', 'encode_worker.py', 'idle_encoder.py', 'media_encoding.py', 'fp8.py', 'fp8_ops.py', 'fp8_gemm.py', 'int8_ops.py',
                  'encoder_precision.py', 'encoder_lowmem.py',
                  'kernel_capabilities.py', 'gpu_budget.py', 'worker.py', 'resident_worker.py', 'failure_cleanup.py',

From 686691eccb7365b5456d9090aa27f586d2bc1bda Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Thu, 22 Oct 2026 01:52:50 +0000
Subject: [PATCH 18/52] Keep the guide clip's sound on a guide-based result
 when requested

A guide reference can carry "keep_source_audio": true. After a successful run the finished MP4 is remuxed: the video stream is copied packet by packet and the audio stream is replaced by the guide clip own audio, trimmed or padded with silence to the video length. The flag needs a guide clip with an audio stream, is validated at request read, and does not enter the conditioning cache key. Requests without it are unchanged.
---
 freevideo_engine/generate.py      |  3 +
 freevideo_engine/guide_audio.py   | 95 +++++++++++++++++++++++++++++++
 freevideo_engine/media_request.py | 21 ++++++-
 3 files changed, 117 insertions(+), 2 deletions(-)
 create mode 100644 freevideo_engine/guide_audio.py

diff --git a/freevideo_engine/generate.py b/freevideo_engine/generate.py
index 2da7746a..5b219b6e 100644
--- a/freevideo_engine/generate.py
+++ b/freevideo_engine/generate.py
@@ -1164,6 +1164,9 @@ def retry(index, row, selected, decision):
                 shutil.copyfile(destination.with_suffix('.engine.json'), artifacts / 'first-pass.engine.json')
                 from .preview import upscale_reads
                 report['preview']['upscale_reads'] = upscale_reads(request['cache'], report['video'], upscaler_checkpoint)
+            if not preview and any(row.get('keep_source_audio') for row in media.get('references', [])):
+                from .guide_audio import apply as keep_source_audio
+                report['keep_source_audio'] = keep_source_audio(destination, media)
             report['success'] = True
     except BaseException as error:
         from .diagnostic_resources import exception_details
diff --git a/freevideo_engine/guide_audio.py b/freevideo_engine/guide_audio.py
new file mode 100644
index 00000000..d70b6e91
--- /dev/null
+++ b/freevideo_engine/guide_audio.py
@@ -0,0 +1,95 @@
+"""Keep the guide clip's own sound on a finished guide-based result.
+
+The video stream is copied packet by packet; only the audio stream is replaced, with
+the guide's audio trimmed or padded with silence to the video length. Requests
+without "keep_source_audio" never reach this module.
+"""
+from fractions import Fraction
+from pathlib import Path
+
+import av
+import numpy as np
+
+
+def has_audio(path):
+    try:
+        with av.open(str(path)) as container:
+            return bool(container.streams.audio)
+    except av.error.FFmpegError as error:
+        raise ValueError('Cannot read the guide clip: %s' % error) from error
+
+
+def _video_seconds(container, stream):
+    end = 0
+    for packet in container.demux(stream):
+        if packet.pts is not None and packet.duration is not None:
+            end = max(end, packet.pts + packet.duration)
+    if not end:
+        raise ValueError('Cannot measure the video length')
+    return float(end * stream.time_base)
+
+
+def _guide_samples(path, rate, layout):
+    """Decode the guide's first audio stream to float planar samples at the output format."""
+    blocks = []
+    with av.open(str(path)) as container:
+        stream = container.streams.audio[0]
+        resampler = av.AudioResampler(format='fltp', layout=layout, rate=rate)
+        for frame in container.decode(stream):
+            for out in resampler.resample(frame):
+                blocks.append(out.to_ndarray())
+        for out in resampler.resample(None):
+            blocks.append(out.to_ndarray())
+    channels = len(av.AudioLayout(layout).channels)
+    return np.concatenate(blocks, axis=1) if blocks else np.zeros((channels, 0), np.float32)
+
+
+def replace_audio(video, guide, output, *, rate=48000, layout='stereo'):
+    """Write ``output``: ``video``'s picture untouched plus ``guide``'s audio fitted to its length."""
+    video, guide, output = Path(video), Path(guide), Path(output)
+    if not has_audio(guide):
+        raise ValueError('The guide clip has no audio stream')
+    with av.open(str(video)) as source:
+        picture = source.streams.video[0]
+        seconds = _video_seconds(source, picture)
+    wanted = round(seconds * rate)
+    samples = _guide_samples(guide, rate, layout)[:, :wanted]
+    if samples.shape[1] < wanted:
+        samples = np.pad(samples, ((0, 0), (0, wanted - samples.shape[1])))
+    with av.open(str(video)) as source, av.open(str(output), 'w', format='mp4') as result:
+        picture = source.streams.video[0]
+        copied = result.add_stream_from_template(picture)
+        sound = result.add_stream('aac', rate=rate, layout=layout)
+        for packet in source.demux(picture):
+            if packet.dts is None:
+                continue
+            packet.stream = copied
+            result.mux(packet)
+        position = 0
+        while position < wanted:
+            block = np.ascontiguousarray(samples[:, position:position + 1024])
+            frame = av.AudioFrame.from_ndarray(block, format='fltp', layout=layout)
+            frame.sample_rate = rate
+            frame.pts = position
+            frame.time_base = Fraction(1, rate)
+            for packet in sound.encode(frame):
+                result.mux(packet)
+            position += block.shape[1]
+        for packet in sound.encode(None):
+            result.mux(packet)
+    return seconds
+
+
+def apply(video, media):
+    """Replace ``video`` in place when the request's guide asks to keep its audio. Returns True if replaced."""
+    guide = next((row for row in media.get('references', []) if row.get('guide') and row.get('keep_source_audio')), None)
+    if guide is None:
+        return False
+    video = Path(video)
+    temporary = video.with_name(video.stem + '.remux.mp4')
+    try:
+        replace_audio(video, guide['path'], temporary)
+        temporary.replace(video)
+    finally:
+        temporary.unlink(missing_ok=True)
+    return True
diff --git a/freevideo_engine/media_request.py b/freevideo_engine/media_request.py
index f28aa6db..56571c79 100644
--- a/freevideo_engine/media_request.py
+++ b/freevideo_engine/media_request.py
@@ -55,7 +55,7 @@ def file_info(name):
                 raise ValueError('Invalid ' + field + ' entry')
             if field != 'references' and 'early_steps' in entry:
                 raise ValueError('early_steps is only allowed on video references')
-            allowed = {'path', 'kind', 'early_steps', 'sound', 'guide'} if field == 'references' else {'path', 'strength', 'alpha'}
+            allowed = {'path', 'kind', 'early_steps', 'sound', 'guide', 'keep_source_audio'} if field == 'references' else {'path', 'strength', 'alpha'}
             if set(entry) - allowed:
                 raise ValueError('Unknown ' + field + ' fields')
             row = file_info(entry.get('path'))
@@ -76,6 +76,10 @@ def file_info(name):
                     # keep exactly the same rows and cache key as before.
                     if entry['guide']:
                         row['guide'] = True
+                if 'keep_source_audio' in entry:
+                    validate_keep_source_audio(entry, row['path'])
+                    if entry['keep_source_audio']:
+                        row['keep_source_audio'] = True
             else:
                 if Path(row['path']).suffix.lower() != '.safetensors':
                     raise ValueError('LoRA requires safetensors; pickle adapters are not loaded')
@@ -140,6 +144,19 @@ def validate_guide(row):
         raise ValueError('A guide clip cannot use early_steps')
 
 
+def validate_keep_source_audio(row, path):
+    """Keeping the guide's sound needs a guide clip that has an audio stream."""
+    if type(row['keep_source_audio']) is not bool:
+        raise ValueError('keep_source_audio must be true or false')
+    if not row['keep_source_audio']:
+        return
+    if row.get('guide') is not True:
+        raise ValueError('keep_source_audio is only allowed on a guide clip')
+    from .guide_audio import has_audio
+    if not has_audio(path):
+        raise ValueError('keep_source_audio needs a guide clip with an audio stream')
+
+
 def reference_stages(media):
     """Active references at each boundary; zero-step inputs never reach an encoder."""
     refs = media.get('references', [])
@@ -160,7 +177,7 @@ def cache_key(prompt, media, canvas):
     for key in ('first', 'last', 'references'):
         value = media.get(key)
         if value:
-            identity[key] = [{k: v for k, v in row.items() if k != 'path'}
+            identity[key] = [{k: v for k, v in row.items() if k not in ('path', 'keep_source_audio')}
                              for row in value] if isinstance(value, list) else value['sha256']
     return 'multimodal:' + json.dumps(identity, sort_keys=True, ensure_ascii=False)
 

From b79aa97cae3ed27f905dbf792a8d59c9e564cbd1 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Thu, 22 Oct 2026 02:02:01 +0000
Subject: [PATCH 19/52] Keep a finished video when the guide audio remux fails

A failed keep_source_audio remux no longer fails the run: the generated video
stays untouched, the temporary file is removed, and the report records
keep_source_audio_failed with a short reason while success stays true.
---
 freevideo_engine/generate.py    |  4 ++--
 freevideo_engine/guide_audio.py | 13 +++++++++++++
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/freevideo_engine/generate.py b/freevideo_engine/generate.py
index 5b219b6e..243ddceb 100644
--- a/freevideo_engine/generate.py
+++ b/freevideo_engine/generate.py
@@ -1165,8 +1165,8 @@ def retry(index, row, selected, decision):
                 from .preview import upscale_reads
                 report['preview']['upscale_reads'] = upscale_reads(request['cache'], report['video'], upscaler_checkpoint)
             if not preview and any(row.get('keep_source_audio') for row in media.get('references', [])):
-                from .guide_audio import apply as keep_source_audio
-                report['keep_source_audio'] = keep_source_audio(destination, media)
+                from .guide_audio import apply_to_report as keep_source_audio
+                keep_source_audio(destination, media, report)
             report['success'] = True
     except BaseException as error:
         from .diagnostic_resources import exception_details
diff --git a/freevideo_engine/guide_audio.py b/freevideo_engine/guide_audio.py
index d70b6e91..4633534d 100644
--- a/freevideo_engine/guide_audio.py
+++ b/freevideo_engine/guide_audio.py
@@ -93,3 +93,16 @@ def apply(video, media):
     finally:
         temporary.unlink(missing_ok=True)
     return True
+
+
+def apply_to_report(video, media, report):
+    """Run ``apply`` after a successful generation; a failed remux leaves the finished video as it is.
+
+    The result is recorded in ``report``: ``keep_source_audio`` is True when the audio was replaced,
+    and ``keep_source_audio_failed`` holds a short reason when it could not be.
+    """
+    try:
+        report['keep_source_audio'] = apply(video, media)
+    except Exception as error:  # the video is already complete and valid; only the audio swap failed
+        report['keep_source_audio'] = False
+        report['keep_source_audio_failed'] = ('%s: %s' % (type(error).__name__, error))[:300]

From e7f0e9611c8c14abf654d5dec4d5e0636334c83f Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Thu, 22 Oct 2026 09:43:55 +0000
Subject: [PATCH 20/52] Add Replace person to the Studio media section

---
 freevideo_engine/comfy_assets.py |   9 ++-
 freevideo_engine/comfy_upload.py |  10 ++-
 web/freevideo.js                 |  22 +++++-
 web/generation_progress.js       |   5 ++
 web/health.js                    |   2 +-
 web/prompt_references.js         |   8 +-
 web/replace_person.js            | 128 +++++++++++++++++++++++++++++++
 web/replace_state.js             |  85 ++++++++++++++++++++
 web/studio.css                   |  17 ++++
 web/studio.js                    |  65 ++++++++++++++--
 10 files changed, 336 insertions(+), 15 deletions(-)
 create mode 100644 web/replace_person.js
 create mode 100644 web/replace_state.js

diff --git a/freevideo_engine/comfy_assets.py b/freevideo_engine/comfy_assets.py
index 0ed3b95c..5c3db2db 100644
--- a/freevideo_engine/comfy_assets.py
+++ b/freevideo_engine/comfy_assets.py
@@ -75,7 +75,7 @@ def resolve_assets(serialized, input_directory):
     root = Path(input_directory).resolve()
     result = {}
     for row in rows:
-        if not isinstance(row, dict) or set(row) - {'file', 'role', 'enabled', 'cast', 'early_steps', 'sound', 'guide'}:
+        if not isinstance(row, dict) or set(row) - {'file', 'role', 'enabled', 'cast', 'early_steps', 'sound', 'guide', 'keep_source_audio'}:
             raise ValueError('Invalid media item')
         # The character an @ mention added the row for; a continued part keeps one picture per character.
         if 'cast' in row and (set(row['cast'] if isinstance(row['cast'], dict) else ('?',)) != {'id'}
@@ -122,6 +122,11 @@ def resolve_assets(serialized, input_directory):
                 validate_guide(dict(row, kind=kind))
                 if row['guide']:
                     reference['guide'] = True
+            if 'keep_source_audio' in row:
+                from .media_request import validate_keep_source_audio
+                validate_keep_source_audio(dict(row, kind=kind), path)
+                if row['keep_source_audio']:
+                    reference['keep_source_audio'] = True
             result.setdefault('references', []).append(reference)
         else:
             raise ValueError('Media role must be first, last or reference')
@@ -227,6 +232,8 @@ def output_summary(report, relative_video):
                 video=relative_video.as_posix(), report=relative_video.with_suffix(
                     '.debug.json' if report.get('diagnostic_file') == relative_video.with_suffix('.debug.json').name
                     else '.request.json').as_posix())
+    if report.get('keep_source_audio_failed'):
+        result['keep_source_audio_failed'] = True
     if type(report.get('output_frames')) is int and report['output_frames'] > 0:
         # Resource reports keep the generated canvas; result cards show only saved frames.
         result['geometry'].update(frames=report['output_frames'],
diff --git a/freevideo_engine/comfy_upload.py b/freevideo_engine/comfy_upload.py
index cc7b408c..175afa8e 100644
--- a/freevideo_engine/comfy_upload.py
+++ b/freevideo_engine/comfy_upload.py
@@ -55,7 +55,15 @@ async def receive(reader, input_directory):
     except BaseException:
         shutil.rmtree(folder, ignore_errors=True)
         raise
-    return {'file': destination.relative_to(base).as_posix(), 'bytes': size}
+    result = {'file': destination.relative_to(base).as_posix(), 'bytes': size}
+    if media_kind(name) == 'video':
+        # Whether the clip has a sound track; the Replace person option is greyed out without one.
+        try:
+            from .guide_audio import has_audio
+            result['audio'] = await asyncio.to_thread(has_audio, destination)
+        except Exception:
+            pass
+    return result
 
 
 def register():
diff --git a/web/freevideo.js b/web/freevideo.js
index a5392780..7512ac52 100644
--- a/web/freevideo.js
+++ b/web/freevideo.js
@@ -6,7 +6,7 @@ import { api } from "../../scripts/api.js";
 import { openEditorView } from './editor_loader.js';
 import { beginWorkspaceRestore, finishWorkspaceRestore, waitForLauncherRestore } from './workspace_restore.js';
 import { openStudio, loraPanel, loraWarning, promptGuide } from "./studio.js";
-import { createGenerationProgress, referenceTrimText, thermalText, sharedGpuText, encoderFileText, encoderFilePath } from './generation_progress.js';
+import { createGenerationProgress, referenceTrimText, thermalText, sharedGpuText, keepSoundText, encoderFileText, encoderFilePath } from './generation_progress.js';
 import { createProgressConnection } from './progress_connection.js';
 import { notifyCompatibility } from './compatibility.js';
 import { startUpdateChecks } from './updates.js';
@@ -16,7 +16,7 @@ import { installNavigation, refreshNavigation, preferredView, collapseWorkspaces
 import { isLaunchVisit } from './launch_visit.js';
 import { openFreeVideoWorkflow } from './launcher.js';
 import { agentInterfaceState } from './agent_connect.js';
-import { attachReferencePicker, referenceItems, syncReferencePrompt, referenceInputs, mediaRows } from './prompt_references.js';
+import { attachReferencePicker, referenceItems, syncReferencePrompt, referenceInputs, mediaRows, mediaNodeOf } from './prompt_references.js';
 import { expandCast } from './cast_mention.js';
 import { outputDownloadURL } from './output_download.js';
 import { shareButton } from './share.js';
@@ -29,6 +29,8 @@ import { openImageEditor, icon } from './image_editor.js';
 import { imageGenerationSupported } from './image_generation.js';
 import { createCastLibrary } from './cast_library.js';
 import { uploadMedia } from './media_upload.js';
+import { swapState, requestRows, swapMissing, withPrefix } from './replace_state.js';
+import { swapMissingText } from './replace_person.js';
 import { issueButton } from './issue_button.js';
 
 const languageOverride = typeof location !== 'undefined'
@@ -366,6 +368,12 @@ function mediaPanel(node, mount = null) {
     let uploading = false;
     serialized.serializeValue = () => {
         if (node.isUploading) throw new Error(text("Wait for media uploads to finish before running", "请等待素材上传完成后再生成"));
+        // Replace person: the two slots are the media, and both are needed.
+        if (swapState(node)) {
+            const missing = swapMissing(swapState(node));
+            if (missing) throw new Error(swapMissingText(missing, text));
+            return JSON.stringify(requestRows(swapState(node)));
+        }
         // The run takes only what it uses (and which character a picture belongs to); the editing data of a picture stays in the workflow.
         try { return JSON.stringify(read().map(({file, role, enabled, cast, sound}) => ({file, role, enabled, ...(sound === false && mediaKindOrNull(file) === 'video' ? {sound: false} : {}), ...(typeof cast?.id === 'string' && cast.id ? {cast: {id: cast.id}} : {})}))); } catch { return serialized.value; }
     };
@@ -578,6 +586,7 @@ function resultPanel(node) {
         if (value.thermal && !value.result_cache_hit) resultNotes.push(el("div", thermalText(value.thermal, text), "fv-note"));
         const shared = value.shared_gpu && !value.result_cache_hit ? sharedGpuText(value.shared_gpu, text) : '';
         if (shared) resultNotes.push(el("div", shared, "fv-note"));
+        if (value.keep_source_audio_failed) resultNotes.push(el("div", keepSoundText(text), "fv-note"));
         if (value.encoder_file) {
             const note = el("div", encoderFileText(value.encoder_file, text), "fv-note");
             const path = encoderFilePath(value.encoder_file);
@@ -754,7 +763,14 @@ app.registerExtension({
                 }
                 // Characters mentioned with @ travel as <Subject N> plus their definitions; the draft keeps the typed names.
                 const prompt = this.widgets?.find(w => w.name === 'text');
-                if (prompt) { const owner = this; prompt.serializeValue = () => expandCast(prompt.value, mediaRows(owner), {continued: Boolean(owner.freevideoContinues?.())}).text; }
+                if (prompt) {
+                    const owner = this;
+                    // Replace person asks for its prefix here, where every way of running the node reads the text.
+                    prompt.serializeValue = () => {
+                        const body = expandCast(prompt.value, mediaRows(owner), {continued: Boolean(owner.freevideoContinues?.())}).text;
+                        return swapState(mediaNodeOf(owner)) ? withPrefix(body) : body;
+                    };
+                }
                 const quality = this.widgets?.find(w => w.name === 'two_pass');
                 if (quality) {
                     quality.label = text('Two-pass acceleration', '二次采样加速');
diff --git a/web/generation_progress.js b/web/generation_progress.js
index d72fde4d..ae7429d7 100644
--- a/web/generation_progress.js
+++ b/web/generation_progress.js
@@ -270,6 +270,11 @@ export function sharedGpuText(shared, t) {
         `其他程序占用了约 ${percent}% 的显卡。`);
 }
 
+// Replace person: the source video's sound was asked for and could not be put into the video.
+export function keepSoundText(t) {
+    return t('The source video sound could not be kept. The video uses generated sound.', '未能保留源视频声音，成片使用生成的声音。');
+}
+
 export function encoderFilePath(file) {
     return file?.offline_installation === true && typeof file.path === 'string' ? file.path : '';
 }
diff --git a/web/health.js b/web/health.js
index c511e8d0..468ad2f8 100644
--- a/web/health.js
+++ b/web/health.js
@@ -17,7 +17,7 @@ export const MODULES = ['chat_data.js', 'phone_model.js', 'phone.js', 'lan_acces
     'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
     'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js',
-    'result_actions.js', 'sampling_effort.js', 'setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'optional_inputs.js', 'studio_queue.js', 'studio_size.js',
+    'result_actions.js', 'sampling_effort.js', 'setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'studio_queue.js', 'studio_size.js',
     'toolbar_position.js', 'updates.js', 'view_navigation.js', 'wordmark.js', 'workspace_restore.js', 'cast_library.js', 'media_upload.js', 'whitebox_encode.js', 'whitebox_mp4.js', 'whitebox_recording.js', 'whitebox_render.js', 'whitebox_scenes.js', 'whitebox_worker.js'];
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 let visibleAt = 0;
diff --git a/web/prompt_references.js b/web/prompt_references.js
index 483e381e..83919bd0 100644
--- a/web/prompt_references.js
+++ b/web/prompt_references.js
@@ -1,6 +1,7 @@
 // H3 numbers each reference kind separately, in the order of comfy_media.export.
 import {caretRect} from './caret_rect.js';
 import {listenDialogKey} from './dialog_keys.js';
+import {effectiveRows} from './replace_state.js';
 const titles = {image: 'Picture', video: 'Video', audio: 'Audio'};
 const widget = (node, name) => node?.widgets?.find(w => w.name === name);
 const linkFor = (node, name) => node?.graph?.links?.[node.inputs?.find(i => i.name === name)?.link];
@@ -14,8 +15,9 @@ export function referenceKind(file) {
 }
 
 // The raw media list a generate node reads, [] when there is none or it cannot be read.
+export const mediaNodeOf = node => sourceFor(node, 'media');
 export function mediaRows(node) {
-    try { const rows = JSON.parse(widget(sourceFor(node, 'media'), 'assets')?.value || '[]'); return Array.isArray(rows) ? rows : []; } catch { return []; }
+    try { const owner = sourceFor(node, 'media'), rows = effectiveRows(owner, widget(owner, 'assets')); return Array.isArray(rows) ? rows : []; } catch { return []; }
 }
 
 export function referenceItems(node) {
@@ -31,14 +33,14 @@ export function referenceItems(node) {
         if (['first','last','references'].some(name => linkFor(node, name))) throw new Error('invalid_media');
         const serialized = widget(media, 'assets');
         if (!serialized) throw new Error('unknown_references');
-        const rows = JSON.parse(serialized.value || '[]'), counts = new Map();
+        const rows = effectiveRows(media, serialized), counts = new Map();
         if (!Array.isArray(rows)) throw new Error('invalid_media');
         for (const row of rows) {
             const occurrence = counts.get(row.file) || 0; counts.set(row.file, occurrence + 1);
             if (row.enabled === false) continue;
             const kind = referenceKind(row.file);
             if (!kind) throw new Error('invalid_media');
-            const item = {key: `file:${media.id}:${row.file}:${occurrence}`, kind, file: row.file,
+            const item = {key: row.slot ? `swap:${media.id}:${row.slot}` : `file:${media.id}:${row.file}:${occurrence}`, kind, file: row.file,
                 name: row.cast?.name || row.file.split('/').pop(), assetIndex: rows.indexOf(row),
                 ...(row.sound === false && kind === 'video' ? {sound: false} : {})};
             if (row.role === 'reference') refs.push(item);
diff --git a/web/replace_person.js b/web/replace_person.js
new file mode 100644
index 00000000..a627b772
--- /dev/null
+++ b/web/replace_person.js
@@ -0,0 +1,128 @@
+// Replace person: a source video and a person image in the Media section.
+// The state lives in the Media node's properties, so the ordinary media list is never touched
+// and comes back unchanged when the option is turned off.
+import { referenceKind } from './prompt_references.js';
+import { uploadMedia } from './media_upload.js';
+import { firstFrameRow } from './first_frame_row.js';
+import { swapState, swapRows, effectiveRows, keepsSound, withPrefix, swapMissing, SWAP_LORA, SWAP_PREFIX, MIN_SOURCE_SECONDS, SWAP_KEY } from './replace_state.js';
+
+export {swapState, swapRows, effectiveRows, keepsSound, withPrefix, swapMissing, SWAP_LORA, SWAP_PREFIX, MIN_SOURCE_SECONDS};
+const KEY = SWAP_KEY;
+
+// A first or last frame, in the media list or on a connected input, rules the option out.
+export function framesPresent(media) {
+    try {
+        const rows = JSON.parse(media?.widgets?.find(w => w.name === 'assets')?.value || '[]');
+        if (rows.some(row => row.enabled !== false && (row.role === 'first' || row.role === 'last'))) return true;
+    } catch {}
+    return Boolean(media?.inputs?.some(input => (input.name === 'first' || input.name === 'last') && input.link != null));
+}
+
+// What is still missing, in one line (t picks the language).
+export const swapMissingText = (missing, t) => missing === 'source' ? t('Add a source video first.', '请先添加源视频。')
+    : missing === 'person' ? t('Add a person image first.', '请先添加人物图。') : t('Add a source video and a person image first.', '请先添加源视频和人物图。');
+
+const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
+
+function videoSeconds(file) {
+    return new Promise(resolve => {
+        const url = URL.createObjectURL(file), probe = document.createElement('video');
+        const done = value => { clearTimeout(timer); probe.removeAttribute('src'); probe.load(); URL.revokeObjectURL(url); resolve(value); };
+        const timer = setTimeout(() => done(null), 5000);
+        probe.preload = 'metadata'; probe.muted = true;
+        probe.onloadedmetadata = () => done(Number.isFinite(probe.duration) ? probe.duration : null);
+        probe.onerror = () => done(null);
+        probe.src = url;
+    });
+}
+
+// mount: the Media section body. onChange runs after any change to the state.
+export function createReplacePerson({t, api, media, mount, view, onChange = () => {}}) {
+    const stored = () => media.properties?.[KEY];
+    const state = () => { media.properties ??= {}; return media.properties[KEY] ??= {on: false, source: null, person: null, keepSound: false}; };
+    const save = info => { media.graph?.change?.(); onChange(info); paint(); };
+    const toggle = firstFrameRow(t, 'fv-first-frame fv-replace-person');
+    toggle.row.firstChild.textContent = t('Replace person', '替换人物');
+    toggle.input.setAttribute('aria-label', t('Replace person', '替换人物'));
+    toggle.row.title = '';
+    const slots = el('div', 'fv-swap-slots'), note = el('div', 'fv-note fv-swap-note'); note.setAttribute('role', 'status');
+    const blockedTitle = t('Not available with first and last frames', '首尾帧不能和替换人物同时使用');
+    function slot(kind) {
+        const box = el('div', 'fv-swap-slot'), title = el('div', 'fv-swap-title', kind === 'video' ? t('Source video', '源视频') : t('Person image', '人物图'));
+        const body = el('button', 'fv-swap-drop'); body.type = 'button';
+        const input = el('input'); input.type = 'file'; input.hidden = true;
+        input.accept = kind === 'video' ? 'video/*,.mp4,.mov,.webm,.mkv,.m4v' : 'image/*,.png,.jpg,.jpeg,.webp,.bmp,.tif,.tiff';
+        body.onclick = () => input.click();
+        input.onchange = () => { const [file] = input.files; input.value = ''; if (file) choose(kind, file); };
+        for (const name of ['dragover', 'dragenter']) box.addEventListener(name, event => { event.preventDefault(); event.stopPropagation(); });
+        box.addEventListener('drop', event => {
+            event.preventDefault(); event.stopPropagation();
+            const file = Array.from(event.dataTransfer?.files || []).find(f => referenceKind(f.name) === (kind === 'video' ? 'video' : 'image'));
+            if (file) choose(kind, file);
+        });
+        box.append(title, body, input);
+        return {box, body, kind};
+    }
+    const source = slot('video'), person = slot('image');
+    const sound = el('label', 'fv-swap-sound', t('Keep source video sound', '保留源视频声音'));
+    const soundInput = el('input'); soundInput.type = 'checkbox'; sound.prepend(soundInput);
+    soundInput.onchange = () => { state().keepSound = soundInput.checked; save(); };
+    source.box.classList.add('fv-swap-source'); person.box.classList.add('fv-swap-person');
+    slots.append(source.box, person.box, sound);
+    mount.prepend(toggle.row, slots, note);
+    let busy = false;
+    async function choose(kind, file) {
+        if (busy || media.isUploading) return;
+        note.textContent = '';
+        if (referenceKind(file.name) !== (kind === 'video' ? 'video' : 'image')) {
+            note.textContent = kind === 'video' ? t('Choose a video file.', '请选择视频文件。') : t('Choose an image file.', '请选择图片文件。');
+            paint(); return;
+        }
+        if (kind === 'video') {
+            const seconds = await videoSeconds(file);
+            if (seconds !== null && seconds < MIN_SOURCE_SECONDS) { note.textContent = t('The source video must be at least 1 second long.', '源视频至少需要 1 秒。'); return; }
+        }
+        busy = true; media.isUploading = true; paint();
+        try {
+            const result = await uploadMedia(api, file);
+            const next = state();
+            if (kind === 'video') { next.source = {file: result.file, audio: result.audio === true}; if (!next.source.audio) next.keepSound = false; }
+            else next.person = {file: result.file};
+            save();
+        } catch (error) { note.textContent = error.message; }
+        finally { busy = false; media.isUploading = false; paint(); }
+    }
+    function fill(part, entry, empty) {
+        part.body.replaceChildren();
+        part.body.classList.toggle('fv-swap-filled', Boolean(entry));
+        if (!entry) { part.body.append(el('span', 'fv-swap-plus', '+'), el('span', 'fv-swap-sub', empty)); part.body.title = empty; return; }
+        const thumb = part.kind === 'video' ? el('video', 'fv-swap-thumb') : el('img', 'fv-swap-thumb');
+        if (part.kind === 'video') { thumb.muted = true; thumb.preload = 'metadata'; thumb.src = view(entry.file) + '#t=0.1'; }
+        else { thumb.alt = ''; thumb.src = view(entry.file); }
+        part.body.append(thumb, el('span', 'fv-swap-name', entry.file.split('/').pop()));
+        part.body.title = entry.file.split('/').pop();
+    }
+    function paint() {
+        const current = stored(), on = current?.on === true, blocked = framesPresent(media);
+        toggle.input.checked = on;
+        toggle.setDisabled(Boolean(busy) || (blocked && !on));
+        toggle.input.title = blocked && !on ? blockedTitle : '';
+        toggle.row.classList.toggle('fv-swap-blocked', blocked && !on);
+        slots.hidden = !on; note.hidden = !on || !note.textContent;
+        mount.classList.toggle('fv-swap-on', on);
+        fill(source, current?.source, t('Add video', '添加视频'));
+        fill(person, current?.person, t('Add image', '添加图片'));
+        const audio = current?.source?.audio === true;
+        sound.hidden = !on; soundInput.disabled = busy || !audio; soundInput.checked = audio && current?.keepSound === true;
+    }
+    toggle.input.onchange = () => {
+        if (toggle.input.checked && framesPresent(media)) { toggle.input.checked = false; return; }
+        state().on = toggle.input.checked; note.textContent = '';
+        save({toggled: true});
+    };
+    paint();
+    const changed = event => { if (String(event.detail) === String(media.id)) paint(); };
+    window.addEventListener('freevideo-media', changed);
+    return {paint, notify(message) { note.textContent = message || ''; paint(); }, get on() { return swapState(media) !== null; }, element: toggle.row,
+        dispose() { window.removeEventListener('freevideo-media', changed); }};
+}
diff --git a/web/replace_state.js b/web/replace_state.js
new file mode 100644
index 00000000..e9b8db83
--- /dev/null
+++ b/web/replace_state.js
@@ -0,0 +1,85 @@
+// Replace person: the saved state and the rules built on it. No imports, so any module (the media list, the prompt
+// numbering, the request) can read it without a cycle; the panel itself is in replace_person.js.
+export const SWAP_LORA = 'alissonerdx-v1.1.safetensors';
+export const SWAP_PREFIX = 'body_swap:';
+export const MIN_SOURCE_SECONDS = 22 / 24; // the engine needs 22 frames
+export const SWAP_KEY = 'freevideo_replace_person';
+
+export const swapState = media => {
+    const state = media?.properties?.[SWAP_KEY];
+    return state && typeof state === 'object' && state.on === true ? state : null;
+};
+export const keepsSound = state => Boolean(state?.keepSound && state.source?.audio === true);
+
+// Person image first (it is Picture 1), then the source video as a guide clip. `slot` keeps the number of each when the
+// file in it is replaced.
+export function swapRows(state) {
+    const rows = [];
+    if (state?.person?.file) rows.push({file: state.person.file, role: 'reference', enabled: true, slot: 'person'});
+    if (state?.source?.file) rows.push({file: state.source.file, role: 'reference', enabled: true, guide: true, slot: 'source',
+        ...(keepsSound(state) ? {keep_source_audio: true} : {})});
+    return rows;
+}
+
+// What the request carries: the rows without the editor-only slot marker.
+export const requestRows = state => swapRows(state).map(({slot, ...row}) => row);
+
+// 'both', 'source', 'person' for what is still missing, null when the two slots are filled.
+export function swapMissing(state) {
+    const source = Boolean(state?.source?.file), person = Boolean(state?.person?.file);
+    return source && person ? null : !source && !person ? 'both' : source ? 'person' : 'source';
+}
+
+// The media list a request reads: the two slots while Replace person is on, else the ordinary list.
+export function effectiveRows(media, serialized) {
+    const state = swapState(media);
+    return state ? swapRows(state) : JSON.parse(serialized?.value || '[]');
+}
+
+export const withPrefix = text => {
+    const body = String(text ?? '').trim();
+    return body ? `${SWAP_PREFIX} ${body}` : SWAP_PREFIX;
+};
+
+// The replace-person adapter as ComfyUI registers it: the same file may sit in a subfolder of models/loras.
+const baseName = name => String(name).split(/[\\/]/).pop().toLowerCase();
+export const swapLoraNames = names => (Array.isArray(names) ? names : []).filter(name => typeof name === 'string' && baseName(name) === SWAP_LORA);
+const active = row => row.enabled !== false && Number(row.strength) > 0;
+
+// Makes the adapters list carry one working replace-person row. Returns {ok, adapters, record}; record says how to undo
+// what was done (a row added, or a row of the user's switched on) and stays as it was when the row is already working.
+// ok is false with reason 'missing' (not installed), 'ambiguous' (several installed, none chosen) or 'unreadable'.
+export function prepareSwapLora(adapters, names, previous = null) {
+    let rows; try { rows = JSON.parse(adapters || '[]'); } catch { return {ok: false, reason: 'unreadable'}; }
+    if (!Array.isArray(rows)) return {ok: false, reason: 'unreadable'};
+    const found = swapLoraNames(names);
+    if (!found.length) return {ok: false, reason: 'missing'};
+    let name = found.length === 1 ? found[0] : null;
+    if (!name) {
+        const used = [...new Set(rows.filter(row => found.includes(row.name) && active(row)).map(row => row.name))];
+        const listed = [...new Set(rows.filter(row => found.includes(row.name)).map(row => row.name))];
+        const pick = used.length ? used : listed;
+        if (pick.length !== 1) return {ok: false, reason: 'ambiguous'};
+        name = pick[0];
+    }
+    const index = rows.findIndex(row => row.name === name), keep = previous?.name === name ? previous : null;
+    if (index < 0) return {ok: true, adapters: JSON.stringify([...rows, {name, strength: 1, enabled: true}]), record: keep || {name, added: true}};
+    const row = rows[index];
+    if (active(row)) return {ok: true, adapters: JSON.stringify(rows), record: keep};
+    const record = keep || {name, restore: {...('enabled' in row ? {enabled: row.enabled} : {}), ...('strength' in row ? {strength: row.strength} : {})}};
+    rows[index] = {...row, enabled: true, strength: Number(row.strength) > 0 ? row.strength : 1};
+    return {ok: true, adapters: JSON.stringify(rows), record};
+}
+
+// Undoes prepareSwapLora: a row it added goes, a row it switched on goes back to how the user had it.
+export function releaseSwapLora(adapters, record) {
+    let rows; try { rows = JSON.parse(adapters || '[]'); } catch { return adapters; }
+    if (!Array.isArray(rows) || !record?.name) return adapters;
+    if (record.added) rows = rows.filter(row => row.name !== record.name);
+    else if (record.restore) rows = rows.map(row => {
+        if (row.name !== record.name) return row;
+        const {enabled, strength, ...rest} = row;
+        return {...rest, ...record.restore};
+    });
+    return JSON.stringify(rows);
+}
diff --git a/web/studio.css b/web/studio.css
index 993a7ce1..91a98ee0 100644
--- a/web/studio.css
+++ b/web/studio.css
@@ -240,3 +240,20 @@
 /* The queued count follows the part number; when the line is too narrow it wraps out of sight. */
 .fv-studio .fv-chain-position:has(.fv-chain-queued){display:flex;flex-wrap:wrap;column-gap:0;line-height:1.4;max-height:1.4em;overflow:hidden}
 .fv-studio .fv-chain-position .fv-chain-queued{white-space:pre}
+.fv-studio .fv-replace-person{margin-top:0;margin-bottom:12px}
+.fv-studio .fv-replace-person.fv-swap-blocked{cursor:not-allowed}
+.fv-studio .fv-swap-on>.fv-panel{display:none}
+.fv-studio .fv-swap-slots{display:grid;grid-template-columns:1fr 1fr;gap:12px}
+.fv-studio .fv-swap-slots[hidden],.fv-studio .fv-swap-note[hidden],.fv-studio .fv-swap-sound[hidden]{display:none}
+.fv-studio .fv-swap-slot{min-width:0}
+.fv-studio .fv-swap-title{font-size:var(--fv-micro);color:var(--fv-muted);margin:0 0 7px}
+.fv-studio .fv-swap-drop{box-sizing:border-box;width:100%;height:112px;flex-direction:column;gap:2px;padding:6px;border:1px dashed var(--fv-border);background:var(--fv-card);color:var(--fv-muted);border-radius:var(--fv-r-sm);overflow:hidden}
+.fv-studio .fv-swap-drop.fv-swap-filled{border-style:solid;gap:4px}
+.fv-studio .fv-swap-plus{font-size:20px;line-height:1;color:var(--fv-ink)}
+.fv-studio .fv-swap-sub{font-size:var(--fv-micro)}
+.fv-studio .fv-swap-thumb{width:100%;height:68px;min-height:0;object-fit:cover;border-radius:4px;background:#0003}
+.fv-studio .fv-swap-name{max-width:100%;line-height:1.3;flex:none;font-size:var(--fv-micro);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.fv-studio .fv-swap-sound{display:flex;align-items:center;gap:8px;grid-column:1/-1;white-space:nowrap;font-size:var(--fv-small,13px)}
+.fv-studio .fv-swap-sound:has(input:disabled){opacity:.4}
+.fv-studio .fv-swap-note{margin-top:8px}
+@media (max-width:480px){.fv-studio .fv-swap-slots{grid-template-columns:1fr}.fv-studio .fv-swap-source{order:1}.fv-studio .fv-swap-sound{order:2}.fv-studio .fv-swap-person{order:3}}
diff --git a/web/studio.js b/web/studio.js
index 72253639..f24686df 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -7,7 +7,7 @@ import { api } from '../../scripts/api.js';
 import { openSetup } from './setup.js';
 import { feedbackButton, feedbackIssueURL } from './feedback.js';
 import { wordmark } from './wordmark.js';
-import { createGenerationProgress, referenceTrimText, thermalText, sharedGpuText, encoderFileText, encoderFilePath } from './generation_progress.js';
+import { createGenerationProgress, referenceTrimText, thermalText, sharedGpuText, keepSoundText, encoderFileText, encoderFilePath } from './generation_progress.js';
 import { viewSwitch, viewChanged, agentTabReady, openAutopilot } from './view_navigation.js';
 import { agentInterfaceState } from './agent_connect.js';
 import { createUpdateNotice, createVersionInfo, productVersion } from './updates.js';
@@ -42,6 +42,8 @@ import { createFirstRunGuide } from './first_run_guide.js';
 import { SHOWCASE_SCENE } from './entry_showcase.js';
 import { createStudioLength, savedSeconds } from './studio_length.js?v=20261011-length';
 import { firstFrameRow } from './first_frame_row.js';
+import { createReplacePerson, swapMissingText } from './replace_person.js';
+import { swapState, swapMissing, effectiveRows, prepareSwapLora, releaseSwapLora, SWAP_LORA } from './replace_state.js';
 import { createStudioChain, chainPosition, chainParts, chainSplit, composePartText, readChainResult, sumPartEstimates, singleRunSnapshot } from './studio_chain.js?v=20261019-words';
 import { waitingText } from './chain_support.js';
 import { createExtendState, extendText, extendSourceProblem, extendSourceState, readExtendRecord, extendSnapshot, mountExtendThumbnail, videoUnavailableText } from './studio_extend.js';
@@ -909,7 +911,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
     canvas.append(samplingSettings); cleanup.push(() => effort.dispose());
     cleanup.push(() => { clearTimeout(effortEstimateTimer); effortEstimateRequest?.abort(); });
     const mediaNode = upstream(node, 'media');
-    const mediaFilled = () => JSON.parse(value(mediaNode, 'assets') || '[]').some(r => r.enabled !== false)
+    const mediaFilled = () => swapState(mediaNode) ? Boolean(swapState(mediaNode).source || swapState(mediaNode).person) : JSON.parse(value(mediaNode, 'assets') || '[]').some(r => r.enabled !== false)
         || Boolean(mediaNode.inputs?.some(input => ['first', 'last', ...referenceInputs, 'reference_audio'].includes(input.name) && input.link != null));
     // The line beside the closed title says what the section is for, until something is added.
     // The guide opens the section it points at; the ring stays on the title row.
@@ -932,6 +934,49 @@ export function openStudio(node, {extendFrom = null} = {}) {
     controls.addEventListener('change', paintMediaHint, true); controls.addEventListener('input', paintMediaHint, true);
     const connectedLora = upstream(node, 'loras');
     const loraNode = connectedLora?.properties?.[CREATED_BY_PANEL] ? pendingLoras(node, connectedLora) : connectedLora || pendingLoras(node);
+    // Replace person: its LoRA row is found among the registered names (it may sit in a subfolder), a row the user had
+    // switched off is switched on for the run, and everything done is undone when the option goes off.
+    // Returns '' when all is well, else the line to show; runs one at a time.
+    let swapLoraBusy = Promise.resolve('');
+    const swapLoraText = reason => reason === 'missing'
+        ? t(`Replace person needs the ${SWAP_LORA} LoRA in the models/loras folder.`, `替换人物需要把 ${SWAP_LORA} 放进 models/loras 文件夹。`)
+        : reason === 'ambiguous' ? t(`More than one ${SWAP_LORA} was found in models/loras. Add the one to use in LoRA.`, `models/loras 中有多个 ${SWAP_LORA}，请在 LoRA 中添加要使用的那个。`)
+        : t('Could not read the LoRA list. Try again.', '没能读取 LoRA 列表，请重试。');
+    async function applySwapLora() {
+        const state = mediaNode?.properties?.freevideo_replace_person;
+        if (!state || !loraNode || !widget(loraNode, 'adapters')) return '';
+        const current = value(loraNode, 'adapters') || '[]';
+        const record = state.lora && typeof state.lora === 'object' ? state.lora : null;
+        if (!state.on) {
+            state.lora = null;
+            if (record) { set(loraNode, 'adapters', releaseSwapLora(current, record)); window.dispatchEvent(new CustomEvent('freevideo-loras', {detail: loraNode.id})); }
+            return '';
+        }
+        let names;
+        try { const response = await api.fetchApi('/models/loras', {cache: 'no-store'}); if (!response.ok) throw new Error(response.statusText); names = await response.json(); }
+        catch { return swapLoraText('unreadable'); }
+        if (!state.on) return '';
+        const now = value(loraNode, 'adapters') || '[]';
+        const result = prepareSwapLora(now, names, record);
+        if (!result.ok) return swapLoraText(result.reason);
+        state.lora = result.record;
+        if (result.adapters !== now) { set(loraNode, 'adapters', result.adapters); window.dispatchEvent(new CustomEvent('freevideo-loras', {detail: loraNode.id})); }
+        return '';
+    }
+    const ensureSwapLora = () => (swapLoraBusy = swapLoraBusy.then(applySwapLora, applySwapLora));
+    let swapPanel = null;
+    function swapChanged(info) {
+        mediaHint.textContent = swapState(mediaNode) ? t('Source video, person image', '源视频、人物图') : t('Reference images, first and last frames', '参考图、首帧、尾帧');
+        // Switching the option only changes which media the prompt reads: its pictures are re-bound, never renumbered.
+        syncReferencePrompt(node, t, info?.toggled === true); paintMediaHint();
+        ensureSwapLora().then(problem => { if (problem) swapPanel?.notify(problem); });
+        window.dispatchEvent(new CustomEvent('freevideo-media', {detail: mediaNode.id}));
+    }
+    if (mediaNode?.freevideoCreateMediaEditor) {
+        const swap = swapPanel = createReplacePerson({t, api, media: mediaNode, mount: mediaMount, view, onChange: swapChanged});
+        cleanup.push(() => swap.dispose());
+        if (swapState(mediaNode)) { mediaHint.textContent = t('Source video, person image', '源视频、人物图'); mediaDetails.open = true; }
+    }
     const [loraDetails, loraMount] = expand(t('LoRA', 'LoRA'));
     if (loraNode && widget(loraNode, 'adapters')) {
         const stop = loraPanel(loraNode, loraMount, {promptNode: node}); cleanup.push(stop);
@@ -1314,7 +1359,8 @@ export function openStudio(node, {extendFrom = null} = {}) {
     const thermalNote = el('div', '', 'fv-note'); thermalNote.hidden = true;
     const sharedGpuNote = el('div', '', 'fv-note'); sharedGpuNote.hidden = true;
     const encoderNote = el('div', '', 'fv-note'); encoderNote.hidden = true;
-    output.append(status, reuseRow, trimNote, memoryNote, thermalNote, sharedGpuNote, encoderNote, links, stats, budget, progress.stall, progress.report, prewarm);
+    const keepSoundNote = el('div', keepSoundText(t), 'fv-note'); keepSoundNote.hidden = true;
+    output.append(status, reuseRow, trimNote, memoryNote, thermalNote, sharedGpuNote, keepSoundNote, encoderNote, links, stats, budget, progress.stall, progress.report, prewarm);
     const failure = createErrorPanel(t, reportRoute); output.append(failure.element);
     // With the picture, the result's actions and numbers form one block, centred below the header.
     output.append(el('div', null, 'fv-preview-end'));
@@ -1360,6 +1406,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
         memoryNote.hidden = !r.low_memory || !!r.result_cache_hit;
         thermalNote.textContent = r.thermal ? thermalText(r.thermal, t) : ''; thermalNote.hidden = !r.thermal || !!r.result_cache_hit;
         sharedGpuNote.textContent = r.shared_gpu ? sharedGpuText(r.shared_gpu, t) : ''; sharedGpuNote.hidden = !sharedGpuNote.textContent || !!r.result_cache_hit;
+        keepSoundNote.hidden = !r.keep_source_audio_failed;
         encoderNote.textContent = r.encoder_file ? encoderFileText(r.encoder_file, t) : ''; encoderNote.hidden = !r.encoder_file;
         const encoderPath = encoderFilePath(r.encoder_file);
         if (encoderPath) encoderNote.append(el('pre', encoderPath, 'fv-encoder-path'));
@@ -1724,7 +1771,11 @@ export function openStudio(node, {extendFrom = null} = {}) {
             }
             invalid.focus(); invalid.reportValidity(); return;
         }
-        if (!extension.source && !prompt.disabled && !prompt.value.trim() && !untouched()) { prompt.focus(); status.textContent = t('Describe your scene first.', '请先描述画面。'); return; }
+        if (!extension.source && !prompt.disabled && !prompt.value.trim() && !untouched() && !swapState(mediaNode)) { prompt.focus(); status.textContent = t('Describe your scene first.', '请先描述画面。'); return; }
+        if (swapState(mediaNode)) {
+            const missing = swapMissing(swapState(mediaNode));
+            if (missing) { status.dataset.error = 'true'; status.textContent = swapMissingText(missing, t); return; }
+        }
         const chosenMode = runMode, batchCount = chosenMode === 'batch' ? Number(count.value) : 1;
         const originalSeed = value(node, 'seed'), seedMode = mode.value;
         // A request that is not accepted leaves the node mode as the user had it; a retry turns it on again.
@@ -1735,7 +1786,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
             stopNote = ''; lastQueueError = null; failure.clear(); node.freevideoFailure = ''; node.freevideoFailureReport = null;
             capturing = true; updateRunButton(); status.dataset.error = 'false'; runOptions.open = false;
             lengthControl.freeze();
-            if ((!extension.source || prompt.value.trim()) && await enhancer.beforeGenerate() === false) return;
+            if ((!extension.source || prompt.value.trim()) && !swapState(mediaNode) && await enhancer.beforeGenerate() === false) return;
             if (disposed) return;
             if (selected === 'input' && !dimensionsLinked) await inputRatio(true);
             const lengthPlan = await lengthControl.ready();
@@ -1747,6 +1798,8 @@ export function openStudio(node, {extendFrom = null} = {}) {
             const sourceState = source ? await extendSourceState(api, source) : 'ok';
             if (sourceState !== 'ok') throw new Error(extendSourceProblem(t, sourceState));
             if (source && lengthPlan?.count > 1) lengthOptions.after = {work: source.video};
+            const swapProblem = await ensureSwapLora();
+            if (swapProblem) { status.dataset.error = 'true'; status.textContent = swapProblem; return; }
             // Only serialization briefly locks the editor. Network submission
             // and all GPU execution leave the next draft fully editable.
             for (const section of controls.querySelectorAll('.fv-section')) section.inert = true;
@@ -1824,7 +1877,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
         set(node, 'width', w); set(node, 'height', h); node.properties.freevideo_aspect = selected; node.properties.freevideo_pixels = pixels; syncCanvasSize();
     }
     async function inputRatio(required = false) {
-        const rows = mediaNode ? JSON.parse(value(mediaNode, 'assets') || '[]') : [];
+        const rows = mediaNode ? effectiveRows(mediaNode, widget(mediaNode, 'assets')) : [];
         const active = rows.filter(r => r.enabled !== false);
         const source = active.find(r => r.role === 'first') || active.find(r => r.role === 'last') || active.find(r => /\.(png|jpe?g|webp|bmp|tiff?)$/i.test(r.file));
         if (!source) { if (required) throw new Error(t('Add an image in Media to follow its aspect ratio.', '请先在素材中添加图片，再跟随输入比例。')); return; }

From bf855bbd6295cf73387e201e35a8fa2a21a1c357 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Fri, 23 Oct 2026 17:20:26 +0000
Subject: [PATCH 21/52] Polish Replace person Studio wording

---
 web/studio.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/web/studio.js b/web/studio.js
index f24686df..1dc5609c 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -939,9 +939,9 @@ export function openStudio(node, {extendFrom = null} = {}) {
     // Returns '' when all is well, else the line to show; runs one at a time.
     let swapLoraBusy = Promise.resolve('');
     const swapLoraText = reason => reason === 'missing'
-        ? t(`Replace person needs the ${SWAP_LORA} LoRA in the models/loras folder.`, `替换人物需要把 ${SWAP_LORA} 放进 models/loras 文件夹。`)
-        : reason === 'ambiguous' ? t(`More than one ${SWAP_LORA} was found in models/loras. Add the one to use in LoRA.`, `models/loras 中有多个 ${SWAP_LORA}，请在 LoRA 中添加要使用的那个。`)
-        : t('Could not read the LoRA list. Try again.', '没能读取 LoRA 列表，请重试。');
+        ? t(`"Replace person" needs the ${SWAP_LORA} LoRA in the models/loras folder.`, `“替换人物”需要把 ${SWAP_LORA} 放进 models/loras 文件夹。`)
+        : reason === 'ambiguous' ? t(`More than one ${SWAP_LORA} was found in models/loras. Add the one to use under "LoRA".`, `models/loras 中有多个 ${SWAP_LORA}，请在“LoRA”一栏添加要使用的那个。`)
+        : t('Could not read the LoRA list. Try again.', '无法读取 LoRA 列表，请重试。');
     async function applySwapLora() {
         const state = mediaNode?.properties?.freevideo_replace_person;
         if (!state || !loraNode || !widget(loraNode, 'adapters')) return '';

From 0a6ab73bbf5a122e1e028ed633e22acc724eb767 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Fri, 23 Oct 2026 17:27:04 +0000
Subject: [PATCH 22/52] Stub replace-person imports in the entry and reference
 test harnesses

---
 scripts/test_freevideo_entry.mjs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/scripts/test_freevideo_entry.mjs b/scripts/test_freevideo_entry.mjs
index 124f326f..4db68afe 100644
--- a/scripts/test_freevideo_entry.mjs
+++ b/scripts/test_freevideo_entry.mjs
@@ -119,13 +119,13 @@ test('main browser entry registers both views and preserves node hooks', async t
             .replace('import { app } from "../../scripts/app.js";', 'const {app} = globalThis.__freevideoEntryTest;')
             .replace('import { api } from "../../scripts/api.js";', 'const {api} = globalThis.__freevideoEntryTest;')
             .replace("import { openStudio, loraPanel, loraWarning, promptGuide } from \"./studio.js\";", 'const {openStudio,loraPanel,loraWarning,promptGuide} = globalThis.__freevideoEntryTest;')
-            .replace("import { createGenerationProgress, referenceTrimText, thermalText, sharedGpuText, encoderFileText, encoderFilePath } from './generation_progress.js';", 'const {createGenerationProgress,referenceTrimText,thermalText,sharedGpuText,encoderFileText,encoderFilePath} = globalThis.__freevideoEntryTest;')
+            .replace("import { createGenerationProgress, referenceTrimText, thermalText, sharedGpuText, keepSoundText, encoderFileText, encoderFilePath } from './generation_progress.js';", 'const {createGenerationProgress,referenceTrimText,thermalText,sharedGpuText,encoderFileText,encoderFilePath} = globalThis.__freevideoEntryTest; const keepSoundText = () => "";')
             .replace("import { createProgressConnection } from './progress_connection.js';", 'const {createProgressConnection} = globalThis.__freevideoEntryTest;')
             .replace("import { notifyCompatibility } from './compatibility.js';", 'const {notifyCompatibility} = globalThis.__freevideoEntryTest;')
             .replace("import { startWhiteboxWorker } from './whitebox_worker.js';", 'const {startWhiteboxWorker} = globalThis.__freevideoEntryTest;')
             .replace("import { startUpdateChecks } from './updates.js';", 'const {startUpdateChecks} = globalThis.__freevideoEntryTest;')
             .replace("import { startDoneNotify, askDesktopPermission, DESKTOP_SETTING } from './done_notify.js';", 'const {startDoneNotify} = globalThis.__freevideoEntryTest; const askDesktopPermission = (...args) => globalThis.__permissionAsks.push(args); const DESKTOP_SETTING = "FreeVideo.DoneNotify.Desktop";')
-            .replace("import { attachReferencePicker, referenceItems, syncReferencePrompt, referenceInputs, mediaRows } from './prompt_references.js';", 'const {attachReferencePicker,referenceItems,syncReferencePrompt,referenceInputs,mediaRows} = globalThis.__freevideoEntryTest;')
+            .replace("import { attachReferencePicker, referenceItems, syncReferencePrompt, referenceInputs, mediaRows, mediaNodeOf } from './prompt_references.js';", 'const {attachReferencePicker,referenceItems,syncReferencePrompt,referenceInputs,mediaRows} = globalThis.__freevideoEntryTest; const mediaNodeOf = () => null;')
             .replace("import { expandCast } from './cast_mention.js';", 'const {expandCast} = globalThis.__freevideoEntryTest;')
             .replace("import { outputDownloadURL } from './output_download.js';", 'const {outputDownloadURL} = globalThis.__freevideoEntryTest;')
             .replace("import { shareButton } from './share.js';", 'const {shareButton} = globalThis.__freevideoEntryTest;')
@@ -142,6 +142,8 @@ test('main browser entry registers both views and preserves node hooks', async t
             .replace("import { imageGenerationSupported } from './image_generation.js';", 'const imageGenerationSupported = () => true;')
             .replace("import { uploadMedia } from './media_upload.js';", 'const {uploadMedia} = globalThis.__freevideoEntryTest;')
             .replace("import { createCastLibrary } from './cast_library.js';", 'const {createCastLibrary} = globalThis.__freevideoEntryTest;')
+            .replace("import { swapState, requestRows, swapMissing, withPrefix } from './replace_state.js';", 'const swapState = () => null, requestRows = () => [], swapMissing = () => [], withPrefix = body => body;')
+            .replace("import { swapMissingText } from './replace_person.js';", 'const swapMissingText = () => "";')
             .replace("import { agentInterfaceState } from './agent_connect.js';", "const agentInterfaceState = async () => 'off';")
             .replace("import { installNativeErrorGuard } from './native_errors.js';", 'const installNativeErrorGuard = () => {};')
             .replace("import { installTranslateGuard } from './translate_guard.js';", 'const installTranslateGuard = () => {};');

From e4e7ed339e75df200f3aa87ba6a6454a0aab061b Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 19:21:18 +0000
Subject: [PATCH 23/52] Default the media encoding base to the model root when
 --base is not given

---
 freevideo_engine/generate.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/freevideo_engine/generate.py b/freevideo_engine/generate.py
index 243ddceb..d5815e69 100644
--- a/freevideo_engine/generate.py
+++ b/freevideo_engine/generate.py
@@ -772,7 +772,8 @@ def interrupted(signum, frame):
                             'metrics': str(destination.with_suffix('.encoding.json')),
                             'diagnostic_output': str(destination)}
                 if media:
-                    encoding.update(media=media, geometry=canvas, base=profile['engine'].get('base'),
+                    from .paths import base_path
+                    encoding.update(media=media, geometry=canvas, base=profile['engine'].get('base') or str(base_path()),
                                     reference_latent_cache=str(input_cache.root.parent.parent) if input_cache else None)
                 # Lets the encoder child read the video model while it computes, on a slow drive.
                 from .model_read_ahead import request_fields

From c7a98e6cdb5f630d41e14964a8bd2815506e9047 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sat, 17 Oct 2026 21:21:10 +0000
Subject: [PATCH 24/52] Depth-only reference videos: convert with Depth
 Anything V2 Small, cached, early steps default 3

---
 THIRD_PARTY_NOTICES.md                        |   1 +
 freevideo_engine/comfy_assets.py              |  10 +-
 freevideo_engine/comfy_bridge.py              |  13 +
 freevideo_engine/component_licenses.py        |  12 +
 .../depth_anything_v2/__init__.py             |   4 +
 freevideo_engine/depth_anything_v2/dinov2.py  | 308 ++++++++++++
 .../dinov2_layers/__init__.py                 |   9 +
 .../dinov2_layers/attention.py                |  58 +++
 .../depth_anything_v2/dinov2_layers/block.py  | 126 +++++
 .../dinov2_layers/drop_path.py                |  40 ++
 .../dinov2_layers/layer_scale.py              |  33 ++
 .../depth_anything_v2/dinov2_layers/mlp.py    |  46 ++
 .../dinov2_layers/patch_embed.py              |  94 ++++
 freevideo_engine/depth_anything_v2/dpt.py     | 209 ++++++++
 .../depth_anything_v2/util/__init__.py        |   4 +
 .../depth_anything_v2/util/blocks.py          | 153 ++++++
 .../depth_anything_v2/util/transform.py       | 173 +++++++
 freevideo_engine/depth_reference.py           | 452 ++++++++++++++++++
 freevideo_engine/depth_reference_model.json   |  12 +
 .../licenses/Depth-Anything-V2-Apache-2.0.txt | 217 +++++++++
 pyproject.toml                                |   2 +-
 web/freevideo.js                              |  13 +-
 web/generation_progress.js                    |   4 +-
 23 files changed, 1988 insertions(+), 5 deletions(-)
 create mode 100644 freevideo_engine/depth_anything_v2/__init__.py
 create mode 100644 freevideo_engine/depth_anything_v2/dinov2.py
 create mode 100644 freevideo_engine/depth_anything_v2/dinov2_layers/__init__.py
 create mode 100644 freevideo_engine/depth_anything_v2/dinov2_layers/attention.py
 create mode 100644 freevideo_engine/depth_anything_v2/dinov2_layers/block.py
 create mode 100644 freevideo_engine/depth_anything_v2/dinov2_layers/drop_path.py
 create mode 100644 freevideo_engine/depth_anything_v2/dinov2_layers/layer_scale.py
 create mode 100644 freevideo_engine/depth_anything_v2/dinov2_layers/mlp.py
 create mode 100644 freevideo_engine/depth_anything_v2/dinov2_layers/patch_embed.py
 create mode 100644 freevideo_engine/depth_anything_v2/dpt.py
 create mode 100644 freevideo_engine/depth_anything_v2/util/__init__.py
 create mode 100644 freevideo_engine/depth_anything_v2/util/blocks.py
 create mode 100644 freevideo_engine/depth_anything_v2/util/transform.py
 create mode 100644 freevideo_engine/depth_reference.py
 create mode 100644 freevideo_engine/depth_reference_model.json
 create mode 100644 freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 614bfccd..66b947ee 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -5,6 +5,7 @@ FreeVideo code uses [Apache-2.0](LICENSE). Its dependencies and models retain th
 | Component | License |
 | --- | --- |
 | [Three.js](https://threejs.org/) r160, © 2010–2023 three.js authors (bundled whitebox renderer) | [MIT](web/vendor/three/LICENSE) |
+| [Depth Anything V2 Small](https://github.com/DepthAnything/Depth-Anything-V2/tree/a561b849ebae10a6f5ef49e26c83cbbcd36c71bf), © 2024 Depth Anything authors; DINOv2 © Meta Platforms, Inc. and affiliates. Small-only DPT/DINOv2 inference and preprocessing are adapted and bundled; Small weights are an optional download pinned at `03876f8651c73a60fe4c2c48294e09fcb6838fcf`. | [Apache-2.0 (code and Small weights)](freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt) |
 | Qt, PySide6 and Shiboken6 | LGPL-3.0; [component notices](freevideo_engine/launcher/licenses/NOTICE.txt) |
 | PyInstaller bootloader | GPL-2.0 with the bootloader exception |
 | CPython / psutil | PSF / BSD-3-Clause |
diff --git a/freevideo_engine/comfy_assets.py b/freevideo_engine/comfy_assets.py
index 5c3db2db..0d085fa3 100644
--- a/freevideo_engine/comfy_assets.py
+++ b/freevideo_engine/comfy_assets.py
@@ -75,8 +75,14 @@ def resolve_assets(serialized, input_directory):
     root = Path(input_directory).resolve()
     result = {}
     for row in rows:
-        if not isinstance(row, dict) or set(row) - {'file', 'role', 'enabled', 'cast', 'early_steps', 'sound', 'guide', 'keep_source_audio'}:
+        if not isinstance(row, dict) or set(row) - {'file', 'role', 'enabled', 'cast', 'early_steps', 'sound', 'guide', 'keep_source_audio', 'depth'}:
             raise ValueError('Invalid media item')
+        if 'depth' in row:
+            if type(row['depth']) is not bool:
+                raise ValueError('Media depth must be a boolean')
+            if (row.get('role') != 'reference' or not isinstance(row.get('file'), str)
+                    or media_kind(row['file']) != 'video'):
+                raise ValueError('depth is only allowed on video references')
         # The character an @ mention added the row for; a continued part keeps one picture per character.
         if 'cast' in row and (set(row['cast'] if isinstance(row['cast'], dict) else ('?',)) != {'id'}
                               or not isinstance(row['cast']['id'], str) or not 0 < len(row['cast']['id']) <= 128):
@@ -106,6 +112,8 @@ def resolve_assets(serialized, input_directory):
             result[role] = str(path)
         elif role == 'reference':
             reference = {'kind': kind, 'path': str(path)}
+            if row.get('depth') is True:
+                reference.update(depth=True, early_steps=3)
             if cast_id(row) is not None:
                 reference['cast'] = cast_id(row)   # only a continued part reads it (comfy_media.continued)
             if 'early_steps' in row:
diff --git a/freevideo_engine/comfy_bridge.py b/freevideo_engine/comfy_bridge.py
index 96010987..76475544 100644
--- a/freevideo_engine/comfy_bridge.py
+++ b/freevideo_engine/comfy_bridge.py
@@ -1392,6 +1392,19 @@ def poll():
         elif export_inputs:
             send_progress({'label': 'Retaining and checking input media', 'timing_phase': 'encoding'})
             extra = export_inputs(run, canvas) or {}
+            if any(row.get('depth') is True for row in (extra.get('media') or {}).get('references', [])):
+                from .depth_reference import prepare_media
+                def release_depth_models():
+                    if release_models:
+                        release_models()
+                    from .encoder_prewarm import IDLE
+                    from .resident_process import OWNER, ENV
+                    IDLE.stop()
+                    OWNER.release('depth_reference')
+                    environment.pop(ENV, None)
+                extra = dict(extra, media=prepare_media(extra['media'], root=root, machine=machine,
+                    environ=environment, progress=send_progress, interrupted=interrupted,
+                    release_models=release_depth_models))
             if extra:
                 if extra.get('conditioning'):
                     position = command.index('--prompt-file')
diff --git a/freevideo_engine/component_licenses.py b/freevideo_engine/component_licenses.py
index 6bc54f06..6dc6990e 100644
--- a/freevideo_engine/component_licenses.py
+++ b/freevideo_engine/component_licenses.py
@@ -35,6 +35,13 @@ def row(key, name, licence, link, text=None, terms=None):
               ('MiniMax H3 Community License Agreement, with the Qwen3-VL Apache License 2.0 notice',
                'MiniMax H3 社区许可协议，附 Qwen3-VL 的 Apache 2.0 声明'),
               'https://huggingface.co/t8star/Vdn-Minimax-H3-Comfy/blob/main/LICENSE')
+DEPTH = row('depth-reference', ('Depth Anything V2 Small code and weights', 'Depth Anything V2 Small 代码和权重'),
+            ('Apache License 2.0', 'Apache 许可证 2.0'),
+            'https://github.com/DepthAnything/Depth-Anything-V2/blob/a561b849ebae10a6f5ef49e26c83cbbcd36c71bf/LICENSE')
+
+
+def depth_license():
+    return local(DEPTH, HERE / 'licenses/Depth-Anything-V2-Apache-2.0.txt')
 # Libraries a runtime may carry, found by file name: versioned Windows names and Linux
 # lib*.so.* alike. A CUDA build of Torch counts for CUDA, so a runtime whose CUDA files
 # are named otherwise still lists it.
@@ -113,12 +120,17 @@ def bundle(root, value):
         # The rest of what the Windows runtime carries (Triton's tools, TinyCC) and where its source is.
         rows.append(row('notices', ('Third-party notices', '第三方组件说明'),
                         ('Copyrights and licenses of the other components', '其余组件的版权和许可'), TEXTS / NOTICES))
+    if any('depth_anything_v2/' in entry['path'].replace('\\', '/')
+           or entry['path'].endswith('depth_anything_v2_vits.pth') for entry in value['files']):
+        rows.append(depth_license())
     return rows
 
 
 def named(url):
     """A row for a licence link from an installation plan; one not listed here shows its site."""
     from urllib.parse import urlsplit
+    if url.startswith('https://huggingface.co/depth-anything/Depth-Anything-V2-Small/'):
+        return depth_license()
     prefixes = ((MODEL, 'https://huggingface.co/OpenVDN/'), (ENCODER, 'https://huggingface.co/t8star/'),
                 *((value, value['link'].rsplit('/', 1)[0] + '/') for value, _ in RUNTIME))
     known = next((value for value, prefix in prefixes if url.startswith(prefix)), None)
diff --git a/freevideo_engine/depth_anything_v2/__init__.py b/freevideo_engine/depth_anything_v2/__init__.py
new file mode 100644
index 00000000..4a686853
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/__init__.py
@@ -0,0 +1,4 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
diff --git a/freevideo_engine/depth_anything_v2/dinov2.py b/freevideo_engine/depth_anything_v2/dinov2.py
new file mode 100644
index 00000000..102e3798
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dinov2.py
@@ -0,0 +1,308 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the Apache License, Version 2.0
+# found in the LICENSE file in the root directory of this source tree.
+
+# References:
+#   https://github.com/facebookresearch/dino/blob/main/vision_transformer.py
+#   https://github.com/rwightman/pytorch-image-models/tree/master/timm/models/vision_transformer.py
+
+from functools import partial
+import math
+import logging
+from typing import Sequence, Tuple, Union, Callable
+
+import torch
+import torch.nn as nn
+import torch.utils.checkpoint
+from torch.nn.init import trunc_normal_
+
+from .dinov2_layers import Mlp, PatchEmbed, Attention, Block
+
+
+logger = logging.getLogger("dinov2")
+
+
+def named_apply(fn: Callable, module: nn.Module, name="", depth_first=True, include_root=False) -> nn.Module:
+    if not depth_first and include_root:
+        fn(module=module, name=name)
+    for child_name, child_module in module.named_children():
+        child_name = ".".join((name, child_name)) if name else child_name
+        named_apply(fn=fn, module=child_module, name=child_name, depth_first=depth_first, include_root=True)
+    if depth_first and include_root:
+        fn(module=module, name=name)
+    return module
+
+
+class BlockChunk(nn.ModuleList):
+    def forward(self, x):
+        for b in self:
+            x = b(x)
+        return x
+
+
+class DinoVisionTransformer(nn.Module):
+    def __init__(
+        self,
+        img_size=224,
+        patch_size=16,
+        in_chans=3,
+        embed_dim=768,
+        depth=12,
+        num_heads=12,
+        mlp_ratio=4.0,
+        qkv_bias=True,
+        ffn_bias=True,
+        proj_bias=True,
+        drop_path_rate=0.0,
+        drop_path_uniform=False,
+        init_values=None,  # for layerscale: None or 0 => no layerscale
+        embed_layer=PatchEmbed,
+        act_layer=nn.GELU,
+        block_fn=Block,
+        ffn_layer="mlp",
+        block_chunks=1,
+        num_register_tokens=0,
+        interpolate_antialias=False,
+        interpolate_offset=0.1,
+    ):
+        """
+        Args:
+            img_size (int, tuple): input image size
+            patch_size (int, tuple): patch size
+            in_chans (int): number of input channels
+            embed_dim (int): embedding dimension
+            depth (int): depth of transformer
+            num_heads (int): number of attention heads
+            mlp_ratio (int): ratio of mlp hidden dim to embedding dim
+            qkv_bias (bool): enable bias for qkv if True
+            proj_bias (bool): enable bias for proj in attn if True
+            ffn_bias (bool): enable bias for ffn if True
+            drop_path_rate (float): stochastic depth rate
+            drop_path_uniform (bool): apply uniform drop rate across blocks
+            weight_init (str): weight init scheme
+            init_values (float): layer-scale init values
+            embed_layer (nn.Module): patch embedding layer
+            act_layer (nn.Module): MLP activation layer
+            block_fn (nn.Module): transformer block class
+            ffn_layer (str): "mlp" (Small only)
+            block_chunks: (int) split block sequence into block_chunks units for FSDP wrap
+            num_register_tokens: (int) number of extra cls tokens (so-called "registers")
+            interpolate_antialias: (str) flag to apply anti-aliasing when interpolating positional embeddings
+            interpolate_offset: (float) work-around offset to apply when interpolating positional embeddings
+        """
+        super().__init__()
+        norm_layer = partial(nn.LayerNorm, eps=1e-6)
+
+        self.num_features = self.embed_dim = embed_dim  # num_features for consistency with other models
+        self.num_tokens = 1
+        self.n_blocks = depth
+        self.num_heads = num_heads
+        self.patch_size = patch_size
+        self.num_register_tokens = num_register_tokens
+        self.interpolate_antialias = interpolate_antialias
+        self.interpolate_offset = interpolate_offset
+
+        self.patch_embed = embed_layer(img_size=img_size, patch_size=patch_size, in_chans=in_chans, embed_dim=embed_dim)
+        num_patches = self.patch_embed.num_patches
+
+        self.cls_token = nn.Parameter(torch.zeros(1, 1, embed_dim))
+        self.pos_embed = nn.Parameter(torch.zeros(1, num_patches + self.num_tokens, embed_dim))
+        assert num_register_tokens >= 0
+        self.register_tokens = (
+            nn.Parameter(torch.zeros(1, num_register_tokens, embed_dim)) if num_register_tokens else None
+        )
+
+        if drop_path_uniform is True:
+            dpr = [drop_path_rate] * depth
+        else:
+            dpr = [x.item() for x in torch.linspace(0, drop_path_rate, depth)]  # stochastic depth decay rule
+
+        if ffn_layer == "mlp":
+            logger.info("using MLP layer as FFN")
+            ffn_layer = Mlp
+        else:
+            raise NotImplementedError
+
+        blocks_list = [
+            block_fn(
+                dim=embed_dim,
+                num_heads=num_heads,
+                mlp_ratio=mlp_ratio,
+                qkv_bias=qkv_bias,
+                proj_bias=proj_bias,
+                ffn_bias=ffn_bias,
+                drop_path=dpr[i],
+                norm_layer=norm_layer,
+                act_layer=act_layer,
+                ffn_layer=ffn_layer,
+                init_values=init_values,
+            )
+            for i in range(depth)
+        ]
+        if block_chunks > 0:
+            self.chunked_blocks = True
+            chunked_blocks = []
+            chunksize = depth // block_chunks
+            for i in range(0, depth, chunksize):
+                # this is to keep the block index consistent if we chunk the block list
+                chunked_blocks.append([nn.Identity()] * i + blocks_list[i : i + chunksize])
+            self.blocks = nn.ModuleList([BlockChunk(p) for p in chunked_blocks])
+        else:
+            self.chunked_blocks = False
+            self.blocks = nn.ModuleList(blocks_list)
+
+        self.norm = norm_layer(embed_dim)
+        self.head = nn.Identity()
+
+        self.mask_token = nn.Parameter(torch.zeros(1, embed_dim))
+
+        self.init_weights()
+
+    def init_weights(self):
+        trunc_normal_(self.pos_embed, std=0.02)
+        nn.init.normal_(self.cls_token, std=1e-6)
+        if self.register_tokens is not None:
+            nn.init.normal_(self.register_tokens, std=1e-6)
+        named_apply(init_weights_vit_timm, self)
+
+    def interpolate_pos_encoding(self, x, w, h):
+        previous_dtype = x.dtype
+        npatch = x.shape[1] - 1
+        N = self.pos_embed.shape[1] - 1
+        if npatch == N and w == h:
+            return self.pos_embed
+        pos_embed = self.pos_embed.float()
+        class_pos_embed = pos_embed[:, 0]
+        patch_pos_embed = pos_embed[:, 1:]
+        dim = x.shape[-1]
+        w0 = w // self.patch_size
+        h0 = h // self.patch_size
+        # we add a small number to avoid floating point error in the interpolation
+        # see discussion at https://github.com/facebookresearch/dino/issues/8
+        # DINOv2 with register modify the interpolate_offset from 0.1 to 0.0
+        w0, h0 = w0 + self.interpolate_offset, h0 + self.interpolate_offset
+        # w0, h0 = w0 + 0.1, h0 + 0.1
+
+        sqrt_N = math.sqrt(N)
+        sx, sy = float(w0) / sqrt_N, float(h0) / sqrt_N
+        patch_pos_embed = nn.functional.interpolate(
+            patch_pos_embed.reshape(1, int(sqrt_N), int(sqrt_N), dim).permute(0, 3, 1, 2),
+            scale_factor=(sx, sy),
+            # (int(w0), int(h0)), # to solve the upsampling shape issue
+            mode="bicubic",
+            antialias=self.interpolate_antialias
+        )
+
+        assert int(w0) == patch_pos_embed.shape[-2]
+        assert int(h0) == patch_pos_embed.shape[-1]
+        patch_pos_embed = patch_pos_embed.permute(0, 2, 3, 1).view(1, -1, dim)
+        return torch.cat((class_pos_embed.unsqueeze(0), patch_pos_embed), dim=1).to(previous_dtype)
+
+    def prepare_tokens_with_masks(self, x, masks=None):
+        B, nc, w, h = x.shape
+        x = self.patch_embed(x)
+        if masks is not None:
+            x = torch.where(masks.unsqueeze(-1), self.mask_token.to(x.dtype).unsqueeze(0), x)
+
+        x = torch.cat((self.cls_token.expand(x.shape[0], -1, -1), x), dim=1)
+        x = x + self.interpolate_pos_encoding(x, w, h)
+
+        if self.register_tokens is not None:
+            x = torch.cat(
+                (
+                    x[:, :1],
+                    self.register_tokens.expand(x.shape[0], -1, -1),
+                    x[:, 1:],
+                ),
+                dim=1,
+            )
+
+        return x
+
+    def _get_intermediate_layers_not_chunked(self, x, n=1):
+        x = self.prepare_tokens_with_masks(x)
+        # If n is an int, take the n last blocks. If it's a list, take them
+        output, total_block_len = [], len(self.blocks)
+        blocks_to_take = range(total_block_len - n, total_block_len) if isinstance(n, int) else n
+        for i, blk in enumerate(self.blocks):
+            x = blk(x)
+            if i in blocks_to_take:
+                output.append(x)
+        assert len(output) == len(blocks_to_take), f"only {len(output)} / {len(blocks_to_take)} blocks found"
+        return output
+
+    def _get_intermediate_layers_chunked(self, x, n=1):
+        x = self.prepare_tokens_with_masks(x)
+        output, i, total_block_len = [], 0, len(self.blocks[-1])
+        # If n is an int, take the n last blocks. If it's a list, take them
+        blocks_to_take = range(total_block_len - n, total_block_len) if isinstance(n, int) else n
+        for block_chunk in self.blocks:
+            for blk in block_chunk[i:]:  # Passing the nn.Identity()
+                x = blk(x)
+                if i in blocks_to_take:
+                    output.append(x)
+                i += 1
+        assert len(output) == len(blocks_to_take), f"only {len(output)} / {len(blocks_to_take)} blocks found"
+        return output
+
+    def get_intermediate_layers(
+        self,
+        x: torch.Tensor,
+        n: Union[int, Sequence] = 1,  # Layers or n last layers to take
+        reshape: bool = False,
+        return_class_token: bool = False,
+        norm=True
+    ) -> Tuple[Union[torch.Tensor, Tuple[torch.Tensor]]]:
+        if self.chunked_blocks:
+            outputs = self._get_intermediate_layers_chunked(x, n)
+        else:
+            outputs = self._get_intermediate_layers_not_chunked(x, n)
+        if norm:
+            outputs = [self.norm(out) for out in outputs]
+        class_tokens = [out[:, 0] for out in outputs]
+        outputs = [out[:, 1 + self.num_register_tokens:] for out in outputs]
+        if reshape:
+            B, _, w, h = x.shape
+            outputs = [
+                out.reshape(B, w // self.patch_size, h // self.patch_size, -1).permute(0, 3, 1, 2).contiguous()
+                for out in outputs
+            ]
+        if return_class_token:
+            return tuple(zip(outputs, class_tokens))
+        return tuple(outputs)
+
+
+def init_weights_vit_timm(module: nn.Module, name: str = ""):
+    """ViT weight initialization, original timm impl (for reproducibility)"""
+    if isinstance(module, nn.Linear):
+        trunc_normal_(module.weight, std=0.02)
+        if module.bias is not None:
+            nn.init.zeros_(module.bias)
+
+
+def vit_small(patch_size=16, num_register_tokens=0, **kwargs):
+    model = DinoVisionTransformer(
+        patch_size=patch_size,
+        embed_dim=384,
+        depth=12,
+        num_heads=6,
+        mlp_ratio=4,
+        block_fn=partial(Block, attn_class=Attention),
+        num_register_tokens=num_register_tokens,
+        **kwargs,
+    )
+    return model
+
+
+def DINOv2(model_name):
+    if model_name != "vits":
+        raise ValueError("Only DINOv2 Small is bundled")
+    return vit_small(img_size=518, patch_size=14, init_values=1.0, ffn_layer="mlp",
+                     block_chunks=0, num_register_tokens=0,
+                     interpolate_antialias=False, interpolate_offset=0.1)
diff --git a/freevideo_engine/depth_anything_v2/dinov2_layers/__init__.py b/freevideo_engine/depth_anything_v2/dinov2_layers/__init__.py
new file mode 100644
index 00000000..d78af092
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dinov2_layers/__init__.py
@@ -0,0 +1,9 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+from .mlp import Mlp
+from .patch_embed import PatchEmbed
+from .block import Block
+from .attention import Attention
diff --git a/freevideo_engine/depth_anything_v2/dinov2_layers/attention.py b/freevideo_engine/depth_anything_v2/dinov2_layers/attention.py
new file mode 100644
index 00000000..b9c68c3a
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dinov2_layers/attention.py
@@ -0,0 +1,58 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the license found in the
+# LICENSE file in the root directory of this source tree.
+
+# References:
+#   https://github.com/facebookresearch/dino/blob/master/vision_transformer.py
+#   https://github.com/rwightman/pytorch-image-models/tree/master/timm/models/vision_transformer.py
+
+import logging
+
+from torch import Tensor
+from torch import nn
+
+
+logger = logging.getLogger("dinov2")
+
+
+class Attention(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        num_heads: int = 8,
+        qkv_bias: bool = False,
+        proj_bias: bool = True,
+        attn_drop: float = 0.0,
+        proj_drop: float = 0.0,
+    ) -> None:
+        super().__init__()
+        self.num_heads = num_heads
+        head_dim = dim // num_heads
+        self.scale = head_dim**-0.5
+
+        self.qkv = nn.Linear(dim, dim * 3, bias=qkv_bias)
+        self.attn_drop = nn.Dropout(attn_drop)
+        self.proj = nn.Linear(dim, dim, bias=proj_bias)
+        self.proj_drop = nn.Dropout(proj_drop)
+
+    def forward(self, x: Tensor) -> Tensor:
+        B, N, C = x.shape
+        qkv = self.qkv(x).reshape(B, N, 3, self.num_heads, C // self.num_heads).permute(2, 0, 3, 1, 4)
+
+        q, k, v = qkv[0] * self.scale, qkv[1], qkv[2]
+        attn = q @ k.transpose(-2, -1)
+
+        attn = attn.softmax(dim=-1)
+        attn = self.attn_drop(attn)
+
+        x = (attn @ v).transpose(1, 2).reshape(B, N, C)
+        x = self.proj(x)
+        x = self.proj_drop(x)
+        return x
diff --git a/freevideo_engine/depth_anything_v2/dinov2_layers/block.py b/freevideo_engine/depth_anything_v2/dinov2_layers/block.py
new file mode 100644
index 00000000..7f268c5e
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dinov2_layers/block.py
@@ -0,0 +1,126 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the license found in the
+# LICENSE file in the root directory of this source tree.
+
+# References:
+#   https://github.com/facebookresearch/dino/blob/master/vision_transformer.py
+#   https://github.com/rwightman/pytorch-image-models/tree/master/timm/layers/patch_embed.py
+
+import logging
+from typing import Callable, List, Any, Tuple, Dict
+
+import torch
+from torch import nn, Tensor
+
+from .attention import Attention
+from .drop_path import DropPath
+from .layer_scale import LayerScale
+from .mlp import Mlp
+
+
+logger = logging.getLogger("dinov2")
+
+
+class Block(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        num_heads: int,
+        mlp_ratio: float = 4.0,
+        qkv_bias: bool = False,
+        proj_bias: bool = True,
+        ffn_bias: bool = True,
+        drop: float = 0.0,
+        attn_drop: float = 0.0,
+        init_values=None,
+        drop_path: float = 0.0,
+        act_layer: Callable[..., nn.Module] = nn.GELU,
+        norm_layer: Callable[..., nn.Module] = nn.LayerNorm,
+        attn_class: Callable[..., nn.Module] = Attention,
+        ffn_layer: Callable[..., nn.Module] = Mlp,
+    ) -> None:
+        super().__init__()
+        # print(f"biases: qkv: {qkv_bias}, proj: {proj_bias}, ffn: {ffn_bias}")
+        self.norm1 = norm_layer(dim)
+        self.attn = attn_class(
+            dim,
+            num_heads=num_heads,
+            qkv_bias=qkv_bias,
+            proj_bias=proj_bias,
+            attn_drop=attn_drop,
+            proj_drop=drop,
+        )
+        self.ls1 = LayerScale(dim, init_values=init_values) if init_values else nn.Identity()
+        self.drop_path1 = DropPath(drop_path) if drop_path > 0.0 else nn.Identity()
+
+        self.norm2 = norm_layer(dim)
+        mlp_hidden_dim = int(dim * mlp_ratio)
+        self.mlp = ffn_layer(
+            in_features=dim,
+            hidden_features=mlp_hidden_dim,
+            act_layer=act_layer,
+            drop=drop,
+            bias=ffn_bias,
+        )
+        self.ls2 = LayerScale(dim, init_values=init_values) if init_values else nn.Identity()
+        self.drop_path2 = DropPath(drop_path) if drop_path > 0.0 else nn.Identity()
+
+        self.sample_drop_ratio = drop_path
+
+    def forward(self, x: Tensor) -> Tensor:
+        def attn_residual_func(x: Tensor) -> Tensor:
+            return self.ls1(self.attn(self.norm1(x)))
+
+        def ffn_residual_func(x: Tensor) -> Tensor:
+            return self.ls2(self.mlp(self.norm2(x)))
+
+        if self.training and self.sample_drop_ratio > 0.1:
+            # the overhead is compensated only for a drop path rate larger than 0.1
+            x = drop_add_residual_stochastic_depth(
+                x,
+                residual_func=attn_residual_func,
+                sample_drop_ratio=self.sample_drop_ratio,
+            )
+            x = drop_add_residual_stochastic_depth(
+                x,
+                residual_func=ffn_residual_func,
+                sample_drop_ratio=self.sample_drop_ratio,
+            )
+        elif self.training and self.sample_drop_ratio > 0.0:
+            x = x + self.drop_path1(attn_residual_func(x))
+            x = x + self.drop_path1(ffn_residual_func(x))  # FIXME: drop_path2
+        else:
+            x = x + attn_residual_func(x)
+            x = x + ffn_residual_func(x)
+        return x
+
+
+def drop_add_residual_stochastic_depth(
+    x: Tensor,
+    residual_func: Callable[[Tensor], Tensor],
+    sample_drop_ratio: float = 0.0,
+) -> Tensor:
+    # 1) extract subset using permutation
+    b, n, d = x.shape
+    sample_subset_size = max(int(b * (1 - sample_drop_ratio)), 1)
+    brange = (torch.randperm(b, device=x.device))[:sample_subset_size]
+    x_subset = x[brange]
+
+    # 2) apply residual_func to get residual
+    residual = residual_func(x_subset)
+
+    x_flat = x.flatten(1)
+    residual = residual.flatten(1)
+
+    residual_scale_factor = b / sample_subset_size
+
+    # 3) add the residual
+    x_plus_residual = torch.index_add(x_flat, 0, brange, residual.to(dtype=x.dtype), alpha=residual_scale_factor)
+    return x_plus_residual.view_as(x)
diff --git a/freevideo_engine/depth_anything_v2/dinov2_layers/drop_path.py b/freevideo_engine/depth_anything_v2/dinov2_layers/drop_path.py
new file mode 100644
index 00000000..a26bc04b
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dinov2_layers/drop_path.py
@@ -0,0 +1,40 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the license found in the
+# LICENSE file in the root directory of this source tree.
+
+# References:
+#   https://github.com/facebookresearch/dino/blob/master/vision_transformer.py
+#   https://github.com/rwightman/pytorch-image-models/tree/master/timm/layers/drop.py
+
+
+from torch import nn
+
+
+def drop_path(x, drop_prob: float = 0.0, training: bool = False):
+    if drop_prob == 0.0 or not training:
+        return x
+    keep_prob = 1 - drop_prob
+    shape = (x.shape[0],) + (1,) * (x.ndim - 1)  # work with diff dim tensors, not just 2D ConvNets
+    random_tensor = x.new_empty(shape).bernoulli_(keep_prob)
+    if keep_prob > 0.0:
+        random_tensor.div_(keep_prob)
+    output = x * random_tensor
+    return output
+
+
+class DropPath(nn.Module):
+    """Drop paths (Stochastic Depth) per sample (when applied in main path of residual blocks)."""
+
+    def __init__(self, drop_prob=None):
+        super(DropPath, self).__init__()
+        self.drop_prob = drop_prob
+
+    def forward(self, x):
+        return drop_path(x, self.drop_prob, self.training)
diff --git a/freevideo_engine/depth_anything_v2/dinov2_layers/layer_scale.py b/freevideo_engine/depth_anything_v2/dinov2_layers/layer_scale.py
new file mode 100644
index 00000000..4b69a9ba
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dinov2_layers/layer_scale.py
@@ -0,0 +1,33 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Modified from: https://github.com/huggingface/pytorch-image-models/blob/main/timm/models/vision_transformer.py#L103-L110
+
+from typing import Union
+
+import torch
+from torch import Tensor
+from torch import nn
+
+
+class LayerScale(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        init_values: Union[float, Tensor] = 1e-5,
+        inplace: bool = False,
+    ) -> None:
+        super().__init__()
+        self.inplace = inplace
+        self.gamma = nn.Parameter(init_values * torch.ones(dim))
+
+    def forward(self, x: Tensor) -> Tensor:
+        return x.mul_(self.gamma) if self.inplace else x * self.gamma
diff --git a/freevideo_engine/depth_anything_v2/dinov2_layers/mlp.py b/freevideo_engine/depth_anything_v2/dinov2_layers/mlp.py
new file mode 100644
index 00000000..66cc9d7b
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dinov2_layers/mlp.py
@@ -0,0 +1,46 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the license found in the
+# LICENSE file in the root directory of this source tree.
+
+# References:
+#   https://github.com/facebookresearch/dino/blob/master/vision_transformer.py
+#   https://github.com/rwightman/pytorch-image-models/tree/master/timm/layers/mlp.py
+
+
+from typing import Callable, Optional
+
+from torch import Tensor, nn
+
+
+class Mlp(nn.Module):
+    def __init__(
+        self,
+        in_features: int,
+        hidden_features: Optional[int] = None,
+        out_features: Optional[int] = None,
+        act_layer: Callable[..., nn.Module] = nn.GELU,
+        drop: float = 0.0,
+        bias: bool = True,
+    ) -> None:
+        super().__init__()
+        out_features = out_features or in_features
+        hidden_features = hidden_features or in_features
+        self.fc1 = nn.Linear(in_features, hidden_features, bias=bias)
+        self.act = act_layer()
+        self.fc2 = nn.Linear(hidden_features, out_features, bias=bias)
+        self.drop = nn.Dropout(drop)
+
+    def forward(self, x: Tensor) -> Tensor:
+        x = self.fc1(x)
+        x = self.act(x)
+        x = self.drop(x)
+        x = self.fc2(x)
+        x = self.drop(x)
+        return x
diff --git a/freevideo_engine/depth_anything_v2/dinov2_layers/patch_embed.py b/freevideo_engine/depth_anything_v2/dinov2_layers/patch_embed.py
new file mode 100644
index 00000000..642712c3
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dinov2_layers/patch_embed.py
@@ -0,0 +1,94 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the license found in the
+# LICENSE file in the root directory of this source tree.
+
+# References:
+#   https://github.com/facebookresearch/dino/blob/master/vision_transformer.py
+#   https://github.com/rwightman/pytorch-image-models/tree/master/timm/layers/patch_embed.py
+
+from typing import Callable, Optional, Tuple, Union
+
+from torch import Tensor
+import torch.nn as nn
+
+
+def make_2tuple(x):
+    if isinstance(x, tuple):
+        assert len(x) == 2
+        return x
+
+    assert isinstance(x, int)
+    return (x, x)
+
+
+class PatchEmbed(nn.Module):
+    """
+    2D image to patch embedding: (B,C,H,W) -> (B,N,D)
+
+    Args:
+        img_size: Image size.
+        patch_size: Patch token size.
+        in_chans: Number of input image channels.
+        embed_dim: Number of linear projection output channels.
+        norm_layer: Normalization layer.
+    """
+
+    def __init__(
+        self,
+        img_size: Union[int, Tuple[int, int]] = 224,
+        patch_size: Union[int, Tuple[int, int]] = 16,
+        in_chans: int = 3,
+        embed_dim: int = 768,
+        norm_layer: Optional[Callable] = None,
+        flatten_embedding: bool = True,
+    ) -> None:
+        super().__init__()
+
+        image_HW = make_2tuple(img_size)
+        patch_HW = make_2tuple(patch_size)
+        patch_grid_size = (
+            image_HW[0] // patch_HW[0],
+            image_HW[1] // patch_HW[1],
+        )
+
+        self.img_size = image_HW
+        self.patch_size = patch_HW
+        self.patches_resolution = patch_grid_size
+        self.num_patches = patch_grid_size[0] * patch_grid_size[1]
+
+        self.in_chans = in_chans
+        self.embed_dim = embed_dim
+
+        self.flatten_embedding = flatten_embedding
+
+        self.proj = nn.Conv2d(in_chans, embed_dim, kernel_size=patch_HW, stride=patch_HW)
+        self.norm = norm_layer(embed_dim) if norm_layer else nn.Identity()
+
+    def forward(self, x: Tensor) -> Tensor:
+        _, _, H, W = x.shape
+        patch_H, patch_W = self.patch_size
+
+        assert H % patch_H == 0, f"Input image height {H} is not a multiple of patch height {patch_H}"
+        assert W % patch_W == 0, f"Input image width {W} is not a multiple of patch width: {patch_W}"
+
+        x = self.proj(x)  # B C H W
+        H, W = x.size(2), x.size(3)
+        x = x.flatten(2).transpose(1, 2)  # B HW C
+        x = self.norm(x)
+        if not self.flatten_embedding:
+            x = x.reshape(-1, H, W, self.embed_dim)  # B H W C
+        return x
+
+    def flops(self) -> float:
+        Ho, Wo = self.patches_resolution
+        flops = Ho * Wo * self.embed_dim * self.in_chans * (self.patch_size[0] * self.patch_size[1])
+        if self.norm is not None:
+            flops += Ho * Wo * self.embed_dim
+        return flops
diff --git a/freevideo_engine/depth_anything_v2/dpt.py b/freevideo_engine/depth_anything_v2/dpt.py
new file mode 100644
index 00000000..89088e64
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/dpt.py
@@ -0,0 +1,209 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, torch resize, no torchvision.
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from .dinov2 import DINOv2
+from .util.blocks import FeatureFusionBlock, _make_scratch
+from .util.transform import Resize, NormalizeImage, PrepareForNet
+
+
+def _make_fusion_block(features, use_bn, size=None):
+    return FeatureFusionBlock(
+        features,
+        nn.ReLU(False),
+        deconv=False,
+        bn=use_bn,
+        expand=False,
+        align_corners=True,
+        size=size,
+    )
+
+
+class DPTHead(nn.Module):
+    def __init__(
+        self,
+        in_channels,
+        features=64,
+        use_bn=False,
+        out_channels=[48, 96, 192, 384],
+        use_clstoken=False
+    ):
+        super(DPTHead, self).__init__()
+
+        self.use_clstoken = use_clstoken
+
+        self.projects = nn.ModuleList([
+            nn.Conv2d(
+                in_channels=in_channels,
+                out_channels=out_channel,
+                kernel_size=1,
+                stride=1,
+                padding=0,
+            ) for out_channel in out_channels
+        ])
+
+        self.resize_layers = nn.ModuleList([
+            nn.ConvTranspose2d(
+                in_channels=out_channels[0],
+                out_channels=out_channels[0],
+                kernel_size=4,
+                stride=4,
+                padding=0),
+            nn.ConvTranspose2d(
+                in_channels=out_channels[1],
+                out_channels=out_channels[1],
+                kernel_size=2,
+                stride=2,
+                padding=0),
+            nn.Identity(),
+            nn.Conv2d(
+                in_channels=out_channels[3],
+                out_channels=out_channels[3],
+                kernel_size=3,
+                stride=2,
+                padding=1)
+        ])
+
+        if use_clstoken:
+            self.readout_projects = nn.ModuleList()
+            for _ in range(len(self.projects)):
+                self.readout_projects.append(
+                    nn.Sequential(
+                        nn.Linear(2 * in_channels, in_channels),
+                        nn.GELU()))
+
+        self.scratch = _make_scratch(
+            out_channels,
+            features,
+            groups=1,
+            expand=False,
+        )
+
+        self.scratch.stem_transpose = None
+
+        self.scratch.refinenet1 = _make_fusion_block(features, use_bn)
+        self.scratch.refinenet2 = _make_fusion_block(features, use_bn)
+        self.scratch.refinenet3 = _make_fusion_block(features, use_bn)
+        self.scratch.refinenet4 = _make_fusion_block(features, use_bn)
+
+        head_features_1 = features
+        head_features_2 = 32
+
+        self.scratch.output_conv1 = nn.Conv2d(head_features_1, head_features_1 // 2, kernel_size=3, stride=1, padding=1)
+        self.scratch.output_conv2 = nn.Sequential(
+            nn.Conv2d(head_features_1 // 2, head_features_2, kernel_size=3, stride=1, padding=1),
+            nn.ReLU(True),
+            nn.Conv2d(head_features_2, 1, kernel_size=1, stride=1, padding=0),
+            nn.ReLU(True),
+            nn.Identity(),
+        )
+
+    def forward(self, out_features, patch_h, patch_w):
+        out = []
+        for i, x in enumerate(out_features):
+            if self.use_clstoken:
+                x, cls_token = x[0], x[1]
+                readout = cls_token.unsqueeze(1).expand_as(x)
+                x = self.readout_projects[i](torch.cat((x, readout), -1))
+            else:
+                x = x[0]
+
+            x = x.permute(0, 2, 1).reshape((x.shape[0], x.shape[-1], patch_h, patch_w))
+
+            x = self.projects[i](x)
+            x = self.resize_layers[i](x)
+
+            out.append(x)
+
+        layer_1, layer_2, layer_3, layer_4 = out
+
+        layer_1_rn = self.scratch.layer1_rn(layer_1)
+        layer_2_rn = self.scratch.layer2_rn(layer_2)
+        layer_3_rn = self.scratch.layer3_rn(layer_3)
+        layer_4_rn = self.scratch.layer4_rn(layer_4)
+
+        path_4 = self.scratch.refinenet4(layer_4_rn, size=layer_3_rn.shape[2:])
+        path_3 = self.scratch.refinenet3(path_4, layer_3_rn, size=layer_2_rn.shape[2:])
+        path_2 = self.scratch.refinenet2(path_3, layer_2_rn, size=layer_1_rn.shape[2:])
+        path_1 = self.scratch.refinenet1(path_2, layer_1_rn)
+
+        out = self.scratch.output_conv1(path_1)
+        out = F.interpolate(out, (int(patch_h * 14), int(patch_w * 14)), mode="bilinear", align_corners=True)
+        out = self.scratch.output_conv2(out)
+
+        return out
+
+
+class DepthAnythingV2(nn.Module):
+    def __init__(
+        self,
+        encoder='vits',
+        features=64,
+        out_channels=[48, 96, 192, 384],
+        use_bn=False,
+        use_clstoken=False
+    ):
+        super(DepthAnythingV2, self).__init__()
+
+        if encoder != 'vits':
+            raise ValueError('Only Depth Anything V2 Small is bundled')
+        self.intermediate_layer_idx = {'vits': [2, 5, 8, 11]}
+
+        self.encoder = encoder
+        self.pretrained = DINOv2(model_name=encoder)
+
+        self.depth_head = DPTHead(self.pretrained.embed_dim, features, use_bn, out_channels=out_channels, use_clstoken=use_clstoken)
+
+    def forward(self, x):
+        patch_h, patch_w = x.shape[-2] // 14, x.shape[-1] // 14
+
+        features = self.pretrained.get_intermediate_layers(x, self.intermediate_layer_idx[self.encoder], return_class_token=True)
+
+        depth = self.depth_head(features, patch_h, patch_w)
+        depth = F.relu(depth)
+
+        return depth.squeeze(1)
+
+    @torch.no_grad()
+    def infer_image(self, raw_image, input_size=518):
+        image, (h, w) = self.image2tensor(raw_image, input_size)
+
+        depth = self.forward(image)
+
+        depth = F.interpolate(depth[:, None], (h, w), mode="bilinear", align_corners=True)[0, 0]
+
+        return depth.cpu().numpy()
+
+    def image2tensor(self, raw_image, input_size=518):
+        transforms = [
+            Resize(
+                width=input_size,
+                height=input_size,
+                resize_target=False,
+                keep_aspect_ratio=True,
+                ensure_multiple_of=14,
+                resize_method='lower_bound',
+                image_interpolation_method='bicubic',
+            ),
+            NormalizeImage(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+            PrepareForNet(),
+        ]
+
+        h, w = raw_image.shape[:2]
+
+        image = raw_image[..., ::-1] / 255.0
+
+        sample = {'image': image}
+        for transform in transforms:
+            sample = transform(sample)
+        image = sample['image']
+        image = torch.from_numpy(image).unsqueeze(0)
+
+        image = image.to(next(self.parameters()).device)
+
+        return image, (h, w)
diff --git a/freevideo_engine/depth_anything_v2/util/__init__.py b/freevideo_engine/depth_anything_v2/util/__init__.py
new file mode 100644
index 00000000..4a686853
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/util/__init__.py
@@ -0,0 +1,4 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
diff --git a/freevideo_engine/depth_anything_v2/util/blocks.py b/freevideo_engine/depth_anything_v2/util/blocks.py
new file mode 100644
index 00000000..cff1779c
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/util/blocks.py
@@ -0,0 +1,153 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, no torchvision.
+
+import torch.nn as nn
+
+
+def _make_scratch(in_shape, out_shape, groups=1, expand=False):
+    scratch = nn.Module()
+
+    out_shape1 = out_shape
+    out_shape2 = out_shape
+    out_shape3 = out_shape
+    if len(in_shape) >= 4:
+        out_shape4 = out_shape
+
+    if expand:
+        out_shape1 = out_shape
+        out_shape2 = out_shape * 2
+        out_shape3 = out_shape * 4
+        if len(in_shape) >= 4:
+            out_shape4 = out_shape * 8
+
+    scratch.layer1_rn = nn.Conv2d(in_shape[0], out_shape1, kernel_size=3, stride=1, padding=1, bias=False, groups=groups)
+    scratch.layer2_rn = nn.Conv2d(in_shape[1], out_shape2, kernel_size=3, stride=1, padding=1, bias=False, groups=groups)
+    scratch.layer3_rn = nn.Conv2d(in_shape[2], out_shape3, kernel_size=3, stride=1, padding=1, bias=False, groups=groups)
+    if len(in_shape) >= 4:
+        scratch.layer4_rn = nn.Conv2d(in_shape[3], out_shape4, kernel_size=3, stride=1, padding=1, bias=False, groups=groups)
+
+    return scratch
+
+
+class ResidualConvUnit(nn.Module):
+    """Residual convolution module.
+    """
+
+    def __init__(self, features, activation, bn):
+        """Init.
+
+        Args:
+            features (int): number of features
+        """
+        super().__init__()
+
+        self.bn = bn
+
+        self.groups=1
+
+        self.conv1 = nn.Conv2d(features, features, kernel_size=3, stride=1, padding=1, bias=True, groups=self.groups)
+
+        self.conv2 = nn.Conv2d(features, features, kernel_size=3, stride=1, padding=1, bias=True, groups=self.groups)
+
+        if self.bn == True:
+            self.bn1 = nn.BatchNorm2d(features)
+            self.bn2 = nn.BatchNorm2d(features)
+
+        self.activation = activation
+
+        self.skip_add = nn.quantized.FloatFunctional()
+
+    def forward(self, x):
+        """Forward pass.
+
+        Args:
+            x (tensor): input
+
+        Returns:
+            tensor: output
+        """
+
+        out = self.activation(x)
+        out = self.conv1(out)
+        if self.bn == True:
+            out = self.bn1(out)
+
+        out = self.activation(out)
+        out = self.conv2(out)
+        if self.bn == True:
+            out = self.bn2(out)
+
+        if self.groups > 1:
+            out = self.conv_merge(out)
+
+        return self.skip_add.add(out, x)
+
+
+class FeatureFusionBlock(nn.Module):
+    """Feature fusion block.
+    """
+
+    def __init__(
+        self,
+        features,
+        activation,
+        deconv=False,
+        bn=False,
+        expand=False,
+        align_corners=True,
+        size=None
+    ):
+        """Init.
+
+        Args:
+            features (int): number of features
+        """
+        super(FeatureFusionBlock, self).__init__()
+
+        self.deconv = deconv
+        self.align_corners = align_corners
+
+        self.groups=1
+
+        self.expand = expand
+        out_features = features
+        if self.expand == True:
+            out_features = features // 2
+
+        self.out_conv = nn.Conv2d(features, out_features, kernel_size=1, stride=1, padding=0, bias=True, groups=1)
+
+        self.resConfUnit1 = ResidualConvUnit(features, activation, bn)
+        self.resConfUnit2 = ResidualConvUnit(features, activation, bn)
+
+        self.skip_add = nn.quantized.FloatFunctional()
+
+        self.size=size
+
+    def forward(self, *xs, size=None):
+        """Forward pass.
+
+        Returns:
+            tensor: output
+        """
+        output = xs[0]
+
+        if len(xs) == 2:
+            res = self.resConfUnit1(xs[1])
+            output = self.skip_add.add(output, res)
+
+        output = self.resConfUnit2(output)
+
+        if (size is None) and (self.size is None):
+            modifier = {"scale_factor": 2}
+        elif size is None:
+            modifier = {"size": self.size}
+        else:
+            modifier = {"size": size}
+
+        output = nn.functional.interpolate(output, **modifier, mode="bilinear", align_corners=self.align_corners)
+
+        output = self.out_conv(output)
+
+        return output
diff --git a/freevideo_engine/depth_anything_v2/util/transform.py b/freevideo_engine/depth_anything_v2/util/transform.py
new file mode 100644
index 00000000..e90bce2d
--- /dev/null
+++ b/freevideo_engine/depth_anything_v2/util/transform.py
@@ -0,0 +1,173 @@
+# Depth Anything V2, Copyright (c) 2024 Depth Anything authors.
+# Adapted from a561b849ebae10a6f5ef49e26c83cbbcd36c71bf for Small inference.
+# SPDX-License-Identifier: Apache-2.0; see freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt.
+# Changes: Small only, ordinary torch attention, explicit device, torch resize, no torchvision.
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+
+
+def _resize(image, width, height, mode):
+    channels = image.ndim == 3
+    value = np.ascontiguousarray(image.transpose(2, 0, 1) if channels else image[None])
+    tensor = torch.from_numpy(value).unsqueeze(0)
+    options = dict(align_corners=False) if mode == 'bicubic' else {}
+    resized = F.interpolate(tensor, (height, width), mode=mode, **options)[0].numpy()
+    return resized.transpose(1, 2, 0) if channels else resized[0]
+
+
+class Resize(object):
+    """Resize sample to given size (width, height).
+    """
+
+    def __init__(
+        self,
+        width,
+        height,
+        resize_target=True,
+        keep_aspect_ratio=False,
+        ensure_multiple_of=1,
+        resize_method="lower_bound",
+        image_interpolation_method='bicubic',
+    ):
+        """Init.
+
+        Args:
+            width (int): desired output width
+            height (int): desired output height
+            resize_target (bool, optional):
+                True: Resize the full sample (image, mask, target).
+                False: Resize image only.
+                Defaults to True.
+            keep_aspect_ratio (bool, optional):
+                True: Keep the aspect ratio of the input sample.
+                Output sample might not have the given width and height, and
+                resize behaviour depends on the parameter 'resize_method'.
+                Defaults to False.
+            ensure_multiple_of (int, optional):
+                Output width and height is constrained to be multiple of this parameter.
+                Defaults to 1.
+            resize_method (str, optional):
+                "lower_bound": Output will be at least as large as the given size.
+                "upper_bound": Output will be at max as large as the given size. (Output size might be smaller than given size.)
+                "minimal": Scale as least as possible.  (Output size might be smaller than given size.)
+                Defaults to "lower_bound".
+        """
+        self.__width = width
+        self.__height = height
+
+        self.__resize_target = resize_target
+        self.__keep_aspect_ratio = keep_aspect_ratio
+        self.__multiple_of = ensure_multiple_of
+        self.__resize_method = resize_method
+        self.__image_interpolation_method = image_interpolation_method
+
+    def constrain_to_multiple_of(self, x, min_val=0, max_val=None):
+        y = (np.round(x / self.__multiple_of) * self.__multiple_of).astype(int)
+
+        if max_val is not None and y > max_val:
+            y = (np.floor(x / self.__multiple_of) * self.__multiple_of).astype(int)
+
+        if y < min_val:
+            y = (np.ceil(x / self.__multiple_of) * self.__multiple_of).astype(int)
+
+        return y
+
+    def get_size(self, width, height):
+        # determine new height and width
+        scale_height = self.__height / height
+        scale_width = self.__width / width
+
+        if self.__keep_aspect_ratio:
+            if self.__resize_method == "lower_bound":
+                # scale such that output size is lower bound
+                if scale_width > scale_height:
+                    # fit width
+                    scale_height = scale_width
+                else:
+                    # fit height
+                    scale_width = scale_height
+            elif self.__resize_method == "upper_bound":
+                # scale such that output size is upper bound
+                if scale_width < scale_height:
+                    # fit width
+                    scale_height = scale_width
+                else:
+                    # fit height
+                    scale_width = scale_height
+            elif self.__resize_method == "minimal":
+                # scale as least as possbile
+                if abs(1 - scale_width) < abs(1 - scale_height):
+                    # fit width
+                    scale_height = scale_width
+                else:
+                    # fit height
+                    scale_width = scale_height
+            else:
+                raise ValueError(f"resize_method {self.__resize_method} not implemented")
+
+        if self.__resize_method == "lower_bound":
+            new_height = self.constrain_to_multiple_of(scale_height * height, min_val=self.__height)
+            new_width = self.constrain_to_multiple_of(scale_width * width, min_val=self.__width)
+        elif self.__resize_method == "upper_bound":
+            new_height = self.constrain_to_multiple_of(scale_height * height, max_val=self.__height)
+            new_width = self.constrain_to_multiple_of(scale_width * width, max_val=self.__width)
+        elif self.__resize_method == "minimal":
+            new_height = self.constrain_to_multiple_of(scale_height * height)
+            new_width = self.constrain_to_multiple_of(scale_width * width)
+        else:
+            raise ValueError(f"resize_method {self.__resize_method} not implemented")
+
+        return (new_width, new_height)
+
+    def __call__(self, sample):
+        width, height = self.get_size(sample["image"].shape[1], sample["image"].shape[0])
+
+        # resize sample
+        sample["image"] = _resize(sample["image"], width, height, self.__image_interpolation_method)
+
+        if self.__resize_target:
+            if "depth" in sample:
+                sample["depth"] = _resize(sample["depth"], width, height, 'nearest')
+
+            if "mask" in sample:
+                sample["mask"] = _resize(sample["mask"].astype(np.float32), width, height, 'nearest')
+
+        return sample
+
+
+class NormalizeImage(object):
+    """Normlize image by given mean and std.
+    """
+
+    def __init__(self, mean, std):
+        self.__mean = mean
+        self.__std = std
+
+    def __call__(self, sample):
+        sample["image"] = (sample["image"] - self.__mean) / self.__std
+
+        return sample
+
+
+class PrepareForNet(object):
+    """Prepare sample for usage as network input.
+    """
+
+    def __init__(self):
+        pass
+
+    def __call__(self, sample):
+        image = np.transpose(sample["image"], (2, 0, 1))
+        sample["image"] = np.ascontiguousarray(image).astype(np.float32)
+
+        if "depth" in sample:
+            depth = sample["depth"].astype(np.float32)
+            sample["depth"] = np.ascontiguousarray(depth)
+
+        if "mask" in sample:
+            sample["mask"] = sample["mask"].astype(np.float32)
+            sample["mask"] = np.ascontiguousarray(sample["mask"])
+
+        return sample
diff --git a/freevideo_engine/depth_reference.py b/freevideo_engine/depth_reference.py
new file mode 100644
index 00000000..5704193f
--- /dev/null
+++ b/freevideo_engine/depth_reference.py
@@ -0,0 +1,452 @@
+"""Optional, file-backed depth references. Torch lives only in a disposable worker.
+
+Small's vendored Apache-2.0 network and preprocessing follow Quinn's fixed
+DAV2 experiment. Cache identity deliberately excludes prompt, seed and K.
+"""
+from contextlib import contextmanager
+from fractions import Fraction
+import hashlib
+import json
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import time
+import uuid
+
+from . import processes
+from .paths import data_root
+
+PREPROCESSING_VERSION = 'dav2-small-pyav-torch-bgr-imagenet-lower-bound-14-v2'
+CODE_VERSION = 'freevideo-depth-reference-v1'
+STAGE = 'depth_reference'
+
+
+def catalog():
+    return json.loads(Path(__file__).with_name('depth_reference_model.json').read_text(encoding='utf-8'))
+
+
+def canonical_json(value):
+    return json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=False, allow_nan=False)
+
+
+def digest(path, check=lambda: None):
+    value = hashlib.sha256()
+    with Path(path).open('rb') as stream:
+        while block := stream.read(1024 * 1024):
+            check()
+            value.update(block)
+    return value.hexdigest()
+
+
+def cache_directory(root=None):
+    # download_cache is OS page-cache advice, not an application cache folder.
+    return Path(root or data_root()) / 'input-cache' / 'depth-cache'
+
+
+@contextmanager
+def _lock(path, check, *, inherit=False):
+    from .locking import runtime_lock
+    while True:
+        check()
+        try:
+            lease = runtime_lock(path, inherit=inherit)
+            descriptor = lease.__enter__()
+            break
+        except BlockingIOError:
+            time.sleep(.1)
+    try:
+        yield descriptor
+    finally:
+        lease.__exit__(None, None, None)
+
+
+def ensure_weights(root, emit, check):
+    """The same optional-model catalog/transfer mechanism as FreeToken and ASR."""
+    from . import network
+    from .adaln_assets import _download_plan
+    from .prompt_vlm.assets import remote
+    spec = catalog()
+    row = spec['files'][0]
+    folder = Path(root) / 'models' / 'depth-anything-v2-small'
+    path = folder / row['file']
+    with _lock(folder / 'download.lock', check):
+        if path.is_file() and path.stat().st_size == row['bytes'] and digest(path, check) == row['sha256']:
+            return path
+        if path.exists():
+            network.retain_partial(path, 'rejected')
+        plan = _download_plan(Path(root))
+        sources = plan['sources'] = dict(plan.get('sources', {}))
+        if not sources.get('image-models'):
+            sources['image-models'] = [dict(row) for row in sources.get('models', [])
+                                       if row['id'] in ('official', 'hf-mirror')]
+            sources['image-models'].append({'id': 'modelscope'})
+        plan.update(quiet=True, resource_check=check)
+        # remote() describes HF pins and a hash-locked ModelScope fallback;
+        # network retains its measured routes and the user's connection mode.
+        def moved(current, total, speed, **_):
+            emit(phase='dependencies', stage='depth_reference_download', label='Downloading depth reference model',
+                 done=current, total=row['bytes'], unit='bytes', bytes_per_second=speed)
+        check()
+        try:
+            network.download(network.model_urls(plan, remote(spec, row)), path, row['sha256'], moved,
+                             network=plan, size=row['bytes'], category='image-models', keep_partial=True,
+                             stall_seconds=30, slow_seconds=15, low_speed_limit=64 * 1024)
+        except Exception as error:
+            from .sampling_assets import _cancel_or_disk
+            if _cancel_or_disk(error):
+                raise
+            check()
+            raise RuntimeError('Depth reference weights are unavailable. Retry with a connection, or put the '
+                               'official depth_anything_v2_vits.pth (99,218,434 bytes, SHA-256 '
+                               + row['sha256'] + ') in ' + str(folder)) from error
+        if path.stat().st_size != row['bytes'] or digest(path, check) != row['sha256']:
+            raise ValueError('Depth reference weight size/SHA-256 verification failed: ' + str(path))
+        return path
+
+
+def _rotation(frame):
+    # PyAV exposes the display matrix as counterclockwise degrees, as in agent.media.
+    try:
+        return round(frame.rotation or 0) % 360
+    except (AttributeError, ValueError):
+        return 0
+
+
+def _upright_bgr(frame):
+    import numpy as np
+    return np.ascontiguousarray(np.rot90(frame.to_ndarray(format='bgr24'), round(_rotation(frame) / 90) % 4))
+
+
+def inspect_video(path, check=lambda: None, *, depth=False):
+    """Decode every frame, rather than trusting container frame-count headers."""
+    import av
+    import numpy as np
+    pts, dimensions, rotation = [], None, None
+    with av.open(str(path)) as container:
+        if not container.streams.video:
+            raise ValueError('Depth reference needs a decodable video')
+        if depth and container.streams.audio:
+            raise ValueError('Depth reference cache unexpectedly contains audio')
+        stream = container.streams.video[0]
+        rate = stream.average_rate
+        if rate is None or rate <= 0:
+            raise ValueError('Depth reference video has no valid frame rate')
+        time_base = stream.time_base
+        for frame in container.decode(stream):
+            check()
+            current_rotation = _rotation(frame)
+            if rotation is not None and current_rotation != rotation:
+                raise ValueError('Depth reference video changes display rotation')
+            rotation = current_rotation
+            size = (frame.width, frame.height)
+            if dimensions is not None and dimensions != size:
+                raise ValueError('Depth reference video changes dimensions')
+            dimensions = size
+            pts.append(frame.pts)
+            if depth:
+                rgb = frame.to_ndarray(format='rgb24')
+                if not (np.array_equal(rgb[..., 0], rgb[..., 1]) and np.array_equal(rgb[..., 1], rgb[..., 2])):
+                    raise ValueError('Depth reference cache is not grayscale')
+    if not pts:
+        raise ValueError('Depth reference video has no decodable frames')
+    if depth and rotation:
+        raise ValueError('Depth reference cache unexpectedly contains display rotation')
+    if round(rotation / 90) % 2:
+        dimensions = dimensions[::-1]
+    return dict(width=dimensions[0], height=dimensions[1], fps_num=rate.numerator, fps_den=rate.denominator,
+                frames=len(pts), pts=pts, time_base=str(time_base), rotation=rotation)
+
+
+def identity(source, video, device, check=lambda: None):
+    spec = catalog()
+    output = {key: video[key] for key in ('width', 'height', 'fps_num', 'fps_den', 'frames')}
+    output.update(fit='source', audio=False)
+    pix_fmt = 'yuv420p' if video['width'] % 2 == video['height'] % 2 == 0 else 'yuv444p'
+    return dict(source_sha256=digest(source, check), source_size=Path(source).stat().st_size,
+                model_id=spec['repo'], weights_sha256=spec['files'][0]['sha256'], source_commit=spec['source_commit'],
+                code_version=CODE_VERSION, preprocessing_version=PREPROCESSING_VERSION,
+                selection_spec=dict(source_start_pts=video['pts'][0], source_end_pts=video['pts'][-1],
+                                    source_time_base=video['time_base'], crop_rect=None,
+                                    rotation=video['rotation'], tail_policy='none'),
+                output_spec=output,
+                inference_spec=dict(input_size=518, precision='fp16' if device == 'cuda' else 'fp32',
+                    normalization='whole_clip_p1_p99_from_240x136_near_white_v1',
+                    encoder='gray-to-'+pix_fmt+'/libx264/crf16/threads2', runtime_backend='torch-'+device))
+
+
+def cache_key(config):
+    return hashlib.sha256(canonical_json(config).encode('utf-8')).hexdigest()
+
+
+def _validate(path, expected, check):
+    observed = inspect_video(path, check, depth=True)
+    if any(observed[key] != expected[key] for key in ('width', 'height', 'fps_num', 'fps_den', 'frames')):
+        raise ValueError('Depth reference output dimensions, frame rate or frame count differ from the input')
+    return observed
+
+
+def _cached(folder, config, check):
+    try:
+        manifest = json.loads((folder / 'manifest.json').read_text(encoding='utf-8'))
+        output = folder / 'depth.mp4'
+        if (manifest['config'] != config or manifest['output_sha256'] != digest(output, check)
+                or manifest['output_bytes'] != output.stat().st_size):
+            return None
+        _validate(output, config['output_spec'], check)
+        return output
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        if isinstance(error, InterruptedError):
+            raise
+        return None
+
+
+def _load_model(weights, device):
+    import torch
+    from .depth_anything_v2.dpt import DepthAnythingV2
+    model = DepthAnythingV2()
+    model.load_state_dict(torch.load(weights, map_location='cpu', weights_only=True), strict=True)
+    return model.to(device).eval()
+
+
+def _infer(source, stage, video, weights, device, emit, check):
+    import av
+    import numpy as np
+    import psutil
+    import torch
+    # Reserve system RAM and account for live free memory before loading.
+    if psutil.virtual_memory().available < 2 * 2**30:
+        raise MemoryError('Depth reference needs 1 GiB working RAM plus 1 GiB system reserve; free memory and retry')
+    if device == 'cuda':
+        if not torch.cuda.is_available():
+            raise RuntimeError('CUDA is unavailable for depth reference; select the CPU backend to use FP32')
+        free, total = torch.cuda.mem_get_info()
+        reserve = max(512 * 2**20, total // 10)
+        if free < reserve + 512 * 2**20:
+            raise MemoryError('Not enough free GPU memory for depth reference and the GPU reserve')
+    torch.set_num_threads(min(8, os.cpu_count() or 1))
+    shape = (video['frames'], video['height'], video['width'])
+    from .disk_space import free_bytes
+    if free_bytes(stage) < (shape[0] * (shape[1] * shape[2] + 240 * 136) * 4 + 256 * 2**20):
+        raise OSError('Not enough disk space to stage depth frames; free space and retry')
+    model = _load_model(weights, device)
+    raw_path, small_path = stage / 'raw.f32', stage / 'small.f32'
+    depths = np.memmap(raw_path, mode='w+', dtype=np.float32, shape=shape)
+    small = np.memmap(small_path, mode='w+', dtype=np.float32, shape=(video['frames'], 136, 240))
+    try:
+        with av.open(str(source)) as container:
+            count = 0
+            for frame in container.decode(video=0):
+                check()
+                bgr = _upright_bgr(frame)
+                if (count >= video['frames'] or bgr.shape[:2] != shape[1:]
+                        or _rotation(frame) != video['rotation']):
+                    raise ValueError('Source video changed during depth conversion')
+                if psutil.virtual_memory().available < 2**30:
+                    raise MemoryError('Depth reference stopped to preserve 1 GiB of free system RAM')
+                with torch.inference_mode(), torch.autocast('cuda', dtype=torch.float16, enabled=device == 'cuda'):
+                    depth = np.asarray(model.infer_image(bgr, 518), dtype=np.float32)
+                if depth.shape != shape[1:] or not np.isfinite(depth).all():
+                    raise ValueError('Depth model returned invalid/nonfinite pixels')
+                depths[count] = depth
+                small[count] = torch.nn.functional.interpolate(torch.from_numpy(depth)[None, None],
+                                                               (136, 240), mode='area')[0, 0].numpy()
+                count += 1
+                emit(done=count, total=video['frames'], unit='frames', phase='depth_reference',
+                     detail='%d/%d frames' % (count, video['frames']))
+            if count != video['frames']:
+                raise ValueError('Source video frame count changed during depth conversion')
+        # Whole-clip p1/p99, in-place selection on disk-backed samples, bounded RAM.
+        small.flush()
+        lo, hi = np.percentile(small.reshape(-1), [1, 99], overwrite_input=True)
+        span = max(float(hi - lo), 1e-6)
+        output = stage / 'depth.mp4'
+        emit(phase='depth_reference', detail='Encoding depth video')
+        with av.open(str(output), 'w') as container:
+            stream = container.add_stream('libx264', rate=Fraction(video['fps_num'], video['fps_den']))
+            stream.width, stream.height = video['width'], video['height']
+            stream.pix_fmt = 'yuv420p' if stream.width % 2 == stream.height % 2 == 0 else 'yuv444p'
+            stream.options = {'crf': '16', 'threads': '2'}
+            for index, depth in enumerate(depths):
+                check()
+                gray = (np.clip((depth - lo) / span, 0, 1) * 255).round().astype(np.uint8)
+                frame = av.VideoFrame.from_ndarray(gray, format='gray')
+                frame.pts, frame.time_base = index, Fraction(video['fps_den'], video['fps_num'])
+                for packet in stream.encode(frame):
+                    container.mux(packet)
+            for packet in stream.encode(None):
+                container.mux(packet)
+        return dict(low=float(lo), high=float(hi), near='white', torch=torch.__version__,
+                    av=av.__version__, ffmpeg=av.library_versions,
+                    attention='ordinary-torch-matmul-softmax', device=device)
+    finally:
+        # Close mappings before deleting or moving files (Windows).
+        depths._mmap.close()
+        small._mmap.close()
+        del depths, small
+        raw_path.unlink(missing_ok=True)
+        small_path.unlink(missing_ok=True)
+
+
+def _convert(request, emit, check):
+    source, root, work = Path(request['source']), Path(request['root']), Path(request['work'])
+    device = request.get('device', 'auto')
+    if device == 'auto':
+        import torch
+        device = 'cuda' if torch.cuda.is_available() else 'cpu'
+    if device not in ('cpu', 'cuda'):
+        raise ValueError('Depth reference device must be cpu, cuda or auto')
+    emit(phase='depth_reference', detail='Checking depth reference cache')
+    initial_hash, initial_size = digest(source, check), source.stat().st_size
+    video = inspect_video(source, check)
+    config = identity(source, video, device, check)
+    if config['source_sha256'] != initial_hash or config['source_size'] != initial_size:
+        raise ValueError('Source video changed during depth inspection')
+    cache = Path(request['cache'])
+    key = cache_key(config)
+    target = cache / key
+    with _lock(cache / '.locks' / (key + '.lock'), check):
+        found = _cached(target, config, check)
+        if found is not None:
+            return dict(path=str(found), cache_hit=True, key=key)
+        weights = ensure_weights(root, emit, check)
+        # Parent releases idle Comfy/engine/encoder models only on a cache miss.
+        emit(phase=STAGE, stage=STAGE, label='Extracting depth from the reference video',
+             done=0, total=video['frames'], unit='frames', detail='Loading depth model', waiting_for_device=True)
+        while not (work / 'device-ready').is_file():
+            check()
+            time.sleep(.05)
+        stage = work / 'result'
+        stage.mkdir()
+        with _lock(Path(os.environ.get('FREEVIDEO_LOCK_PATH', root / 'engine.lock')), check, inherit=True):
+            metrics = _infer(source, stage, video, weights, device, emit, check)
+        observed = _validate(stage / 'depth.mp4', video, check)
+        if digest(source, check) != config['source_sha256'] or source.stat().st_size != config['source_size']:
+            raise ValueError('Source video changed during depth conversion')
+        manifest = dict(config=config, source_pts=video['pts'], source_time_base=video['time_base'], output=observed,
+                        output_sha256=digest(stage / 'depth.mp4', check), output_bytes=(stage / 'depth.mp4').stat().st_size,
+                        normalization=metrics, license='Apache-2.0',
+                        license_sources=['https://github.com/DepthAnything/Depth-Anything-V2/tree/'+catalog()['source_commit'],
+                                         'https://huggingface.co/'+catalog()['repo']+'/tree/'+catalog()['revision']])
+        (stage / 'manifest.json').write_text(canonical_json(manifest), encoding='utf-8')
+        check()
+        if target.exists():
+            # Retain invalid old artifacts separately; never accept a partial directory.
+            target.rename(cache / (key + '.rejected-' + uuid.uuid4().hex))
+        os.replace(stage, target)
+        return dict(path=str(target / 'depth.mp4'), cache_hit=False, key=key)
+
+
+def convert(source, *, root=None, cache=None, device='auto', python=None, environ=None,
+            progress=None, interrupted=None, release_models=None):
+    """Convert in a supervised child; return a validated cache path after it exits.
+
+    Progress carries stage=depth_reference and done/total in frames. Cancellation
+    stops the whole child tree and removes only this request's temporary files.
+    """
+    root = Path(root or data_root()).resolve()
+    cache = Path(cache or cache_directory(root)).resolve()
+    cache.mkdir(parents=True, exist_ok=True)
+    def check():
+        if interrupted:
+            interrupted()
+    check()
+    with tempfile.TemporaryDirectory(prefix='.depth-', dir=cache) as directory:
+        work = Path(directory)
+        request = dict(source=str(Path(source).resolve()), root=str(root), cache=str(cache), device=device, work=str(work))
+        (work / 'request.json').write_text(canonical_json(request), encoding='utf-8')
+        command = processes.module_command('freevideo_engine.depth_reference', '--request', work / 'request.json')
+        if python is not None:
+            command[0] = str(python)
+        with (work / 'worker.log').open('wb') as log:
+            child = processes.popen(command, env=environ, stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT,
+                                    start_new_session=True, supervise=True, pass_fds=processes.descriptors())
+            last, released = None, False
+            def poll():
+                nonlocal last, released
+                check()
+                try:
+                    value = json.loads((work / 'progress.json').read_text(encoding='utf-8'))
+                except (OSError, ValueError):
+                    return
+                if value.get('waiting_for_device') and not released:
+                    if release_models:
+                        release_models()
+                    check()
+                    (work / 'device-ready').touch()
+                    released = True
+                if progress and value != last:
+                    progress({key: val for key, val in value.items() if key != 'waiting_for_device'})
+                last = value
+            try:
+                while child.poll() is None:
+                    poll()
+                    try:
+                        child.wait(timeout=.1)
+                    except subprocess.TimeoutExpired:
+                        pass
+                poll()
+                if child.returncode:
+                    try:
+                        error = json.loads((work / 'error.json').read_text(encoding='utf-8'))['error']
+                    except (OSError, ValueError, KeyError):
+                        error = 'Depth reference worker exited with code %s' % child.returncode
+                    raise RuntimeError(error)
+                result = json.loads((work / 'result.json').read_text(encoding='utf-8'))
+                check()
+                return Path(result['path'])
+            except BaseException:
+                (work / 'cancelled').touch()
+                processes.stop(child)
+                raise
+
+
+def prepare_media(media, *, root, machine, environ, progress, interrupted, release_models):
+    """Execution only. With depth off, return the original object unchanged."""
+    if not any(row.get('depth') is True for row in media.get('references', [])):
+        return media
+    result = dict(media, references=[])
+    for row in media.get('references', []):
+        if 'depth' in row and (type(row['depth']) is not bool or row.get('kind') != 'video'):
+            raise ValueError('depth must be a boolean on a video reference')
+        if row.get('depth') is not True:
+            result['references'].append(row)
+            continue
+        converted = convert(row['path'], root=root, python=machine['python'], environ=environ,
+                            device='cpu' if machine.get('device_backend') in ('cpu', 'mps') else 'cuda',
+                            progress=progress, interrupted=interrupted, release_models=release_models)
+        value = {key: val for key, val in row.items() if key != 'depth'}
+        value['path'] = str(converted)
+        value.setdefault('early_steps', 3)
+        result['references'].append(value)
+    return result
+
+
+def main():
+    import argparse
+    from .monitoring import save
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--request', required=True, type=Path)
+    args = parser.parse_args()
+    request = json.loads(args.request.read_text(encoding='utf-8'))
+    work = Path(request['work'])
+    def check():
+        if (work / 'cancelled').exists():
+            raise InterruptedError('Depth reference conversion cancelled')
+    state = dict(stage=STAGE, phase=STAGE, timing_phase='encoding', label='Extracting depth from the reference video',
+                 done=0, total=None, unit='frames', references=True)
+    def emit(**values):
+        state.update(values)
+        save(work / 'progress.json', state)
+    try:
+        with processes.worker_signals():
+            result = _convert(request, emit, check)
+        save(work / 'result.json', result)
+    except Exception as error:
+        save(work / 'error.json', dict(error=type(error).__name__ + ': ' + str(error)))
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())
diff --git a/freevideo_engine/depth_reference_model.json b/freevideo_engine/depth_reference_model.json
new file mode 100644
index 00000000..54553f38
--- /dev/null
+++ b/freevideo_engine/depth_reference_model.json
@@ -0,0 +1,12 @@
+{
+  "repo": "depth-anything/Depth-Anything-V2-Small",
+  "revision": "03876f8651c73a60fe4c2c48294e09fcb6838fcf",
+  "source_commit": "a561b849ebae10a6f5ef49e26c83cbbcd36c71bf",
+  "license": "Apache-2.0",
+  "modelscope": {"repo": "depth-anything/Depth-Anything-V2-Small", "revision": "master"},
+  "files": [{
+    "file": "depth_anything_v2_vits.pth",
+    "bytes": 99218434,
+    "sha256": "715fade13be8f229f8a70cc02066f656f2423a59effd0579197bbf57860e1378"
+  }]
+}
diff --git a/freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt b/freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt
new file mode 100644
index 00000000..d3e3fc83
--- /dev/null
+++ b/freevideo_engine/licenses/Depth-Anything-V2-Apache-2.0.txt
@@ -0,0 +1,217 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+FreeVideo attribution and modification notice
+-------------------------------------------
+Depth Anything V2 Small code and weights: Depth Anything authors (2024).
+DINOv2: Copyright (c) Meta Platforms, Inc. and affiliates.
+Source: https://github.com/DepthAnything/Depth-Anything-V2
+Source commit: a561b849ebae10a6f5ef49e26c83cbbcd36c71bf
+Small model: https://huggingface.co/depth-anything/Depth-Anything-V2-Small
+Weight revision: 03876f8651c73a60fe4c2c48294e09fcb6838fcf
+SHA-256: 715fade13be8f229f8a70cc02066f656f2423a59effd0579197bbf57860e1378
+Only Small is included. The Apache-2.0 permission for Small does not apply to
+Base/Large/Giant weights, which are not bundled or downloaded by this feature.
+FreeVideo changes: retain Small DPT and DINOv2 only; remove xformers, nested-tensor
+and SwiGLU paths; use ordinary torch matmul/softmax attention on every machine;
+replace torchvision Compose with the same sequential transforms; follow the
+model's explicit device, and add bounded, cached video conversion in a worker.
diff --git a/pyproject.toml b/pyproject.toml
index fe22466f..e9fb437e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,4 +36,4 @@ include = ["freevideo_engine*"]
 [tool.setuptools.package-data]
 "freevideo_engine.prompt_vlm" = ["model.json"]
 "freevideo_engine.image_gen" = ["image_models.json", "licenses/NOTICE.txt"]
-freevideo_engine = ["stage_estimate_params.json", "build-version.txt", "build-identity.json", "release_notes.json", "dependencies.json", "model_files.json", "model_shares.json", "prepared_models.json", "macos_reference_catalog.json", "superseded_tables.json", "bootstrap_versions.json", "curl_windows.json", "git_linux.json", "git_macos.json", "gcc_linux.json", "uv_downloads.json", "torch_downloads.json", "test_prompts.json", "windows_bootstrap.ps1", "assets/*.png", "assets/*.ico", "launcher/*.qml", "launcher/licenses/*.txt", "licenses/*.txt", "licenses/runtime/*.txt", "subtitle_pack.json", "frame_preview_weights.json", "agent/skill/freevideo/*.txt", "agent/skill/freevideo/references/*.txt"]
+freevideo_engine = ["stage_estimate_params.json", "build-version.txt", "build-identity.json", "release_notes.json", "dependencies.json", "model_files.json", "model_shares.json", "prepared_models.json", "macos_reference_catalog.json", "superseded_tables.json", "bootstrap_versions.json", "curl_windows.json", "git_linux.json", "git_macos.json", "gcc_linux.json", "uv_downloads.json", "torch_downloads.json", "test_prompts.json", "windows_bootstrap.ps1", "assets/*.png", "assets/*.ico", "launcher/*.qml", "launcher/licenses/*.txt", "licenses/*.txt", "licenses/runtime/*.txt", "subtitle_pack.json", "frame_preview_weights.json", "agent/skill/freevideo/*.txt", "agent/skill/freevideo/references/*.txt", "depth_reference_model.json"]
diff --git a/web/freevideo.js b/web/freevideo.js
index 7512ac52..a6bd54a9 100644
--- a/web/freevideo.js
+++ b/web/freevideo.js
@@ -51,7 +51,7 @@ style.textContent = `
 .fv-panel button,.fv-panel select,.fv-panel a{box-sizing:border-box;min-height:var(--fv-h-sm,32px);border:1px solid var(--fv-border);border-radius:var(--fv-r-sm,8px);background:var(--fv-raised);color:var(--fv-ink);padding:5px 10px;font:inherit;font-weight:var(--fv-medium,500);cursor:pointer;text-decoration:none}
 .fv-panel button:hover,.fv-panel a:hover{background:var(--fv-hover)}.fv-panel button:disabled{opacity:.45;cursor:wait}
 .fv-menu-failure{width:min(460px,calc(100vw - 32px));height:auto}.fv-menu-failure::backdrop{background:#0009}
-.fv-panel select{max-width:170px}.fv-note{color:var(--fv-muted);font-size:var(--fv-micro,12px);margin:8px 0;white-space:pre-wrap}.fv-error{color:var(--fv-danger)}
+.fv-panel select{max-width:170px}.fv-note{color:var(--fv-muted);font-size:var(--fv-micro,12px);margin:8px 0;white-space:pre-wrap}.fv-error{color:var(--fv-danger)}.fv-depth-only{display:flex;align-items:center;gap:8px;margin:8px 0 0;white-space:nowrap;font-size:var(--fv-small,13px);cursor:pointer}.fv-depth-only input{margin:0}
 .fv-mode{font-size:var(--fv-micro,12px);color:var(--fv-accent)}
 .fv-panel[data-freevideo=media]>.fv-mode{display:inline-block;margin:4px 0 2px;padding:2px 8px;border-radius:var(--fv-r-xs,3px);background:var(--fv-selected);font-weight:var(--fv-medium,500)}.fv-card{border:1px solid var(--fv-border);border-radius:var(--fv-r-md,12px);padding:10px;margin-top:10px;background:var(--fv-raised)}
 .fv-card[data-enabled=false]{opacity:.5}.fv-file{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1;min-width:60px}
@@ -354,6 +354,15 @@ function mediaPanel(node, mount = null) {
                 };
                 preview.onloadedmetadata = () => showLength();
             }
+            if (kind === "video" && row.role === "reference") {
+                // Off by default: the video itself is the reference. On: its depth picture is, and the picture and colours are not asked for.
+                const depth = el("label", undefined, "fv-depth-only"), box = el("input");
+                box.type = "checkbox"; box.checked = row.depth === true;
+                box.onchange = () => { if (box.checked) rows[index].depth = true; else delete rows[index].depth; update(rows); };
+                depth.append(box, el("span", text("Depth only", "仅参考深度")));
+                depth.title = text("Uses a depth version of this video as the reference.", "转成深度视频后再作参考。");
+                card.append(depth);
+            }
             const controls = el("div", undefined, "fv-row");
             const move = delta => { const target = index + delta; if (target < 0 || target >= rows.length) return; [rows[index], rows[target]] = [rows[target], rows[index]]; update(rows); };
             if (kind === "image") {
@@ -375,7 +384,7 @@ function mediaPanel(node, mount = null) {
             return JSON.stringify(requestRows(swapState(node)));
         }
         // The run takes only what it uses (and which character a picture belongs to); the editing data of a picture stays in the workflow.
-        try { return JSON.stringify(read().map(({file, role, enabled, cast, sound}) => ({file, role, enabled, ...(sound === false && mediaKindOrNull(file) === 'video' ? {sound: false} : {}), ...(typeof cast?.id === 'string' && cast.id ? {cast: {id: cast.id}} : {})}))); } catch { return serialized.value; }
+        try { return JSON.stringify(read().map(({file, role, enabled, cast, sound, depth}) => ({file, role, enabled, ...(sound === false && mediaKindOrNull(file) === 'video' ? {sound: false} : {}), ...(depth === true && role === 'reference' && mediaKindOrNull(file) === 'video' ? {depth: true} : {}), ...(typeof cast?.id === 'string' && cast.id ? {cast: {id: cast.id}} : {})}))); } catch { return serialized.value; }
     };
     async function upload(files) {
         if (node.isUploading || !files.length) return;
diff --git a/web/generation_progress.js b/web/generation_progress.js
index ae7429d7..896d5a8f 100644
--- a/web/generation_progress.js
+++ b/web/generation_progress.js
@@ -20,6 +20,7 @@ const SUBACTIVITY = {
     gpu: ['Loading the prompt model', '正在加载提示词模型'],
     prompt: ['Processing the prompt', '正在处理提示词'],
     reference: ['Processing reference images and videos', '正在处理参考图片和视频'],
+    depth: ['Extracting depth from the reference video', '正在提取参考视频的深度'],
     load: ['Loading the video model', '正在载入视频模型'],
     first: ['Running the first step (it takes longer the first time a size is used or after an update)',
         '正在进行第一步（首次使用这个尺寸或更新后，第一步要多花一些时间）'],
@@ -38,6 +39,7 @@ const SAMPLING_NAME = {
 };
 const SAMPLING_PASS = {first: ['first pass', '一采'], pass2: ['second pass', '二采'], preview: ['preview', '预览']};
 const SUBACTIVITY_LABELS = {
+    'Extracting depth from the reference video': 'depth',
     'Starting generation process': 'start', 'Starting text encoder': 'libraries',
     'Loading text encoder': 'libraries', 'Preparing text encoder GPU': 'gpu',
     'Reading text encoder weights': 'weights', 'Preparing text encoder model': 'weights',
@@ -122,7 +124,7 @@ const LABEL_ACTIVITY = {
         'Preparing prompt data', 'Saving prompt cache', 'Reusing prompt cache', 'Prompt ready',
         'Releasing idle models and checking available memory again'],
     combined: ['Encoding text and images', 'Preparing the prompt and images', 'Preparing text and image tokens'],
-    reference: ['Preparing reference media', 'Retaining and checking input media', 'Encoding input media',
+    reference: ['Extracting depth from the reference video', 'Preparing reference media', 'Retaining and checking input media', 'Encoding input media',
         'Encoding reference media', 'Encoding image/video references', 'Encoding reference audio',
         'Encoding long references', 'Encoding long references in smaller blocks'],
     load: ['Loading the video model', 'Loading video model', 'Loading native MPS model', 'Loading cached video model',

From 32e632e2742b5757cf08ac8457c349479c89d43f Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sun, 18 Oct 2026 01:36:46 +0000
Subject: [PATCH 25/52] Render depth references as clay relief

---
 freevideo_engine/depth_reference.py | 53 ++++++++++++++++++++++++-----
 1 file changed, 44 insertions(+), 9 deletions(-)

diff --git a/freevideo_engine/depth_reference.py b/freevideo_engine/depth_reference.py
index 5704193f..3d4e92c9 100644
--- a/freevideo_engine/depth_reference.py
+++ b/freevideo_engine/depth_reference.py
@@ -17,7 +17,7 @@
 from . import processes
 from .paths import data_root
 
-PREPROCESSING_VERSION = 'dav2-small-pyav-torch-bgr-imagenet-lower-bound-14-v2'
+PREPROCESSING_VERSION = 'dav2-small-pyav-torch-bgr-imagenet-lower-bound-14-clay-relief-v1'
 CODE_VERSION = 'freevideo-depth-reference-v1'
 STAGE = 'depth_reference'
 
@@ -121,7 +121,6 @@ def _upright_bgr(frame):
 def inspect_video(path, check=lambda: None, *, depth=False):
     """Decode every frame, rather than trusting container frame-count headers."""
     import av
-    import numpy as np
     pts, dimensions, rotation = [], None, None
     with av.open(str(path)) as container:
         if not container.streams.video:
@@ -144,10 +143,6 @@ def inspect_video(path, check=lambda: None, *, depth=False):
                 raise ValueError('Depth reference video changes dimensions')
             dimensions = size
             pts.append(frame.pts)
-            if depth:
-                rgb = frame.to_ndarray(format='rgb24')
-                if not (np.array_equal(rgb[..., 0], rgb[..., 1]) and np.array_equal(rgb[..., 1], rgb[..., 2])):
-                    raise ValueError('Depth reference cache is not grayscale')
     if not pts:
         raise ValueError('Depth reference video has no decodable frames')
     if depth and rotation:
@@ -172,7 +167,8 @@ def identity(source, video, device, check=lambda: None):
                 output_spec=output,
                 inference_spec=dict(input_size=518, precision='fp16' if device == 'cuda' else 'fp32',
                     normalization='whole_clip_p1_p99_from_240x136_near_white_v1',
-                    encoder='gray-to-'+pix_fmt+'/libx264/crf16/threads2', runtime_backend='torch-'+device))
+                    render='clay-relief-v1',
+                    encoder='rgb-to-'+pix_fmt+'/libx264/crf16/threads2', runtime_backend='torch-'+device))
 
 
 def cache_key(config):
@@ -209,6 +205,45 @@ def _load_model(weights, device):
     return model.to(device).eval()
 
 
+def _clay_relief(gray):
+    """Render quantized, near-bright depth with Quinn's fixed shade.py recipe.
+
+    SciPy's default Gaussian uses sigma=3, radius=12 and half-sample symmetric
+    reflection (including the edge pixel). Torch's reflect pad excludes that
+    pixel, so use reflected indices; this also works on frames below 13 pixels.
+    """
+    import numpy as np
+    import torch
+    from torch.nn.functional import conv2d
+
+    d = torch.from_numpy(gray.astype(np.float32) / 255)[None, None]
+    offsets = torch.arange(-12, 13, dtype=torch.float64)
+    kernel = torch.exp(-0.5 * offsets.square() / 3.0**2)
+    kernel = (kernel / kernel.sum()).float()
+    # Match gaussian_filter's axis order and float32 intermediate images.
+    for axis in (2, 3):
+        size = d.shape[axis]
+        indices = torch.arange(-12, size + 12) % (2 * size)
+        indices = torch.where(indices < size, indices, 2 * size - 1 - indices)
+        weight = kernel.reshape(1, 1, 25, 1) if axis == 2 else kernel.reshape(1, 1, 1, 25)
+        d = conv2d(d.index_select(axis, indices), weight)
+    d = d[0, 0].numpy()
+    height, width = d.shape
+    # numpy.gradient uses central differences inside and one-sided edges.
+    gy = np.gradient(d, axis=0) if height > 1 else np.zeros_like(d)
+    gx = np.gradient(d, axis=1) if width > 1 else np.zeros_like(d)
+    k = 5.0
+    nx, ny, nz = -gx*k*width/64, -gy*k*height/64, np.ones_like(d)
+    n = np.sqrt(nx**2 + ny**2 + nz**2)
+    nx, ny, nz = nx/n, ny/n, nz/n
+    light = np.array([-0.5, -0.6, 0.62])
+    light /= np.linalg.norm(light)
+    lam = np.clip(nx*light[0] + ny*light[1] + nz*light[2], 0, 1)
+    shade = (0.25 + 0.75*lam) * (0.75 + 0.25*d)
+    base = np.array([0.82, 0.80, 0.77])
+    return (np.clip(shade, 0, 1)[..., None] * base * 255).astype(np.uint8)
+
+
 def _infer(source, stage, video, weights, device, emit, check):
     import av
     import numpy as np
@@ -270,7 +305,7 @@ def _infer(source, stage, video, weights, device, emit, check):
             for index, depth in enumerate(depths):
                 check()
                 gray = (np.clip((depth - lo) / span, 0, 1) * 255).round().astype(np.uint8)
-                frame = av.VideoFrame.from_ndarray(gray, format='gray')
+                frame = av.VideoFrame.from_ndarray(_clay_relief(gray), format='rgb24')
                 frame.pts, frame.time_base = index, Fraction(video['fps_den'], video['fps_num'])
                 for packet in stream.encode(frame):
                     container.mux(packet)
@@ -325,7 +360,7 @@ def _convert(request, emit, check):
             raise ValueError('Source video changed during depth conversion')
         manifest = dict(config=config, source_pts=video['pts'], source_time_base=video['time_base'], output=observed,
                         output_sha256=digest(stage / 'depth.mp4', check), output_bytes=(stage / 'depth.mp4').stat().st_size,
-                        normalization=metrics, license='Apache-2.0',
+                        normalization=metrics, render='clay-relief-v1', license='Apache-2.0',
                         license_sources=['https://github.com/DepthAnything/Depth-Anything-V2/tree/'+catalog()['source_commit'],
                                          'https://huggingface.co/'+catalog()['repo']+'/tree/'+catalog()['revision']])
         (stage / 'manifest.json').write_text(canonical_json(manifest), encoding='utf-8')

From 0726702b9036d28bbe1e939e28f2f1af74cdcb8e Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 21 Oct 2026 19:03:34 +0000
Subject: [PATCH 26/52] Align the depth-only option with the sound option

---
 web/freevideo.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/freevideo.js b/web/freevideo.js
index a6bd54a9..277942f4 100644
--- a/web/freevideo.js
+++ b/web/freevideo.js
@@ -51,7 +51,7 @@ style.textContent = `
 .fv-panel button,.fv-panel select,.fv-panel a{box-sizing:border-box;min-height:var(--fv-h-sm,32px);border:1px solid var(--fv-border);border-radius:var(--fv-r-sm,8px);background:var(--fv-raised);color:var(--fv-ink);padding:5px 10px;font:inherit;font-weight:var(--fv-medium,500);cursor:pointer;text-decoration:none}
 .fv-panel button:hover,.fv-panel a:hover{background:var(--fv-hover)}.fv-panel button:disabled{opacity:.45;cursor:wait}
 .fv-menu-failure{width:min(460px,calc(100vw - 32px));height:auto}.fv-menu-failure::backdrop{background:#0009}
-.fv-panel select{max-width:170px}.fv-note{color:var(--fv-muted);font-size:var(--fv-micro,12px);margin:8px 0;white-space:pre-wrap}.fv-error{color:var(--fv-danger)}.fv-depth-only{display:flex;align-items:center;gap:8px;margin:8px 0 0;white-space:nowrap;font-size:var(--fv-small,13px);cursor:pointer}.fv-depth-only input{margin:0}
+.fv-panel select{max-width:170px}.fv-note{color:var(--fv-muted);font-size:var(--fv-micro,12px);margin:8px 0;white-space:pre-wrap}.fv-error{color:var(--fv-danger)}.fv-panel .fv-depth-only{display:flex;align-items:center;gap:6px;margin:0 0 8px;white-space:nowrap;font-size:var(--fv-micro);cursor:pointer}
 .fv-mode{font-size:var(--fv-micro,12px);color:var(--fv-accent)}
 .fv-panel[data-freevideo=media]>.fv-mode{display:inline-block;margin:4px 0 2px;padding:2px 8px;border-radius:var(--fv-r-xs,3px);background:var(--fv-selected);font-weight:var(--fv-medium,500)}.fv-card{border:1px solid var(--fv-border);border-radius:var(--fv-r-md,12px);padding:10px;margin-top:10px;background:var(--fv-raised)}
 .fv-card[data-enabled=false]{opacity:.5}.fv-file{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1;min-width:60px}

From 31813c1d159716789f5524df0051c71495a302d7 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Thu, 22 Oct 2026 09:26:44 +0000
Subject: [PATCH 27/52] Group the reference depth option with the sound option
 and put it first

---
 web/freevideo.js | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/web/freevideo.js b/web/freevideo.js
index 277942f4..0c5d9317 100644
--- a/web/freevideo.js
+++ b/web/freevideo.js
@@ -51,7 +51,7 @@ style.textContent = `
 .fv-panel button,.fv-panel select,.fv-panel a{box-sizing:border-box;min-height:var(--fv-h-sm,32px);border:1px solid var(--fv-border);border-radius:var(--fv-r-sm,8px);background:var(--fv-raised);color:var(--fv-ink);padding:5px 10px;font:inherit;font-weight:var(--fv-medium,500);cursor:pointer;text-decoration:none}
 .fv-panel button:hover,.fv-panel a:hover{background:var(--fv-hover)}.fv-panel button:disabled{opacity:.45;cursor:wait}
 .fv-menu-failure{width:min(460px,calc(100vw - 32px));height:auto}.fv-menu-failure::backdrop{background:#0009}
-.fv-panel select{max-width:170px}.fv-note{color:var(--fv-muted);font-size:var(--fv-micro,12px);margin:8px 0;white-space:pre-wrap}.fv-error{color:var(--fv-danger)}.fv-panel .fv-depth-only{display:flex;align-items:center;gap:6px;margin:0 0 8px;white-space:nowrap;font-size:var(--fv-micro);cursor:pointer}
+.fv-panel select{max-width:170px}.fv-note{color:var(--fv-muted);font-size:var(--fv-micro,12px);margin:8px 0;white-space:pre-wrap}.fv-error{color:var(--fv-danger)}.fv-panel .fv-depth-only input,.fv-panel .fv-sound input{min-height:0;height:auto}.fv-panel .fv-depth-only{display:flex;align-items:center;gap:6px;margin:0 0 8px;white-space:nowrap;font-size:var(--fv-micro);cursor:pointer}
 .fv-mode{font-size:var(--fv-micro,12px);color:var(--fv-accent)}
 .fv-panel[data-freevideo=media]>.fv-mode{display:inline-block;margin:4px 0 2px;padding:2px 8px;border-radius:var(--fv-r-xs,3px);background:var(--fv-selected);font-weight:var(--fv-medium,500)}.fv-card{border:1px solid var(--fv-border);border-radius:var(--fv-r-md,12px);padding:10px;margin-top:10px;background:var(--fv-raised)}
 .fv-card[data-enabled=false]{opacity:.5}.fv-file{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1;min-width:60px}
@@ -337,6 +337,15 @@ function mediaPanel(node, mount = null) {
                 card.append(preview);
             }
             let showLength = () => {};
+            if (kind === "video" && row.role === "reference") {
+                // Off by default: the video itself is the reference. On: its depth picture is, and the picture and colours are not asked for.
+                const depth = el("label", undefined, "fv-depth-only"), box = el("input");
+                box.type = "checkbox"; box.checked = row.depth === true;
+                box.onchange = () => { if (box.checked) rows[index].depth = true; else delete rows[index].depth; update(rows); };
+                depth.append(box, el("span", text("Depth only", "仅参考深度")));
+                depth.title = text("Uses a depth version of this video as the reference.", "转成深度视频后再作参考。");
+                card.append(depth);
+            }
             if (kind === "video") {
                 const sound = el("label", undefined, "fv-sound"); const box = el("input"); box.type = "checkbox"; box.checked = row.sound !== false;
                 box.onchange = () => { if (box.checked) delete rows[index].sound; else rows[index].sound = false; showLength(); update(rows); };
@@ -354,15 +363,6 @@ function mediaPanel(node, mount = null) {
                 };
                 preview.onloadedmetadata = () => showLength();
             }
-            if (kind === "video" && row.role === "reference") {
-                // Off by default: the video itself is the reference. On: its depth picture is, and the picture and colours are not asked for.
-                const depth = el("label", undefined, "fv-depth-only"), box = el("input");
-                box.type = "checkbox"; box.checked = row.depth === true;
-                box.onchange = () => { if (box.checked) rows[index].depth = true; else delete rows[index].depth; update(rows); };
-                depth.append(box, el("span", text("Depth only", "仅参考深度")));
-                depth.title = text("Uses a depth version of this video as the reference.", "转成深度视频后再作参考。");
-                card.append(depth);
-            }
             const controls = el("div", undefined, "fv-row");
             const move = delta => { const target = index + delta; if (target < 0 || target >= rows.length) return; [rows[index], rows[target]] = [rows[target], rows[index]]; update(rows); };
             if (kind === "image") {

From a467232126e68d8a7dc98c626612334254f0de9e Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 18:12:32 +0000
Subject: [PATCH 28/52] Let the built-in AI pick a white-model template instead
 of writing scene code

A yes/no check first; a no, an unreadable answer or an invalid choice means no white model.
Colour, speed, camera height and field of view are applied to the chosen template by a fixed wrapper.
Only templates whose video was measured to follow the white model are selectable (the cat scene).
---
 freevideo_engine/agent/whitebox_pick.py | 135 ++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 freevideo_engine/agent/whitebox_pick.py

diff --git a/freevideo_engine/agent/whitebox_pick.py b/freevideo_engine/agent/whitebox_pick.py
new file mode 100644
index 00000000..d291ad1c
--- /dev/null
+++ b/freevideo_engine/agent/whitebox_pick.py
@@ -0,0 +1,135 @@
+"""The built-in AI picks a ready-made white-model scene for a shot instead of writing scene code.
+
+Two short questions go to the local prompt model: first whether any template fits at all (a single 是/否), then,
+only on a yes, a five-field JSON choice. A no, an unreadable answer or an invalid choice means no white model:
+the video is generated as usual. Scene code is never taken from the model; the chosen template's code runs
+with its few parameters applied by a fixed wrapper."""
+import json
+import math
+import re
+
+from .whitebox_presets import preset
+
+# The templates the built-in AI may choose: those in the ready-made scenes whose generated video was measured to
+# follow the white model. Adding or retiring one is a change to the scenes and these tables.
+ENABLED = ('cat',)
+GATE_NAMES = dict(cat='猫在客厅逐层跳上书架')
+PICK_NAMES = dict(cat='橘猫跳上书架')
+# Camera height offsets (metres) each template tolerates without the camera meeting a wall or leaving the subject.
+SAFE_HEIGHT = dict(cat=(-0.5, 0.5))
+LIMITS = (('speed', .7, 1.3), ('camera_height', -1, 3), ('fov_scale', .8, 1.25))
+KEYS = ('template', 'hero_color', 'speed', 'camera_height', 'fov_scale')
+NONE = dict(template='none', hero_color=None, speed=1, camera_height=0, fov_scale=1)
+GATE_TOKENS = 16
+PICK_TOKENS = 120
+SYSTEM = '你是视频制作助手，严格按要求的格式回答。'
+
+GATE_PROMPT = """判断镜头能否用以下任一固定模板，只答是或否。
+模板：{NAMES}
+镜头与模板的动作基本一致即答是。只调颜色、速度、机位高度、视野无法实现的镜头答否。
+镜头：{SHOT}"""
+PICK_PROMPT = """镜头：{SHOT}
+模板：{NAMES}
+只输出JSON，五字段全齐：template(以上id；都不像选none)，hero_color(主体#RRGGBB；未提颜色填null)，speed(时间倍率0.7~1.3)，camera_height(相机高度偏移-1~3米)，fov_scale(视野倍率0.8~1.25)。未指定数值用1、0、1。"""
+
+# Applies the parameters to a built template; embedded in the compiled scene as it is.
+APPLY = """function applyParameters(base, p) {
+  const {scene, camera} = base;
+  if (p.hero_color !== null) {
+    scene.traverse(object => {
+      if (!object.isMesh) return;
+      let hero = false;
+      for (let node = object; node; node = node.parent) {
+        if ((node.name || '').startsWith('hero')) { hero = true; break; }
+      }
+      if (!hero) return;
+      const recolor = material => {
+        const copy = material.clone();
+        if (copy.color) copy.color.set(p.hero_color);
+        return copy;
+      };
+      object.material = Array.isArray(object.material) ? object.material.map(recolor) : recolor(object.material);
+    });
+  }
+  camera.fov *= p.fov_scale;
+  camera.updateProjectionMatrix();
+  let previousOffset = 0;
+  return {scene, camera, update(t) {
+    if (typeof t !== 'number' || !Number.isFinite(t)) throw new Error('invalid_time');
+    camera.position.y -= previousOffset;
+    base.update(Math.min(5, Math.max(0, t * p.speed)));
+    camera.position.y += p.camera_height;
+    previousOffset = p.camera_height;
+  }};
+}"""
+
+
+def gate_question(shot):
+    return GATE_PROMPT.format(NAMES='；'.join(GATE_NAMES[i] for i in ENABLED), SHOT=shot)
+
+
+def pick_question(shot):
+    return PICK_PROMPT.format(NAMES='；'.join(i + ' ' + PICK_NAMES[i] for i in ENABLED) + '。', SHOT=shot)
+
+
+def gate_allows(text):
+    """True for 是, False for 否; anything else is not an answer."""
+    answer = text.strip() if isinstance(text, str) else ''
+    if answer not in ('是', '否'):
+        raise ValueError('gate_invalid')
+    return answer == '是'
+
+
+def parameters(value):
+    """The five fields, checked strictly; the choice may name none or an enabled template only."""
+    if not isinstance(value, dict) or set(value) != set(KEYS):
+        raise ValueError('params_invalid')
+    if value['template'] != 'none' and value['template'] not in ENABLED:
+        raise ValueError('params_invalid')
+    color = value['hero_color']
+    if color is not None and not (isinstance(color, str) and re.fullmatch(r'#[0-9a-fA-F]{6}', color)):
+        raise ValueError('params_invalid')
+    for key, low, high in LIMITS:
+        number = value[key]
+        if isinstance(number, bool) or not isinstance(number, (int, float)) or not math.isfinite(number) \
+                or not low <= number <= high:
+            raise ValueError('params_invalid')
+    return {key: value[key] for key in KEYS}
+
+
+def effective(value):
+    """The parameters as rendered: camera height limited to what the template can hold."""
+    result = parameters(value)
+    if result['template'] != 'none':
+        low, high = SAFE_HEIGHT[result['template']]
+        result['camera_height'] = min(high, max(low, result['camera_height']))
+    return result
+
+
+def compile_scene(value):
+    """Scene code for the page: the template's own code plus the fixed parameter wrapper; None for no template."""
+    params = effective(value)
+    if params['template'] == 'none':
+        return None
+    source = preset(params['template'])['code']
+    head = 'export function build(THREE)'
+    if source.count(head) != 1:
+        raise ValueError('template_invalid')
+    return (source.replace(head, 'function buildTemplate(THREE)') + '\n' + APPLY + '\nexport function build(THREE) {\n'
+            '  return applyParameters(buildTemplate(THREE), ' + json.dumps(params) + ');\n}\n')
+
+
+def pick(shot, ask):
+    """Choose a scene for the shot. `ask(question, system, answer_format, max_tokens)` returns the model's answer
+    row (`text`, and `json` for the JSON format). The result always has `params`; `code` is None, and `reason`
+    says why, whenever no white model should be made."""
+    try:
+        if not gate_allows(ask(gate_question(shot), SYSTEM, 'text', GATE_TOKENS).get('text')):
+            return dict(params=dict(NONE), code=None, reason='gate_no')
+        row = ask(pick_question(shot), SYSTEM, 'json', PICK_TOKENS)
+        params = effective(row.get('json'))
+        code = compile_scene(params)
+    except (ValueError, AttributeError, TypeError) as error:
+        reason = str(error)
+        return dict(params=dict(NONE), code=None, reason=reason if reason in ('gate_invalid', 'params_invalid') else 'params_invalid')
+    return dict(params=params, code=code, reason='none' if code is None else 'template')

From 397101c7bbb506dcd7b76dc676531b922dbaab48 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 19:14:54 +0000
Subject: [PATCH 29/52] Built-in AI picks a white-model scene from a typed
 sentence when no Agent is connected

---
 freevideo_engine/agent/routes.py           | 56 +++++++++++++++++++---
 freevideo_engine/agent/schema.py           |  4 +-
 freevideo_engine/agent/whitebox_pick.py    | 19 ++++++--
 freevideo_engine/agent/whitebox_presets.py |  1 +
 web/autopilot_chat.js                      | 37 +++++++++-----
 web/whitebox_scenes.js                     | 10 ++++
 6 files changed, 101 insertions(+), 26 deletions(-)

diff --git a/freevideo_engine/agent/routes.py b/freevideo_engine/agent/routes.py
index 450dc543..28ff6608 100644
--- a/freevideo_engine/agent/routes.py
+++ b/freevideo_engine/agent/routes.py
@@ -31,6 +31,7 @@
 
 PREFIX = '/freevideo/agent/v1'
 from .whitebox import MAX_VIDEO_BYTES as MAX_WHITEBOX_VIDEO
+from . import whitebox_pick
 from .whitebox_presets import PRESETS, preset as whitebox_preset
 # What an empty wait tells the agent: the conversation is open for as long as the user keeps the page.
 KEEP_WAITING = ('Nothing new yet. The user is still in FreeVideo and may speak at any moment: call this wait '
@@ -46,6 +47,8 @@
            'say nothing until the user speaks, then carry on from there.')
 BEFORE_LINES, BEFORE_TEXT = 8, 600
 # The user started a white-model scene and then spoke: the words may be about it, not a new request.
+# Seconds one question to the local prompt model may take, loading the model included.
+WHITEBOX_ASK_SECONDS = 120
 WHITEBOX_PENDING = ('The user started a white-model scene in this conversation ("whitebox" lists it). If the words ask about '
                     'it or about progress, answer from its status in one sentence (waiting or rendering: still being made; '
                     'failed: say it was not made, and why) and start nothing. A question is never a prompt.')
@@ -2191,24 +2194,63 @@ async def whitebox_next(request):
     async def whitebox_presets(request):
         return reply(dict(presets=[{k: row[k] for k in ('id', 'name', 'shot', 'prompt')} for row in PRESETS]))
 
+    def whitebox_ask(question, system, answer_format, max_tokens):
+        """One question to the local prompt model; a refusal, a timeout or a lost job is an OSError for pick()."""
+        try:
+            key = port.vlm_start('ask', dict(questions=[dict(text=question, images=[])], format=answer_format,
+                                              max_tokens=max_tokens, system=system))
+        except JobError as error:
+            raise OSError(error.code) from None
+        deadline = time.monotonic() + WHITEBOX_ASK_SECONDS
+        while True:
+            try:
+                state = port.vlm_status(key)
+            except (ValueError, JobError):
+                raise OSError('lost') from None
+            phase = state.get('phase')
+            if phase == 'complete':
+                answers = state.get('answers') or []
+                if len(answers) != 1 or not isinstance(answers[0], dict):
+                    raise OSError('invalid_output')
+                return answers[0]
+            if phase not in ('starting', 'loading', 'rewriting', 'answering', 'finishing', 'cancelling'):
+                raise OSError(str(state.get('error') or phase))
+            if time.monotonic() > deadline:
+                port.vlm_cancel(key)
+                raise TimeoutError('timeout')
+            time.sleep(.5)
+
     @routes.post('/freevideo/agent/whitebox/try')
     @guarded
     async def whitebox_try(request):
         if request.content_type != 'application/json':
             return problem('unsupported_media_type', 'Send JSON', 415)
         value = await body(request)
-        row = whitebox_preset(value.get('preset') if isinstance(value, dict) else None)
-        if row is None:
-            raise JobError('not_found', 'No such ready-made scene')
+        if not isinstance(value, dict):
+            raise JobError('invalid_request', 'Send a JSON object')
         sid = value.get('session')
-        notice = None
         if sid is not None:
             store = work_sessions()
             if store is None or not isinstance(sid, str) or not store.has(chat['client'], sid):
                 raise JobError('not_found', 'No such conversation')
-            # The conversation gets the confirmation card once the page has rendered the scene.
-            notice = dict(question=row['prompt'], summary=row['name'])
-        scene = await asyncio.to_thread(jobs.whitebox.create, row['code'], row['shot'], sid, notice)
+        shot = value.get('shot')
+        if (shot is None) == (value.get('preset') is None):
+            raise JobError('invalid_request', 'Send either a preset or a shot')
+        if shot is not None:
+            # The built-in AI picks a ready-made scene for the shot; when none fits, the video is made as usual.
+            picked = await asyncio.to_thread(whitebox_pick.pick, shot, whitebox_ask)
+            if picked['code'] is None:
+                return reply(dict(scene=None, reason=picked['reason']))
+            row = whitebox_preset(picked['params']['template'])
+            code = picked['code']
+        else:
+            row = whitebox_preset(value.get('preset'))
+            if row is None:
+                raise JobError('not_found', 'No such ready-made scene')
+            shot, code = row['shot'], row['code']
+        # The conversation gets the confirmation card once the page has rendered the scene.
+        notice = dict(question=row['prompt'], summary=row['name']) if sid is not None else None
+        scene = await asyncio.to_thread(jobs.whitebox.create, code, shot, sid, notice)
         return reply(dict(scene, preset=row['id'], name=row['name'], prompt=row['prompt']), 201)
 
     @routes.post('/freevideo/agent/whitebox/{id}/video')
diff --git a/freevideo_engine/agent/schema.py b/freevideo_engine/agent/schema.py
index ad76ce1b..a3ea6e8d 100644
--- a/freevideo_engine/agent/schema.py
+++ b/freevideo_engine/agent/schema.py
@@ -491,8 +491,8 @@ def route(summary, body=None, query=None, **kw):
     for method, suffix, summary, extra in (
             ('GET', '/next', 'The page asks for a white-model scene to render', {}),
             ('GET', '/presets', 'The ready-made white-model scenes the page can try', {}),
-            ('POST', '/try', 'The page renders one ready-made white-model scene (no model writes code)',
-             dict(body=obj(dict(preset=string(32, pattern=r'^[a-z0-9-]{1,32}$'), session=SESSION), ('preset',)))),
+            ('POST', '/try', 'The page renders one ready-made white-model scene, named (preset) or picked by the built-in AI for a shot (shot); no model writes code',
+             dict(body=obj(dict(preset=string(32, pattern=r'^[a-z0-9-]{1,32}$'), shot=string(4000), session=SESSION)))),
             ('POST', '/{id}/video', 'The page sends the rendered white-model video (the raw mp4 body)',
              dict(path=obj({'id': WHITEBOX}, ('id',)))),
             ('POST', '/{id}/failed', 'The page reports that a white-model scene could not be rendered',
diff --git a/freevideo_engine/agent/whitebox_pick.py b/freevideo_engine/agent/whitebox_pick.py
index d291ad1c..098ca1f2 100644
--- a/freevideo_engine/agent/whitebox_pick.py
+++ b/freevideo_engine/agent/whitebox_pick.py
@@ -57,7 +57,7 @@
   return {scene, camera, update(t) {
     if (typeof t !== 'number' || !Number.isFinite(t)) throw new Error('invalid_time');
     camera.position.y -= previousOffset;
-    base.update(Math.min(5, Math.max(0, t * p.speed)));
+    base.update(Math.min(p.seconds, Math.max(0, t * p.speed)));
     camera.position.y += p.camera_height;
     previousOffset = p.camera_height;
   }};
@@ -111,25 +111,34 @@ def compile_scene(value):
     params = effective(value)
     if params['template'] == 'none':
         return None
-    source = preset(params['template'])['code']
+    row = preset(params['template'])
+    if row is None:
+        raise ValueError('template_invalid')
+    source = row['code']
+    seconds = row['seconds']
+    if isinstance(seconds, bool) or not isinstance(seconds, (int, float)) or not 0 < seconds <= 12:
+        raise ValueError('template_invalid')
     head = 'export function build(THREE)'
     if source.count(head) != 1:
         raise ValueError('template_invalid')
     return (source.replace(head, 'function buildTemplate(THREE)') + '\n' + APPLY + '\nexport function build(THREE) {\n'
-            '  return applyParameters(buildTemplate(THREE), ' + json.dumps(params) + ');\n}\n')
+            '  return applyParameters(buildTemplate(THREE), ' + json.dumps(dict(params, seconds=seconds)) + ');\n}\n')
 
 
 def pick(shot, ask):
     """Choose a scene for the shot. `ask(question, system, answer_format, max_tokens)` returns the model's answer
     row (`text`, and `json` for the JSON format). The result always has `params`; `code` is None, and `reason`
-    says why, whenever no white model should be made."""
+    says why, whenever no white model should be made. A failure to ask at all (timeout, connection) is one of those."""
     try:
         if not gate_allows(ask(gate_question(shot), SYSTEM, 'text', GATE_TOKENS).get('text')):
             return dict(params=dict(NONE), code=None, reason='gate_no')
         row = ask(pick_question(shot), SYSTEM, 'json', PICK_TOKENS)
         params = effective(row.get('json'))
         code = compile_scene(params)
-    except (ValueError, AttributeError, TypeError) as error:
+    except (OSError, TimeoutError):
+        # The model could not be asked (timeout, connection): the video is made without a white model.
+        return dict(params=dict(NONE), code=None, reason='ask_failed')
+    except (ValueError, AttributeError, TypeError, KeyError) as error:
         reason = str(error)
         return dict(params=dict(NONE), code=None, reason=reason if reason in ('gate_invalid', 'params_invalid') else 'params_invalid')
     return dict(params=params, code=code, reason='none' if code is None else 'template')
diff --git a/freevideo_engine/agent/whitebox_presets.py b/freevideo_engine/agent/whitebox_presets.py
index 450d1465..7f700d97 100644
--- a/freevideo_engine/agent/whitebox_presets.py
+++ b/freevideo_engine/agent/whitebox_presets.py
@@ -3,6 +3,7 @@
 PRESETS = (
     dict(id='cat', name='橘猫跳上书架', shot='一只橘猫在客厅地板上蹲下蓄力，沿着错落的书架层板一级一级跳上去，最后蹲在最高一层，镜头侧面平移并略微上摇跟随。',
          prompt='A ginger cat crouches on a living room floor, gathers itself and leaps up a staggered wooden bookshelf, jumping from one shelf to the next between rows of books, and finally settles on the top shelf, while the camera pans sideways and tilts up slightly to follow. Warm indoor daylight, realistic fur and wood, soft shadows, smooth camera motion. Soft room tone and the light thud of paws on wood.',
+         seconds=5,
          code='export function build(THREE) {\n  const scene = new THREE.Scene();\n  const camera = new THREE.PerspectiveCamera(65, 960 / 544, 0.1, 300);\n  const std = c => new THREE.MeshStandardMaterial({ color: c, roughness: 1 });\n  const add = (geo, mat, x, y, z, name, parent) => {\n    const m = new THREE.Mesh(geo, mat); m.position.set(x, y, z); m.name = name || "";\n    m.castShadow = true; m.receiveShadow = true; (parent || scene).add(m); return m;\n  };\n  const ss = x => x * x * (3 - 2 * x);\n  const lerp = (a, b, u) => a + (b - a) * u;\n  const clamp01 = x => Math.min(1, Math.max(0, x));\n  const sun = new THREE.DirectionalLight(0xffffff, 1.8);\n  sun.castShadow = true; sun.shadow.mapSize.set(2048, 2048);\n  sun.shadow.camera.left = -60; sun.shadow.camera.right = 60; sun.shadow.camera.top = 60; sun.shadow.camera.bottom = -60; sun.shadow.camera.far = 200;\n  scene.add(sun);\n\n  scene.background = new THREE.Color(0xe9e2d6);\n  scene.add(new THREE.HemisphereLight(0xfff4e6, 0x8a7f72, 1.2)); sun.position.set(6, 10, 8);\n  add(new THREE.PlaneGeometry(14, 10).rotateX(-Math.PI / 2), std(0xb88f65), 0, 0, 0, "floor");\n  add(new THREE.BoxGeometry(14, 4, 0.2), std(0xe9e2d6), 0, 2, -1.2, "wall");\n  // bookshelf: two side boards, staggered shelves\n  add(new THREE.BoxGeometry(0.1, 2.6, 0.5), std(0x7a5232), -1.4, 1.3, -0.9, "side");\n  add(new THREE.BoxGeometry(0.1, 2.6, 0.5), std(0x7a5232), 1.4, 1.3, -0.9, "side");\n  const shelves = [[0.6, -0.9], [1.2, -0.4], [1.8, 0.2], [2.4, 0.6]];\n  const stepsX = [-0.9, -0.2, 0.5, 1.0], ys = [0.55, 1.05, 1.55, 2.1];\n  for (let i = 0; i < 4; i++) {\n    add(new THREE.BoxGeometry(1.0, 0.06, 0.5), std(0x9a6b3f), stepsX[i], ys[i] - 0.03, -0.9, "shelf");\n    for (let k = 0; k < 3; k++) add(new THREE.BoxGeometry(0.12, 0.28, 0.3), std([0x3c6ea8, 0xb04a4a, 0x4a8a5a][(i + k) % 3]), stepsX[i] - 0.3 + k * 0.2, ys[i] + 0.14, -1.0, "book");\n  }\n  add(new THREE.BoxGeometry(0.9, 0.5, 0.5), std(0x6b7b8c), -2.6, 0.25, 0.6, "sofa_block");\n  const cat = new THREE.Group(); cat.name = "hero_cat"; scene.add(cat);\n  const orange = std(0xe58a2e);\n  const body = add(new THREE.BoxGeometry(0.42, 0.22, 0.2), orange, 0, 0.18, 0, "hero_cat_body", cat);\n  add(new THREE.SphereGeometry(0.11, 10, 8), orange, 0.26, 0.28, 0, "hero_cat_head", cat);\n  add(new THREE.ConeGeometry(0.035, 0.08, 4), orange, 0.28, 0.4, 0.06, "hero_cat_ear", cat);\n  add(new THREE.ConeGeometry(0.035, 0.08, 4), orange, 0.28, 0.4, -0.06, "hero_cat_ear", cat);\n  const tail = add(new THREE.CylinderGeometry(0.03, 0.03, 0.4, 6), orange, -0.34, 0.3, 0, "hero_cat_tail", cat);\n  tail.rotation.z = 0.8;\n  // waypoints: floor crouch, jump to each shelf\n  const wp = [[-1.9, 0.0, 0.1], [-1.9, 0.0, 0.1], [stepsX[0], ys[0], -0.9], [stepsX[1], ys[1], -0.9], [stepsX[2], ys[2], -0.9], [stepsX[3], ys[3], -0.9], [stepsX[3], ys[3], -0.9]];\n  const times = [0, 0.7, 1.4, 2.3, 3.2, 4.1, 5.0];\n  const pos = t => { let i = 0; while (i < 5 && t > times[i + 1]) i++;\n    const u = clamp01((t - times[i]) / (times[i + 1] - times[i])); const a = wp[i], b = wp[i + 1];\n    const arc = (i >= 1 && i <= 4) ? Math.sin(Math.PI * u) * 0.45 : 0;\n    const e = ss(u); return new THREE.Vector3(lerp(a[0], b[0], e), lerp(a[1], b[1], u) + arc, lerp(a[2], b[2], e)); };\n  return { scene, camera, update(t) {\n    const p = pos(t); cat.position.copy(p);\n    cat.scale.y = (t < 0.7) ? 1 - 0.35 * Math.sin(Math.PI * clamp01(t / 0.7)) : 1;\n    cat.rotation.z = (t > 0.7 && t < 4.1) ? 0.35 : 0;\n    camera.position.set(p.x * 0.6, 0.9 + p.y * 0.5, 2.7);\n    camera.lookAt(p.x * 0.85, 0.35 + p.y * 0.85, -0.9);\n  } };\n}\n'),
 )
 
diff --git a/web/autopilot_chat.js b/web/autopilot_chat.js
index a1fdeca9..43091dc6 100644
--- a/web/autopilot_chat.js
+++ b/web/autopilot_chat.js
@@ -2,7 +2,7 @@
 // cards at the place they happened. Reads and sends use the page session; the agent's token never enters the page.
 import {agentGet, agentPost, retryAgentPost} from './agent_session.js';
 import {ATTACH, attachmentURL, pickPictures, thumbnail, uploadPicture} from './chat_attachments.js';
-import {SCENE_TEXT, sceneList, startScene, watchScene} from './whitebox_scenes.js';
+import {SCENE_TEXT, pickScene, sceneList, startScene, watchScene} from './whitebox_scenes.js';
 import {chatData, chatDelay, chatReadRequest, emptyChat, chatMerge, chatEntries, canSend, newId, SEND_ATTEMPTS, WAIT_FOR_AGENT, sendRefused, sendError} from './chat_data.js';
 export {emptyChat, chatMerge, chatEntries, canSend} from './chat_data.js';
 import {isolateDialogKeys, listenDialogKey, routeDialogKey} from './dialog_keys.js';
@@ -279,6 +279,7 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
     function setWhiteboxPreview(enabled) {
         whiteboxPreview = enabled; whiteboxButton.setAttribute('aria-pressed', String(enabled));
         try { localStorage.setItem(WHITEBOX_PREVIEW.storageKey, String(enabled)); } catch {}
+        queueMicrotask(() => { if (!stopped) render(); });
     }
     whiteboxButton.setAttribute('aria-pressed', String(whiteboxPreview));
     if (initialWhiteboxPreview) setWhiteboxPreview(true);
@@ -304,11 +305,13 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
             }));
         }).catch(() => { sceneRows = null; toggleScenes(false); say(t(...SCENE_TEXT.failed) + t('Connection lost. Try again.', '连接中断，请重试。')); });
     }
-    async function runScene(preset, session = state.session) {
-        if (!session || stopped || sceneWaiting) return;
+    // `start` resolves with the scene's id; false means the video is made as usual (no ready-made scene fits).
+    async function runScene(preset, session = state.session, start = () => startScene(api, preset, session)) {
+        if (!session || stopped || sceneWaiting) return null;
         say(t(...SCENE_TEXT.preparing)); sceneWaiting = true;
         try {
-            const id = await startScene(api, preset, session);
+            const id = await start();
+            if (id === false) { sceneWaiting = false; say(''); return false; }
             const result = id ? await watchScene(api, id, {stopped: () => stopped, onState: value => { if (value.status === 'rendering') say(t(...SCENE_TEXT.rendering)); }}) : {status: 'ready'};
             if (result.status === 'failed') {
                 sceneWaiting = false; const why = (result.error || '').replace(/[.。]+$/, '');
@@ -319,6 +322,7 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
                 say(t(...(result.last === 'rendering' ? SCENE_TEXT.timeout : result.page_open ? SCENE_TEXT.notStarted : SCENE_TEXT.noPage)));
             }
         } catch (failure) { sceneWaiting = false; say(t(...SCENE_TEXT.failed) + reason(failure)); }
+        return true;
     }
     // Pictures waiting to be sent, per conversation draft: {key, url, attachment|null}. A picture is uploaded the moment it is added.
     const attachButton = press('fv-chat-attach', null, () => fileInput.click()), fileInput = el('input'), strip = el('ul', 'fv-chat-attached');
@@ -367,7 +371,7 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
     }
     function addPictures(files) {
         files = [...files || []];
-        if (!files.length || !composeAllowed()) return;
+        if (!files.length || !composeAllowed() || builtinScene()) return;
         const session = draftSession, list = stagedList(session), {accepted, problem} = pickPictures(files, ATTACH.count - list.length);
         say(problem ? t(...ATTACH[problem]) : '');
         for (const file of accepted) {
@@ -751,7 +755,8 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
     // A hidden page keeps reading, slowly, so that its title can tell what happened.
     const reading = () => !stopped && element.isConnected && shown();
     const inSelectedChat = () => !creating && (!selectedSession || selectedSession === state.session);
-    const composeAllowed = () => inSelectedChat() && state.agent.connected === true;
+    const builtinScene = () => whiteboxPreview && state.agent.connected !== true;
+    const composeAllowed = () => inSelectedChat() && (state.agent.connected === true || builtinScene() && !!state.session);
     const sendingAllowed = () => inSelectedChat() && canSend(state);
 
     const draftSending = () => pending.some(entry => entry.sending && entry.draft && entry.draft === drafts.get(draftSession));
@@ -1145,9 +1150,7 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
     const MAKE = {hello, examples, dots, user: () => message('user'), agent: () => message('agent'), job: jobCard, confirm: confirmCard};
 
     function render(follow = false) {
-        const builtin = state.agent?.builtin === true;
-        whiteboxButton.disabled = builtin;
-        whiteboxButton.title = builtin ? t('Not available with the built-in AI', '内置 AI 不支持白模') : t(...WHITEBOX_PREVIEW.name);
+        whiteboxButton.title = t(...WHITEBOX_PREVIEW.name);
         whiteboxButton.setAttribute('aria-label', whiteboxButton.title);
         const entries = chatEntries(state), ids = new Set(entries.map(entry => entry.id).filter(Boolean));
         for (const entry of pending) if (entry.session === state.session && ids.has(entry.id)) acknowledge(entry);
@@ -1193,8 +1196,9 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
             if (log.children[index] !== node.element) log.insertBefore(node.element, log.children[index] || null);
         });
         const sendable = sendingAllowed();
-        input.disabled = state.agent.connected !== true || creating || !!selectedSession && selectedSession !== state.session;
-        input.placeholder = state.agent.connected === true && !sendable ? t('Ask your agent to continue', '请在 Agent 里让它继续') : t('Message the agent…', '对 Agent 说…');
+        input.disabled = !(state.agent.connected === true || builtinScene() && !!state.session) || creating || !!selectedSession && selectedSession !== state.session;
+        input.placeholder = builtinScene() ? t(...SCENE_TEXT.describe)
+            : state.agent.connected === true && !sendable ? t('Ask your agent to continue', '请在 Agent 里让它继续') : t('Message the agent…', '对 Agent 说…');
         refreshSend();
         if (focusSession === state.session && focusSession && !input.disabled && active()) { focusSession = null; input.focus(); }
         if (stick) { pinned = true; scroller.scrollTop = scroller.scrollHeight; down.hidden = true; }
@@ -1251,7 +1255,16 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
             say(creating ? t('Creating a new chat…', '正在新建对话…') : t('Loading this chat. Please send again shortly.', '正在读取对话，请稍后再发一次'));
             return false;
         }
-        const entry = original || {id: newId(), text, attachments: attachments || [], session: state.session ?? null, draft, whiteboxPreview: whiteboxPreview && state.agent?.builtin !== true};
+        // With no Agent connected the white-model button is the way in: the sentence goes to the built-in AI, which
+        // picks a ready-made scene or says that none fits. It is never queued for an Agent.
+        if (builtinScene()) {
+            if (attachments?.length || original || !state.session) return false;
+            const made = await runScene(null, state.session, () => pickScene(api, text, state.session));
+            if (made === false) say(t(...SCENE_TEXT.failed) + t(...SCENE_TEXT.noFit));
+            else if (made === true) { input.value = ''; grow(); }
+            return made === true;
+        }
+        const entry = original || {id: newId(), text, attachments: attachments || [], session: state.session ?? null, draft, whiteboxPreview};
         if (draft) entry.draft = draft;
         if (!original) pending.push(entry);
         if (!automatic) entry.attempts = 0;
diff --git a/web/whitebox_scenes.js b/web/whitebox_scenes.js
index 0a770759..53458193 100644
--- a/web/whitebox_scenes.js
+++ b/web/whitebox_scenes.js
@@ -7,6 +7,8 @@ export const SCENE_TEXT = Object.freeze({
     label: ['Ready-made', '现成场景'], name: ['Start from a ready-made white-model scene', '用现成的白模场景开始'],
     preparing: ['Preparing the white model…', '正在准备白模…'], failed: ['The white model could not be made: ', '白模没有做成：'],
     rendering: ['Rendering the white model…', '正在渲染白模…'], retry: ['. Try again.', '。请重试。'],
+    noFit: ['no ready-made scene fits this sentence. Try again.', '没有适合这句话的现成场景。请重试。'],
+    describe: ['Describe the shot…', '描述一个镜头…'],
     bare: ['The white model could not be made. Try again.', '白模没有做成。请重试。'],
     noPage: ['The white model could not be made: the renderer is not running in this page. Reload the page and try again.', '白模没有做成：这个页面里的渲染没有运行。请刷新页面后重试。'],
     notStarted: ['The white model could not be made: rendering did not start within 3 minutes. Try again.', '白模没有做成：三分钟内渲染没有开始。请重试。'],
@@ -27,6 +29,14 @@ export async function startScene(api, preset, session) {
     return value?.id || null;
 }
 
+// The built-in AI picks a scene for the shot: the scene's id, or false when no ready-made scene fits.
+export async function pickScene(api, shot, session) {
+    const response = await agentPost(api, '/freevideo/agent/whitebox/try', {shot, ...(session ? {session} : {})});
+    const value = await response.json().catch(() => ({}));
+    if (!response.ok) throw new Error(value?.error?.message || value?.error?.code || `HTTP ${response.status}`);
+    return value?.id || false;
+}
+
 // Resolves with the scene's last state: 'ready' (the card follows), 'failed' (with error), or 'timeout' (with the
 // last state seen: 'waiting' nobody claimed it, 'rendering' it did not finish, page_open false no page was asking).
 // onState hears every state seen, so the page can say what is happening.

From 6febf08bc45ad9dad41380c852a7046dea3cec69 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 19:26:20 +0000
Subject: [PATCH 30/52] White-model no-fit sentence names the next step, and
 attach is disabled with the built-in AI

White-model no-fit sentence names the next step, attach button is disabled with the built-in AI, guide entry added.
---
 .../\344\275\277\347\224\250\350\257\264\346\230\216.md"      | 4 ++++
 web/autopilot_chat.js                                         | 1 +
 web/whitebox_scenes.js                                        | 2 +-
 3 files changed, 6 insertions(+), 1 deletion(-)

diff --git "a/docs/zh-CN/\344\275\277\347\224\250\350\257\264\346\230\216.md" "b/docs/zh-CN/\344\275\277\347\224\250\350\257\264\346\230\216.md"
index dcc7dfd2..53e0c03e 100644
--- "a/docs/zh-CN/\344\275\277\347\224\250\350\257\264\346\230\216.md"
+++ "b/docs/zh-CN/\344\275\277\347\224\250\350\257\264\346\230\216.md"
@@ -32,6 +32,10 @@
 - 编号顺序是：先是上传的素材，再是从上到下连接的图片，最后是音频。参考视频的声音也占一个音频编号。
 - 删除或关闭某张素材后，描述里指向它的标记会改成“[素材已移除]”，其余标记按新编号更新。
 
+## 用一句话做白模
+
+未连接外部 Agent 时，可开启聊天框中的白模按钮，用一句话描述镜头。有合适的现成场景时，会先生成白模供您确认。
+
 ## 做更长的视频
 
 有三种做法，可以单独用，也可以搭配。
diff --git a/web/autopilot_chat.js b/web/autopilot_chat.js
index 43091dc6..46d24378 100644
--- a/web/autopilot_chat.js
+++ b/web/autopilot_chat.js
@@ -1196,6 +1196,7 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
             if (log.children[index] !== node.element) log.insertBefore(node.element, log.children[index] || null);
         });
         const sendable = sendingAllowed();
+        attachButton.disabled = builtinScene();
         input.disabled = !(state.agent.connected === true || builtinScene() && !!state.session) || creating || !!selectedSession && selectedSession !== state.session;
         input.placeholder = builtinScene() ? t(...SCENE_TEXT.describe)
             : state.agent.connected === true && !sendable ? t('Ask your agent to continue', '请在 Agent 里让它继续') : t('Message the agent…', '对 Agent 说…');
diff --git a/web/whitebox_scenes.js b/web/whitebox_scenes.js
index 53458193..99b6e06d 100644
--- a/web/whitebox_scenes.js
+++ b/web/whitebox_scenes.js
@@ -7,7 +7,7 @@ export const SCENE_TEXT = Object.freeze({
     label: ['Ready-made', '现成场景'], name: ['Start from a ready-made white-model scene', '用现成的白模场景开始'],
     preparing: ['Preparing the white model…', '正在准备白模…'], failed: ['The white model could not be made: ', '白模没有做成：'],
     rendering: ['Rendering the white model…', '正在渲染白模…'], retry: ['. Try again.', '。请重试。'],
-    noFit: ['no ready-made scene fits this sentence. Try again.', '没有适合这句话的现成场景。请重试。'],
+    noFit: ['no ready-made scene fits this sentence. Describe the shot another way.', '没有适合这句话的现成场景。请换一种说法描述镜头。'],
     describe: ['Describe the shot…', '描述一个镜头…'],
     bare: ['The white model could not be made. Try again.', '白模没有做成。请重试。'],
     noPage: ['The white model could not be made: the renderer is not running in this page. Reload the page and try again.', '白模没有做成：这个页面里的渲染没有运行。请刷新页面后重试。'],

From 23cc578fd82283edae2309c9475ecc3d4cc93a15 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 23:45:16 +0000
Subject: [PATCH 31/52] White-model request that fails to reach the built-in AI
 keeps the typed sentence

---
 web/autopilot_chat.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/autopilot_chat.js b/web/autopilot_chat.js
index 46d24378..70da243f 100644
--- a/web/autopilot_chat.js
+++ b/web/autopilot_chat.js
@@ -321,7 +321,7 @@ export function agentChat(t, api, {open, edit, shown = () => true, changed = ()
                 sceneWaiting = false;
                 say(t(...(result.last === 'rendering' ? SCENE_TEXT.timeout : result.page_open ? SCENE_TEXT.notStarted : SCENE_TEXT.noPage)));
             }
-        } catch (failure) { sceneWaiting = false; say(t(...SCENE_TEXT.failed) + reason(failure)); }
+        } catch (failure) { sceneWaiting = false; say(t(...SCENE_TEXT.failed) + reason(failure)); return 'error'; }
         return true;
     }
     // Pictures waiting to be sent, per conversation draft: {key, url, attachment|null}. A picture is uploaded the moment it is added.

From b9e46019602eba94805426d366f70573f1367147 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 23:46:04 +0000
Subject: [PATCH 32/52] White-model no-fit sentence keeps its last phrase
 together on narrow screens

---
 web/whitebox_scenes.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/whitebox_scenes.js b/web/whitebox_scenes.js
index 99b6e06d..732fb194 100644
--- a/web/whitebox_scenes.js
+++ b/web/whitebox_scenes.js
@@ -7,7 +7,7 @@ export const SCENE_TEXT = Object.freeze({
     label: ['Ready-made', '现成场景'], name: ['Start from a ready-made white-model scene', '用现成的白模场景开始'],
     preparing: ['Preparing the white model…', '正在准备白模…'], failed: ['The white model could not be made: ', '白模没有做成：'],
     rendering: ['Rendering the white model…', '正在渲染白模…'], retry: ['. Try again.', '。请重试。'],
-    noFit: ['no ready-made scene fits this sentence. Describe the shot another way.', '没有适合这句话的现成场景。请换一种说法描述镜头。'],
+    noFit: ['no ready-made scene fits this sentence. Describe the shot another way.', '没有适合这句话的现成场景。请换一种说\u2060法描述镜头。'],
     describe: ['Describe the shot…', '描述一个镜头…'],
     bare: ['The white model could not be made. Try again.', '白模没有做成。请重试。'],
     noPage: ['The white model could not be made: the renderer is not running in this page. Reload the page and try again.', '白模没有做成：这个页面里的渲染没有运行。请刷新页面后重试。'],

From 5df0fea151b8f6dd5d0d6ccfcedc7c9b9ded9a07 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 21 Oct 2026 22:09:14 +0000
Subject: [PATCH 33/52] Record which process holds the installation lock when
 generation cannot start

---
 freevideo_engine/failure_details.py |  11 +-
 freevideo_engine/locking.py         | 195 +++++++++++++++++++++++++++-
 freevideo_engine/managed.py         |  29 ++++-
 web/error_panel.js                  |   2 +
 4 files changed, 229 insertions(+), 8 deletions(-)

diff --git a/freevideo_engine/failure_details.py b/freevideo_engine/failure_details.py
index 14b8531a..99ded67d 100644
--- a/freevideo_engine/failure_details.py
+++ b/freevideo_engine/failure_details.py
@@ -375,6 +375,7 @@ def launcher_failure(value, *, zh=False, other_disk=False, disk_name='', can_rep
         return dict(title='', detail='', action='', kind='')
     text = _without_ready_curl_diagnostics(str(value))
     # Match only the cause position, never an echoed input or a log line below it.
+    # Holder diagnostics follow this exact cause; they are not part of its signature.
     causes = [line.strip() for line in text.splitlines() if line.strip()]
     index = 1 if causes and re.fullmatch(r'FreeVideo generation failed(?: \(exit -?\d+\))?', causes[0]) else 0
     cause = re.sub(r'^(?:[A-Za-z_][\w.]*(?:Error|Exception)):\s*', '', causes[index]) if len(causes) > index else ''
@@ -897,10 +898,12 @@ def generation_failure(run, exit_code=None, *, repair=None):
     report = _report(run)
     redactor.structured(report)  # Collect prompt values without showing the request.
     # Read the whole bounded log, not a tail that could hide other output.
-    # A legacy managed failure has exactly this one nonempty line and exit 1.
-    if exit_code == 1 and [line for line in _read(run / 'generate.log', 8192).splitlines()
-                           if line.strip()] == [ENGINE_BUSY]:
-        lines.append(ENGINE_BUSY)
+    # Managed failures contain only the exact busy sentence and optional holder
+    # diagnostics. Other output must never acquire a busy classification.
+    busy_lines = [line for line in _read(run / 'generate.log', 8192).splitlines() if line.strip()]
+    if exit_code == 1 and busy_lines[:1] == [ENGINE_BUSY] \
+            and all(line.startswith('Lock holder:') for line in busy_lines[1:]):
+        lines.extend(busy_lines)
     # What the worker found when cuDNN refused its own files, ahead of the trace.
     explained = _runtime_explanation(report, REPAIR_MARK)
     if explained:
diff --git a/freevideo_engine/locking.py b/freevideo_engine/locking.py
index 9524bc6f..9748aa99 100644
--- a/freevideo_engine/locking.py
+++ b/freevideo_engine/locking.py
@@ -11,6 +11,7 @@
 from pathlib import Path
 import re
 import sys
+import threading
 import time
 
 
@@ -22,23 +23,31 @@
 ENGINE_BUSY = 'Setup, testing or generation is already using this installation/GPU lock. Retry after it finishes.'
 
 
-def lock_holders(paths):
+def lock_holders(paths, *, deadline=None):
     """Read-only Linux diagnostics, including orphans retaining inherited FDs."""
     if windows() or not Path('/proc/self/fd').is_dir():
         return []
     identities = set()
     for path in paths:
+        if deadline is not None and time.monotonic() >= deadline:
+            break
         try:
             item = Path(path).stat()
             identities.add((item.st_dev, item.st_ino))
         except OSError:
             pass
     holders = []
+    if not identities:
+        return []
     for directory in Path('/proc').iterdir():
+        if deadline is not None and time.monotonic() >= deadline:
+            break
         if not directory.name.isdigit():
             continue
         try:
             for fd in (directory / 'fd').iterdir():
+                if deadline is not None and time.monotonic() >= deadline:
+                    break
                 try:
                     item = fd.stat()
                     if (item.st_dev, item.st_ino) in identities:
@@ -51,6 +60,190 @@ def lock_holders(paths):
     return sorted(holders)
 
 
+# Only these small, public command identifiers may leave process diagnostics.
+_COMMAND_WORD = re.compile(r'[a-z][a-z0-9_.-]{0,40}\Z')
+_EXECUTABLE = re.compile(r'[A-Za-z0-9_][A-Za-z0-9_.-]{0,80}\Z')
+_HOLDER_TIMEOUT = 2.0
+
+
+def _executable_basename(value):
+    name = value.replace('\\', '/').rsplit('/', 1)[-1]
+    return name if _EXECUTABLE.fullmatch(name) else 'unknown'
+
+
+def _lock_command(cmdline):
+    """Pure allowlist parser: no scripts, option values, prompts or environment."""
+    arguments = cmdline.decode('utf-8', errors='replace').rstrip('\0').split('\0')
+    executable = _executable_basename(arguments[0])
+    index = 1
+    # Do not mistake a script/-c argument or an option's value for Python's -m.
+    while index < len(arguments) and arguments[index] in (
+            '-B', '-u', '-E', '-s', '-S', '-I', '-O', '-OO', '-q', '-P'):
+        index += 1
+    words = []
+    if index < len(arguments) and arguments[index] == '-m':
+        for word in arguments[index + 1:index + 4]:
+            if not _COMMAND_WORD.fullmatch(word):
+                break  # Never skip an option/path to expose its value as a word.
+            words.append(word)
+    return executable, ' '.join(words)
+
+
+def _holder_line(pid, executable, command='', seconds=None):
+    line = f'Lock holder: pid {int(pid)}, {_executable_basename(executable)}'
+    if command:
+        line += f' ({command})'
+    if seconds is not None and math.isfinite(seconds) and seconds >= 0:
+        line += f', running {int(seconds)} s'
+    return line
+
+
+def _linux_holder(pid):
+    executable, command, seconds = 'unknown', '', None
+    try:
+        with (Path('/proc') / str(pid) / 'cmdline').open('rb') as stream:
+            executable, command = _lock_command(stream.read(65536))
+    except Exception:
+        pass
+    try:
+        # comm may itself contain spaces and parentheses; starttime is field 22.
+        stat = (Path('/proc') / str(pid) / 'stat').read_text()
+        ticks = int(stat.rsplit(')', 1)[1].split()[19])
+        uptime = float(Path('/proc/uptime').read_text().split()[0])
+        seconds = uptime - ticks / os.sysconf('SC_CLK_TCK')
+    except Exception:
+        pass
+    return _holder_line(pid, executable, command, seconds)
+
+
+def _windows_lock_holders(paths, deadline, lines):
+    """Restart Manager is read-only here: never request a shutdown or restart."""
+    import ctypes
+    from ctypes import POINTER, c_int32, c_uint32, c_void_p, c_wchar, c_wchar_p
+
+    class FileTime(ctypes.Structure):
+        _fields_ = [('low', c_uint32), ('high', c_uint32)]
+
+    class UniqueProcess(ctypes.Structure):
+        _fields_ = [('pid', c_uint32), ('started', FileTime)]
+
+    class ProcessInfo(ctypes.Structure):
+        _fields_ = [('process', UniqueProcess), ('app', c_wchar * 256),
+                    ('service', c_wchar * 64), ('kind', c_int32),
+                    ('status', c_uint32), ('session', c_uint32), ('restartable', c_int32)]
+
+    manager = ctypes.WinDLL('rstrtmgr.dll', use_last_error=True)
+    kernel = ctypes.WinDLL('kernel32.dll', use_last_error=True)
+    signatures = (
+        (manager.RmStartSession, [POINTER(c_uint32), c_uint32, c_wchar_p], c_uint32),
+        (manager.RmRegisterResources, [c_uint32, c_uint32, POINTER(c_wchar_p), c_uint32,
+                                      POINTER(UniqueProcess), c_uint32, POINTER(c_wchar_p)], c_uint32),
+        (manager.RmGetList, [c_uint32, POINTER(c_uint32), POINTER(c_uint32),
+                           POINTER(ProcessInfo), POINTER(c_uint32)], c_uint32),
+        (manager.RmEndSession, [c_uint32], c_uint32),
+        (kernel.OpenProcess, [c_uint32, c_int32, c_uint32], c_void_p),
+        (kernel.QueryFullProcessImageNameW, [c_void_p, c_uint32, c_wchar_p, POINTER(c_uint32)], c_int32),
+        (kernel.CloseHandle, [c_void_p], c_int32),
+    )
+    for function, arguments, result in signatures:
+        function.argtypes, function.restype = arguments, result
+    session = c_uint32()
+    if time.monotonic() >= deadline or manager.RmStartSession(ctypes.byref(session), 0, ctypes.create_unicode_buffer(33)):
+        return
+    try:
+        resources = (c_wchar_p * len(paths))(*(str(Path(path).absolute()) for path in paths))
+        if not resources or time.monotonic() >= deadline:
+            return
+        if manager.RmRegisterResources(session, len(resources), resources, 0, None, 0, None):
+            return
+        needed, count, reason = c_uint32(), c_uint32(), c_uint32()
+        items = None
+        # The list can grow between calls. Bound both allocation and retries.
+        for _ in range(3):
+            if time.monotonic() >= deadline:
+                return
+            status = manager.RmGetList(session, ctypes.byref(needed), ctypes.byref(count), items, ctypes.byref(reason))
+            if status == 0:
+                break
+            if status != 234 or not 0 < needed.value <= 4096:  # ERROR_MORE_DATA
+                return
+            count.value = needed.value
+            items = (ProcessInfo * count.value)()
+        else:
+            return
+        holders = {item.process.pid: item for item in (items or ())[:count.value]
+                   if item.process.pid and item.process.pid != os.getpid()}
+        for pid in sorted(holders)[:5]:
+            if time.monotonic() >= deadline:
+                return
+            item = holders[pid]
+            executable = _executable_basename(item.app)
+            seconds = None
+            try:
+                ticks = (item.process.started.high << 32) | item.process.started.low
+                if ticks:
+                    seconds = time.time() - (ticks / 10_000_000 - 11_644_473_600)
+            except Exception:
+                pass
+            # RM's app name is the fallback when the process has exited or access
+            # is denied. QueryFullProcessImageNameW returns no command arguments.
+            position = len(lines)
+            lines.append(_holder_line(pid, executable, seconds=seconds))
+            handle = None
+            try:
+                handle = kernel.OpenProcess(0x1000, False, pid)  # QUERY_LIMITED_INFORMATION
+                if handle and time.monotonic() < deadline:
+                    image = ctypes.create_unicode_buffer(32768)
+                    size = c_uint32(len(image))
+                    if kernel.QueryFullProcessImageNameW(handle, 0, image, ctypes.byref(size)):
+                        lines[position] = _holder_line(pid, image.value, seconds=seconds)
+            except Exception:
+                pass
+            finally:
+                if handle:
+                    kernel.CloseHandle(handle)
+        if len(holders) > 5:
+            lines.append(f'Lock holder: and {len(holders) - 5} more')
+    finally:
+        manager.RmEndSession(session)
+
+
+def describe_lock_holders(paths) -> list[str]:
+    """Best-effort, redacted diagnostics; even a stalled OS call gets two seconds.
+
+    A daemon thread is deliberate: native calls have no timeout, and an attempt
+    to cancel Restart Manager must not delay the busy exit or interpreter exit.
+    Completed rows remain available if a later process/API query fails or hangs.
+    """
+    lines = []
+
+    def query():
+        try:
+            if windows():
+                _windows_lock_holders(paths, deadline, lines)
+            else:
+                holders = sorted(set(lock_holders(paths, deadline=deadline)) - {os.getpid()})
+                for pid in holders[:5]:
+                    if time.monotonic() >= deadline:
+                        return
+                    lines.append(_linux_holder(pid))
+                if len(holders) > 5:
+                    lines.append(f'Lock holder: and {len(holders) - 5} more')
+        except Exception:
+            pass
+        finally:
+            done.set()
+
+    try:
+        deadline = time.monotonic() + _HOLDER_TIMEOUT
+        done = threading.Event()
+        threading.Thread(target=query, daemon=True, name='lock-holder-diagnostics').start()
+        done.wait(max(0, deadline - time.monotonic()))
+    except Exception:
+        pass
+    return lines[:]
+
+
 def device_lock_path(device, path=None):
     """The lease for one device, beside the machine lease it shares a root with."""
     base = Path(path or os.environ.get('FREEVIDEO_LOCK_PATH', data_root() / 'engine.lock'))
diff --git a/freevideo_engine/managed.py b/freevideo_engine/managed.py
index 25ef5a8a..a19e17e8 100644
--- a/freevideo_engine/managed.py
+++ b/freevideo_engine/managed.py
@@ -9,7 +9,7 @@
 from .agent import enabled as agent_enabled
 from .bootstrap import DEFAULT_ROOT
 from . import __version__
-from .locking import runtime_lock, LOCK_ENV, ENGINE_BUSY
+from .locking import runtime_lock, describe_lock_holders, LOCK_ENV, ENGINE_BUSY
 from . import processes
 from .system import windows
 
@@ -39,7 +39,7 @@ def command_for(machine, command, arguments):
     return [machine['python'], '-m', 'freevideo_engine', command, *extra, *arguments]
 
 
-def _main(argv=None):
+def _main(argv=None, *, lock_paths=None):
     argv = list(sys.argv[1:] if argv is None else argv)
     parser = argparse.ArgumentParser(prog='./freevideo', add_help=False)
     parser.add_argument('--root', type=Path, default=Path(os.environ.get('FREEVIDEO_HOME', DEFAULT_ROOT)))
@@ -117,6 +117,8 @@ def _main(argv=None):
                 or (command == 'doctor' and '--probe' not in tail) or '--help' in tail or '-h' in tail)
     snapshot = json.loads(config.read_text(encoding='utf-8'))
     lock_path = os.environ.get('FREEVIDEO_LOCK_PATH', str(Path(snapshot['root']) / 'engine.lock'))
+    if lock_paths is not None:
+        lock_paths.append(lock_path)
     with nullcontext() if readonly else runtime_lock(lock_path, wait_seconds=3 if command == 'generate' else 0) as descriptor:
         machine = json.loads(config.read_text(encoding='utf-8'))
         if machine != snapshot:
@@ -137,10 +139,31 @@ def _main(argv=None):
 
 
 def main(argv=None):
+    lock_paths = []
     try:
-        return _main(argv)
+        return _main(argv, lock_paths=lock_paths)
     except BlockingIOError:
         print(ENGINE_BUSY, file=sys.stderr)
+        try:
+            if not lock_paths:
+                # Normally _main supplies the configured path. Keep failures
+                # before that point best-effort, without reading configuration.
+                path = os.environ.get('FREEVIDEO_LOCK_PATH')
+                if path:
+                    lock_paths.append(path)
+                else:
+                    arguments = list(sys.argv[1:] if argv is None else argv)
+                    root = os.environ.get('FREEVIDEO_HOME', DEFAULT_ROOT)
+                    for index, argument in enumerate(arguments):
+                        if argument == '--root':
+                            root = arguments[index + 1]
+                        elif argument.startswith('--root='):
+                            root = argument.partition('=')[2]
+                    lock_paths.append(Path(root) / 'engine.lock')
+            for line in describe_lock_holders(lock_paths):
+                print(line, file=sys.stderr)
+        except Exception:
+            pass
         return 1
     except KeyboardInterrupt:
         print('Cancelled. Workers stopped; existing outputs and reports retained.', file=sys.stderr)
diff --git a/web/error_panel.js b/web/error_panel.js
index ac8efa2a..e5792a4b 100644
--- a/web/error_panel.js
+++ b/web/error_panel.js
@@ -89,6 +89,8 @@ const PLAIN_ERRORS = [
 // line counts (after an optional "ValueError: "), or the line right under the
 // worker's "FreeVideo generation failed" header, so an input echoed inside or
 // below another error, even one line of a longer prompt, never turns into this advice.
+// Optional "Lock holder:" diagnostic lines follow the engine-busy cause; keep
+// matching its exact first line, so those details cannot become a new signature.
 function knownError(text) {
     const lines = String(text).slice(0, 65536).split(/\r?\n/).map(line => line.trim()).filter(Boolean);
     const index = /^FreeVideo generation failed(?: \(exit -?\d+\))?$/.test(lines[0] ?? '') ? 1 : 0;

From 93b00be25a3c25dcb2a40fe4ec4c28d00da0d0d3 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sun, 25 Oct 2026 08:21:49 +0000
Subject: [PATCH 34/52] Keep a foreign module's arguments out of the lock
 holder report

Keep a foreign module's arguments out of the lock holder report, say the file is open rather than held, and give the deadline test room.
---
 freevideo_engine/failure_details.py |  2 +-
 freevideo_engine/locking.py         | 11 +++++++----
 web/error_panel.js                  |  2 +-
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/freevideo_engine/failure_details.py b/freevideo_engine/failure_details.py
index 99ded67d..1a88a9c1 100644
--- a/freevideo_engine/failure_details.py
+++ b/freevideo_engine/failure_details.py
@@ -902,7 +902,7 @@ def generation_failure(run, exit_code=None, *, repair=None):
     # diagnostics. Other output must never acquire a busy classification.
     busy_lines = [line for line in _read(run / 'generate.log', 8192).splitlines() if line.strip()]
     if exit_code == 1 and busy_lines[:1] == [ENGINE_BUSY] \
-            and all(line.startswith('Lock holder:') for line in busy_lines[1:]):
+            and all(line.startswith('Lock file open:') for line in busy_lines[1:]):
         lines.extend(busy_lines)
     # What the worker found when cuDNN refused its own files, ahead of the trace.
     explained = _runtime_explanation(report, REPAIR_MARK)
diff --git a/freevideo_engine/locking.py b/freevideo_engine/locking.py
index 9748aa99..2acd4a47 100644
--- a/freevideo_engine/locking.py
+++ b/freevideo_engine/locking.py
@@ -82,7 +82,10 @@ def _lock_command(cmdline):
         index += 1
     words = []
     if index < len(arguments) and arguments[index] == '-m':
-        for word in arguments[index + 1:index + 4]:
+        # Words after the module are that program's own arguments. Only our own
+        # modules have subcommands known not to carry private values.
+        own = arguments[index + 1].startswith('freevideo_engine') if index + 1 < len(arguments) else False
+        for word in arguments[index + 1:index + (4 if own else 2)]:
             if not _COMMAND_WORD.fullmatch(word):
                 break  # Never skip an option/path to expose its value as a word.
             words.append(word)
@@ -90,7 +93,7 @@ def _lock_command(cmdline):
 
 
 def _holder_line(pid, executable, command='', seconds=None):
-    line = f'Lock holder: pid {int(pid)}, {_executable_basename(executable)}'
+    line = f'Lock file open: pid {int(pid)}, {_executable_basename(executable)}'
     if command:
         line += f' ({command})'
     if seconds is not None and math.isfinite(seconds) and seconds >= 0:
@@ -203,7 +206,7 @@ class ProcessInfo(ctypes.Structure):
                 if handle:
                     kernel.CloseHandle(handle)
         if len(holders) > 5:
-            lines.append(f'Lock holder: and {len(holders) - 5} more')
+            lines.append(f'Lock file open: and {len(holders) - 5} more')
     finally:
         manager.RmEndSession(session)
 
@@ -228,7 +231,7 @@ def query():
                         return
                     lines.append(_linux_holder(pid))
                 if len(holders) > 5:
-                    lines.append(f'Lock holder: and {len(holders) - 5} more')
+                    lines.append(f'Lock file open: and {len(holders) - 5} more')
         except Exception:
             pass
         finally:
diff --git a/web/error_panel.js b/web/error_panel.js
index e5792a4b..97c4d051 100644
--- a/web/error_panel.js
+++ b/web/error_panel.js
@@ -89,7 +89,7 @@ const PLAIN_ERRORS = [
 // line counts (after an optional "ValueError: "), or the line right under the
 // worker's "FreeVideo generation failed" header, so an input echoed inside or
 // below another error, even one line of a longer prompt, never turns into this advice.
-// Optional "Lock holder:" diagnostic lines follow the engine-busy cause; keep
+// Optional "Lock file open:" diagnostic lines follow the engine-busy cause; keep
 // matching its exact first line, so those details cannot become a new signature.
 function knownError(text) {
     const lines = String(text).slice(0, 65536).split(/\r?\n/).map(line => line.trim()).filter(Boolean);

From 84ca136ccd17280119358c375d570223c1e49c24 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 21 Oct 2026 12:18:11 +0000
Subject: [PATCH 35/52] Confirm a recovered Windows video-memory budget at each
 pass boundary before the next pass allocates

---
 freevideo_engine/gpu_budget.py | 11 ++++++++++-
 freevideo_engine/worker.py     | 12 ++++++------
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/freevideo_engine/gpu_budget.py b/freevideo_engine/gpu_budget.py
index 83a7420b..e04733e0 100644
--- a/freevideo_engine/gpu_budget.py
+++ b/freevideo_engine/gpu_budget.py
@@ -305,13 +305,22 @@ def _settle(self, workspace):
                 return min(seen), samples
         return None, samples
 
-    def refresh(self, stage, reclaim=None, workspace=None):
+    def refresh(self, stage, reclaim=None, workspace=None, confirm=False):
         cuda = self.torch.cuda
         free, reserved, local, decision, known, candidate = self._observe()
         target, action = self.limit, 'hold'
         if candidate < self.limit:
             target, action, self.pending = candidate, 'shrink', None
         elif candidate >= self.limit + 64 * 2**20:
+            if self.pending is None and confirm:
+                # A pass boundary has no earlier step to have seen the larger
+                # budget, and the next pass allocates against this limit at
+                # once. Confirm with a second reading here instead of starting
+                # it under a cap left over from the last pass's pressure.
+                self.sleep(SETTLE_INTERVAL)
+                *_, again_known, again = self._observe()
+                if again_known and again >= self.limit + 64 * 2**20:
+                    self.pending = candidate = min(candidate, again)
             if self.pending is not None:
                 target, action = min(candidate, self.pending), 'grow'
                 self.pending = None
diff --git a/freevideo_engine/worker.py b/freevideo_engine/worker.py
index ac812592..ba03bf6b 100644
--- a/freevideo_engine/worker.py
+++ b/freevideo_engine/worker.py
@@ -130,7 +130,7 @@ def released(engine):
             live_budget = LiveGPUBudget(torch, metrics['device_memory'],
                 request.get('gpu_capacity_bytes', metrics['device_memory']['device_total_bytes']) - reserve, reserve)
 
-        def refresh_budget(stage, reclaim=None, workspace=None):
+        def refresh_budget(stage, reclaim=None, workspace=None, confirm=False):
             def release(target):
                 if reclaim is not None:
                     reclaim(target)
@@ -140,7 +140,7 @@ def release(target):
                             break
                         if role != 'engine' or stage == 'decode':
                             resident.drop(role, 'Live GPU budget decreased')
-            limit = live_budget.refresh(stage, release, workspace=workspace)
+            limit = live_budget.refresh(stage, release, workspace=workspace, confirm=confirm)
             if resident is not None:
                 resident.gpu_budget = limit
             return limit
@@ -443,7 +443,7 @@ def sampling_complete(latents, audio, sampled):
                                                       total=sampling_plan['total_steps'])):
                                 tick = time.perf_counter()
                                 if live_budget is not None:
-                                    refresh_budget('upscale')
+                                    refresh_budget('upscale', confirm=True)
                                 need = upscale_workspace(sampling_plan['upscale_target']) if sampling_plan['upscaler_sha256'] else 0
                                 # Its weights go straight to the GPU. Charging 2 GiB of
                                 # host RAM evicted the second pass's own engine on
@@ -565,9 +565,9 @@ def refined_complete(video, sound, receipt):
                                      lora=bool(manifest.get('online_lora')))
                         head_need = windows_int8_refinement_head_need(engine.config, canvas, **guard)
                         second_compute = None
+                        if live_budget is not None:
+                            refresh_budget('refine', confirm=True)
                         if head_need is not None:
-                            if live_budget is not None:
-                                refresh_budget('refine')
                             limit = metrics['device_memory'].get('effective_allocator_limit_bytes')
                             second_compute = windows_int8_refinement_heads(engine.config, canvas, limit, **guard)
                             if second_compute:
@@ -627,7 +627,7 @@ def refined_complete(video, sound, receipt):
             metrics['decode_phase'] = 'decoder_admission'
         metrics['phase'] = 'decode'
         if live_budget is not None:
-            refresh_budget('decode')
+            refresh_budget('decode', confirm=True)
             if engine is not None:
                 metrics['transformer_released_before_decode'] = released(engine)
         if resident is not None:

From 1f1b43ab2f41ce6e08ce71968f541f09ac3848ac Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sat, 24 Oct 2026 23:43:37 +0000
Subject: [PATCH 36/52] Find the installer's own Git and restore long lists of
 files in batches

Restore deleted tokenizer files from the pinned local source checkout before
encoding and during Repair, and explain missing encoder files in both languages.
Use the installer's recorded Git when no other Git is available and restore
long file lists in batches. Preserve the existing Windows long-path checks.
---
 freevideo_engine/encode_worker.py  |   2 +
 freevideo_engine/encoder_source.py | 105 +++++++++++++++++++++++++++++
 freevideo_engine/network.py        |   5 ++
 web/error_panel.js                 |   5 ++
 4 files changed, 117 insertions(+)
 create mode 100644 freevideo_engine/encoder_source.py

diff --git a/freevideo_engine/encode_worker.py b/freevideo_engine/encode_worker.py
index 1ea774db..6f173580 100644
--- a/freevideo_engine/encode_worker.py
+++ b/freevideo_engine/encode_worker.py
@@ -263,6 +263,8 @@ def phase(name, **metrics):
             return dict(state='skipped', resource_decision=decision,
                         reason='Foreground work or insufficient live memory for idle preloading')
     phase('encoder_options')
+    from .encoder_source import ensure
+    ensure(args.comfy_root)
     sys.path.insert(0, str(args.comfy_root.resolve()))
     import comfy.options
     comfy.options.enable_args_parsing()
diff --git a/freevideo_engine/encoder_source.py b/freevideo_engine/encoder_source.py
new file mode 100644
index 00000000..100bfd0f
--- /dev/null
+++ b/freevideo_engine/encoder_source.py
@@ -0,0 +1,105 @@
+"""Keep the encoder's pinned ComfyUI source tree whole.
+
+The tree is a sparse Git checkout of one commit, so a file that disappears after
+installation (security software, a cleanup tool) is still in the local object
+store: put it back from there instead of downloading anything.
+"""
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+from . import subprocess_output
+from .paths import data_root
+from .windows_ux import hidden_console
+
+# Read when the native Qwen tokenizer is built. Without vocab.json or merges.txt
+# the tokenizers library fails with an error that names neither file.
+REQUIRED = ('comfy/text_encoders/qwen25_tokenizer/vocab.json',
+            'comfy/text_encoders/qwen25_tokenizer/merges.txt',
+            'comfy/text_encoders/qwen25_tokenizer/tokenizer_config.json')
+
+
+# A Windows command line holds 32767 characters; a deleted tree can name more paths than that.
+BATCH = 8000
+
+
+class EncoderSourceError(RuntimeError):
+    """Text encoder files are missing and could not be restored."""
+
+
+def executable(env=None):
+    """The Git to use: the one the installer exported, one on PATH, else the one it recorded.
+
+    Windows installs keep their own MinGit under the installation folder and
+    note it only in machine.json, so a machine without a system Git has neither
+    of the first two.
+    """
+    found = (env or os.environ).get('FREEVIDEO_GIT') or shutil.which('git')
+    if found:
+        return found
+    try:
+        recorded = json.loads((data_root() / 'machine.json').read_text(encoding='utf-8')).get('git')
+    except (OSError, ValueError, AttributeError):
+        return None
+    return recorded if recorded and Path(recorded).is_file() else None
+
+
+def missing(root):
+    return [name for name in REQUIRED if not (Path(root) / name).is_file()]
+
+
+def deleted(root, env=None):
+    """Tracked files that are gone from the work tree; None if Git cannot say."""
+    git = executable(env)
+    if not git or not (Path(root) / '.git').exists():
+        return None
+    try:
+        result = subprocess_output.run_external([git, '-C', str(root), 'ls-files', '-d', '-z'],
+            env=env, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=60, **hidden_console())
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    if result.returncode:
+        return None
+    return [name for name in (result.stdout or '').split('\0') if name]
+
+
+def restore(root, names, env=None):
+    """Check the named tracked files out again; True if every command succeeded."""
+    git = executable(env)
+    if not git or not names:
+        return False
+    batches, used = [[]], 0
+    for name in names:
+        if batches[-1] and used + len(name) + 1 > BATCH:
+            batches.append([])
+            used = 0
+        batches[-1].append(name)
+        used += len(name) + 1
+    for batch in batches:
+        try:
+            result = subprocess_output.run_external([git, '-C', str(root), 'checkout', '--', *batch],
+                env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=120, **hidden_console())
+        except (OSError, ValueError, subprocess.SubprocessError):
+            return False
+        if result.returncode:
+            return False
+    return True
+
+
+def ensure(root, env=None):
+    """Restore the tokenizer files if they are gone; the usual case reads three paths only."""
+    absent = missing(root)
+    if not absent:
+        return []
+    gone = deleted(root, env)
+    # Another ComfyUI layout, or no Git to ask: leave it to the library.
+    lost = [name for name in absent if name in (gone or ())]
+    if not lost:
+        return []
+    restore(root, gone, env)
+    lost = missing(root)
+    if lost:
+        raise EncoderSourceError('FreeVideo text encoder files are missing: %s' % ', '.join(lost))
+    return gone
diff --git a/freevideo_engine/network.py b/freevideo_engine/network.py
index cb811cad..75152447 100644
--- a/freevideo_engine/network.py
+++ b/freevideo_engine/network.py
@@ -1607,6 +1607,11 @@ def clone(target, url, commit, *, sparse=None, run=None, network=None, env=None)
             head, dirty = repository_state(target, git, env)
         except (subprocess.CalledProcessError, OSError):
             head, dirty = None, ''  # Git cannot read it as a repository of its own.
+        if head == commit and dirty and all(line[:2] == ' D' for line in dirty.splitlines()):
+            # Files deleted after installation: the same commit's objects are still local, nothing is downloaded.
+            from . import encoder_source
+            if encoder_source.restore(target, encoder_source.deleted(target, env), env):
+                head, dirty = repository_state(target, git, env)
         if head == commit and not dirty:
             return target
         if target.parent.name == 'vendor' and git_settings_out_of_reach(target):
diff --git a/web/error_panel.js b/web/error_panel.js
index 97c4d051..54d6e176 100644
--- a/web/error_panel.js
+++ b/web/error_panel.js
@@ -422,6 +422,11 @@ export function failureAdvice(value, t, known = knownError(value)) {
         return row('model-files', ['The model is not fully installed', '模型没有装全'],
             ['Some of the model files FreeVideo needs are missing.', 'FreeVideo 需要的部分模型文件缺失。'],
             repairAction());
+    // The second form is the tokenizers library's own error when its vocab or merges file is gone.
+    if (/FreeVideo text encoder files are missing|`vocab` and `merges` must be both be from memory/i.test(text))
+        return row('encoder-files', ['The text encoder is not fully installed', '文本编码器没有装全'],
+            ['Some of the text encoder files FreeVideo needs are missing.', 'FreeVideo 需要的部分文本编码器文件缺失。'],
+            repairAction());
     if (/No space left on device|WinError 112|disk (?:is )?full/i.test(text))
         return row('disk', ['Disk space is insufficient', '磁盘空间不足'],
             ['FreeVideo could not write a required file.', 'FreeVideo 无法写入所需文件。'],

From 81f6ffe1c3e124fa03bdbc395054cb2be837b21d Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Sun, 25 Oct 2026 11:09:33 +0000
Subject: [PATCH 37/52] Restrict encoder source restoration to safe managed
 checkouts

---
 freevideo_engine/encoder_source.py | 47 +++++++++++++++++++++++-------
 freevideo_engine/network.py        |  2 +-
 2 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/freevideo_engine/encoder_source.py b/freevideo_engine/encoder_source.py
index 100bfd0f..2a9ea46c 100644
--- a/freevideo_engine/encoder_source.py
+++ b/freevideo_engine/encoder_source.py
@@ -8,9 +8,11 @@
 import os
 from pathlib import Path
 import shutil
+import stat
 import subprocess
 
 from . import subprocess_output
+from .long_paths import io_path
 from .paths import data_root
 from .windows_ux import hidden_console
 
@@ -41,9 +43,32 @@ def executable(env=None):
         return found
     try:
         recorded = json.loads((data_root() / 'machine.json').read_text(encoding='utf-8')).get('git')
+        if isinstance(recorded, str) and recorded.strip() and Path(recorded).is_file():
+            return recorded
     except (OSError, ValueError, AttributeError):
-        return None
-    return recorded if recorded and Path(recorded).is_file() else None
+        pass
+    return None
+
+
+def managed(root, env=None):
+    """Only the installer's vendor checkout, with no linked path or Git directory."""
+    environ = os.environ if env is None else env
+    home = Path(environ['FREEVIDEO_HOME']).expanduser() if environ.get('FREEVIDEO_HOME') else data_root()
+    root = Path(root).expanduser().absolute()
+    expected = (home / 'vendor' / 'h3-text-encoder').absolute()
+    if root != expected or '..' in root.parts:
+        return False
+    try:
+        # Do not resolve first: that would hide symlinks, junctions and other
+        # reparse points, including one in an ancestor of the installation.
+        for path in (root / '.git', root, *root.parents):
+            info = io_path(path).lstat()
+            if (not stat.S_ISDIR(info.st_mode) or
+                    getattr(info, 'st_file_attributes', 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT):
+                return False
+    except (OSError, ValueError):
+        return False
+    return True
 
 
 def missing(root):
@@ -56,7 +81,8 @@ def deleted(root, env=None):
     if not git or not (Path(root) / '.git').exists():
         return None
     try:
-        result = subprocess_output.run_external([git, '-C', str(root), 'ls-files', '-d', '-z'],
+        result = subprocess_output.run_external([git, '--literal-pathspecs', '-c', 'core.longpaths=true',
+            '-C', str(root), 'ls-files', '-d', '-z'],
             env=env, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=60, **hidden_console())
     except (OSError, ValueError, subprocess.SubprocessError):
         return None
@@ -79,7 +105,8 @@ def restore(root, names, env=None):
         used += len(name) + 1
     for batch in batches:
         try:
-            result = subprocess_output.run_external([git, '-C', str(root), 'checkout', '--', *batch],
+            result = subprocess_output.run_external([git, '--literal-pathspecs', '-c', 'core.longpaths=true',
+                '-C', str(root), 'checkout', '--', *batch],
                 env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=120, **hidden_console())
         except (OSError, ValueError, subprocess.SubprocessError):
             return False
@@ -89,17 +116,17 @@ def restore(root, names, env=None):
 
 
 def ensure(root, env=None):
-    """Restore the tokenizer files if they are gone; the usual case reads three paths only."""
+    """Restore missing vendor files; custom ComfyUI checkouts stay read-only."""
     absent = missing(root)
-    if not absent:
+    if not absent or not managed(root, env):
         return []
     gone = deleted(root, env)
     # Another ComfyUI layout, or no Git to ask: leave it to the library.
     lost = [name for name in absent if name in (gone or ())]
     if not lost:
         return []
-    restore(root, gone, env)
-    lost = missing(root)
-    if lost:
-        raise EncoderSourceError('FreeVideo text encoder files are missing: %s' % ', '.join(lost))
+    restored = restore(root, gone, env)
+    lost = missing(root) if restored else [name for name in gone if not io_path(Path(root) / name).exists()]
+    if not restored or lost:
+        raise EncoderSourceError('FreeVideo text encoder files are missing: %s' % ', '.join(lost[:10]))
     return gone
diff --git a/freevideo_engine/network.py b/freevideo_engine/network.py
index 75152447..79131f5b 100644
--- a/freevideo_engine/network.py
+++ b/freevideo_engine/network.py
@@ -1610,7 +1610,7 @@ def clone(target, url, commit, *, sparse=None, run=None, network=None, env=None)
         if head == commit and dirty and all(line[:2] == ' D' for line in dirty.splitlines()):
             # Files deleted after installation: the same commit's objects are still local, nothing is downloaded.
             from . import encoder_source
-            if encoder_source.restore(target, encoder_source.deleted(target, env), env):
+            if encoder_source.managed(target, env) and encoder_source.restore(target, encoder_source.deleted(target, env), env):
                 head, dirty = repository_state(target, git, env)
         if head == commit and not dirty:
             return target

From 3e34ff38f5e2cfcda58d07e287eb1741d474e77a Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 06:58:51 +0000
Subject: [PATCH 38/52] Editor: say a description over the limit before
 sending, on a retry too, and drop lone surrogates

---
 web/editor.js | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/web/editor.js b/web/editor.js
index bac41e14..bf27b932 100644
--- a/web/editor.js
+++ b/web/editor.js
@@ -43,6 +43,10 @@ const editorStyles = Promise.all(['result_actions.css', 'editor.css', 'editor_ex
 }));
 const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
 const language = () => new URLSearchParams(location.search).get('freevideo_lang') || navigator.language;
+// A half of a surrogate pair left by a cut or a paste is dropped; the description limit counts characters, not code units.
+export const wellFormed = text => typeof text === 'string' ? text.replace(/[\ud800-\udbff][\udc00-\udfff]|[\ud800-\udfff]/g, pair => pair.length === 2 ? pair : '') : text;
+export const characters = text => Array.from(text).length;
+export const textLongText = (t, limit) => t('The description is too long. Shorten it to %d characters or fewer.', '描述过长，请缩短到 %d 字以内。').replace('%d', limit);
 // The engine's limits on continuing parts, refused before a generation starts; the engine says the same.
 export const PARTS_LIMIT_CODES = ['chain_too_long', 'chain_part_too_short', 'chain_short_parts'];
 export function partsLimitText(code, t = en => en, limit = null) {
@@ -316,6 +320,10 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         }
         if (['audio_prepare', 'speed_pending', 'speed_locked', 'speed'].includes(code)) return {ok: false, reason: code};
         if (code === 'unsupported') { genbar?.update(null); return; }
+        if (code === 'text_long') {
+            const text = textLongText(t, Number.isInteger(value.limit) ? value.limit : 8000);
+            out(text); return {ok: false, reason: code, say: text};
+        }
         if (PARTS_LIMIT_CODES.includes(code)) {
             const [en, zh] = (value.said || []).map(text => typeof text === 'string' && text ? text.slice(0, 200) : null);
             const text = en && zh ? t(en, zh) : partsLimitText(code, t, Number.isInteger(value.limit) ? value.limit : null);
@@ -914,7 +922,10 @@ export function openEditor({api, app, from = null, panel = {}, components: given
         // texts: a description for each planned part, by the part's picture; otherwise text is every part's.
         async generate({target = 'both', text = '', texts = null, label = t('Generate', '生成'), selection = state.selection, shown = selection === state.selection} = {}) {
             if (target !== 'both' || !actions.supportedSelection(selection)) throw new model.EditError('unsupported');
+            // A half of a pair left by a cut or a paste is dropped; a description over the limit is said before anything is sent.
+            text = wellFormed(text);
             if (!actions.canGenerate(text, selection)) throw new model.EditError('text');
+            if (characters(text) > model.RULES.maxText) throw Object.assign(new model.EditError('text_long'), {limit: model.RULES.maxText});
             submissionFailure = null; genbar?.update(null);
             const chosen = state.selection;
             generationBusy = true; updateTop(); updateTransport();
@@ -1010,6 +1021,7 @@ export function openEditor({api, app, from = null, panel = {}, components: given
             }
             if (disposed || closing || epoch !== projectEpoch) return;
             if (!selectionRange(selection)) return {say: t('Drag on the timeline to choose a part first.', '先在时间线上拖出一段。')};
+            if (characters(wellFormed(text)) > model.RULES.maxText) return {say: textLongText(t, model.RULES.maxText), focus: true};
             if (actions.selectionHeld()) return {say: t('Queued', '排队中')};
             if (busySelection(selection)) return {say: t('This part is generating.', '这一段正在生成。')};
             const flush = flushSpot(selection);

From b21738cc032ecc6187aa255ba2541b9a4039c2fb Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 08:57:06 +0000
Subject: [PATCH 39/52] Show each GPU check's failure reason when the check
 before an int8 move fails

The failed-step message read the kernel report from a fixed file name, so a
failure of the GPU check that runs first when moving to int8 lost its
per-check reasons. The message now reads the report the command was told to
write, and falls back to the old file.
---
 freevideo_engine/bootstrap.py       | 3 ++-
 freevideo_engine/failure_details.py | 4 ++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/freevideo_engine/bootstrap.py b/freevideo_engine/bootstrap.py
index b3975267..e9d02978 100644
--- a/freevideo_engine/bootstrap.py
+++ b/freevideo_engine/bootstrap.py
@@ -1579,8 +1579,9 @@ def update_progress(*, final=False):
                             if self.ui.verbose or not success else 'Ready')
         if child.returncode:
             from .failure_details import setup_command_failure, environment_python_removed
+            report = args[args.index('--out') + 1] if '--out' in args[:-1] else None
             raise RuntimeError(environment_python_removed(args, getattr(self, 'pythons', {}).values())
-                               + setup_command_failure(label, log, child.returncode))
+                               + setup_command_failure(label, log, child.returncode, report=report))
         return log
 
     def component_tasks(self, uv):
diff --git a/freevideo_engine/failure_details.py b/freevideo_engine/failure_details.py
index 1a88a9c1..fec07b67 100644
--- a/freevideo_engine/failure_details.py
+++ b/freevideo_engine/failure_details.py
@@ -161,7 +161,7 @@ def display_launcher_error(value, *, zh=False, replacements=()):
     return text
 
 
-def setup_command_failure(label, log, exit_code):
+def setup_command_failure(label, log, exit_code, report=None):
     """Keep the complete failed step, with required GPU failures before metadata."""
     log = Path(log)
     try:
@@ -171,7 +171,7 @@ def setup_command_failure(label, log, exit_code):
     lines = ['Failed step: %s (exit code %s)' % (label, exit_code)]
     if label == 'kernels':
         try:
-            report = json.loads((log.parent / 'kernel-capabilities.json').read_text(encoding='utf-8'))
+            report = json.loads(Path(report or log.parent / 'kernel-capabilities.json').read_text(encoding='utf-8'))
         except (OSError, ValueError):
             report = {}
         if isinstance(report, dict):

From 72a46575520aa12301d41dae759891e35aa11910 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 18:23:58 +0000
Subject: [PATCH 40/52] Launcher: share the proxy hop secret with the ComfyUI
 it starts and the LAN access proxy

LAN requests from a phone reached ComfyUI with a hop header that the server
could not verify, so Agent endpoints answered 403 local_only.
---
 freevideo_engine/comfy_launcher_runtime.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/freevideo_engine/comfy_launcher_runtime.py b/freevideo_engine/comfy_launcher_runtime.py
index fd1b6740..f2006644 100644
--- a/freevideo_engine/comfy_launcher_runtime.py
+++ b/freevideo_engine/comfy_launcher_runtime.py
@@ -687,6 +687,8 @@ def __init__(self, source, *, child_environment=None):
         self.server_address = None
         self.access_proxy = None
         self.access_configuration = None
+        # Shared only by the ComfyUI this controller starts and the access proxy in front of it.
+        self.hop_secret = secrets.token_urlsafe(32)
         self.access_links = []
         self.access_polled = 0
         self._server_lock = threading.RLock()
@@ -1242,7 +1244,8 @@ def _start_access_proxy(self):
                 if self._closed or self.cancelled.is_set():
                     raise RuntimeError('LAN access startup cancelled')
                 self.access_proxy = start_proxy(selected, listen='0.0.0.0', port=port,
-                    upstream=loopback_url(selected['url']), token_file=folder(selected['engine']) / TOKEN, tls=None)
+                    upstream=loopback_url(selected['url']), token_file=folder(selected['engine']) / TOKEN, tls=None,
+                    hop_secret=self.hop_secret if self.owns_server() else None)
             try:
                 check_proxy(self.access_proxy, scheme='http', port=port, secret=secret)
                 if self._closed or self.cancelled.is_set():
@@ -1372,6 +1375,9 @@ def _connect_comfy(self):
         if not loopback_host(parsed.hostname):
             env = bypass_local(env, parsed.hostname)
         env['FREEVIDEO_COMFY_LOG'] = str(self.server_log)
+        from .proxy_identity import ENV as HOP
+        self.hop_secret = env.get(HOP) or self.hop_secret
+        env[HOP] = self.hop_secret
         from .launcher_bridge import ENV as BRIDGE
         env.pop(BRIDGE, None)
         if self.update_bridge:

From c377f92b151cc9d55e1fbedd84ad372a70596351 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 11:27:28 +0000
Subject: [PATCH 41/52] Agent MCP lists the common tools in full and reaches
 the large ones through tool help and call

Agent MCP lists the common tools in full and reaches the large ones through freevideo_tool_help and freevideo_call; freevideo_wait waits up to 45 seconds.
---
 freevideo_engine/agent/mcp.py    | 56 ++++++++++++++++++++++++++++----
 freevideo_engine/agent/schema.py |  2 +-
 2 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/freevideo_engine/agent/mcp.py b/freevideo_engine/agent/mcp.py
index ee5836aa..1b2ae34f 100644
--- a/freevideo_engine/agent/mcp.py
+++ b/freevideo_engine/agent/mcp.py
@@ -21,11 +21,12 @@
 
 from .client import ApiError, Client, DONE
 
+JOB_WAIT = 45.  # freevideo_wait only; the other waits keep 25 s. Fewer empty turns, each of which carries the whole context again.
 PROTOCOLS = ('2025-06-18', '2025-03-26', '2024-11-05')
 INSTRUCTIONS = """FreeVideo generates videos (MiniMax H3) on this computer's GPU.
-Start with freevideo_status and freevideo_capabilities. Write prompts as the guide says (freevideo_prompt_guide): English sections
+Start with freevideo_status and freevideo_capabilities. Picture editing, storyboards (submit_batch), editor operations and plan are not listed in full: freevideo_tool_help {name} gives the schema, freevideo_call runs them. Write prompts as the guide says (freevideo_prompt_guide): English sections
 integrated_multimodal_description / overall_soundscape / non_diegetic_music, [Shot N] cuts, (S1) <d>[Language] ...</d>
-dialogue. Generation uses continuous chains and takes minutes: submit, then call freevideo_wait (at most 25 seconds)
+dialogue. Generation uses continuous chains and takes minutes: submit, then call freevideo_wait (up to 45 seconds; it returns as soon as the job ends)
 or freevideo_job. Interrupted/failed/cancelled generation can continue with freevideo_resume; completed blocks stay.
 Chain shots by starting the next shot from the previous one's last frame (media.first = {"from_job": id,
 "frame": "last"}), look at results with freevideo_look, ask the local VLM with freevideo_ask, and join clips
@@ -53,7 +54,7 @@ def tool_list():
         dict(name='freevideo_generate_image', title='Generate a picture', description='Generate a picture from a prompt; with images, change or combine input pictures; with people, make a first frame with them near the places you say, in the scene from scene_image or the prompt. The result is an input file to use as a first frame, as a reference, or in images again.', annotations=write),
         dict(name='freevideo_submit_batch', title='Submit a storyboard', description='Submit several jobs at once. Each row is a job object with "kind" (generate default, assemble, vlm, enhance, image) and an optional "ref"; later rows use "@ref" wherever a job id is expected (from_job, after, clips, refine_from). FreeVideo runs them in dependency order.', annotations=write),
         dict(name='freevideo_job', title='Job status', description='Status, progress, result or error of a job.', annotations=read),
-        dict(name='freevideo_wait', title='Wait for a job or the user', description="Wait at most 25 seconds for a job (with id) or, without id, at most 50 seconds for what the user says in FreeVideo (inbox). again=true means nothing new yet: call it again. A job wait returns early when the user says something. If the job is still active, call it again with the same ID; do not resubmit.", annotations=read),
+        dict(name='freevideo_wait', title='Wait for a job or the user', description="Wait up to 45 seconds for a job (with id) or, without id, at most 50 seconds for what the user says in FreeVideo (inbox). again=true means nothing new yet: call it again. A job wait returns early when the user says something. If the job is still active, call it again with the same ID; do not resubmit.", annotations=read),
         dict(name='freevideo_jobs', title='List jobs', description='Recent agent jobs, optionally by status (comma-separated), project or kind.', annotations=read),
         dict(name='freevideo_cancel', title='Cancel a job', description='Cancel a waiting, queued or running job.', annotations={'readOnlyHint': False, 'destructiveHint': True, 'openWorldHint': False}),
         dict(name='freevideo_resume', title='Resume generation', description='Resume a failed, interrupted or cancelled generation; only unfinished blocks run. Poll the same job ID.', annotations=write),
@@ -95,6 +96,34 @@ def tool_list():
     return rows
 
 
+GATEWAY_TOOLS = ('freevideo_tool_help', 'freevideo_call')
+
+
+def hidden_tools():
+    """Tools whose full schemas stay out of tools/list: every client sends the whole list with every request,
+    and these are the largest and the least often used. They are described by name and listed in the help tool."""
+    from .schema import IMAGE_TOOLS
+    return frozenset(IMAGE_TOOLS.values()) | {'freevideo_submit_batch', 'freevideo_edit_image', 'freevideo_editor_operations', 'freevideo_plan'}
+
+
+def listed_tools(rows=None):
+    """What tools/list returns: the common tools in full, the rest through freevideo_tool_help and freevideo_call."""
+    rows = rows if rows is not None else tool_list()
+    hidden = hidden_tools()
+    brief = '; '.join('%s (%s)' % (r['name'], r['description'].split('. ')[0].rstrip('.')[:90]) for r in rows if r['name'] in hidden)
+    read = {'readOnlyHint': True, 'openWorldHint': False}
+    visible = [r for r in rows if r['name'] not in hidden]
+    visible.append(dict(name='freevideo_tool_help', title='Schema of a tool not listed', annotations=read,
+        description='Full description and input schema of one of the tools not listed here: ' + brief + '. Call it once before the first use, then call the tool through freevideo_call.',
+        inputSchema=dict(type='object', properties=dict(name=dict(type='string', enum=sorted(hidden))), required=['name'], additionalProperties=False)))
+    visible.append(dict(name='freevideo_call', title='Call a tool not listed',
+        annotations={'readOnlyHint': False, 'destructiveHint': False, 'openWorldHint': False},
+        description='Call one of the tools that freevideo_tool_help describes with its arguments; the result is the tool\'s own result.',
+        inputSchema=dict(type='object', properties=dict(tool=dict(type='string', enum=sorted(hidden)), arguments=dict(type='object')),
+                         required=['tool'], additionalProperties=False)))
+    return visible
+
+
 PROMPTS = [
     dict(name='short_drama', title='Make a short drama',
          description='Plan and produce a short drama: script, consistent characters, chained shots, review, assembly.',
@@ -116,7 +145,7 @@ def short_drama(arguments):
 4. Follow todo: freevideo_drama_sheet shows each take, then freevideo_drama_choose or freevideo_drama_reshoot
    with a concrete note. Continuations wait for the previous chosen take. Prefer aspect "{aspect}" and quality light.
 5. When every shot is chosen, freevideo_drama_finish accepts assembly; get until the output library_id is ready.
-Use ref to replay writes safely. Ordinary job batches remain available through freevideo_submit_batch."""
+Use ref to replay writes safely. Ordinary job batches go through freevideo_call with tool freevideo_submit_batch."""
 
 
 def preload():
@@ -218,7 +247,7 @@ def dispatch(self, identity, method, params):
             return {}
         if method == 'tools/list':
             if self.tools is None:
-                self.tools = tool_list()
+                self.tools = listed_tools()
             return dict(tools=self.tools)
         if method == 'tools/call':
             return self.call(identity, params.get('name'), params.get('arguments') or {},
@@ -245,6 +274,19 @@ def dispatch(self, identity, method, params):
     # Tools -----------------------------------------------------------------------------------------------
     def call(self, identity, name, arguments, progress_token):
         from . import schema, spec, errors
+        if name == 'freevideo_tool_help':
+            row = next((r for r in tool_list() if r['name'] == arguments.get('name') and r['name'] in hidden_tools()), None)
+            if row is None:
+                problem = errors.build('invalid_request', validation=True, details=[dict(field='name', allowed=sorted(hidden_tools()))])
+                return dict(content=[dict(type='text', text=errors.text(problem))], structuredContent={'error': problem}, isError=True)
+            return dict(content=[dict(type='text', text=json.dumps(row, ensure_ascii=False))], structuredContent=row, isError=False)
+        if name == 'freevideo_call':
+            target, inner = arguments.get('tool'), arguments.get('arguments') or {}
+            if target not in hidden_tools() or not isinstance(inner, dict):
+                problem = errors.build('invalid_request', validation=True, details=[dict(field='tool' if target not in hidden_tools() else 'arguments',
+                                       allowed=sorted(hidden_tools()) if target not in hidden_tools() else 'object')])
+                return dict(content=[dict(type='text', text=errors.text(problem))], structuredContent={'error': problem}, isError=True)
+            return self.call(identity, target, inner, progress_token)
         try:
             schema.validate(schema.tool_schema(name), arguments)
             arguments = dict(arguments)
@@ -357,7 +399,7 @@ def tool(self, identity, name, args, token):
         if name == 'freevideo_wait':
             if not args.get('id'):
                 return c.get('/inbox', wait=min(50., float(args.get('timeout', 50)))), []
-            return self.wait(identity, args['id'], min(25., float(args.get('timeout', 25))), token), []
+            return self.wait(identity, args['id'], min(JOB_WAIT, float(args.get('timeout', JOB_WAIT))), token), []
         if name == 'freevideo_jobs':
             return dict(jobs=c.jobs(**args)), []
         if name == 'freevideo_cancel':
@@ -380,7 +422,7 @@ def tool(self, identity, name, args, token):
         raise LookupError('Unknown tool: %s' % name)
 
     def wait(self, identity, job, timeout, token):
-        deadline = time.monotonic() + max(0., min(25., float(timeout)))
+        deadline = time.monotonic() + max(0., min(JOB_WAIT, float(timeout)))
         last = None
         while True:
             left = max(0., deadline - time.monotonic())
diff --git a/freevideo_engine/agent/schema.py b/freevideo_engine/agent/schema.py
index a3ea6e8d..066a752c 100644
--- a/freevideo_engine/agent/schema.py
+++ b/freevideo_engine/agent/schema.py
@@ -1648,7 +1648,7 @@ def _tool_schema(name):
             value['required'].append('shot')
         if name == 'freevideo_wait':
             value['properties'].pop('wait')
-            value['properties']['timeout'] = number(0, 50, default=25, description='With id at most 25 seconds; without id (the user) up to 50, default 50.')
+            value['properties']['timeout'] = number(0, 50, default=45, description='With id up to 45 seconds; without id (the user) up to 50, default 50.')
             value['required'] = [k for k in value['required'] if k != 'id']
         return value
     if name == 'freevideo_asset':

From 3e298d402b5251be7d0d523251b1bb158cf93e0a Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 19:50:33 +0000
Subject: [PATCH 42/52] Register the entry module before loading it in the
 installation check

---
 scripts/check_installation.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/check_installation.py b/scripts/check_installation.py
index c0e7867e..72697c0a 100644
--- a/scripts/check_installation.py
+++ b/scripts/check_installation.py
@@ -24,6 +24,7 @@ def main():
     spec = importlib.util.spec_from_file_location('freevideo_install_check', ROOT / '__init__.py',
                                                 submodule_search_locations=[str(ROOT)])
     entry = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = entry
     spec.loader.exec_module(entry)
     assert callable(entry.comfy_entrypoint)
     assert (ROOT / entry.WEB_DIRECTORY).is_dir()

From d992a0d675ef990376a3b181b133df017ace4376 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 03:17:37 +0000
Subject: [PATCH 43/52] Creation panel: reuse an earlier video's prompt and
 settings

Picking an earlier video in Recent videos now offers a Reuse settings
button in its action row. It fills the video's prompt, picture size and
duration back into the creation panel; seed, quality, second pass and
media stay as they are.

- A new read-only library route returns the prompt saved in the video's
  folder; the button appears only when a prompt was kept and differs from
  what the panel holds.
- When the panel held something different, the button turns into
  "Filled in - Undo" for 10 seconds and Undo restores the previous prompt,
  size and duration; editing any of them first withdraws it.
---
 freevideo_engine/comfy_library.py | 27 +++++++++++++++
 web/health.js                     |  2 +-
 web/result_actions.css            |  7 ++++
 web/result_actions.js             | 56 ++++++++++++++++++++++++++++++-
 web/result_reuse.js               | 28 ++++++++++++++++
 web/studio.js                     | 38 ++++++++++++++++++++-
 6 files changed, 155 insertions(+), 3 deletions(-)
 create mode 100644 web/result_reuse.js

diff --git a/freevideo_engine/comfy_library.py b/freevideo_engine/comfy_library.py
index 3f2ece89..f8469bf7 100644
--- a/freevideo_engine/comfy_library.py
+++ b/freevideo_engine/comfy_library.py
@@ -19,6 +19,8 @@
 from .system import windows
 
 _ID = re.compile(r'\d{4}-\d{2}-\d{2}/[0-9a-f]{32}')
+# The prompt box takes 20000 characters; a character is at most 4 bytes.
+_PROMPT_BYTES = 4 * 20000
 
 
 def _video(root, identity):
@@ -142,6 +144,23 @@ def list_videos(output_directory, *, before=None, limit=24):
     return dict(items=rows, next=next_cursor, unreadable=sum(last is None or key > last for key in unreadable))
 
 
+def prompt_text(output_directory, identity):
+    """The text a saved video was made from, or None for a run that kept none."""
+    path = _video(output_directory, identity)
+    root = Path(output_directory).resolve() / 'FreeVideo'
+    saved = path.with_name('prompt.txt')
+    if saved.is_symlink() or not saved.resolve().is_relative_to(root):
+        raise ValueError('Saved prompt is outside the library or is a symbolic link')
+    _report(path)
+    try:
+        with os.fdopen(os.open(saved, os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_BINARY', 0)), 'rb') as stream:
+            data = stream.read(_PROMPT_BYTES + 1)
+    except FileNotFoundError:
+        return None
+    # Longer than the prompt box takes: its beginning alone is not the prompt.
+    return data.decode('utf-8').strip() if len(data) <= _PROMPT_BYTES else None
+
+
 def thumbnail(output_directory, identity):
     path = _video(output_directory, identity)
     saved = path.with_suffix('.thumbnail.jpg')
@@ -1162,6 +1181,14 @@ async def library(request):
         except ValueError as error:
             raise web.HTTPBadRequest(text=str(error)) from error
 
+    @server.routes.get('/freevideo/library/prompt')
+    async def prompt(request):
+        try:
+            text = await asyncio.to_thread(prompt_text, folder_paths.get_output_directory(), request.query.get('id'))
+        except (OSError, ValueError, UnicodeDecodeError):
+            raise web.HTTPNotFound(text='Prompt unavailable') from None
+        return web.json_response(dict(prompt=text), headers={'Cache-Control': 'no-store'})
+
     @server.routes.get('/freevideo/library/thumbnail')
     async def preview(request):
         async with thumbnails:
diff --git a/web/health.js b/web/health.js
index 468ad2f8..577ed0b3 100644
--- a/web/health.js
+++ b/web/health.js
@@ -17,7 +17,7 @@ export const MODULES = ['chat_data.js', 'phone_model.js', 'phone.js', 'lan_acces
     'editor.js', 'editor_actions.js', 'editor_lifecycle.js', 'editor_adjust.js', 'editor_adjust_picture.js', 'editor_picture_fields.js', 'editor_picture_session.js', 'editor_preview_picture.js', 'editor_entry.js', 'editor_expand.js', 'editor_export_dialog.js', 'editor_first_frame.js', 'editor_media_references.js', 'editor_references.js', 'editor_genbar.js', 'editor_geometry.js', 'editor_library.js', 'editor_menu.js', 'editor_model.js', 'editor_frame.js', 'editor_player.js', 'editor_room.js', 'editor_select.js', 'editor_state.js', 'editor_store.js', 'editor_tracks.js', 'editor_generation.js', 'editor_transport.js', 'editor_transport_model.js', 'editor_audio.js', 'editor_audio_model.js', 'editor_audio_notes.js', 'editor_audio_replace.js', 'editor_audio_rules.js', 'editor_speed.js', 'editor_speed_model.js', 'editor_failure.js', 'editor_header_fit.js',
     'editor_loader.js', 'editor_text_coverage.js', 'editor_text.js', 'editor_toolbar_more.js', 'editor_text_model.js', 'editor_text_layout.js', 'editor_notes.js', 'editor_icons.js', 'dialog_keys.js', 'done_notify.js', 'failure_issue.js', 'feedback.js', 'frame_sizes.js', 'health.js', 'image_commands.js', 'image_editor.js', 'image_editor_engine.js', 'image_generation.js', 'launch_visit.js', 'launcher.js', 'length_plan.js', 'lora_triggers.js', 'lora_check.js', 'library.js', 'motion.js', 'native_errors.js', 'translate_guard.js', 'output_download.js', 'port_notice.js', 'preview_scene.js',
     'progress_connection.js', 'prompt_draft.js', 'prompt_enhance.js', 'prompt_references.js', 'prompt_terms.js', 'request_assets.js', 'repair_hint.js', 'report_issue.js', 'issue_button.js', 'studio_recent.js',
-    'result_actions.js', 'sampling_effort.js', 'setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'studio_queue.js', 'studio_size.js',
+    'result_actions.js', 'result_reuse.js', 'sampling_effort.js', 'setup.js', 'share.js', 'share_layout.js', 'studio.js', 'studio_chain.js', 'studio_extend.js', 'studio_length.js', 'first_frame_row.js', 'replace_person.js', 'replace_state.js', 'optional_inputs.js', 'studio_queue.js', 'studio_size.js',
     'toolbar_position.js', 'updates.js', 'view_navigation.js', 'wordmark.js', 'workspace_restore.js', 'cast_library.js', 'media_upload.js', 'whitebox_encode.js', 'whitebox_mp4.js', 'whitebox_recording.js', 'whitebox_render.js', 'whitebox_scenes.js', 'whitebox_worker.js'];
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 let visibleAt = 0;
diff --git a/web/result_actions.css b/web/result_actions.css
index b3b1b2da..584bef8a 100644
--- a/web/result_actions.css
+++ b/web/result_actions.css
@@ -66,3 +66,10 @@
 .fv-actions[data-unavailable=true] :is(a.fv-action[download],.fv-action-extend,.fv-share-trigger){opacity:.45;cursor:default;pointer-events:none}
 .fv-action-copy .fv-copy-text{display:inline-grid;justify-items:start}
 .fv-action-copy .fv-copy-text::after{content:attr(data-widest);grid-area:1/1;visibility:hidden;height:0;overflow:hidden}
+.fv-action-reuse .fv-reuse-text{display:inline-grid;justify-items:start;white-space:nowrap}
+.fv-action-reuse .fv-reuse-text::after{content:attr(data-widest);grid-area:1/1;visibility:hidden;height:0;overflow:hidden}
+.fv-action-reuse .fv-reuse-text>*{grid-area:1/1}
+.fv-reuse-done{cursor:default}
+.fv-action-reuse .fv-reuse-undo{all:unset;cursor:pointer;color:var(--fv-accent,#6db8fa);text-decoration:underline;text-underline-offset:2px}
+.fv-action-reuse .fv-reuse-undo:focus-visible{outline:2px solid var(--fv-accent,#6db8fa);outline-offset:2px;border-radius:3px}
+.fv-action-reuse[hidden]{display:none}
diff --git a/web/result_actions.js b/web/result_actions.js
index 75befcd9..91973575 100644
--- a/web/result_actions.js
+++ b/web/result_actions.js
@@ -3,6 +3,7 @@ import { outputDownloadURL } from './output_download.js';
 import { shareButton } from './share.js';
 import { canExtend, extendText, extendSourceProblem, extendSourceState } from './studio_extend.js';
 import { issueButton } from './issue_button.js';
+import { savedSettings, differs } from './result_reuse.js';
 
 const css = document.createElement('link');
 css.rel = 'stylesheet'; css.href = new URL('./result_actions.css', import.meta.url).href; document.head.append(css);
@@ -140,12 +141,64 @@ export async function copyText(text) {
     try { return document.execCommand('copy'); } catch { return false; } finally { area.remove(); }
 }
 
+// Fills the prompt, size and duration of an earlier video back into the panel. It is offered only when
+// the video kept its prompt and the panel does not already hold the same settings. Resolves to the button or null.
+// `reuse`: {now(saved), apply(saved), onEdit(listener) -> stop}
+async function reuseAction(record, t, reuse) {
+    const saved = await savedSettings(api, record);
+    if (!saved) return null;
+    const label = t('Reuse settings', '复用设置'), filled = t('Filled in', '已填入'), undoLabel = t('Undo', '撤销');
+    const widest = [label, `${filled} · ${undoLabel}`, filled].sort((a, b) => b.length - a.length)[0];
+    // The label sits over an invisible copy of the longest state, so the bar does not shift when it changes.
+    const make = (...parts) => {
+        const text = document.createElement('span'); text.className = 'fv-reuse-text'; text.dataset.widest = widest;
+        const inner = document.createElement('span'); inner.append(...parts); text.append(inner);
+        return text;
+    };
+    let timer = 0, stop = () => {}, current = null;
+    const offered = () => differs(saved, reuse.now(saved));
+    const idle = () => {
+        clearTimeout(timer); stop();
+        const button = action('button', '', 'back', 'fv-action-secondary fv-action-reuse');
+        button.lastElementChild.replaceWith(make(label));
+        button.hidden = !offered();
+        button.onclick = () => {
+            const before = reuse.now(saved), hadContent = Boolean(before.text.trim()) && differs(saved, before);
+            reuse.apply(saved); show(hadContent ? before : null);
+        };
+        stop = reuse.onEdit(() => {
+            if (!button.isConnected) { stop(); return; }
+            button.hidden = !offered();
+        });
+        swap(button);
+    };
+    // A later state takes the place of the button in the bar.
+    const swap = next => { if (current?.parentNode) current.replaceWith(next); current = next; };
+    const show = before => {
+        clearTimeout(timer); stop();
+        const chip = document.createElement('span'); chip.className = 'fv-action fv-action-secondary fv-action-reuse fv-reuse-done';
+        chip.setAttribute('role', 'status');
+        chip.append(icon('back'));
+        const parts = [before ? `${filled} · ` : filled];
+        if (before) {
+            const undo = document.createElement('button'); undo.type = 'button'; undo.className = 'fv-reuse-undo'; undo.textContent = undoLabel;
+            undo.onclick = () => { reuse.apply(before); idle(); };
+            parts.push(undo);
+        }
+        chip.append(make(...parts)); swap(chip);
+        timer = setTimeout(idle, before ? 10000 : 1800);
+        if (before) stop = reuse.onEdit(() => { if (!chip.isConnected) stop(); else idle(); });
+    };
+    idle();
+    return current;
+}
+
 // Download the video first; share and the report follow. A first-pass preview
 // leads with `secondPass` instead, and saved creations end with `remove`.
 // `diagnostic` downloads the redacted report (and may offer to send it); a
 // result without one shows no report entry, because the full generation
 // record keeps local paths and is not meant to be shared.
-export function resultActions(record, t, {diagnostic = null, secondPass = null, remove = null, extend = null} = {}) {
+export function resultActions(record, t, {diagnostic = null, secondPass = null, remove = null, extend = null, reuse = null} = {}) {
     const bar = document.createElement('div'); bar.className = 'fv-actions';
     if (secondPass) bar.append(secondPassAction(t, secondPass));
     if (record.video) {
@@ -163,6 +216,7 @@ export function resultActions(record, t, {diagnostic = null, secondPass = null,
             timer = setTimeout(() => { text.textContent = t('Copy path', '复制路径'); }, 1800);
         };
         bar.append(copy);
+        if (reuse) reuseAction(record, t, reuse).then(button => { if (button && bar.isConnected) copy.after(button); });
     }
     if (extend && canExtend(record)) {
         const button = action('button', extendText(t, 'action'), 'extend', 'fv-action-secondary fv-action-extend');
diff --git a/web/result_reuse.js b/web/result_reuse.js
new file mode 100644
index 00000000..7963b217
--- /dev/null
+++ b/web/result_reuse.js
@@ -0,0 +1,28 @@
+// The prompt, size and duration an earlier video was made from, to fill back into the creation panel.
+const IDENTITY = /^FreeVideo\/(\d{4}-\d{2}-\d{2}\/[0-9a-f]{32})\/video\.mp4$/;
+
+// Frames a duration in seconds becomes (the model takes 17k + 5).
+export function framesOf(seconds) {
+    const requested = Math.ceil(Number(seconds) * 24);
+    return requested + ((5 - requested) % 17 + 17) % 17;
+}
+
+// Null when the video kept no prompt, or is not a saved creation.
+export async function savedSettings(api, record) {
+    const id = IDENTITY.exec(record?.video || '')?.[1], g = record.geometry;
+    if (!id || !(g?.width > 0) || !(g?.height > 0)) return null;
+    try {
+        const reply = await api.fetchApi('/freevideo/library/prompt?' + new URLSearchParams({id}), {cache: 'no-store'});
+        if (!reply.ok) return null;
+        const {prompt} = await reply.json();
+        if (typeof prompt !== 'string' || !prompt) return null;
+        const frames = Number(g.frames) > 0 ? Number(g.frames) : framesOf(g.seconds);
+        return {text: prompt, width: Number(g.width), height: Number(g.height), frames: Number.isFinite(frames) ? frames : null};
+    } catch { return null; }
+}
+
+// Whether filling the saved settings would change anything the panel can still change.
+export function differs(saved, now) {
+    return saved.text !== now.text || saved.width !== now.width || saved.height !== now.height
+        || (saved.frames !== null && saved.frames !== now.frames);
+}
diff --git a/web/studio.js b/web/studio.js
index 1dc5609c..a8e7442b 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -31,6 +31,7 @@ import { reconcileLoraTriggers } from './lora_triggers.js';
 import { createVerdicts, describeVerdict, feedbackDraft } from './lora_check.js';
 import { continuationUpscale, createSamplingEffort, effortFor, effortsFrom, passSwitch, stepCacheOf, upscaleOf } from './sampling_effort.js';
 import { resultActions, previewBadge, icon, actionsUnavailable } from './result_actions.js';
+import { framesOf } from './result_reuse.js';
 import { createPromptEnhancer } from './prompt_enhance.js';
 import { createRequestAssets, enabledLoras, referenceFiles } from './request_assets.js';
 import { promptDraftTrouble, rememberPromptDraft, restorePromptDraft, savePromptDraft, trackPromptDraft, watchPromptDraftTrouble } from './prompt_draft.js';
@@ -1371,6 +1372,41 @@ export function openStudio(node, {extendFrom = null} = {}) {
     cleanup.push(() => recent.dispose());
     // A run this window watched. Its result can arrive before or after the
     // final progress message, and more than once; the tip stays with that video.
+    // "Reuse settings" in the result bar: what the panel holds now, filling an earlier video's settings back,
+    // and the edits that withdraw the offer. A field the panel cannot change counts as already matching.
+    let reuseApplying = false;
+    function setSize(w, h) {
+        set(node, 'width', w); set(node, 'height', h);
+        ratio = w / h; pixels = w * h / 1024 ** 2;
+        selected = [['16:9', 16 / 9], ['9:16', 9 / 16], ['1:1', 1]].find(([, r]) => Math.abs(Math.log(ratio / r)) < .035)?.[0] || 'custom';
+        node.properties.freevideo_aspect = selected; node.properties.freevideo_pixels = pixels;
+        if (![...mp.options].some(option => Number(option.value) === pixels)) { const option = el('option', `${pixels.toFixed(2)} MP`); option.value = pixels; mp.append(option); }
+        mp.value = String(pixels); syncCanvasSize();
+    }
+    const reuse = {
+        now: saved => {
+            const sizeLocked = dimensionsLinked || Boolean(extension.source), lengthLocked = linked(node, 'seconds') || Boolean(extension.source);
+            return {text: prompt.disabled ? saved.text : prompt.value, width: sizeLocked ? saved.width : Number(value(node, 'width')),
+                height: sizeLocked ? saved.height : Number(value(node, 'height')),
+                frames: lengthLocked ? saved.frames : framesOf(seconds.value), seconds: Number(seconds.value)};
+        },
+        apply: saved => {
+            reuseApplying = true;
+            try {
+                if (!prompt.disabled) { set(node, 'text', saved.text); window.dispatchEvent(new CustomEvent('freevideo-reference-prompt', {detail: node.id})); }
+                if (!dimensionsLinked && !extension.source) setSize(saved.width, saved.height);
+                if (!linked(node, 'seconds') && !extension.source) {
+                    seconds.value = String(saved.seconds ?? Math.floor(saved.frames / 24 * 1000) / 1000);
+                    seconds.dispatchEvent(new Event('input')); seconds.dispatchEvent(new Event('change'));
+                }
+            } finally { reuseApplying = false; }
+        },
+        onEdit: listener => {
+            const heard = () => { if (!reuseApplying) listener(); };
+            controls.addEventListener('input', heard, true); controls.addEventListener('change', heard, true);
+            return () => { controls.removeEventListener('input', heard, true); controls.removeEventListener('change', heard, true); };
+        },
+    };
     let reportTipTimer = null, watchedRun = false, reportTipFor = null, shownReport = null;
     // chosen: a video picked from Recent videos. It only changes the picture; a run in progress keeps its progress.
     function showResult(r, {chosen = false} = {}) {
@@ -1429,7 +1465,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
         links.replaceChildren(resultActions(r, t, {diagnostic: reported ? downloadReport : null,
                                                    extend: saved => openExtendEditor(saved, node, {studio: dialog,
                                                        isCurrent: () => dialog.open && dialog.dataset.closing !== 'true' && topDialog() === dialog && result === r}),
-                                                   secondPass: r.preview ? secondPass(r) : null}));
+                                                   secondPass: r.preview ? secondPass(r) : null, reuse: r.preview ? null : reuse}));
         if (runButtonReady) updateExtendButton();
         // After a video finished just now, point at the report menu until the
         // user closes the tip once, whichever version they first saw it in.

From 5ea9fdc4423c063e896e5ff64244a3efc2790cd9 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 03:24:19 +0000
Subject: [PATCH 44/52] Normalise saved frames before comparing in reuse
 settings

---
 web/result_reuse.js | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/web/result_reuse.js b/web/result_reuse.js
index 7963b217..d255802b 100644
--- a/web/result_reuse.js
+++ b/web/result_reuse.js
@@ -16,8 +16,10 @@ export async function savedSettings(api, record) {
         if (!reply.ok) return null;
         const {prompt} = await reply.json();
         if (typeof prompt !== 'string' || !prompt) return null;
-        const frames = Number(g.frames) > 0 ? Number(g.frames) : framesOf(g.seconds);
-        return {text: prompt, width: Number(g.width), height: Number(g.height), frames: Number.isFinite(frames) ? frames : null};
+        // The panel keeps seconds to three decimals, so the frames it will ask for are those of that rounded duration.
+        const raw = Number(g.frames) > 0 ? Number(g.frames) / 24 : Number(g.seconds);
+        const seconds = raw > 0 ? Math.floor(raw * 1000) / 1000 : null;
+        return {text: prompt, width: Number(g.width), height: Number(g.height), seconds, frames: seconds === null ? null : framesOf(seconds)};
     } catch { return null; }
 }
 

From d6251e02b62fad4a160fd6bd223475771b096a4b Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 03:26:53 +0000
Subject: [PATCH 45/52] Skip the duration fill when the saved video has no
 duration

---
 web/studio.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/web/studio.js b/web/studio.js
index a8e7442b..047afe8b 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -1395,8 +1395,8 @@ export function openStudio(node, {extendFrom = null} = {}) {
             try {
                 if (!prompt.disabled) { set(node, 'text', saved.text); window.dispatchEvent(new CustomEvent('freevideo-reference-prompt', {detail: node.id})); }
                 if (!dimensionsLinked && !extension.source) setSize(saved.width, saved.height);
-                if (!linked(node, 'seconds') && !extension.source) {
-                    seconds.value = String(saved.seconds ?? Math.floor(saved.frames / 24 * 1000) / 1000);
+                if (saved.seconds !== null && !linked(node, 'seconds') && !extension.source) {
+                    seconds.value = String(saved.seconds);
                     seconds.dispatchEvent(new Event('input')); seconds.dispatchEvent(new Event('change'));
                 }
             } finally { reuseApplying = false; }

From 1989604139c1bccd4363f8831a7d3bc7f83c3458 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 04:37:06 +0000
Subject: [PATCH 46/52] Split long-video descriptions without replaying the
 story in every part

The shared description now holds only what stays the same in every part:
people, place, lighting, framing, style and background sound. An answer
that copies the story or the spoken lines into it, leaves the first part
empty, or answers in another language is asked again instead of being
repeated in every part. An opening action left only in the shared text
moves to the first part, a part that repeats an earlier one carries on
quietly, and a short story continues with something new without adding
speech.

Without the prompt model, or when no usable split comes back, the
description's sentences go to the parts in order instead of every part
using the whole description. A part with no sentence of its own carries
on without speech. Resuming after a busy or out-of-memory split still
splits again.

Splitting stops as soon as the model starts its answer over, instead of
writing until the token limit and asking again.
---
 freevideo_engine/chain_runner.py      |  37 +++++-
 freevideo_engine/chain_store.py       |  12 +-
 freevideo_engine/prompt_vlm/rules.py  | 163 ++++++++++++++++++++++----
 freevideo_engine/prompt_vlm/worker.py |  25 ++--
 web/generation_progress.js            |   6 +-
 5 files changed, 200 insertions(+), 43 deletions(-)

diff --git a/freevideo_engine/chain_runner.py b/freevideo_engine/chain_runner.py
index ad3ce625..d4928750 100644
--- a/freevideo_engine/chain_runner.py
+++ b/freevideo_engine/chain_runner.py
@@ -13,6 +13,28 @@
 from . import chain_store as store
 
 
+def _split_value(record, text):
+    """What the prompt model sorts into parts: the whole description and each part's new seconds."""
+    first = next(row for row in record['blocks'] if row['index'] == 0)
+    return dict(text=text, continued=first['after'] is not None,
+                seconds=[row['new_frames'] / chain_plan.FPS for row in record['blocks']])
+
+
+def _ordered_texts(record, value):
+    """Part texts when the description could not be split: its sentences in order, with the LoRA trigger
+    words every part carries, or None for a description without sentences."""
+    from .lora_triggers import apply_chain_triggers
+    from .prompt_vlm.rules import order_split
+    if not isinstance(value['text'], str):
+        return None
+    try:
+        probe = dict(snapshot=deepcopy(record['snapshot']), node=record['node'],
+                     blocks=[dict(inputs=dict(text=text)) for text in order_split(value)])
+        apply_chain_triggers(probe)
+    except Exception:
+        return None
+    return [row['inputs']['text'] for row in probe['blocks']]
+
 class ChainBusy(ValueError):
     pass
 
@@ -373,10 +395,14 @@ def resume(self, chain_id, client_id=None):
                                  fraction=0., remaining_seconds=None, continuation=None,
                                  skip_frames=0, skip_audio_samples=0)
             split = record.get('split')
+            whole = record['snapshot']['prompt'][record['node']]['inputs'].get('text')
             if (split is not None and split['state'] == 'failed' and split['reason'] in ('busy', 'memory')
                     and all(row['state'] != 'done' for row in record['blocks'])
-                    and len({row['inputs']['text'] for row in record['blocks']}) == 1):
+                    and [row['inputs']['text'] for row in record['blocks']] in (
+                        [whole] * len(record['blocks']), _ordered_texts(record, _split_value(record, whole)))):
                 # Busy and memory pass; nothing has started and no part was rewritten, so split again.
+                for row in record['blocks']:
+                    row['inputs']['text'] = whole
                 split.update(state='pending', reason=None)
             if client_id is not None:
                 record['client_id'] = client_id
@@ -722,8 +748,7 @@ def _step_chain(self, identity):
                 split['state'] = 'running'
                 record['state'] = 'running'
                 self._save(record)
-                value = dict(text=block['inputs']['text'], continued=block['after'] is not None,
-                             seconds=[row['new_frames'] / chain_plan.FPS for row in record['blocks']])
+                value = _split_value(record, block['inputs']['text'])
                 action = 'split'
             elif prompt_id is None:
                 self.progress_messages.pop(identity, None)
@@ -851,9 +876,13 @@ def cancelled():
                         row['inputs']['text'] = value['text']
                     record['split'].update(state='failed', reason='failed')
             else:
-                # The whole description goes to every part, as before; the page says why.
+                # Without the prompt model the sentences go to the parts in order, so no part plays the whole
+                # story again; the page says why. A description without sentences goes to every part.
                 if parts is not None:
                     reason = 'unusable'
+                texts = _ordered_texts(record, value)
+                for row, text in zip(record['blocks'], texts or [value['text']] * len(record['blocks'])):
+                    row['inputs']['text'] = text
                 record['split'].update(state='failed', reason=reason if reason in store.SPLIT_REASONS else 'failed')
             self._save(record)
 
diff --git a/freevideo_engine/chain_store.py b/freevideo_engine/chain_store.py
index 7dd23902..cd4bb63f 100644
--- a/freevideo_engine/chain_store.py
+++ b/freevideo_engine/chain_store.py
@@ -19,12 +19,12 @@
 # pending: split before the first part; given: the request gave one text per part; none: nothing to split.
 SPLIT_STATES = ('pending', 'running', 'done', 'failed', 'given', 'none')
 SPLIT_REASONS = {
-    'model_missing': 'The prompt model is not installed, so every part used the whole description.',
-    'busy': 'The prompt model was busy, so every part used the whole description.',
-    'memory': 'There was not enough memory to split the description, so every part used the whole description.',
-    'unusable': 'The description could not be split into parts, so every part used the whole description.',
-    'unavailable': 'Splitting is not available here, so every part used the whole description.',
-    'failed': 'Splitting the description failed, so every part used the whole description.',
+    'model_missing': 'The prompt model is not installed, so the parts took the sentences of the description in order.',
+    'busy': 'The prompt model was busy, so the parts took the sentences of the description in order.',
+    'memory': 'There was not enough memory to split the description, so the parts took the sentences of the description in order.',
+    'unusable': 'The description could not be split into parts, so the parts took the sentences of the description in order.',
+    'unavailable': 'Splitting is not available here, so the parts took the sentences of the description in order.',
+    'failed': 'Splitting the description failed, so the parts took the sentences of the description in order.',
 }
 # Parts one video may be continued through: the first part and seven continuations (fewer with a short part).
 MAX_PARTS = chain_plan.MAX_PARTS
diff --git a/freevideo_engine/prompt_vlm/rules.py b/freevideo_engine/prompt_vlm/rules.py
index 1f36d939..20b65791 100644
--- a/freevideo_engine/prompt_vlm/rules.py
+++ b/freevideo_engine/prompt_vlm/rules.py
@@ -547,12 +547,15 @@ def split_instruction(value):
     return f"""A long video is made of {count} parts generated one after another; each part continues where the
 previous one ended. Sort the user's description into what stays the same and what happens in each part:
 {chr(10).join(rows)}
-Shared: who is in the scene and how they look, the place, the lighting, the camera, the style and the
-background sound. Copy these words from the description. Leave out every action, event, change, every [L]
-marker and all talking: how someone speaks belongs next to their marker.
+Shared: only what stays the same in every part: who is in the scene and how they look, the place, the
+lighting, the camera framing, the style and the background sound. Copy these words from the description.
+Leave out every action, movement, event and change, camera moves, anything that only appears later, every
+[L] marker and all talking: how someone speaks belongs next to their marker. Shared never retells the story.
 Part N: only what happens during that part, in the order of the description, so each action happens
 once. Part 1 {opening}; each later part picks up where the previous part ended. When the story is
-shorter than the video, the later parts go on with small, calm, silent actions instead of repeating it.
+shorter than the video, the later parts carry it on with a simple new development that follows from it,
+such as a next small action or a new view of the scene; they never repeat an earlier action and add no
+speech. Every part has something of its own.
 The markers [L1], [L2], ... stand for spoken lines; their speaking time is given. Put each marker in
 exactly one part, in order, where it is said, as "he says [L2]" or "她说 [L2]"; spread them so each
 part's speech fits its seconds. Do not write any other speech: nobody talks, keeps talking or goes
@@ -625,26 +628,97 @@ def spoken(line, words):
     return ('说：' if language(words) in ('Chinese', 'Japanese') else 'says: ') + line
 
 
+def clauses(text):
+    """Sentences, and the comma-separated pieces inside them, in order. A period before a digit (00:04.000)
+    or a letter does not end one."""
+    pieces = re.findall(r'.+?(?:[。！？!?；;，,]+[”"’』」)]*|\.(?![\w])[”"’』」)]*|$)', text, re.S)
+    return [piece.strip() for piece in pieces if piece.strip()]
+
+
+def sentences(body):
+    """Sentences in order; a spoken line [L1] ends one. A period before a digit or a letter does not."""
+    return [piece.strip() for piece in re.findall(
+        r'.+?(?:\[L\d+\][。！？!?.，,]*|[。！？!?]+[”"’』」)]*|\.(?![\w])[”"’』」)]*|$)', ' '.join(body.split()), re.S)
+        if piece.strip()]
+
+
+def wide(words):
+    """Mostly Chinese, Japanese or Korean letters."""
+    letters = re.findall(r'[^\W\d_]', words)
+    return sum(bool(re.match('[\u3040-\u30ff\u4e00-\u9fff\uac00-\ud7af]', c)) for c in letters) * 2 > len(letters)
+
+
+def action(words):
+    """Long enough to be an action rather than a name: six Chinese or Japanese characters, or twelve letters."""
+    return len(words) >= (6 if re.search('[\u3040-\u30ff\u4e00-\u9fff\uac00-\ud7af]', words) else 12)
+
+
+def quiet(body):
+    return '画面继续，没有人说话。' if language(body) == 'Chinese' else 'The scene goes on and nobody speaks.'
+
+
 def validate_split(text, value, *, strict=False):
     """Part texts built from the model's sorting; every spoken line kept once, in order.
 
-    A part with nothing new carries on from the previous one; a misplaced line is placed by speaking time.
-    Only an answer without the expected layout or a usable shared description fails; strict also
-    fails when the model did not place every line once and in order, so it can be asked again.
+    Shared is what every part repeats, so an action in it is played again in every part: words of Shared
+    that also stand in a part, or in the description after its opening sentence, are story and are left
+    out, and a Shared that holds a spoken line or a whole part is the story itself and fails, as does an
+    answer in another language than the description. Strict also fails on such words, on a part with
+    nothing of its own and on lines not placed once and in order, so the model can be asked again;
+    otherwise a misplaced line is placed by speaking time and an empty later part carries on quietly.
     """
     body, sound, lines = part_source(value['text'])
     shared, events = split_answer(text, len(value['seconds']))
-    shared = ' '.join(re.sub(r'\[L\d+\]', '', shared).split())
+    if re.search(r'\[L\d+\]', shared) or wide(body) != wide(shared + ' '.join(events)):
+        raise ValueError('invalid_output')
+    used = set()
+    def once(match):
+        # A marker written twice stays where it first stands.
+        if match.group(0) in used:
+            return ''
+        used.add(match.group(0))
+        return match.group(0)
+    events = [' '.join(re.sub(r'\[L\d+\]', once, event).split()) for event in events]
+    keys = [plain(re.sub(r'\[L\d+\]', '', event)) for event in events]
+    if any(len(event) > 4000 for event in events) or any(key and (key in plain(shared) or key == plain(body))
+                                                         for key in keys):
+        raise ValueError('invalid_output')
+    # Clauses after the opening sentence, each with whether it stands in the first half of the description.
+    told_at, story = 0, []
+    for index, sentence in enumerate(sentences(body)):
+        for piece in clauses(sentence):
+            words = plain(re.sub(r'\[L\d+\]', '', piece))
+            if index and action(words):
+                story.append((words, told_at < len(body) / 2))
+            told_at += len(piece)
     if not 20 <= len(shared) <= 4000:
         raise ValueError('invalid_output')
-    seen, cleaned = {plain(shared), plain(body)}, []
-    for event in events:
-        key = plain(re.sub(r'\[L\d+\]', '', event))
-        if len(event) > 4000 or not key or key in seen or key in plain(shared):
+    def placed_twice(piece):
+        return action(plain(piece)) and any(plain(piece) in key for key in keys)
+    def told(piece):
+        return next((early for words, early in story if action(plain(piece))
+                     and (plain(piece) in words or words in plain(piece))), None)
+    if strict and any(placed_twice(piece) for piece in clauses(shared)):
+        raise ValueError('invalid_output')
+    join = '' if wide(shared) else ' '
+    kept = [piece for piece in clauses(shared) if not placed_twice(piece) and told(piece) is None]
+    # Story the model left in Shared alone: its first half opens the video, the rest is not repeated.
+    opening = [piece for piece in clauses(shared) if not placed_twice(piece) and told(piece)]
+    shared = ' '.join(join.join(kept).split()).rstrip(',，;；')
+    if opening:
+        lead = ' '.join(join.join(opening).split()).rstrip(',，;；。.') + ('。' if join == '' else '.')
+        events[0] = join.join([lead[:1].upper() + lead[1:], events[0]]).strip()
+        keys[0] = plain(re.sub(r'\[L\d+\]', '', events[0]))
+    seen, cleaned = [], []
+    for event, key in zip(events, keys):
+        if any(key in earlier for earlier in seen):
             key = ''
-        seen.add(key)
+        seen.append(key)
         cleaned.append(event if key else ' '.join(re.findall(r'\[L\d+\]', event)))
     events = cleaned
+    if not re.sub(r'\[L\d+\]', '', events[0]).strip() or strict and not all(
+            re.sub(r'\[L\d+\]', '', event).strip() for event in events):
+        raise ValueError('invalid_output')
     placed = [int(n) for event in events for n in re.findall(r'\[L(\d+)\]', event)]
     if placed != list(range(1, len(lines) + 1)) and strict:
         raise ValueError('invalid_output')
@@ -659,14 +733,58 @@ def restore(words):
                                                       else spoken(lines[int(m.group(2)) - 1], shared)), words)
     parts = []
     for index, event in enumerate(events):
-        if index == 0 and not re.sub(r'\[[LP]\d+\]', '', event).strip():
-            # Nothing sorted into the opening: it is the user's own description, without later lines.
-            mine = set(re.findall(r'\[[LP](\d+)\]', event))
-            words = re.sub(r'\[L(\d+)\]', lambda m: m.group(0) if m.group(1) in mine else '', body)
-            words = restore(' '.join(words.split()))
-        else:
-            words = ' '.join(([CONTINUE] if index or value.get('continued') else []) + [shared] +
-                             ([restore(event)] if event else []))
+        words = ' '.join(([CONTINUE] if index or value.get('continued') else []) + ([shared] if shared else []) +
+                         [restore(event) if re.sub(r'\[[LP]\d+\]', '', event).strip() else
+                          (restore(event) + ' ' + quiet(body)).strip()])
+        if sound:
+            words = 'integrated_multimodal_description: [Shot 1] ' + words + '\n\n' + sound
+        parts.append(words)
+    return parts
+
+
+def order_split(value):
+    """Part texts when the prompt model cannot sort the description: its sentences in order, each in one part.
+
+    Nothing is repeated, so no part plays the story again; a spoken line ends its sentence. A part between
+    sentences carries on from the previous one without speech. Shot labels and their times describe the whole video and
+    are left out.
+    """
+    body, sound, lines = part_source(value['text'])
+    body = re.sub(r'\[Shot \d+\]\s*|\bAt \d{2}:\d{2}(?:\.\d+)?\s*[:,]?\s*', '', body)
+    pieces = sentences(body)
+    count = len(value['seconds'])
+    if not pieces:
+        raise ValueError('invalid_prompt')
+    owner = []
+    if len(pieces) <= count:
+        # A short story is spread over the video instead of ending early.
+        owner = [index * count // len(pieces) for index in range(len(pieces))]
+    else:
+        # Each part takes the sentences whose middle falls in its share of the video, at least one each.
+        # Spoken lines take time: a sentence weighs as much as its words with the lines put back.
+        sizes = [len(re.sub(r'\[L(\d+)\]', lambda m: lines[int(m.group(1)) - 1], piece)) for piece in pieces]
+        total, ends = sum(sizes), []
+        clock = 0.
+        for length in value['seconds']:
+            clock += length
+            ends.append(clock / sum(value['seconds']))
+        done = 0
+        for index, size in enumerate(sizes):
+            middle = (done + size / 2) / total
+            done += size
+            part = next(n for n, end in enumerate(ends) if middle <= end or n == count - 1)
+            low = owner[-1] if owner else 0
+            # Room for every later part to get one sentence, and no part skipped while sentences remain.
+            part = max(low, count - (len(pieces) - index), min(part, low + 1 if owner else 0))
+            owner.append(part)
+    events = [[] for _ in range(count)]
+    for piece, part in zip(pieces, owner):
+        events[part].append(piece)
+    parts = []
+    for index, event in enumerate(events):
+        # A part with no sentence of its own goes on quietly instead of inventing speech.
+        words = re.sub(r'\[L(\d+)\]', lambda m: lines[int(m.group(1)) - 1], ' '.join(event)) or quiet(body)
+        words = ' '.join(([CONTINUE] if index or value.get('continued') else []) + [words])
         if sound:
             words = 'integrated_multimodal_description: [Shot 1] ' + words + '\n\n' + sound
         parts.append(words)
@@ -727,4 +845,5 @@ def validate_parts(parts, value):
 
 
 SPLIT_RETRY = ('Answer again with exactly one "Shared:" line and the "Part N:" lines, every [L] marker exactly once '
-               'and in order, and no marker in Shared.')
+               'and in order, and no marker in Shared. Shared holds no action, and every part has something of its '
+               'own that no other part repeats.')
diff --git a/freevideo_engine/prompt_vlm/worker.py b/freevideo_engine/prompt_vlm/worker.py
index 3d8bfbe4..90fe5d71 100644
--- a/freevideo_engine/prompt_vlm/worker.py
+++ b/freevideo_engine/prompt_vlm/worker.py
@@ -2,6 +2,7 @@
 import json
 import os
 from pathlib import Path
+import re
 import sys
 import time
 import traceback
@@ -331,8 +332,8 @@ def load_model(folder, torch, stats, checkpoint):
     return model, device
 
 
-def generate(torch, model, inputs, max_new_tokens, started, on_token):
-    """Greedy decoding; on_token(timing) sees first-output and decode speed."""
+def generate(torch, model, inputs, max_new_tokens, started, on_token, stop=None):
+    """Greedy decoding; on_token(timing) sees first-output and decode speed, and stop(ids) may end it early."""
     from transformers import StoppingCriteria, StoppingCriteriaList
     prompt = inputs.input_ids.shape[-1]
     timing = {}
@@ -351,7 +352,7 @@ def __call__(self, input_ids, scores, **kwargs):
             timing.update(output_tokens=tokens, decode_seconds=now - self.first,
                           decode_tokens_per_second=(tokens - 1) / (now - self.first) if now > self.first else None)
             on_token(timing)
-            return False
+            return bool(stop is not None and tokens % 16 == 0 and stop(input_ids[0, prompt:]))
     with torch.inference_mode():
         output = model.generate(**inputs, max_new_tokens=max_new_tokens, do_sample=False, use_cache=True,
                                 stopping_criteria=StoppingCriteriaList([Progress()]))
@@ -500,8 +501,17 @@ def on_token(timing):
         if time.monotonic() - shown[0] > .5:
             checkpoint('decode', 'splitting')
             shown[0] = time.monotonic()
-    ids, _ = generate(torch, model, inputs.to(device), limit, loaded, on_token)
-    answers = [processor.decode(ids, skip_special_tokens=True)] if len(ids) < limit else []
+    def ended(ids):
+        # A model that starts the answer over after the last part would repeat it until the limit.
+        text = processor.decode(ids, skip_special_tokens=True)
+        last = re.search(r'(?m)^Part %d:' % count, text)
+        again = last and re.search(r'(?m)^(?:Part \d+:|Shared:)', text[last.end():])
+        return text[:last.end() + again.start()].rstrip() if again else None
+    def answer(ids):
+        text = ended(ids)
+        return [text] if text is not None else [processor.decode(ids, skip_special_tokens=True)] if len(ids) < limit else []
+    ids, _ = generate(torch, model, inputs.to(device), limit, loaded, on_token, ended)
+    answers = answer(ids)
     stats.update(split_seconds=time.monotonic() - loaded, output_tokens=len(ids))
     parts = None
     try:
@@ -512,10 +522,9 @@ def on_token(timing):
             split_user_text(value) + '\n\n' + SPLIT_RETRY)}]}]
         retry_inputs = tokenize(processor, retry)
         if retry_inputs.input_ids.shape[-1] + limit <= stats.get('kv_positions', 10 ** 9):
-            ids, _ = generate(torch, model, retry_inputs.to(device), limit, time.monotonic(), lambda timing: None)
+            ids, _ = generate(torch, model, retry_inputs.to(device), limit, time.monotonic(), lambda timing: None, ended)
             stats.update(split_retry=True, retry_output_tokens=len(ids), split_seconds=time.monotonic() - loaded)
-            if len(ids) < limit:
-                answers.insert(0, processor.decode(ids, skip_special_tokens=True))
+            answers[:0] = answer(ids)
         for strict in (True, False):
             for answer in answers:
                 try:
diff --git a/web/generation_progress.js b/web/generation_progress.js
index 896d5a8f..51b7ff7a 100644
--- a/web/generation_progress.js
+++ b/web/generation_progress.js
@@ -98,7 +98,7 @@ const STALL_SECONDS_BY_PHASE = Object.freeze({
     latent_upscale: 180, sample_finalize: 180, decode: 180, save: 180,
     dependencies: 180, recovery: 180, other: 180,
     // A long video's part descriptions: the server waits at most 10 min for the model and
-    // writes for at most 15 min, then falls back to the whole description on its own.
+    // writes for at most 15 min, then splits the description by sentence on its own.
     describe: 1500,
 });
 // Normal stage sentences keep the sampling step or a download's size and speed.
@@ -780,8 +780,8 @@ export function createGenerationProgress(t, now = () => Date.now(), {compact = f
             automatic: compatibilityText,
             notice: trimStatus([...trims.values()], t),
             // A long video whose part descriptions could not be written: the server's own words stay in the report.
-            split: splitFailed === 'model_missing' ? t('Prompt model not installed. Every part uses the same description.', '未安装提示词模型，各段用同一段描述')
-                : t('Every part uses the same description.', '各段用同一段描述')}[level] || (!ended ? progressText : '');
+            split: splitFailed === 'model_missing' ? t('Prompt model not installed. The description is split across the parts by sentence.', '未安装提示词模型，描述按句子顺序分到各段')
+                : t('The description is split across the parts by sentence.', '描述按句子顺序分到各段')}[level] || (!ended ? progressText : '');
         if (status.textContent !== explanation) status.textContent = explanation;
         status.hidden = !explanation; status.dataset.level = level;
         const announcements = [];

From dae8a954ac101c06846a6da2aa958fb5b249cc92 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 03:30:02 +0000
Subject: [PATCH 47/52] Add prompt model download notice for multi-part videos

---
 web/prompt_enhance.js | 98 ++++++++++++++++++++++++++++++++-----------
 web/studio.css        |  3 ++
 web/studio.js         |  2 +-
 web/studio_length.js  | 26 +++++++++++-
 4 files changed, 102 insertions(+), 27 deletions(-)

diff --git a/web/prompt_enhance.js b/web/prompt_enhance.js
index 2c46e339..4fd9341c 100644
--- a/web/prompt_enhance.js
+++ b/web/prompt_enhance.js
@@ -97,6 +97,7 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
     meter.append(fill); status.append(statusText, meter, report);
     // One place sets what the status line says and how it looks.
     function show(text, state = '', fraction = null) {
+        if (downloadOnly) { publishModel({text: text || ''}); return; }
         statusText.textContent = text || '';
         status.dataset.state = text ? state : '';
         report.hidden = !text || state !== 'error';
@@ -114,6 +115,26 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
     install.append(detail, actions);
     bar.append(label, tabs, redo, cancel); element.append(bar, editor || input, status, install);
     let disposed = false, token = '', job = '', running = null, consent = null, cancelling = false, waiting = false, replacing = false;
+    let downloadOnly = false, modelReading = null;
+    const modelState = {info: null, text: '', busy: false}, modelListeners = new Set();
+    function publishModel(change) {
+        Object.assign(modelState, change);
+        if (!disposed) for (const listener of modelListeners) listener(modelState);
+    }
+    // Share status with the length notice, including installs started by enhancement.
+    function readModel() {
+        if (modelReading) return modelReading;
+        modelReading = (async () => {
+            const reply = await api.fetchApi('/freevideo/prompt-vlm');
+            const info = await reply.json();
+            if (!reply.ok) throw new Error(info.error || 'request_failed');
+            token = info.token;
+            if (info.ram_bytes) ramBytes = info.ram_bytes;
+            publishModel({info});
+            return info;
+        })().catch(error => { publishModel({info: null}); throw error; }).finally(() => { modelReading = null; });
+        return modelReading;
+    }
     const prestart = promptPrestart(api, node.id, () => versions.value.enabled, () => !disposed && !input.disabled);
     const onFocus = () => { if (versions.value.enabled) void prestart.request(); };
     input.addEventListener('focus', onFocus);
@@ -225,12 +246,11 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
                 }
                 if (row.phase === 'complete') return row;
                 if (row.phase === 'failed') throw Object.assign(new Error(row.error || 'rewrite_failed'), {ramBytes: row.diagnostics?.ram_required_bytes});
-                if (row.phase === 'cancelled') throw new Error('cancelled');
+                if (row.phase === 'cancelled') throw new Error(action === 'install' ? 'download_failed' : 'cancelled');
                 if (disposed) throw new Error('cancelled');
                 if (row.phase === 'download') {
-                    const fraction = (row.done || 0) / (row.total || 1), gib = value => (value / 2 ** 30).toFixed(1);
-                    show(t(`Downloading the model · ${gib(row.done || 0)} / ${gib(row.total || 0)} GiB`, `正在下载模型 · ${gib(row.done || 0)} / ${gib(row.total || 0)} GiB`), 'progress', fraction);
-                } else {
+                    showDownload(row.done || 0, row.total || 0);
+                } else if (action !== 'install') {
                     // The ellipsis says "still going" until the seconds start counting.
                     const [en, zh] = row.phase === 'rewriting' ? ['Enhancing the prompt', '正在改写提示词'] : ['Preparing enhancement', '正在准备提示词增强'];
                     const s = elapsed(), m = Math.floor(s / 60), r = s % 60;
@@ -245,6 +265,46 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
             throw error;
         } finally { job = ''; }
     }
+    function showDownload(done, total) {
+        const size = value => (value / 2 ** 30).toFixed(1);
+        const text = t(`Downloading the model · ${size(done)} / ${size(total)} GiB`, `正在下载模型 · ${size(done)} / ${size(total)} GiB`);
+        publishModel({text}); show(text, 'progress', done / (total || 1));
+    }
+    async function installModel(info) {
+        if (info.ready) return true;
+        const model = String(info.model || 'Qwen/Qwen3-VL-4B-Instruct').split('/').pop().replace(/-Instruct$/, '');
+        detail.textContent = t(`Local model ${model} · ${(info.bytes / 2 ** 30).toFixed(1)} GiB download · needs ${gib(ramBytes)} GiB free RAM. Your prompt and images stay on this computer.`,
+            `本地模型 ${model} · 下载 ${(info.bytes / 2 ** 30).toFixed(1)} GiB · 需 ${gib(ramBytes)} GiB 可用内存。提示词和图片只在本机处理。`);
+        agree.textContent = downloadOnly ? t('Download', '下载') : t('Download and enable', '下载并启用');
+        install.hidden = false; render();
+        if (downloadOnly) install.scrollIntoView({block: 'nearest'});
+        const accepted = await new Promise(resolve => { consent = resolve; agree.onclick = () => resolve(true); decline.onclick = () => resolve(false); });
+        consent = null; install.hidden = true; render();
+        if (!accepted || disposed || cancelling) return false;
+        publishModel({busy: true}); showDownload(0, info.bytes || 0);
+        try {
+            await poll('install', {accept_download: true});
+            // A complete install is already authoritative; refresh metadata as well.
+            publishModel({info: {...info, ready: true}, text: ''});
+            await readModel().catch(() => {});
+        } catch (error) {
+            publishModel({text: errorText(error)});
+            throw error;
+        } finally { publishModel({busy: false}); }
+        return true;
+    }
+    function downloadModel() {
+        if (running || disposed) return;
+        downloadOnly = true; cancelling = false;
+        running = Promise.resolve().then(async () => {
+            const info = await readModel();
+            if (!disposed && !cancelling) await installModel(info);
+        }).catch(error => { if (!disposed) show(errorText(error)); }).finally(() => {
+            running = null; downloadOnly = false; cancelling = false; install.hidden = true; render();
+        });
+        render();
+        return running;
+    }
     async function enhance() {
         if (running) return running;
         if (!versions.value.original.trim()) {
@@ -256,25 +316,12 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
             if (disposed || cancelling) throw new Error('cancelled');
             versions.value.useOriginal = false;
             const scene = context(), key = versions.key(scene), original = versions.value.original, edits = versions.value.edits;
-            const reply = await api.fetchApi('/freevideo/prompt-vlm');
-            const info = await reply.json();
+            const info = await readModel();
             if (disposed || cancelling) throw new Error('cancelled');
-            if (!reply.ok) throw new Error(info.error);
-            token = info.token;
-            if (info.ram_bytes) ramBytes = info.ram_bytes;
-            if (!info.ready) {
-                const model = String(info.model || 'Qwen/Qwen3-VL-4B-Instruct').split('/').pop().replace(/-Instruct$/, '');
-                detail.textContent = t(`Local model ${model} · ${(info.bytes / 2 ** 30).toFixed(1)} GiB download · needs ${gib(ramBytes)} GiB free RAM. Your prompt and images stay on this computer.`,
-                    `本地模型 ${model} · 下载 ${(info.bytes / 2 ** 30).toFixed(1)} GiB · 需 ${gib(ramBytes)} GiB 可用内存。提示词和图片只在本机处理。`);
-                install.hidden = false; render();
-                const accepted = await new Promise(resolve => { consent = resolve; agree.onclick = () => resolve(true); decline.onclick = () => resolve(false); });
-                consent = null; install.hidden = true; render();
-                if (!accepted || disposed || cancelling) {
-                    versions.value.enabled = false;
-                    versions.select('original'); apply();
-                    throw new Error('cancelled');
-                }
-                await poll('install', {accept_download: true});
+            if (!await installModel(info)) {
+                versions.value.enabled = false;
+                versions.select('original'); apply();
+                throw new Error('cancelled');
             }
             const result = await poll('rewrite', {text: prepare(original), ...scene});
             if (disposed || cancelling) throw new Error('cancelled');
@@ -300,7 +347,10 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
         versions.value.selected = 'original'; apply();
         show(t(`Generated with the original prompt. ${fallbackText(error)}`, `已用原文生成。${fallbackText(error)}`), 'note');
     }
-    return {element, async beforeGenerate() {
+    return {element, model: {read: readModel, download: downloadModel, subscribe(listener) {
+        modelListeners.add(listener); listener(modelState);
+        return () => modelListeners.delete(listener);
+    }}, async beforeGenerate() {
         if (running) {
             try { await running; }
             catch (error) {
@@ -318,7 +368,7 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
             useOriginal(error);
         }
     }, sync() { if (input.value !== versions.text()) changed(); }, dispose() {
-        disposed = true; prestart.dispose(); cancelJob().catch(() => {}); input.removeEventListener('input', changed);
+        disposed = true; modelListeners.clear(); prestart.dispose(); cancelJob().catch(() => {}); input.removeEventListener('input', changed);
         input.removeEventListener('beforeinput', replace);
         input.removeEventListener('focus', onFocus);
     }};
diff --git a/web/studio.css b/web/studio.css
index 91a98ee0..1b2c3d5d 100644
--- a/web/studio.css
+++ b/web/studio.css
@@ -35,6 +35,9 @@
 .fv-studio .fv-length-link{display:inline;min-height:0;padding:0;border:0;border-radius:0;background:transparent;color:var(--fv-accent);font:inherit;vertical-align:baseline;text-decoration:underline;text-underline-offset:3px;white-space:nowrap}
 .fv-studio .fv-length-link:hover{background:transparent;color:var(--fv-ink)}
 .fv-studio .fv-length-link:focus-visible{outline:2px solid var(--fv-accent);outline-offset:3px}
+.fv-studio .fv-length-model{margin:12px 0;line-height:1.6}
+.fv-studio .fv-length-model .fv-quiet{min-height:28px;padding:3px 8px;margin-left:4px;font:inherit;white-space:nowrap}
+@media(max-width:480px){.fv-studio .fv-length-model .fv-quiet{display:flex;width:max-content;margin:6px 0 0}}
 .fv-studio .fv-resolution-select{position:relative;min-width:0}
 .fv-studio .fv-resolution-select select{appearance:none;-webkit-appearance:none;color:transparent;padding-right:36px}
 .fv-studio .fv-resolution-select option{color:var(--fv-ink)}
diff --git a/web/studio.js b/web/studio.js
index 047afe8b..5395472b 100644
--- a/web/studio.js
+++ b/web/studio.js
@@ -1006,7 +1006,7 @@ export function openStudio(node, {extendFrom = null} = {}) {
         };
     }
     advanced.append(custom);
-    lengthControl = createStudioLength({api, node, seconds, advanced, fields, t, field,
+    lengthControl = createStudioLength({api, node, seconds, advanced, fields, t, field, promptModel: enhancer.model,
         setSeconds: seconds => set(node, 'seconds', seconds), onChange: () => { if (runButtonReady) { updateRunButton(); showEffortEstimate(); updateDuration(); } },
         onEditor: toEditor, onAutopilot: toAutopilot, autopilot: !autopilotTab.hidden});
     cleanup.push(() => lengthControl.dispose());
diff --git a/web/studio_length.js b/web/studio_length.js
index bc72c781..dfd0b41f 100644
--- a/web/studio_length.js
+++ b/web/studio_length.js
@@ -28,7 +28,7 @@ export async function readLengthCapability(api, context, signal, onReply = () =>
 // onEditor and onAutopilot are the creation panel's own view-switch actions; autopilot says whether that tab shows.
 export function createStudioLength({api, node, seconds, advanced, fields, t, field, setSeconds,
     onChange = () => {}, capability = readLengthCapability, delay = 220, capabilityTimeout = 10000,
-    onEditor = () => {}, onAutopilot = () => {}, autopilot = false}) {
+    onEditor = () => {}, onAutopilot = () => {}, autopilot = false, promptModel = null}) {
     const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text) e.textContent = text; return e; };
     const controls = el('div', 'fv-length-controls'); controls.style.marginTop = '14px';
     const single = el('input'); single.type = 'checkbox'; single.dataset.fvLength = 'single';
@@ -64,6 +64,13 @@ export function createStudioLength({api, node, seconds, advanced, fields, t, fie
         : hint.replaceChildren(t('Each run makes one continuous shot, split into up to 8 parts when longer. ', '每次生成一个连续镜头，较长时自动分段，最多 8 段。'), ...storyboard());
     writeHint();
     fields.after(hint);
+    const modelNotice = el('div', 'fv-muted fv-length-model'); modelNotice.hidden = true; modelNotice.setAttribute('role', 'status');
+    const modelText = el('span');
+    const download = el('button', 'fv-quiet', t('Download prompt model', '下载提示词模型')); download.type = 'button';
+    modelNotice.append(modelText, download); hint.after(modelNotice);
+    download.onclick = () => { void promptModel?.download(); };
+    let modelState = {}, modelChecked = false;
+
     let limits = null, planLimits = null, contextKey = '', revision = 0, timer = null, request = null, capabilityRequest = null, capabilityRevision = 0;
     let capabilityState = 'idle', waiting = false, waitingTimer = null, timeoutTimer = null, submitted = false;
     let plan = null, error = null, absent = false, disposed = false, pending = null, edited = false, blockEdited = false, plannedSeconds = null;
@@ -77,6 +84,20 @@ export function createStudioLength({api, node, seconds, advanced, fields, t, fie
             blockSeconds: blockEdited || Object.hasOwn(node.properties || {}, LENGTH_PROPERTIES.block) ? Number(block.value)
                 : !planLimits && total() > 15 && total() <= 30 ? defaultBlockSeconds(null) : null};
     }
+    function paintModel() {
+        const multiple = !absent && !error && plan?.count >= 2;
+        modelNotice.hidden = !multiple || modelState.info?.ready !== false;
+        modelText.textContent = modelState.text || t('The prompt model is not installed, so the description will be split across the parts by sentence.', '未安装提示词模型，描述将按句子顺序分到各段。');
+        download.hidden = Boolean(modelState.busy); download.disabled = Boolean(modelState.busy);
+        // Pending plans do not reset the check on every keystroke. A known single part does.
+        if (plan?.count === 1 || (!plan && !effectiveSingle() && total() <= singleLimitSeconds(planLimits?.maximum)
+            && !Object.hasOwn(node.properties || {}, LENGTH_PROPERTIES.block))) modelChecked = false;
+        if (multiple && !modelChecked && promptModel) {
+            modelChecked = true;
+            promptModel.read().catch(() => {});
+        }
+    }
+    const unsubscribeModel = promptModel?.subscribe(state => { modelState = state; if (!disposed) paintModel(); });
     function paint() {
         const maximum = planLimits?.maximum, forcedMaximum = planLimits?.singleMaximum;
         const clamped = positive(maximum) && node.properties?.[LENGTH_PROPERTIES.block] > maximum;
@@ -103,6 +124,7 @@ export function createStudioLength({api, node, seconds, advanced, fields, t, fie
         if (error === 'too_long') note.replaceChildren(TOO_LONG(), ...storyboard());
         else note.textContent = error ? errorMessage(error) : '';
         if (error === 'other') note.append(issueButton(t, () => ({where: ['Video length planning', '视频分段规划'], message: errorMessage('other')})));
+        paintModel();
         note.style.margin = noParts && error === 'continuation_unavailable' ? '12px 0' : ''; // as spaced as the line it replaces
     }
     function errorMessage(kind) {
@@ -215,6 +237,6 @@ export function createStudioLength({api, node, seconds, advanced, fields, t, fie
                 catch { settle(null); }
             })();
         },
-        dispose() { disposed = true; clearTimeout(timer); clearTimeout(waitingTimer); clearTimeout(timeoutTimer); request?.abort(); capabilityRequest?.abort(); seconds.removeEventListener('input', input); },
+        dispose() { disposed = true; unsubscribeModel?.(); clearTimeout(timer); clearTimeout(waitingTimer); clearTimeout(timeoutTimer); request?.abort(); capabilityRequest?.abort(); seconds.removeEventListener('input', input); },
     };
 }

From 116d2c3f1b5d55fc0aef961a74e93a36754b90d3 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 04:57:57 +0000
Subject: [PATCH 48/52] Pause the prompt model download when a multi-part video
 starts

Generating while the download confirmation is open or the download is
running no longer waits for it: the download is paused, the parts are
split by sentence, and Retry resumes the download later.
---
 web/prompt_enhance.js | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/web/prompt_enhance.js b/web/prompt_enhance.js
index 4fd9341c..0bc3e400 100644
--- a/web/prompt_enhance.js
+++ b/web/prompt_enhance.js
@@ -115,7 +115,7 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
     install.append(detail, actions);
     bar.append(label, tabs, redo, cancel); element.append(bar, editor || input, status, install);
     let disposed = false, token = '', job = '', running = null, consent = null, cancelling = false, waiting = false, replacing = false;
-    let downloadOnly = false, modelReading = null;
+    let downloadOnly = false, pausing = false, modelReading = null;
     const modelState = {info: null, text: '', busy: false}, modelListeners = new Set();
     function publishModel(change) {
         Object.assign(modelState, change);
@@ -288,7 +288,7 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
             publishModel({info: {...info, ready: true}, text: ''});
             await readModel().catch(() => {});
         } catch (error) {
-            publishModel({text: errorText(error)});
+            publishModel({text: errorText(pausing ? {message: 'download_failed'} : error)});
             throw error;
         } finally { publishModel({busy: false}); }
         return true;
@@ -299,12 +299,20 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
         running = Promise.resolve().then(async () => {
             const info = await readModel();
             if (!disposed && !cancelling) await installModel(info);
-        }).catch(error => { if (!disposed) show(errorText(error)); }).finally(() => {
-            running = null; downloadOnly = false; cancelling = false; install.hidden = true; render();
+        }).catch(error => { if (!disposed) show(errorText(pausing ? {message: 'download_failed'} : error)); }).finally(() => {
+            running = null; downloadOnly = false; cancelling = false; pausing = false; install.hidden = true; render();
         });
         render();
         return running;
     }
+    async function stopped(id) {
+        // The engine is free again once the server reports the download job ended (at most 10 s).
+        for (let i = 0; id && !disposed && i < 40; i++) {
+            const row = await post('status', {job: id}).catch(() => null);
+            if (!row || ['complete', 'failed', 'cancelled'].includes(row.phase)) return;
+            await new Promise(resolve => setTimeout(resolve, 250));
+        }
+    }
     async function enhance() {
         if (running) return running;
         if (!versions.value.original.trim()) {
@@ -351,6 +359,15 @@ export function createPromptEnhancer({node, input, editor, api, context, setText
         modelListeners.add(listener); listener(modelState);
         return () => modelListeners.delete(listener);
     }}, async beforeGenerate() {
+        if (running && downloadOnly) {
+            // The download holds the engine the video needs: pause it (Retry resumes) instead of waiting for it.
+            const request = running, downloading = consent ? '' : job;
+            pausing = true;
+            await cancelJob().catch(() => {});
+            await request;
+            await stopped(downloading);
+            return;
+        }
         if (running) {
             try { await running; }
             catch (error) {

From ad573b48c5a71d454a2ebb86972807319b2815e1 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Tue, 27 Oct 2026 04:59:22 +0000
Subject: [PATCH 49/52] Show the prompt model download as an outlined button on
 its own line

---
 web/studio.css | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/web/studio.css b/web/studio.css
index 1b2c3d5d..31abc304 100644
--- a/web/studio.css
+++ b/web/studio.css
@@ -36,8 +36,8 @@
 .fv-studio .fv-length-link:hover{background:transparent;color:var(--fv-ink)}
 .fv-studio .fv-length-link:focus-visible{outline:2px solid var(--fv-accent);outline-offset:3px}
 .fv-studio .fv-length-model{margin:12px 0;line-height:1.6}
-.fv-studio .fv-length-model .fv-quiet{min-height:28px;padding:3px 8px;margin-left:4px;font:inherit;white-space:nowrap}
-@media(max-width:480px){.fv-studio .fv-length-model .fv-quiet{display:flex;width:max-content;margin:6px 0 0}}
+.fv-studio .fv-length-model .fv-quiet{display:flex;width:max-content;margin:6px 0 0;min-height:28px;padding:3px 12px;border:1px solid var(--fv-border,#ffffff2e);border-radius:var(--fv-r-sm,6px);color:var(--fv-ink);font:inherit;white-space:nowrap}
+.fv-studio .fv-length-model .fv-quiet:hover:not(:disabled){border-color:var(--fv-muted,#a2abba)}
 .fv-studio .fv-resolution-select{position:relative;min-width:0}
 .fv-studio .fv-resolution-select select{appearance:none;-webkit-appearance:none;color:transparent;padding-right:36px}
 .fv-studio .fv-resolution-select option{color:var(--fv-ink)}

From 9045b9a2efb32ea93b5f60e055e77f6257517026 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Mon, 26 Oct 2026 17:57:20 +0000
Subject: [PATCH 50/52] Keep a running chain block's report id and mark a
 restarted run's report as interrupted

Keep a running chain block's report id and mark a restarted run's report as interrupted, on top of the persisted report index.
---
 freevideo_engine/chain_runner.py   |  9 +++++++++
 freevideo_engine/comfy_progress.py |  4 +++-
 freevideo_engine/support_report.py | 11 ++++++++---
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/freevideo_engine/chain_runner.py b/freevideo_engine/chain_runner.py
index d4928750..401ee784 100644
--- a/freevideo_engine/chain_runner.py
+++ b/freevideo_engine/chain_runner.py
@@ -5,6 +5,7 @@
 import math
 from pathlib import Path, PurePosixPath
 import random
+import re
 import threading
 import time
 import uuid
@@ -12,6 +13,8 @@
 from . import chain_leads, chain_plan
 from . import chain_store as store
 
+REPORT_ID = re.compile(r'[a-f0-9]{32}')
+
 
 def _split_value(record, text):
     """What the prompt model sorts into parts: the whole description and each part's new seconds."""
@@ -959,6 +962,12 @@ def progress(self, node, message):
             block = self._current(record)
             if block is None or block['state'] != 'running':
                 return None
+            token = message.get('report_id')
+            if isinstance(token, str) and REPORT_ID.fullmatch(token) and block['report_id'] != token:
+                # A restart ends this block before `finished` stores its report, and the
+                # report of the interrupted run is the one a failure needs.
+                block['report_id'] = record['last_report_id'] = token
+                self._save(record)
             overall = message.get('overall') or {}
             used = _number(overall.get('elapsed_seconds'))
             used = self._elapsed(block) if used is None else used
diff --git a/freevideo_engine/comfy_progress.py b/freevideo_engine/comfy_progress.py
index d51268d0..572be5c8 100644
--- a/freevideo_engine/comfy_progress.py
+++ b/freevideo_engine/comfy_progress.py
@@ -236,6 +236,8 @@ def _recall(self, token):
         return None
 
     def snapshot(self, token):
+        with self.lock:
+            restarted = token not in self.runs
         output = self._lookup(token)
         if output is None:
             raise KeyError('Unknown report')
@@ -244,7 +246,7 @@ def snapshot(self, token):
         target = output.with_suffix('.live.debug.json')
         if is_link(output.parent) or target.is_symlink() or target.exists() and is_link(target):
             raise KeyError('Report unavailable')
-        path = write(output, live=True)
+        path = write(output, live=True, restarted=restarted)
         if path is None:
             raise RuntimeError('Report not available yet')
         return path.read_bytes()
diff --git a/freevideo_engine/support_report.py b/freevideo_engine/support_report.py
index d9fa71b2..6e44f2b0 100644
--- a/freevideo_engine/support_report.py
+++ b/freevideo_engine/support_report.py
@@ -308,8 +308,11 @@ def write_encoder_retry(output, encoding, *, index):
     return write(output, _retry=dict(stage='encoding', index=index, encoding=encoding))
 
 
-def write(output, report=None, bridge=None, *, _retry=None, live=False):
-    """Bounded JSON/log reads only. Failure to write must not fail generation."""
+def write(output, report=None, bridge=None, *, _retry=None, live=False, restarted=False):
+    """Bounded JSON/log reads only. Failure to write must not fail generation.
+
+    restarted: a live report of a run that an earlier ComfyUI process started; nothing is still running it.
+    """
     output = Path(output)
     notes = []
     def read_json(suffix, path=None):
@@ -454,7 +457,7 @@ def count(value):
         if not request.get('encoding_resources'):
             request['encoding_resources'] = dict(ram=read_json('.encoding.memory.json'))
         summary = summarize(request, engine, encoding)
-        if live and bridge.get('status') in ('starting', 'running'):
+        if live and not restarted and bridge.get('status') in ('starting', 'running'):
             summary['status'] = 'running'
         if bridge.get('status') == 'reused':
             summary['status'] = 'reused'
@@ -535,6 +538,8 @@ def count(value):
         payload = redactor.structured(payload)
         if live:
             payload['snapshot'] = dict(collected_at=time.time(), running=summary['status'] == 'running')
+            if restarted:
+                payload['snapshot']['restarted_since_run'] = True
         # The generic secret redactor matches "token_summary" as a token key.
         # Restore only its fixed numeric counts, never token IDs or text.
         from .diagnostic_resources import token_summary

From 4b9d43ff04c9840bf388c57abb733b750751f735 Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Wed, 28 Oct 2026 23:29:23 +0000
Subject: [PATCH 51/52] Release notes for 0.4.24

---
 freevideo_engine/release_notes.json | 86 ++++++++++++++---------------
 1 file changed, 42 insertions(+), 44 deletions(-)

diff --git a/freevideo_engine/release_notes.json b/freevideo_engine/release_notes.json
index 41b3113e..4f421f4f 100644
--- a/freevideo_engine/release_notes.json
+++ b/freevideo_engine/release_notes.json
@@ -1,21 +1,56 @@
 {
   "schema": 1,
-  "product_version": "0.4.23",
+  "product_version": "0.4.24",
   "en": {
-    "summary": "Each part planned in the editor can have its own description; low-memory generations explain why they are slower.",
+    "summary": "A person in a source video can be replaced with the character in a person image; reference videos can be used for depth only; the built-in AI sets up a white-model scene from one sentence; an earlier video's prompt and settings can be reused; decoding on cards with less video memory is quicker.",
     "changes": [
-      "Generation: When a generation runs in low-memory mode, the progress view says why it is slower.",
-      "Editor: Each part of a video planned in the editor can now have its own description, and a continued part uses exactly what you write for it. The highlight on characters mentioned with @ in the prompt box updates as soon as a rewritten prompt is filled in."
+      "Studio: \"Replace person\" in the Media section replaces the person in a source video with the character in a person image, and can keep the source video's sound; if that sound cannot be added, the finished video is still kept. A reference video can be set to \"Depth only\"; its depth is computed once and reused by later requests.",
+      "Creation panel: after an earlier video is selected in Recent videos, \"Reuse settings\" fills its prompt, picture size and duration back into the panel; \"Undo\" restores the previous values within 10 seconds.",
+      "White models: when no external Agent is connected, the white-model button in the chat box works with the built-in AI. Describe the shot in one sentence; if a ready-made scene fits, a white model is generated for confirmation, otherwise the reason is shown and the sentence is kept.",
+      "Long videos: when a description is split across parts, the story is no longer repeated in every part; the shared text keeps only what stays the same, such as people, place, lighting and style. Without the prompt model, the description is split across the parts by sentence instead of every part using the whole description, and the creation panel offers to download the prompt model; a download in progress is paused when generation starts.",
+      "Editor: a continued part can be as short as 5 seconds, and on Mac and on computers that cannot make 10 seconds at once a new part starts at 5 seconds; a video with a continued part shorter than 10 seconds has at most 4 parts. A description over the length limit is pointed out before sending, including on a retry.",
+      "Generation: after other ComfyUI workflows have run, the video memory they hold is released before a picture or a prompt rewrite starts, without restarting ComfyUI. A missing text encoder model is detected before encoding starts, with repair guidance; if a model repair fails while downloading, the original file is restored. When generation cannot start because the installation is in use, the failure details name the programs holding it open. When the GPU checks before switching to int8 fail, the failure card lists the reason for each check.",
+      "Memory and speed: on graphics cards that cannot hold the whole decoder, decoding no longer prepares the same layers again for every video segment or every new request while memory allows, with identical output. On most Windows graphics cards with 8 to 12 GB of video memory, the first pass of two-pass videos between 10 and 12 seconds without LoRA computes 8 attention heads at a time instead of 4, as shorter videos already did. On Windows, when other programs free video memory during a generation, the next pass and decoding use the recovered memory.",
+      "Install: setup no longer stops with a dependency mismatch after the installation folder was moved, copied or restored, and a dependency folder too deep for Windows is reported as a long path. Text encoder and tokenizer files deleted after installation are restored from the local copy before encoding and during repair, without downloading.",
+      "Phone access: the phone page works when local network access is switched on in the launcher, and no longer shows \"Connection lost. Reconnecting…\" with no content.",
+      "Agents: the install-skill command installs the FreeVideo skill for an Agent, also from deeply nested Windows folders. The tool list an Agent receives is shorter: common tools are listed in full and the others are opened through a help tool.",
+      "Diagnostic reports: when ComfyUI restarts during a generation, the report of that run is marked as interrupted instead of running, and a long video keeps the report of the part that was interrupted."
     ]
   },
   "zh": {
-    "summary": "剪辑里规划的每一段可以单独写描述；低显存模式下的生成会说明较慢的原因。",
+    "summary": "可以用人物图中的角色替换源视频里的人物；参考视频可以仅参考深度；内置 AI 可以用一句话搭出白模场景；可以复用之前视频的提示词和设置；显存较小的显卡解码更快。",
     "changes": [
-      "生成：低显存模式下，进度区会说明这次生成较慢的原因。",
-      "剪辑视图：剪辑里规划的每一段现在都可以单独写描述，接着生成的一段会用为它写的描述。改写后的提示词填回时，@人物 高亮立即刷新。"
+      "工作室：“素材”一栏新增“替换人物”，用人物图中的角色替换源视频里的人物，可选保留源视频的声音；声音未能加入时，生成的视频仍会保留。参考视频可以勾选“仅参考深度”，深度只计算一次，之后的请求直接复用。",
+      "创作面板：在“最近作品”中选中之前的视频后，点“复用设置”可以把它的提示词、画面尺寸和时长填回面板；10 秒内点“撤销”可以恢复原来的内容。",
+      "白模：未连接外部 Agent 时，聊天框的白模按钮也可以使用。用一句话描述镜头，有合适的现成场景就先生成白模供确认，没有则说明原因并保留输入。",
+      "长视频：描述分到各段时，不再在每一段重复整个故事，各段共用的部分只保留人物、场景、光线和风格等不变的内容。未安装提示词模型时，描述按句子顺序分到各段，不再每段都用整段描述，创作面板会提示下载提示词模型；开始生成时，正在进行的下载会暂停。",
+      "剪辑视图：接着生成的每段最短可以是 5 秒，在 Mac 和无法一次生成 10 秒的电脑上，新的一段默认 5 秒；含短于 10 秒的接续段时，一个视频最多 4 段。描述超过长度上限时，发送前（包括重试时）就会提示。",
+      "生成：在 ComfyUI 里跑过其他工作流之后，生成图片和改写提示词前会先释放这些工作流占用的显存，无需重启 ComfyUI。文本编码器模型缺失时，会在编码开始前检测并给出修复指引；模型修复在下载中失败时，会还原原来的文件。安装正被占用而无法开始生成时，失败详情会写出占用它的程序。切换到 int8 前的 GPU 检查失败时，错误卡片会列出每项检查的失败原因。",
+      "内存与速度：显存放不下整个解码器的显卡，在内存允许时解码不再为每个视频片段或每次新请求重复准备同样的层，输出不变。显存 8–12 GB 的大多数 Windows 显卡上，10–12 秒、不带 LoRA 的两遍视频，第一遍每次计算的注意力头由 4 个增加到 8 个，与更短的视频相同。Windows 上，生成过程中其他程序释放显存后，下一遍和解码会用上恢复的显存。",
+      "安装：安装目录被移动、复制或还原后，安装不再因依赖不一致而停下；依赖目录层级过深时会按长路径问题提示。安装后被删掉的文本编码器和分词器文件，会在编码前和修复时从本地副本还原，不需要下载。",
+      "手机访问：在启动器里打开局域网访问后，手机页可以正常使用，不再一直显示“连接断了，正在重新连接…”且没有内容。",
+      "Agent：install-skill 命令可以为 Agent 安装 FreeVideo 技能，Windows 上层级很深的目录也能装。Agent 拿到的工具列表更短：常用工具完整列出，其余工具通过帮助工具打开。",
+      "诊断报告：生成过程中 ComfyUI 重启后，这次运行的报告会标为已中断，不再显示为运行中；长视频会保留被中断那一段的报告。"
     ]
   },
   "history": [
+    {
+      "product_version": "0.4.23",
+      "en": {
+        "summary": "Each part planned in the editor can have its own description; low-memory generations explain why they are slower.",
+        "changes": [
+          "Generation: When a generation runs in low-memory mode, the progress view says why it is slower.",
+          "Editor: Each part of a video planned in the editor can now have its own description, and a continued part uses exactly what you write for it. The highlight on characters mentioned with @ in the prompt box updates as soon as a rewritten prompt is filled in."
+        ]
+      },
+      "zh": {
+        "summary": "剪辑里规划的每一段可以单独写描述；低显存模式下的生成会说明较慢的原因。",
+        "changes": [
+          "生成：低显存模式下，进度区会说明这次生成较慢的原因。",
+          "剪辑视图：剪辑里规划的每一段现在都可以单独写描述，接着生成的一段会用为它写的描述。改写后的提示词填回时，@人物 高亮立即刷新。"
+        ]
+      }
+    },
     {
       "product_version": "0.4.22",
       "en": {
@@ -206,43 +241,6 @@
           "提交问题：反馈里的内存读数分开记录物理可用内存和提交余量。"
         ]
       }
-    },
-    {
-      "product_version": "0.4.15",
-      "en": {
-        "summary": "Image generation keeps a history of every picture and needs less memory on both small and large graphics cards, error messages everywhere now come with a button to report the problem, and Windows updates download faster in mainland China.",
-        "changes": [
-          "Image generation: every image generated on this machine is kept in a history, newest first, and can be placed on the canvas, used as a reference, deleted, or opened in its folder. Blank canvases offer Standard and HD sizes.",
-          "Image generation: on 6-8 GB graphics cards, decoding uses less graphics memory and runs faster. On cards that can hold the whole model, the weights load straight to the card and no second copy stays in system memory, which cuts memory use after loading from about 15 GB to about 2 GB.",
-          "Reporting problems: wherever an error or failure message appears, including generation, editing and export, models and environment, image generation, the agent connection, the library, prompt enhancement, sharing, updates, and the launcher, a Report a problem button next to it opens the feedback form with the context filled in.",
-          "AI Autopilot: when a chat cannot be deleted, it now says why and offers Stop and delete; other failures are reported with a button to submit the problem.",
-          "White models: only the cat ready-made scene remains, and one click starts it. A white model that was not made now says why and what to do next, and the page shows rendering progress. A question about progress is answered instead of being started as a new request.",
-          "Character sheets: in the back view, the head now turns away together with the body.",
-          "Mac: long videos can now be generated in parts.",
-          "Launcher and updates: Windows updates download faster in mainland China. When GitHub is slow, the launcher can fetch the update from a domestic mirror, and every file from the mirror is checked against the release signature before use. The install confirmation page now fits narrow windows: the sidebar collapses to icons and the buttons stay visible.",
-          "Workflows: workflows saved by older versions run again. Options added in later versions that are empty or invalid in an old file are set back to their defaults.",
-          "Video generation: the High quality level generates faster. On 8 GB graphics cards, 1920x1088 videos that were refused for falling just short of graphics memory now run. Changing the early steps setting of a video reference now produces a new result instead of reusing the earlier one.",
-          "LoRA: a LoRA trained for Wan 2.x now says so when it is selected for the int8 model, instead of only saying it cannot be used.",
-          "Linux: on computers with less memory, generating again right after a generation no longer runs out of memory near the end of sampling. On 6 GB graphics cards, Max no longer takes hours to finish."
-        ]
-      },
-      "zh": {
-        "summary": "生图工具会保存所有生成过的图片，小显存和大显存的显卡生图都更省内存；所有错误提示旁都有“提交问题”按钮；Windows 版在中国大陆更新更快。",
-        "changes": [
-          "生图：本机生成过的图片都保存在历史记录里，按时间从新到旧排列，可放到画布、用作参考图、删除或打开所在文件夹。空白画布可选“标准 / 高清”尺寸。",
-          "生图：6–8 GB 显存的显卡解码时占用的显存更少，速度更快。显存放得下整个模型的显卡，权重直接加载到显卡，不再在内存里留一份副本，加载后内存占用从约 15 GB 降到约 2 GB。",
-          "提交问题：生成、剪辑与导出、环境与模型、生图、智能体连接、作品库、提示词优化、分享、更新和启动器里，出现错误或失败提示的地方旁边都有“提交问题”按钮，点击后带上情况打开问题反馈。",
-          "AI 全自动：对话删不掉时会说明原因，并提供“停止并删除”；其他失败也会提示，并带“提交问题”按钮。",
-          "白模：现成场景只保留“橘猫跳上书架”，点击直接开始。白模没做成时会说明原因和下一步，渲染中页面显示进度。问白模进度时会回答进度，不再当成新要求。",
-          "人物设定图：背面图里头和身体一起转向背后。",
-          "Mac：支持分段生成长视频。",
-          "启动器与更新：Windows 版在中国大陆更新更快。GitHub 慢时，启动器可以从国内镜像下载更新，镜像上的每个文件都先按发布签名校验。“确认安装”页适配窄窗口：侧栏收成图标，按钮始终可见。",
-          "工作流：旧版本存的工作流可以直接运行。旧文件里后加的选项为空或不合法时，改回默认值。",
-          "视频生成：“精细”档生成更快。8 GB 显存的显卡上，以前因显存差一点而被拒绝的 1920×1088 视频，现在可以生成。改动视频参考的前期步数设置后，会生成新的结果，不再沿用之前的结果。",
-          "LoRA：为 Wan 2.x 训练的 LoRA 选进 int8 模型时，会说明这是给 Wan 2.x 训练的 LoRA，不再只说无法使用。",
-          "Linux：内存较小的电脑接着再生成一次时，不再在采样快结束时内存不足。6 GB 显存的显卡选“极致”时，不再要等好几个小时。"
-        ]
-      }
     }
   ]
 }

From a2a663442947fe3630b52e2d1752a3bcee602d7e Mon Sep 17 00:00:00 2001
From: Bowen Xue <kbrask@ustc.edu>
Date: Thu, 29 Oct 2026 00:57:26 +0000
Subject: [PATCH 52/52] Release notes for 0.4.24: use a plain ellipsis in the
 English notes

---
 freevideo_engine/release_notes.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/freevideo_engine/release_notes.json b/freevideo_engine/release_notes.json
index 4f421f4f..99621093 100644
--- a/freevideo_engine/release_notes.json
+++ b/freevideo_engine/release_notes.json
@@ -12,7 +12,7 @@
       "Generation: after other ComfyUI workflows have run, the video memory they hold is released before a picture or a prompt rewrite starts, without restarting ComfyUI. A missing text encoder model is detected before encoding starts, with repair guidance; if a model repair fails while downloading, the original file is restored. When generation cannot start because the installation is in use, the failure details name the programs holding it open. When the GPU checks before switching to int8 fail, the failure card lists the reason for each check.",
       "Memory and speed: on graphics cards that cannot hold the whole decoder, decoding no longer prepares the same layers again for every video segment or every new request while memory allows, with identical output. On most Windows graphics cards with 8 to 12 GB of video memory, the first pass of two-pass videos between 10 and 12 seconds without LoRA computes 8 attention heads at a time instead of 4, as shorter videos already did. On Windows, when other programs free video memory during a generation, the next pass and decoding use the recovered memory.",
       "Install: setup no longer stops with a dependency mismatch after the installation folder was moved, copied or restored, and a dependency folder too deep for Windows is reported as a long path. Text encoder and tokenizer files deleted after installation are restored from the local copy before encoding and during repair, without downloading.",
-      "Phone access: the phone page works when local network access is switched on in the launcher, and no longer shows \"Connection lost. Reconnecting…\" with no content.",
+      "Phone access: the phone page works when local network access is switched on in the launcher, and no longer shows \"Connection lost. Reconnecting...\" with no content.",
       "Agents: the install-skill command installs the FreeVideo skill for an Agent, also from deeply nested Windows folders. The tool list an Agent receives is shorter: common tools are listed in full and the others are opened through a help tool.",
       "Diagnostic reports: when ComfyUI restarts during a generation, the report of that run is marked as interrupted instead of running, and a long video keeps the report of the part that was interrupted."
     ]