Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
release(v4.0.0): LTX-2.5 is the generation Phosphene renders with
mrbizarro280dd0ebcb48
diff --git a/.gitignore b/.gitignoreindex 5b92ca5..9ba8c04 100644--- a/.gitignore+++ b/.gitignore@@ -52,6 +52,16 @@ mlx_models/# =============================================================================# Third-party — installed alongside, not part of this repo# =============================================================================+# A TRAILING SLASH MATCHES DIRECTORIES ONLY, NEVER SYMLINKS. That is not+# theoretical here: Pinokio's `fs.link` step creates mlx_models / mlx_outputs /+# panel_uploads / state as symlinks into its virtual drive, which is exactly why+# every one of those carries a bare form as well as a slashed one below. The+# vendored trees had only the slashed form, and it bit during the v3.8.0 release+# build — a symlinked `ltx-2-mlx` pointing at the real install got STAGED into+# the release commit and had to be caught by hand before the push. A vendored+# checkout is ours to ignore whether it arrived as a real directory, a symlink,+# or an fs.link mapping, so each entry is spelled both ways.+ltx-2-mlxltx-2-mlx/# The optional Hailuo H3 pack: install_h3.js clones minimax-h3-mlx INTO the# app directory (it has to — the panel resolves the runner relative to ROOT,@@ -62,7 +72,9 @@ ltx-2-mlx/# check — every H3 user lost the update pill (#52, @Morac2). Anchored with a# leading slash: only the clone at the repo root, never a same-named dir# nested inside a vendored tree.+/minimax-h3-mlx/minimax-h3-mlx/+.venv.venv/# =============================================================================@@ -75,7 +87,11 @@ ltx-2-mlx/# Both were only ever invisible to the maintainer because his two clones carry# them in .git/info/exclude — users never had that, so they hit the same# permanently-dirty status as the H3 clone above (#52).+# Both spelled twice for the symlink reason documented in the third-party+# section above — a symlinked `cache` or `logs` is the #52 shape all over again.+/cache/cache/+/logs/logs/# =============================================================================@@ -117,3 +133,15 @@ __pycache__/# Claude Preview tool config (per-machine, not Phosphene).claude/++# =============================================================================+# Campaign notes — private by convention, and now by rule+# =============================================================================+# Design specs, validation reports and release planning live OUTSIDE this repo,+# and agents write those notes constantly during a campaign. Nothing has+# leaked — `git ls-files` has never carried a notes/ path+# — but the sibling `state/` is ignored and this was not, so the only thing+# standing between a stray `notes/` write inside the repo and a public commit+# was that nobody made one. Same defence-in-depth reasoning as the stats file+# above: cheap rule, permanent class of mistake.+notes/diff --git a/CLAUDE.md b/CLAUDE.mdindex f7c4753..38acab1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -23,9 +23,9 @@ the dev codename that became v3.0.0). The `VERSION` file should readcomments still use the `Y1.NNN` counter (Y1.001 → Y1.039) — historical;do not introduce new `Y` labels.-The authoritative current engineering snapshot is-`~/AI/projects/phosphene/notes/DEEP_REVIEW_2026-05.md` (verified risk-register + 5-phase stabilization plan). The `## 2.0` capability list+The authoritative current engineering snapshot is `docs/STATE.md`+(current capabilities, version history, known bugs). The `## 2.0`+capability listbelow is retained as historical baseline — everything in it shipped; thev3.0 additions (Characters, voice LoRA, Image Studio, A2V, Train tab,capability tiers) are now baseline too.@@ -197,8 +197,8 @@ These are not arbitrary — every pin is a paid lesson:| `mlx==0.31.1` | mlx 0.31.2 introduced a numerical regression that attenuates LTX 2.3 vocoder output by ~22 dB. Verified: same model + same prompt + same seed → -42 dB peak on 0.31.2 vs -9 dB peak on 0.31.1. || `mlx-lm==0.31.1` `mlx-metal==0.31.1` | Same release line, kept consistent with mlx. || `huggingface-hub>=1.0` | `hf` CLI replaced `huggingface-cli`; older Pinokio bundles ship < 1.0. |-| `ltx-2-mlx` PINNED to the FORK BUILD **`871694d`** (`mrbizarro/ltx-2-mlx` `feat/ltx-2.5` = v0.14.19 `1192051` + the LTX-2.5 port) | install.js + update.js add a `fork` remote, `git fetch fork feat/ltx-2.5` and `git checkout 871694d` (**a SHA, not a tag** — upstream has no 2.5 branch; if dgrauet ports 2.5 we drop ours and go back to a tag). The packages report **`0.14.19+ltx25.1`**; `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py must equal that string or every render logs VERSION SKEW — move the two together. This pin is what lets **LTX-2.5 render through the panel** — but 2.5 is NOT registered in this release and **LTX-2.3 is the only generation**, because the 2.5 weight packs are not publicly downloadable yet. Every 2.5 flag in the vendored port defaults to its 2.3 value, so an unversioned checkpoint builds exactly what it built before. The base tag v0.14.19 landed 2026-08-11 (a catch-up from v0.14.8, itself a 2026-06-01 catch-up from v0.14.0). **STAY PINNED** — this is NOT "main HEAD", and not upstream's tip either. The v0.14.8 bump had pulled dgrauet's native `_pre_denoise_flush` (the Metal-watchdog fix for the I2V "mosaic" on memory-pressured Macs, #17), budget-aware VAE decode tiling and first-class `frame_rate`, which cut us from 7 runtime patches to 1 (codec-only). The v0.14.19 bump keeps that shape and adds: checkpoint-read `av_ca_timestep_scale_multiplier` (0.14.11 — **audio/dialogue weighting changes on every render**, toward upstream parity, plus `LTXModelConfig.from_checkpoint_dir()`), `frame_rate` forwarded at the A2V/lipdub call sites and no more shortest-stream mux truncation (0.14.15), quantized transformers at any `group_size` (0.14.16), and GPU-watchdog explanation + DiT-freed-before-VAE-decode + a Gemma cache-limit fix (0.14.19). **No model re-download**: 0.14.13+ prefers a versioned `transformer-distilled-*.safetensors` and falls back to the unversioned name, and update.js trims the `-1.1` variants, so file resolution is identical to v0.14.8. Bumping the pin further is a deliberate, tested operation — read the release notes, bump `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py, smoke-test the matrix on dev, then bump BOTH install.js and update.js in one commit. The historic `dcd639e (0.1.0)` detour broke the Extend `cfg_scale` API; do not revisit. |-| `hatchling<1.32` (build-time only, `pip-build-constraints.txt`) | Not a runtime dep — the **wheel build backend** for the three vendored `ltx-*` packages. All three declare `readme = "../../README.md"`, which hatchling 1.32.0 turned into a hard error, so both installer paths (uv in install.js, pip in update.js) died at `metadata-generation-failed` on *every* pinned tag from the day 1.32 shipped. Wired as `--build-constraints` (uv) / `PIP_CONSTRAINT=` (pip). Remove only when a pinned upstream tag stops pointing `readme` outside the package dir. |+| `ltx-2-mlx` PINNED to the FORK TAG **`v0.14.19+ltx25.3`** (`mrbizarro/ltx-2-mlx`, commit `7cada57` on `release/ltx25.3` = v0.14.19 `1192051` + the LTX-2.5 port + the schedule/sampler/live-preview work) | **The pin is a TAG and it lives in `scripts/pinokio/ltx_checkout.sh`**, which is the ONE checkout implementation both lanes call (install.js dispatches it; scripts/post_update.sh calls it). It was a bare SHA through v3.8.3 and was reachable only by luck — a force-push would have stranded every install with an un-fetchable pin and a dead Update button. `check_ltx_pin.js` is the gate. The packages report **`0.14.19+ltx25.3`**; `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py must equal that string or every render logs VERSION SKEW — move the two together. This pin is what lets **LTX-2.5 render through the panel**, and on **dev/beta** 2.5 is the registry DEFAULT (2.3 stays installed, selectable via `LTX_MODEL_VERSION=ltx23`). **v3.8.x did NOT register `ltx25` at all** and shipped 2.3 as the only generation, because the 2.5 weight packs were not publicly downloadable when it was cut — a fresh install would have booted into a generation it could not fetch. They are published now, and **v4.0.0 closes that divergence**: 2.5 is the registered default everywhere. If you ever need to curate a release back to a single generation, it is one `MODEL_VERSIONS` dict plus its three `required_files.json` rows (watch the `kind: "base"` trap: any base row is mandatory for an install to read complete, in the panel *and* in `pinokio.js`). The **pin diverged for the same reason**: v3.8.x shipped `871694d` / `0.14.19+ltx25.1`, one commit behind, because `e6be9d6` (the 2.5 sampler + stage-2 schedule, below) had no 2.3 regression evidence behind it at cut time. It does now — a 2.3 sha256-identity pair across the change — so the next release should choose the pin deliberately rather than inherit either. The base tag v0.14.19 landed 2026-08-11 (a catch-up from v0.14.8, itself a 2026-06-01 catch-up from v0.14.0). **STAY PINNED** — this is NOT "main HEAD", and not upstream's tip either. The v0.14.8 bump had pulled dgrauet's native `_pre_denoise_flush` (the Metal-watchdog fix for the I2V "mosaic" on memory-pressured Macs, #17), budget-aware VAE decode tiling and first-class `frame_rate`, which cut us from 7 runtime patches to 1 (codec-only). The v0.14.19 bump keeps that shape and adds: checkpoint-read `av_ca_timestep_scale_multiplier` (0.14.11 — **audio/dialogue weighting changes on every render**, toward upstream parity, plus `LTXModelConfig.from_checkpoint_dir()`), `frame_rate` forwarded at the A2V/lipdub call sites and no more shortest-stream mux truncation (0.14.15), quantized transformers at any `group_size` (0.14.16), and GPU-watchdog explanation + DiT-freed-before-VAE-decode + a Gemma cache-limit fix (0.14.19). **The `+ltx25.2` bump (2026-08-12) is the first one that changes what a 2.5 render computes**, and only a 2.5 render: (a) the **euler-ancestral sampler is finally REACHED** — it had been implemented with 48 tests and zero callers, so every prior 2.5 render silently used the 2.3 Euler step, against upstream's own `ANCESTRAL_SAMPLER_SINCE_VERSION = (2, 5)` and all three official ComfyUI 2.5 templates; keyframe/flf2v deliberately stays on Euler because the flf2v template pins eta to 0. (b) **stage 2's first sigma is now the vendor's 0.85**, read from `video_ltx2_5_t2v.json` node 395, where we had been using 2.3's 0.909375 — a refine pass starting at the wrong noise level. Both are version-keyed off the checkpoint's own `model_version`, and 2.3 output is proven **sha256-identical** before and after. **No model re-download**: 0.14.13+ prefers a versioned `transformer-distilled-*.safetensors` and falls back to the unversioned name, and update.js trims the `-1.1` variants, so file resolution is identical to v0.14.8. Bumping the pin further is a deliberate, tested operation — read the release notes, bump `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py, smoke-test the matrix on dev, then bump BOTH install.js and update.js in one commit. The historic `dcd639e (0.1.0)` detour broke the Extend `cfg_scale` API; do not revisit. |+| `hatchling<1.32` (build-time only, `pip-build-constraints.txt`) | Not a runtime dep — the **wheel build backend** for the three vendored `ltx-*` packages. All three declare `readme = "../../README.md"`, which hatchling 1.32.0 turned into a hard error, so both installer paths died at `metadata-generation-failed` on *every* pinned tag from the day 1.32 shipped. **Both are now `uv pip install --build-constraints ../pip-build-constraints.txt`** — install.js always was, update.js as of the v3.8.0 port-back. **NOT `PIP_CONSTRAINT=`**: modern pip spawns its build-dependency sub-install with `_PIP_IN_BUILD_IGNORE_CONSTRAINTS=1` and drops the env constraint on purpose, so that spelling silently resolved hatchling 1.32.0 and failed anyway (proven on pip 26.1/26.2.1, relative and absolute paths). pip's `--build-constraint` flag would work but does not exist on older pips, and Update runs on venvs seeded years apart. Remove only when a pinned upstream tag stops pointing `readme` outside the package dir. |When changing a version, document the test that proved the new pin is OK.The v0.14.19 pin was proved by: 607 passed / 22 skipped on the vendored@@ -445,6 +445,51 @@ that already pulled 0.31.2 can recover by clicking Update.click Stop + Start in Pinokio, or `pkill -f mlx_ltx_panel.py`and click Start.+### The GPU lock — BOTH of them, and staleness is a TIMESTAMP++This machine runs several agents at once and one 40 GiB render. Two of+them do not fit. Every render, benchmark or experiment that touches the+GPU takes **both** locks for its whole duration and releases both after:++| lock | shape | who introduced it |+|---|---|---|+| `~/AI/projects/hailuo-mlx/.gpu_lock` | a **directory** (`mkdir` = atomic acquire, `rmdir` = release) | the H3 tree |+| `/tmp/phosphene_gpu.lock` | a **file** (`set -o noclobber` + `>` = atomic create-or-fail) | the Phosphene agents |++**A lock only one party reads is not a lock.** Both exist, both are+live, and an agent that honours one of them will happily start a second+render next to an agent honouring the other. That is not hypothetical:+on 2026-08-05 two ~40 GiB jobs overlapped and the OS killed the panel+*and* its child mid-test.++Acquire in that order (directory first, then file; release in reverse),+so two agents racing cannot each hold one and deadlock. `gpu_lock.sh` in+the LTX-2.5 port working tree is the reference implementation.++**Staleness is decided by the lock's TIMESTAMP, never by a PID.**+Write the owner string into the file for humans to read, but do not+parse a pid out of it and do not ask whether that pid is alive:++- pids are recycled, so "that pid exists" is not "that render is+ running" — the crash-reap work already learned this the hard way and+ matches on the process **cmdline**, not the number alone;+- the holder may be a *different container of work* than the process+ that wrote the file (a driver script that spawns the render), so the+ writer can legitimately be gone while the GPU is still busy;+- and a pid check invites the failure it is meant to prevent: an agent+ that concludes "stale" and steals the lock starts the second render.++Use an age threshold longer than any render this repo can produce+(the longest measured is a 15 s H3 chain at ~27 min, so **60 minutes**+is the floor), announce that you are overriding, and say so in the+session record. If in doubt, **wait** — a blocked agent costs minutes,+a collided render costs the machine.++**Never touch `:8199`.** It is the owner's daemon. Do not kill it, do+not restart it, do not queue to it. Test instances go on **:8240+**+with isolated `LTX_STATE_DIR` / `LTX_OUTPUT_DIR` / `LTX_UPLOADS_DIR`,+and are killed by the PID you saved when you started them.+### Disk consolidation- Old `~/Documents/Codex/...` dev folder was deleted.Don't recreate. The Pinokio install is canonical.@@ -455,6 +500,41 @@ that already pulled 0.31.2 can recover by clicking Update.## 8. Test workflow+### The gates — run these before pushing anything they cover++Each exists because the thing it guards broke in the field at least once,+and each is cheap enough that "I forgot" is not a reason.++| gate | run it when you touch | what it refuses |+|---|---|---|+| `node scripts/check_pinokio_scripts.js` | any launcher `.js` | a single dispatch over 500 chars — Pinokio 8.0.x wedges at 764 and at 1,417 |+| `node scripts/check_ltx_pin.js` | the vendored pin, `update.js`, `install.js`, `_LTX_EXPECTED_VERSION` | a pin that is a bare SHA, a pin that disagrees with the version the runtime reports, a second checkout implementation, or anything in `update.js` that belongs post-pull |+| `node scripts/check_post_update.js` | `scripts/post_update.sh` | the codec patch running before the reinstall or after anything optional, and a load-bearing step that cannot fail the Update |+| `./ltx-2-mlx/env/bin/python3.11 scripts/assert_registry.py` | `MODEL_VERSIONS`, `required_files.json`, pack paths, the text-encoder seam, deep-verify sources | a generation that resolves another generation's weights or text encoder — the two bugs that shipped silently on 2026-08-12, neither of which raised anything |+| `./ltx-2-mlx/env/bin/python3.11 scripts/assert_schedules.py` | `make_job`, any `*_steps` default, a new render mode, a pin move | a job dict that asks a checkpoint to PAD a fixed sigma table — the class that let Colorize/Restore/Ingredients/Control/HDR burn 218 s and die on "cannot thin a 9-point schedule (8 steps) up to 10 steps" |+| `./ltx-2-mlx/env/bin/python3.11 patch_ltx_codec.py` | the vendored pin, any package reinstall | a bypassed codec patch — v3.8.1 shipped silent 4:2:0 for a whole release because this ran eleven steps too late and never executed |++**The codec rule, stated correctly.** It has been passed around as *"`grep -rn+libx264` in the vendored tree must return exactly one hit"*, and read literally+that is false — repo-wide the grep is 8 (the trainer's `video_utils` and+`slice_clips`, `media_io`, `video_vae`). What the rule actually asserts:++> `grep -rn --include="*.py" libx264 ltx-2-mlx/packages/ltx-core-mlx` returns+> **exactly one** hit — the UNPATCHED source at `video_vae.py:487` — while the+> installed copy in `ltx-2-mlx/env/lib/python3.11/site-packages/` is patched.+> `patch_ltx_codec.py` resolves its target through the INTERPRETER and verifies+> its own work, so its own exit code is the real gate; the grep is the+> human-readable cross-check that the source tree was left clean.++A second hit in `ltx-core-mlx` means the patch was applied to the git-tracked+source instead of site-packages — the editable-install failure that made every+v3.8.0 pin move fail.++`assert_registry.py` also **pins known defects**: it asserts the current+*wrong* value, prints a `DEFECT` banner every run, and turns RED when+somebody fixes it, so a fix cannot land without the marker being removed.+A pinned defect is not a pass — read the banners.+For HTML/UI/JS changes:1. Edit `mlx_ltx_panel.py`2. Restart panel (Pinokio Stop + Start, OR `pkill -f mlx_ltx_panel.py`diff --git a/README.md b/README.mdindex c527a9c..6abbce5 100644--- a/README.md+++ b/README.md@@ -1,22 +1,3 @@-## About this fork--This fork adds audio-to-video mode for low memory pipeline.--Adds A2V Distilled Pipeline (a2vid_distilled.py) in phosphene root for-Q4-distilled audio-to-video generation. No ltx-2-mlx modifications-required — imports from stock ltx-pipelines-mlx package.--Key differences from the standard A2V path:-- a2vid_distilled.py lives in phosphene root (not inside ltx-2-mlx)-- mlx_warm_helper.py imports from the local a2vid_distilled module-- Distilled path (generate_a2v_distilled) passes audio_conditioning_scale- (built into a2vid_distilled.py)-- Non-distilled path (generate_a2v) omits audio_conditioning_scale- (upstream A2VidPipelineTwoStage does not accept it)-- patch_ltx_codec.py is unchanged (codec patch only)---<p align="center"><img src="assets/phosphene_banner.png" alt="Phosphene" width="100%"></p>@@ -32,11 +13,11 @@ Key differences from the standard A2V path:</p>-> **Current release: v3.8.3 — the fix for an install that hung Pinokio before it started.** On Pinokio 8.0.x a fresh install could freeze at 100% CPU right after `git rev-parse --short HEAD`, with no child process and no error, until you force-quit. v3.6.2 shortened the shell lines for this and it was not enough: what Pinokio writes to its shell is the whole joined step, and the LTX venv step handed it 1,417 characters in one go. Those payloads now live in `scripts/pinokio/*.sh` and each step dispatches one short line, with a gate that measures what is actually dispatched. Also: installing Hailuo H3 no longer tells you to look for an "Engine row" in the Video tab — the engine switcher is in the top right of the header. v3.8.2 fixed an update that silently skipped the video-encoder patch and encoded every render 4:2:0; v3.8.1 fixed an Update that could abort at the video-engine pin and never be retried; v3.8.0 brought Storyboard plus the fix for the install failure that had been breaking every fresh install since hatchling 1.32.0 shipped. Full notes on the [releases page](https://github.com/mrbizarro/phosphene/releases).+> **Current release: v4.0.0.** LTX-2.5 is the engine Phosphene renders with — the first native Mac build of it, and the generation a fresh install now downloads. A live preview of the frame being made, a Stop early that saves the wait, trained characters in about two and a half minutes, and the five control modes fixed. Full notes on the [releases page](https://github.com/mrbizarro/phosphene/releases).## Overview-Phosphene is a local generative-media panel for Apple Silicon. It runs [LTX-Video 2.3](https://github.com/Lightricks/LTX-Video) (MLX port) for joint audio-and-video synthesis, [Qwen-Image-Edit-2509](https://huggingface.co/Qwen/Qwen-Image-Edit-2509) (with a Lightning 4-step fast tier) for stills, and ships an in-panel LoRA training pipeline for character identity (face + optional voice from a single dataset). Everything runs on-device: no cloud, no API keys, and no prompt, image, video or filename ever leaves your Mac. It does send anonymous usage counts (version, hardware class, render stats) — every field is listed in [docs/ANALYTICS.md](docs/ANALYTICS.md), and one click in Settings turns it off.+Phosphene is a local generative-media panel for Apple Silicon. It runs [LTX-Video 2.5](https://github.com/Lightricks/LTX-Video) (MLX port) for joint audio-and-video synthesis, [Qwen-Image-Edit-2509](https://huggingface.co/Qwen/Qwen-Image-Edit-2509) (with a Lightning 4-step fast tier) for stills, and ships an in-panel LoRA training pipeline for character identity (face + optional voice from a single dataset). Everything runs on-device: no cloud, no API keys, and no prompt, image, video or filename ever leaves your Mac. It does send anonymous usage counts (version, hardware class, render stats) — every field is listed in [docs/ANALYTICS.md](docs/ANALYTICS.md), and one click in Settings turns it off.3.0 introduces in-panel character training (face + voice LoRA from one dataset), the Audio-to-Video workflow, the Image Studio tab, hardware capability tiering, and an agentic prompt enhancer driven by the same local Gemma 3 12B used for auto-captioning.@@ -77,7 +58,7 @@ New workflow tab in 3.0. WAV or MP3 in, MP4 out — the audio drives motion in t### LoRAs-Drop `.safetensors` into `mlx_models/loras/` for immediate use, or browse and install LTX 2.3 LoRAs from CivitAI inside the panel (per-row rename, download, companion-aware delete). Character bundles live alongside style LoRAs and are filtered out of the regular picker so they don't show up twice.+Drop `.safetensors` into `mlx_models/loras/` for immediate use, or browse and install LTX LoRAs from CivitAI inside the panel (per-row rename, download, companion-aware delete). Character bundles live alongside style LoRAs and are filtered out of the regular picker so they don't show up twice.### HTTP API@@ -104,13 +85,15 @@ Apple Silicon only. MLX is Apple-only by design.| RAM | Tier | What runs ||---|---|---|-| Under 48 GB | Compact (Q4 surface) | Text and image-to-video at smaller sizes. Image tab works. Character, FFLF, Extend, and HQ are hidden. They need Q8. |+| Under 48 GB | Compact (Q4 surface) | Text and image-to-video at smaller sizes. Image tab works. FFLF, Extend and High are hidden — they need more memory than this tier has. || 48 to 79 GB | Comfortable (Q8 surface) | The canonical tier, built on M4 Max 64 GB. Everything works. FFLF and Extend capped at 768 px long side. || 80 to 119 GB | Roomy | Most modes at full size. FFLF and Extend up to 1024 px. || 120 GB+ | Studio | No size limits. |Working-memory footprint is non-negotiable: standard 1280×704 generation peaks at roughly 22 GiB resident, and HQ with the Q8 dev transformer at roughly 38 GiB. Tier is detected once at boot from RAM and exposed to the UI via `body[data-cap-tier="q4|q8"]`. Set `LTX_FORCE_CAP_TIER=q4` to preview the Compact surface from a higher-tier machine.+**RAM is not the only gate, and on LTX-2.5 it is not the interesting one.** The table above answers "what can this Mac's memory serve". Whether trained **characters** render faithfully, and whether the **High** tier exists at all, are questions about which weight packs are on disk — a 64 GB Mac holding only the base pack is Comfortable-tier and still cannot do either. The panel tracks that separately (`body[data-q8-pack]`), and every surface that offers a download says which pack and how big.+## Install### Via Pinokio (recommended)@@ -120,9 +103,13 @@ Working-memory footprint is non-negotiable: standard 1280×704 generation peaks3. Click **Install**.4. Click **Start** -> **Open Panel** -> http://127.0.0.1:8198.-Pinokio handles the hardware gate, the upstream `dgrauet/ltx-2-mlx` clone, the uv-managed Python 3.11 venv, the runtime patches, and the filtered model download (~28 GB: Q4 plus the Gemma encoder).+Pinokio handles the hardware gate, the vendored `ltx-2-mlx` clone at its pinned tag, the uv-managed Python 3.11 venv, the runtime patches, and the model download.++**What a fresh install fetches (~37 GB):** LTX-2.5's engine (20.74 GB) and its Gemma 4 text encoder (6.73 GB) — the generation the panel renders with — plus the 22 MB live-preview decoder; Gemma 3 (~6 GB), which is what **Enhance** and the **Storyboard planner** run on; and three control LoRAs (~4 GB) for the **Colorize / Restore**, **Ingredients** and **Control** modes. Every step is resumable. (**HDR** uses a fourth, gated LoRA — add a Hugging Face token in Settings and the panel fetches it on first use.)-For the Q8 HQ tier (required for Character, FFLF, Extend), click **Download Q8** in the panel sidebar after first launch. About 37 GB, one time.+**LTX-2.3 is not downloaded.** It is needed only to *train* a character — the trainer runs against 2.3, not 2.5 — so the panel offers it (~20 GB, plus the ~21 GB full-precision dev transformer) the moment you open the **Train Character** tab, and in **Settings → Models** any time. Everything else, including all four control-LoRA modes, renders on LTX-2.5.++For trained characters and voices, install the **LTX-2.5 Q8 weights** (30.02 GB) from **Settings → Models**. The **High** tier additionally needs the **High add-on** (29.50 GB), which installs into the same folder.If you have a Hugging Face token, paste it under **Settings** in the panel. Downloads run roughly 10x faster, and the same token unlocks the gated LoRAs (HDR and Lightricks Control).@@ -135,8 +122,8 @@ cd phosphenegit clone https://github.com/dgrauet/ltx-2-mlx.git ltx-2-mlxcd ltx-2-mlxgit remote add fork https://github.com/mrbizarro/ltx-2-mlx.git-git fetch fork feat/ltx-2.5-git checkout 871694ddaa09c1598d663a49005a2f91ae6b4ed2+git fetch fork +refs/tags/v0.14.19+ltx25.3:refs/tags/v0.14.19+ltx25.3+git checkout v0.14.19+ltx25.3cd ..# 2. Create the Python 3.11 venv inside ltx-2-mlx (uv-managed).@@ -165,11 +152,16 @@ cd ..# 4. Apply the runtime patches (idempotent, fail loud on upstream drift)../ltx-2-mlx/env/bin/python3.11 patch_ltx_codec.py-# 5. Download the Q4 LTX weights + the Gemma 3 4-bit encoder (~28 GB total).-HF_HUB_ENABLE_HF_TRANSFER=1 ./ltx-2-mlx/env/bin/hf download \- dgrauet/ltx-2.3-mlx-q4 --local-dir mlx_models/ltx-2.3-mlx-q4-HF_HUB_ENABLE_HF_TRANSFER=1 ./ltx-2-mlx/env/bin/hf download \- mlx-community/gemma-3-12b-it-4bit --local-dir mlx_models/gemma-3-12b-it-4bit+# 5. Download LTX-2.5 — the base install: the engine (20.74 GB), its Gemma 4+# text encoder (6.73 GB) and the 22 MB live-preview decoder. 27.5 GB total,+# resumable and sha256-verified. NOT `hf download`: these are our own+# quantisation of a gated upstream, mirrored as GitHub release assets.+./ltx-2-mlx/env/bin/python3.11 scripts/fetch_pack_release.py \+ --repo-key q4_25 --repo-key gemma4_25 --repo-key tae++# 5b. (Optional) The Q8 weights (30.02 GB) — what trained characters and+# voices need. The High tier additionally needs the High add-on (29.50 GB).+./ltx-2-mlx/env/bin/python3.11 scripts/fetch_pack_release.py --repo-key q8_25# 6. (Optional) Image tab — install mflux + apply the FBCache patch../ltx-2-mlx/env/bin/pip install 'mflux==0.17.5'@@ -185,7 +177,7 @@ HF_HUB_ENABLE_HF_TRANSFER=1 ./ltx-2-mlx/env/bin/hf download \./ltx-2-mlx/env/bin/python3.11 mlx_ltx_panel.py```-About the version pins: `mlx 0.31.2` attenuates the LTX vocoder by 22 dB. Stay on 0.31.1. `ltx-2-mlx` is pinned to the fork build `871694d` (`mrbizarro/ltx-2-mlx`, branch `feat/ltx-2.5`) — v0.14.19 plus the LTX-2.5 port, because upstream has no 2.5 branch. We track a known-good commit, never upstream `main`; the installed packages report `0.14.19+ltx25.1` and `_LTX_EXPECTED_VERSION` must match that string exactly. `mflux 0.17.5` is the version `patch_mflux_fbcache.py` is line-targeted against. `hatchling<1.32` (in `pip-build-constraints.txt`) is a *build-time* pin: 1.32 rejects the `readme = "../../README.md"` that all three upstream packages declare, which fails the wheel build on every tag.+About the version pins: `mlx 0.31.2` attenuates the LTX vocoder by 22 dB. Stay on 0.31.1. `ltx-2-mlx` is pinned to the fork **tag** `v0.14.19+ltx25.3` (`mrbizarro/ltx-2-mlx`, commit `7cada57`) — v0.14.19 plus the LTX-2.5 port, because upstream has no 2.5 branch. A tag, not a bare SHA: a force-push upstream would strand every install with an un-fetchable pin and a dead Update button. The installed packages report `0.14.19+ltx25.3` and `_LTX_EXPECTED_VERSION` must match that string exactly, or every render logs a VERSION SKEW warning. `scripts/pinokio/ltx_checkout.sh` holds the pin and `node scripts/check_ltx_pin.js` enforces the agreement. `mflux 0.17.5` is the version `patch_mflux_fbcache.py` is line-targeted against. `hatchling<1.32` (in `pip-build-constraints.txt`) is a *build-time* pin: 1.32 rejects the `readme = "../../README.md"` that all three upstream packages declare, which fails the wheel build on every tag.## Interface@@ -245,11 +237,11 @@ Behavioral changes worth noting in 3.0:## License and credits-Panel: MIT, see [LICENSE](LICENSE). LTX-Video 2.3 weights: Lightricks' license. MLX: Apache 2.0. Gemma 3 12B: Google's terms. PiperSR: AGPL-3.0.+Panel: MIT, see [LICENSE](LICENSE). LTX-Video 2.5 weights: Lightricks' license. MLX: Apache 2.0. Gemma 3 12B: Google's terms. PiperSR: AGPL-3.0.Phosphene depends on the following projects:-- [Lightricks](https://github.com/Lightricks/LTX-Video) — LTX 2.3 and the joint audio + video architecture+- [Lightricks](https://github.com/Lightricks/LTX-Video) — LTX 2.5 and the joint audio + video architecture- [@dgrauet](https://github.com/dgrauet/ltx-2-mlx) — MLX port of LTX-Video; the foundation everything else builds on- [Apple ML team](https://github.com/ml-explore/mlx) — MLX- [HiDream-ai](https://huggingface.co/HiDream-ai/HiDream-O1-Image-Dev) — HiDream-O1 weights and reference implementationdiff --git a/VERSION b/VERSIONindex 269aa9c..fcdb2e1 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-3.8.3+4.0.0diff --git a/docs/ANALYTICS.md b/docs/ANALYTICS.mdindex 37bc813..0506342 100644--- a/docs/ANALYTICS.md+++ b/docs/ANALYTICS.md@@ -159,7 +159,8 @@ Once per panel start.| `os_version` | string | `"26.4"` | macOS major.minor. Patch level deliberately dropped || `chip_family` | string | `"M4 Max"` | Parsed from the CPU brand string. A hardware *class*, identical across every machine of that model. `"unknown"` or `"non-apple-silicon"` when unparseable || `ram_gb` | int | `64` | Unified memory, rounded to whole GB |-| `cap_tier` | string | `"q8"` | `q4` or `q8` — which capability surface the UI is showing |+| `cap_tier` | string | `"q8"` | `q4` or `q8` — which capability surface the UI is showing. A statement about this Mac's RAM folded down to what the generation can serve, NOT about which weights are on disk |+| `model_version` | string | `"ltx25"` | Which LTX generation this install serves (`ltx23` / `ltx25`). Added in v4.0 as a NEW field rather than by redefining `cap_tier`, so the existing capability series stays comparable across the 2.5 cutover || `packs` | object | `{"h3":true,"sharp":false,"q8":true,"qwen":false}` | Booleans only: is each optional pack installed || `h3_chain_supported` | bool | `false` | Whether the installed H3 runner supports window chaining (10 s / 15 s tiers) |diff --git a/docs/API.md b/docs/API.mdindex 22cd10c..8188325 100644--- a/docs/API.md+++ b/docs/API.md@@ -32,7 +32,9 @@ Add a job to the panel's queue. Returns immediately; the helper renders it async| `negative_prompt` | string | Optional. Usually empty. || `width`, `height` | int | Both divisible by 32. || `frames` | int | Must satisfy `frames % 8 == 1`. 121 = 5s, 169 = 7s, 241 = 10s. |-| `frame_rate` | float | Default `24`. LTX-2.3 was trained at 24 fps; deviation degrades quality. |+| `frame_rate` | float | Default `24`. LTX is trained at 24 fps; deviation degrades quality. |+| `character_strength` | float | Default `1.0`. The FACE LoRA's strength, 0–2. |+| `character_voice_strength` | float | Default `1.0`. The VOICE LoRA's strength, 0–2, applied to `<trigger>.audio.safetensors` only. It is a separate number from the face because the face file's audio-branch deltas are noise and are louder than the voice file's signal at equal strength — so running the voice hotter (1.2 is parity, 1.4 is the first setting with real headroom) is what makes it win. The default stays at the graded `1.0`; the hotter rungs are yours to reach for. || `seed` | int or `-1` | `-1` = random. || `quality` | `quick` \| `balanced` \| `standard` \| `high` | **For character LoRA work, use `high`.** `balanced` silently routes >121f clips to the Q4 distilled transformer where current LoRAs lose identity. || `stage1_steps`, `stage2_steps` | int | HQ two-stage pipeline. Validated defaults: `10` / `3`. |@@ -146,7 +148,34 @@ Field semantics:- `history` — completed/failed jobs. Each entry has `status`, `elapsed_sec`, `output_path`, `raw_path` (native pre-upscale), `error`.- `log` — rolling buffer of helper stdout lines (last ~50 jobs).-**Polling loop:** GET `/status` every 15–30s. A job is terminal when its `status` is one of `done`, `failed`, `cancelled`, `error`. Until then it's `queued` or `running`.+**Polling loop:** GET `/status` every 15–30s. A job is terminal when its `status` is one of `done`, `failed`, `cancelled`, `stopped`, `error`. Until then it's `queued` or `running`.++`stopped` means the user stopped the render on purpose (see `POST /stop?mode=early`). It is **not** a failure: nothing was saved because the clip was never finished, but nothing went wrong. `stopped_reason` carries the runner's own sentence.++#### `current.progress`++Present while a job runs.++```jsonc+{+ "pct": 41, "phase": "denoise", "phase_label": "Denoising · step 5 / 10",+ "elapsed_sec": 62, "remaining_sec": 84, "eta_sec": 146,+ "preview": {+ "url": "/file?path=…/live/preview_latest.png&t=1786…", // cache-busted server-side+ "estimate": 4, "total": 12,+ "meaningful": true, // THE gate — the server decides, the client renders+ "abortable": true, // meaningful && the runner published an abort sentinel+ "saves_sec": 182 // remaining_sec at the moment it became abortable+ },+ "preview_url": "/file?path=…" // top-level alias, present only once meaningful+}+```++`preview` is absent unless the live preview is on (Settings → Memory / speed) and the tiny decoder is installed. **`meaningful` is computed server-side and must not be re-derived**: the rule differs per pipeline — estimate 6 of 8 on the distilled schedule, whose first estimates are still essentially noise; estimate 2 on the two-stage HQ path, which evaluates the denoiser twice per stage-2 step. A client counting estimates would have to know which schedule is running.++#### `POST /stop?mode=early`++Asks the running render to stop at the next forward boundary by touching an `ABORT` sentinel. The runner exits **75** — a distinct code meaning "the user stopped this", not a crash — and the job resolves `status: "stopped"` with no output file. Returns `404` when nothing is rendering and `409` when the render has no live preview to stop through (use the hard `POST /stop`, which kills the helper).**Encoding caveat:** the log buffer can contain literal control characters from prompts with embedded newlines. Strip them before JSON-parsing:@@ -372,7 +401,7 @@ Every completed clip writes a sidecar at `<output>.mp4.json` alongside the MP4."elapsed_sec": 426.13,"video_duration_sec": 7.0,"fps": 24,- "model": "dgrauet/ltx-2.3-mlx-q4",+ "model": "mlx_models/ltx-2.5-mlx-q4","queue_id": "j-<...>","helper_elapsed_sec": 425.5,"output_codec": { "preset": "standard", "pix_fmt": "yuv420p", "crf": "18" },diff --git a/docs/H3_ENGINE.md b/docs/H3_ENGINE.mdindex b6803f6..253a7b9 100644--- a/docs/H3_ENGINE.md+++ b/docs/H3_ENGINE.md@@ -3,7 +3,7 @@MiniMax-H3 (FL2VA) takes one prompt and returns **picture, dialogue and soundgenerated together**. It ships as an **optional pack**, not part of the baseinstall: ~75 GB of weights, a 64 GB+ Mac, and a licence with territory-restrictions. LTX-2.3 stays the default engine and is completely untouched by+restrictions. LTX stays the default engine and is completely untouched byany of this.---@@ -109,7 +109,7 @@ axes (the runner errors otherwise), so exact 16:9 means width `512k`, height| 2 | **1024×576** | **0.59 MP** | **the delivery canvas — `wide_5s`** || 3 | 1536×864 | 1.33 MP | over the model's own `MAX_PIXELS` (1.03 MP) and dearer than native 1344×768. Not shipped. |-`wide_5s` is measured, not extrapolated (`notes/QUALITY_LOOP.md` R1 on the same+`wide_5s` is measured, not extrapolated (the quality loop's R1 run, on the sameM4 Max): 22,923 packed rows, 126.0 s/step, 90.5 s VAE decode, 10.71 GiB decodepeak, **18.8 min**; the same probe put 768×448 at 9.1 min against this table's~8 min, hence the ~17-19 band. Denoise stayed at 37.6 GiB — identical to@@ -149,7 +149,7 @@ audio cross-fade (the chain's real overlap). The panel passes:--frames <window_frames> --chain-windows N --chain-total-frames <delivered>```-Measured (M4 Max 64 GB, `notes/CHAIN_WINDOWS.md` in the H3 campaign):+Measured (M4 Max 64 GB, on the H3 campaign's chained-window runs):| | Dense 10 s | Chained 10 s | Chained 15 s ||---|---:|---:|---:|@@ -302,17 +302,17 @@ install. Two working configurations:no venv of its own, so borrow the sibling one:```sh-export LTX_H3_ROOT=/Users/salo/AI/projects/hailuo-mlx/codex/opt-export LTX_H3_PYTHON=/Users/salo/AI/projects/hailuo-mlx/codex/minimax-h3-mlx/.venv/bin/python-export LTX_H3_MODELS=/Users/salo/AI/projects/hailuo-mlx/codex/models+export LTX_H3_ROOT=<campaign-checkout>/opt+export LTX_H3_PYTHON=<campaign-checkout>/minimax-h3-mlx/.venv/bin/python+export LTX_H3_MODELS=<campaign-checkout>/models```**What a user gets from `install_h3.js` today (Text only)** — the publishedbranch, with its own venv:```sh-export LTX_H3_ROOT=/Users/salo/AI/projects/hailuo-mlx/codex/minimax-h3-mlx-export LTX_H3_MODELS=/Users/salo/AI/projects/hailuo-mlx/codex/models+export LTX_H3_ROOT=<campaign-checkout>/minimax-h3-mlx+export LTX_H3_MODELS=<campaign-checkout>/models```Add either block to the normal panel env (`start.js` / `run_panel.sh`) anddiff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.mdindex 9791add..34f64c2 100644--- a/docs/RELEASE_CHECKLIST.md+++ b/docs/RELEASE_CHECKLIST.md@@ -49,8 +49,8 @@ Only applies to packs whose `required_files.json` entry has a `mirror` block(the LTX-2.5 ones). They are quantised by us and published as release assets, sounlike an `hf download` repo **nothing publishes them but us** — and a pack thatis not published is a fresh install with no weights, silently, only for new-users. LTX-2.5 came within one commit of being released as the default-generation with no download step behind it; this gate is why it wasn't.+users. That is exactly how LTX-2.5 shipped as the default generation with no+download step behind it.If you touched a mirrored pack's contents, its file list, or its `tag`:diff --git a/docs/STATE.md b/docs/STATE.mdindex 4f694cd..27eaa5d 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,6 +1,42 @@# Phosphene — project state, history, open work-**Public release: `v3.8.3`** (see the v3.8.3 + v3.8.2 + v3.8.1 + v3.8.0 CHANGELOG entries below; the narrative in this paragraph stops at v3.1.1 and is kept as history). The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)** → **v3.0.11 (latent helper-handshake hang fixed: `_read_until` mixed `select()` on the raw fd with a buffered `readline()`, so any event the helper emitted *right before* `ready` — a version-skew line, the new runtime fingerprint — got stranded in the TextIOWrapper buffer and the panel hung 120 s → "helper failed to start: None". This is the true root cause behind the mislabeled "⚠️-emoji" handshake break. Now reads the raw fd via `os.read()` into a carry buffer and drains every complete line before re-`select()`-ing. PLUS: every render log self-documents its runtime — mlx/mlx-metal version + Apple chip + macOS — surfaced in `/status`, the `helper ready ·` line, and a standalone `runtime |` line, the exact data needed to triangulate the remaining MLX-numerical "mosaic")** → **v3.0.12 (the REAL mosaic fix + 3 more. The mosaic is NOT a code bug or the missing-upscaler theory (both disproved by local repro — the bare 6-file Q4 set renders byte-identical-clean on M4 Max); it's stale/corrupt weight *content* — right size, wrong bytes — that v3.0.10's header+size check can't see (confirmed: ronyeoh/#18 + claude3d/#5 fixed it only by a fresh full re-download). Added **deep checksum verify vs upstream**: Settings → Model files → "Verify model files (checksum)" / `/models/verify-deep` hashes every weight + compares to HuggingFace's published SHA-256 (proven to match local), mismatches feed the existing one-click Repair re-download. Validated: flipped 16 bytes mid-file → header+size passed, deep-verify caught it. ALSO in v3.0.12: character-LoRA-shows-as-"style-only" fix (#5 — `list_user_loras` recovers trigger+kind from the `_v2` filename when the sidecar is missing); `cgi`→`email` multipart migration (Python-3.13-ready, removes the boot DeprecationWarning, adopted from @ssfeather's PR #22); dynamic 3–8 multi-keyframe UI (adopted from @youngbee12's PR #20, ported clean with the integrity feature preserved + a JS ReferenceError fixed). Folds in v3.0.11's handshake fix + runtime fingerprint.)** → **v3.0.13 (character LoRA fixes, #5 @claude3d: a multi-word/spaced character filename no longer mislabels as style-only — the id regex gated out spaces before the sidecar was read; and the Character tab no longer silently falls back to plain T2V — a UI desync left the avatar's selection ring lit after `character_id` was cleared. Plus an `enhancePrompt` element-id fix. Cherry-picked to prod `ce03139`, release `814dc2d`.)** → **v3.1.0 (Ideogram 4 — open-weight 9.3B text-rendering image model + a visual text-placement canvas that places exact text via normalized-bbox captions. mflux 0.18 `mflux-generate-ideogram4`; gated `ideogram-ai/ideogram-4-fp8` ~26 GB, needs a HF Read token + license. Fixed the gated-download 401 that would have hit EVERY user — the panel now exports its configured token to subprocess env via `_sync_hf_token_to_env` so a stale `hf auth login` cache can't shadow it; proven clean-room. Validated end-to-end: 8-text-element field-guide poster rendered clean, every label placed per its bbox.)** → **v3.1.1 (Ideogram output-card buttons hotfix, reported by Mr Bizarro: an Ideogram image's prompt is a caption JSON, which broke every output surface that fed it into a plain box / inline onclick — the Recent-list Animate button was worked-but-dead because apostrophes/&/< in the caption terminated the single-quoted onclick. Display-layer fix: `_displayPromptFor` derives `high_level_description`, `escapeHtml` the onclick args, friendly `_imgEngineLabel`, and `loadParams` restores an Ideogram image into the visual canvas instead of dumping JSON. `params.prompt` stays the caption JSON; renders unaffected. Validated live.)** All validated end-to-end on the dev panel (deep-verify corrupt-detect + repair, /loras, byte-identical upload, multi-keyframe render, FFLF regression). See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.+**Public release: `v4.0.0`** (2026-08-13 — LTX-2.5 becomes the generation the panel serves; see the v4.0 entry below. The narrative in this paragraph stops at v3.1.1 and is kept as history). **The 2.3/2.5 divergence that ran through the v3.8.x line is closed by this release** — LTX-2.5 is the registered default and the vendored port is pinned at the tag `v0.14.19+ltx25.3`. v3.8.x registered 2.3 only and pinned `871694d`, because the 2.5 packs were not publicly downloadable at cut time; they are now. See `CLAUDE.md`'s pin table. The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)** → **v3.0.11 (latent helper-handshake hang fixed: `_read_until` mixed `select()` on the raw fd with a buffered `readline()`, so any event the helper emitted *right before* `ready` — a version-skew line, the new runtime fingerprint — got stranded in the TextIOWrapper buffer and the panel hung 120 s → "helper failed to start: None". This is the true root cause behind the mislabeled "⚠️-emoji" handshake break. Now reads the raw fd via `os.read()` into a carry buffer and drains every complete line before re-`select()`-ing. PLUS: every render log self-documents its runtime — mlx/mlx-metal version + Apple chip + macOS — surfaced in `/status`, the `helper ready ·` line, and a standalone `runtime |` line, the exact data needed to triangulate the remaining MLX-numerical "mosaic")** → **v3.0.12 (the REAL mosaic fix + 3 more. The mosaic is NOT a code bug or the missing-upscaler theory (both disproved by local repro — the bare 6-file Q4 set renders byte-identical-clean on M4 Max); it's stale/corrupt weight *content* — right size, wrong bytes — that v3.0.10's header+size check can't see (confirmed: ronyeoh/#18 + claude3d/#5 fixed it only by a fresh full re-download). Added **deep checksum verify vs upstream**: Settings → Model files → "Verify model files (checksum)" / `/models/verify-deep` hashes every weight + compares to HuggingFace's published SHA-256 (proven to match local), mismatches feed the existing one-click Repair re-download. Validated: flipped 16 bytes mid-file → header+size passed, deep-verify caught it. ALSO in v3.0.12: character-LoRA-shows-as-"style-only" fix (#5 — `list_user_loras` recovers trigger+kind from the `_v2` filename when the sidecar is missing); `cgi`→`email` multipart migration (Python-3.13-ready, removes the boot DeprecationWarning, adopted from @ssfeather's PR #22); dynamic 3–8 multi-keyframe UI (adopted from @youngbee12's PR #20, ported clean with the integrity feature preserved + a JS ReferenceError fixed). Folds in v3.0.11's handshake fix + runtime fingerprint.)** → **v3.0.13 (character LoRA fixes, #5 @claude3d: a multi-word/spaced character filename no longer mislabels as style-only — the id regex gated out spaces before the sidecar was read; and the Character tab no longer silently falls back to plain T2V — a UI desync left the avatar's selection ring lit after `character_id` was cleared. Plus an `enhancePrompt` element-id fix. Cherry-picked to prod `ce03139`, release `814dc2d`.)** → **v3.1.0 (Ideogram 4 — open-weight 9.3B text-rendering image model + a visual text-placement canvas that places exact text via normalized-bbox captions. mflux 0.18 `mflux-generate-ideogram4`; gated `ideogram-ai/ideogram-4-fp8` ~26 GB, needs a HF Read token + license. Fixed the gated-download 401 that would have hit EVERY user — the panel now exports its configured token to subprocess env via `_sync_hf_token_to_env` so a stale `hf auth login` cache can't shadow it; proven clean-room. Validated end-to-end: 8-text-element field-guide poster rendered clean, every label placed per its bbox.)** → **v3.1.1 (Ideogram output-card buttons hotfix, reported by Mr Bizarro: an Ideogram image's prompt is a caption JSON, which broke every output surface that fed it into a plain box / inline onclick — the Recent-list Animate button was worked-but-dead because apostrophes/&/< in the caption terminated the single-quoted onclick. Display-layer fix: `_displayPromptFor` derives `high_level_description`, `escapeHtml` the onclick args, friendly `_imgEngineLabel`, and `loadParams` restores an Ideogram image into the visual canvas instead of dumping JSON. `params.prompt` stays the caption JSON; renders unaffected. Validated live.)** All validated end-to-end on the dev panel (deep-verify corrupt-detect + repair, /loras, byte-identical upload, multi-keyframe render, FFLF regression). See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.++> **🎬 2026-08-13 — v4.0 INTEGRATION: LTX-2.5 becomes the generation the panel SERVES, not just the one it loads.** The registry has carried 2.5 since 2026-08-12 and the weights have been mirrored since the same day; what was missing was the product. The panel still called the engine "LTX-2.3", still priced tiers with two hand-rolled subtitle writers printing 2.3-era minutes, still offered a duration one lane silently rounded away, and had no way to say "you can have the good tier, it costs 29.5 GB, here is the button." The FROM-ZERO gate — a fresh Pinokio install rendering one clip — was the last blocker before public promote, and it passed.+>+> - **The switcher says `LTX 2.5`, and the generation line is DERIVED.** The label is the family name; the build is its own span, resolved in `engines_payload()` from the active version. A user pinned back with `LTX_MODEL_VERSION=ltx23` reads `LTX 2.3`; the day 2.6 lands neither string is edited. A static `"LTX-2.5"` would have been the same bug one generation later.+> - **A tier table, so every LTX estimate is measured or says it isn't.** LTX gets H3's two-axis quality × length grammar — the same functions generalised, not forked, with the engine argument defaulted to `'h3'` so all **560** H3 chips are byte-identical across the change (sha256 `679937ef…`). The cost model is fitted to two renders made that day and **cross-validated**: pricing `balanced/5s/q8` — a cell neither anchor is — gives 142.8 s against the 139.4 s measured, 2.4 % out. Three measured rows, not twenty invented ones. Three subtitle writers deleted or neutered.+> - **The anti-mosaic preflight had been DEAD since 2.5 became the default** (`_canonical_layout()` compared MODEL_ID against the *active* generation's q4 path). The guard written after the June-2026 rainbow-mosaic investigation was itself switched off in the field. Fixed and proven with the bug's own repro — withhold `spatial_upscaler_x2_v1_1.safetensors` and the refusal names the file — plus a **pre-render** layer that disables Generate before Gemma loads instead of failing 30 s in.+> - **The 7-second lie, and the three other duration tables behind it.** A shot set to 7 s on H3 snapped to 5 s (124 frames) while the select still read "7 s" and the estimate agreed with the select. Every menu now reads the engine's own table; an off-axis board round-trips with `7 s · nearest 5s`, and H3's 15 s is reachable for the first time.+> - **2.5 characters were routed onto an ungraded pipeline, and then could not render at all.** `balanced_q8_fast` (a 2.3 speed optimisation, no version gate) rerouted Balanced → `high`, which demanded the 29.5 GB HQ add-on; and the panel's LoRA-fusion patch built its DiT from `LTXModel()` **defaults**, so every 2.5 render with a LoRA attached died on `Received 1 parameters not in model: keyframes_abs_pos_embedding`. Both fixed; characters now render q8 + distilled — the recipe every graded 2.5 clip ran — proven end to end **with the add-on withheld from disk**, clean identity at frame 60.+> - **The voice gets its own strength — and the shipped default is the graded `1.0`.** The face file's audio-branch deltas are noise and at equal strength they are LOUDER than the voice file's signal (median ‖D‖ 1.45 vs 1.10), so running the voice hotter is what makes it win: parity is 1.2, 1.4 is the first rung with real headroom. The SPLIT CONTROL ships and the help-dot explains the mechanism, but the **default stays at 1.0/1.0 — the pair every graded clip was rendered at and passed on.** 1.4 was the pre-release default and no ear had passed it; a default nobody has listened to is not a default. Raise it when one says so. `character_voice_strength` is asserted into `params` in the same commit that adds it — the allowlist trap, closed with a test rather than a hope.+> - **Live preview + Stop early.** `--live-preview tae` with the 22 MB decoder now shipping as an ordinary `github-release` registry row. Preview on vs off is **byte-identical** (`79ec11a7…` both) with the preview demonstrably running; an abort exits **75**, writes no mp4, and resolves as `status: "stopped"` — muted card, "Nothing was saved" — not a failure. The `meaningful` gate is server-owned because the rule differs per pipeline (estimate 6 on distilled, 2 on res_2s); a Stop button over a noise field aborts takes that were going to be fine.+> - **Settings → Storage**, measured by walking the real directories rather than reading `size_gb`: LTX-2.3 57.8 GB, the High add-on 29.5 GB (sized from its two filenames — a directory walk there deletes the q8 pack), Gemma 3 8.1 GB shown greyed with *why it cannot go*. `/models/remove` refuses the active model, an in-flight folder and an unregistered key, and never takes a path from the client.+> - **Both foundation defects closed**: `assert_registry` is **113 passed, 0 failed, 0 known defects pinned** — the first honestly green run since the markers went in.+>+> **FROM-ZERO: PASSED.** A fresh Pinokio install, from an empty directory, through the install lane and out the other side rendering a clip. That gate blocks public promote and nothing substitutes for it.++> **📦 2026-08-12 — THE SHIP BLOCKER IS CLOSED: the LTX-2.5 packs are published, and a fresh install can now fetch the default generation.** LTX-2.5 became the default the same morning, while `install.js` still downloaded only 2.3 — `q4_25` / `gemma4_25` named `mrbizarro/...` HuggingFace repos **that do not exist and never will** (our token is read-only, and these packs are our own quantisation of a gated upstream). On the box that built them the default lane was correct; on a **fresh install there were no weights at all for the generation the panel boots into**, and nothing in the product would have said so until the first render failed. `ltx25_pin_move.md` §8.1 called it the one blocker; this is it, closed.+>+> - **Mirrored as GitHub release assets** — `weights-ltx25-v1`, tagged on **public `main` d4c6ac5** (v3.7.0's release commit, `--latest=false` so it does not displace v3.7.0), the same lane the `bizarrotrn_v2` sample character has taken since July. `q4_25` (20.74 GB) + `gemma4_25` (6.73 GB).+> - **A release asset is capped at 2 GiB and the transformer is 11.32 GB**, so anything over the cap is published as ordered 1.9 GB shards. `scripts/publish_pack_release.py` writes, uploads and **deletes one shard at a time** — publishing a 21 GB pack costs 1.9 GB of scratch, not a second copy of the pack, on machines already tight enough that we quantised the model for them. Uploads resume by skipping assets already on the release; the **manifest goes up last**, so a half-published release cannot be consumed.+> - **`scripts/fetch_pack_release.py` is the consumer, and it is stdlib-only** because it runs from `install.js` before anything optional exists and from inside the panel. Every shard is checked against its own sha256 as it lands, the reassembled file against the file sha256, and a file is renamed into place **only after that second check** — so a killed download never leaves something the loader would pick up. Resume works at two levels: an HTTP Range request inside a shard, and a sidecar at shard granularity that is trusted **only when the partial's length agrees with it**.+> - **The manifest is NOT a second format.** It is the `phosphene_quant_manifest.json` `scripts/quantize_ltx.py` already emits, plus a `release` block and a `shards` list per file; `files: {name: {bytes, sha256}}` is preserved exactly, so the panel's existing `_manifest_meta()` deep-verify reader consumes either.+> - **A real finding: the in-pack quant manifest is stale for two sidecars.** `embedded_config.json` (says 2,557 B and config.json's hash; is 7,589 B) and `split_model.json` (says 302 B; is 305 B) were rewritten by the conversion step *after* the quantiser wrote its manifest. **Every `.safetensors` hash matches**, which is why deep-verify never noticed — it only hashes safetensors. The publisher publishes the **files'** hashes, records the disagreement in `quant_manifest_drift`, and does not "fix" the quantiser's deterministic output to hide it.+> - **Licence, as files rather than intentions.** These weights are a Derivative under §1.5 of the **LTX-2.x Community License Agreement**, redistributable under §3 on conditions 3.1–3.5. The complete Agreement (Attachment A and all, fetched verbatim from `Lightricks/LTX-2`) and a `NOTICE.md` enumerating exactly what we changed — layout rewrite, 4/8-bit quantisation of the DiT block linears at group size 64, a provenance metadata key, generated sidecar configs, a pure byte split for transport — and what we did **not** (no training, no distillation, nothing removed or circumvented from the Licensor's safety or use restrictions) ship as release assets **and are fetched into the pack directory**, so the terms land on the user's disk next to the weights. The §3.5 Commercial-Entity notice ($10M revenue → paid licence from Lightricks) is stated in both. No territory restriction exists in this licence; that was H3's problem, not this one.+> - **The panel got a second download lane, not a second downloader.** `_download_thread` picks its command from the registry — a repo with a `mirror` block spawns the fetcher, everything else spawns `hf` exactly as before. The retry loop, the character-at-a-time log streaming, the single global download slot and cancel-by-process-group are all shared. Repair works unchanged on the new lane, and the missing-`hf` guard no longer blocks a pack that never needed hf.+> - **`install.js` fails loud** if the 2.5 fetch fails (it is the default lane, and a panel that cannot render is not a successful install); **`update.js` is best-effort** (an Update must not be brickable, and the Models page now retries through the same fetcher). `pinokio.js` needed no change: `baseRepos` already filters `kind === "base"`, so an install without 2.5 weights already renders **Resume Install** — the self-heal path was always there, it just had nothing to fetch.+> - **FROM ZERO, against the real release** — the gate this ships on. Both packs pulled into an **empty directory** with the exact command `install.js` runs, against the real release. `q4_25`: 19 files, 20.74 GB. `gemma4_25`: 11 files, 6.73 GB. Every shard and every reassembled file sha256-verified, `--check-only` green on both afterwards. The reassembled 11,320,074,467-byte transformer and 6,344,495,432-byte connector hash **identical to the packs that were published** (`7c8c4f71a4cf…`, `120b43898339…`). The transformer then went through the **vendored loader** — `load_split_safetensors` → `apply_quantization` → `load_weights` → `mx.eval`, the production path — and came back `loaded: true, n_weights: 7355, loader_detected_bits: 4` in 7.6 s. sha256 proves the bytes arrived; only that proves they are a model. Separately, the published manifests were checked against the **real on-disk packs** and matched every file, which is the assertion that the mirror is the pack and not a copy of it. **Daemon :8199 never touched** — PID 58950, 10 h 51 m uptime, answering 200 before, during and after.+> - **16 tests**, `scripts/test_pack_release.py`, publisher and fetcher exercised together against a loopback HTTP server through the same code paths a real publish and a real fresh install take. A corrupted shard never reaches the pack **and no longer abandons the rest of it** (that one was found by the test and fixed in the fetcher); an interrupted download resumes instead of restarting; a complete pack is left alone; a pack missing a mandatory file cannot be published at all.+> - **Still open: `q8_25` is deliberately NOT mirrored.** `e870061` added `transformer-dev.safetensors` and `ltx-2.5-22b-distilled-lora-450.safetensors` to it (30 → 58 GB) and neither exists on disk yet. A release cut from the old file list would produce a pack the panel reports incomplete on arrival — the June mechanism verbatim — so `q8_25` gets no `mirror` block until the pack is complete. The publisher would refuse anyway; that refusal is the point.+>+> **SAME DAY, PHASES 2 + 3 — THE MIRROR IS COMPLETE: 89 assets, 86.99 GB, q4 + gemma4 + q8 + hq, all un-gated.** Owner's call was ship q4+q8 now and let High follow, which required a split: `e870061` had listed `transformer-dev.safetensors` and `ltx-2.5-22b-distilled-lora-450.safetensors` inside `q8_25`, so a pack that was **complete on disk, gates passed, 30 GB** was both unpublishable and un-installable while a 42 GB download it did not contain finished. Those two files became their own download unit, `hq_25`, sharing `local_dir` with the q8 pack because they are loaded out of it **by name** — two entries, one directory, on purpose: an entry is a *download unit*, not a directory.+>+> - **The gate e870061 bought was moved, not given back.** Splitting the file list without moving the gate would have restored the exact bug it fixed, so the four two-stage gates now ask `hq_surface_missing()` (the union of pack and add-on) and still refuse by the same two filenames; `q8_available` — which is what the UI reads to enable High / Extend / Keyframe / FFLF — now means "that surface can run", or the wave-through simply relocates from the job gate to the pill. `balanced_q8_fast` deliberately still asks `q8_missing_files()`: Q8 Fast runs the distilled transformer and never touches the dev one. **Inert for 2.3 by construction** (it declares no `hq_addon_repo_key`), verified by calling the real functions against the real registry.+> - **A DOWNLOAD UNIT IS NOT A DIRECTORY — caught mid-upload.** `pack_files()` published every file in the pack directory, so the moment the add-on's weights landed in the q8 directory the *running* q8 publish began uploading 29 GB of add-on under a `q8_25__` prefix — silently restoring the coupling the split existed to remove. Killed it, deleted three stray assets; nothing was ever advertised because the manifest uploads last. Now a host publishes its directory minus anything another entry with the same `local_dir` declares, and a guest declares `publish_scope: "files"` and cannot sweep up its host's sidecars. Both directions tested.+> - **Resume could skip a file whose content changed.** GitHub publishes no asset checksum, so resume compares sizes — blind to same-size content changes. Not hypothetical: the in-pack `phosphene_quant_manifest.json` was rewritten by the dev-pack agent between two publishes (gaining the sha256 rows that let deep-verify check both new files). Anything ≤ 16 MB is now always re-uploaded; big shards keep the size skip, where such a change still fails loudly on the fetcher's sha256 instead of installing.+> - **Also survived, in production:** a real `dial tcp: lookup uploads.github.com: i/o timeout` that killed the first q8 run on its last file (re-running skipped ~29 GB and finished the tail), and free space hitting **322 MiB** mid-upload while the dev build churned — the upload lived because its footprint is one shard.+> - **FROM ZERO, all four lanes, byte-identical to source:** q4 `7c8c4f71…`, gemma `a3e8b162…`, q8 `36a346c1…`, dev `90b7e01d…` + LoRA `86370bbf…`. `loader_detected_bits` came back **4** for q4 and **8** for q8 and dev, so each lane is the pack it claims to be. **The split is proven, not asserted:** the q8 lane fetched into an empty directory contains no add-on file — a 30 GB q8 install, not a 59 GB one. Daemon :8199 untouched throughout (PID 58950, 14 h 09 m). Final free space 66 GiB.> **🌍 2026-08-12 — THE GEOIP KILL (analytics schema-v2 Phase 1): every event now tells PostHog not to locate it.** The panel has never sent a location field. It didn't have to: PostHog derives country, city, subdivision, timezone and the city's coordinates from the connecting IP by **default**, and the previous posture — in `_analytics_post`'s own docstring — was *"we neither add to nor suppress that."* Now suppressed, on every event, via `_ANALYTICS_RECEIVER_DIRECTIVES` spread **last** into the properties block so no call site can override it.>@@ -20,7 +56,7 @@> - **`app_installed` documented.** It has shipped and fired since the module landed, and `ANALYTICS.md` never named it — a bug by that page's own opening rule. Fields (`version`, `chip_family`, `ram_gb`), why it exists (it is the denominator; without it "new installs over time" tempts someone to profile ids), and the once-ever mechanism (`analytics_install_reported`).> - **Suite RED → 38/38 GREEN, rewritten not deleted.** `test_shipped_default_key_is_empty` → `test_shipped_key_is_a_write_only_project_key` (the real invariant was never "no key", it was "no READ-capable key" — `phx_`/`phs_` must never ship). `test_no_key_means_no_socket` → `test_opt_out_is_the_toggle_not_the_key`. The third failure was a **stale fixture with correct new behaviour**: `h3_tier: "5s"` is a LENGTH, never a tier key, so `"unknown"` is right — fixture moved to the real legacy key `hq_5s` → `standard_5s`, with `"5s"` kept as the worked example in a new closed-vocabulary test. Added `test_app_installed_fields` and a **documentation-parity test**: every event name `_analytics_capture()` can be called with must appear in `ANALYTICS.md`, so the next undocumented event fails the build instead of shipping.> - **Validated:** `py_compile`; the analytics settings-section re-parsed out of the served HTML with a tag checker (balanced, `details`/`summary` intact); 38/38 suite; and the new guards **mutation-tested** — blank the key, ship a `phx_` key, ignore the toggle, undocument an event, break legacy tier resolution, re-fire `app_installed`: **9/9 turn the matching test red.** A guard that cannot fail is how `acfbdc7` got through.-> - **NOT done here, still open** (schema v2, `~/AI/projects/phosphene/notes/analytics_spec_2026-08-11.md`): `$geoip_disable` + `$ip: null` on the payload (GeoIP is still on by default) — ⚠️ **SUPERSEDED 2026-08-12 by the GeoIP-kill entry above; and `$ip: null` as written here is a no-op, see there for what actually works**, `error_class` replacing free-text `error_signature`, version/chip context on render events, `update_state`, `wall_sec_bucket`. Phase 0 was shipped alone deliberately — the doc had to stop being false before anything else was worth arguing about.+> - **NOT done here, still open** (schema v2): `$geoip_disable` + `$ip: null` on the payload (GeoIP is still on by default) — ⚠️ **SUPERSEDED 2026-08-12 by the GeoIP-kill entry above; and `$ip: null` as written here is a no-op, see there for what actually works**, `error_class` replacing free-text `error_signature`, version/chip context on render events, `update_state`, `wall_sec_bucket`. Phase 0 was shipped alone deliberately — the doc had to stop being false before anything else was worth arguing about.> **🎬 2026-08-07 — PER-WINDOW PROMPTS: the "10s just repeats after 5 seconds" report, fixed (dev only, not shipped).** Reported in public on v3.6.0 by **@Wizard_1981**: 10 s and 15 s clips *"just repeat immediately after 5 seconds."* The owner's instruction was direct — *"fix it and ship, make it user friendly, add ? if you need tooltip."*>@@ -157,7 +193,7 @@> **📐 2026-08-06 — H3 gets a TRUE 16:9 tier, and every tier now says its aspect out loud.** Mr Bizarro: *"H3 users are getting bars on every clip for no reason."* He was right, and nothing in the UI admitted it. Every H3 tier rendered at an odd ratio and then got **pillarboxed** by the export pass — 768×448 is 12:7, 640×384 is 5:3, our best hero canvas 1152×640 is 9:5, and none of them is 16:9 (1.7778). Meanwhile LTX's Balanced preset renders 1024×576, which IS 16:9, so its 720p export is a pure 1.25× scale with no padding at all.>> - **The arithmetic, and why there is exactly one answer.** The runner errors unless both axes are multiples of 32 (`if args.height % 32 or args.width % 32: parser.error(...)` — verified in `generate_staged.py`, not taken on trust). Exact 16:9 on that grid means width `512k`, height `288k`, and only three of those exist near H3's envelope (`packing.py`: SHORT_EDGE 768, MAX_PIXELS 768·1344, CANVAS_MULTIPLE 32): **512×288** (0.15 MP), **1024×576** (0.59 MP), **1536×864** (1.33 MP — *over* the model's own MAX_PIXELS of 1.03 MP, and dearer than the native 1344×768 canvas that measured 44.8 min per 5 s window; not shipped, and now written down so nobody re-derives it).-> - **`wide_5s` — 1024×576 · 124f · 9 sigma points, `~17-19 min`.** Not extrapolated: `notes/QUALITY_LOOP.md` R1 measured **exactly this geometry at exactly these 8 forwards** on this M4 Max — 22,923 packed rows, 126.0 s/step, 90.5 s VAE decode, 10.71 GiB decode peak, **18.8 min wall**, denoise flat at 37.6 GiB (identical to 768×448 — the DiT weights dominate, there is no memory wall). The same probe put 768×448/124f at 9.1 min against this table's advertised ~8 min, which is where the 17-19 band comes from. **On Turbo the same canvas is MEASURED at 8.5 min** — see the cost-model correction below. Same seed, same still, same forwards, judged at 1:1 on a 1080p delivery, 1024×576 against 768×448: eyebrows become individual hairs, forehead gets pores instead of wax, eyelashes exist at all, fur reads as strands — **and** the pillarbox disappears while the 1080p enlargement drops 2.41× → 1.875×.+> - **`wide_5s` — 1024×576 · 124f · 9 sigma points, `~17-19 min`.** Not extrapolated: the quality loop's R1 run measured **exactly this geometry at exactly these 8 forwards** on this M4 Max — 22,923 packed rows, 126.0 s/step, 90.5 s VAE decode, 10.71 GiB decode peak, **18.8 min wall**, denoise flat at 37.6 GiB (identical to 768×448 — the DiT weights dominate, there is no memory wall). The same probe put 768×448/124f at 9.1 min against this table's advertised ~8 min, which is where the 17-19 band comes from. **On Turbo the same canvas is MEASURED at 8.5 min** — see the cost-model correction below. Same seed, same still, same forwards, judged at 1:1 on a 1080p delivery, 1024×576 against 768×448: eyebrows become individual hairs, forehead gets pores instead of wax, eyelashes exist at all, fur reads as strands — **and** the pillarbox disappears while the 1080p enlargement drops 2.41× → 1.875×.> - **A 16:9 draft (512×288, ~2 min) is wired but OFF, behind `LTX_H3_WIDE_DRAFT=1`** — the same pattern `LTX_H3_DENSE_10S` uses. Judgement call, stated plainly: it would be the cleanest draft→finish pair on the table (identical aspect, an exact 2× to Wide 5s, so the framing a draft shows is the framing that ships), but 0.15 MP is a third of the pixels the Draft note *already* hedges about, and **nothing in this campaign has ever rendered below 640×384** — the ladder only ever went up. Shipping an unmeasured bottom-of-ladder tier is how a user concludes "H3 is bad", which is the exact failure the draft note exists to prevent. One env var and one render decides it.> - **Every tier now labels its own aspect,** derived from its width/height by `_h3_aspect()` and appended to the `spec` the chip prints — `1024×576 · 124f · 16:9` against `768×448 · 124f · 12:7`. Derived, never typed, so an advertised ratio cannot drift from the geometry that renders. The `wide` boolean rides along for anything that needs the machine-readable form.> - **And a live sentence under the Export row** (`#h3ExportNote`, the existing `engine-hint` style): *"720p: pure 1.25× scale to 1280×720 — no bars, no padding."* vs *"720p: 12:7 fits to 1234×720 inside 1280×720 — 23 px bars left and right."* It is per **(tier × export target)**, because that is what the answer actually depends on, and the strings are generated server-side by `_h3_export_notes()` **from `compute_upscale_plan` itself** — the copy cannot disagree with the ffmpeg command because it is built from it. Hidden on Native. Incidentally this corrects a long-standing wording error in this file and the code: 12:7 is *taller* than 16:9, so it fits by height and the bars land at the **sides**. It was never letterboxing; it was pillarboxing, 23 px at 720p and 34 px at 1080p — the 34 matches the campaign's own measurement of "1851×1080 of content".@@ -289,13 +325,13 @@ Current `dev` head: see `git log -1` for the live SHA. `dev` tracks `beta/main`> **✅ DONE 2026-07-23 — shippable sample character (kills the #1 barrier: "must train a LoRA before you can try Remix").**> - `bizarrotrn_v2.safetensors` (817 MB, the exact character from the demo clip) hosted as a **public GitHub release asset**: `https://github.com/mrbizarro/phosphene/releases/tag/sample-character-bizarro` (HTTP 200 verified; sha256 `a52e648a…`). Visual LoRA only (no voice) — the audio sibling is optional per `list_characters()`.> - **In-app one-click** "Get a sample character (Bizarro)" button in BOTH empty states (Character-mode strip `charsEmpty` + standalone Characters grid `charactersEmpty`). Backend: `POST /characters/download-sample` (202 + bg thread, atomic .partial→rename, sha256-verified, **refuses to overwrite** an existing `bizarrotrn_v2`) + `GET /characters/download-sample/status` poll. Commit `033acb5` (beta). Verified live end-to-end (both buttons render + click cleanly; already-installed path; character discovered as "Bizarro").-> - Remix draft post (`~/AI/projects/phosphene/launch/remix_launch_post_DRAFT.md`) updated to explain the Character requirement + point at the one-click sample.+> - Remix draft post updated to explain the Character requirement + point at the one-click sample.> - ⚠️ **HF hosting was NOT possible** — this machine's HF token is READ-only (salocharly). If Mr Bizarro wants it mirrored on Hugging Face too, that needs a WRITE token he provides. GitHub release is the shipped path.>> **REMAINING before pushing Remix public:**> 1. **From-zero fresh-Pinokio-install run** — the manifest audit is static analysis; still do one real clean install + one render per new mode (Ingredients / Control / Colorize / Ingredients×Character / A2V). This is the last hard gate ([[feedback_validate_from_zero]]).> 2. **Q4-character label — DECIDED, NOT YET IMPLEMENTED.** Decision: character stays UNLOCKED on Q4 (check-in data: 8 GB = 20%, 16 GB = 25% of users → locking out 45% costs more than a softer face). Add a short "Q4 fallback — identity is approximate; Q8 gives faithful faces" note near the character quality strip. Relevant code: `setMode()` character branch ~`mlx_ltx_panel.py:23745`, quality chips ~20903/21131, `_validate_character_quality` ~5607 (server already allows Q4). Reversible one-liner if Mr Bizarro disagrees.-> 3. **Publish the staged Remix post WITH the release** — full text + live `assets.pinokio.co` media URLs backed up at `~/AI/projects/phosphene/launch/remix_launch_post_DRAFT.md`. ⚠️ The Pinokio composer AUTO-SAVES and the browser draft was overwritten by the v3.2.7 post — use the backup file, not the composer draft.+> 3. **Publish the staged Remix post WITH the release** — full text + live `assets.pinokio.co` media URLs backed up outside this repo. ⚠️ The Pinokio composer AUTO-SAVES and the browser draft was overwritten by the v3.2.7 post — use the backup file, not the composer draft.> 4. Bump VERSION (3.2.13 → 3.3.0 suggested; it's a feature wave, not a patch) + tag.> 5. saved-j's training validation — a real train run to confirm the precision fix (#35/#36) end-to-end.@@ -311,7 +347,7 @@ Current `dev` head: see `git log -1` for the live SHA. `dev` tracks `beta/main`> **Session 2026-07-10 — P0 install-breaker fix + full GitHub triage + triage-automation repair + /stats issues board:**> - **🔴 P0 (public): `transformers 5.13.0` breaks EVERY fresh install.** `mlx-lm 0.31.1` requires `transformers>=5.0.0` (no upper bound); after 5.13.0 dropped (~Jul 9) it broke `mlx_lm.tokenizer_utils` → Gemma encoder silently no-ops → every generation crashes (`'str' object has no attribute '__module__'` / "Model not loaded"). 4 reports (#40/#38/#37/#33). **Fixed:** pinned `transformers>=5.0.0,<5.13.0` on the mlx-lm `uv pip install` step in `install.js` (beta `e5ef1b3`). Known-good: 5.7.0 (our build) + 5.12.x. Existing users' manual unblock: `cd ltx-2-mlx && uv pip install --python env/bin/python 'transformers>=5.0.0,<5.13.0'`. **NOT yet on public main** — needs the OK to cherry-pick + push (users have the workaround). #40 kept open as the tracker; #33/#37/#38 closed as dups.> - **GitHub backlog fully triaged:** replied to all; closed #33/#37/#38 (transformers dups) + PR #39 (mode-bar CSS, superseded by the beta Remix rework). #34 replied (empty body, awaiting details). **#35 + #36 kept open, tracking a code fix:** the trainer's `_patch_loader_prefer_dev_transformer` picks the **Q4-quantized** `transformer-dev.safetensors` (~11 GB in the q4 dir) over the **full-precision Q8 dev** (~20 GB in the q8 dir) → near-zero LoRA weights (root cause of "trained LoRA doesn't apply"). FIX TODO (validate with a real train run): prefer the full/Q8 dev + placement-aware integrity (warn on a quantized dev in the q4 dir; verify `spatial_upscaler_x2_v1_1.safetensors` present; size-check vs expected). PRs #31/#29 already reviewed (ADOPT-WITH-CHANGES).-> - **Triage automation repaired.** It wasn't just "launchd disabled" — the launchd job was retired Jul 8 and replaced by a Claude Routine (`phosphene-morning-triage`, enabled, 8am) that (a) silently no-op'd (fetch failed in the unattended env — PATH/`gh`) and (b) was **drafts-only by design** → contributors never got answered. Fixed both: (1) hardened `~/AI/projects/phosphene/notes/triage/fetch_morning_brief.sh` — 3-try network retry + absolute `GH=$(command -v gh || …)`; (2) rewrote `~/.claude/scheduled-tasks/phosphene-morning-triage/SKILL.md` into a **gated posting spec** modeled on the working Bloom triage: reply-on-playbook-match / label / close-dup, **escalate anything new, NEVER push code**, ≤6 posts/run, skeleton-brief-first, always leaves a brief. Reads `issue_triage_playbook.md`. Armed for next 8am.+> - **Triage automation repaired.** It wasn't just "launchd disabled" — the launchd job was retired Jul 8 and replaced by a Claude Routine (`phosphene-morning-triage`, enabled, 8am) that (a) silently no-op'd (fetch failed in the unattended env — PATH/`gh`) and (b) was **drafts-only by design** → contributors never got answered. Fixed both: (1) hardened the triage fetch script — 3-try network retry + absolute `GH=$(command -v gh || …)`; (2) rewrote `~/.claude/scheduled-tasks/phosphene-morning-triage/SKILL.md` into a **gated posting spec** modeled on the working Bloom triage: reply-on-playbook-match / label / close-dup, **escalate anything new, NEVER push code**, ≤6 posts/run, skeleton-brief-first, always leaves a brief. Reads `issue_triage_playbook.md`. Armed for next 8am.> - **/stats now lists issues + PRs.** New "Needs attention" board (open issues | open PRs, newest-first, author/age/labels/badge) — `scripts/fetch_repo_stats.py` gains `fetch_open_items()`, `panel_assets/stats.html` gains the board section (beta `709850d`). Data in the gitignored `state/stats-data.jsonl` (non-sensitive fields only); /stats stays 127.0.0.1-only. Reads at request time (no restart needed).> - Stats snapshot: 92★ (nearing 100), 14 forks, ~4.3k users, 95 clones/day.@@ -338,13 +374,13 @@ Current `dev` head: see `git log -1` for the live SHA. `dev` tracks `beta/main`> - **LoRA/character fixes — SHIPPED PUBLIC as `v3.0.13`** (beta `f4f992e` → cherry-picked to prod `ce03139`, release commit `814dc2d`, tag `v3.0.13`, 2026-06-11). Two bugs @claude3d reported on v3.0.12, fixed + validated live in the dev panel: (1) a character LoRA whose filename contains a **space** (e.g. `Annie Phosphene_v2.safetensors`) was misclassified as style-only / "No trained characters yet" even with a correct sidecar — `_CHARACTERS_ID_RE` rejected spaces and gated `list_characters()` *before* the sidecar was read. Widened the regex to `[A-Za-z0-9 _-]+` and made `_character_safe_id` URL-decode so spaced ids resolve in the `/characters/<id>/{preview,generate,delete,rename}` routes (unquote-then-validate stays traversal-safe). (2) Character tab could silently render plain T2V — a **UI desync** left the avatar's `.active` ring ON after the hidden `character_id` was cleared on a mode switch, so Generate shipped `character_id=""` → no LoRA. ("Params shows Text" is by design — `character_id` drives the LoRA stack, not the mode field.) The ring now re-renders in lockstep with the cleared selection. Plus a latent `enhancePrompt` wrong-element-id fix. **Deliberately NOT bundled with the Ideogram work below** so the fixes can ship without waiting on the gate. Validation: `/characters` lists a spaced-name char; in-browser pick→switch-away→switch-back leaves the ring OFF + field empty, re-pick ships `character_id`.> - **Ideogram 4 engine + visual text-placement canvas — SHIPPED PUBLIC as `v3.1.0`** (2026-06-11). Open-weight 9.3B text-rendering model + a client-side bbox text-placement canvas. mflux 0.18 `mflux-generate-ideogram4`; gated `ideogram-ai/ideogram-4-fp8` (~26 GB; user needs a HF **Read** token + accept the license). **Root-caused + fixed the gated-download 401 that would have hit every user:** the image-engine mflux subprocess inherits `os.environ`, but the panel never exported its configured token there, so huggingface_hub fell back to a stale `hf auth login` cache (a different/unauthorized account) → 401. `_sync_hf_token_to_env()` now pushes the settings token → `HF_TOKEN` env (wins over the cache) at boot + per image job. Proven clean-room (fresh empty env: old path 401s, fix authenticates). Validated end-to-end: an 8-text-element field-guide poster rendered clean with every label placed per its bbox. Gate-error message reworded to name a wrong-account token instead of telling users to re-accept the license. Memory: `phosphene_hf_ideogram_account` + `feedback_fixes_must_reach_users`.> - **Mosaic (Q4 on certain Apple GPUs) — confirmed an upstream engine bug.** dgrauet ([ltx-2-mlx#40](https://github.com/dgrauet/ltx-2-mlx/issues/40)) traced it to the **MLX 4-bit Metal kernel on specific GPU sub-families** — NOT monotonic by chip (his M2 Pro is clean; an M4 Max reporter, shdwmacca, mosaics). He gave a 30-sec `mlx_q4_check.py` repro (saved `/tmp/mlx_q4_check.py`); our M4 Max is clean (`applegpu_g16s`, all rows <1%). **Still need the script output from an affected box** (poppy0396 M3 Ultra / elbarto M3 Max / rathore M2) — relayed to GitHub #23 + #40; **still to relay on the Pinokio @rathore thread (Mr Bizarro pastes — Mac browser isn't logged into Pinokio).** Workaround: render High/Q8. Detail: memory `phosphene_ltx_pin_v0148.md`.-> - **8 AM triage cron fixed** — `fetch_morning_brief.sh` had been dead since **May 31** (exit 127: `gh` is in `~/bin`, off the launchd PATH). Fixed + verified in the PM hub (`~/AI/projects/phosphene/notes/triage/`, outside this repo). Closed GitHub #18 (ronyeoh) + #19 (shakeworks).+> - **8 AM triage cron fixed** — `fetch_morning_brief.sh` had been dead since **May 31** (exit 127: `gh` is in `~/bin`, off the launchd PATH). Fixed + verified outside this repo. Closed GitHub #18 (ronyeoh) + #19 (shakeworks).Live URL: `https://github.com/mrbizarro/phosphene` · Linear project: `https://linear.app/hairstylemojo/project/phosphene-9c11240704bb`This doc is the **session-start handoff**. A new Claude window entering this project should read this first, then `CLAUDE.md` (architecture), then the relevant Linear issues.-> **Authoritative engineering snapshot:** `/Users/salo/AI/projects/phosphene/notes/DEEP_REVIEW_2026-05.md` (2026-05-31) — the deep stabilization review: risk register + phased stabilization plan. It is the source of truth for current bug state and supersedes the historical log in §7 below.+> **Authoritative engineering snapshot:** the 2026-05-31 deep stabilization review — risk register + phased stabilization plan. It is the source of truth for current bug state and supersedes the historical log in §7 below.---@@ -670,7 +706,7 @@ phosphene-dev.git/`mlx_ltx_panel.py` is the heart of it — almost all panel behavior lives there. `mlx_warm_helper.py` is the long-running inference subprocess. `patch_ltx_codec.py` is a runtime modifier that fixes upstream code without forking it.-> The vendored `ltx-2-mlx` is pinned at **v0.14.0** (SHA `b35254a`). The deep review (`notes/DEEP_REVIEW_2026-05.md`) flags the **runtime-monkey-patch + version-skew axis as the single top fragility** — the panel/helper patch a moving upstream at runtime, and (pre-Phase-0) nothing asserted the imported `ltx_pipelines_mlx` was actually v0.14.0. The stabilization plan there (Phase 0 loud version gate, Phase 3 retire the runtime-patch class) addresses it.+> The vendored `ltx-2-mlx` is pinned at **v0.14.0** (SHA `b35254a`). The deep review flags the **runtime-monkey-patch + version-skew axis as the single top fragility** — the panel/helper patch a moving upstream at runtime, and (pre-Phase-0) nothing asserted the imported `ltx_pipelines_mlx` was actually v0.14.0. The stabilization plan there (Phase 0 loud version gate, Phase 3 retire the runtime-patch class) addresses it.## 6. What worked / didn't this session (May 3–5 2026)@@ -707,7 +743,7 @@ phosphene-dev.git/## 7. Known bugs-> **Source of truth for bug state: `/Users/salo/AI/projects/phosphene/notes/DEEP_REVIEW_2026-05.md`** (the deep stabilization review — full verified risk register + phased plan). The list below is the short reconciliation; the review has the complete severity-ranked register and the fix directions. The CHANGELOG further down is the historical record of what was fixed when — not a list of live bugs.+> **Source of truth for bug state: the deep stabilization review** (full verified risk register + phased plan). The list below is the short reconciliation; the review has the complete severity-ranked register and the fix directions. The CHANGELOG further down is the historical record of what was fixed when — not a list of live bugs.### Currently open@@ -738,172 +774,29 @@ Reconciled against the deep review (2026-05-31). Everything that was a recent fi> **Read the gap honestly:** this section stopped being maintained after v3.0.6. Everything> between v3.0.7 and v3.7.0 was released with its notes in the `release(vX.Y.Z)` commit body> and on <https://github.com/mrbizarro/phosphene/releases>, which is where the per-release-> record actually lives. The dated blockquote log at the top of this file is the engineering-> handoff, not a user changelog. v3.8.0 is written up here as well because a release that-> changes the install path deserves a line somebody can find with grep.--#### v3.8.3 — the install that hung Pinokio before it ever started-- **Symptom.** On Pinokio 8.0.40 a fresh install freezes at ~100% CPU immediately after- `git rev-parse --short HEAD`. No child process spawns, nothing is logged, and the only way- out is force-quitting Pinokio. Reported by **@davidaircloud** on a completely clean- Pinokio 8.0.40 + Phosphene 3.8.0 (#50, reopened after the v3.6.2 fix) and independently by- **@itrejomx** (#56), who saw the same stall before `uv venv` and fixed it locally by- splitting the payload into smaller steps.-- **Cause — the rule was right and the measurement was wrong.** @Morac2 bisected the ceiling- in #50: a 764-char command hangs, ~373 passes. v3.6.2 adopted *"no generated shell line over- 350"* and the issue was closed. But what Pinokio writes to the pty is not a line of our- source. `pinokiod/kernel/shells.js` `launch()` dispatches an **array** message one element- per shell, and a **string** message in ONE unchunked write (`shell.js:1911`) — and every- long payload in this repo is `[ ... ].join("\n")`, deliberately, so an `if/else` runs in a- single shell. Those were exactly the dispatches nobody was counting. The LTX venv step's- source lines were all under 110 chars and it handed Pinokio **1,417** characters in one go —- the exact number @davidaircloud measured himself, and the exact thing he fixed by moving the- body into a `.sh`.-- **Corroboration from Pinokio's own source.** `Shell.emit()` (shell.js:665-711) chunks- anything over 1024 chars into 256-byte pieces with a 10 ms gap, so the kernel already treats- large pty writes as unsafe; the `shell.run` dispatch path simply does not do it. A local pty- probe using Pinokio's own shell and args (`bash --noprofile --norc`, one unchunked write)- completes a 1,475-byte payload fine — so this is **not** a kernel tty limit, and dispatch- size is the only lever available from this side.-- **The fix.** Four oversized dispatches move into `scripts/pinokio/`, each step becoming one- short `bash …` line: the LTX venv check (1,417), the mflux image-engine pack (529), the H3- memory preflight (845) and the H3 Q8 engine build (595). Worst dispatch in the tree is now- **498**. Every script is a verbatim lift, run as `bash <path>` so no execute bit is involved,- keeping the `\n`-joined steps' no-`set -e` semantics. The vendored engine pin is unchanged- and still lives in the `.js` beside the notes that document it.-- **Proof.** Each old inline payload and its new script were run in byte-identical sandboxes- across every branch — healthy venv, broken venv, macOS 13 abort, mflux, H3 preflight at- 32 / 48 / 64 GB, Q8 already-built / build / skip — and compared on stdout and exit code.- 10/10 identical; the only difference is that bash's own diagnostic now names the script- instead of saying `bash`.-- **The gate.** `scripts/check_pinokio_scripts.js` loads each launcher module and models- `launch()` to find the real dispatches, failing anything over 500 chars. 500 sits above the- largest dispatch that has demonstrably shipped and worked (498) and well under the smallest- that has demonstrably hung (764). Six dispatches sit in the 352-498 band; they work today and- tightening toward 350 belongs in a feature release, not a hotfix.-- **Also — the H3 install pointed at a control that had moved (#58).** After a 75 GB download,- `install_h3.js` said *"the Video tab now has an Engine row"*. The engine control has been the- switcher in the **top right of the header** since the engine table landed; there is no Engine- row in the Video tab to find, and #58 is a user who installed H3 successfully and went- looking there. The notification and `docs/H3_ENGINE.md` now say where it is, and name the one- condition that genuinely hides it: the switcher only appears when more than one engine is- renderable, and on a sub-60 GB Mac `h3_capable()` stays false until the reduced-RAM Q8 pack- exists on disk (`dit_choice.q8_available` in `/status`).--#### v3.8.2 — the codec patch never ran, and nothing noticed-- **Symptom: none.** That is what made it dangerous. After updating to v3.8.1 the app reported- a finished update, the engine pin had moved, the version handshake was green — and- `video_vae.py` in site-packages was still upstream. Every render was encoded 4:2:0- `yuv420p`: no error, no warning, just blocky compression on faces and skin, which is the one- thing Phosphene patches the encoder to avoid.-- **Cause 1 — the run truncated.** Pinokio's own session log for a real v3.1.1 → v3.8.1 update- records steps 0–7 of 18 and then nothing. The last step executed was `certifi`, a plain- `pip install --upgrade`, whose output carried pip's *"ERROR: pip's dependency resolver does- not currently take into account all the packages that are installed"* block — a permanent- side effect of `mlx-vlm` being installed `--no-deps`, which makes pip's post-install- consistency pass complain after any step that actually changes something. pip still exits 0- (measured); the run ended anyway, and every step after it was skipped in silence. Confirmed- on that install: no `smolagents`, no `mflux`, no `mlx-teacache` — those steps had not run in- a long time either.-- **Cause 2 — the patch sat too late.** It was eleven steps down, behind litellm, smolagents,- mflux and the IC-LoRA fetches: all optional, all able to end the run before the one step- that is not optional.-- **Cause 3 — the patch script guessed.** `_find` walked a hardcoded list of relative paths- resolved against the working directory, so running it by hand from anywhere but the app root- reported `MISSING — target file not found` on an install whose file was sitting right there.-- **Fixes.** The codec patch now runs *immediately* after the uv reinstall that replaces- site-packages, before any optional step exists to truncate the run — and a gate enforces that- ordering. Every remaining plain-pip step in `update.js` is now a uv step (same installs, same- broken metadata, zero resolver-ERROR output — measured side by side); `install.js` was- already all-uv, which is why fresh installs patched correctly. `patch_ltx_codec.py` resolves- its target through the running interpreter's own import machinery — the file the panel will- actually import, editable install or not — with the path list kept only as a fallback,- anchored on the script's directory rather than the CWD. And after patching it re-reads the- resolved file, asserts both markers, and exits non-zero behind a banner if they are absent.-- **If you rendered anything on v3.8.1, re-render it after updating.** Those clips are 4:2:0.- Nothing else is affected: no re-download, no weight change, no pin change (still `871694d` /- `0.14.19+ltx25.1`).--#### v3.8.1 — the Update that could not be retried-- **Update / Install aborted at the video-engine pin, permanently.** Both paths move the- vendored `ltx-2-mlx` checkout with `git checkout <sha>`, and for an affected install that- line failed with `error: Your local changes to the following files would be overwritten by- checkout: packages/ltx-core-mlx/src/ltx_core_mlx/model/video_vae/video_vae.py`. Nothing in- the flow ever un-dirtied the file, so every retry died on the same line — including "click- Install again", the recovery we tell people to use.-- **Where the dirty file came from — every install, not a rare cohort.** `ltx-2-mlx` is a uv- *workspace*, and `install.js` installs its members with deps and without `--reinstall`, so uv- links them **editable**: site-packages gets `_editable_impl_ltx_core_mlx.pth`, not a copy.- `patch_ltx_codec.py` resolves its target through `VENV_ROOTS` — site-packages first,- `packages/ltx-core-mlx/src` as a fallback — finds no `ltx_core_mlx` directory in- site-packages, and patches the **git-tracked source**. A perfectly successful install- therefore ends with a modified tracked file, every time. (An install that *died* at the- package step lands in the same place for a different reason: nothing in site-packages at- all.) The `v0.14.8 → 871694d` pin move rewrites the very ffmpeg lines that patch edits, so- git refused to move the pin.-- **The fix.** Both `install.js` and `update.js` discard local edits in the vendored checkout- (`git reset --hard HEAD`, behind a guard that the shell really landed in that tree) before- moving the pin. The checkout is app-managed: models live in `../mlx_models`, the build- constraints in `../pip-build-constraints.txt`, and the only non-tracked thing inside it on a- real install is the ignored `env/` venv — which `reset --hard` does not touch. Update's own- `uv pip install --reinstall --no-deps` step then replaces the editable `.pth` links with real- copies in site-packages, and the codec patch re-applies **there** — so the runtime imports a- patched `video_vae.py` and the vendored tree is left clean for the next pin move. General,- not SHA-specific: any modified tracked file that differs across a pin move is now cleared.-- **No model re-download, no weight change, no pin change.** The vendored pin is still- `871694d` / `0.14.19+ltx25.1`.+> record actually lives (there is no `CHANGELOG.md`). The dated blockquote log at the top of+> this file is the engineering handoff, not a user changelog. v3.8.0 gets an entry here+> because a release that changes the install path deserves a line somebody can find with grep.#### v3.8.0 — Storyboard, and the install that had been failing for everyone new-- **Storyboard tab** — a concept sentence is planned into a shot list by- `storyboard_planner.py` (running on the `gemma-3-12b-it-4bit` weights the panel already- downloads for `/prompt/enhance`, so the feature costs no new bytes), reviewed and edited by- the user, then rendered through the ordinary queue. Shots are shot GROUPED BY PIPELINE, not- in story order, because the warm helper holds one pipeline at a time. Plans are durable- under `state/storyboards/<id>/`; `/storyboard/export` writes a `storyboard.md` + `.json`.-- **The face law** — the planner is structurally prevented from writing silhouettes, backs of- heads and out-of-frame faces unless the brief asked for them in so many words. `face` is a- closed enum and Python, not the model, writes the sentence. Person-silhouettes across a- 56-shot corpus: 5 → 0.+- **Storyboard tab** — a concept sentence is planned into a shot list, edited by the user, then+ rendered through the ordinary queue, grouped by pipeline rather than story order. The planner+ runs on the `gemma-3-12b-it-4bit` weights the panel already downloads, so the feature costs+ no new bytes. Plus the face law (`face` as a closed enum; person-silhouettes 5 → 0 across a+ 56-shot corpus).- **Install + Update fixed (no issue number — it hit everyone)** — hatchling 1.32.0 made- `readme = "../../README.md"` a hard error, and all three vendored `ltx-*` packages declare- exactly that. Every fresh install and every Update click had been dying at- `metadata-generation-failed` on every pinned tag since that release landed. Both paths now- pin the build backend through `pip-build-constraints.txt` (`hatchling<1.32`), and both use- uv to do it — the `PIP_CONSTRAINT` environment variable no longer works, because pip now- spawns its build-dependency install with `_PIP_IN_BUILD_IGNORE_CONSTRAINTS=1`.-- **#52, the dead update pill (@Morac2)** — the dirty-tree probe used `git status --porcelain`,- which lists untracked paths, and installing the H3 pack *creates* untracked paths. The- update check was suppressed forever. Both probes now pass `-uno`; `minimax-h3-mlx/`,- `cache/` and `logs/` are root-anchored in `.gitignore`.-- **#46, audio start offset (@blackest)** — both A2V pipelines had accepted `audio_start_time`- all along; the panel never put a value on the job. Wired end to end (field → `make_job`- allowlist → `a2v_params`), clamped through a new `_safe_float`, and stored in the sidecar so- Load Params restores it. The duration slider now warns past 241 frames instead of staying- silent — a warning, deliberately not a hard cap.-- **#53, stretched first keyframe (@Morac2)** — upstream hard-stretches keyframe 0 onto the- canvas because it treats it as the geometry anchor, and the panel only ever sends keyframe 0,- so no setting could avoid it. The reference is now cover-cropped to the exact canvas first,- which makes upstream's own early return fire and skip the resize entirely. Best-effort: any- failure falls back to today's behaviour rather than killing the render.-- **H3 menu opens at 46 GB** — v3.7.0 shipped the ~27 GiB Q8 H3 lane and opened the engine to- 48 GB Macs, but `pinokio.js` still gated the menu entry at 60 GB, so the users it was built- for could not see it.-- **Model-version registry + the conditioning seam** — one declarative table describes a- generation's packs, cap tiers, text encoder and HQ weight filenames, and every consumer reads- it instead of a module-level constant. This is what turns "which LTX generation" into a- curation decision rather than a rewrite.-- **Analytics truth pass** — `docs/ANALYTICS.md` and the README had been claiming "no- telemetry" and "a fresh clone sends nothing" after the build started shipping a working- PostHog key. Eleven sites corrected, and the guard suite that should have caught it was red- and is now green and mutation-tested. Also: clearing the key in Settings is **not** an off- switch, and every surface now says so — the toggle and `PHOSPHENE_ANALYTICS_DISABLED=1` are- the only two.-- **Every event now tells PostHog not to locate it** — `$geoip_disable`, a truthy `$ip`- placeholder and `$process_person_profile: False`, spread last so no call site can override- them. Nothing was removed, because no location code ever existed here; what changed is that- the receiver's default derivation is now suppressed instead of merely unmentioned.-- **Vendored MLX port re-pinned** to the fork build `871694d` (`0.14.19+ltx25.1`). Every LTX-2.5- flag defaults to its 2.3 value, so 2.3 renders exactly what it rendered before.+ `readme = "../../README.md"` a hard error and all three vendored `ltx-*` packages declare+ exactly that, so every fresh install and every Update click had been dying at+ `metadata-generation-failed` on every pinned tag. Both paths now pin the build backend+ through `pip-build-constraints.txt` (`hatchling<1.32`) **via uv** — `PIP_CONSTRAINT=` is dead+ on modern pip. The update.js half of that was found during release validation and did not+ exist on this branch until the port-back; dev's Update path was broken for every beta user.+- **#52 dead update pill (@Morac2)**, **#46 audio start offset (@blackest)**, **#53 stretched+ first keyframe (@Morac2)**, H3 menu opening at 46 GB, the model-version registry, and the+ analytics truth pass + geoip kill. Full text in the release commit body.+- **Shipped WITHOUT LTX-2.5** — the `ltx25` entry was curated out of the release tree and 2.3+ is the only generation there. That curation is public-only; this branch keeps 2.5 as the+ default until v4.0.#### v3.0.6 — deep-review hardening- **HDR action un-deaded** — `generate_hdr` referenced undefined `HELPER_LOW_MEMORY` → NameError killed every HDR job. One-token rename to `LOW_MEMORY` (`mlx_warm_helper.py`).diff --git a/download_q8.js b/download_q8.jsindex 7e061d6..ac8ee36 100644--- a/download_q8.js+++ b/download_q8.js@@ -1,55 +1,35 @@module.exports = {- // On-demand Q8 download for the High quality tier.- // ~37 GB, resumable. The panel auto-detects when it lands and unlocks- // the High pill in the Quality picker.+ // On-demand Q8 download — the optional pack trained characters and voices+ // need. The panel auto-detects when it lands and unlocks the surfaces that+ // depend on it.//- // Y1.024: this used to be advertised as ~25 GB but actually pulled- // ~82 GB — dgrauet's Q8 repo hosts THREE transformer variants- // (transformer-dev, transformer-distilled, transformer-distilled-1.1),- // TWO distilled-LoRA variants (-384 and -384-1.1), the x1.5 spatial- // upscaler we don't wire, and the temporal upscaler we don't wire.- // `hf download` with no filter grabs all of them. Reported by- // @ContentForAll as "download stalls past 50 GB" — there was no stall;- // the bundle really was ~82 GB and we were lying about the size.- // The --include allowlist below pulls only the 8 files the panel- // loads at runtime; total ~37 GB. Keep in sync with- // required_files.json → repos[q8].download_include.+ // v4.0: this fetched dgrauet/ltx-2.3-mlx-q8 and advertised "~37 GB". Both+ // were 2.3 facts, and 2.5 is the generation the panel serves now. The body+ // moved to scripts/pinokio/q8_weights.sh (see its header for why the LANE had+ // to move with the copy, and why the 2.5 packs come from a GitHub release+ // rather than `hf download`).+ //+ // The size claim is the measured one: required_files.json → q8_25 is+ // 30.02 GB. The High add-on is a SEPARATE 29.50 GB download and is not+ // fetched here — it is one more click in Settings → Models, and folding it in+ // would hold a complete pack hostage to twice the wait.run: [{method: "notify",params: {- html: "<b>Downloading Q8 model (~37 GB)…</b><br>This is the High quality tier (Q8 two-stage HQ + TeaCache and FFLF keyframing). Resumable if interrupted."+ html: "<b>Downloading the LTX-2.5 Q8 weights (~30 GB)…</b><br>8-bit weights instead of 4-bit. This is what trained characters and voices need — on the base pack most of a trained face is lost before the first frame. Resumable if interrupted."}},{method: "shell.run",params: {- venv: "ltx-2-mlx/env",- // Y1.022: HF_HUB_ENABLE_HF_TRANSFER=1 turns on the Rust downloader- // (~5-10× faster on the 37 GB Q8 bundle). hf_transfer is added by- // install.js / update.js. Falls back to plain Python downloader- // with a warning if the package isn't on disk for any reason.- env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },- message: [- // One command over shell line-continuations: Pinokio 8.0.x hangs on- // very long single lines (#50), and trailing backslashes keep this a- // single hf invocation.- [- "hf download dgrauet/ltx-2.3-mlx-q8 --local-dir mlx_models/ltx-2.3-mlx-q8 \\",- " --include '*.json' --include 'transformer-dev.safetensors' \\",- " --include 'connector.safetensors' \\",- " --include 'ltx-2.3-22b-distilled-lora-384.safetensors' \\",- " --include 'vae_decoder.safetensors' --include 'vae_encoder.safetensors' \\",- " --include 'audio_vae.safetensors' --include 'vocoder.safetensors' \\",- " --include 'spatial_upscaler_x2_v1_1.safetensors'",- ].join("\n")- ]+ message: "bash scripts/pinokio/q8_weights.sh"}},{method: "notify",params: {- html: "<b>Q8 ready.</b><br>The High quality option will unlock automatically in the panel within a few seconds. FFLF keyframing also requires Q8 and is now usable."+ html: "<b>Q8 ready.</b><br>Characters and voices now render at full strength. The High tier needs one more download — the High add-on (~29.5 GB) — in Settings → Models."}}]diff --git a/install.js b/install.jsindex b685af8..8e4ac64 100644--- a/install.js+++ b/install.js@@ -145,7 +145,7 @@ module.exports = {// Idempotent — works on a fresh clone (already on the cloned// branch's tip) AND on a re-install where the clone exists.// 2026-08-12 — THE PIN IS NOW A FORK BUILD, NOT AN UPSTREAM TAG.- // Vendored: mrbizarro/ltx-2-mlx `feat/ltx-2.5` @ 871694d, which is+ // Vendored: mrbizarro/ltx-2-mlx `feat/ltx-2.5` @ e6be9d6, which is// v0.14.19 (1192051) plus the LTX-2.5 port — keyframe pos-emb, the// vendored Gemma 4 tower, the Euler-ancestral sampler, the duration// head. dgrauet has no 2.5 branch; if he ports it we drop ours and@@ -157,37 +157,52 @@ module.exports = {//// Every 2.5 flag defaults to its 2.3 value, so an unversioned// checkpoint builds exactly what it built before — proven here by- // 802/22 on the vendored suite, a byte-identical job-dict capture- // across 18 form shapes, and a real 2.3 draft render.+ // 876/22 on the vendored suite, a byte-identical job-dict capture+ // across 18 form shapes, and THREE real 2.3 draft renders whose mp4s+ // are sha256-identical to the one recorded before any of this work+ // (three arms, the last of which renders out of the INSTALLED+ // packages with no PYTHONPATH override — i.e. the thing a user+ // actually runs).//- // The packages report `0.14.19+ltx25.1`, and `_LTX_EXPECTED_VERSION`+ // What this pin CHANGES, and only on 2.5: the Euler-ancestral sampler+ // is finally reached (it had zero callers, so every prior 2.5 render+ // used the 2.3 Euler step), and stage 2 starts at the vendor's 0.85+ // instead of 2.3's 0.909375. Both are keyed off the checkpoint's own+ // model_version, which is why 2.3 can be byte-stable across a change+ // this large.+ //+ // The packages report `0.14.19+ltx25.2`, and `_LTX_EXPECTED_VERSION`// in mlx_warm_helper.py must equal that string. The local segment is// the ONLY thing distinguishing this tree from upstream v0.14.19 at// runtime — the release segment is deliberately unchanged. Move the// two together.+ // 2026-08-13 (v4.0) — THE PIN IS A TAG, AND IT NO LONGER LIVES IN A+ // LAUNCHER SCRIPT. Both lanes now call the one implementation in+ // `scripts/pinokio/ltx_checkout.sh`, which holds the literal:+ //+ // v0.14.19+ltx25.3 on mrbizarro/ltx-2-mlx+ //+ // Two reasons, both structural. (1) A SHA on a branch is not a pin:+ // v3.8.x fetched `feat/ltx-2.5` and checked out a SHA that the branch+ // head had ALREADY moved past, so one rebase upstream would have+ // stranded every existing install with an un-fetchable pin and a dead+ // Update button. (2) A pin written in `update.js` can only ever move+ // ONE CLICK LATE — Pinokio loads that file before our own step pulls+ // the repo — so it has to live in the post-pull tree. install.js has+ // no such constraint but shares the file anyway: before v4.0 the two+ // lanes carried byte-identical copies of this block, and a duplicated+ // fix is a fix that half-lands.+ //+ // The packages report `0.14.19+ltx25.3`, and `_LTX_EXPECTED_VERSION`+ // in mlx_warm_helper.py must equal that string. The local segment is+ // the ONLY thing distinguishing this tree from upstream v0.14.19 at+ // runtime — the release segment is deliberately unchanged. Move the+ // two together. `node scripts/check_ltx_pin.js` is the gate that keeps+ // this comment, the shell script and the helper constant in agreement.{method: "shell.run",params: {- path: "ltx-2-mlx",- message: [- "git fetch --tags origin",- "git remote get-url fork > /dev/null 2>&1 || git remote add fork https://github.com/mrbizarro/ltx-2-mlx.git",- "git fetch fork feat/ltx-2.5",- // 3.8.1 HOTFIX — the same guard as update.js, and it matters here- // too. ltx-2-mlx is a uv workspace, so the package step below links- // its members EDITABLE; patch_ltx_codec.py (further down this file)- // therefore lands on the git-tracked source instead of- // site-packages, and every successful install leaves this tree with- // a modified video_vae.py. "Click Install again" — the recovery we- // tell people to take — then aborts right here with "Your local- // changes ... would be overwritten by checkout", and no retry can- // clear it. The tree is app-managed: nothing user-owned lives in it,- // and reset --hard leaves the ignored env/ venv alone. See update.js- // for the full rationale.- "if [ -f packages/ltx-core-mlx/pyproject.toml ]; then echo 'vendored tree is app-managed; discarding local edits before the pin move:'; git status --porcelain | head -20; git reset --hard HEAD; else echo 'WARN: not the vendored ltx-2-mlx tree - skipping reset'; fi",- "git checkout 871694ddaa09c1598d663a49005a2f91ae6b4ed2",- "git rev-parse --short HEAD"- ]+ message: "bash scripts/pinokio/ltx_checkout.sh"}},@@ -274,8 +289,31 @@ module.exports = {// metadata-generation-failed). uv resolves the build backend fresh// from PyPI into an isolated env, so from the day 1.32.0 shipped// this step failed for every NEW install on every pinned tag. See- // pip-build-constraints.txt; update.js carries the pip equivalent.+ // pip-build-constraints.txt; update.js runs the same uv command+ // (it used to spell it `PIP_CONSTRAINT=`, which modern pip ignores+ // by design — one lane now, one failure mode)."uv pip install --python env/bin/python --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer",+ // v4.0 — THE SECOND PASS IS THE POINT, and it closes a trap that has+ // shipped since the workspace landed. `ltx-2-mlx` is a uv WORKSPACE:+ // the line above (with deps, without --reinstall) links its members+ // EDITABLE. site-packages gets `_editable_impl_ltx_core_mlx.pth`+ // instead of a copy, so `import ltx_core_mlx` resolves to+ // `packages/ltx-core-mlx/src/...` — the GIT-TRACKED source. The codec+ // patch further down then finds no ltx_core_mlx directory in+ // site-packages and patches the tracked file, which is why a+ // PERFECTLY SUCCESSFUL install ended with+ // M packages/ltx-core-mlx/src/.../video_vae.py+ // every single time — and why the v3.8.0 pin move hit "your local+ // changes would be overwritten by checkout" for the whole fleet.+ //+ // v3.8.1 made the pin move survive that (reset --hard first) and+ // v3.8.1's own notes filed this as the follow-up: cure the cause, so+ // a FRESH install no longer starts dirty. `--reinstall --no-deps`+ // replaces the .pth links with real copies and re-resolves nothing;+ // it is the exact command update.js has run for many releases, so+ // the end state is one every install already converges to on its+ // first Update. One lane, one runtime shape.+ "uv pip install --python env/bin/python --reinstall --no-deps --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer",// Auto-caption (Gemma 3 12B via mlx-vlm) needs the mlx-vlm// package. Pinned to 0.4.4 — caption_with_gemma.py's import// surface (load, generate, prompt_utils.apply_chat_template)@@ -384,29 +422,6 @@ module.exports = {// upscalers we don't use. Without filters `hf download` grabs the full// 56 GB tree; the panel only needs ~20 GB. Keep this list in sync with// required_files.json → repos[q4].download_include.- {- method: "shell.run",- params: {- venv: "env",- path: "ltx-2-mlx",- // Y1.022: HF_HUB_ENABLE_HF_TRANSFER=1 enables the Rust accelerator,- // ~5-10× faster on 20 GB. Falls back gracefully if hf_transfer- // isn't yet on disk (warning + plain Python downloader).- env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },- message: [- // Short lines over shell continuations — Pinokio 8.0.x hangs on very- // long single lines (#50); still one hf invocation.- [- "hf download dgrauet/ltx-2.3-mlx-q4 --local-dir ../mlx_models/ltx-2.3-mlx-q4 \\",- " --include '*.json' --include 'transformer-distilled.safetensors' \\",- " --include 'connector.safetensors' \\",- " --include 'vae_decoder.safetensors' --include 'vae_encoder.safetensors' \\",- " --include 'audio_vae.safetensors' --include 'vocoder.safetensors' \\",- " --include 'spatial_upscaler_x2_v1_1.safetensors'",- ].join("\n")- ]- }- },// ---- (no transformer.safetensors symlink needed on HEAD — 0.2.0 reads// split_model.json to resolve transformer-distilled.safetensors.@@ -425,6 +440,46 @@ module.exports = {}},+ // ---- Download LTX-2.5, the DEFAULT generation (~28 GB) ----------------+ // SHIP-BLOCKER, closed 2026-08-12. LTX-2.5 became the default generation+ // while nothing in this file downloaded it: `q4_25` and `gemma4_25` name+ // `mrbizarro/...` HuggingFace repos that DO NOT EXIST (our HF token is+ // read-only, and these packs are our own quantisation of a gated upstream).+ // On the machine that built them the default lane worked; on a FRESH+ // INSTALL there were no weights at all for the generation the panel boots+ // into. That is what these two steps fix.+ //+ // Not `hf download`: the packs are mirrored as assets on a release of the+ // public repo, the same lane the sample-character LoRA takes. Files over+ // GitHub's 2 GiB asset cap are published as 1.9 GB shards;+ // scripts/fetch_pack_release.py downloads them, checks each shard's+ // sha256, reassembles, and only renames a file into place once the+ // whole-file sha256 matches the published manifest. It is resumable and+ // idempotent, so Resume Install re-runs it for the price of a read pass+ // and re-downloads only what is actually missing.+ //+ // Both packs are REQUIRED, not optional. 2.5 conditions on its own Gemma 4+ // fine-tune and cannot use the Gemma 3 encoder above — the mismatch does+ // not raise, it silently encodes wrongly — so the two are fetched together+ // and the install stops if either fails, instead of marching on to a panel+ // that cannot render.+ //+ // 3.8.3: body moved to scripts/pinokio/ltx25_weights.sh. It was a+ // "\n"-joined string — ONE 748-char dispatch, not the short lines the old+ // note here claimed, because that is not what Pinokio writes to the pty.+ {+ method: "notify",+ params: {+ html: "<b>Downloading LTX-2.5 (~27 GB)…</b><br>The engine and its text encoder — this is what the panel renders with. Resumable: if this stops, run Install again and it picks up where it left off.<br><br>A full install is about <b>37 GB</b>: this, the Gemma 3 language model that Enhance and the Storyboard planner run on, and three small control LoRAs. <b>LTX-2.3 is no longer downloaded</b> — it is only needed to TRAIN a character, and the panel offers it in Settings → Models the moment you want it."+ }+ },+ {+ method: "shell.run",+ params: {+ message: "bash scripts/pinokio/ltx25_weights.sh"+ }+ },+// ---- Image-engine pack (mflux: Ideogram 4 + Qwen-Edit) ----------------// 2026-06-13: Ideogram 4 + the visual text-placement editor are headline// features now, so the mflux image-engine runner ships by default insteaddiff --git a/install_h3.js b/install_h3.jsindex 183a2df..546f174 100644--- a/install_h3.js+++ b/install_h3.js@@ -86,13 +86,46 @@ module.exports = {// Pin to the branch on every run, so Resume Install after a partial clone// lands on the same code the panel was validated against.+ //+ // v4.0 — TWO BUGS OF THE SAME CLASS AS THE LTX LANE, both filed in the+ // v3.8.1 hotfix notes (§9.3) and the 2026-08-13 sweep (§8.6) and fixed here.+ //+ // 1. THE FETCH NEVER ADVANCED ANYTHING. `git fetch origin <branch>` writes+ // FETCH_HEAD and updates `refs/remotes/origin/<branch>`; the following+ // `git checkout <branch>` resolves the LOCAL branch, which the clone+ // created once and which nothing has moved since. So every H3 user has+ // been pinned to whatever the branch tip was on the day they first+ // installed, and re-running the installer could never bring them+ // forward. `--force -B <branch> FETCH_HEAD` makes the local branch point+ // at what was actually fetched, which is what "pin to the branch on+ // every run" always claimed to do.+ //+ // 2. A DIRTY TREE BLOCKED THE CHECKOUT, silently, the same way it killed+ // the LTX pin move for the whole fleet on 3.8.0. Nothing of ours patches+ // this tree today, which is exactly why it is worth guarding now rather+ // than after the first user reports it: `minimax-h3-mlx/` is+ // app-managed, its weights live outside it in ../mlx_models/hailuo-h3,+ // and its venv is ignored, so reset --hard costs nothing and cannot+ // touch user content. Same guard shape, same reasoning, one class.+ // The guard tests `minimax_h3_mlx/` — the package directory, verified+ // present at the branch tip; this repo has no root pyproject.toml, so+ // the LTX lane's marker would have been wrong here.+ //+ // CONSEQUENCE, STATED RATHER THAN BURIED: an existing H3 user who re-runs+ // the installer now MOVES FORWARD to the branch tip instead of staying on+ // their install-day snapshot. That is what the step always said it did.+ // It is safe because the panel PROBES the installed runner for its+ // capabilities (`h3_supports_chain()`, `h3_supports_chain_prompts()`)+ // rather than assuming them, so a runner that gains or loses a flag is+ // handled by the UI instead of dying in argparse 30 s into a render.{method: "shell.run",params: {path: "minimax-h3-mlx",message: [- "git fetch origin " + H3_BRANCH,- "git checkout " + H3_BRANCH,+ "git fetch --force origin " + H3_BRANCH,+ "if [ -d minimax_h3_mlx ]; then git reset --hard HEAD; else echo 'WARN: not the H3 tree - skipping reset'; fi",+ "git checkout --force -B " + H3_BRANCH + " FETCH_HEAD","git rev-parse --short HEAD"]}diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex ded18b8..43a6632 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -314,10 +314,16 @@ MODEL_VERSIONS: tuple[dict, ...] = ("label": "LTX-2.3","engine_id": "ltx","config_key": "ltx-2.3",- # The default — and in this release the only registered generation.- # Every character LoRA in the wild is trained against 2.3, and its two- # packs are the ones users can actually download today.- "default": True,+ # Characters render on the two-stage HQ path here: 2.3's character LoRAs+ # are dev-trained and distilled inference barely locks identity. Stated+ # rather than defaulted, so the two generations' answers sit side by+ # side and neither is an accident. See character_render_quality().+ "character_quality": "high",+ # No longer the default (2026-08-12 — 2.5 is the standard), but still+ # fully installed and selectable with LTX_MODEL_VERSION=ltx23. Existing+ # workflows must not break, and the character LoRAs are trained against+ # this generation until they are retrained.+ "default": False,"cap_tiers": ("q4", "q8"),# The text encoder is part of the generation, not of the install.# 2.3 conditions on stock Gemma 3; 2.5 conditions on its own Gemma 4@@ -368,20 +374,129 @@ MODEL_VERSIONS: tuple[dict, ...] = (},),},- # --- LTX-2.5 is NOT registered in this release ------------------------ # 2.5 renders through the panel (the vendored ltx-2-mlx pin carries the- # port) but its weight packs are not publicly downloadable yet: `q4_25`,- # `q8_25` and `gemma4_25` are our own quantisations of a gated upstream,- # and the public mirror is still being uploaded. Registering a version- # here puts its packs on the Models page with a live Download button and- # makes `kind: "base"` packs mandatory for the install to read complete —- # so a fresh install would boot into a generation it cannot fetch.- #- # The registry seam exists precisely so this is a curation, not a revert:- # the 2.5 entry lives on the development line, and the packs' own- # `required_files.json` rows come back with it. Re-registering is adding- # one dict here plus its three repo entries — nothing else in the panel- # is 2.5-aware, because every consumer reads this registry.+ {+ # LTX-2.5. Registered but NOT default: selected with+ # LTX_MODEL_VERSION=ltx25.+ #+ # 2026-08-12: this now RENDERS through the panel. The vendored+ # ltx-2-mlx pin moved from v0.14.19 to the fork build e6be9d6, which+ # is where keyframes_abs_pos_embedding, the Gemma 4 tower and the+ # ancestral sampler live. Proven end to end on an isolated test+ # instance: 2.5 q4 pack + Gemma 4 encoder, real face-forward prompt+ # through the normal Video-tab form, video and audio both intact.+ #+ # It is also now the DEFAULT generation — 2.5 is the standard, 2.3+ # stays installed and selectable rather than being retired.+ #+ # SHIPPING GATE, not satisfied yet: `q4_25` / `q8_25` / `gemma4_25`+ # name mrbizarro HF repos that DO NOT EXIST PUBLICLY. Our HF token is+ # read-only and the mirror is still open work. On a machine that+ # already has the packs (this one) the default lane is correct; on a+ # FRESH install it has no weights, because install.js hardcodes its+ # download steps and none of them fetch 2.5. Publish the packs and add+ # those steps BEFORE this default reaches users.+ #+ # Both tiers ship now. The q8 pack was built 2026-08-12 and cleared the+ # same gates the q4 pack did — 20,595,260,317 B against the 2.3 q8+ # pack's 20,597,189,549 B (−0.0094 %), 1632 modules, 7355 tensors,+ # group_size 64, loader round-trip detecting bits=8 — and the whole+ # −1,929,232 B delta is accounted for to the byte by 2.5's 96 absent+ # FFN biases, its one extra keyframe embedding and the header growth.+ # So `cap_tiers` gains "q8" here, which is precisely the one-line+ # change this comment used to promise.+ "id": "ltx25",+ "label": "LTX-2.5",+ "engine_id": "ltx",+ "config_key": "ltx-2.5",+ "default": True,+ # Which pipeline a TRAINED CHARACTER renders on. On 2.3 this is "high",+ # because its character LoRAs are dev-trained and distilled inference+ # barely locks identity. On 2.5 the reasoning INVERTS: the recipe the+ # owner graded — "insane quality", voice PASS by ear — is q8 + the+ # DISTILLED pipeline at 1024x576x121, and every graded 2.5 character+ # clip in the campaign ran that path. Forcing "high" would route+ # characters onto a pipeline nobody has graded them on AND charge a+ # 29.5 GB add-on for a result the q8 pack already delivers, in 139 s+ # instead of 246 s. It lives in the registry so the two generations do+ # not each own a copy of the rule and the markup never decides it.+ "character_quality": "balanced",+ # NOT optional and NOT interchangeable with 2.3's. 2.5 conditions on a+ # Gemma 4 12B fine-tune (`gemma4_unified`); the vendored tower refuses+ # to build it from anything else. The trap is that Gemma 3 12B does+ # not fail loudly here: 3840 x (48 + 1) = 188160 is the projection+ # width BOTH towers produce, so a 2.5 DiT fed Gemma 3 hidden states+ # loads, runs, and returns plausible garbage with no shape ever+ # disagreeing. Verified the hard way — the first 2.5 render through+ # this panel was conditioned on gemma-3-12b-it-4bit and completed+ # happily in 44 s.+ "text_encoder": {"repo_key": "gemma4_25",+ "path": MODELS_DIR / "gemma4-12b-ltx25-q4"},+ # See the 2.3 entry for why this is named per generation. 2.5's+ # distilled LoRA carries alpha/rank 450 where 2.3's carries 384, and+ # the vendored pipeline resolves the file by this exact stem — so a+ # 2.5 pack holding a file named after 2.3 would be a lie the loader+ # believes, and a 2.5 pack relying on the vendored default would not+ # be found at all.+ #+ # 2026-08-12: both files now exist in the 2.5 q8 pack. Lightricks+ # shipped BOTH two-stage HQ components with 2.5 —+ # ltx-2.5-22b-dev-transformer-bf16 and+ # ltx-2.5-22b-distilled-lora-450-bf16 — which REFUTES the earlier+ # finding (ltx25_ab_lora.md §2A.1) that 2.5 had no High tier. That+ # finding was true of the eight files weights day happened to stage,+ # not of the release.+ "hq_weights": {+ "dev_transformer": "transformer-dev.safetensors",+ "distilled_lora": "ltx-2.5-22b-distilled-lora-450.safetensors",+ },+ # ...and WHERE those two files come from as a download. They are a+ # separate, later build from the rest of the q8 pack (the dev+ # transformer is 42 GB upstream), so they are their own download unit+ # -- `hq_25` in required_files.json -- that lands INSIDE the q8 pack+ # directory, because that is where they are loaded from by name.+ #+ # 2.3 declares no add-on and must not: it ships both files inside its+ # own q8 repo, so `hq_addon_missing()` returns [] for it and every gate+ # below behaves byte-for-byte as it did before the split.+ "hq_addon_repo_key": "hq_25",+ "cap_tiers": ("q4", "q8"),+ "packs": (+ {+ "quant": "q4",+ "role": "base",+ "repo_key": "q4_25",+ "path": MODELS_DIR / "ltx-2.5-mlx-q4",+ "hf_repo_id": "mrbizarro/ltx-2.5-mlx-q4",+ "serves_cap_tiers": ("q4", "q8"),+ # GitHub-release mirror: no checksum API, so expected hashes+ # come from phosphene_quant_manifest.json inside the pack.+ "verify_source": "manifest",+ },+ {+ # Same shape as 2.3's hq pack. Every non-transformer component+ # in it is sha256-identical to the q4 pack's copy (both are+ # verbatim copies of the same bf16 source, and that identity+ # was verified file by file before the bf16 tree was deleted),+ # which is the 2.3 policy: quantisation touches the DiT blocks+ # and nothing else.+ #+ # The text encoder is deliberately NOT doubled here. 2.3 serves+ # both tiers from one 4-bit Gemma 3, and 2.5 serves both from+ # the one 4-bit Gemma 4 that `gemma4_25` already lists. An+ # 8-bit Gemma 4 pack exists locally and is proven to load, but+ # registering it would add ~12.7 GB to a q8 install for a+ # quality delta nobody has looked at yet — that is the owner's+ # call, not a side effect of shipping the DiT.+ "quant": "q8",+ "role": "hq",+ "repo_key": "q8_25",+ "path": MODELS_DIR / "ltx-2.5-mlx-q8",+ "hf_repo_id": "mrbizarro/ltx-2.5-mlx-q8",+ "serves_cap_tiers": ("q8",),+ "verify_source": "manifest",+ },+ ),+ },)# Which version this panel is driving. Env override exists so a 2.5 pack can@@ -463,6 +578,34 @@ def _quant_for_repo_key(repo_key: str | None,return None+def pack_for_repo_key(repo_key: str | None) -> dict | None:+ """The pack entry backing this required_files.json repo key, searched+ across EVERY registered generation rather than only the active one.++ A repo key names exactly one pack in the whole registry (`q4` is 2.3's,+ `q4_25` is 2.5's), so this reverse lookup has a version-free answer — and+ every property that belongs to the PACK rather than to the current session+ must be read through here.++ DEFECT-2, and why the version-scoped lookup was wrong: `_pack_verify_source`+ resolved `version_pack(quant)` against the ACTIVE version, so the non-active+ generation's packs were not recognised as packs at all and fell through to+ the "hf-api" default. With 2.5 active the four answers happened to be right+ and two of them were right by accident; flip the default back to 2.3 with+ LTX_MODEL_VERSION=ltx23 and the 2.5 packs get sent to a HuggingFace repo+ that does not exist and never will, surviving only on `_expected_meta`'s+ empty-answer fallback to the manifest. That is one silent step from+ "verified" meaning "not checked" — the June-mosaic blind spot, restored by+ an env var."""+ if not repo_key:+ return None+ for v in MODEL_VERSIONS:+ for p in v.get("packs", ()):+ if p.get("repo_key") == repo_key:+ return p+ return None++def version_cap_tiers(version_id: str | None = None) -> tuple[str, ...]:return tuple(model_version(version_id).get("cap_tiers", ("q4",)))@@ -604,6 +747,10 @@ def _settings_defaults() -> dict:# Memory/speed policy. Defaults to Auto so 5 s clips keep the fast# full-decode path while long/high-pressure renders stay protected."memory_policy": DEFAULT_MEMORY_POLICY,+ # Live preview. On by default: it costs ~0.2 % of the render,+ # never changes the result, and it is what makes Stop early+ # possible at all.+ "live_preview": "on",# ---- Anonymous usage analytics -----------------------------------# Full contract in the "Anonymous usage analytics" section further# down this file, and the event-by-event schema in docs/ANALYTICS.md.@@ -856,6 +1003,15 @@ def _validate_settings_patch(patch: dict) -> tuple[dict, str | None]:return {}, f"unknown memory_policy: {policy}"out["memory_policy"] = policy+ if "live_preview" in patch:+ # Two states, and anything unrecognised is refused rather than+ # silently coerced — a settings field that accepts junk and means+ # "on" is how a user ends up with a setting they did not choose.+ lp = str(patch["live_preview"]).strip().lower()+ if lp not in ("on", "off"):+ return {}, f"live_preview must be on or off, got: {lp}"+ out["live_preview"] = lp+# ---- H3 DiT precision --------------------------------------------------# auto (RAM decides — the default), q8 (force the low-RAM pack: ~15 GiB# back for the OS on any machine), bf16 (force max quality where it fits).@@ -972,6 +1128,7 @@ def get_settings_public() -> dict:"models_card_dismissed": bool(s.get("models_card_dismissed", False)),"spicy_mode": bool(s.get("spicy_mode", False)),"memory_policy": s.get("memory_policy", DEFAULT_MEMORY_POLICY),+ "live_preview": str(s.get("live_preview", "on")),# Analytics. Same has_X-boolean treatment as the other secrets —# the keys themselves never come back over the wire. The install id# DOES come back: it's a random UUID with no meaning off this@@ -2002,6 +2159,27 @@ def _train_required_models() -> list[dict]:_FULL_DEV_MIN_BYTES = 15 * 1000**3items = [+ {+ # THE ASSUMPTION THAT EXPIRED. This function's own docstring says+ # "the rest of the Q4 stack (vae, audio, etc.) are already required+ # for inference so they should already be present" — true right up+ # until v4.0, when a fresh install stopped fetching LTX-2.3 at all.+ # The trainer runs against 2.3 and needs its VAE, audio VAE and+ # vocoder; without this row the Train tab would have looked ready+ # and failed at load time on a pack nobody told the user about.+ "key": "ltx23_base",+ "label": "LTX-2.3 base pack (training runs against 2.3)",+ "blurb": "The trainer runs against LTX-2.3, not 2.5 — it needs 2.3's "+ "VAE, audio VAE and vocoder. Your clips still render on "+ "LTX-2.5; this is training-only. A fresh v4.0 install does "+ "not download it, so it is fetched when you want to train.",+ "repo_id": "dgrauet/ltx-2.3-mlx-q4",+ "filename": "vae_decoder.safetensors",+ "local_dir": str(q4_local_dir),+ "size_gb": 20.48,+ "ready": _file_present(q4_local_dir, "dgrauet/ltx-2.3-mlx-q4",+ "vae_decoder.safetensors"),+ },{"key": "ltx_dev_transformer","label": "LTX-2.3 dev transformer (training-only, full precision)",@@ -2979,12 +3157,32 @@ def list_styles() -> list[dict]:# correspond to 5s / 7s / 10s / 15s at 24 fps. 15s pushes the helper# past its usual sweet spot but works fine — Mr Bizarro measured 9.5min for# 10s/241f on Q8 HQ, so 15s/361f extrapolates to ~14min.-_CHARACTER_DURATION_FRAMES = {- "5s": 121,- "7s": 169,- "10s": 241,- "15s": 361,-}+def _character_duration_frames() -> dict[str, int]:+ """The Characters tab's duration axis — DERIVED from LTX_LENGTHS.++ This was a fourth hardcoded vocabulary for one concept (`{5s:121, 7s:169,+ 10s:241, 15s:361}`), sitting beside the storyboard card's `[3,5,7,10]`, the+ Manual strip's free numeric field and H3's own table. It was honest — the+ tab is LTX-only and those frame counts are right on the 8k+1 grid — but four+ tables mean four things to keep in step, and the 7-second lie is what+ happens when one of them drifts.++ NOTE the shape change it implies: 15s LEAVES and 3s/20s ARRIVE, because the+ axis is now the one the engine actually publishes. 15 s was never on LTX's+ 8k+1 axis as a named rung anyway — 361 frames is 15.0 s at 24 fps and+ renders fine, so any sidecar carrying it still resolves through the+ compatibility entry below."""+ out = {l["key"]: int(l["frames"]) for l in LTX_LENGTHS.values()}+ # Every value this endpoint has ever accepted keeps resolving. 15s is the+ # one the shipped chip row offered and clips exist at it.+ out.setdefault("15s", 361)+ return out+++# Bound AFTER LTX_LENGTHS exists — see the assignment beside the tier table.+# Declared here as an empty dict so the name is defined for any import-time+# reader, and filled in one place rather than being re-derived per request.+_CHARACTER_DURATION_FRAMES: dict[str, int] = {}# Quality-to-resolution map for the Characters tab. Nothing else.# 2026-05-16 — Mr Bizarro's call: stop translating the user's request through@@ -2993,7 +3191,9 @@ _CHARACTER_DURATION_FRAMES = {# things the tab adds are the LoRA stack lookup and the duration→frames# / quality→resolution mappings._CHARACTER_QUALITY_RESOLUTION = {- "draft": (736, 416), # ~3:30 wall for 7s, Q8 HQ, lower per-frame detail+ # 704x384, not 736x416: both were off the 64-grid the two-stage lane snaps+ # to, so this chip advertised a canvas it never delivered either.+ "draft": (704, 384), # ~3:30 wall for 7s, Q8, lower per-frame detail"balanced": (1024, 576), # reserved for a real fast-but-quality-equal tier"high": (1024, 576), # locked production recipe}@@ -3672,8 +3872,7 @@ def text_encoder_dir(version_id: str | None = None) -> str:all. `MODEL_VERSIONS` described which DiT weights a generation loads whilethe encoder stayed a module-level constant pointing at Gemma 3, soselecting 2.5 moved the transformer and left the text tower behind — and- the mismatch is silent — a Gemma 3 tower hands a 188160-wide projection- to a generation that wants its own, and nothing raises."""+ the mismatch is silent (see the ltx25 entry's note on 188160)."""te = model_version(version_id).get("text_encoder") or {}return str(te.get("path") or GEMMA)@@ -3723,6 +3922,57 @@ def hq_weights(version_id: str | None = None) -> dict:return {k: str(names.get(k) or v) for k, v in _HQ_WEIGHTS_FALLBACK.items()}+def hq_addon_missing(version_id: str | None = None) -> list[str]:+ """Missing files of this version's HQ ADD-ON pack (bare filenames).++ Returns [] for a version that declares no add-on -- which is 2.3, and which+ is why the split is inert for it: 2.3 ships its dev transformer and+ distilled LoRA inside its own q8 repo, so `pack_missing_files("q8")` already+ accounts for them and this adds nothing.++ Checked against the Q8 PACK PATH, not the registry's `local_dir`, so+ `LTX_Q8_LOCAL` keeps working: the add-on has no directory of its own, it+ lands in the q8 pack beside the weights it is loaded with.+ """+ key = model_version(version_id).get("hq_addon_repo_key")+ if not key:+ return []+ repo = next((r for r in _repos() if r.get("key") == key), None)+ if not repo:+ return []+ base = pack_path("q8", version_id)+ missing = []+ for fname in repo.get("files", []):+ fpath = base / fname+ try:+ if not fpath.exists() or fpath.stat().st_size < _MIN_FILE_BYTES:+ missing.append(fname)+ except OSError:+ missing.append(fname)+ return missing+++def hq_surface_missing(version_id: str | None = None) -> list[str]:+ """Everything the two-stage HQ surface needs and doesn't have.++ High, Extend, Keyframe and A2V do not just point at the q8 pack -- they+ reach inside it and load two more files by name. Before the packs were+ split those two were listed in the q8 repo entry, so asking+ `q8_missing_files()` answered both questions at once; splitting them into+ their own download unit would have silently made every one of those gates+ wave through to a FileNotFoundError mid-render, which is the exact bug+ e870061 was written to end.++ So the gates ask THIS instead, and it is the union. Same names, same+ refusals, one more place they can come from.+ """+ missing = pack_missing_files("q8", version_id)+ for fname in hq_addon_missing(version_id):+ if fname not in missing:+ missing.append(fname)+ return missing++def ltx_model_dir(quant: str, version_id: str | None = None) -> str:"""Pack directory for a job spec, with the fallback the IC-LoRA / HDRsites hand-rolled four times: if the pack directory isn't on disk, hand@@ -3738,8 +3988,26 @@ def _canonical_layout() -> bool:False for the two shapes we must never second-guess: LTX_MODEL set to abare HF repo id (weights resolve through the HF cache) and LTX_MODELpointed at a directory the user assembled themselves. We have no- manifest for either, so completeness claims about them would be lies."""- return str(MODEL_ID).startswith("/") and str(MODEL_ID) == str(pack_path("q4"))+ manifest for either, so completeness claims about them would be lies.++ DEFECT-1, and it had been live since 2.5 became the default. This compared+ MODEL_ID against `pack_path("q4")` with no version_id — i.e. against+ whichever generation is ACTIVE. That was an identity while ltx23 was the+ only entry; from the day a second generation landed it compared the 2.3+ install path against the 2.5 pack path, which are never equal, so it was+ False on every stock install. It is the SOLE gate on ltx_pack_preflight(),+ so that function returned at line 1 and refused nothing: an incomplete pack+ rendered the June-2026 rainbow mosaic instead of naming the missing file —+ the exact two-week failure the preflight was written to end.++ The question it is asking is "is MODEL_ID the pack we installed, wherever+ it came from", and MODEL_ID is defaulted from Q4_LOCAL_PATH — a 2.3 path.+ So it must be compared WITHIN a version, against any generation's own q4+ pack, rather than against whatever happens to be default today."""+ mid = str(MODEL_ID)+ if not mid.startswith("/"):+ return False+ return any(mid == str(pack_path("q4", v["id"])) for v in MODEL_VERSIONS)def ltx_pack_preflight(quant: str, feature: str,@@ -3828,14 +4096,17 @@ def repo_status_list() -> list[dict]:for r in _repos():local_dir = r["local_dir"]if r.get("key") == "q8":- # DISPLAY convention only, deliberately left as a special case:- # this string is what /models and the model browser print, and- # q8 has printed the absolute path since LTX_Q8_LOCAL existed- # while every other repo prints the ROOT-relative one. Making- # them agree is a cosmetic change to a shipped surface, not part- # of the version seam — the seam is WHICH FILES in WHICH DIR, and- # that is registry-driven below.+ # This row printed an ABSOLUTE path while all nine of its siblings+ # printed a ROOT-relative one — a leftover from when LTX_Q8_LOCAL+ # was the only way to move a pack. Relative when it is inside the+ # app (the normal case), absolute only when the env var really has+ # pointed it somewhere else, which is the one time the full path is+ # the information.local_dir = str(Q8_LOCAL_PATH)+ try:+ local_dir = str(Q8_LOCAL_PATH.relative_to(ROOT))+ except ValueError:+ pass# Completeness is asked of the registry when this repo backs a# registered pack, so the answer is per-(version, pack) and a second@@ -3876,10 +4147,305 @@ def repo_status_list() -> list[dict]:"present_files": present,"missing_files": missing,"complete": not missing,+ # Does this row's download need the `hf` binary?+ #+ # The 2.3 packs come from HuggingFace via `hf download`; the 2.5+ # packs come from a GitHub release, fetched by scripts/+ # fetch_pack_release.py, which needs nothing but stdlib. The modal+ # used to gate EVERY row's button on hf_available, so an install+ # without `hf` could not start the download it is perfectly capable+ # of doing — and the modal's own header already told the user the+ # LTX-2.5 rows do not need it. Derived from the registry's `mirror`+ # block rather than a key list in JS, so a future mirrored pack is+ # right by construction.+ "needs_hf": not bool(r.get("mirror")),+ # WHICH GENERATION owns this row, and whether that is the one this+ # build renders with. Without it the modal called 2.3's base packs+ # "required" on a 2.5 install, with capability copy ("Drives+ # Quick / Balanced / Standard renders") that is simply false now —+ # and the footer's "Required: N/M" counted them, so §7.1's stated+ # first-visit contract was unreachable by construction.+ #+ # None = generation-neutral (the IC-LoRAs, the tiny decoder): those+ # are required or optional on their own terms, not a generation's.+ "generation": _repo_generation(r.get("key")),+ # `gemma` is 2.3's text encoder AND the prompt enhancer AND the+ # storyboard planner, on every generation — so it is genuinely in+ # use no matter which one renders, and badging it "previous+ # generation" would be as wrong as Storage offering to delete it.+ # Storage already carves out the same exception, for the same+ # reason; the two surfaces agree because the reason is the same one.+ "active": (r.get("key") == "gemma"+ or _repo_generation(r.get("key")) in (None, ACTIVE_MODEL_VERSION)),+ # A guest pack: `local_dir` is another repo's directory and the+ # files are loaded from there BY NAME. Downloading one into an+ # absent host produces a folder holding two files and nothing else,+ # so the UI states the dependency instead of enforcing it silently.+ "host_key": _repo_host_key(r),})return out+def _dir_size_bytes(base: Path) -> int:+ """Sum of every regular file under `base`. 0 when it isn't there."""+ total = 0+ try:+ for p in base.rglob("*"):+ try:+ if p.is_file() and not p.is_symlink():+ total += p.stat().st_size+ except OSError:+ continue+ except OSError:+ return 0+ return total+++# NOTE: the size formatter for this section is `_fmt_gb`, which already existed+# further down this file. This block deliberately does NOT define a second one —+# a duplicate was written here first and was silently shadowed by the existing+# definition (later binding wins at module level), which is the same+# "two definitions of one thing" class the tier tables and the subtitle writers+# were. One formatter, and it is decimal GB (n / 1e9).+#+# THE UNIT IS LOAD-BEARING. The Models modal prints `size_gb` from+# required_files.json, which is decimal GB (~30.02 GB for a pack `du -h` calls+# 28G). Storage sits directly under it in the same dialog, so if one section+# used binary GiB the two would disagree by 7 % about the same folder and it+# would read as a bug. Never mix in `du -h`.+++# What a pack is worth keeping FOR. Computed from things the panel already+# knows, not typed per row: the trainer preflight hardcodes 2.3's q8 + q4, and+# the IC-LoRA registry names ltx-2.3-* files, so removing 2.3 really does turn+# off Train and the four control-LoRA modes.+STORAGE_KEEP_IF = {+ # 2.3's keep-if clause. TRAIN CHARACTER IS THE WHOLE LIST, and the earlier+ # version of this sentence was wrong in a way that cost the user 20 GB: it+ # also named Colorize, Restore, Ingredients and HDR. Those four resolve+ # `ltx_model_dir("q4")`, which is the ACTIVE generation's base — they run on+ # 2.5 — and their control LoRAs are separate ~4 GB files in+ # mlx_models/loras/ic that the installer fetches regardless. Removing the+ # 2.3 pack does not touch them. Only the trainer genuinely needs it.+ # It used to be printed for whichever generation was inactive, so a user+ # pinned back with LTX_MODEL_VERSION=ltx23 was shown a row offering to+ # delete 80 GB of 2.5 with a sentence arguing that keeping 2.3 matters.+ # Keyed per generation now; see _storage_generation_note().+ "ltx23": ("Keep it only if you train characters — the Train tab trains "+ "against LTX-2.3. Nothing else needs it: your renders, and the "+ "Colorize, Restore, Ingredients and HDR modes, all run on "+ "LTX-2.5."),+ "hq_addon": ("Removing this turns off the High tier, Extend and Keyframes "+ "until you fetch it again."),+ "q8": ("Removing this means trained characters render approximate faces "+ "and voices."),+}+++def _storage_generation_note(vid: str) -> str:+ """Why keeping THIS generation might matter, or the honest default.++ A generation the product does not currently render with is still not+ interchangeable with any other: 2.3 carries the trainer and the control+ LoRAs, and 2.5 is what a user who unsets an env var will boot into with no+ weights. Saying "previous generation" about the newer one, under 2.3's+ keep-if sentence, was the shape of that bug."""+ if vid in STORAGE_KEEP_IF:+ return STORAGE_KEEP_IF[vid]+ ver = next((v for v in MODEL_VERSIONS if v["id"] == vid), None)+ label = (ver or {}).get("label", vid)+ if ver is not None and ver.get("default"):+ # The registry default: unset LTX_MODEL_VERSION and this is what boots.+ return (f"Keep it unless you are sure. {label} is what this build boots "+ f"into by default — it is only inactive because "+ f"LTX_MODEL_VERSION is set, and removing it leaves that default "+ f"lane with no weights.")+ return (f"{label} is not the generation this build is rendering with right "+ f"now. Removing it frees the space; re-installing it later is a "+ f"fresh download.")+++def storage_rows() -> list[dict]:+ """What can be reclaimed on this disk, and what deliberately cannot.++ A row exists for every registered pack whose version is NOT the active one,+ plus the two generation-scoped extras. SIZES COME FROM WALKING THE ACTUAL+ DIRECTORY, not from required_files.json's `size_gb`: the honest number is+ what is on THIS disk, a partial pack must not claim a full one's footprint,+ and the planning note's own inventory was already 3 GB out on 2.3's q4 half.+ Measuring the row is the whole argument."""+ rows: list[dict] = []+ active = ACTIVE_MODEL_VERSION+ seen_dirs: set[str] = set()++ for v in MODEL_VERSIONS:+ if v["id"] == active:+ continue+ dirs, nbytes = [], 0+ for pack in v.get("packs", ()):+ p = Path(pack["path"])+ if str(p) in seen_dirs or not p.is_dir():+ continue+ seen_dirs.add(str(p))+ dirs.append(p)+ nbytes += _dir_size_bytes(p)+ if not dirs:+ continue+ # "previous" is only true of a generation that came BEFORE the active+ # one. Pinned back to 2.3, calling 2.5 "previous generation" inverted+ # the product's own story and invited the user to delete the default.+ _order = [x["id"] for x in MODEL_VERSIONS]+ _is_older = (_order.index(v["id"]) < _order.index(active)+ if active in _order and v["id"] in _order else True)+ _suffix = "previous generation" if _is_older else "not the active generation"+ rows.append({+ "key": f"version:{v['id']}",+ "name": f"{v['label']} · {_suffix}",+ "paths": [str(d.relative_to(ROOT)) if d.is_relative_to(ROOT) else str(d)+ for d in dirs],+ "bytes": nbytes,+ "size": _fmt_gb(nbytes),+ "note": _storage_generation_note(v["id"]),+ # A generation that is only inactive because an env var says so is+ # NOT safe to offer for deletion: unset the var and the panel boots+ # into it with nothing on disk. The registry default is protected;+ # everything else is the user's to reclaim.+ "removable": not bool(v.get("default")),+ })++ # The High add-on has NO DIRECTORY OF ITS OWN — its local_dir IS the q8+ # pack's — so it sizes itself from the two filenames hq_weights() names and+ # removing it deletes exactly those two. Getting this wrong deletes the q8+ # pack, which is why it is a separate branch and not a directory walk.+ addon_key = model_version().get("hq_addon_repo_key")+ if addon_key and not hq_addon_missing():+ base = pack_path("q8")+ files = [base / n for n in hq_weights().values()]+ nbytes = sum(f.stat().st_size for f in files if f.is_file())+ if nbytes:+ rows.append({+ "key": addon_key,+ "name": f"{model_version()['label']} High add-on",+ "paths": [str(f.relative_to(ROOT)) if f.is_relative_to(ROOT) else str(f)+ for f in files],+ "bytes": nbytes,+ "size": _fmt_gb(nbytes),+ "note": STORAGE_KEEP_IF["hq_addon"],+ "removable": True,+ })++ # The ACTIVE generation's Q8 weights. Specified in §6.3 and missed in the+ # first pass — and it is the largest single reclaimable item for anyone who+ # does not use trained characters. Sized by walking the directory MINUS the+ # add-on's two files, which are their own row above: counting them twice+ # would advertise ~60 GB of reclaimable space where ~30 GB exists.+ q8_dir = pack_path("q8")+ if q8_dir.is_dir() and str(q8_dir) not in seen_dirs and not q8_missing_files():+ addon_names = set(hq_weights().values()) if addon_key else set()+ nbytes = 0+ for f in q8_dir.rglob("*"):+ try:+ if f.is_file() and not f.is_symlink() and f.name not in addon_names:+ nbytes += f.stat().st_size+ except OSError:+ continue+ if nbytes:+ rows.append({+ "key": (version_pack("q8") or {}).get("repo_key") or "q8",+ "name": f"{model_version()['label']} Q8 weights",+ "paths": [str(q8_dir.relative_to(ROOT)) if q8_dir.is_relative_to(ROOT) else str(q8_dir)],+ "bytes": nbytes,+ "size": _fmt_gb(nbytes),+ "note": STORAGE_KEEP_IF["q8"],+ "removable": True,+ })++ # Gemma 3 is NEVER offered. It is 2.3's text encoder AND the prompt enhancer+ # AND the storyboard planner, so removing it silently breaks Enhance and+ # Storyboard on every generation. Stating why something CANNOT go is part of+ # this section's job — a user hunting 7 GB should find the answer here+ # rather than delete it and file a bug.+ gemma3 = next((r for r in _repos() if r.get("key") == "gemma"), None)+ if gemma3:+ base = ROOT / gemma3["local_dir"]+ nbytes = _dir_size_bytes(base)+ if nbytes:+ rows.append({+ "key": "gemma",+ "name": "Gemma 3 12B",+ "paths": [gemma3["local_dir"]],+ "bytes": nbytes,+ "size": _fmt_gb(nbytes),+ "note": "Kept — this is also what Enhance and the Storyboard "+ "planner run on.",+ "removable": False,+ })+ return rows+++def storage_payload() -> dict:+ rows = storage_rows()+ reclaimable = sum(r["bytes"] for r in rows if r["removable"])+ try:+ free = shutil.disk_usage(OUTPUT).free+ except OSError:+ free = 0+ return {+ "rows": rows,+ "reclaimable": reclaimable,+ "reclaimable_label": _fmt_gb(reclaimable),+ "free_label": _fmt_gb(free),+ }+++def _repo_generation(repo_key: str | None) -> str | None:+ """Which model generation owns this repo, or None if it belongs to none.++ A pack, a text encoder or an HQ add-on belongs to exactly one generation.+ The IC-LoRAs and the tiny decoder belong to none — they are required or+ optional on their own terms, and calling them "previous generation" would+ be as wrong as calling 2.3's base "required" on a 2.5 build."""+ if not repo_key:+ return None+ for v in MODEL_VERSIONS:+ if any(p.get("repo_key") == repo_key for p in v.get("packs", ())):+ return v["id"]+ if (v.get("text_encoder") or {}).get("repo_key") == repo_key:+ return v["id"]+ if v.get("hq_addon_repo_key") == repo_key:+ return v["id"]+ return None+++def _repo_host_key(repo: dict) -> str | None:+ """The repo key whose directory this one installs INTO, when that is a+ different repo. None for every repo that owns its own directory.++ The HQ add-on is the only such entry today: its `local_dir` IS the q8+ pack's directory, which is correct (it loads from there by name) and is why+ it is a separate download unit rather than part of that pack."""+ key = repo.get("key")+ # ONLY a declared GUEST has a host. `publish_scope: "files"` is exactly the+ # flag that says "I am a set of files landing in someone else's folder, and+ # I must not claim that folder's sidecars" — so it is the right predicate.+ #+ # Sharing a directory is NOT sufficient, and assuming it was is a bug this+ # function had for one revision: the three IC-LoRAs all live in+ # mlx_models/loras/ic and would have named each other as hosts, so an+ # incomplete Colorize would have put "Needs Q8" on the Ingredients row.+ if not key or not repo.get("publish_scope"):+ return None+ mine = str(repo.get("local_dir") or "")+ if not mine:+ return None+ for other in _repos():+ if other.get("key") == key or other.get("publish_scope"):+ continue+ if str(other.get("local_dir") or "") == mine:+ return other.get("key")+ return None++# ---- Model integrity (corrupt/partial-weight detection) ----------------------# A truncated or corrupt safetensors decodes to garbage — the leading# *non-Metal* explanation for the "mosaic" / latent-grid output some users hit@@ -4305,11 +4871,12 @@ def _manifest_meta(base: Path) -> dict:def _pack_verify_source(repo_key: str | None) -> str:"""Where the expected SHAs for this repo come from — "hf-api" (default,- and what every 2.3 pack plus gemma and the IC-LoRAs use) or "manifest"."""- quant = _quant_for_repo_key(repo_key)- if not quant:- return "hf-api"- pack = version_pack(quant) or {}+ and what every 2.3 pack plus gemma and the IC-LoRAs use) or "manifest".++ Keyed off the PACK, across every generation (`pack_for_repo_key`), because+ where a pack's checksums live is a property of the pack, not of whichever+ generation happens to be active in this process."""+ pack = pack_for_repo_key(repo_key) or {}return pack.get("verify_source") or "hf-api"@@ -5757,6 +6324,47 @@ H3_CHAIN_PROMPT_HELP = (# file instead (no separator to collide with a prompt that contains '|||'), but# a hand-rolled curl may still post this form and it costs one split to accept.H3_CHAIN_PROMPT_SEPARATOR = " ||| "+# Why the voice runs hotter than the face. Same four-hop Python-owned path as+# H3_CHAIN_PROMPT_HELP (constant -> bootstrap key -> lazy textContent fill), for+# the same reason: the sentence explaining a mechanism lives beside the+# mechanism or it drifts from it.+LTX_VOICE_STRENGTH_HELP = (+ "The face and the voice are two separate trained files, and on a q8 pack "+ "they both land at nearly full strength. The face file was trained on still "+ "images, so the marks it leaves on the audio side carry no voice — but they "+ "are still there, and at equal strength they are louder than the voice "+ "file's. Running the voice a little hotter than the face is what makes it "+ "win. 1.4 is the first setting with real headroom; 1.2 is about even. Below "+ "1.0 the voice is mostly the face file's noise.")+# Why a trained character needs the Q8 pack.+#+# "Same render time either way" is MEASURED, not assumed: 1024x576x121,+# distilled 8+3, the same two LoRAs fused, seed 411774, both GPU locks held,+# 2026-08-13 — q4 168.7 s vs q8 171.2 s, a 1.5 % difference that is inside the+# run-to-run noise of a single render. The coordinator flagged this sentence as+# unverified; it is now the one claim here with a same-geometry pair behind it.+# WHAT THE THUMBNAIL IS, AND — the part that matters — WHAT IT IS NOT.+#+# §4.1 makes this a CONSTRAINT rather than a nicety: the preview is a+# composition monitor, not a face monitor. The tiny decoder is soft by design+# and the thumbnail is pooled to half at the Stage-2 grid. Faces are this+# project's metric, so a soft 96-px decode sitting next to a progress bar with+# nothing telling anyone not to judge a face from it is exactly how the feature+# starts costing quality decisions instead of saving time.+LTX_PREVIEW_HELP = (+ "This is a rough, fast decode of what the model has decided so far — the "+ "framing, the light, roughly where everything is. It is deliberately soft: "+ "judge the shot from it, never the face. Faces only resolve in the finished "+ "render. It costs a fraction of the render time, and the clip you get is "+ "byte-for-byte the clip you would have got with it switched off."+)++LTX_Q8_CHARACTER_HELP = (+ "Trained characters need the Q8 weights. The 4-bit base pack rounds most of "+ "a trained delta away before the first frame — about nineteen twentieths of "+ "it — so the trigger word still changes the picture and the face is not the "+ "face you trained. Same render time either way; Q8 is a bigger download and "+ "holds more in memory.")# Storyboard's `?` copy, on the same four-hop Python-owned path as# H3_CHAIN_PROMPT_HELP above and for the same reason: the sentence explaining a# mechanism has to live beside the mechanism or it drifts. It names no model and@@ -5775,18 +6383,18 @@ STORYBOARD_RAM_HELP = (STORYBOARD_ENGINE_HELP = ("You choose this once for the whole film, in the brief. On Auto each shot ""gets the engine that can actually render it: a shot cast with one of your "- "trained characters goes to LTX-2.3 — that is where character LoRAs load, "+ "trained characters goes to LTX — that is where character LoRAs load, ""and Hailuo H3 cannot stack one, so a cast shot on H3 would render a ""stranger — and every other shot goes to Hailuo H3, which renders dialogue, ""voices and sound together with the picture. Pick an engine by name and the "- "whole film goes there, except that a cast shot always stays on LTX-2.3. "+ "whole film goes there, except that a cast shot always stays on LTX. ""The chip on each card tells you which one that shot got. Changing the ""choice on a film that is already planned means re-planning it, because the ""two engines want their prompts written differently — that is why the same ""control is in the Re-plan box. Shots are rendered grouped by engine, so ""each model loads once instead of once per shot.")STORYBOARD_ENGINE_NOTE = "The plan picks the engine per shot — the chip on each card says which."-STORYBOARD_ENGINE_NOTE_NO_H3 = "Hailuo H3 isn't installed, so every shot renders on LTX-2.3."+STORYBOARD_ENGINE_NOTE_NO_H3 = "Hailuo H3 isn't installed, so every shot renders on LTX."# The Draft canvas renders at 0.25 MP. The H3 community's practical floor is# ~0.5 MP, and video STRUCTURE resolves in the last denoise step, so at 9 steps a# 0.25 MP pass is genuinely noisy: composition, motion and dialogue timing are@@ -5866,10 +6474,10 @@ H3_LOAD_SEC = 40.5H3_DECODE_SEC_PER_PX_FRAME = 90.5 / float(H3_REF_W * H3_REF_H * H3_REF_FRAMES)# Past this, an estimate stops being "how long until I can look at it" and starts# being "queue it and walk away". Same threshold the old 15 s / dense tiers used.-H3_ETA_BATCH_MIN = 25.0+ETA_BATCH_MIN = 25.0# Past THIS, minutes stop being readable. Native × 15 s is 136 minutes and# "~136 min" is a number nobody parses at a glance; "~2h 16m" is.-H3_ETA_HOURS_MIN = 60.0+ETA_HOURS_MIN = 60.0def _h3_aspect(w: int, h: int) -> str:@@ -5939,12 +6547,12 @@ def h3_estimate_minutes(w: int, h: int, window_frames: int, windows: int,return (windows * max(0, int(forwards)) * per_fwd + windows * fixed) / 60.0-def _h3_fmt_eta(minutes: float) -> str:+def _fmt_eta(minutes: float) -> str:""""~9 min", "~38 min · batch", "~2h 16m · batch". No decimals: the model isgood to a few percent and "~18.4 min" would claim precision it doesn'thave."""- tail = " · batch" if minutes >= H3_ETA_BATCH_MIN else ""- if minutes >= H3_ETA_HOURS_MIN:+ tail = " · batch" if minutes >= ETA_BATCH_MIN else ""+ if minutes >= ETA_HOURS_MIN:hrs = int(minutes // 60)mins = int(round(minutes - hrs * 60))if mins == 60:@@ -6179,11 +6787,11 @@ def _build_h3_tiers() -> dict[str, dict]:H3_TURBO_FORWARDS)# Turbo removes forwards; it can never make a shape slower.turbo_min = min(eta_min, turbo_min)- eta, eta_measured = _h3_fmt_eta(eta_min), False+ eta, eta_measured = _fmt_eta(eta_min), Falsehit = H3_MEASURED_ETA.get((q["key"], ln["key"], False))if hit:eta_min, eta, eta_measured = hit[0], hit[1], True- turbo_eta, turbo_measured = _h3_fmt_eta(turbo_min), False+ turbo_eta, turbo_measured = _fmt_eta(turbo_min), Falsehit = H3_MEASURED_ETA.get((q["key"], ln["key"], True))if hit:turbo_min, turbo_eta, turbo_measured = hit[0], hit[1], True@@ -6353,6 +6961,553 @@ def h3_fallback_tier(key: str) -> str:if cand and h3_cell_gate(cand)[0]:return cand["key"]return H3_TIER_DEFAULT+++# =============================================================================+# LTX tiers — the SAME two-axis grammar H3 already ships, generalised+# =============================================================================+#+# H3 got quality × length, per-cell measured ETAs, an honest `notes` list and an+# `unavailable` state because the owner said: "somebody may want to run the HQ+# 5s version for 10s, and it's now not possible from the UI." LTX had one axis+# and a free numeric Duration field beside a `Frames · 8k+1` box, and its two+# per-chip subtitles were written by two hand-rolled updaters printing numbers+# no measurement on 2.5 supported.+#+# This is the same table, not a similar one: same dict shape, same key set, same+# `offered` semantics, same measured-overrides-modelled rule, same `_fmt_eta`.+#+# THE COST MODEL. LTX's distilled lane is TWO STAGES and they are not the same+# price: stage 1 denoises a HALF-RESOLUTION latent, stage 2 the full one. A+# model that averaged them would misprice every cell whose stage split differs+# from the one it was fitted at, so the two stages are priced separately and the+# per-forward cost is a power law in packed rows — H3's shape, LTX's geometry.+#+# An LTX latent cell is 32×32 px (four times H3's 16×16) and the temporal VAE+# puts frames on the 8k+1 grid, so packed rows = (w/32)·(h/32)·((f−1)/8+1).+LTX_LATENT_CELL = 32++# The two anchors, both measured on THIS machine on 2026-08-13, both GPU locks+# held, MLX 0.31.1, M4 Max 64 GB, engine v0.14.19+ltx25.3:+#+# 1024×576×121, q8, distilled 8+3 171.2 s total − 26.2 s fixed = 145.0 s+# (the voice-ladder arm, rendered through the panel)+# 640×448×49, q4, distilled 8+2 39.31 s total − 13.0 s fixed = 26.3 s+# (the step-0 confirmation render through the panel, job j-19ffa750b91-001)+#+# Fitting A and the exponent to those two and then pricing a cell NEITHER of+# them is gives 142.8 s for balanced/5s/q8 at 8+2, against the 139.4 s the+# campaign measured for exactly that cell: 2.4 % out, on a cross-validation the+# fit never saw. That is the whole claim this model makes — good to a few+# percent, which is why `_fmt_eta` prints no decimals.+LTX_FWD_COEFF = 4.357242e-03+LTX_FWD_EXPONENT = 0.9620+# Load + text-encode, measured as the sum of the four load phases the render log+# prints (Gemma 3.8 + encode 3.2 + transformer 3.8 + decoders 0.1). Does not+# scale with the canvas.+LTX_LOAD_SEC = 10.9+# VAE decode + audio + mux, 15.3 s at 1024×576×121, linear in pixel-frames.+LTX_DECODE_SEC_PER_PX_FRAME = 15.3 / float(1024 * 576 * 121)+++def _ltx_latent_frames(frames: int) -> int:+ """Latent frames behind a delivered frame count on the 8k+1 grid at 24 fps.+ 73 → 10, 121 → 16, 169 → 22, 241 → 31, 481 → 61."""+ return max(1, (max(1, int(frames)) - 1) // 8 + 1)+++def _ltx_packed_rows(w: int, h: int, frames: int) -> int:+ """Latent cells the DiT attends over for this shape."""+ return max(+ 1,+ (int(w) // LTX_LATENT_CELL) * (int(h) // LTX_LATENT_CELL)+ * _ltx_latent_frames(frames),+ )+++def _ltx_forward_seconds(rows: int) -> float:+ """Seconds for ONE denoise forward at this sequence length."""+ return LTX_FWD_COEFF * max(1, int(rows)) ** LTX_FWD_EXPONENT+++def _ltx_half(v: int) -> int:+ """Stage 1's axis: half, floored onto the 32-px latent grid."""+ return max(LTX_LATENT_CELL, (int(v) // 2) // LTX_LATENT_CELL * LTX_LATENT_CELL)+++def ltx_estimate_minutes(w: int, h: int, frames: int,+ stage1_steps: int, stage2_steps: int,+ stage2_evals: int = 1) -> float:+ """Wall clock, in minutes, for an LTX render of this exact shape.++ `stage2_evals` is 2 on the res_2s HQ path, which evaluates the denoiser+ twice per stage-2 step (an anchor and a substep) — the same reason its live+ preview publishes every 2nd estimate. Every LTX estimate in the panel comes+ from this one function."""+ s1 = _ltx_packed_rows(_ltx_half(w), _ltx_half(h), frames)+ s2 = _ltx_packed_rows(w, h, frames)+ denoise = (max(0, int(stage1_steps)) * _ltx_forward_seconds(s1)+ + max(0, int(stage2_steps)) * max(1, int(stage2_evals))+ * _ltx_forward_seconds(s2))+ fixed = LTX_LOAD_SEC + LTX_DECODE_SEC_PER_PX_FRAME * int(w) * int(h) * int(frames)+ return (denoise + fixed) / 60.0+++# END-TO-END WALL CLOCKS actually observed, keyed+# (version, quality, length, quant). H3 keys its third element on `turbo`+# because that changes the forward count; LTX keys on `quant` because the pack+# decides which pipeline runs. A cell is only "measured" when the GEOMETRY+# MATCHES EXACTLY — same canvas, same frame count, same schedule. Everything+# else prints from the model above with `eta_measured: False`, and says so.+#+# THREE HONEST ROWS BEAT TWENTY INVENTED ONES. In particular Quick and Standard+# have no measurement at their OWN geometry: the only draft-tier number in the+# campaign is 768×448×49 at 50.1 s, a different canvas AND a different frame+# count from Quick's 640×480×73. Keying it as Quick's would be exactly the+# mistake this table exists to prevent. It is a good seed for the model, not a+# measurement.+LTX_MEASURED_ETA: dict[tuple[str, str, str, str], tuple[float, str]] = {+ # LTX-2.5, q8, distilled 8+2 — the schedule shipped on codex/ltx25-sched+ # (dfee6cf). The confirmation render is byte-identical (sha256 b831a821…)+ # to the arm the owner graded, so this is the clip he passed, timed.+ ("ltx25", "balanced", "5s", "q8"): (2.32, "~2 min"), # 139.4 s+ # LTX-2.5, q8 + HQ add-on, two-stage HQ, modality 1.0 (25b9b8e,+ # owner-passed). Confirmation render, env_overrides {}.+ ("ltx25", "high", "5s", "q8"): (4.14, "~4 min"), # 248.5 s+ # LTX-2.3, q8, two-stage HQ, modality 3.0 — the SFT value 2.3 keeps.+ ("ltx23", "high", "5s", "q8"): (5.08, "~5 min"), # 304.5 s+}++# The four tier notes. Python constants on the same four-hop path+# H3_CHAIN_PROMPT_HELP takes (constant → bootstrap key → lazy textContent fill),+# so they cannot drift from the mechanism and are one edit from a translator.+# The first sentence is generation-invariant; what High NEEDS is not. 2.3 ships+# its dev transformer and distilled LoRA inside its own q8 repo and has no+# add-on at all, so a pinned-back user was told to fetch something that does not+# exist for them.+_LTX_TIER_HIGH_NOTE_BASE = (+ "High runs a second, larger pass over the first one — sharper detail and "+ "steadier motion, for roughly twice the wait."+)+++def ltx_tier_high_note(version_id: str | None = None) -> str:+ if model_version(version_id).get("hq_addon_repo_key"):+ return _LTX_TIER_HIGH_NOTE_BASE + " It needs the Q8 weights and the High add-on."+ return _LTX_TIER_HIGH_NOTE_BASE + " It needs the Q8 weights."+++LTX_TIER_HIGH_NOTE = ltx_tier_high_note()+LTX_TIER_Q4_CHARACTER_NOTE = (+ "Trained characters need the Q8 weights. On the base pack most of the "+ "trained face is lost before the first frame, and a stranger renders."+)+LTX_TIER_LONG_NOTE = (+ "Past about ten seconds the picture can start to come apart at the tail "+ "while the sound keeps going. Smaller canvases hold together longer."+)+LTX_TIER_STANDARD_NOTE = (+ "More pixels, same denoising schedule as Balanced — bigger, not more "+ "detailed."+)++# The distilled lane's shipped schedule on 2.5 (8 stage-1 steps, 2 stage-2).+# The HQ lane keeps its explicit stage2_steps=3: the adopted 8+2 default is a+# DRAFT-lane verdict and retuning HQ stage 2 is ungraded and out of scope.+LTX_DISTILLED_STAGE1 = 8+LTX_DISTILLED_STAGE2 = 2+LTX_HQ_STAGE1 = 8+LTX_HQ_STAGE2 = 3+++def _ltx_qualities() -> dict[str, dict]:+ """The CANVAS axis.++ Keys are UNCHANGED from the shipped data-quality values+ (quick/balanced/standard/high) so every sidecar ever written, every Load+ Params round-trip and every issue thread quoting a tier name still resolves.+ This is the H3_TIER_ALIASES lesson applied BEFORE it costs us.++ `preview_every` / `preview_meaningful_at` are the live-preview lane rules,+ carried here because they differ per PIPELINE and a client counting+ estimates would have to know which schedule is running. The server decides;+ the client renders."""+ out: dict[str, dict] = {+ "quick": {+ # 640x448, NOT 640x480. The two-stage distilled lane snaps output+ # dimensions to multiples of 64 (`snap_output_dimensions`), and 480+ # is not one — so a chip advertising 640x480 was describing a render+ # that ffprobe reports as 640x448, on the draft tier most people+ # live in and the only tier where 20s is allowed. The label is the+ # thing that was wrong, so the label is what changed: no render+ # behaviour moves, and the ETA model is now fed the geometry that+ # actually runs.+ "key": "quick", "label": "Quick", "order": 0,+ "width": 640, "height": 448,+ "pack": "q4", "pipeline": "distilled",+ "stage1": LTX_DISTILLED_STAGE1, "stage2": LTX_DISTILLED_STAGE2,+ "stage2_evals": 1,+ "preview_every": 1, "preview_meaningful_at": 6,+ "blurb": "The fastest look at the shot.",+ "offered": True,+ },+ "balanced": {+ "key": "balanced", "label": "Balanced", "order": 1,+ "width": 1024, "height": 576,+ "pack": "q4", "pipeline": "distilled",+ "stage1": LTX_DISTILLED_STAGE1, "stage2": LTX_DISTILLED_STAGE2,+ "stage2_evals": 1,+ "preview_every": 1, "preview_meaningful_at": 6,+ "blurb": "16:9 at the size most things are watched.",+ "offered": True,+ },+ "standard": {+ "key": "standard", "label": "Standard", "order": 2,+ "width": 1280, "height": 704,+ "pack": "q4", "pipeline": "distilled",+ "stage1": LTX_DISTILLED_STAGE1, "stage2": LTX_DISTILLED_STAGE2,+ "stage2_evals": 1,+ "preview_every": 1, "preview_meaningful_at": 6,+ "blurb": "The largest canvas the distilled lane serves.",+ "note": LTX_TIER_STANDARD_NOTE,+ "offered": True,+ },+ "high": {+ "key": "high", "label": "High", "order": 3,+ "width": 1024, "height": 576,+ # The two-stage HQ path: dev transformer + CFG + the distilled LoRA,+ # res_2s. It needs the Q8 weights AND the High add-on, which is why+ # its chip carries `.needs-install` until both are on disk.+ "pack": "q8", "pipeline": "hq",+ "stage1": LTX_HQ_STAGE1, "stage2": LTX_HQ_STAGE2,+ # res_2s evaluates the denoiser twice per stage-2 step.+ "stage2_evals": 2,+ # The odd ANCHOR estimates come back patchy until ~8; the even+ # SUBSTEP ones are clean from the start. `every 2` selects exactly+ # the clean ones and halves the cost.+ "preview_every": 2, "preview_meaningful_at": 2,+ "blurb": "A second, larger pass over the first.",+ "note": LTX_TIER_HIGH_NOTE,+ # Offered when this GENERATION can serve q8 at all. Whether the+ # pack is on disk is a separate, runtime question — that one is the+ # `.needs-install` state, and both must be able to be true.+ "offered": "q8" in version_cap_tiers(),+ },+ }+ for q in out.values():+ q.setdefault("note", "")+ q["aspect"] = _h3_aspect(q["width"], q["height"])+ q["canvas"] = f"{q['width']}×{q['height']}"+ return out+++def _ltx_lengths() -> dict[str, dict]:+ """The DURATION axis.++ Frames land on the 8k+1 grid at 24 fps — the table docs/API.md already+ publishes and the one storyboard.ltx_frames_for() already computes. 20 s is+ the ceiling because it is the longest render anyone has confirmed holding+ together (issue #46, @blackest, 640×480 × 481f)."""+ out: dict[str, dict] = {+ "3s": {"key": "3s", "label": "3s", "order": 0, "seconds": 3,+ "frames": 73, "blurb": "One short beat.", "offered": True},+ "5s": {"key": "5s", "label": "5s", "order": 1, "seconds": 5,+ "frames": 121, "blurb": "The default — one full beat.",+ "offered": True},+ "7s": {"key": "7s", "label": "7s", "order": 2, "seconds": 7,+ "frames": 169, "blurb": "A beat with room to land.",+ "offered": True},+ "10s": {"key": "10s", "label": "10s", "order": 3, "seconds": 10,+ "frames": 241,+ "blurb": "Long for one shot. Motion drifts at the tail.",+ "note": LTX_TIER_LONG_NOTE, "offered": True},+ # Offered on Quick ONLY, because that is exactly what the field report+ # says: 640×480 fine at 481 frames, 1024×576 dies around frame 454,+ # 1280×720 white by 481. Same per-quality restriction mechanism+ # _h3_lengths() already has — restricted to nothing = available on+ # every canvas.+ "20s": {"key": "20s", "label": "20s", "order": 4, "seconds": 20,+ "frames": 481,+ "blurb": "The longest anyone has confirmed holding together, "+ "and only at Quick.",+ "note": LTX_TIER_LONG_NOTE,+ "qualities": ("quick",), "offered": True},+ }+ for l in out.values():+ l.setdefault("note", "")+ l.setdefault("qualities", ())+ return out+++LTX_QUALITIES: dict[str, dict] = _ltx_qualities()+LTX_LENGTHS: dict[str, dict] = _ltx_lengths()+LTX_QUALITY_DEFAULT = "balanced"+LTX_LENGTH_DEFAULT = "5s"+# The Characters tab's duration axis, derived from the table above rather than+# typed a fourth time. Bound here because that is the first point at which+# LTX_LENGTHS exists; the function and the argument live at its declaration.+_CHARACTER_DURATION_FRAMES.update(_character_duration_frames())+++def _build_ltx_tiers() -> dict[str, dict]:+ """Every (quality × length) cell, keyed `<quality>_<length>`.++ EVERY combination is built, including the ones a canvas does not offer —+ `offered` decides what the UI lists, and a cell that stops being offered+ must still resolve so a sidecar written while it was replays correctly."""+ tiers: dict[str, dict] = {}+ version_id = ACTIVE_MODEL_VERSION+ for q in LTX_QUALITIES.values():+ for ln in LTX_LENGTHS.values():+ key = f"{q['key']}_{ln['key']}"+ w, h = int(q["width"]), int(q["height"])+ frames = int(ln["frames"])+ eta_min = ltx_estimate_minutes(+ w, h, frames, int(q["stage1"]), int(q["stage2"]),+ int(q.get("stage2_evals") or 1))+ eta, eta_measured = _fmt_eta(eta_min), False+ hit = LTX_MEASURED_ETA.get(+ (version_id, q["key"], ln["key"], q["pack"]))+ if hit:+ eta_min, eta, eta_measured = hit[0], hit[1], True+ allowed = ln.get("qualities") or ()+ restricted = bool(allowed) and q["key"] not in allowed+ notes = [n for n in (q["note"], ln["note"]) if n]+ tiers[key] = {+ "key": key,+ "label": f"{q['label']} · {ln['label']}",+ "quality": q["key"], "quality_label": q["label"],+ "length": ln["key"], "length_label": ln["label"],+ "width": w, "height": h, "frames": frames,+ "seconds": int(ln["seconds"]),+ "aspect": q["aspect"],+ "spec": f"{w}×{h} · {frames}f",+ "pack": q["pack"], "pipeline": q["pipeline"],+ "stage1_steps": int(q["stage1"]),+ "stage2_steps": int(q["stage2"]),+ "preview_every": int(q["preview_every"]),+ "preview_meaningful_at": int(q["preview_meaningful_at"]),+ "eta": eta, "eta_min": round(eta_min, 2),+ "eta_measured": eta_measured,+ "blurb": f"{q['blurb']} {ln['blurb']}".strip(),+ "notes": notes,+ "note": " ".join(notes),+ "offered": bool(q["offered"] and ln["offered"] and not restricted),+ # `available` is the field the shared chip factory reads for the+ # `.unavailable` state — the same key H3's cells carry, so one+ # renderer serves both without learning a second vocabulary.+ # For LTX the two coincide today: a cell is unavailable exactly+ # when its canvas does not serve that length.+ "available": not restricted,+ # A cell a canvas does not serve renders `.unavailable` with a+ # reason, which is the H3 mechanism and needs no new UI.+ "unavailable_reason": (+ f"{ln['label']} is only offered at Quick — at "+ f"{w}×{h} a {frames}-frame render comes apart before the "+ f"end. Smaller canvases hold together longer."+ if restricted else ""),+ }+ return tiers+++LTX_TIERS: dict[str, dict] = _build_ltx_tiers()+++TAE_CHECKPOINT = MODELS_DIR / "tae" / "taeltx2_3.safetensors"+++def live_preview_enabled() -> bool:+ """Is the live preview on? Off when the user turned it off, or when the+ 22 MB decoder is not on disk (an install that predates it, mid-download)."""+ if not TAE_CHECKPOINT.is_file():+ return False+ return str(get_settings().get("live_preview", "on")).lower() != "off"+++def live_preview_dir(job_id: str) -> Path:+ """Per-job scratch for the preview contract: status.json, the PNGs and the+ ABORT sentinel. Per JOB, not per panel, so a stale sentinel from a previous+ render can never reach this one."""+ return STATE_DIR / "live" / _safe_job_id(job_id)+++def _live_preview_params(job: dict, p: dict) -> dict:+ """The three job-spec keys that turn the preview on, or {}.++ `live_preview_every` is THE LANE RULE and it is decided here, server-side,+ because it differs per pipeline: 1 on the distilled lane; 2 on res_2s,+ which evaluates the denoiser twice per stage-2 step and whose odd ANCHOR+ estimates come back patchy until ~8 while the even SUBSTEP ones are clean+ from the start. `every 2` selects exactly the clean ones and halves the+ cost. A client counting estimates would have to know which schedule is+ running, so it never gets the chance."""+ if not live_preview_enabled():+ return {}+ cell = LTX_QUALITIES.get(p.get("quality") or "", {})+ return {+ "live_preview_dir": str(live_preview_dir(job["id"])),+ "live_preview_tae": str(TAE_CHECKPOINT),+ "live_preview_every": int(cell.get("preview_every") or 1),+ }+++def pack_offers(version_id: str | None = None) -> dict:+ """What the install CTAs should OFFER, for the generation actually active.++ Every surface that says "download the Q8 pack" used to name the key `q8`+ and the number `37 GB`, both of which are 2.3 facts hardcoded in 2.3's+ era. v4.0 fixed exactly one of those call sites (download_q8.js) and left+ the panel's own biggest install card selling 37 GB of the retired+ generation on a 2.5 build — a button that WORKS, spends the user's evening,+ and leaves them exactly as unable to render High as before.++ So the keys and the sizes come from the registry, per version, and the+ string a CTA prints is derived from the same row the download uses. A third+ generation gets this right without anyone editing a button.++ Sizes are `required_files.json`'s decimal GB — the same number the Models+ modal prints for the same pack, so the two cannot disagree."""+ ver = model_version(version_id)++ def row(repo_key: str | None) -> dict | None:+ if not repo_key:+ return None+ r = next((x for x in _repos() if x.get("key") == repo_key), None)+ if not r:+ return None+ gb = r.get("size_gb")+ return {"key": repo_key, "name": r.get("name") or repo_key,+ "size_gb": gb,+ "size": (f"{gb:g} GB" if isinstance(gb, (int, float)) else "?"),+ # Same registry-derived answer the Models modal uses, so a CTA+ # cannot disable a download the modal would happily start.+ "needs_hf": not bool(r.get("mirror"))}++ base_key = (version_pack("q4", ver["id"]) or {}).get("repo_key")+ q8_key = (version_pack("q8", ver["id"]) or {}).get("repo_key")+ enc_key = (ver.get("text_encoder") or {}).get("repo_key")+ return {+ "base": row(base_key),+ "encoder": row(enc_key),+ "q8": row(q8_key),+ "hq_addon": row(ver.get("hq_addon_repo_key")),+ }+++def character_render_quality(version_id: str | None = None) -> str:+ """Which pipeline a TRAINED CHARACTER renders on, per generation.++ Resolved here, server-side, so the two generations do not each own a copy of+ the rule — the markup must never decide this.++ 2.3 -> "high". Its character LoRAs are dev-trained and distilled inference+ barely locks identity, so the character strip forces the two-stage HQ path.+ That reasoning is real and it is why the strip exists.++ 2.5 -> "balanced". On 2.5 the reasoning INVERTS. The recipe the owner graded+ — "insane quality", voice PASS by ear — is q8 + the DISTILLED pipeline at+ 1024x576x121 with the face LoRA at 1.0, and every graded 2.5 character clip+ in the campaign ran that path. Forcing `high` there would (a) route+ characters onto a pipeline nobody has graded them on and (b) require a+ 29.5 GB add-on for a result the 30 GB q8 pack already delivers, in 139 s+ instead of 246 s. Two mistakes, so: the graded path is the default.+ """+ return str(model_version(version_id).get("character_quality") or "high")+++def character_strip_payload() -> dict:+ """The two character chips, priced from the same table everything else uses.++ "~2 min" here is not typed: it is the MEASURED 139.4 s row for+ (ltx25, balanced, 5s, q8) — the character lane really does submit balanced+ at q8, which is exactly why ltx_measured_eta takes a quant."""+ q = character_render_quality()+ pack = "q8"+ hit = ltx_measured_eta(q, "5s", pack)+ pro_eta = hit[1] if hit else _fmt_eta(+ ltx_estimate_minutes(1024, 576, 121,+ LTX_QUALITIES[q]["stage1"], LTX_QUALITIES[q]["stage2"],+ LTX_QUALITIES[q].get("stage2_evals") or 1))+ draft_eta = _fmt_eta(+ ltx_estimate_minutes(704, 384, 121,+ LTX_QUALITIES[q]["stage1"], LTX_QUALITIES[q]["stage2"],+ LTX_QUALITIES[q].get("stage2_evals") or 1))+ label = "Q8" if q != "high" else "Q8 HQ"+ return {+ "quality": q,+ "draft": {"width": 704, "height": 384,+ "tier": f"{label} · {draft_eta} / 5s",+ "title": f"Q8 at 704×384 — faster, slightly less per-frame detail."},+ "pro": {"width": 1024, "height": 576,+ "tier": f"{label} · {pro_eta} / 5s · best identity",+ "title": "Q8 at 1024×576 — the recipe the character LoRAs were "+ "graded on."},+ }+++def ltx_measured_eta(quality: str, length: str, quant: str,+ version_id: str | None = None) -> tuple[float, str] | None:+ """The measured wall clock for this exact (version, quality, length, pack),+ or None when nobody has timed it.++ Exists because the PACK is not always the one the quality chip implies. The+ Quick / Balanced / Standard chips run the distilled lane on the BASE pack,+ so `("ltx25", "balanced", "5s", "q8")` is not their number — but the+ character lane submits balanced AT q8 (§5.6), and that is the 139.4 s row.+ One table, asked the right question by each caller, instead of a second+ table for characters."""+ return LTX_MEASURED_ETA.get(+ ((version_id or ACTIVE_MODEL_VERSION), quality, length, quant))+++def ltx_compose_tier(quality: str | None, length: str | None) -> str | None:+ """The two axes → the cell key, or None if either axis is unknown."""+ q = (quality or "").strip().lower()+ ln = (length or "").strip().lower()+ if not q or not ln:+ return None+ key = f"{q}_{ln}"+ return key if key in LTX_TIERS else None+++def ltx_tiers_payload() -> dict:+ """The LTX table as the page sees it.++ Deliberately the SAME field names and the same shapes H3 publishes+ (`tiers` a flat cell list, `qualities` / `lengths` the two axes,+ `default_quality` / `default_length`), because the client renderer is one+ generalised function serving both engines. A second shape here would mean a+ second renderer, which is the fork this whole area exists to avoid."""+ return {+ "tiers": [dict(t) for t in sorted(+ LTX_TIERS.values(),+ key=lambda t: (LTX_QUALITIES[t["quality"]]["order"],+ LTX_LENGTHS[t["length"]]["order"]))],+ "qualities": [dict(q) for q in sorted(+ LTX_QUALITIES.values(), key=lambda x: x["order"]) if q["offered"]],+ "lengths": [dict(l) for l in sorted(+ LTX_LENGTHS.values(), key=lambda x: x["order"]) if l["offered"]],+ "default_quality": LTX_QUALITY_DEFAULT,+ "default_length": LTX_LENGTH_DEFAULT,+ # The `?` copy the LTX help-dots fill from, on the same four-hop+ # Python-owned path H3's chain-prompt help takes. It rides the LTX+ # bootstrap block rather than a top-level one so everything the LTX+ # surface reads arrives together.+ "help": {+ "voice_strength": LTX_VOICE_STRENGTH_HELP,+ "q8_character": LTX_Q8_CHARACTER_HELP,+ "preview": LTX_PREVIEW_HELP,+ },+ # The character strip's two chips, and the PIPELINE they submit —+ # resolved per generation so the markup never owns that rule.+ "character": character_strip_payload(),+ # What the install CTAs offer, keyed and sized from the registry for the+ # ACTIVE generation. Every button that spends a user's bandwidth reads+ # this instead of naming a pack.+ "packs": pack_offers(),+ }++# Post-render export targets for an H3 clip. Most tiers write 768×448 (12:7),# which is neither 720p nor 1080p, so the panel applies the SAME ffmpeg recipe# LTX renders get: lanczos fit inside the canvas, pad the remainder, re-encode@@ -7477,9 +8632,25 @@ ENGINE_DEFAULT = "ltx"ENGINES: tuple[dict, ...] = ({"id": "ltx",- "label": "LTX-2.3",+ # The switcher answers "which model family renders this", not "which+ # build". Its segments differ in CAPABILITY — LTX takes LoRAs,+ # characters, i2v, keyframes and extend; H3 generates joint+ # dialogue+sound and stacks no character LoRA. 2.3 and 2.5 differ in+ # none of that: same LoRA files (1152/1152 modules fuse on both), same+ # modes, same form. A third segment reading "LTX-2.3 | LTX-2.5 | Hailuo+ # H3" would tell the user those three are peers, and two of them are the+ # same engine. So the family name is the label and the GENERATION gets+ # its own line — see `generation_from` below.+ "label": "LTX","sublabel": "built in","tagline": "every mode, LoRAs, characters",+ # Rendered as the chip's generation line and nowhere else. Read from the+ # ACTIVE version so a user pinned back with LTX_MODEL_VERSION=ltx23 sees+ # the truth rather than a constant. This is the one field in the table+ # that is DERIVED rather than declared, and it is derived because the+ # answer changes: a static "2.5" here is the same bug as the static+ # "LTX-2.3" it replaces, one generation later.+ "generation_from": "model_version", # -> model_version()["label"] minus "LTX-""mark": "eng-mark-ltx","accent": "#5EEAFF","accent_dim": "rgba(94,234,255,0.13)",@@ -7599,6 +8770,19 @@ def engines_payload() -> list[dict]:d["modes"] = list(e["modes"]) if e.get("modes") else Noned["excluded_modes"] = list(e.get("excluded_modes") or ())d["surfaces"] = list(e.get("surfaces") or ("video",))+ # `generation_from` is the one derived field in the table. Resolve it+ # HERE, once, so the client never computes a version string — it only+ # prints one. "model_version" means "the label of the generation this+ # process is actually serving, minus the family prefix the chip already+ # shows": LTX-2.5 -> 2.5, and LTX-2.3 -> 2.3 for a pinned-back user.+ if d.pop("generation_from", None) == "model_version":+ # popped, not read: `generation_from` is an instruction to the+ # server, and the client only ever needs the ANSWER. Shipping both+ # invites a second implementation in JS.+ _lbl = str(model_version().get("label") or "")+ _gen = _lbl.replace("LTX-", "").strip()+ if _gen and _gen != _lbl.strip():+ d["generation"] = _genout.append(d)return out@@ -8163,7 +9347,14 @@ def _analytics_boot() -> None:"os_version": _analytics_os_version(),"chip_family": _analytics_chip_family(),"ram_gb": int(round(SYSTEM_RAM_GB)),+ # `cap_tier` keeps reporting the FEATURE tier, unchanged, so the+ # existing series stays comparable across the 2.5 cutover — a field+ # that quietly changes meaning is worse than a missing one."cap_tier": _resolve_cap_tier(),+ # The generation this install actually serves, as a NEW field rather+ # than a redefinition of an old one. Without it every 2.5 number+ # since 2026-08-12 is indistinguishable from a 2.3 number.+ "model_version": ACTIVE_MODEL_VERSION,"packs": packs,"h3_chain_supported": bool(packs["h3"] and h3_supports_chain()),})@@ -9293,6 +10484,7 @@ def list_outputs(# whether a clip is a finishable H3 draft. Without them the "Finish# at …" button would need a /sidecar fetch on every gallery click.engine = None+ model = None # which weights made this clip (sidecar-derived)h3_tier = None# Which film this clip is a shot of, if any — {"id": ..., "n": 3} or None.# Derived from the sidecar read already happening below, so it costs@@ -9315,6 +10507,16 @@ def list_outputs(_eng = meta.get("engine") or _sc_params.get("engine")if isinstance(_eng, str) and _eng:engine = _eng+ # WHICH WEIGHTS MADE THIS CLIP. The sidecar has always known —+ # the LTX path records its job spec's model_dir and the H3 path+ # records its DiT — but the credit under the player was a+ # one-shot read of BOOT.model at page load, so it printed the+ # active LTX pack under an H3 render and under every clip ever+ # made on another generation. A clip that predates the field+ # simply has no `model` here and the credit falls back.+ _mdl = meta.get("model") or _sc_params.get("model")+ if isinstance(_mdl, str) and _mdl:+ model = _mdl# RESOLVED here, not raw: a clip rendered before the two-axis# refactor carries `hq_5s` / `wide_5s` / `long_10s`, and the# panel's Finish affordance looks the key up in the CURRENT@@ -9366,6 +10568,10 @@ def list_outputs(# the RESOLVED cell key, so the two axes below are just its halves# and the browser can gate on quality without splitting a string."engine": engine,+ # Which weights made this clip. The credit under the player reads+ # it; None for a clip that predates the field, and the client falls+ # back to BOOT.model silently.+ "model": model,"h3_tier": h3_tier,"h3_quality": (H3_TIERS[h3_tier]["quality"] if h3_tier else None),"h3_length": (H3_TIERS[h3_tier]["length"] if h3_tier else None),@@ -9446,6 +10652,16 @@ def load_queue() -> None:# ---- warm helper -------------------------------------------------------------+class JobStopped(Exception):+ """The user stopped this render on purpose.++ A separate type from RuntimeError because the difference is the whole+ point: exit 75 exists so a supervisor can tell "the user stopped this"+ apart from "this crashed" without parsing a message, and a stopped take+ must not land in the UI wearing a failure's red card. Nothing was saved —+ the clip was never finished — but nothing went wrong."""++class WarmHelper:def __init__(self):self.proc: subprocess.Popen | None = None@@ -9488,7 +10704,7 @@ class WarmHelper:# Version-aware, for the same reason LTX_MODEL is. This was# `str(GEMMA)` — a constant naming Gemma 3 — so selecting LTX-2.5# moved the transformer and silently left the text tower on 2.3's- # encoder. It renders; it just renders wrong.+ # encoder. It renders; it just renders wrong (ltx25 entry, above).env["LTX_GEMMA"] = text_encoder_dir()env["LTX_IDLE_TIMEOUT"] = str(HELPER_IDLE_TIMEOUT)env["LTX_LOW_MEMORY"] = HELPER_LOW_MEMORY@@ -9875,7 +11091,11 @@ class WarmHelper:raise RuntimeError(f"helper stdin closed: {exc}")log_hook, panic_check = self._build_post_decode_panic(job_spec)ev = self._read_until(- ["done", "error", "exit"],+ # "stopped" is a TERMINAL event like the other three. Without it+ # here the reader logged the helper's stop generically and then+ # kept waiting for an event that was never coming, so a+ # deliberate Stop early surfaced as whatever timed out first.+ ["done", "error", "exit", "stopped"],log_hook=log_hook,panic_check=panic_check,)@@ -9956,6 +11176,13 @@ class WarmHelper:"which phase died, and the crashlog at ""~/Library/Logs/DiagnosticReports/python3.11_*.crash if any.")+ if ev.get("event") == "stopped":+ # A USER STOP, not a failure. Exit 75 is the runner's own way of+ # saying so, and the panel is the supervisor it was written for.+ # A distinct exception type so run_job_inner can mark the job+ # `stopped` instead of `failed` — nothing was saved, but nothing+ # went wrong.+ raise JobStopped(ev.get("reason") or "stopped early")if ev.get("event") == "error":raise RuntimeError(ev.get("error", "helper error"))if ev.get("event") == "exit":@@ -10951,7 +12178,7 @@ def _sb_policy_for(draft_quality: str, final_quality: str) -> dict:to what this Mac can actually render."""cap = _sb_max_dim()table = {- "quick": (640, 480),+ "quick": (640, 448),"balanced": (768, 432),"standard": (1024, 576),"high": (1024, 576),@@ -11494,8 +12721,8 @@ def _validate_character_quality(form: dict[str, list[str]] | dict[str, str]) ->except Exception:continueif (meta.get("kind") or "") == "train_character":- log_push(f"[character] raw train_character LoRA {p.name!r} at quality={quality!r} "- f"on Q4 base — identity match may be imperfect")+ push(f"[character] raw train_character LoRA {p.name!r} at quality={quality!r} "+ f"on Q4 base — identity match may be imperfect")return None@@ -12158,8 +13385,9 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,# user signed off on at the time. Power users can dial back# to stage1=15 / teacache=1.0 for the conservative Max via# the advanced fields.- "stage1_steps": max(1, int(f("stage1_steps", "10") or 10)),- "stage2_steps": max(0, int(f("stage2_steps", "3") or 3)),+ # stage1_steps / stage2_steps are NOT stamped here — see the+ # conditional block after this dict, and `stg_scale` above for the+ # same pattern and the same reason.# HQ TeaCache default — 1.8 is the empirically-measured sweet# spot for character mode. The upstream calibration constant# (LTX2_HQ_TEACACHE_THRESH) claims 1.0 is optimal, but that@@ -12275,6 +13503,33 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,job["params"]["stg_scale"] = max(0.0, min(4.0, float(_stg_raw)))except (TypeError, ValueError):pass+ # SCHEDULE STEP COUNTS — same rule as stg_scale above, and it took a+ # 218-second failure to notice they did not follow it.+ #+ # These were stamped UNCONDITIONALLY at the HQ lane's tuning values+ # (stage1=10, stage2=3) on every job, from a form field that does not+ # exist — so the value was always 10. Every other lane's own considered+ # default was dead code behind it: `generate_restore` reads+ # p.get("stage1_steps", 8) and never once saw 8.+ #+ # On 2.3 that was invisible: its distilled table is long enough to thin to+ # 10. On 2.5 the table is a fixed 9 points / 8 steps, and a step count is a+ # request to THIN the checkpoint's own table — so asking for 10 is asking+ # it to pad, which the sampler correctly refuses. Colorize and Restore+ # therefore loaded models, ran stage work for 218 s, and died on+ # "cannot thin a 9-point schedule (8 steps) up to 10 steps".+ #+ # So: stamp only what the user actually sent. Each dispatch keeps its own+ # default, an explicit value still reaches the engine, and the clamp in+ # mlx_warm_helper._clamp_stage_steps() makes even an explicit value+ # impossible to turn into a pad request on whichever pack is loaded.+ for _sk, _lo in (("stage1_steps", 1), ("stage2_steps", 0)):+ _raw = f(_sk, "")+ if _raw != "":+ try:+ job["params"][_sk] = max(_lo, int(_raw))+ except (TypeError, ValueError):+ pass# Attach Characters-origin metadata only when the form actually carried# it. Keeps the params shape unchanged for every other entry point.if _source == "characters" and _character_id:@@ -12310,6 +13565,41 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,except (TypeError, ValueError):char_strength = 1.0char_strength = max(0.0, min(2.0, char_strength))+ # THE VOICE IS A SEPARATE FILE AND IT NEEDS A SEPARATE NUMBER.+ #+ # A character is two trained LoRAs: <trigger>.safetensors (1152 modules,+ # 384 of them on the audio branch) and <trigger>.audio.safetensors (576,+ # all audio). They OVERLAP on 384 modules, and on those the face file's+ # audio deltas are NOISE — it was trained on 42 still images with+ # generate_audio false, so whatever the optimiser did to those+ # parameters encodes no voice at all. Measured, the noise is LOUDER than+ # the signal: median ||D|| 1.45 against the voice file's 1.10, an SNR of+ # 0.81x at equal strength. At q4 both were erased (~95 %) and the ratio+ # never mattered; at q8 ~90 % of both survives, which is why fixing the+ # face is what surfaced the voice.+ #+ # So running the voice a little hotter than the face is what makes it+ # win. Parity is 1.2; 1.4 is the first setting with real headroom, and+ # it is independently where current community guidance for 2.5 puts+ # "balanced".+ #+ # THE DEFAULT IS 1.0 ANYWAY, and that is a listening decision, not a+ # measurement one. 1.0/1.0 is the pair every graded clip was rendered+ # at and passed on; the hotter rungs are real and reachable — the split+ # control ships, the help text explains the mechanism — but a default+ # nobody has listened to is not a default. Raise it when an ear says so.+ #+ # THE ALLOWLIST TRAP: make_job builds params from named reads, and a+ # field nobody reads here is dropped with no error — the render+ # succeeds and the voice silently runs at the face's strength. That has+ # bitten this project before (image params, 2026-05). The assertion that+ # this key reaches params is part of the same commit.+ try:+ char_voice_strength = float(+ f("character_voice_strength", "1.0") or "1.0")+ except (TypeError, ValueError):+ char_voice_strength = 1.0+ char_voice_strength = max(0.0, min(2.0, char_voice_strength))# Per-render voice opt-out (2026-05-18). When the user flips the# "No voice" toggle in composer-tools, drop the character's# audio LoRA from the stack for THIS render — face still locks,@@ -12335,7 +13625,8 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,additions.append({"path": face_p, "strength": char_strength})existing_paths.add(face_p)if audio_p and audio_p not in existing_paths and not no_voice:- additions.append({"path": audio_p, "strength": char_strength})+ additions.append({"path": audio_p,+ "strength": char_voice_strength})existing_paths.add(audio_p)elif audio_p and no_voice:job["params"]["no_voice"] = True@@ -12352,9 +13643,14 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,# later restore the picker selection.if "character_id" not in job["params"]:job["params"]["character_id"] = _character_id- # Persist the strength too so Load Params can restore the- # exact slider value (defaults to 1.0 on the picker).+ # Persist BOTH strengths so Load Params restores the exact sliders+ # and the sidecar records what actually rendered. The voice value is+ # stamped even when it equals the default: the number in a clip's+ # sidecar is how a future listener knows which rung of the ladder+ # they are hearing.job["params"].setdefault("character_strength", char_strength)+ job["params"].setdefault("character_voice_strength",+ char_voice_strength)# ---- lane scrub: a LoRA never crosses engines --------------------------# The picker is ONE control shared by both video engines, and its hidden@@ -14302,13 +15598,15 @@ def run_job_inner(job: dict) -> None:# Y1.024 download filter pruned the dupe and exposed that Extend is# structurally Q8-class. Gate it the same way Keyframe does and route# the helper to the Q8 dir.- ext_missing = q8_missing_files()+ ext_missing = hq_surface_missing()if ext_missing:raise RuntimeError(f"Extend requires the full Q8 model at {pack_path('q8')}. "f"Missing {len(ext_missing)} file(s): {', '.join(ext_missing[:3])}"f"{' …' if len(ext_missing) > 3 else ''}. "- f"Click \"Download Q8\" in Pinokio to install it (~37 GB)."+ f"Install it from Settings \u2192 Models "+ f"({(pack_repo('q8') or {}).get('name', 'the Q8 pack')}, "+ f"~{(pack_repo('q8') or {}).get('size_gb', '?')} GB).")src = p["video_path"]if not src or not Path(src).exists():@@ -14907,7 +16205,7 @@ def run_job_inner(job: dict) -> None:# "directory exists and non-empty" check let half-downloaded Q8# installs through, only to crash later mid-render with a# `load_safetensors` error referencing a specific missing file.- kf_missing = q8_missing_files()+ kf_missing = hq_surface_missing()if kf_missing:raise RuntimeError(f"Keyframe mode requires the full Q8 model at {pack_path('q8')}. "@@ -15072,7 +16370,7 @@ def run_job_inner(job: dict) -> None:if mode == "a2v":uses_q8 = SYSTEM_CAPS["allows_q8"]if uses_q8:- a2v_missing = q8_missing_files()+ a2v_missing = hq_surface_missing()if a2v_missing:push(f"Q8 not available ({len(a2v_missing)} file(s) missing) "f"— falling back to Q4 distilled A2V pipeline")@@ -15229,8 +16527,25 @@ def run_job_inner(job: dict) -> None:# distilled + lanczos path that has worked since yesterday.Q8_FAST_OK_MODES = ("t2v",)Q8_FAST_FRAMES_LIMIT = 121+ # 2.3 ONLY, and this gate is the substance of the v4.0 character routing.+ #+ # Every number above — stage1=10, teacache 1.0, "~6 min", the eye-checks —+ # was measured on 2.3's two-stage HQ pipeline. On 2.5 this silently+ # rerouted quality=balanced onto `high`, which means:+ # * a CHARACTER render, whose graded 2.5 recipe is q8 + DISTILLED, landed+ # on the two-stage HQ path nobody has graded 2.5 characters on; and+ # * it then demanded the 29.5 GB HQ add-on, so on a machine with the full+ # q8 pack and no add-on it did not render at all — "High quality+ # requires the full Q8 model", for a job the user asked to run on+ # Balanced.+ # Found exactly that way: the step-13 proof render failed on a stock 2.5+ # install with the add-on withheld.+ #+ # 2.3 keeps the routing unchanged. When someone measures the equivalent on+ # 2.5's pipeline it can come back, per generation, with its own numbers.balanced_q8_fast = (quality == "balanced"+ and ACTIVE_MODEL_VERSION == "ltx23"and SYSTEM_TIER == "standard"and SYSTEM_CAPS.get("allows_q8", False)and not q8_missing_files()@@ -15391,7 +16706,15 @@ def run_job_inner(job: dict) -> None:# 'generate' action uses. ICLoraPipeline runs Stage 1# with the LoRA fused, Stage 2 reloads a clean# transformer (matches the Lightricks reference).- "stage1_steps": int(p.get("stage1_steps", 10)),+ #+ # 8, NOT 10. ICLoraPipeline THINS a fixed 9-point table+ # (`thin_sigmas(DISTILLED_SIGMAS, n)`), so 8 steps is its+ # ceiling and 10 is a pad request the sampler refuses — after+ # the model has loaded. This default was 10 and was invisible+ # only because make_job's unconditional stamp overwrote it with+ # the same wrong number. Removing the stamp exposed it, which+ # is the honest outcome: the lane's own default was wrong too.+ "stage1_steps": int(p.get("stage1_steps", 8)),"stage2_steps": int(p.get("stage2_steps", 3)),},}@@ -15423,7 +16746,7 @@ def run_job_inner(job: dict) -> None:# Route to TwoStageHQPipeline (Q8 dev model + res_2s sampler + CFG anchor + TeaCache).# Defaults from ltx-2-mlx CLAUDE.md LTX_2_3_PARAMS.# Same completeness check as keyframe — see comment there.- hq_missing = q8_missing_files()+ hq_missing = hq_surface_missing()if hq_missing:raise RuntimeError(f"High quality requires the full Q8 model at {pack_path('q8')}. "@@ -15533,7 +16856,31 @@ def run_job_inner(job: dict) -> None:"path": CURATED_LORAS["hdr"]["repo_id"],"strength": float(CURATED_LORAS["hdr"]["default_strength"]),})- ltx_pack_preflight("q4", "This render")+ # CHARACTERS RENDER ON THE Q8 WEIGHTS, ON THE DISTILLED PIPELINE.+ #+ # This is the `pack=q8` half of the 2.5 character recipe, and without it+ # the other half is worse than useless: routing a character to+ # `quality=balanced` puts it on the DISTILLED pipeline (right) reading+ # the Q4 pack (wrong), and fusing a rank-32 character LoRA into int4+ # weights destroys most of the delta — the helper's own instrument+ # measured 867 % of the delta destroyed on this exact pack + LoRA, and+ # the render then died outright on a parameter mismatch. A trigger word+ # that changes the picture into a stranger is the failure this whole+ # area exists to end.+ #+ # So: same pipeline, different weights. The q8 pack ships its own+ # `transformer-distilled.safetensors`, which is exactly what makes+ # "q8 + distilled" a thing that can be asked for — and it is the recipe+ # every graded 2.5 character clip ran. Resolved from the registry, so+ # 2.3 (whose characters go to `high` and never reach this branch) is+ # untouched.+ _char_pack = "q4"+ if p.get("character_id") and character_render_quality() != "high":+ _char_pack = "q8"+ push(f"[character] {model_version()['label']} characters render on "+ f"the Q8 weights with the distilled pipeline — the recipe they "+ f"were graded on.")+ ltx_pack_preflight(_char_pack, "This render")job_spec = {"action": "generate","id": job["id"],@@ -15545,7 +16892,14 @@ def run_job_inner(job: dict) -> None:# already loads -- the point is that a second model version# becomes a different string here rather than a different# helper process.- "model_dir": base_model_dir(),+ "model_dir": (str(pack_path("q8")) if _char_pack == "q8"+ else base_model_dir()),+ # Live preview. The panel owns the LANE RULE (how often an+ # estimate is worth publishing) because it differs per pipeline+ # and only the server knows which schedule is running; the+ # helper takes the number. All three keys absent = off, which+ # is exactly what the Settings toggle produces.+ **_live_preview_params(job, p),"mode": mode,"prompt": p["prompt"],"negative_prompt": p.get("negative_prompt", ""),@@ -15723,8 +17077,10 @@ def run_job_inner(job: dict) -> None:# The sidecar is the clip's provenance — the one durable record of# which weights made it. MODEL_ID names the DEFAULT install, so on a# non-default version this recorded 2.3's pack for a 2.5 render. The- # job spec already resolves the right directory; report that.- "fps": FPS, "model": base_model_dir(), "queue_id": job["id"],+ # job spec already resolves the right directory; report THAT, not a+ # re-derivation — a character render routes to the q8 pack, and a+ # sidecar that said q4 for it would be provenance that is simply wrong.+ "fps": FPS, "model": job_spec["params"]["model_dir"], "queue_id": job["id"],"helper_elapsed_sec": result.get("elapsed_sec"),"output_codec": output_codec_settings(),"memory_policy": memory_plan,@@ -15785,6 +17141,15 @@ def worker_loop() -> None:with _GPU_LOCK:run_job_inner(job)job["status"] = "done"+ except JobStopped as stop:+ # EXIT 75 IS A CANCEL, NOT A FAILURE. The user looked at the live+ # preview, saw the wrong shot and stopped it. Nothing was saved —+ # the clip was never finished — but nothing went wrong, and a red+ # card here would be the panel calling the user's decision an+ # error.+ job["status"] = "stopped"+ job["stopped_reason"] = str(stop)+ push(f"Stopped early: {stop}")except Exception as exc:if job.get("cancel_requested"):job["status"] = "cancelled"@@ -16661,9 +18026,33 @@ class Handler(BaseHTTPRequestHandler):# we zero it out when Q8 is reachable via cache so the UI# doesn't show a spurious "missing files" warning alongside# an enabled FFLF button.- _q8_available = q8_available_anywhere()+ # The UI reads q8_available to enable High / Extend / Keyframe /+ # FFLF. Those need the HQ add-on as well as the pack, so a pack-only+ # answer would light the pill up and let the job fail at load time+ # -- the same wave-through e870061 closed, moved to the UI layer.+ # For 2.3 `hq_addon_missing()` is [] and this is byte-for-byte the+ # old expression.+ _hq_addon_missing = hq_addon_missing()+ _q8_available = q8_available_anywhere() and not _hq_addon_missingpayload["q8_available"] = _q8_availablepayload["q8_missing"] = [] if _q8_available else _q8_missing+ # THE Q8 WEIGHTS PACK, on its own — distinct from `q8_available`+ # above, which folds in the HQ add-on because High / Extend /+ # Keyframe genuinely need both.+ #+ # Characters need the PACK and not the add-on: on 2.5 they render on+ # q8 + distilled, which is the recipe every graded 2.5 character+ # clip ran. Reading `q8_available` for them would tell a user who+ # has the full 30 GB pack that they must "Install Q8 (30 GB)"+ # because a DIFFERENT 29.5 GB download is absent — the pack they+ # already have, demanded again, to run a path that does not use the+ # missing file. One conflated boolean, two very different questions.+ payload["q8_pack_available"] = q8_available_anywhere()+ payload["q8_pack_missing"] = _q8_missing+ # Reported separately so the Models page can say WHICH download is+ # the one standing between the user and the High tier.+ payload["hq_addon_missing"] = _hq_addon_missing+ payload["hq_surface_missing"] = hq_surface_missing()payload["q8_path"] = str(pack_path("q8"))payload["base_available"] = not _base_missingpayload["base_missing"] = _base_missing@@ -17195,6 +18584,13 @@ class Handler(BaseHTTPRequestHandler):)self._json(payload)return+ if parsed.path == "/storage":+ # What can be reclaimed on this disk. Walks the real directories, so+ # it is deliberately NOT part of /status (which polls every 1.5 s).+ # The Settings modal asks for it on open, which is the only moment+ # anyone looks.+ self._json(storage_payload())+ returnif parsed.path == "/settings":# Return current panel settings + the preset table so the UI# can render preset pills with labels and blurbs without@@ -18153,7 +19549,7 @@ class Handler(BaseHTTPRequestHandler):self._json({"ok": False,"error": "Hailuo H3 can't load a trained character. ""Pick Auto to keep them (their shots render on "- "LTX-2.3), or clear the cast."}, 400)+ "LTX), or clear the cast."}, 400)returnchars = [c for c in (list_characters() or []) if c.get("id") == cid] if cid else []board["engine_mode"] = emode@@ -19644,10 +21040,40 @@ class Handler(BaseHTTPRequestHandler):f"{sorted(_CHARACTER_DURATION_FRAMES)}"}, 400); returnframes = _CHARACTER_DURATION_FRAMES[duration]- quality = (form.get("quality", ["high"])[0] or "high").strip().lower()- if quality not in _CHARACTER_QUALITY_RESOLUTION:- self._json({"error": "quality must be draft, balanced or high"}, 400); return- width, height = _CHARACTER_QUALITY_RESOLUTION[quality]+ # The DEFAULT is resolved per generation, not hardcoded: 2.3 renders+ # characters on the two-stage HQ path, 2.5 on q8 + distilled (the+ # recipe every graded 2.5 character clip ran). An explicit `quality`+ # in the form still wins — this endpoint stays a thin wrapper — but+ # a caller that says nothing gets the graded path for the generation+ # actually installed.+ # TWO SEPARATE QUESTIONS, and conflating them is what kept this+ # tab on the wrong pipeline.+ #+ # SIZE which canvas — the tab's two chips, Q8 Draft (704x384)+ # and Q8 Pro (1024x576).+ # PIPELINE which schedule runs — and that is NOT the user's+ # choice, it is the generation's: ltx25 -> balanced+ # (q8 + distilled, the recipe every graded 2.5 character+ # clip ran), ltx23 -> high (its LoRAs are dev-trained and+ # distilled inference barely locks identity).+ #+ # `quality` used to mean both at once, so picking the small canvas+ # also picked a pipeline, and the only two tokens on offer were+ # 2.3's. A caller that names a real pipeline quality still wins —+ # this endpoint stays a thin wrapper — but the chips no longer have+ # to lie to ask for a size.+ _char_default = character_render_quality()+ _q_raw = (form.get("quality", [""])[0] or "").strip().lower()+ _SIZE_TOKENS = {"draft": (704, 384), "pro": (1024, 576)}+ if _q_raw in _SIZE_TOKENS:+ width, height = _SIZE_TOKENS[_q_raw]+ quality = _char_default+ else:+ quality = _q_raw or _char_default+ if quality not in _CHARACTER_QUALITY_RESOLUTION:+ self._json({"error": "quality must be draft, pro, balanced "+ "or high"}, 400); return+ width, height = _CHARACTER_QUALITY_RESOLUTION[quality]seed = (form.get("seed", ["-1"])[0] or "-1").strip()try:@@ -19655,16 +21081,35 @@ class Handler(BaseHTTPRequestHandler):except (TypeError, ValueError):self._json({"error": "seed must be an integer"}, 400); return- # Character LoRA strength (applied to BOTH face + audio LoRAs).- # Default 0.8: Aria/Bizarro/Mr Bizarro v2 LoRAs were trained to 5000- # steps (vs Lightricks-recommended 2000), so they over-bake- # training-time visual quirks at strength 1.0. Dropping to 0.8- # noticeably reduces sparkles/mesh without hurting identity.+ # Character LoRA strengths — face and voice, separately.+ #+ # ONE CHARACTER, ONE MEANING OF "STRENGTH", WHICHEVER TAB YOU ARE ON.+ # This lane read `character_strength` with a default of 0.8 and+ # applied that one number to BOTH files, while the Manual tab's+ # picker defaulted to 1.0 — so the same character rendered+ # differently depending on which surface launched it, and neither+ # number was written down anywhere the other could see. The 0.8 was+ # a 2.3-era correction for over-baked visual quirks at 5000 steps;+ # on 2.5 q8 the graded recipe is the face at 1.0.+ #+ # The voice takes its own number for the reason spelled out in+ # make_job: the face file's audio-branch deltas are noise, they are+ # louder than the voice file's signal at equal strength, and running+ # the voice hotter is what makes it win. It still DEFAULTS to 1.0 —+ # the graded pair — because the hotter rungs have not been listened+ # to. Same default on both lanes or the two surfaces disagree again.try:- char_strength = float((form.get("character_strength", ["0.8"])[0] or "0.8"))+ char_strength = float(+ (form.get("character_strength", ["1.0"])[0] or "1.0"))except (TypeError, ValueError):- char_strength = 0.8+ char_strength = 1.0char_strength = max(0.0, min(2.0, char_strength))+ try:+ char_voice_strength = float(+ (form.get("character_voice_strength", ["1.0"])[0] or "1.0"))+ except (TypeError, ValueError):+ char_voice_strength = 1.0+ char_voice_strength = max(0.0, min(2.0, char_voice_strength))# LoRA stack: face always, audio when the character has one.# Extra LoRAs (style LoRAs like cinematronx, etc.) can be@@ -19673,7 +21118,8 @@ class Handler(BaseHTTPRequestHandler):# to prevent footguns.lora_stack = [{"path": char["face_lora_path"], "strength": char_strength}]if char.get("audio_lora_path"):- lora_stack.append({"path": char["audio_lora_path"], "strength": char_strength})+ lora_stack.append({"path": char["audio_lora_path"],+ "strength": char_voice_strength})extra_loras_raw = (form.get("extra_loras", [""])[0] or "").strip()if extra_loras_raw:try:@@ -19736,10 +21182,23 @@ class Handler(BaseHTTPRequestHandler):"frames": [str(frames)],"frame_rate": ["24"],"seed": [str(seed_int)],- "quality": ["high"],+ # THE RESOLVED quality, not a hardcoded "high". This line was+ # missed by the commit that added character_render_quality(),+ # so the Characters TAB kept doing exactly the two things that+ # function's docstring says it exists to prevent: routing 2.5+ # characters onto the two-stage HQ path nobody has graded them+ # on (~246 s instead of ~139 s), and demanding the 29.5 GB High+ # add-on for a result the q8 pack already delivers. The main+ # form was fixed; this lane was not, so the same character+ # rendered differently depending on which tab launched it —+ # the exact split the strength unification closed earlier.+ #+ # `quality` above is character_render_quality() unless the+ # caller asked for something explicitly: ltx25 -> balanced+ # (q8 + distilled, the graded recipe), ltx23 -> high.+ # make_job's character branch then routes the PACK to q8.+ "quality": [quality],"temporal_mode": ["native"],- "stage1_steps": [_val("stage1_steps", "10")],- "stage2_steps": [_val("stage2_steps", "3")],# HQ TeaCache default — 1.8 is the empirical sweet spot for# character mode (see make_job comment). Reverted from 1.0# after the 2026-05-20 chartest v3 diagnostic confirmed 1.0@@ -19763,6 +21222,17 @@ class Handler(BaseHTTPRequestHandler):job_form["audio"] = [audio_path]# Minimal Characters-origin metadata for Load Params restoration.+ # Schedule step counts ride only when the CALLER sent them — the+ # same rule make_job now follows. This form used to hardcode+ # stage1_steps=10, re-introducing the pad-request landmine that+ # cost Colorize/Restore 218 s per failed render: inert on the HQ+ # lane (which computes its schedule) but a live hazard the moment a+ # character routes to a thinning lane. On 2.3 nothing changes —+ # generate_hq's own default is the same 10.+ for _k in ("stage1_steps", "stage2_steps"):+ _v = form.get(_k, [""])[0]+ if _v:+ job_form[_k] = [_v]job_form["character_id"] = [cid]job_form["source"] = ["characters"]job_form["duration"] = [duration]@@ -20185,6 +21655,28 @@ class Handler(BaseHTTPRequestHandler):# `download` block for progress (existing infra).if path == "/train/install":key = (form.get("key", [""])[0] or "").strip()+ # The 2.3 base pack goes through the ORDINARY download lane — the+ # same singleton, the same progress tail, the same Resume and the+ # same deep-verify every other pack uses. A second downloader for+ # the trainer's benefit is exactly the improvisation this campaign+ # removes.+ if key == "ltx23_base":+ repo = next((r for r in _repos() if r.get("key") == "q4"), None)+ if not repo:+ self._json({"error": "LTX-2.3 is not a registered pack"}, 400); return+ with DOWNLOAD_LOCK:+ if DOWNLOAD["active"]:+ self._json({"error": f"another download is in progress: "+ f"{DOWNLOAD['repo_id']}. Wait for it to "+ f"finish (or click Cancel)."}, 409); return+ DOWNLOAD["active"] = True+ DOWNLOAD["key"] = "q4"+ DOWNLOAD["repo_id"] = repo["repo_id"]+ DOWNLOAD["started_ts"] = time.time()+ DOWNLOAD["last_line"] = "starting…"+ threading.Thread(target=_download_thread, args=(repo,), daemon=True).start()+ self._json({"ok": True, "key": "q4", "repo_id": repo["repo_id"]}, 202)+ returnif key != "ltx_dev_transformer":self._json({"error": f"unknown install key {key!r}"}, 400); returnresult = _train_install_dev_transformer(push)@@ -21094,7 +22586,12 @@ class Handler(BaseHTTPRequestHandler):})return- if path == "/stop":+ if path == "/stop" and qs.get("mode", [""])[0] != "early":+ # The HARD stop: kill the helper. Unchanged, and still what the+ # Stop button does. `?mode=early` is handled further down and is a+ # different thing entirely — it asks the render to stop itself at+ # the next forward boundary, which is why it needs its own branch+ # rather than a flag inside this one.stop_current_job()self._json({"ok": True}); return@@ -21136,6 +22633,137 @@ class Handler(BaseHTTPRequestHandler):threading.Thread(target=_download_thread, args=(repo,), daemon=True).start()self._json({"ok": True, "key": key, "repo_id": repo["repo_id"]}); return+ if path == "/stop" and qs.get("mode", [""])[0] == "early":+ # STOP EARLY — distinct from the hard /stop below, which kills the+ # helper. This one touches the ABORT sentinel the runner checks+ # between forwards; it stops cleanly at the next boundary and+ # exits 75.+ #+ # The two must not be the same button: a kill leaves a half-written+ # process to reap and reports as a cancellation of unknown shape,+ # while this is the render agreeing to stop.+ #+ # A FILE, not a signal, and that is the runner's design: a sentinel+ # works across a UI, a shell, an ssh session and a supervisor+ # without any of them holding the process handle. It also means+ # this endpoint cannot half-kill a render — the worst case is a+ # file nobody reads.+ with LOCK:+ cur = STATE.get("current")+ job_id = (cur or {}).get("id")+ if not job_id:+ self._json({"error": "nothing is rendering"}, 404); return+ d = live_preview_dir(job_id)+ if not d.is_dir():+ self._json({"error": "this render has no live preview to stop "+ "through — use Cancel."}, 409); return+ try:+ (d / "ABORT").touch()+ except OSError as exc:+ self._json({"error": f"could not write the stop sentinel: {exc}"}, 500); return+ push("Stop early requested — finishing the current step, then stopping.")+ self._json({"ok": True, "id": job_id}); return++ if path == "/models/remove":+ # POST { repo_key } — free the space a retired pack is holding.+ #+ # It REFUSES THREE THINGS, server-side, and says which. This is the+ # one endpoint in the panel that deletes multi-GB weights, so the+ # refusals are here rather than in the UI that calls it: a stale+ # tab, a replayed request or a curl must hit the same wall the+ # button does.+ #+ # And it NEVER TAKES A PATH FROM THE CLIENT. Every branch resolves+ # its own paths out of the registry from a key, so the worst a+ # malicious caller can do is delete a pack the registry names —+ # which is exactly what the button does.+ key = (form.get("repo_key", [""])[0] or "").strip()++ # (2) a download in flight is using that folder.+ with DOWNLOAD_LOCK:+ busy_key = DOWNLOAD.get("key") if DOWNLOAD["active"] else None++ targets: list[Path] = []+ label = ""+ if key.startswith("version:"):+ vid = key.split(":", 1)[1]+ ver = next((v for v in MODEL_VERSIONS if v["id"] == vid), None)+ if not ver:+ self._json({"error": f"unknown model version: {vid!r}"}, 400); return+ # (1) never the model this build renders with — and never the+ # REGISTRY DEFAULT either. Pinned back with+ # LTX_MODEL_VERSION=ltx23, `active` is ltx23, so this check+ # alone would have happily deleted 80 GB of 2.5: the generation+ # the product ships with, that the very next unset of that env+ # var boots into with no weights at all.+ if vid == ACTIVE_MODEL_VERSION:+ self._json({"error": "That's the model this build renders with."}, 400); return+ if (next((v for v in MODEL_VERSIONS if v["id"] == vid), {}) or {}).get("default"):+ self._json({"error": "That's the generation this build boots "+ "into by default — it is only inactive "+ "because LTX_MODEL_VERSION is set."}, 400); return+ for pack in ver.get("packs", ()):+ if busy_key and _quant_for_repo_key(busy_key, vid) == pack["quant"]:+ self._json({"error": "A download is using that folder — "+ "cancel it first."}, 409); return+ p = Path(pack["path"])+ if p.is_dir():+ targets.append(p)+ label = f"{ver['label']}"+ else:+ repo = next((r for r in _repos() if r.get("key") == key), None)+ # (3) not registered.+ if not repo:+ self._json({"error": f"unknown repo key: {key!r}"}, 400); return+ if busy_key == key:+ self._json({"error": "A download is using that folder — "+ "cancel it first."}, 409); return+ addon_key = model_version().get("hq_addon_repo_key")+ if key == addon_key:+ # The add-on has no directory of its own: delete exactly the+ # two files it consists of, BY NAME. A directory walk here+ # would delete the q8 pack.+ base = pack_path("q8")+ targets = [base / n for n in hq_weights().values()]+ label = f"{model_version()['label']} High add-on"+ else:+ _q = _quant_for_repo_key(key)+ if _q and _q in version_quants():+ self._json({"error": "That's the model this build renders with."}, 400); return+ if key == "gemma":+ self._json({"error": "Gemma 3 is also what Enhance and the "+ "Storyboard planner run on."}, 400); return+ # A directory SHARED by several repos must never be+ # rmtree'd by key: the three IC-LoRAs all resolve+ # mlx_models/loras/ic, so removing one would take all+ # three. When the directory is shared, delete exactly this+ # repo's own declared files — the same rule the HQ add-on+ # branch above follows, and for the same reason.+ p = ROOT / repo["local_dir"]+ shared = sum(1 for o in _repos()+ if str(o.get("local_dir")) == str(repo.get("local_dir"))) > 1+ if shared:+ targets = [p / f for f in (repo.get("files") or [])]+ elif p.is_dir():+ targets.append(p)+ label = repo.get("name") or key++ freed = 0+ for t in targets:+ try:+ if t.is_dir():+ freed += _dir_size_bytes(t)+ shutil.rmtree(t)+ elif t.is_file():+ freed += t.stat().st_size+ t.unlink()+ except OSError as exc:+ push(f"[storage] could not remove {t}: {exc}")+ self._json({"error": f"could not remove {t.name}: {exc}"}, 500); return+ push(f"[storage] removed {label} — {_fmt_gb(freed)} freed")+ self._json({"ok": True, "freed": freed, "freed_label": _fmt_gb(freed),+ "label": label}); return+if path == "/models/cancel":# Best-effort kill — the next status poll will see active=False.with DOWNLOAD_LOCK:@@ -21739,6 +23367,84 @@ def _compute_progress(current: dict | None, log_lines: list[str]) -> dict | None"remaining_sec": round(remaining, 1) if remaining is not None else None,"denoise_step": signals["denoise_step"],"denoise_total": signals["denoise_total"],+ **_preview_progress(current, remaining, phase),+ }+++def _preview_progress(current: dict | None, remaining: float | None,+ phase: str = "denoise") -> dict:+ """The live preview's half of `current.progress`, or {}.++ THE `meaningful` GATE IS DECIDED HERE, SERVER-SIDE, and that is the whole+ design. The rule differs per lane — estimate 6 of 8 on the distilled+ schedule, where DISTILLED_SIGMAS puts five of nine points at >= 0.975 and+ the first estimates are still essentially noise; estimate 2 on res_2s,+ whose even substep estimates are clean from the start — so a client+ counting estimates would have to know which schedule is running. It never+ has to: it renders what this says.++ Why it matters beyond tidiness: the abort affordance must NOT appear before+ the preview means something. A Stop-early button over a noise field is a+ trap — the user aborts a take that was going to be fine."""+ if not current:+ return {}+ d = live_preview_dir(current.get("id") or "")+ try:+ st = json.loads((d / "status.json").read_text())+ except (OSError, ValueError):+ return {}+ latest = d / "preview_latest.png"+ if not latest.is_file():+ return {}+ q = (current.get("params") or {}).get("quality") or ""+ cell = LTX_QUALITIES.get(q, {})+ need = int(cell.get("preview_meaningful_at") or 1)+ every = max(1, int(cell.get("preview_every") or 1))+ # `forward` counts denoiser evaluations; the PUBLISHED series is every Nth.+ published = int(st.get("forward") or 0) // every+ meaningful = published >= need+ prev = {+ # Cache-busted server-side: the file is rewritten in place, atomically,+ # and a browser that caches it would show the first estimate forever.+ # /image, NOT /file — and this one word was the whole of BLOCK-1.+ #+ # `latest` lives under STATE_DIR (state/live/<job>/preview_latest.png).+ # /file serves OUTPUT only and 404s on anything else; /image already+ # admits OUTPUT, UPLOADS and STATE_DIR, and already does thumbnail+ # resizing, which is exactly what a 96 px card wants. So every render+ # published a correct preview, wrote a correct <img src>, and the+ # browser drew a broken-image glyph.+ #+ # The alternative — widening /file's roots to STATE_DIR — was refused:+ # /file is the VIDEO endpoint with Range support, and handing it the+ # whole state directory to serve makes settings, queue and stats files+ # fetchable to buy nothing the narrow fix does not already give.+ #+ # Everything behind this line was right (the lane rule, the meaningful+ # gate, saves_sec, the PNGs on disk). The spec itself wrote+ # "/file?path=…" into the §4.2 contract, so the implementation matched+ # the spec and the review matched the contract, and neither loaded the+ # image. The same URL feeds the storyboard's #sbRunThumb via the+ # preview_url alias below, so both consumers were broken by one word.+ "url": f"/image?path={quote(str(latest))}&t={int((d / 'status.json').stat().st_mtime)}",+ "estimate": published,+ "total": max(1, int(st.get("total_forwards") or 0) // every),+ "meaningful": meaningful,+ # Abortable only once the picture means something AND the runner has+ # published somewhere to put the sentinel.+ # Only while there is still denoising to abort. The sentinel is checked+ # BETWEEN FORWARDS, so once the loop has handed off to VAE decode and+ # mux there is nothing left to stop — and offering to save 30 s four+ # seconds from the end is an offer the render cannot honour.+ "abortable": bool(meaningful and d.is_dir() and phase == "denoise"),+ "saves_sec": round(remaining, 1) if remaining is not None else None,+ }+ return {+ "preview": prev,+ # Top-level alias, because the storyboard spec already designed+ # #sbRunThumb against exactly this key. One line keeps a shipped+ # surface working with no edit.+ "preview_url": prev["url"] if meaningful else None,}@@ -21850,6 +23556,12 @@ def page() -> str:# points at this block by name (its `probe` key), rather than the# switcher knowing anything about H3 in particular."h3": h3_status(),+ # LTX's own (quality × length) table, in the SAME shape as `h3` above so+ # the two strips are rendered by one generalised function rather than+ # two that drift. Every LTX estimate the page prints is a lookup into+ # this — the browser never computes a canvas, a frame count or a wall+ # clock of its own.+ "ltx": ltx_tiers_payload(),# Storyboard — planner presence, the RAM copy, the shot/quality choices# and the boards already on disk. In the bootstrap (not just /status) so# the tab renders its real state on first paint instead of flickering.@@ -22705,6 +24417,10 @@ HTML = r"""<!doctype html>.sb-enginepick-note b { color: var(--text); font-weight: 600; }.sb-chip-pass { cursor: pointer; }.sb-chip-pass:hover { color: var(--text); border-color: var(--border-strong); }+ /* Read-only, and it appears ONLY on shots that speak. There is no "silent"+ chip: silence is the honest default and a chip for it would be noise on+ every other card. */+ .sb-chip-voice { cursor: default; }.sb-shot-est {font-size: 10.5px; color: var(--muted); flex: 0 0 auto;font-family: var(--ph-font-mono, ui-monospace, Menlo, monospace);@@ -26732,12 +28448,64 @@ HTML = r"""<!doctype html>opacity: 1;position: relative;}+ /* STOPPED sits directly beside FAILED so the two can never disagree about+ the card's geometry — but it is --muted, not --danger. The user stopped+ this on purpose; nothing was saved, and nothing went wrong. */+ .now-card.stopped {+ border-color: var(--border-strong);+ background: rgba(140,160,220,0.05);+ opacity: 1;+ position: relative;+ }/* Reserve room on the right of the title/meta so the action row(Retry + Close) doesn't overlap the text it sits next to. */.now-card.failed .ttl,- .now-card.failed .meta {+ .now-card.failed .meta,+ .now-card.stopped .ttl,+ .now-card.stopped .meta {padding-right: 140px;}+ /* ---- the live-preview slot -------------------------------------------+ A fixed 16:9 box, always the same size once a render starts, so the+ thumbnail's ARRIVAL causes no reflow. The card becomes a two-column+ flex only while the box is shown. */+ /* POSITION:RELATIVE UNCONDITIONALLY. `.now-card-actions` is+ position:absolute, and only `.failed` / `.stopped` established a+ containing block — because that row had only ever been populated after a+ job ended. v4.0 is the first release to put a button there WHILE a job+ runs, and a running card is plain `.now-card`, so Stop early resolved+ against the initial containing block and rendered in the page header,+ 870 px from the thumbnail it refers to. It snapped into place only once+ the job stopped and `.stopped` supplied the relative — i.e. exactly when+ it was no longer needed. */+ .now-card { display: flex; gap: 12px; align-items: flex-start; position: relative; }+ .now-card > .now-body { flex: 1; min-width: 0; }+ .now-thumb {+ flex: 0 0 auto;+ width: 96px; aspect-ratio: 16 / 9;+ border-radius: var(--r-sm);+ background: var(--bg-2);+ border: 1px solid var(--border);+ overflow: hidden;+ position: relative;+ }+ .now-thumb[hidden] { display: none; }+ .now-thumb img { width: 100%; height: 100%; object-fit: cover; display: block; }+ /* WARMING — the estimates so far are still essentially noise, so there is+ nothing worth showing and nothing worth judging. A placeholder that+ breathes, flattened by the global prefers-reduced-motion rule. */+ .now-thumb.is-warming::after {+ content: "";+ position: absolute; inset: 0;+ background: currentColor;+ opacity: .18;+ -webkit-mask: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 5h16v14H4z" fill="none" stroke="black" stroke-width="1.6"/><path d="M4 9h16M4 15h16M8 5v14M16 5v14" stroke="black" stroke-width="1.2"/></svg>') center/60% no-repeat;+ mask: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 5h16v14H4z" fill="none" stroke="black" stroke-width="1.6"/><path d="M4 9h16M4 15h16M8 5v14M16 5v14" stroke="black" stroke-width="1.2"/></svg>') center/60% no-repeat;+ animation: nowThumbPulse 2.4s ease-in-out infinite;+ }+ @keyframes nowThumbPulse { 0%,100% { opacity:.10 } 50% { opacity:.26 } }+ /* ABORTING — frozen on the last frame it managed to show. */+ .now-thumb.is-aborting img { opacity: .55; }/* Failure-card action row — Retry + Close on the failed Now card.Lives in its own sibling element of .ttl so poll()'s rewritesdon't replace the buttons mid-click. Pinned to the top-right of@@ -27553,6 +29321,55 @@ HTML = r"""<!doctype html>min-width: 28px; text-align: right;}+ /* `split` — a TEXT affordance, not a chevron, because it sits inside a+ one-line control where a rotating glyph would read as decoration. Same+ aria-expanded contract as .help-dot. */+ .chars-strip-active .chars-split-toggle {+ background: transparent;+ border: 1px solid var(--ph-border-soft);+ border-radius: 4px;+ padding: 1px 6px;+ font-size: 10px; font-family: var(--ph-font-mono);+ color: var(--muted); cursor: pointer;+ white-space: nowrap;+ }+ .chars-strip-active .chars-split-toggle:hover {+ color: var(--text); border-color: var(--ph-border-strong);+ }+ .chars-strip-active .chars-split-toggle[aria-expanded="true"] {+ color: var(--accent-bright); border-color: var(--accent);+ }+ /* The disclosure. Full width under the one-line row, so the two sliders+ line up with each other rather than with the name beside them. */+ .chars-strip-active .chars-split {+ flex-basis: 100%;+ margin-top: 6px;+ padding-top: 6px;+ border-top: 1px solid var(--ph-border-soft);+ display: flex; flex-direction: column; gap: 4px;+ }+ .chars-strip-active .chars-split-line {+ display: flex; align-items: center; gap: 6px;+ font-size: 10px; color: var(--muted);+ }+ .chars-strip-active .chars-split-line > span:first-child {+ min-width: 34px;+ }+ .chars-strip-active .chars-split-line input[type="range"] {+ width: 140px; accent-color: var(--accent);+ }+ .chars-strip-active .chars-split-line output {+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;+ font-size: 11px; color: var(--text);+ min-width: 28px; text-align: right;+ }++ /* A Storage row that is KEPT on purpose: informational, never a warning.+ It used to reuse `.partial`, which paints an amber border and a warning+ glyph — trouble signalling on a healthy file. */+ .models-list li.kept { border-color: var(--border); }+ .models-list li.kept .icon { color: var(--muted); }+.chars-strip-empty {font-size: 11px; color: var(--muted);padding: 4px 2px;@@ -27563,14 +29380,22 @@ HTML = r"""<!doctype html>Q8-capable machines never see it; shown only when the page renders inthe Q4 tier (16 GB / Q4 fallback), where a character fuses into thedistilled base and identity comes out approximate vs. faithful on Q8. */+ /* SCOPED ON PACK PRESENCE, not on cap-tier, and the difference now matters.+ `cap_tier` is the FEATURE tier — "how much RAM does this Mac have, folded+ down to what this generation can serve". It does NOT answer "are the+ weights on disk", and on 2.5 those two diverge for the first time: a+ 64 GB Mac holding only q4_25 resolves cap_tier=q8, so a note warning+ about approximate identity would NOT have shown while the Q8 chips+ offered weights that are not there. #qualityGroup's own `high` hide rule+ stays on cap-tier because that one really is the feature question. */.chars-q4-note { display: none; }- body[data-cap-tier="q4"] .chars-q4-note {+ body[data-q8-pack="missing"] .chars-q4-note {display: block;font-size: 11px; line-height: 1.5;color: var(--muted);padding: 4px 2px 2px;}- body[data-cap-tier="q4"] .chars-q4-note b { color: var(--text); font-weight: 600; }+ body[data-q8-pack="missing"] .chars-q4-note b { color: var(--text); font-weight: 600; }/* Manage characters modal — list view with rename + delete per row. */.chars-manage-list {@@ -28521,6 +30346,14 @@ HTML = r"""<!doctype html>background: rgba(140, 160, 220, 0.08);border: 1px solid var(--ph-border-soft);}+ /* The generation line. The label answers "which engine"; this answers+ "which build", muted, in the same span slot as the badge beside it. It+ is derived from the ACTIVE model version, so it reads 2.5 here and 2.3+ for a user pinned back with LTX_MODEL_VERSION=ltx23. */+ body > header .eng-seg-gen {+ font-size: 10px; font-weight: 600; letter-spacing: .3px;+ color: var(--muted); margin-left: 5px; font-family: var(--ph-font-mono);+ }/* An offer (download / repair) is worth the engine's own colour; a plainconstraint ("text · image", "soon") is not. */body > header .eng-badge.offer {@@ -28535,6 +30368,7 @@ HTML = r"""<!doctype html>@media (max-width: 1500px) {body > header .eng-seg { padding: 0 4px; gap: 0; }body > header .eng-seg .eng-seg-name { display: none; }+ body > header .eng-seg .eng-seg-gen { display: none; }body > header .eng-badge { display: none; }}@@ -29197,12 +31031,17 @@ HTML = r"""<!doctype html>.h3-winhelp[hidden] { display: none !important; }</style></head>-<!-- data-cap-tier is set at request time by page() based on SYSTEM_CAPS.allows_q8- (or the LTX_FORCE_CAP_TIER env override). CSS rules- `body[data-cap-tier="q4"]` and `body[data-cap-tier="q8"]` switch which- intents are visible: q4 hides FFLF / Extend / Character (Q8-only pipeline- paths); q8 surfaces all five intents. window.PHOSPHENE_CAP_TIER mirrors- this for any runtime JS branches. -->+<!-- data-cap-tier is set at request time by page() from _resolve_cap_tier() —+ the FEATURE tier: this Mac's RAM, folded down to what the active+ generation can serve (or the LTX_FORCE_CAP_TIER env override). CSS rules+ `body[data-cap-tier="q4|q8"]` switch which intents are visible.+ window.PHOSPHENE_CAP_TIER mirrors it for runtime JS branches.++ IT DOES NOT ANSWER "are the weights on disk" — that is `data-q8-pack`,+ written every poll from /status. On 2.5 the two diverge for the first+ time: a 64 GB Mac holding only the base pack resolves cap_tier=q8 and+ still cannot render a trained character. Both must be able to be true;+ see §11-E of the v4.0 spec. --><!-- data-engine is stamped in the markup, not left for setEngine() to add onboot: the per-engine fold rules (`body:not([data-engine="ltx"])[data-ltx-only]`) match a body with NO attribute, so every LTX-only@@ -29466,6 +31305,12 @@ HTML = r"""<!doctype html><input type="hidden" name="preset_label" id="preset_label" value=""><input type="hidden" name="mode" id="mode" value="t2v"><input type="hidden" name="quality" id="quality" value="balanced">+ <!-- The DURATION axis's own field. It is a LABEL for the shape, not the+ shape itself: #duration and #frames remain what the render reads, and+ _ltxApplyShape writes all three together. A cell key here means "the+ user picked this rung"; empty means a custom duration, which lights+ no chip and prints itself in #ltxLengthMeta. -->+ <input type="hidden" name="ltx_length" id="ltx_length" value="5s"><input type="hidden" name="accel" id="accel" value="off"><input type="hidden" name="temporal_mode" id="temporal_mode" value="native"><input type="hidden" name="upscale" id="upscale" value="fit_720p">@@ -29513,7 +31358,7 @@ HTML = r"""<!doctype html>title="Rescan mlx_models/characters/ for new bundles"onclick="refreshManualCharacters()"><svg class="ph" aria-hidden="true"><use href="#ph-arrow-clockwise-bold"/></svg></button></div>- <div class="chars-q4-note"><b>Q4 fallback:</b> on this machine characters render on the fast (distilled) base — identity comes out <em>approximate</em>. A Q8-capable Mac renders faithful faces.</div>+ <div class="chars-q4-note"><b>Trained characters need the Q8 weights.</b> Right now this Mac has the base pack, so the trained face comes out approximate. <a href="#" onclick="openModelsModal();return false;">Install Q8 (30 GB) →</a></div><!-- One-liner that surfaces under the strip when a character isactive. Shows trigger word + a tiny strength control inline.charsSummaryMeta stays as a hidden carrier for legacy JS@@ -29538,6 +31383,14 @@ HTML = r"""<!doctype html></div><input type="hidden" name="character_id" id="characterIdInput" value=""><input type="hidden" name="character_strength" id="characterStrength" value="1.0">+ <!-- The VOICE half of a character's strength. A character is two trained+ files and the face file's audio-branch deltas are noise that is+ louder than the voice file's signal at equal strength — so running+ the voice hotter is what makes it win, and the split control below is+ how you do it. The DEFAULT is the graded pair, 1.0/1.0; the hotter+ rungs are an ear's decision, not the shipped starting point.+ MUST be in make_job's named reads or it silently no-ops. -->+ <input type="hidden" name="character_voice_strength" id="characterVoiceStrength" value="1.0"><!-- ============== COMPOSER CARD ==============Hero element of the form. Carries the reference picker(s)@@ -29873,9 +31726,10 @@ HTML = r"""<!doctype html>on H3 the toggle could only ever be a no-op. --><label class="toggle-pill" id="noVoicePill" hidden data-ltx-onlytitle="Skip the character's voice LoRA for this render. The face still locks, but audio stays ambient — no speech, no gibberish.">- <input type="checkbox" id="noVoice" name="no_voice">+ <input type="checkbox" id="noVoice" name="no_voice"+ onchange="markNoVoiceTouched()"><span class="toggle-dot"></span>- <span>No voice</span>+ <span id="noVoiceLabel">No voice</span></label></div></div>@@ -29976,28 +31830,38 @@ HTML = r"""<!doctype html>inference uses transformer-distilled.safetensors and theidentity barely locks). Forcing quality=high here meansthe user can't accidentally ship a Q4 character render. -->- <div class="quality-strip pill-group" id="qualityGroup" data-ltx-only>- <button type="button" class="q-chip pill-btn pill-quality" data-quality="quick">- <span class="ql-name">Quick</span>- <span class="q-spec ql-spec sub">640×480</span>- <span class="ql-tier" hidden>Q4 · any Mac</span>- </button>- <button type="button" class="q-chip pill-btn pill-quality active" data-quality="balanced">- <span class="ql-name">Balanced</span>- <span class="q-spec ql-spec sub">1024×576</span>- <span class="ql-tier" id="balancedSub">Q4 · 5 min</span>- </button>- <button type="button" class="q-chip pill-btn pill-quality" data-quality="standard">- <span class="ql-name">Standard</span>- <span class="q-spec ql-spec sub">1280×704</span>- <span class="ql-tier" hidden>Q4 · standard tier+</span>- </button>- <button type="button" class="q-chip pill-btn pill-quality disabled" data-quality="high" id="qualityHigh">- <span class="ql-name">High</span>- <span class="q-spec ql-spec sub" id="highSpec">1024×576</span>- <span class="ql-tier" id="highSub">Q8 not installed</span>- </button>+ <!-- LTX's CANVAS axis. Rendered by renderTierAxes('ltx') from+ BOOT.ltx.qualities / .lengths / .tiers, exactly as H3's two+ strips are, so the server-side table is the single source of+ truth for geometry and every estimate.++ These four chips used to be static markup carrying hand-written+ subtitles ("Q4 · 5 min", "Q8 Pro · 7 min") kept up to date by two+ separate JS updaters — numbers no measurement on 2.5 supported.+ The table fills the third slot now, the way H3's already did, and+ both updaters are deleted.++ `data-quality` is UNCHANGED: five surfaces read it (the click+ handler, setQuality's active toggle, applyTierTimes, the+ trained-LoRA compatibility gate, the character-strip swap). -->+ <div class="quality-strip pill-group" id="qualityGroup" data-ltx-only></div>+ <!-- LTX's DURATION axis — the same second row H3 grew, for the same+ reason: a canvas and a length are independent choices and one+ strip cannot express both. Duration used to be a free numeric+ field whose value one lane silently rounded away. The field+ itself is not deleted (power users have shipped work with it);+ it lives in Customize and a value off the axis lights no chip. -->+ <div class="ltx-axes" id="ltxAxes" data-ltx-only>+ <div class="qs-label h3-axis-label">+ <span class="qs-name">Length</span>+ <span class="qs-meta" id="ltxLengthMeta"></span>+ </div>+ <div class="quality-strip pill-group" id="ltxLengthGroup"></div></div>+ <!-- The selected cell's honest notes, joined — the mirror of+ #h3TierNote. Empty and hidden when the combination has nothing+ to warn about, which is most of them. -->+ <div class="engine-hint" id="ltxTierNote" hidden></div><!-- Character-only quality strip — revealed by selectManualCharacterwhen a character is selected. Both buttons submit quality=high(the only inference path that matches dev-trained character@@ -30011,16 +31875,24 @@ HTML = r"""<!doctype html>active, switching to H3 left this strip lit BESIDE the H3 tierstrip — two primary strips, both claiming to set the render. Thefold rule settles it declaratively, whatever the JS believes. -->+ <!-- The two chips' PIPELINE and their ETAs are filled by+ renderCharacterStrip() from BOOT.ltx.character, which the server+ resolves per generation. The markup carries geometry and nothing+ else, deliberately: 2.3 renders characters on the two-stage HQ+ path and 2.5 on q8 + distilled (the exact recipe every graded 2.5+ character clip ran), and two generations each carrying a copy of+ that rule is how they drift. "~2 min" on Q8 Pro is the MEASURED+ 139.4 s row, not a typed number. --><div class="quality-strip pill-group" id="qualityGroupCharacter" hidden data-ltx-only>- <button type="button" class="q-chip pill-btn pill-quality char-quality" data-char-quality="draft" data-width="736" data-height="416" title="Q8 HQ at 736×416 — faster, slightly less per-frame detail.">+ <button type="button" class="q-chip pill-btn pill-quality char-quality" data-char-quality="draft" data-width="704" data-height="384"><span class="ql-name">Q8 Draft</span>- <span class="q-spec ql-spec sub">736×416</span>- <span class="ql-tier">Q8 HQ · ~3 min / 5s</span>+ <span class="q-spec ql-spec sub">704×384</span>+ <span class="ql-tier"></span></button>- <button type="button" class="q-chip pill-btn pill-quality char-quality active" data-char-quality="pro" data-width="1024" data-height="576" title="Q8 HQ at 1024×576 — locked production recipe, best identity.">+ <button type="button" class="q-chip pill-btn pill-quality char-quality active" data-char-quality="pro" data-width="1024" data-height="576"><span class="ql-name">Q8 Pro</span><span class="q-spec ql-spec sub">1024×576</span>- <span class="ql-tier">Q8 HQ · ~5 min / 5s · best identity</span>+ <span class="ql-tier"></span></button></div><!-- Hailuo H3 render shape — TWO INDEPENDENT AXES, not one fixed tier@@ -30258,14 +32130,6 @@ HTML = r"""<!doctype html><div class="mode-only show" id="quickMetricsRow"><div class="mini-fields">- <div class="mf-cell" data-ltx-only>- <span class="mf-label">Duration (s)</span>- <input id="duration" value="5" type="number" min="1" max="20" step="any">- </div>- <div class="mf-cell" data-ltx-only>- <span class="mf-label">Frames <span class="mf-hint">8k+1</span></span>- <input name="frames" id="frames" value="121" type="number" min="1" title="Must be 8k+1 (e.g., 121, 161, 201). Duration auto-syncs.">- </div><div class="mf-cell"><span class="mf-label">Seed <span class="mf-hint">-1 = random</span></span><input name="seed" id="seed" value="-1" title="-1 picks a fresh random seed per render. Any integer locks the seed for repeatable output.">@@ -30462,6 +32326,26 @@ HTML = r"""<!doctype html></div></div>+ <!-- Duration / Frames — the power-user override, MOVED HERE in+ v4.0 (spec §2.2). It used to sit in the primary form ~60 px+ under the Length chips, which meant the panel showed a+ 5-second, ~2-minute shape while the form would render 337+ frames: the release's own headline bug, two rows below the+ control that fixed it.++ NOT deleted — power users have shipped work with the raw+ Frames box, and removing a control people use is not polish.+ It lives with every other override, and a value off the axis+ lights no chip and prints `custom · 337f · 14 s` in the Length+ meta. -->+ <div id="durationRow" class="cz-control" data-ltx-only>+ <div class="cz-label">Duration <span class="cz-label-hint">seconds, and the frames it lands on</span></div>+ <div class="row">+ <div><input id="duration" value="5" type="number" min="1" max="20" step="any" aria-label="Duration in seconds"></div>+ <div><input name="frames" id="frames" value="121" type="number" min="1" aria-label="Frames" title="Must be 8k+1 (e.g., 121, 161, 201). Duration auto-syncs."></div>+ </div>+ </div>+<!-- 2026-05-17 (Codex C+ pass 5): the Speed (Boost/Turbo)acceleration row used to live here. Killed from the publicsurface — it's a Q4-distilled-pipeline-only knob; the Q8@@ -31649,7 +33533,7 @@ HTML = r"""<!doctype html><button type="button" class="ghost-btn js-get-sample-char" style="padding:2px 8px;font-size:12px"onclick="downloadSampleCharacter()">get a sample character (Bizarro)</button>.</div>- <div class="chars-q4-note"><b>Q4 fallback:</b> on this machine characters render on the fast (distilled) base — identity comes out <em>approximate</em>. A Q8-capable Mac renders faithful faces.</div>+ <div class="chars-q4-note"><b>Trained characters need the Q8 weights.</b> Right now this Mac has the base pack, so the trained face comes out approximate. <a href="#" onclick="openModelsModal();return false;">Install Q8 (30 GB) →</a></div></div><details class="customize-section" id="sbMustSection">@@ -31760,11 +33644,13 @@ HTML = r"""<!doctype html><div class="mini-fields"><div class="mf-cell"><span class="mf-label">Width</span>- <input type="number" id="audioStudioWidth" value="1024" min="256" max="1920" step="32">+ <input type="number" id="audioStudioWidth" value="1024" min="256" max="1920" step="32"+ oninput="audioStudioDurationChanged()"></div><div class="mf-cell"><span class="mf-label">Height</span>- <input type="number" id="audioStudioHeight" value="576" min="256" max="1920" step="32">+ <input type="number" id="audioStudioHeight" value="576" min="256" max="1920" step="32"+ oninput="audioStudioDurationChanged()"></div><div class="mf-cell"><span class="mf-label">Seed</span>@@ -32123,7 +34009,7 @@ HTML = r"""<!doctype html><div class="cz-control"><div class="cz-label">Draft pass <span class="cz-label-hint">what you watch first</span></div><div class="pill-group cols-3" id="sbDraftQuality">- <button type="button" class="pill-btn active" data-q="quick">Quick<span class="sub">640×480</span></button>+ <button type="button" class="pill-btn active" data-q="quick">Quick<span class="sub">640×448</span></button><button type="button" class="pill-btn" data-q="balanced">Balanced<span class="sub">768×432</span></button><button type="button" class="pill-btn" data-q="standard">Standard<span class="sub">1024×576</span></button></div>@@ -32326,6 +34212,21 @@ HTML = r"""<!doctype html><select id="settingsMemoryPolicy" style="flex:1"></select></div><div class="hint" id="settingsMemoryPolicyHint" style="margin-top:6px"></div>+ <!-- A speed/behaviour setting, so it belongs in this section rather than+ in one of its own. -->+ <div class="settings-row" style="margin-top:10px">+ <label>Live preview</label>+ <select id="settingsLivePreview" style="flex:1">+ <option value="on">On — show the shot as it forms</option>+ <option value="off">Off</option>+ </select>+ </div>+ <div class="hint" style="margin-top:6px">+ Never changes the result — the clip is byte-for-byte the same either way.+ Costs a fraction of the render: about 0.2 % on High, a few per cent on a+ short draft, where the render is short enough for the decode to show.+ Turning it off also removes the Stop-early button.+ </div></div><div class="settings-section">@@ -32344,6 +34245,27 @@ HTML = r"""<!doctype html></div></div>+ <!-- Storage. Directly after its only disk-facing sibling on purpose: one+ section says WHAT IS INSTALLED, the next says WHAT CAN GO.++ It renders NOTHING — including its own <h3> — when there is nothing to+ reclaim, so a single-generation install never sees it. That is rule 5:+ a user who never opens a pack sees no new chrome at all.++ .models-list / .models-foot are reused wholesale, so a Storage row and+ a Models row look like siblings because they are. -->+ <div class="settings-section" id="settingsStorageSection" style="display:none">+ <h3>Storage</h3>+ <div class="hint" style="margin-bottom:8px">+ Weights on this disk that this build does not render with by default —+ and, where one is listed, what you would lose by removing it. Removing+ frees the space immediately; re-installing later is a fresh download of+ the size shown. Nothing here is deleted without asking.+ </div>+ <ul class="models-list" id="storageList"></ul>+ <div class="models-foot" id="storageFoot"></div>+ </div>+<div class="settings-section"><h3>API tokens</h3><div class="hint" style="margin-bottom:8px">@@ -32440,7 +34362,8 @@ HTML = r"""<!doctype html><div class="hint" style="margin-bottom:10px">Sends anonymous counts so bugs in the field get noticed: panelversion, hardware class (e.g. <em>M4 Max, 64 GB</em>), which- optional packs are installed, and for each render the engine,+ model generation you render with, which optional packs are+ installed, and for each render the engine,tier, resolution, frame count and a coarse duration bucket —plus the first line of the error when one fails.<b>Never your prompts, filenames, paths, images or video.</b>@@ -32700,14 +34623,21 @@ HTML = r"""<!doctype html></nav><div class="bottom-body"><div class="tab-content show" id="tab-now">+ <!-- The live-preview slot is a FIXED 16:9 box that is present from the+ moment a render starts, so the arrival of a thumbnail causes NO+ layout shift — the storyboard spec's rule, carried over verbatim.+ It is display:none while idle and reserves its own space otherwise. --><div class="now-card idle" id="nowCard">- <div class="ttl">Idle</div>- <div class="progress-bar"><div class="fill" id="progressFill" style="width:0%"></div></div>- <div class="meta" id="nowDetail">No job running</div>- <!-- Action row populated on the failed state with Retry + Close.- Lives outside .ttl so poll()'s innerHTML rewrites don't- clobber the buttons mid-click. Hidden when empty. -->- <div class="now-card-actions" id="nowCardActions"></div>+ <div class="now-thumb" id="nowThumb" hidden aria-hidden="true"></div>+ <div class="now-body">+ <div class="ttl">Idle</div>+ <div class="progress-bar"><div class="fill" id="progressFill" style="width:0%"></div></div>+ <div class="meta" id="nowDetail">No job running</div>+ <!-- Action row populated on the failed state with Retry + Close.+ Lives outside .ttl so poll()'s innerHTML rewrites don't+ clobber the buttons mid-click. Hidden when empty. -->+ <div class="now-card-actions" id="nowCardActions"></div>+ </div></div></div><div class="tab-content" id="tab-queue">@@ -32816,20 +34746,20 @@ window.PHOSPHENE_CAP_TIER = (BOOT.cap_tier || 'q8');// of the optimistic baseline. Runs once on boot, plus when the tier modal// reports new info (rare — tier is fixed for a given Mac).function applyTierTimes() {- const qt = (BOOT.quality_times || {});- document.querySelectorAll('#qualityGroup .pill-quality').forEach(btn => {- const key = btn.dataset.quality;- const time = qt[key];- const spec = btn.querySelector('.ql-spec');- if (!spec) return;- const dimsMatch = spec.textContent.match(/^([0-9]+×[0-9]+(\s+→\s+[0-9p]+)?)/);- const dims = dimsMatch ? dimsMatch[1] : '';- if (time && dims) {- spec.textContent = `${dims} · ${time}`;- } else if (time) {- spec.textContent = time;- }- });+ // NO-OP for the LTX strip since v4.0, deliberately, and kept as a named+ // function because the tier modal still calls it.+ //+ // This was the THIRD writer of the LTX chips' subtitles, and it wrote a+ // per-hardware-tier estimate into the .ql-spec slot that now carries the+ // canvas and the frame count. Two writers for one span is how a chip ends up+ // claiming "1024×576 · about 8 min" for a render the table prices at ~2 min.+ //+ // The tier-aware estimate is not lost: BOOT.quality_times is a RAM-tier+ // figure, and the tier table's own model is anchored on renders measured on+ // this class of machine. When a per-tier coefficient is wanted it belongs in+ // ltx_estimate_minutes(), server-side, where one number serves the chip, the+ // Length meta and the queue card at once.+ return;}// Keyframe mode toggle — 2-frame FFLF, or any 3–8-anchor long shot.@@ -33252,14 +35182,36 @@ function _autoMainOutputsFilterForMode(mode) {// Model tag in the bottom-pane nav links to dgrauet's repo. Strip an// absolute filesystem path back to the HF repo id form for display// (the panel sets LTX_MODEL to a local path in Pinokio installs).-(function () {- const m = String(BOOT.model || '');+// THE CREDIT NAMES THE WEIGHTS THAT MADE THE CLIP YOU ARE LOOKING AT.+//+// It used to be a one-shot read of BOOT.model at page load, so it printed the+// active LTX pack under an H3 render, and under every clip ever made on another+// generation. The sidecar has always known which model ran; list_outputs now+// carries it, so the credit follows the SELECTION rather than the process.+//+// A clip that predates the field has no `model` and falls back to BOOT.model+// silently — the old behaviour, for the only case where it was ever right.+function _modelCreditLabel(raw) {+ const m = String(raw || '');+ if (!m) return '';let label = m;const idx = m.indexOf('mlx_models/');if (idx >= 0) label = m.slice(idx + 'mlx_models/'.length);if (label.startsWith('/')) label = label.split('/').slice(-2).join('/');- document.getElementById('modelTag').textContent = label;-})();+ return label;+}+function updateModelCredit(path) {+ const el = document.getElementById('modelTag');+ if (!el) return;+ let raw = '';+ try {+ const p = path || (typeof activePath !== 'undefined' ? activePath : '');+ const entry = (typeof currentOutputs !== 'undefined' && currentOutputs || []).find(o => o && o.path === p);+ if (entry && entry.model) raw = entry.model;+ } catch (e) {}+ el.textContent = _modelCreditLabel(raw || BOOT.model);+}+updateModelCredit();// `audio` is still a free-text input (advanced section); `image` is now a// picker — leave the picker empty by default and let the user pick or// drop. Pre-filling examples/reference.png surprised users into rendering@@ -35482,34 +37434,63 @@ function audioStudioRenderSlots() {// rounded up to the 8k+1 grid), so the number shown is the number the model// is actually asked for — not a rounded-down approximation of it.//-// This warns rather than blocks on purpose. What is known about where A2V-// gives out is two independent field reports converging on ~257 frames-// (#46): @blackest saw anatomy break around 337f and the picture go white-// by 433f here, and hit the same wall at 257f on a different MLX pipeline.-// Nobody has measured it in this repo, and the question that decides whether-// it is a length ceiling at all — does the AUDIO survive past the point the-// picture dies — is still unanswered. So the slider keeps its range and the-// panel stops being silent about the risk. 241f (10 s) is the last 8k+1 stop-// under 257.+// This warns rather than blocks on purpose, and as of 3.8.3 it warns on the+// right quantity.+//+// It used to fire on FRAME COUNT alone, past ~257. @blackest then answered the+// two questions that were open in #46, and both answers moved the target:+//+// 1. The AUDIO survives. "I am certain it continues right to the end of the+// 20 seconds" — so this is the picture running out of coherence, not the+// joint sequence failing.+// 2. It is not a frame cap. Same 20 s request, same machine (M2 Max 96 GB):+// 640x480 481 frames fine, all 20 s+// 1024x576 481 asked picture dies at frame ~454+// 1280x720 481 asked white out by 481+// "I think its not so much a frame cap but a limit on how many frames at+// x size can be generated."+//+// So the budget is frames x AREA, and the old warning was simply wrong in the+// case that matters most: it shouted at a 640x480 20 s render that works.+//+// A2V_PIXEL_BUDGET is the largest configuration anyone has reported working —+// 640x480 x 481 = 147.7 Mpx — rounded to 150. It is a field observation from+// one machine, not a measurement made here, and the copy says so. Anything+// derived from it (the max frames for the chosen canvas) is presented as+// guidance, never as a cap: the slider keeps its full range.+const A2V_PIXEL_BUDGET = 150e6;function _a2vFramesForSeconds(sec) {const target = Math.max(1, Math.round(sec * 24));return ((target - 1 + 7) >> 3 << 3) + 1; // round up to 8k+1}function audioStudioDurationChanged(val) {- const sec = parseInt(val || '7', 10);+ const slider = document.getElementById('audioStudioDuration');+ // Called with no argument from the Width/Height inputs, so the canvas and+ // the length always warn against each other rather than in isolation.+ const sec = parseInt((val !== undefined && val !== null ? val+ : (slider ? slider.value : '7')) || '7', 10);const out = document.getElementById('audioStudioDurationVal');if (out) out.textContent = sec + ' s';const warn = document.getElementById('audioStudioDurationWarn');if (!warn) return;const frames = _a2vFramesForSeconds(sec);- if (frames > 257) {+ const w = parseInt((document.getElementById('audioStudioWidth') || {}).value || '1024', 10);+ const h = parseInt((document.getElementById('audioStudioHeight') || {}).value || '576', 10);+ const area = (w > 0 && h > 0) ? w * h : 1024 * 576;+ if (frames * area > A2V_PIXEL_BUDGET) {+ // The longest length that fits this canvas, on the 8k+1 grid, in seconds.+ const maxFrames = Math.max(9, ((Math.floor(A2V_PIXEL_BUDGET / area) - 1) >> 3) * 8 + 1);+ const maxSec = Math.max(1, Math.floor((maxFrames - 1) / 24));warn.style.display = '';- warn.innerHTML = '<b>' + frames + ' frames</b> — past the ~257-frame point '- + 'where Audio → Video has been reported to lose structural coherence '- + '(two independent reports, <a href="https://github.com/mrbizarro/Phosphene/issues/46" '- + 'target="_blank" rel="noopener">#46</a> — not a limit measured here). '- + '10 s = 241 frames is the last stop under it. Longer still renders; '- + 'expect anatomy to drift and the picture to wash out toward the end.';+ warn.innerHTML = '<b>' + frames + ' frames at ' + w + '\u00d7' + h + '</b> — bigger than any '+ + 'Audio \u2192 Video render that has been reported holding together. What gives out is the '+ + 'picture, not the sound: the audio plays to the end while anatomy drifts and the frame '+ + 'washes out. It is <b>frames \u00d7 canvas</b>, not length alone \u2014 640\u00d7480 has been '+ + 'reported fine at the full 20 s, while 1024\u00d7576 died around frame 454 on the same machine '+ + '(<a href="https://github.com/mrbizarro/Phosphene/issues/46" target="_blank" rel="noopener">#46</a> '+ + '\u2014 field reports, not a limit measured here). '+ + 'At this canvas, about <b>' + maxSec + ' s</b> (' + maxFrames + ' frames) is the last stop under it; '+ + 'a smaller canvas buys length. Longer still renders.';} else {warn.style.display = 'none';warn.textContent = '';@@ -35768,7 +37749,8 @@ window.CHARACTERS = {list: [], // [{id, name, trigger, pronoun, subject_noun, sample_image_url, ...}]selected: null, // currently-composing character (object from list)duration: '7s', // 5s | 7s | 10s | 15s- quality: 'high', // draft | high+ quality: 'pro', // SIZE token: draft | pro. The PIPELINE is the+ // generation's answer, resolved server-side (§5.6).// Character LoRA strength (applied to both face_lora and audio_lora).// Default 0.8 reduces over-trained baked artifacts at small identity cost.charStrength: 0.8,@@ -35794,16 +37776,35 @@ const CHARACTERS_FRAMING = [['MS', 'MS', 'medium shot'],['LS', 'LS', 'long shot'],];-const CHARACTERS_DURATION = [- ['5s', '5s', '5 seconds'],- ['7s', '7s', '7 seconds'],- ['10s', '10s', '10 seconds'],- ['15s', '15s', '15 seconds — slower (~14min)'],-];-const CHARACTERS_QUALITY = [- ['draft', 'Draft', 'Draft — 736x416, Q8 + Turbo, ~3:30 wall, lower detail'],- ['high', 'High', 'High — 1024x576, Q8 two-stage + Turbo, ~6:00 wall, best identity'],-];+// DERIVED from the engine's own length table, not typed. This was the fourth+// independent duration vocabulary in the panel (after the storyboard card's+// [3,5,7,10], the Manual strip and H3's table), and four tables for one concept+// is how the 7-second lie happened. The blurb is the table's own.+const CHARACTERS_DURATION = (((BOOT.ltx || {}).lengths) || [])+ .filter(l => l.offered !== false)+ .map(l => [l.key, l.label, `${l.seconds} seconds — ${l.blurb}`]);+// DERIVED from BOOT.ltx.character — the same server-resolved table the+// composer's character strip renders, so the two surfaces cannot disagree+// about what a character render is.+//+// It used to be a hardcoded pair, `draft` / `high`, carrying 2.3-era wall times+// and "Turbo". Two problems at once: there was no way for the tab to ASK for+// the graded 2.5 path (q8 + distilled), and `high` on 2.5 meant the two-stage+// HQ pipeline plus the 29.5 GB add-on — so the tab was offering the only two+// choices that were wrong.+//+// The values are now SIZE tokens. Which pipeline runs is the generation's+// answer, resolved server-side (§5.6); the chips pick a canvas, not a schedule.+const CHARACTERS_QUALITY = (() => {+ const c = ((BOOT.ltx || {}).character) || {};+ if (!c.draft || !c.pro) {+ return [['pro', 'Q8 Pro', 'Q8 Pro — the recipe the character LoRAs were graded on']];+ }+ return [+ ['draft', 'Q8 Draft', `Q8 Draft — ${c.draft.width}×${c.draft.height}, ${c.draft.tier}`],+ ['pro', 'Q8 Pro', `Q8 Pro — ${c.pro.width}×${c.pro.height}, ${c.pro.tier}`],+ ];+})();// Look-up by value → full descriptive text (the third tuple slot).const CHARACTERS_FRAMING_TEXT = Object.fromEntries(CHARACTERS_FRAMING.map(([v, , full]) => [v, full])@@ -36361,7 +38362,14 @@ async function charactersLoadParams(p) {window.CHARACTERS.duration = p.duration;}if (typeof p.quality_choice === 'string' && p.quality_choice) {- window.CHARACTERS.quality = p.quality_choice;+ // Legacy sidecars carry a PIPELINE token where the chips now carry a SIZE+ // token. Map it to the equivalent canvas rather than replaying it: a clip+ // recorded as `high` on 2.5 would otherwise re-request the two-stage HQ+ // path and its 29.5 GB add-on — the exact route this tab was moved off.+ // Both mean 1024x576, so the canvas the user sees is unchanged.+ const _legacySize = { high: 'pro', balanced: 'pro', standard: 'pro',+ quick: 'draft', draft: 'draft', pro: 'pro' };+ window.CHARACTERS.quality = _legacySize[p.quality_choice] || 'pro';}charactersRenderChips();// Prompt textarea. The verbatim prompt from the sidecar is the@@ -36519,9 +38527,10 @@ async function trainCheckPreflight() {`).join('')}</div><div class="train-preflight-foot">- Phosphene's default install ships only the inference model. The dev- transformer is needed for training and is downloaded on demand to- keep the base install lean.+ Phosphene installs only what it renders with. Training runs against+ LTX-2.3 and needs its own weights, so they are downloaded on demand+ rather than shipped to everyone. Each download is resumable, and+ nothing above is needed to render.</div></div>`;@@ -37604,7 +39613,7 @@ async function trainDeleteLora(loraPath) {// pixel count. The richer label is preserved in the sidecar so the// info modal can show "Quick" / "Standard" / "High" verbatim.const QUALITY_PRESETS = {- quick: { w: 640, h: 480, upscale: 'off' }, // 4:3, fastest sanity check+ quick: { w: 640, h: 448, upscale: 'off' }, // 10:7, fastest sanity check. 448 not 480: the two-stage lane snaps to multiples of 64, so 480 was never delivered.balanced: { w: 1024, h: 576, upscale: 'fit_720p' }, // exact 16:9 → 1280×720standard: { w: 1280, h: 704, upscale: 'off' }, // LTX-wide canonical render// High = Q8 quality at 1024×576. Lab finding 2026-05-09: at 1024×576@@ -37653,6 +39662,12 @@ function setQuality(q) {try { setH3Tier((document.getElementById('h3_tier') || {}).value); } catch (_) {}if (typeof setUpscale === 'function') { try { setUpscale('off'); } catch (_) {} }}+ // Repaint the LTX strips LAST, after every field this function owns is+ // settled, so the chips print the shape that is now actually in the form.+ // Both axes are repainted because moving the canvas re-prices every length.+ if (typeof renderTierAxes === 'function') {+ try { renderTierAxes('ltx'); } catch (_) {}+ }}function setAccel(a) {const allowed = document.getElementById('quality').value !== 'high' && currentMode !== 'extend' && currentMode !== 'keyframe';@@ -37762,7 +39777,7 @@ function updateCustomizeSummary() {const upscale = document.getElementById('upscale').value || 'off';const parts = [];// Aspect (Quick is fixed 4:3, no choice; Standard/High show landscape/vertical).- if (q === 'quick') parts.push('4:3 · 640×480');+ if (q === 'quick') parts.push('10:7 · 640×448');else parts.push(aspect === 'vertical' ? '9:16' : '16:9');// Flag custom dims if they don't match the preset.const preset = QUALITY_PRESETS[q] || QUALITY_PRESETS['standard'];@@ -37882,7 +39897,7 @@ function engineById(id) {}function defaultEngine() {return engineById(ENGINE_DEFAULT) || ENGINES[0]- || { id: 'ltx', label: 'LTX-2.3', builtin: true, strip_label: 'Quality' };+ || { id: 'ltx', label: 'LTX', builtin: true, strip_label: 'Quality' };}// An engine's live capability block. `probe` names the bootstrap key that@@ -38413,6 +40428,7 @@ function renderEngineSwitch() {title="${escapeHtml(_engineTooltip(e, st, modeOk))}"><span class="eng-mark"><svg class="ph" aria-hidden="true"><use href="#${escapeHtml(e.mark)}"/></svg></span><span class="eng-seg-name">${escapeHtml(e.label)}</span>${+ e.generation ? `<span class="eng-seg-gen">${escapeHtml(e.generation)}</span>` : ''}${badge ? `<span class="eng-badge${badgeClass}">${escapeHtml(badge)}</span>` : ''}</button>`;}).join('');@@ -38426,7 +40442,12 @@ function renderEngineSwitch() {// 75 GB of weights on disk that the engine "isn't installed" is the v3.4.0// regression report, verbatim.function _engineTooltip(e, st, modeOk) {- const name = e.label + ' · ' + (e.sublabel || '');+ // The generation belongs in the TITLE too: the compact breakpoint+ // (<=1500 px — a 14" MBP window) hides .eng-seg-name and .eng-seg-gen, so on+ // a laptop the release's headline fix had no surface at all and #modelTag was+ // the only thing naming the build.+ const name = e.label + (e.generation ? ' ' + e.generation : '')+ + ' · ' + (e.sublabel || '');if (st.announced) return name + ' — ' + (e.tagline || 'not released yet');if (!e.builtin && !st.capable) {return name + ' — needs ' + (st.min_ram_gb || 64) + ' GB unified memory';@@ -38468,60 +40489,310 @@ function engineSegClick(id) {// is live on both axes at once and changing either one re-prices the other. The// numbers are the server's: a chip looks up a cell, it never computes a canvas// or a duration of its own.-function _h3ChipHtml(kind, item, cell, active) {+// Per-engine differences, and ONLY the differences. Everything else about a+// tier chip — the classes, the three spans, the unavailable state, the title+// rules — is shared, because it was already right for H3 and re-deriving it for+// LTX is how two strips start disagreeing about what "unavailable" looks like.+//+// The engine argument is DEFAULTED to 'h3' throughout this section on purpose:+// every existing H3 call site then stays byte-identical, which is the property+// the refactor is checked against (560 chips, diffed before and after).+const TIER_ENGINES = {+ h3: {+ boot: () => H3,+ // H3's canvases are several different aspect ratios, so the ratio is the+ // fact worth printing beside the canvas.+ qualitySpec: (item, cell) => `${item.canvas} · ${item.aspect}`,+ lengthSpec: (item, cell) => (cell+ ? `${cell.frames}f` + (cell.chain_windows > 1 ? ` · ${cell.chain_windows}×5s` : '')+ : `${item.frames}f`),+ eta: (cell) => h3CellEta(cell),+ cellFor: (q, l) => h3CellFor(q, l),+ currentQuality: () => h3CurrentQuality(),+ currentLength: () => h3CurrentLength(),+ setQuality: (k) => setH3Quality(k),+ setLength: (k) => setH3Length(k),+ qStripId: 'h3QualityGroup', lStripId: 'h3LengthGroup',+ metaId: 'h3LengthMeta', noteId: '',+ qAttr: 'h3-quality', lAttr: 'h3-length',+ },+ ltx: {+ boot: () => (BOOT.ltx || {}),+ // LTX is 16:9 or 4:3 and the user picked the canvas by name; what changes+ // under them as they move the Length axis is the FRAME COUNT, so that is+ // what the quality chip prints. It is the current cell's frames, never a+ // fixed number — a chip that said "73f" while rendering 121 would be the+ // same class of lie as the engine label this release is fixing.+ qualitySpec: (item, cell) => `${item.canvas} · ${cell ? cell.frames : '—'}f`,+ lengthSpec: (item, cell) => (cell ? `${cell.frames}f` : `${item.frames}f`),+ eta: (cell) => ltxCellEta(cell),+ // A cell whose weights are not on disk is an INSTALL OFFER, not a choice.+ // `offered` is the RAM question and is resolved at import time; this is the+ // pack question and it can only be answered at runtime, so it lives here.+ needsInstall: (cell) => ltxCellNeedsInstall(cell),+ installLabel: (cell) => ltxCellInstallLabel(cell),+ cellFor: (q, l) => ltxCellFor(q, l),+ currentQuality: () => ltxCurrentQuality(),+ currentLength: () => ltxCurrentLength(),+ setQuality: (k) => setLtxQuality(k),+ setLength: (k) => setLtxLength(k),+ qStripId: 'qualityGroup', lStripId: 'ltxLengthGroup',+ metaId: 'ltxLengthMeta', noteId: 'ltxTierNote',+ // The CANVAS chips keep the SHIPPED `data-quality` attribute rather than+ // taking an engine-prefixed one. Five surfaces already read it — the click+ // handler, setQuality's active toggle, applyTierTimes, the trained-LoRA+ // compatibility gate and the character-strip swap — and renaming it to+ // match a naming scheme would have broken all five for tidiness. H3's+ // chips are new markup and have no such history, so they keep theirs.+ qAttr: 'quality', lAttr: 'ltx-length',+ // A duration that is not on the axis is not an error and is not hidden —+ // power users have shipped work with the raw Frames field. It lights no+ // chip and says what it is: `custom · 337f · 14 s`.+ customMeta: () => {+ const f = parseInt((document.getElementById('frames') || {}).value, 10);+ if (!Number.isFinite(f)) return '';+ const secs = Math.round(((f - 1) / 24) * 10) / 10;+ return `custom · ${f}f · ${secs} s`;+ },+ },+};++function _tierChipHtml(engine, kind, item, cell, active) {+ const E = TIER_ENGINES[engine] || TIER_ENGINES.h3;const ok = !cell ? false : (cell.available !== false);+ // NEEDS-INSTALL is a third state, distinct from unavailable: the cell is+ // renderable on this Mac, the weights just aren't here yet. It reads as a+ // CTA (dashed + download glyph via .needs-install) and its third slot names+ // the download instead of an ETA the user cannot have yet.+ const needsInstall = ok && E.needsInstall ? !!E.needsInstall(cell) : false;const cls = 'q-chip pill-btn pill-quality'- + (active ? ' active' : '') + (ok ? '' : ' unavailable');- const spec = (kind === 'quality')- ? `${item.canvas} · ${item.aspect}`- : (cell ? `${cell.frames}f` + (cell.chain_windows > 1 ? ` · ${cell.chain_windows}×5s` : '')- : `${item.frames}f`);- const foot = ok ? h3CellEta(cell) : 'unavailable';+ + (active ? ' active' : '') + (ok ? '' : ' unavailable')+ + (needsInstall ? ' needs-install' : '');+ const spec = (kind === 'quality') ? E.qualitySpec(item, cell)+ : E.lengthSpec(item, cell);+ const foot = !ok ? 'unavailable'+ : needsInstall ? E.installLabel(cell)+ : E.eta(cell);const title = ok? ((cell && cell.blurb) || item.blurb || ''): (cell && cell.unavailable_reason) || 'Not available on this install.';+ const attr = (kind === 'quality') ? (E.qAttr || `${engine}-quality`)+ : (E.lAttr || `${engine}-length`);return `- <button type="button" class="${cls}" data-h3-${kind}="${escapeHtml(item.key)}"+ <button type="button" class="${cls}" data-${attr}="${escapeHtml(item.key)}"${ok ? '' : 'aria-disabled="true"'} title="${escapeHtml(title)}"><span class="ql-name">${escapeHtml(item.label)}</span><span class="q-spec ql-spec sub">${escapeHtml(spec)}</span><span class="ql-tier">${escapeHtml(foot)}</span></button>`;}+// The shipped name, kept as a one-line shim so every H3 call site is unchanged.+function _h3ChipHtml(kind, item, cell, active) {+ return _tierChipHtml('h3', kind, item, cell, active);+}-function renderH3Axes() {- const qStrip = document.getElementById('h3QualityGroup');- const lStrip = document.getElementById('h3LengthGroup');+function renderTierAxes(engine) {+ engine = engine || 'h3';+ const E = TIER_ENGINES[engine] || TIER_ENGINES.h3;+ const B = E.boot() || {};+ const qStrip = document.getElementById(E.qStripId);+ const lStrip = document.getElementById(E.lStripId);if (!qStrip || !lStrip) return;- const qualities = H3.qualities || [];- const lengths = H3.lengths || [];- const curQ = h3CurrentQuality();- const curL = h3CurrentLength();+ const qualities = B.qualities || [];+ const lengths = B.lengths || [];+ const curQ = E.currentQuality();+ const curL = E.currentLength();qStrip.style.gridTemplateColumns = `repeat(${Math.max(1, qualities.length)}, 1fr)`;qStrip.innerHTML = qualities.map(q =>- _h3ChipHtml('quality', q, h3CellFor(q.key, curL), q.key === curQ)).join('');+ _tierChipHtml(engine, 'quality', q, E.cellFor(q.key, curL), q.key === curQ)).join('');// Past four lengths (the lab dense pass turns a fifth on) the chips would// squeeze; wrap to three per row and let the strip grow a line instead.lStrip.style.gridTemplateColumns =`repeat(${lengths.length > 4 ? 3 : Math.max(1, lengths.length)}, 1fr)`;lStrip.innerHTML = lengths.map(l =>- _h3ChipHtml('length', l, h3CellFor(curQ, l.key), l.key === curL)).join('');-- qStrip.querySelectorAll('[data-h3-quality]').forEach(b => {- b.onclick = () => setH3Quality(b.dataset.h3Quality);+ _tierChipHtml(engine, 'length', l, E.cellFor(curQ, l.key), l.key === curL)).join('');++ const qAttr = E.qAttr || `${engine}-quality`;+ const lAttr = E.lAttr || `${engine}-length`;+ qStrip.querySelectorAll(`[data-${qAttr}]`).forEach(b => {+ b.onclick = () => {+ // A needs-install chip is a DOWNLOAD BUTTON, not a tier choice. Binding+ // setQuality directly here bypassed the shipped .needs-install routing:+ // clicking High selected a tier the machine could not render, the+ // pre-render block explained why for ~1.5 s, and the next poll silently+ // moved the form to a bigger, slower canvas nobody asked for.+ if (b.classList.contains('needs-install')) {+ if (typeof openModelsModal === 'function') openModelsModal();+ return;+ }+ E.setQuality(b.getAttribute(`data-${qAttr}`));+ };});- lStrip.querySelectorAll('[data-h3-length]').forEach(b => {- b.onclick = () => setH3Length(b.dataset.h3Length);+ lStrip.querySelectorAll(`[data-${lAttr}]`).forEach(b => {+ b.onclick = () => E.setLength(b.getAttribute(`data-${lAttr}`));});// The right-hand meta on the Length label: the combination, in one line.- const meta = document.getElementById('h3LengthMeta');- const cell = h3CellFor(curQ, curL);+ const meta = E.metaId ? document.getElementById(E.metaId) : null;+ const cell = E.cellFor(curQ, curL);if (meta) {- meta.textContent = cell- ? `${cell.width}×${cell.height} · ${cell.frames}f · ${h3CellEta(cell)}`- : '';- }+ // A synthesised custom cell (length '') gets the custom line, which is the+ // one that can state the DURATION a raw frame count works out to — the+ // number the user actually wanted to know when they typed it.+ const custom = !cell || cell.length === '';+ meta.textContent = custom+ ? (E.customMeta ? E.customMeta() : '')+ : `${cell.width}×${cell.height} · ${cell.frames}f · ${E.eta(cell)}`;+ }+ // The selected cell's honest notes, joined. H3 has no note element and+ // passes noteId '' — the lookup is skipped rather than guarded downstream.+ const note = E.noteId ? document.getElementById(E.noteId) : null;+ if (note) {+ const txt = (cell && cell.note) || '';+ note.textContent = txt;+ note.hidden = !txt;+ }+}+// The shipped name, kept so every H3 call site is unchanged.+function renderH3Axes() { return renderTierAxes('h3'); }++// ---- LTX's side of the shared axis machinery --------------------------------+// The mirror of h3CellFor / h3CurrentQuality / h3CellEta, and nothing more. The+// LTX form already owns #quality (the shipped hidden select every mode reads),+// so the CANVAS axis writes the field that already exists rather than a second+// one — a new hidden input here would be a second definition of "what will+// render", which is the bug class this release keeps closing.+function ltxCellFor(quality, length) {+ const cell = ((BOOT.ltx || {}).tiers || [])+ .find(t => t.quality === quality && t.length === length) || null;+ if (cell || length !== '') return cell;+ // CUSTOM DURATION. The canvas is still perfectly available — only the length+ // is off the axis — so the quality chips must not go grey and claim+ // otherwise. Synthesise a cell that carries the real canvas and the real+ // frame count, and leave the eta as the word `custom` rather than inventing+ // a number: pricing an arbitrary shape in the browser would be the second+ // cost model this whole table exists to avoid.+ const q = ((BOOT.ltx || {}).qualities || []).find(x => x.key === quality);+ if (!q) return null;+ const f = parseInt((document.getElementById('frames') || {}).value, 10);+ if (!Number.isFinite(f)) return null;+ return {+ quality: q.key, quality_label: q.label, length: '', length_label: 'custom',+ width: q.width, height: q.height, frames: f,+ pack: q.pack, pipeline: q.pipeline,+ eta: 'custom', eta_measured: false, available: true, note: '',+ blurb: q.blurb || '',+ };+}+function ltxCurrentQuality() {+ const v = (document.getElementById('quality') || {}).value;+ return v || (BOOT.ltx || {}).default_quality || 'balanced';+}+// DERIVED FROM #frames, not from the hidden field, and that direction matters.+// #frames is what actually renders; the chip is a label on top of it. Reading+// the label would let the two disagree the moment somebody types 337 into+// Customize — the chip would still show 5s while a 14-second clip rendered,+// which is precisely the 7-second lie this release exists to fix, relocated.+// An off-axis frame count matches no rung, lights no chip, and prints itself.+function ltxCurrentLength() {+ const f = parseInt((document.getElementById('frames') || {}).value, 10);+ const lens = (BOOT.ltx || {}).lengths || [];+ const hit = lens.find(l => Number(l.frames) === f);+ if (hit) return hit.key;+ if (Number.isFinite(f)) return ''; // custom — no chip is active+ return (document.getElementById('ltx_length') || {}).value+ || (BOOT.ltx || {}).default_length || '5s';+}+function ltxCurrentCell() {+ return ltxCellFor(ltxCurrentQuality(), ltxCurrentLength());+}+// The eta STRING for a cell. The server's own string wins whenever the state is+// one the server priced, because that is where a MEASURED wall clock lives —+// and where it is NOT measured the string is still the server's model, so the+// browser never carries a second cost model. The only case it recomputes is a+// custom duration, which by definition has no cell.+function ltxCellEta(cell) {+ if (!cell) return '';+ if (cell.eta === 'custom') return 'custom';+ const tail = (cell.pack === 'q8' && cell.pipeline === 'hq') ? ' · Q8 HQ' : '';+ return (cell.eta || '') + tail;+}+// Are this cell's weights on disk? A RUNTIME question — the tier table is built+// at import time and cannot know. `offered` answers "can this Mac's RAM serve+// this tier"; both must be able to be true (§11-E).+function ltxCellNeedsInstall(cell) {+ if (!cell || cell.pack !== 'q8') return false;+ const s = window.__phosLastStatus || {};+ // UNKNOWN IS NOT MISSING. Before the first /status lands there is no pack+ // answer at all, and `!undefined` is `true` — so the chip was born claiming+ // weights were absent on a machine that has them, and clicking it opened a+ // download for a 30 GB pack the user already owned. A tier is only an install+ // OFFER once we have actually been told something is missing; until then it+ // is an ordinary chip. Being briefly wrong in the harmless direction beats+ // being confidently wrong in the expensive one.+ if (s.q8_available === undefined && s.q8_pack_available === undefined) return false;+ const packOk = (s.q8_pack_available !== undefined) ? s.q8_pack_available : s.q8_available;+ if (cell.pipeline === 'hq') {+ // High needs the pack AND the add-on.+ return !(packOk && (s.hq_addon_missing || []).length === 0);+ }+ return !packOk;+}+// What the chip says instead of an ETA, and it names the download that is+// actually missing rather than a fixed string.+function ltxCellInstallLabel(cell) {+ const s = window.__phosLastStatus || {};+ const P = ((BOOT.ltx || {}).packs) || {};+ const packOk = (s.q8_pack_available !== undefined) ? s.q8_pack_available : s.q8_available;+ // NAME THE DOWNLOAD THAT IS MISSING, not the family it belongs to. With the+ // 30 GB pack present and only the 29.5 GB add-on absent, offering "Q8+ // weights" is the exact conflation `q8_pack_available` was introduced to+ // kill — telling a user to re-buy what they already have.+ const addonMissing = (s.hq_addon_missing || []).length > 0;+ // The pack comes first: without it the add-on has nowhere to land. Once it is+ // present, High's only remaining gap is the add-on.+ let want = P.q8;+ if (cell && cell.pipeline === 'hq' && packOk && addonMissing) want = P.hq_addon;+ if (!want) return 'install needed';+ const short = String(want.name || '').replace(/^LTX-2\.5\s*/, '');+ return `Install ${short} · ${want.size}`;+}+// Set the CANVAS. Length is untouched — the whole point of the two axes.+function setLtxQuality(key) {+ const q = ((BOOT.ltx || {}).qualities || []).find(x => x.key === key);+ if (!q) return;+ _ltxApplyShape(q.key, ltxCurrentLength());+}+// Set the DURATION. Canvas is untouched.+function setLtxLength(key) {+ const l = ((BOOT.ltx || {}).lengths || []).find(x => x.key === key);+ if (!l) return;+ _ltxApplyShape(ltxCurrentQuality(), l.key);+}+// The ONE place the form's LTX shape is written — the mirror of _h3ApplyShape.+// Every other caller (the strips, Load Params, a restored state) routes through+// here, so there is exactly one definition of what the form now says it will+// render, and #duration / #frames stay in agreement with the chips instead of+// drifting from them.+function _ltxApplyShape(qKey, lKey) {+ const cell = ltxCellFor(qKey, lKey);+ if (!cell) return;+ // A cell this canvas does not serve is REFUSED, not silently redirected: the+ // chip is already greyed with the reason in its title, so a click that+ // quietly rendered something else would be worse than a click that does+ // nothing.+ if (cell.available === false) return;+ const setv = (id, v) => { const el = document.getElementById(id); if (el && v != null) el.value = v; };+ // The DURATION half is ours. The CANVAS half is setQuality()'s — it has+ // owned #quality, #width, #height, the aspect row and the upscale default+ // since long before this table existed, and a second writer here would be a+ // second definition of "what will render". So we hand it the key and let it+ // do its job; it calls back into renderTierAxes('ltx') when it is done.+ setv('ltx_length', cell.length);+ setv('duration', cell.seconds);+ setv('frames', cell.frames);+ if (typeof setQuality === 'function') setQuality(cell.quality);+ else renderTierAxes('ltx');}// Set the CANVAS. Length is untouched — that is the entire point of the@@ -39237,6 +41508,10 @@ function setEngine(engine, opts) {const _qp = QUALITY_PRESETS[(document.getElementById('quality') || {}).value];if (_qp) { try { setUpscale(_qp.upscale || 'off'); } catch (e) {} }}+ // LTX's own two strips, the mirror of the renderH3Axes() call above.+ if (typeof renderTierAxes === 'function') {+ try { renderTierAxes('ltx'); } catch (e) {}+ }if (typeof _applyCharacterQualityStripVisibility === 'function') {// Restore whichever LTX strip the current selection calls for.try { _applyCharacterQualityStripVisibility(); } catch (e) {}@@ -39672,15 +41947,25 @@ function updateDerived() {['width','height','frames','duration'].forEach(id => {const el = document.getElementById(id);+ // THE OTHER DIRECTION OF THE 7-SECOND LIE. The chips write these fields+ // correctly; these fields never repainted the chips. Type 14 into Duration+ // and the Length strip kept showing `5s` / `121f` / `~2 min` over a form+ // that would render 337 frames — the exact defect ltxCurrentLength()'s own+ // comment predicts, arriving from the side nobody wired.+ const repaintTiers = () => {+ if (typeof renderTierAxes === 'function') {+ try { renderTierAxes('ltx'); } catch (e) {}+ }+ };if (id === 'duration') {- el.addEventListener('input', e => { document.getElementById('frames').value = durationToFrames(parseFloat(e.target.value) || 0); updateDerived(); });+ el.addEventListener('input', e => { document.getElementById('frames').value = durationToFrames(parseFloat(e.target.value) || 0); updateDerived(); repaintTiers(); });} else if (id === 'frames') {- el.addEventListener('input', e => { document.getElementById('duration').value = framesToDuration(parseInt(e.target.value) || 0); updateDerived(); });- el.addEventListener('blur', () => { snapFramesTo8kPlus1(); updateDerived(); });+ el.addEventListener('input', e => { document.getElementById('duration').value = framesToDuration(parseInt(e.target.value) || 0); updateDerived(); repaintTiers(); });+ el.addEventListener('blur', () => { snapFramesTo8kPlus1(); updateDerived(); repaintTiers(); });} else {// width / height: also refresh the Customize summary so "custom" flags// appear/disappear as the user types away from the preset values.- el.addEventListener('input', () => { updateCustomizeSummary(); updateDerived(); });+ el.addEventListener('input', () => { updateCustomizeSummary(); updateDerived(); repaintTiers(); });}});document.getElementById('keyframe_mid_seconds')?.addEventListener('input', () => {@@ -40017,13 +42302,36 @@ function _thumbUrl(url, w) {}async function api(path, method = 'GET', body = null) {+ // The second argument is a METHOD STRING, not a fetch options object — and+ // that is a genuinely surprising signature, because everything else in the+ // browser takes `{method, body}`. Both of v4.0's new actions (Stop early,+ // Storage → Remove) were written against the shape everyone expects, and+ // `fetch(path, {method: {method:'POST'}})` THROWS before the request leaves+ // the page: "'[object Object]' is not a valid HTTP method." Two headline+ // features were dead in the UI while both servers behaved perfectly, because+ // each was proved with curl instead of with the button.+ //+ // So the helper now accepts either shape. This is not politeness towards a+ // typo: the options-object form is the conventional one, and a helper that+ // silently throws on it will keep collecting this bug forever.+ if (method && typeof method === 'object') {+ body = (method.body != null) ? method.body : body;+ method = method.method || 'GET';+ }const opts = { method };if (body) {opts.body = body instanceof FormData ? new URLSearchParams(body) : body;opts.headers = { 'Content-Type': 'application/x-www-form-urlencoded' };}const r = await fetch(path, opts);- if (!r.ok && r.status !== 409) throw new Error(`${path}: ${r.status}`);+ if (!r.ok && r.status !== 409) {+ // Prefer the SERVER'S sentence. /models/remove's three refusals are+ // carefully written ("That's the model this build renders with.") and+ // throwing a bare status turned every one of them into "…: 400".+ let msg = '';+ try { msg = ((await r.json()) || {}).error || ''; } catch (e) {}+ throw new Error(msg || `${path}: ${r.status}`);+ }return r.status === 409 ? { error: 'busy' } : r.json().catch(() => ({}));}@@ -40139,8 +42447,13 @@ function renderDeepVerifyStatus(deep) {+ ' — see the red banner up top.</span>';} else {const uv = (r.unverified || []).length;+ // §3.5: "unverifiable" is not a failure, and the user deserves to know WHY+ // some files cannot be checked rather than being left to assume the worst.+ // An absent or malformed manifest reports unverified and stays ok,+ // precisely so it never triggers a spurious multi-GB re-download.st.innerHTML = '<span style="color:#5bbf7b">✓ all ' + r.checked + ' file(s) match upstream'- + (uv ? ' (' + uv + ' unverifiable)' : '') + '.</span>';+ + (uv ? ' (' + uv + ' unverifiable — the LTX-2.5 packs carry their own '+ + 'checksum list; an older copy may not have one)' : '') + '.</span>';}}@@ -40237,6 +42550,21 @@ function friendlyJobError(raw) {hint: 'Check the log for the last "step:*" breadcrumb (tells us which ' +'phase died). If memory-pressured, close other apps and retry.' };}+ // Layer 2. Layer 1 (applyPackIncompleteGate) should have stopped this before+ // the render started; this fires when it could not — a file removed while the+ // job sat in the queue, or a surface that reaches make_job without the form.+ // The RuntimeError text itself is deliberately unchanged upstream: it is what+ // the log carries and what a bug report quotes. This translates it, it does+ // not replace it.+ if (/model is\s+incomplete\. Missing/i.test(raw)) {+ const m = /Missing \d+ file\(s\) in [^:]+: ([^.]+)\./.exec(raw);+ return {+ friendly: 'Stopped before rendering — the model weights are incomplete.',+ hint: (m ? 'Missing: ' + m[1].trim() + '. ' : '')+ + 'Rendering with a file missing produces garbled "mosaic" video rather '+ + 'than an error, so Phosphene stops instead. Settings → Models → Resume.',+ };+ }if (rawLower.includes('q8') || rawLower.includes('keyframe')) {return { friendly: 'This mode needs the Q8 model.', hint: raw };}@@ -40270,6 +42598,17 @@ async function poll() {return;}LAST_STATUS = s;+ // PUBLISHED HERE, AT THE TOP, and that position is the fix for R2-B1.+ // It used to be assigned ~230 lines further down — AFTER the block that+ // repaints the tier strips. So the one repaint that fires (the first poll,+ // when the pack signature changes from undefined) read `{}` and re-rendered+ // the chips from a status that had not arrived yet; every later poll saw an+ // unchanged signature and never repainted again. The High chip was born an+ // install offer on a fully-equipped machine and stayed one until the user+ // happened to click another quality chip.+ //+ // Anything derived from /status has to be able to see /status.+ window.__phosLastStatus = s;// Corrupt/partial-weight banner (mosaic self-heal).try { renderIntegrityBanner(mergeIntegrity(s.model_integrity, s.deep_verify)); } catch (_) {}@@ -40384,6 +42723,10 @@ async function poll() {// Hailuo H3 install state — refreshes the engine pill in place when the// pack lands (or disappears), same live-unlock contract Q8 already has.if (typeof updateH3Availability === 'function') updateH3Availability(s);+ // The pack-incomplete gate, BEFORE the render rather than 30 s into it.+ if (typeof applyPackIncompleteGate === 'function') {+ try { applyPackIncompleteGate(s); } catch (e) {}+ }// Queue pill + tab badge. Animate the bottom-pane Queue badge with// a brief scale-up "pop" when the count goes up — draws the eye to@@ -40425,29 +42768,51 @@ async function poll() {document.getElementById('pauseBtn').textContent = s.paused ? 'Resume queue' : 'Pause queue';- // Q8 / High enable. Subtitle shows what pipeline this chip uses; goes- // visible permanently (no more `hidden` attribute on the span) so users- // can see at a glance which engine drives each tier.- const highBtn = document.getElementById('qualityHigh');- const highSub = document.getElementById('highSub');- if (s.q8_available) {- highBtn.classList.remove('disabled', 'needs-install');- highSub.textContent = 'Q8 Pro · 7 min';- } else {- // Disabled-but-actionable: a click on the High pill now opens the- // Models modal so the user can install Q8 in one move instead of- // hunting for the download. CSS .needs-install gives the pill an- // accent-tinted look + download arrow in the subtitle so it reads- // as a CTA, not a dead button.- highBtn.classList.add('disabled', 'needs-install');- const missing = (s.q8_missing || []).length;- if (missing > 0 && missing < 6) {- highSub.textContent = `Q8 downloading · ${missing} left`;- highBtn.classList.remove('needs-install'); // mid-download, no need for the CTA hint- } else {- highSub.textContent = 'Install Q8 (37 GB)';+ // Q8 / High enable.+ //+ // This block used to WRITE the chip's subtitle as well — "Q8 Pro · 7 min",+ // "Install Q8 (37 GB)" — one of two hand-rolled updaters printing numbers+ // that no measurement on 2.5 supports (the 2.5 Q8 pack is 30.02 GB and the+ // High add-on is a separate 29.50 GB). The tier table fills every chip's+ // third slot now, the way H3's already did, so what is left here is the+ // STATE: is the pack on disk, and is the chip therefore an install CTA.+ // PACK PRESENCE, as distinct from cap-tier. `data-cap-tier` answers "what can+ // this Mac's RAM serve"; this answers "are the weights on disk". On 2.5 those+ // two diverge for the first time — a 64 GB Mac holding only q4_25 resolves+ // cap_tier=q8 — so every surface that used to key off cap-tier to mean "no+ // Q8" has to read this instead. Both must be able to be true.+ // Reads q8_PACK_available, NOT q8_available: characters render on q8 ++ // distilled and do not touch the HQ add-on, so a user with the full 30 GB+ // pack and no add-on must not be told to install the pack they already have.+ const q8PackOk = (s.q8_pack_available !== undefined) ? s.q8_pack_available : s.q8_available;+ document.body.dataset.q8Pack = q8PackOk ? 'ready' : 'missing';+ // The character chips name Q8 weights, so with no pack on disk they are an+ // install CTA rather than a dead choice — the same contract the High chip has.+ document.querySelectorAll('#qualityGroupCharacter .char-quality').forEach(b => {+ b.classList.toggle('needs-install', !q8PackOk);+ });++ // The High chip's install state is rendered by renderTierAxes now+ // (ltxCellNeedsInstall / ltxCellInstallLabel), so the chip's third slot+ // names the download instead of an ETA the user cannot have yet, and a click+ // opens the Models modal instead of selecting a tier that cannot render.+ //+ // THE SILENT BOUNCE IS GONE. This block used to `setQuality('standard')`+ // whenever Q8 was absent and High was selected — so clicking High moved the+ // form, by itself, to a BIGGER and SLOWER canvas the user never asked for,+ // one and a half seconds after showing them the explanation. The pre-render+ // gate (applyPackIncompleteGate) already disables Generate and names the+ // missing file; the user keeps the tier they chose and is told why it cannot+ // run, which is the honest version of the same information.+ //+ // Repaint so the chips follow pack state as a download lands or a file goes+ // missing, without a reload.+ if (typeof renderTierAxes === 'function' && document.body.dataset.engine !== 'h3') {+ const packSig = `${s.q8_available}|${(s.q8_missing || []).length}|${(s.hq_addon_missing || []).length}`;+ if (window._lastPackSig !== packSig) {+ window._lastPackSig = packSig;+ try { renderTierAxes('ltx'); } catch (e) {}}- if (document.getElementById('quality').value === 'high') setQuality('standard');}// Balanced subtitle: on the "standard" (48–79 GB) tier with Q8 installed,@@ -40458,11 +42823,6 @@ async function poll() {// will actually get when they hit Generate. Re-evaluated on every poll// and on mode/frames change (see the listener wired at DOMContentLoaded// below this function).- window.__phosLastStatus = s;- if (typeof window.refreshBalancedSubtitle === 'function') {- window.refreshBalancedSubtitle(s);- }-// Keyframe (FFLF) and Extend both require Q8 — server enforces it (see// run_job_inner). The UI was previously silently downgrading the user to// Standard when they picked keyframe with Q8 missing, then the server@@ -40477,7 +42837,14 @@ async function poll() {const left = (s.q8_missing || []).length;genBtn.title = left > 0 && left < 6? `${modeName} needs Q8 — ${left} file(s) still downloading.`- : `${modeName} needs the Q8 model. Click "Download Q8 (~37 GB)" in Pinokio.`;+ : (() => {+ // Registry-driven: the pack this generation actually needs, at the+ // size the registry actually records. "37 GB" was 2.3's number.+ const P = ((BOOT.ltx || {}).packs) || {};+ const w = P.q8;+ return w ? `${modeName} needs ${w.name} (~${w.size}) — install it from Settings → Models.`+ : `${modeName} needs the Q8 weights — install them from Settings → Models.`;+ })();genBtn.textContent = 'Generate · Q8 required';} else if (genBtn.disabled && genBtn.textContent.startsWith('Generate · Q8')) {// Restore — only do so if WE were the ones who disabled it, otherwise@@ -40534,7 +42901,9 @@ async function poll() {nowCard.querySelector('.meta').innerHTML = phaseLabel? `${baseMeta}<br><span style="color:var(--muted)">${escapeHtml(phaseLabel)}</span>`: baseMeta;+ renderNowPreview(s, prog);} else {+ renderNowPreview(s, null);// Idle state. If the LAST history entry was a failure (helper crash,// OOM, etc.) surface it loud-and-clear here — otherwise users like// cocktailpeanut just see "Idle" and assume "the panel did nothing."@@ -40583,9 +42952,31 @@ async function poll() {`title="Dismiss this failure" aria-label="Dismiss this failure">` +`<svg class="ph" aria-hidden="true"><use href="#ph-x-bold"/></svg></button>`;}+ } else if (last && last.status === 'stopped' && !s.queue.length+ && last.id !== window._dismissedFailureId) {+ // STOPPED EARLY — a sibling of the failed card, muted rather than red.+ // The user looked at the preview, saw the wrong shot and stopped it;+ // calling that an error would be the panel second-guessing a decision it+ // exists to enable.+ nowCard.classList.remove('idle', 'failed');+ nowCard.classList.add('stopped');+ nowCard.querySelector('.ttl').textContent = 'Stopped early';+ nowCard.querySelector('.meta').innerHTML =+ `<span style="color: var(--muted)">${escapeHtml(snippet(last.params.label || last.params.prompt, 80))}</span>` ++ `<br><span style="color: var(--text)">Nothing was saved.</span>`;+ if (actionsEl) {+ actionsEl.dataset.jobId = String(last.id);+ actionsEl.innerHTML =+ `<button type="button" class="now-card-retry" data-action="retry" ` ++ `title="Run this again with the same params">` ++ `<svg class="ph" aria-hidden="true"><use href="#ph-arrow-clockwise"/></svg>` ++ `<span>Try again</span></button>` ++ `<button type="button" class="now-card-dismiss" data-action="dismiss" ` ++ `title="Dismiss" aria-label="Dismiss"><svg class="ph" aria-hidden="true"><use href="#ph-x-bold"/></svg></button>`;+ }} else {nowCard.classList.add('idle');- nowCard.classList.remove('failed');+ nowCard.classList.remove('failed', 'stopped');nowCard.querySelector('.ttl').textContent = s.paused ? 'Paused' : 'Idle';nowCard.querySelector('.meta').textContent = s.paused? 'Worker paused — current job (if any) finishes, queue waits for resume.'@@ -40760,6 +43151,7 @@ async function poll() {// Outputs / carouselif (JSON.stringify(currentOutputs) !== JSON.stringify(s.outputs)) {currentOutputs = s.outputs;+ if (typeof updateModelCredit === 'function') { try { updateModelCredit(); } catch (e) {} }renderCarousel();// Pick the first FILTERED entry as the default selection so the// viewer agrees with what the gallery is showing — without this,@@ -40859,47 +43251,84 @@ async function poll() {if (typeof sbPollHook === 'function') { try { sbPollHook(s); } catch (e) {} }}-// Balanced chip subtitle — kept in sync with current mode + frames so the-// label tells the truth about which pipeline a click on Balanced will run.-// Mirrors the server-side `balanced_q8_fast` rule in run_job_inner: Q8 Fast-// only on standard tier with Q8 installed, mode ∈ {t2v, a2v}, frames ≤ 121.-window.refreshBalancedSubtitle = function(state) {- const sub = document.getElementById('balancedSub');- if (!sub) return;- const s = state || (window.__phosLastStatus || {});- const tierKey = (s.tier && (s.tier.key || s.tier.tier)) || '';- const q8Capable = !!s.q8_available && tierKey === 'standard';- if (!q8Capable) {- sub.textContent = 'Q4 · 5 min';- return;- }- const framesEl = document.getElementById('frames');- const frames = parseInt((framesEl && framesEl.value) || '121', 10);- const mode = (typeof currentMode !== 'undefined') ? currentMode : 't2v';- // T2V only — see Q8_FAST_OK_MODES on the server side.- // I2V/a2v Q8 Fast caused identity drift on real content; reverted until- // plan C (upscaled half-ref) or low_ram block streaming lands.- const eligible = mode === 't2v' && frames <= 121;- sub.textContent = eligible- ? 'Q8 Fast · 6 min'- : 'Q4 fallback';-};-document.addEventListener('DOMContentLoaded', function() {- const framesEl = document.getElementById('frames');- if (framesEl && !framesEl.__balancedSubWired) {- framesEl.addEventListener('input', () => window.refreshBalancedSubtitle());- framesEl.__balancedSubWired = true;- }- // Wrap setMode() if it exists, so mode flips also re-evaluate the label.- if (typeof setMode === 'function' && !setMode.__balancedSubWired) {- const _orig = setMode;- window.setMode = function(m) {- _orig(m);- window.refreshBalancedSubtitle();- };- window.setMode.__balancedSubWired = true;- }-});+// ---- Layer 1 of the pack-incomplete story, and the one that matters ---------+//+// `ltx_pack_preflight()` already refuses a render whose weights are incomplete+// and names the file. It is the right refusal in the wrong PLACE: it raises+// mid-render, after Gemma has loaded and the user has watched a progress bar+// for half a minute. (Worse, on dev it had been dead code since 2.5 became the+// default — see DEFECT-1 — so the actual behaviour was the June-2026 rainbow+// mosaic with no error at all.)+//+// /status already carries q8_missing, hq_addon_missing and base_missing. So the+// same question the server asks at job time is asked here every poll, against+// the tier the form is actually pointing at, and the answer disables Generate+// with the filenames in the note instead of spending the user's minute first.+//+// Scoped to the SELECTED tier on purpose. A T2V user on Balanced is not nagged+// about weights High would need — the existing #engineRowNote contract is "the+// one-line reason a gate fired", not a standing inventory.+function applyPackIncompleteGate(s) {+ const note = document.getElementById('engineRowNote');+ const genBtn = document.getElementById('genBtn');+ if (!note || !genBtn) return;+ // H3 has its own install card and its own gates; this is the LTX lane.+ const engine = document.body.dataset.engine || 'ltx';+ const clear = () => {+ if (genBtn.dataset.packBlocked === '1') {+ genBtn.disabled = false;+ genBtn.removeAttribute('title');+ delete genBtn.dataset.packBlocked;+ }+ if (note.dataset.packNote === '1') {+ note.hidden = true; note.innerHTML = '';+ delete note.dataset.packNote;+ }+ };+ if (engine !== 'ltx') { clear(); return; }+ const cell = (typeof ltxCurrentCell === 'function') ? ltxCurrentCell() : null;+ // The cell knows its pack. Falling back to the raw quality field keeps this+ // correct before the table has rendered, and on any surface that sets+ // #quality directly.+ const pack = (cell && cell.pack)+ || (((document.getElementById('quality') || {}).value === 'high') ? 'q8' : 'q4');+ // Only the q8 lane can be half-installed in a way the user can act on: an+ // incomplete BASE pack is already a hard block in the models card above, and+ // duplicating it here would give the same fact two voices.+ if (pack !== 'q8') { clear(); return; }+ const missing = [].concat(s.q8_missing || [], s.hq_addon_missing || []);+ if (!missing.length) { clear(); return; }+ // A pack with NOTHING installed is an install offer, not an incomplete+ // download — the High chip's .needs-install state and the Models modal+ // already say so, and "finish the download" would be the wrong verb.+ if (!s.q8_available && missing.length > 6) { clear(); return; }+ const label = (cell && cell.quality_label) || 'This tier';+ // Relative, as §3.6's verbatim has it: an absolute path is this machine's+ // detail, and the note has to fit on one line beside the Generate button.+ const dir = String(s.q8_path || 'the Q8 pack').replace(/^.*?(?=mlx_models\/)/, '');+ const shown = missing.slice(0, 3).join(', ') + (missing.length > 3 ? ' …' : '');+ note.innerHTML = escapeHtml(+ `${label} needs ${missing.length} more file(s) in ${dir} — ${shown}. `+ + `Finish the download first.`)+ + ` <a href="#" onclick="openModelsModal();return false;">Finish the download →</a>`;+ note.hidden = false;+ note.dataset.packNote = '1';+ genBtn.disabled = true;+ genBtn.title = "The weights this tier needs aren't all there yet.";+ genBtn.dataset.packBlocked = '1';+}++// DELETED in v4.0: window.refreshBalancedSubtitle.+//+// It wrote the Balanced chip's third slot ("Q4 · 5 min" / "Q8 Fast · 6 min" /+// "Q4 fallback") from a rule it re-derived in JS, and it wired itself to+// #frames input and wrapped setMode() to stay current. Every number in it was+// a 2.3 figure that no measurement on 2.5 supports, and the wrapper made+// setMode a function two files had opinions about.+//+// The tier table fills that slot now, for all four chips, from a cost model+// anchored on measured renders — the same mechanism H3's chips have always+// used. One writer, one source of truth, and re-pricing is a Python edit.// Recent-tab type filter (All / Videos / Photos). Stored on window so// the value survives across renders without polluting the existing@@ -41344,6 +43773,8 @@ function findOutputByPath(path) {}function selectOutput(path) {activePath = path;+ // The credit names the weights that made THIS clip.+ if (typeof updateModelCredit === 'function') { try { updateModelCredit(path); } catch (e) {} }// If the Ideogram editor canvas is holding the stage, a USER click on an// output means they want to see the render — flip the stage to Result.// Gate on isTrusted so the boot-time auto-select of the newest output (and@@ -42381,8 +44812,21 @@ document.getElementById('genForm').addEventListener('submit', async e => {if ((fd.get('engine') || 'ltx') === 'h3') {fd.set('negative_prompt', ''); // guidance-distilled: no unconditional branchfd.set('character_id', ''); // character LoRAs are an LTX construct- fd.set('loras', ''); // ditto — the H3 runner stacks nothingfd.set('no_voice', ''); // only ever meant "skip the character's voice LoRA"+ // `loras` IS NOT SCRUBBED, and the line that used to scrub it said "the H3+ // runner stacks nothing" — true when it was written, false since the H3+ // LoRA import shipped in 3.7.0. H3 takes ONE adapter from its own family+ // through the same `--lora` flag Turbo rides, the picker offers exactly+ // that family (it filters on the engine's own `lora_tag`, "video:h3"), and+ // `h3_lora_slot` exists for the sole purpose of deciding whether that slot+ // spends on Turbo or on the user's pick. Blanking the field here made the+ // whole picker a control that renders, accepts a selection, and posts+ // nothing — the silent-no-op class this release keeps closing.+ //+ // Cross-lane safety is the SERVER's job and it already does it: make_job+ // filters the stack by the directory each file lives in and logs+ // "Dropped N LoRA(s) that belong to the other video engine". That is+ // strictly better than blanking here, because the user is told why.}// Disable the Generate button while we POST to /queue/add so a fast@@ -42632,11 +45076,21 @@ function updateModelsCard(s) {icon.innerHTML = '<svg class="ph" aria-hidden="true"><use href="#ph-warning-fill"/></svg>';title.textContent = 'Base models needed before you can render';const missing = (s.base_missing || []).length;- sub.innerHTML = `Q4 (~20 GB) and Gemma (~6 GB) are required. Click below — downloads resume if interrupted.${+ // REGISTRY-DRIVEN, for the ACTIVE generation. `base_missing` is already+ // version-scoped, so offering `q4` here downloaded 2.3's base to fix a+ // broken 2.5 install: 20 GB spent, still broken.+ const P = ((BOOT.ltx || {}).packs) || {};+ const pBase = P.base, pEnc = P.encoder;+ sub.innerHTML = `${escapeHtml(pBase ? pBase.name : 'The base model')} (~${escapeHtml(pBase ? pBase.size : '?')})`+ + ` and ${escapeHtml(pEnc ? pEnc.name : 'its text encoder')} (~${escapeHtml(pEnc ? pEnc.size : '?')})`+ + ` are required. Click below — downloads resume if interrupted.${missing ? ` <span style="color:var(--muted)">(${missing} files left)</span>` : ''}`;- actions.innerHTML = (s.hf_available ?? true)- ? `<button onclick="startDownload('q4')">Download Q4 (20 GB)</button>`+ // A mirrored pack does not need `hf` at all — the same per-row question the+ // Models modal already asks, answered from the same registry field.+ const baseNeedsHf = pBase ? (pBase.needs_hf !== false) : true;+ actions.innerHTML = ((s.hf_available ?? true) || !baseNeedsHf)+ ? `<button onclick="startDownload('${escapeHtml(pBase ? pBase.key : 'q4')}')">Download ${escapeHtml(pBase ? pBase.name : 'base')} (${escapeHtml(pBase ? pBase.size : '?')})</button>`: `<button disabled title="hf binary not found — reinstall via Pinokio">hf missing</button>`;return;}@@ -42659,16 +45113,38 @@ function updateModelsCard(s) {card.style.display = '';card.classList.add('state-warn', 'dismissible');icon.innerHTML = '<svg class="ph" aria-hidden="true"><use href="#ph-download-simple"/></svg>';- const reason = currentMode === 'keyframe' ? 'FFLF needs the Q8 model'- : currentMode === 'extend' ? 'Extend needs the Q8 model'- : 'High quality needs the Q8 model';- title.textContent = reason;- const missing = (s.q8_missing || []).length;- sub.innerHTML = `Q8 (~37 GB) is a separate one-time download. Resumable.${- missing && missing < 8 ? ` <span style="color:var(--muted)">(${missing} files left — partial install detected)</span>` : ''- }`;- actions.innerHTML = (s.hf_available ?? true)- ? `<button onclick="startDownload('q8')">Download Q8 (37 GB)</button>`+ // The title has to name the SAME download the body and the button do.+ // "High quality needs the Q8 model" over a button reading "Download+ // LTX-2.5 High add-on" is one card telling two stories.+ const P0 = ((BOOT.ltx || {}).packs) || {};+ const q8PackOk0 = (s.q8_pack_available !== undefined) ? s.q8_pack_available : q8Ok;+ const wantName = ((q8PackOk0 && P0.hq_addon) ? P0.hq_addon : P0.q8 || {}).name || 'the Q8 model';+ const feature = currentMode === 'keyframe' ? 'Keyframes'+ : currentMode === 'extend' ? 'Extend'+ : 'High quality';+ title.textContent = `${feature} needs ${wantName}`;+ // REGISTRY-DRIVEN. This card offered `startDownload('q8')` — 2.3's pack —+ // and advertised 37 GB, on a build where High needs 2.5's 30.02 GB Q8 pack+ // PLUS a separate 29.50 GB add-on. The button worked, which made it worse+ // than a broken one.+ const P = ((BOOT.ltx || {}).packs) || {};+ const pQ8 = P.q8, pHq = P.hq_addon;+ // High/Extend/Keyframe need the add-on too, when this generation has one.+ // Offer the pack that is actually missing rather than the one whose name+ // used to be hardcoded here.+ const q8PackOk = (s.q8_pack_available !== undefined) ? s.q8_pack_available : q8Ok;+ const want = (q8PackOk && pHq) ? pHq : pQ8;+ if (!want) { card.style.display = 'none'; return; }+ const missing = ((q8PackOk ? s.hq_addon_missing : s.q8_pack_missing) || []).length;+ sub.innerHTML = escapeHtml(+ `${want.name} (~${want.size}) is a separate one-time download. Resumable.`)+ + (pHq && !q8PackOk+ ? ` <span style="color:var(--muted)">The High tier additionally needs the ${escapeHtml(pHq.name)} (~${escapeHtml(pHq.size)}).</span>` : '')+ + (missing && missing < 8+ ? ` <span style="color:var(--muted)">(${missing} files left — partial install detected)</span>` : '');+ const wantNeedsHf = (want.needs_hf !== false);+ actions.innerHTML = ((s.hf_available ?? true) || !wantNeedsHf)+ ? `<button onclick="startDownload('${escapeHtml(want.key)}')">Download ${escapeHtml(want.name)} (${escapeHtml(want.size)})</button>`: `<button disabled>hf missing</button>`;return;}@@ -42849,7 +45325,7 @@ function openTierModal() {time: tt.i2v_standard,},{- title: 'Quick (640×480)',+ title: 'Quick (640×448)',desc: 'Smaller preview to scout prompts and seeds before a full-size render.',on: true,size: 'Always smaller than Standard',@@ -43041,11 +45517,93 @@ async function submitBugReport() {// duplicated in JS.let _settingsCache = null;+// Storage. Refreshed on modal OPEN, never on a timer — it walks real+// directories, and the only moment anyone looks at it is when the dialog opens.+async function refreshStorageSection() {+ const sec = document.getElementById('settingsStorageSection');+ const list = document.getElementById('storageList');+ const foot = document.getElementById('storageFoot');+ if (!sec || !list || !foot) return;+ let d;+ try { d = await api('/storage'); } catch (e) { sec.style.display = 'none'; return; }+ const rows = d.rows || [];+ // Rule 5: nothing to reclaim -> the section and its <h3> are both absent. A+ // single-generation install never sees it.+ // GATED ON WHAT CAN ACTUALLY BE RECLAIMED, not on row count. Rule 5 says a+ // single-generation install never sees this section — and it didn't, on the+ // box §7c was proved on, which happened to hold q8 + the add-on. On a genuine+ // fresh install /storage returns exactly ONE row: Gemma 3, removable false,+ // 0 GB reclaimable — and `rows.length` is 1, so the whole section rendered,+ // <h3> and all, to say that nothing can be freed. A "kept, and here is why"+ // row earns its place BESIDE something actionable; on its own it is a section+ // about nothing.+ const actionable = rows.filter(r => r.removable && (r.bytes || 0) > 0);+ if (!actionable.length) { sec.style.display = 'none'; return; }+ sec.style.display = '';+ list.innerHTML = rows.map(r => {+ // A KEPT FILE IS NOT A PROBLEM. `partial` painted an amber border and+ // #ph-warning-fill on a perfectly healthy Gemma 3, under a heading about+ // weights this build does not render with — three signals of trouble on a+ // file that is working exactly as intended. A lock reads as "deliberate";+ // a warning triangle reads as "you have a problem".+ const icon = r.removable+ ? '<svg class="ph" aria-hidden="true"><use href="#ph-check-bold"/></svg>'+ : '<svg class="ph" aria-hidden="true"><use href="#ph-info"/></svg>';+ const btn = r.removable+ ? `<button class="ghost" onclick="removeStoragePack('${escapeHtml(r.key)}')">Remove</button>`+ : '';+ return `+ <li class="${r.removable ? 'ready' : 'kept'}">+ <span class="icon">${icon}</span>+ <div class="meta">+ <span class="ttl">${escapeHtml(r.name)}<span style="float:right">${escapeHtml(r.size)}</span></span>+ <span class="sub">${escapeHtml((r.paths || []).join(' + '))}</span>+ <span class="sub">${escapeHtml(r.note)}</span>+ </div>+ ${btn}+ </li>`;+ }).join('');+ foot.innerHTML = escapeHtml(+ `${d.reclaimable_label} reclaimable · ${d.free_label} free on this disk`)+ + `<br>Removing a pack never touches <code>mlx_outputs/</code> — your clips stay where they are.`;+}++// Native confirm(), the house rule, and it names the size AND the consequence.+// No modal: this dialog is a .models-modal with no focus trap (see the spec's+// §11-D), and stacking a custom confirm inside it would be a worse experience+// than the browser's own.+async function removeStoragePack(key) {+ let d;+ try { d = await api('/storage'); } catch (e) { return; }+ const row = (d.rows || []).find(r => r.key === key);+ if (!row) return;+ const consequence = row.note ? row.note + '\n' : '';+ if (!confirm(`Remove ${row.name}?\n\n`+ + `Frees ${row.size} from mlx_models/.\n`+ + consequence+ + `Nothing you have already rendered is affected.`)) return;+ let res;+ try {+ res = await api('/models/remove', 'POST',+ new URLSearchParams({ repo_key: key }));+ } catch (e) {+ phosToast(String((e && e.message) || e), { kind: 'danger', duration: 6000 });+ return;+ }+ phosToast(`Removed ${res.label} — ${res.freed_label} free.`,+ { kind: 'success', duration: 6000 });+ refreshStorageSection();+ if (document.getElementById('modelsModal').style.display !== 'none') {+ refreshModelsModal({ silent: true });+ }+}+async function openSettingsModal() {const modal = document.getElementById('settingsModal');modal.style.display = 'flex';document.getElementById('settingsStatus').textContent = '';document.getElementById('settingsStatus').className = 'settings-status';+ refreshStorageSection();try {const r = await fetch('/settings');_settingsCache = await r.json();@@ -43115,6 +45673,10 @@ async function openSettingsModal() {}memSelect.value = cur.memory_policy || 'auto';memSelect.onchange = renderMemoryPolicyHint;+ }+ const lpSelect = document.getElementById('settingsLivePreview');+ if (lpSelect) {+ lpSelect.value = (cur.live_preview === 'off') ? 'off' : 'on';renderMemoryPolicyHint();}@@ -43511,6 +46073,7 @@ async function applySettings() {fd.set('output_crf', document.getElementById('settingsCrfNum').value);}fd.set('memory_policy', document.getElementById('settingsMemoryPolicy')?.value || 'auto');+ fd.set('live_preview', document.getElementById('settingsLivePreview')?.value || 'on');// Tokens — only send a key when the input has a value. Empty input// means "leave as-is" (clearing is explicit via the Clear button).// This protects against accidentally wiping a saved key by clicking@@ -44707,6 +47270,10 @@ function _renderCharsAppliedNote() {if (voicePill.hidden) {const cb = document.getElementById('noVoice');if (cb) cb.checked = false;+ } else if (typeof refreshNoVoiceAuto === 'function') {+ // Casting a character with a voice is the moment the default becomes+ // meaningful, so evaluate it here as well as on prompt input.+ refreshNoVoiceAuto();}}const name = escapeHtml(c.name || c.trigger || c.id);@@ -44717,18 +47284,310 @@ function _renderCharsAppliedNote() {? ` · <em title="No audio LoRA on disk — face only">silent</em>`: '';const cur = parseFloat(document.getElementById('characterStrength')?.value || '1.0');+ const voi = parseFloat(document.getElementById('characterVoiceStrength')?.value || '1.0');+ const hasVoice = !!c.audio_lora_path;+ // ONE slider stays the default surface; the split lives one disclosure down.+ // A character is two files, but the panel is not asking anyone to think about+ // two numbers before they have a reason to. `split` is a text affordance, not+ // a chevron — it sits inside a one-line control — and its label carries the+ // pair once they differ, so a non-default voice is visible without opening it.+ const splitLabel = (Math.abs(voi - cur) > 0.001)+ ? `split · ${cur.toFixed(1)} / ${voi.toFixed(1)}`+ : 'split';note.innerHTML = `<span><strong>${name}</strong>${triggerCode}${silentBadge}</span><span class="chars-inline-strength"><span>strength</span><input type="range" min="0" max="2" step="0.05" value="${cur.toFixed(2)}"- oninput="this.nextElementSibling.value = parseFloat(this.value).toFixed(1); document.getElementById('characterStrength').value = this.value">- <output>${cur.toFixed(1)}</output>+ oninput="setCharStrength('face', this.value)">+ <output id="charFaceOut">${cur.toFixed(1)}</output>+ ${hasVoice ? `<button type="button" class="chars-split-toggle" id="charSplitBtn"+ aria-expanded="false" aria-controls="charSplitRow"+ title="Set the face and the voice separately"+ onclick="toggleCharSplit()">${escapeHtml(splitLabel)}</button>` : ''}</span>+ ${hasVoice ? `+ <div class="chars-split" id="charSplitRow" hidden>+ <div class="chars-split-line">+ <span>face</span>+ <input type="range" min="0" max="2" step="0.05" value="${cur.toFixed(2)}"+ oninput="setCharStrength('face', this.value)">+ <output id="charFaceSplitOut">${cur.toFixed(1)}</output>+ </div>+ <div class="chars-split-line">+ <span>voice</span>+ <input type="range" min="0" max="2" step="0.05" value="${voi.toFixed(2)}"+ oninput="setCharStrength('voice', this.value)">+ <output id="charVoiceOut">${voi.toFixed(1)}</output>+ <button type="button" class="help-dot" id="charVoiceHelpBtn" aria-expanded="false"+ aria-controls="charVoiceHelpNote" title="Why run the voice hotter?"+ onclick="toggleCharVoiceHelp()">?</button>+ </div>+ <div class="h3-winhelp" id="charVoiceHelpNote" hidden></div>+ </div>` : ''}`;note.hidden = false;}+// The character strip's two chips, filled from the server-resolved table. Runs+// once at boot and again whenever pack presence changes, because the chips are+// an install CTA when the weights they name are not on disk.+function renderCharacterStrip() {+ const cfg = ((BOOT.ltx || {}).character) || {};+ const group = document.getElementById('qualityGroupCharacter');+ if (!group || !cfg.pro) return;+ [['draft', cfg.draft], ['pro', cfg.pro]].forEach(([key, c]) => {+ if (!c) return;+ const btn = group.querySelector(`[data-char-quality="${key}"]`);+ if (!btn) return;+ btn.title = c.title || '';+ btn.dataset.tooltipDefault = c.title || '';+ const tier = btn.querySelector('.ql-tier');+ if (tier) tier.textContent = c.tier || '';+ const spec = btn.querySelector('.q-spec');+ if (spec) spec.textContent = `${c.width}×${c.height}`;+ });+}++// ---- The live preview, in the Now card --------------------------------------+//+// Four states, and the transitions between them are what the copy is for:+//+// warming a pulsing film-frame glyph. The first estimates are still+// essentially noise and there is nothing worth judging, so+// there is deliberately NO Stop-early button yet — a stop+// over a noise field is a trap that aborts a good take.+// first-meaningful the live image, and Stop early appears with what it saves.+// aborting frozen on the last frame, the button disabled.+// aborted the card takes over (see the `stopped` branch in poll()).+//+// `meaningful` is the SERVER's call — see _preview_progress(). The client+// renders it; it never counts estimates.+function renderNowPreview(s, prog) {+ const box = document.getElementById('nowThumb');+ const actions = document.getElementById('nowCardActions');+ if (!box) return;+ const prev = prog && prog.preview;+ if (!s.running || !prev) {+ box.hidden = true;+ box.className = 'now-thumb';+ box.innerHTML = '';+ const oldDot = document.querySelector('.now-thumb-help');+ if (oldDot) oldDot.remove();+ const oldNote = document.getElementById('nowThumbHelpNote');+ if (oldNote) oldNote.remove();+ if (actions && actions.dataset.stopEarly === '1') {+ actions.innerHTML = ''; delete actions.dataset.stopEarly;+ }+ return;+ }+ box.hidden = false;+ const stopping = window._stopEarlyRequested === s.current.id;+ // The copy constraint, on the element it constrains. §4.1: "The UI must never+ // invite a face judgement from it." Rendered once per render rather than per+ // poll so the button does not flicker under the 1.5 s cadence.+ if (!box.parentNode.querySelector('.now-thumb-help')) {+ const dot = document.createElement('button');+ dot.type = 'button';+ dot.className = 'help-dot now-thumb-help';+ dot.title = 'What am I looking at?';+ dot.setAttribute('aria-expanded', 'false');+ dot.setAttribute('aria-controls', 'nowThumbHelpNote');+ dot.textContent = '?';+ dot.onclick = toggleNowThumbHelp;+ box.parentNode.insertBefore(dot, box.nextSibling);+ const note = document.createElement('div');+ note.className = 'h3-winhelp';+ note.id = 'nowThumbHelpNote';+ note.hidden = true;+ box.parentNode.appendChild(note);+ }+ if (!prev.meaningful) {+ box.className = 'now-thumb is-warming';+ box.innerHTML = '';+ } else {+ box.className = 'now-thumb' + (stopping ? ' is-aborting' : '');+ // Replace the src in place rather than the node, so the browser does not+ // flash white between estimates.+ let img = box.querySelector('img');+ if (!img) { img = document.createElement('img'); img.alt = ''; box.appendChild(img); }+ if (img.getAttribute('src') !== prev.url) img.setAttribute('src', prev.url);+ }+ // The second line of #nowDetail, and the button, both follow `meaningful`.+ const meta = document.querySelector('#nowCard .meta');+ if (meta) {+ const saves = (prev.saves_sec != null && prev.saves_sec > 0)+ ? ` — saves about ${fmtMin(prev.saves_sec)}` : ''; // absent -> drop the sentence+ const line = stopping+ ? 'Finishing the current step, then stopping.'+ : (prev.meaningful+ ? `This is the shot it's making. Stop now if it's wrong${saves}.`+ : 'Finding the shot…');+ meta.innerHTML += `<br><span style="color:var(--muted)">${escapeHtml(line)}</span>`;+ }+ if (actions && prev.abortable) {+ if (stopping) {+ actions.dataset.stopEarly = '1';+ actions.innerHTML = `<button type="button" class="qchip" disabled>Stopping…</button>`;+ } else if (actions.dataset.stopEarly !== '1' || !actions.querySelector('[data-action="stop-early"]')) {+ actions.dataset.stopEarly = '1';+ actions.innerHTML =+ `<button type="button" class="qchip" data-action="stop-early" ` ++ `title="Stops this render now. Nothing is saved — the clip was never finished.">Stop early</button>`;+ }+ }+}++// Fills lazily from the Python-owned constant, the same four-hop path the voice+// help takes.+function toggleNowThumbHelp() {+ const note = document.getElementById('nowThumbHelpNote');+ const btn = document.querySelector('.now-thumb-help');+ if (!note || !btn) return;+ if (!note.textContent) {+ note.textContent = ((BOOT.ltx || {}).help || {}).preview || '';+ }+ const open = note.hidden;+ note.hidden = !open;+ btn.setAttribute('aria-expanded', open ? 'true' : 'false');+}++// The house rule: native confirm() for anything destructive, and it says what+// is lost. The minutes come from the server's own remaining estimate; when it+// has none, the sentence is DROPPED rather than guessed.+async function stopEarly() {+ const s = window.__phosLastStatus || {};+ const cur = s.current;+ if (!cur) return;+ const prev = ((cur.progress || {}).preview) || {};+ const saves = (prev.saves_sec != null && prev.saves_sec > 0)+ ? `About ${fmtMin(prev.saves_sec)} of work is dropped. ` : '';+ if (!confirm('Stop this render?\n\n' ++ "The shot you're looking at is a preview — it was never finished, so nothing is saved.\n" ++ saves + 'The queue carries on with the next job.')) return;+ window._stopEarlyRequested = cur.id;+ try {+ await api('/stop?mode=early', 'POST');+ } catch (e) {+ window._stopEarlyRequested = null;+ phosToast(String((e && e.message) || e), { kind: 'danger', duration: 6000 });+ }+}++// ---- No voice, defaulted rather than guessed --------------------------------+//+// The storyboard lane DERIVES this exactly, from the planner's <d> tags. The+// Manual tab cannot: a typed prompt has no markup, and a panel that claimed to+// know whether you meant someone to speak would be wrong often enough to be+// worse than useless. So it does the one honest thing available — it sets a+// default and SAYS IT DID.+//+// NO TRI-STATE. A checkbox that is checked is checked; the ` · auto` suffix+// says who checked it, and one click removes the suffix permanently for the+// session. That is the whole disclosure.+const SPEECH = /(^|\s)says\b|<d>|["“](?=[^"”]{3,})/i;+let _noVoiceTouched = false;+function markNoVoiceTouched() {+ _noVoiceTouched = true;+ const lbl = document.getElementById('noVoiceLabel');+ if (lbl) lbl.textContent = 'No voice';+ const pill = document.getElementById('noVoicePill');+ if (pill) pill.title = "Skip the character's voice LoRA for this render. The face still locks, but audio stays ambient — no speech, no gibberish.";+}+function refreshNoVoiceAuto() {+ // Only while the pill is untouched THIS SESSION. Once the user has an+ // opinion, their choice is frozen and the prompt stops moving it.+ if (_noVoiceTouched) return;+ const cb = document.getElementById('noVoice');+ const pill = document.getElementById('noVoicePill');+ const lbl = document.getElementById('noVoiceLabel');+ if (!cb || !pill || !lbl || pill.hidden) return;+ const prompt = (document.getElementById('prompt') || {}).value || '';+ const hasSpeech = SPEECH.test(prompt);+ cb.checked = !hasSpeech;+ lbl.textContent = hasSpeech ? 'No voice' : 'No voice · auto';+ pill.title = "Skip the character's voice LoRA for this render. The face still locks, but audio stays ambient — no speech, no gibberish."+ + (hasSpeech ? '' : '\nSet on its own because there are no spoken lines in the prompt — click to override.');+}+(function wireNoVoiceAuto() {+ const attach = () => {+ const p = document.getElementById('prompt');+ if (!p || p.__noVoiceWired) return;+ let t = null;+ p.addEventListener('input', () => {+ clearTimeout(t);+ t = setTimeout(refreshNoVoiceAuto, 500);+ });+ p.__noVoiceWired = true;+ };+ if (document.readyState === 'loading') {+ document.addEventListener('DOMContentLoaded', attach);+ } else { attach(); }+})();++// ---- The two halves of a character's strength -------------------------------+// One writer for both hidden fields, so the collapsed slider, the two split+// sliders and every `output` beside them can never disagree about what will+// render.+//+// COLLAPSED BEHAVIOUR, and it is deliberate: moving the single slider moves the+// FACE only. The voice keeps its own value and does not track. A user who never+// opens the disclosure gets face 1.0 / voice 1.0 — the graded pair — and+// dragging "strength" changes the thing that word means to them (how much like+// the trained person it looks), not the audio. The hotter voice is one+// disclosure away, and the label carries the pair the moment they differ.+function setCharStrength(which, value) {+ const v = Math.max(0, Math.min(2, parseFloat(value)));+ if (!Number.isFinite(v)) return;+ const id = (which === 'voice') ? 'characterVoiceStrength' : 'characterStrength';+ const el = document.getElementById(id);+ if (el) el.value = v.toFixed(2);+ // Every visible control for this half, wherever it is on screen.+ const sel = (which === 'voice')+ ? ['#charVoiceOut']+ : ['#charFaceOut', '#charFaceSplitOut'];+ sel.forEach(s => { const o = document.querySelector(s); if (o) o.value = v.toFixed(1); });+ document.querySelectorAll('.chars-inline-strength input[type="range"]').forEach(r => {+ if (which === 'face' && parseFloat(r.value) !== v) r.value = v.toFixed(2);+ });+ const row = document.getElementById('charSplitRow');+ if (row) {+ const lines = row.querySelectorAll('.chars-split-line input[type="range"]');+ const idx = (which === 'voice') ? 1 : 0;+ if (lines[idx] && parseFloat(lines[idx].value) !== v) lines[idx].value = v.toFixed(2);+ }+ // The toggle's own label carries the pair once they differ, so a non-default+ // voice is legible without opening the disclosure.+ const btn = document.getElementById('charSplitBtn');+ if (btn) {+ const f = parseFloat((document.getElementById('characterStrength') || {}).value || '1.0');+ const s = parseFloat((document.getElementById('characterVoiceStrength') || {}).value || '1.0');+ btn.textContent = (Math.abs(s - f) > 0.001)+ ? `split · ${f.toFixed(1)} / ${s.toFixed(1)}` : 'split';+ }+}+function toggleCharSplit() {+ const row = document.getElementById('charSplitRow');+ const btn = document.getElementById('charSplitBtn');+ if (!row || !btn) return;+ const open = row.hidden;+ row.hidden = !open;+ btn.setAttribute('aria-expanded', open ? 'true' : 'false');+}+// The doctrine, filled lazily from the Python-owned string so the sentence+// explaining the mechanism ships with the mechanism.+function toggleCharVoiceHelp() {+ const note = document.getElementById('charVoiceHelpNote');+ const btn = document.getElementById('charVoiceHelpBtn');+ if (!note || !btn) return;+ if (!note.textContent) {+ note.textContent = ((BOOT.ltx || {}).help || {}).voice_strength || '';+ }+ const open = note.hidden;+ note.hidden = !open;+ btn.setAttribute('aria-expanded', open ? 'true' : 'false');+}+// ============== Manage characters modal (2026-05-18) ==============// Pencil icon in the avatar strip opens this modal. Lists every// trained character with rename + delete actions. Rename only touches@@ -44959,7 +47818,12 @@ function _setCharacterQuality(btn) {const aspect = document.getElementById('aspect');const w = parseInt(btn.dataset.width || '1024', 10);const h = parseInt(btn.dataset.height || '576', 10);- if (qInp) qInp.value = 'high';+ // RESOLVED SERVER-SIDE, never decided here. On 2.3 this is 'high' (its+ // character LoRAs are dev-trained and distilled inference barely locks+ // identity); on 2.5 it is 'balanced', because q8 + distilled is the exact+ // path every graded 2.5 character clip ran. The markup must not own that+ // rule — two generations each carrying a copy is how they drift.+ if (qInp) qInp.value = ((BOOT.ltx || {}).character || {}).quality || 'high';// Honor the orientation chip — swap w/h for vertical renders.const vertical = aspect && aspect.value === 'vertical';if (wInp) wInp.value = vertical ? h : w;@@ -45185,7 +48049,7 @@ function civitaiRenderFamilyPills(available, active) {const labels = {qwen: 'Qwen-Image',hidream: 'HiDream',- ltx: 'LTX-2.3',+ ltx: 'LTX',h3: 'Hailuo H3',};const all = ['all', ...available];@@ -45507,7 +48371,7 @@ async function civitaiInstall(btn, item) {? ' — auto-enabled below.': (lane === 'h3'? ' — it is a Hailuo H3 LoRA, so switch the engine to Hailuo H3 to use it.'- : ' — it is an LTX LoRA, so switch the engine to LTX-2.3 to use it.'))+ : ' — it is an LTX LoRA, so switch the engine to LTX to use it.'))+ (data.converted? ' Converted from the ComfyUI key layout on install (a key rename;'+ ' the tensors are untouched).'@@ -45616,9 +48480,21 @@ async function refreshModelsModal({ silent = false } = {}) {const active = data.active_download;hint.innerHTML = data.hf_available? `Each row shows what's on disk. Click <b>Download</b> to fetch the missing files; progress streams to the log at the bottom of the page. Everything is resumable and checksum-verified.`- : `<span style="color:var(--warning,#d29922)"><svg class="ph" aria-hidden="true" style="margin-right:4px;vertical-align:-2px"><use href="#ph-warning-fill"/></svg><code>hf</code> not found</span> — this Pinokio install doesn't have <code>huggingface_hub>=1.0</code> in the venv. Run Update from Pinokio, then come back.`;+ : `<span style="color:var(--warning,#d29922)"><svg class="ph" aria-hidden="true" style="margin-right:4px;vertical-align:-2px"><use href="#ph-warning-fill"/></svg><code>hf</code> not found</span> — this Pinokio install doesn't have <code>huggingface_hub>=1.0</code> in the venv. Run Update from Pinokio, then come back. The LTX-2.5 rows do not need it — they download from a GitHub release.`;+ // A row whose HOST pack is missing cannot usefully be downloaded: the add-on+ // lands INSIDE that pack's directory and loads from there by name, so+ // fetching it alone produces a folder holding two files and nothing else. The+ // dependency is STATED, not enforced silently.+ const completeByKey = {};+ repos.forEach(r => { completeByKey[r.key] = !!r.complete; });const rows = repos.map(r => {let cls, icon, statusText, btnHtml;+ // Per ROW, not per install. The 2.5 packs download from a GitHub release+ // and need no `hf` at all — gating them on it disabled a button that would+ // have worked, on the exact install the modal's own header tells to go+ // ahead. `needs_hf` is derived from the registry's mirror block.+ const hfOk = (data.hf_available ?? true) || (r.needs_hf === false);+ const hostMissing = r.host_key && !completeByKey[r.host_key];if (active && active.key === r.key) {cls = 'downloading';icon = '<svg class="ph" aria-hidden="true"><use href="#ph-arrow-clockwise-bold"/></svg>';@@ -45639,17 +48515,26 @@ async function refreshModelsModal({ silent = false } = {}) {cls = 'partial'; icon = '<svg class="ph" aria-hidden="true"><use href="#ph-download-simple"/></svg>';const left = r.total_files - r.present_files;statusText = `Partial · ${r.present_files}/${r.total_files} files · ${left} missing — resume to finish`;- btnHtml = data.hf_available+ btnHtml = hostMissing+ ? `<button disabled title="Install the Q8 weights first — the add-on lives inside that folder.">Needs Q8</button>`+ : hfOk? `<button onclick="startDownload('${escapeHtml(r.key)}')" ${active ? 'disabled' : ''}>Resume</button>`: `<button disabled>Resume</button>`;} else {cls = 'missing'; icon = '<svg class="ph" aria-hidden="true"><use href="#ph-x-circle"/></svg>';statusText = `Not installed · ~${r.size_gb || '?'} GB`;- btnHtml = data.hf_available+ btnHtml = hostMissing+ ? `<button disabled title="Install the Q8 weights first — the add-on lives inside that folder.">Needs Q8</button>`+ : hfOk? `<button onclick="startDownload('${escapeHtml(r.key)}')" ${active ? 'disabled' : ''}>Download</button>`: `<button disabled>Download</button>`;}- const kindBadge = r.kind === 'optional'+ // "required" means required BY THIS BUILD. A base pack from the retired+ // generation is neither required nor optional — it is previous, and saying+ // so is the difference between an inventory and a claim.+ const kindBadge = (r.active === false)+ ? `<span style="color:var(--muted)">previous generation</span>`+ : r.kind === 'optional'? `<span style="color:var(--muted)">optional</span>`: `<span style="color:var(--success,#3fb950)">required</span>`;return `@@ -45697,12 +48582,17 @@ async function refreshModelsModal({ silent = false } = {}) {}list.innerHTML = (rows + h3Row) || `<li class="empty-state">No model manifest found — required_files.json is missing or unreadable.</li>`;// Footer summarises required vs optional counts.- const reqRepos = repos.filter(r => r.kind !== 'optional');- const optRepos = repos.filter(r => r.kind === 'optional');+ // Count only what THIS BUILD needs. 2.3's two base rows were inside+ // "Required: N/M ready", which made §7.1's first-visit contract+ // ("Required: 2/2 ready") unreachable on any machine that also has 2.3.+ const reqRepos = repos.filter(r => r.kind !== 'optional' && r.active !== false);+ const optRepos = repos.filter(r => r.kind === 'optional' && r.active !== false);+ const prevRepos = repos.filter(r => r.active === false);const reqReady = reqRepos.filter(r => r.complete).length;const optReady = optRepos.filter(r => r.complete).length;foot.innerHTML = `- <div>Required: ${reqReady}/${reqRepos.length} ready · Optional: ${optReady}/${optRepos.length} ready</div>+ <div>Required: ${reqReady}/${reqRepos.length} ready · Optional: ${optReady}/${optRepos.length} ready${+ prevRepos.length ? ` · <span style="color:var(--muted)">${prevRepos.length} from a previous generation (Settings → Storage)</span>` : ''}</div><div style="margin-top:4px">Tip: downloads resume on retry — closing this dialog mid-download keeps it running in the background.</div>`;}async function startDownload(key) {@@ -46072,10 +48962,14 @@ document.addEventListener('visibilitychange', () => { if (!document.hidden) poll// click that landed mid-rewrite could be lost. A single delegated// listener on document survives every rewrite + costs nothing.document.addEventListener('click', (e) => {- const btn = e.target.closest('[data-action="retry"], [data-action="dismiss"]');+ const btn = e.target.closest('[data-action="retry"], [data-action="dismiss"], [data-action="stop-early"]');if (!btn) return;e.stopPropagation();e.preventDefault();+ // A third delegated action in the same row, for the same reason the other+ // two are delegated: poll() rewrites this element every 1.5 s, and an inline+ // handler would be lost to that race mid-click.+ if (btn.dataset.action === 'stop-early') { stopEarly(); return; }const actions = btn.closest('.now-card-actions');const id = actions ? actions.dataset.jobId : '';if (!id) return;@@ -46091,7 +48985,8 @@ poll();setMode('t2v');setAspect('landscape'); // sets aspect first so the default preset orients correctlysetQuality('balanced'); // bundles quality + dims; respects current aspect-applyTierTimes(); // rewrite Quality pill subtitles to match this Mac+applyTierTimes(); // no-op for LTX since v4.0 — the tier table owns those subtitles+renderCharacterStrip(); // the two character chips, priced per generation// Engine picker — re-apply the last-used engine after the boot sequence above// has settled the mode. setEngine() re-runs every gate (capable / installed /// mode), so a stale localStorage value from a machine that has since lost the@@ -46362,7 +49257,7 @@ function sbEngineChip(id) {accent: '', accent_dim: '', accent_soft: '', tagline: '' };const why = id === 'h3'? 'Renders on Hailuo H3 — video, dialogue and sound together. The optional pack.'- : 'Renders on LTX-2.3 — the built-in engine, and the only one that loads a trained character.';+ : 'Renders on LTX — the built-in engine, and the only one that loads a trained character.';return `<span class="sb-chip sb-chip-engine" data-engine="${escapeHtml(e.id)}"style="--eng-accent:${escapeHtml(e.accent)};--eng-dim:${escapeHtml(e.accent_dim)};--eng-soft:${escapeHtml(e.accent_soft)}"title="${escapeHtml(why)}"><span class="eng-mark"><svg class="ph" aria-hidden="true"><use href="#${escapeHtml(e.mark)}"/></svg></span>${escapeHtml(e.label)}</span>`;@@ -46399,7 +49294,7 @@ function sbPickCast(id) {// pair snaps back to Auto rather than being quietly ignored at plan time.if (_sbCastId && _sbEngineMode === 'h3') {sbSetEngineMode('auto');- phosToast('Auto: Hailuo H3 can’t load a trained character, so their shots go to LTX-2.3.',+ phosToast('Auto: Hailuo H3 can’t load a trained character, so their shots go to LTX.',{duration: 6000});}sbRenderCast();@@ -46418,7 +49313,7 @@ let _sbEngineMode = 'auto';const SB_ENGINE_OPTS = [{ key: 'auto', label: 'Auto', sub: 'per shot' },{ key: 'h3', label: 'Hailuo H3', sub: 'voice + sound', engine: 'h3' },- { key: 'ltx', label: 'LTX-2.3', sub: 'characters', engine: 'ltx' },+ { key: 'ltx', label: 'LTX', sub: 'characters', engine: 'ltx' },];function sbH3Installed() {@@ -46436,11 +49331,11 @@ function sbEnginePickerHtml(active) {+ (offer ? ' needs-install' : '');const style = e ? `--eng-accent:${escapeHtml(e.accent)};--eng-dim:${escapeHtml(e.accent_dim)};--eng-soft:${escapeHtml(e.accent_soft)}` : '';const title = o.key === 'auto'- ? 'The plan decides per shot: a shot with one of your trained characters goes to LTX-2.3, everything else to Hailuo H3.'+ ? 'The plan decides per shot: a shot with one of your trained characters goes to LTX, everything else to Hailuo H3.': offer ? 'Hailuo H3 isn’t installed yet — install it from the Phosphene sidebar in Pinokio.': blocked ? 'This Mac can’t run Hailuo H3.': o.key === 'h3' ? 'Every shot on Hailuo H3 — it renders dialogue, voices and sound with the picture. No trained characters.'- : 'Every shot on LTX-2.3 — the built-in engine, and the only one that loads a trained character.';+ : 'Every shot on LTX — the built-in engine, and the only one that loads a trained character.';const glyph = e ? `<span class="eng-mark"><svg class="ph" aria-hidden="true"><use href="#${escapeHtml(e.mark)}"/></svg></span>` : '';return `<button type="button" class="${cls}" data-sb-engine="${o.key}" style="${style}"${blocked && !offer ? 'disabled' : ''} title="${escapeHtml(title)}">@@ -46452,12 +49347,12 @@ function sbEnginePickerNote(active) {const h3 = sbH3Installed();if (!h3.available) {return h3.capable- ? 'Hailuo H3 isn’t installed — <b>Install Hailuo H3</b> in the Phosphene sidebar in Pinokio, and this film can use it. Until then every shot renders on LTX-2.3.'- : 'This Mac can’t run Hailuo H3, so every shot renders on LTX-2.3.';+ ? 'Hailuo H3 isn’t installed — <b>Install Hailuo H3</b> in the Phosphene sidebar in Pinokio, and this film can use it. Until then every shot renders on LTX.'+ : 'This Mac can’t run Hailuo H3, so every shot renders on LTX.';}if (active === 'h3') return 'Every shot on Hailuo H3 — dialogue, voices and sound rendered with the picture. <b>A trained character can’t come along</b>: H3 loads no LoRAs.';- if (active === 'ltx') return 'Every shot on LTX-2.3 — every mode, and the only engine that loads a trained character.';- return 'A shot with one of your trained characters goes to <b>LTX-2.3</b>; every other shot goes to <b>Hailuo H3</b>.';+ if (active === 'ltx') return 'Every shot on LTX — every mode, and the only engine that loads a trained character.';+ return 'A shot with one of your trained characters goes to <b>LTX</b>; every other shot goes to <b>Hailuo H3</b>.';}function sbRenderEnginePicker() {@@ -46496,7 +49391,31 @@ function sbRenderReplanEnginePicker() {const g = sbEl('sbReplanEngineGroup');if (g) g.innerHTML = sbEnginePickerHtml(_sbReplanEngineMode);const n = sbEl('sbReplanEngineNote');- if (n) n.innerHTML = sbEnginePickerNote(_sbReplanEngineMode);+ if (n) n.innerHTML = sbEnginePickerNote(_sbReplanEngineMode) + sbEngineSnapWarning(_sbReplanEngineMode);+}++// Flipping a film's engine RE-SNAPS every shot, because H3 and LTX do not share+// a length axis: H3 renders in 3, 5, 10 or 15-second beats and LTX in 3, 5, 7,+// 10. A 7 s shot moving to H3 becomes 5 s. That is a real change to the plan,+// so it is announced rather than discovered — the same class of silence the+// 7-second lie was, one level up. Counted against the shots that are actually+// on the board, so it says "two shots" only when two shots really move.+function sbEngineSnapWarning(mode) {+ const shots = ((SB.board || {}).shots) || [];+ if (!shots.length) return '';+ const target = (mode === 'h3') ? 'h3' : (mode === 'ltx' ? 'ltx' : '');+ if (!target) return ''; // 'auto' changes nothing by itself+ const lens = ((target === 'h3' ? (BOOT.h3 || {}).lengths : (BOOT.ltx || {}).lengths) || [])+ .filter(l => l.offered !== false).map(l => Number(l.seconds));+ if (!lens.length) return '';+ const moving = shots.filter(s => lens.indexOf(Math.round(s.duration_s)) === -1).length;+ if (!moving) return '';+ const beats = lens.slice(0, -1).join(', ') + ' or ' + lens[lens.length - 1];+ const eng = (target === 'h3') ? 'Hailuo H3' : 'LTX';+ const n = (moving === 1) ? 'One shot' : `${moving} shots`;+ return `<div class="sb-enginepick-note" style="margin-top:4px">`+ + escapeHtml(`${eng} renders in ${beats}-second beats. ${n} will move to the nearest one.`)+ + `</div>`;}// ---- plan ------------------------------------------------------------------@@ -46871,12 +49790,12 @@ function sbRenderPlan(r) {} else if (mode === 'h3') {engText = 'You set this film to <b>Hailuo H3</b> — every shot.';} else if (mode === 'ltx') {- engText = 'You set this film to <b>LTX-2.3</b> — every shot.';+ engText = 'You set this film to <b>LTX</b> — every shot.';} else {engText = SB_BOOT.engine_note || '';- if (mix.h3 && mix.ltx) engText += ` <b>${mix.h3} on Hailuo H3, ${mix.ltx} on LTX-2.3.</b>`;+ if (mix.h3 && mix.ltx) engText += ` <b>${mix.h3} on Hailuo H3, ${mix.ltx} on LTX.</b>`;else if (mix.h3) engText += ` <b>All ${mix.h3} on Hailuo H3.</b>`;- else if (mix.ltx) engText += ` <b>All ${mix.ltx} on LTX-2.3.</b>`;+ else if (mix.ltx) engText += ` <b>All ${mix.ltx} on LTX.</b>`;}if (r.h3_available && mode !== 'auto') engText += ' Change it in Re-plan.';sbEl('sbEngineNoteText').innerHTML = engText;@@ -46943,10 +49862,55 @@ function sbShotCard(s, r, errs) {// With no trained characters on this Mac the cast select can only ever say// "nobody", so it isn't shown at all and the Character button says why.const noCast = !chars.length;- const durs = [3, 5, 7, 10];- if (durs.indexOf(Math.round(s.duration_s)) === -1) durs.push(Math.round(s.duration_s));- const durOpts = durs.sort((a, b) => a - b).map(d =>- `<option value="${d}" ${Math.round(s.duration_s) === d ? 'selected' : ''}>${d} s</option>`).join('');+ // THE 7-SECOND LIE, and what it actually was.+ //+ // This menu was `[3, 5, 7, 10]` for both engines. A shot set to 7 s whose+ // engine is h3 reaches storyboard.h3_length_for(7.0), which snaps to the+ // nearest of {3,5,10,15} with ties to the shorter — |5-7| beats |10-7| — so+ // it rendered 5s, 124 frames, about 5.2 seconds. The select still read "7 s".+ // estimate() priced it at 5 s too, so nothing anywhere disagreed and the user+ // had no way to find out except by watching the clip. It generalised: any+ // planner-written duration was pushed into the menu, so an 8 s H3 shot+ // silently became 10 s. And in the other direction H3's 15 s was UNREACHABLE+ // from a menu that stopped at 10.+ //+ // The menu is now the engine's own table — the same one the Manual strips,+ // the Characters tab and every estimate read. An H3 shot offers 3/5/10/15 and+ // has no 7; an LTX shot offers 3/5/7/10 (and 20s, which the table itself+ // restricts to Quick). One duration vocabulary per engine, server-owned.+ const _lenTable = (engine === 'h3' ? (BOOT.h3 || {}).lengths : (BOOT.ltx || {}).lengths) || [];+ // `offered` is the GLOBAL flag; a length can also be restricted to certain+ // canvases, and 20s is — it holds together at 640x448 and comes apart around+ // frame 454 at 1024x576. Filtering on `offered` alone put 20s on every LTX+ // shot, and shot_to_job then enqueued {quality: balanced, frames: 481}: the+ // exact cell the Manual strip greys out with a reason. The per-quality gate+ // is the same one the tier table already carries, asked here too.+ const _sbQual = (engine === 'h3')+ ? null+ : (((r.board || {}).policy || {})[r.pass === 'final' ? 'final' : 'draft'] || {}).quality+ || ((BOOT.ltx || {}).default_quality);+ const _lens = _lenTable.filter(l => {+ if (l.offered === false) return false;+ const allowed = l.qualities || [];+ return !(allowed.length && _sbQual && allowed.indexOf(_sbQual) === -1);+ });+ const _cur = Math.round(s.duration_s);+ let durOpts = _lens.map(l =>+ `<option value="${l.seconds}" ${_cur === Number(l.seconds) ? 'selected' : ''}>${escapeHtml(l.label)}</option>`).join('');+ // A board carrying an OFF-AXIS duration keeps round-tripping — a hand-edited+ // board, or one planned before this table existed, must not silently lose its+ // value. But on the H3 lane the extra option says what it will ACTUALLY do,+ // because that is the whole bug: it is the snap that was invisible.+ if (_lens.length && !_lens.some(l => Number(l.seconds) === _cur)) {+ let label = `${_cur} s`;+ if (engine === 'h3') {+ const near = _lens.reduce((a, b) =>+ (Math.abs(b.seconds - _cur) < Math.abs(a.seconds - _cur)+ || (Math.abs(b.seconds - _cur) === Math.abs(a.seconds - _cur) && b.seconds < a.seconds)) ? b : a);+ label = `${_cur} s · nearest ${near.label}`;+ }+ durOpts += `<option value="${_cur}" selected>${escapeHtml(label)}</option>`;+ }const passLabel = r.pass === 'final' ? 'Delivery' : 'Draft';const seedSet = (s.seed != null && s.seed !== -1);@@ -46997,6 +49961,9 @@ function sbShotCard(s, r, errs) {<select class="sb-select sb-shot-char" data-act="char" aria-label="Who's in this shot" ${locked ? 'disabled' : ''} ${noCast ? 'hidden' : ''}>${opts}</select><select class="sb-select sb-shot-dur" data-act="dur" aria-label="Length" ${locked ? 'disabled' : ''}>${durOpts}</select>${sbEngineChip(engine)}+ ${isChar && /<d>\s*(?!<\/\s*d\s*>)\S/i.test(s.prompt || '')+ ? `<span class="sb-chip sb-chip-voice" title="This shot has spoken lines, so the character's voice loads.">voice</span>`+ : ''}<span class="sb-chip sb-chip-pass" data-act="pass" title="Quality is set for the whole film — click to change it">${passLabel}</span><span class="sb-shot-est">${sbShotEst(est)}</span><span class="sb-shot-spacer"></span>@@ -47549,7 +50516,7 @@ document.addEventListener('click', (ev) => {const board = ((SB.payload || {}).board);if (!board) return;const which = q.closest('#sbDraftQuality') ? 'draft' : 'final';- const table = { quick: [640, 480], balanced: [768, 432], standard: [1024, 576], high: [1024, 576] };+ const table = { quick: [640, 448], balanced: [768, 432], standard: [1024, 576], high: [1024, 576] };const dims = table[q.dataset.q] || [1024, 576];board.policy = board.policy || {};board.policy[which] = Object.assign({}, board.policy[which],diff --git a/mlx_warm_helper.py b/mlx_warm_helper.pyindex 8b3029c..acb8385 100644--- a/mlx_warm_helper.py+++ b/mlx_warm_helper.py@@ -717,10 +717,44 @@ def _install_lora_fusion_patches() -> None:if not classes:return # very old install — nothing to patch- from ltx_core_mlx.model.transformer.model import LTXModel+ from ltx_core_mlx.model.transformer.model import LTXModel, LTXModelConfigfrom ltx_core_mlx.utils.memory import aggressive_cleanupfrom ltx_core_mlx.utils.weights import apply_quantization, load_split_safetensors+ def _new_dit(tx_path):+ """An LTXModel shaped by the PACK'S OWN CONFIG, exactly as the library+ builds it (`_base.py`: LTXModel(LTXModelConfig.from_checkpoint_dir(...))).++ This used to be a bare `LTXModel()`, i.e. LTXModelConfig's DEFAULTS. On+ 2.3 that was harmless because every default matched. On 2.5 it is not:+ the packs set `use_keyframes_abs_pos_embedding: true` and their+ checkpoints carry `transformer.keyframes_abs_pos_embedding`, while the+ default is False — so the model was built WITHOUT that parameter and+ load_weights refused the checkpoint with++ Received 1 parameters not in model: keyframes_abs_pos_embedding.++ Every LTX-2.5 render with a LoRA attached died there, which is every+ character render on the distilled path. It went unnoticed because the+ panel had been routing Balanced characters to the HQ pipeline (a 2.3+ speed optimisation, now version-gated), and that path builds its DiT+ somewhere else.++ Ask the pack, never assume: a future generation that adds another+ config-gated parameter is then right by construction rather than one+ more line here."""+ try:+ return LTXModel(LTXModelConfig.from_checkpoint_dir(Path(tx_path).parent))+ except Exception as exc: # noqa: BLE001+ # Degrade to the previous behaviour rather than failing the render:+ # an older library without from_checkpoint_dir, or a pack with no+ # readable config, is exactly the 2.3 case this used to serve.+ emit({"event": "log",+ "line": f"WARN: could not read the transformer config next to "+ f"{os.path.basename(str(tx_path))} ({exc}); building "+ f"the DiT from defaults."})+ return LTXModel()+distilled_cls = next((c for c in classes if c.__name__ == "DistilledPipeline"), None)@@ -764,7 +798,7 @@ def _install_lora_fusion_patches() -> None:f"{os.path.basename(str(tx_path))}..."})weights = load_split_safetensors(tx_path, prefix="transformer.")weights = self._fuse_pending_loras(weights, pending)- self.dit = LTXModel()+ self.dit = _new_dit(tx_path)apply_quantization(self.dit, weights)self.dit.load_weights(list(weights.items()))aggressive_cleanup()@@ -803,7 +837,7 @@ def _install_lora_fusion_patches() -> None:f"{os.path.basename(str(tx_path))}..."})weights = load_split_safetensors(tx_path, prefix="transformer.")weights = self._fuse_pending_loras(weights, pending)- dit = LTXModel()+ dit = _new_dit(tx_path)apply_quantization(dit, weights)dit.load_weights(list(weights.items()))aggressive_cleanup()@@ -1016,6 +1050,124 @@ _hq_lora_key: str | None = None_hq_weight_key: tuple[str | None, str | None] | None = None+def _checkpoint_generation(model_dir: str) -> tuple[int, ...]:+ """The generation of the checkpoint in ``model_dir``, e.g. ``(2, 5)``.++ Returns the empty tuple when it cannot be read, which every+ generation-keyed default in the vendored library treats as "older than+ anything" and therefore answers with the legacy value. A pack whose+ config we cannot parse must render exactly as it did before.++ Reads `config.json` / `embedded_config.json` — the sidecars the quantiser+ writes next to the weights — and parses with the LIBRARY's own+ ``parse_model_version``, so the panel cannot disagree with the pipeline+ about what "2.5" means. Costs one small JSON read, no weights.+ """+ try:+ from ltx_core_mlx.model.transformer.model import parse_model_version+ except Exception: # noqa: BLE001 — older library: no generations exist+ return ()+ import json as _json+ from pathlib import Path as _Path+ base = _Path(str(model_dir))+ for name in ("config.json", "embedded_config.json"):+ try:+ raw = _json.loads((base / name).read_text())+ except Exception: # noqa: BLE001 — absent/unreadable/not JSON+ continue+ version = raw.get("model_version")+ if version is None:+ version = (raw.get("transformer") or {}).get("model_version")+ if version is None:+ continue+ try:+ return tuple(parse_model_version(str(version)))+ except Exception: # noqa: BLE001+ continue+ return ()+++def _hq_modality_scale(model_dir: str) -> float:+ """The HQ path's default ``modality_scale`` for this checkpoint.++ The detail-guidance slider (STG) has to hand the pipeline EXPLICIT guider+ params to make `stg_blocks=[28]` bite, and those params carry every other+ field too. Hardcoding `modality_scale=3.0` there meant the slider changed+ TWO things at once on LTX-2.5: the pipeline's own default became 1.0 in+ the v4.0 pin (isolated-modality guidance off — an owner-graded output+ change worth −60.7 s), but any render with detail guidance above 0 would+ silently re-enable the dead pass and pay for it again.++ So the value is asked of the library rather than restated here: the panel+ and `TI2VidTwoStagesHQPipeline` resolve it through the SAME function, and+ a future generation cannot make the two disagree. On a library that+ predates the keying — any older pin — the import fails and 3.0 comes back,+ which is byte-identical to what shipped before.+ """+ try:+ from ltx_pipelines_mlx.ti2vid_two_stages_hq import resolve_modality_scale+ except Exception: # noqa: BLE001 — pre-25b9b8e library: 3.0 was the only value+ return 3.0+ try:+ return float(resolve_modality_scale(_checkpoint_generation(model_dir)))+ except Exception: # noqa: BLE001 — never let this block a render+ return 3.0+++def _thin_table_caps(model_dir: str) -> tuple[int, int] | None:+ """(stage1, stage2) step ceilings for the FIXED tables this checkpoint+ thins, or None when they cannot be read."""+ try:+ from ltx_pipelines_mlx.scheduler import distilled_presets_for+ except Exception: # noqa: BLE001 — older library: leave requests alone+ return None+ try:+ vendor = (distilled_presets_for(_checkpoint_generation(model_dir)) or {}).get("vendor")+ if not vendor:+ return None+ return (max(1, len(vendor.stage1) - 1), max(1, len(vendor.stage2) - 1))+ except Exception: # noqa: BLE001 — never block a render on a probe+ return None+++def _thin_cap(model_dir: str, key: str, want: int) -> int:+ """Clamp a step count to what THIS checkpoint's fixed table can serve.++ A step count on a thinning lane means "give me N of the checkpoint's own+ steps" — it thins a fixed table. Asking for more than the table holds is+ asking it to PAD, which is a different operation with a different answer,+ so `thin_sigmas` refuses it. Correctly: a padded schedule is not a longer+ render, it is a made-up one.++ The panel must therefore never ask, and this is the belt behind that.+ It clamps the RESOLVED value — after a lane's own `p.get(key, default)` —+ because the value that broke Colorize came from a default, not from the+ form. An earlier version of this guard only inspected incoming params and+ sailed straight past HDR's own `stage1_steps=10`.++ Clamping rather than raising is deliberate: the user asked for a finer+ schedule than the checkpoint can serve, and its finest with a log line is a+ better answer than a dead render four minutes in.++ Only ever called from the lanes that thin a FIXED table (ICLoraPipeline:+ Colorize / Restore / Ingredients / Control / HDR). The CFG-dev lanes+ (`generate_hq` res_2s, `generate_keyframe`) COMPUTE a schedule of whatever+ length they are asked for, and their 10 and 20 are graded values — clamping+ those would silently change owner-approved output.+ """+ caps = _thin_table_caps(model_dir)+ if not caps:+ return want+ cap = caps[0] if key.startswith("stage1") else caps[1]+ if want > cap:+ emit({"event": "log",+ "line": f"{key}={want} exceeds what this checkpoint's schedule "+ f"holds ({cap} steps); using {cap}. A step count thins "+ f"the checkpoint's own table — it cannot pad it."})+ return cap+ return want++def get_hq_pipe(model_dir: str, loras: list[dict] | None = None,dev_transformer: str | None = None,distilled_lora: str | None = None):@@ -1356,6 +1508,42 @@ def _free_pipe_for_decode(pipe):pass+def _build_live_preview(kwargs: dict):+ """A LivePreviewMonitor for this job, or None when the preview is off.++ THE LANE RULES ARE THE PANEL'S, NOT OURS. `live_preview_every` arrives in+ the job spec because the right value differs per PIPELINE — 1 on the+ distilled lane, 2 on res_2s, which evaluates the denoiser twice per stage-2+ step and whose odd anchor estimates come back patchy — and a client counting+ estimates would have to know which schedule is running. We take the number+ and use it.++ Never fatal. A missing checkpoint, an unreadable directory or a library+ without the module means the render proceeds with no preview: this is a+ monitor, and a monitor must not be able to stop the thing it watches."""+ d = kwargs.get("live_preview_dir")+ tae = kwargs.get("live_preview_tae")+ if not d or not tae:+ return None+ try:+ from ltx_pipelines_mlx.live_preview import LivePreviewMonitor+ except Exception as exc: # noqa: BLE001+ emit({"event": "log",+ "line": f"live preview unavailable in this engine build ({exc}) — "+ f"rendering without it."})+ return None+ try:+ return LivePreviewMonitor(+ Path(d), Path(tae),+ output=Path(kwargs["output_path"]),+ every=max(1, int(kwargs.get("live_preview_every") or 1)),+ )+ except Exception as exc: # noqa: BLE001+ emit({"event": "log",+ "line": f"live preview could not start ({exc}) — rendering without it."})+ return None++def _generate_latents(pipe, *, needs_image: bool, kwargs: dict):# On second+ runs the video/audio decoders (~2.5 GB combined) remain# resident from the previous job's decode phase. During the@@ -1444,6 +1632,11 @@ def _generate_latents(pipe, *, needs_image: bool, kwargs: dict):)if "frame_rate" in sig.parameters:call_kwargs["frame_rate"] = kwargs.get("frame_rate", 24.0)+ # Only when the installed pipeline actually takes it — the panel+ # must never die in argparse-equivalent 30 s into a render because+ # an older engine build does not have the parameter.+ if "live_preview" in sig.parameters and kwargs.get("_live_preview") is not None:+ call_kwargs["live_preview"] = kwargs["_live_preview"]return pipe.generate(**call_kwargs)except TypeError:# New DistilledPipeline.generate inherits from the two-stage@@ -1457,7 +1650,7 @@ def _generate_latents(pipe, *, needs_image: bool, kwargs: dict):emit({"event": "log","line": "[t2v-two-stage] PHOSPHENE_T2V_TWO_STAGE=1 — routing T2V Standard through generate_two_stage (half-res → 2× upsample → Stage-2 refine)."})# Unified new-API fallback (post-refactor packages).- return pipe.generate_two_stage(+ _two_stage_kwargs = dict(prompt=kwargs["prompt"],image=kwargs.get("image") if needs_image else None,height=kwargs["height"],@@ -1471,6 +1664,14 @@ def _generate_latents(pipe, *, needs_image: bool, kwargs: dict):frame_rate=kwargs.get("frame_rate", 24.0),num_steps=kwargs.get("num_steps"),)+ if kwargs.get("_live_preview") is not None:+ try:+ import inspect as _inspect+ if "live_preview" in _inspect.signature(pipe.generate_two_stage).parameters:+ _two_stage_kwargs["live_preview"] = kwargs["_live_preview"]+ except (TypeError, ValueError):+ pass+ return pipe.generate_two_stage(**_two_stage_kwargs)# ---- LTX 2.3 spatial latent upscaler (Y1.021+) ------------------------------@@ -1917,17 +2118,29 @@ def configure_acceleration(mode: str) -> str:# of letting it surface as an un-triageable TypeError mid-render.## 2026-08-12: this is a FORK BUILD, not an upstream tag. The vendored checkout-# is mrbizarro/ltx-2-mlx `feat/ltx-2.5` at 871694d — v0.14.19 plus the LTX-2.5-# port (keyframe pos-emb, Gemma 4 tower, ancestral sampler). The release-# segment stays 0.14.19 because that is genuinely what it branches from; the-# `+ltx25.1` local segment is what makes the two distinguishable.+# is mrbizarro/ltx-2-mlx at the immutable tag `v0.14.19+ltx25.3` — v0.14.19 plus+# the LTX-2.5 port (keyframe pos-emb, Gemma 4 tower, ancestral sampler). The+# release segment stays 0.14.19 because that is genuinely what it branches from;+# the `+ltx25.N` local segment is what makes the two distinguishable.+#+# The N moves whenever the fork changes what a render COMPUTES, not merely when+# the SHA moves. `.2` was the ancestral sampler actually being reached on 2.5+# plus the vendor's stage-2 first sigma (0.85, not 2.3's 0.909375). `.3` is the+# v4.0 pin: isolated-modality guidance off by default on the 2.5 HQ path, the+# distilled lane refining in 2 steps, and a step count thinning the checkpoint's+# table instead of truncating it. All three change output on 2.5; none touches+# 2.3.+#+# The TAG is the pin, not the SHA. A branch tip moves and a SHA on a rebased+# branch stops being fetchable; a tag is the only form of this reference that+# cannot rot under an existing install. install.js / update.js fetch the tag.## That local segment exists FOR this gate. The fork originally carried the bare# string "0.14.19", so a 2.5 runtime reported `match: true` against the 2.3 pin# — a skew gate blind to the one skew that mattered. Bumping the pin here# without bumping the packages (or the reverse) puts it back into permanent# SKEW warnings, so the two move together or not at all.-_LTX_EXPECTED_VERSION = "0.14.19+ltx25.1"+_LTX_EXPECTED_VERSION = "0.14.19+ltx25.3"def _detect_ltx_version() -> dict:@@ -2051,6 +2264,13 @@ for line in sys.__stdin__:_last_activity = time.time()action = msg.get("action")+ # ONE CHOKE POINT for schedule step counts, before any action reads them.+ # Every generate_* lane resolves its own stage1/stage2 defaults, and any of+ # them can be handed an explicit value by the form, by Load Params, or by a+ # sidecar replayed from another generation. Clamping here — once, against+ # the pack this job actually names — means no lane can ask a checkpoint to+ # pad a table it does not have, and a lane added tomorrow is covered+ # without anyone remembering to add it.if action == "exit":emit({"event": "exit", "reason": "shutdown"})os._exit(0)@@ -2123,6 +2343,19 @@ for line in sys.__stdin__:# generate() so it propagates through the whole chain (the patched# decode_and_stream reads os.environ at decode call time)._apply_vae_streaming_decision(kwargs["num_frames"])+ # LIVE PREVIEW. Read-only: the thumbnail is a decode of the x0+ # estimate the denoise loop ALREADY HOLDS, so nothing is+ # recomputed, no scheduler is re-entered and no tensor the+ # denoiser owns is written. A render with it on is byte-identical+ # to the same render with it off — proven by hash, not asserted.+ for _k in ("live_preview_dir", "live_preview_tae", "live_preview_every"):+ if p.get(_k) is not None:+ kwargs[_k] = p[_k]+ kwargs["_live_preview"] = _build_live_preview(kwargs)+ if kwargs["_live_preview"] is not None:+ emit({"event": "log",+ "line": f"live preview on — every {kwargs.get('live_preview_every', 1)} "+ f"estimate(s) → {p.get('live_preview_dir')}"})if needs_image:src_image = p.get("image")if src_image:@@ -2235,7 +2468,36 @@ for line in sys.__stdin__:passexcept Exception as exc:_last_activity = time.time()- emit({"event": "error", "id": job_id, "error": str(exc), "trace": traceback.format_exc()})+ # A USER STOP IS NOT A FAILURE. The abort sentinel raises+ # LivePreviewAborted between forwards, and the CLI turns that into+ # exit 75 precisely so a supervisor can tell "the user stopped this"+ # apart from "this crashed" without parsing anything. The panel is+ # that supervisor, and it gets a distinct event rather than a red+ # card: nothing was saved, but nothing went wrong either.+ if type(exc).__name__ == "LivePreviewAborted":+ # DROP THE WARM PIPELINE. The abort raises from BETWEEN two+ # forwards, so the pipeline is left mid-generate: latents,+ # scheduler position and the monitor's own state all belong to+ # a render that will never finish. The helper's whole point is+ # that it keeps that object alive for the next job — so the+ # next job inherited the wreckage and died instantly with an+ # empty error, and every job after it did too. Stop early+ # bricked the render lane until the panel was restarted.+ #+ # Found by rendering AFTER a stop rather than stopping and+ # walking away, which is the thing a user does and a curl test+ # does not. The next job pays one pipeline reload (~7 s) and+ # everything downstream is clean.+ try:+ with _pipe_lock:+ release_pipelines(None)+ except Exception:+ pass+ emit({"event": "stopped", "id": job_id, "reason": str(exc),+ "exit_code": 75})+ else:+ emit({"event": "error", "id": job_id, "error": str(exc),+ "trace": traceback.format_exc()})finally:try:configure_acceleration("off")@@ -2428,25 +2690,34 @@ for line in sys.__stdin__:# other defaults verbatim (cfg/rescale/modality) so STG is the only# thing that changes. At stg_scale<=0 we pass nothing → the pipeline# builds its own [] params → byte-identical to the pre-slider path.+ #+ # `modality_scale` is the one field that is NOT a constant: it is+ # generation-keyed, and `_hq_modality_scale` asks the library for+ # the same answer the pipeline's own default would compute. 2.3+ # still gets 3.0; 2.5 gets 1.0, so the slider changes STG and+ # nothing else. Hardcoding 3.0 here made the slider silently+ # re-enable the isolated-modality pass on 2.5 — the one the v4.0+ # pin removed by default._stg = float(kwargs.get("stg_scale", 0.0))if _stg > 0.0:try:from ltx_core_mlx.components.guiders import MultiModalGuiderParams+ _modality = _hq_modality_scale(model_dir)kwargs["video_guider_params"] = MultiModalGuiderParams(cfg_scale=float(kwargs.get("cfg_scale", 3.0)),stg_scale=_stg,rescale_scale=0.45,- modality_scale=3.0,+ modality_scale=_modality,stg_blocks=[28],)kwargs["audio_guider_params"] = MultiModalGuiderParams(cfg_scale=7.0,stg_scale=_stg,rescale_scale=1.0,- modality_scale=3.0,+ modality_scale=_modality,stg_blocks=[28],)- emit({"event": "log", "line": f"STG detail guidance ON — stg_scale={_stg:g}, stg_blocks=[28]"})+ emit({"event": "log", "line": f"STG detail guidance ON — stg_scale={_stg:g}, stg_blocks=[28], modality_scale={_modality:g}"})except Exception as _stg_exc:# Never let STG wiring block a render — fall back to the# plain (STG-off) HQ path if the import/shape ever drifts.@@ -2862,8 +3133,10 @@ for line in sys.__stdin__:num_frames=num_frames,frame_rate=float(p.get("frame_rate", 24.0)),seed=seed,- stage1_steps=int(p.get("stage1_steps", 10)),- stage2_steps=int(p.get("stage2_steps", 3)),+ stage1_steps=_thin_cap(model_dir, "stage1_steps",+ int(p.get("stage1_steps", 8))),+ stage2_steps=_thin_cap(model_dir, "stage2_steps",+ int(p.get("stage2_steps", 3))),)kwargs = _filter_unsupported_kwargs(pipe.generate_and_save, kwargs)out_path = pipe.generate_and_save(**kwargs)@@ -2980,8 +3253,13 @@ for line in sys.__stdin__:num_frames=num_frames,frame_rate=float(p.get("frame_rate", 24.0)),seed=seed,- stage1_steps=int(p.get("stage1_steps", 8)),- stage2_steps=int(p.get("stage2_steps", 3)),+ # Clamped to this checkpoint's fixed table — ICLoraPipeline THINS+ # it, so the table's own length is the ceiling and an over-ask is a+ # pad request the sampler refuses after the model has loaded.+ stage1_steps=_thin_cap(model_dir, "stage1_steps",+ int(p.get("stage1_steps", 8))),+ stage2_steps=_thin_cap(model_dir, "stage2_steps",+ int(p.get("stage2_steps", 3))),)# Ingredients (multi-reference) reuses this same action but runs the# public Space's single-stage recipe — skip_stage_2=True, generateddiff --git a/patch_ltx_codec.py b/patch_ltx_codec.pyindex 07523d3..e390c06 100644--- a/patch_ltx_codec.py+++ b/patch_ltx_codec.py@@ -255,7 +255,7 @@ def _shout(*lines: str) -> None:def main() -> int:- print("Applying LTX23MLX codec patch (ltx-2-mlx 871694d / 0.14.19+ltx25.1 — only the codec edit remains):")+ print("Applying LTX23MLX codec patch (ltx-2-mlx v0.14.19+ltx25.3 — only the codec edit remains):")# `upgrade_marker="+faststart"` lets us upgrade installs where the# earlier version of this patch was applied (LTX_OUTPUT_PIX_FMT markerdiff --git a/pinokio.js b/pinokio.jsindex 5f3eb6b..575e07e 100644--- a/pinokio.js+++ b/pinokio.js@@ -101,7 +101,14 @@ module.exports = {// --- per-repo completeness from the unified manifest ---const repos = required.repos || []const baseRepos = repos.filter(r => r.kind === "base")- const q8Repo = repos.find(r => r.key === "q8")+ // THE PACK THE BUTTON ACTUALLY INSTALLS. This read `key === "q8"` —+ // LTX-2.3's pack — while the menu entry it gates dispatches+ // download_q8.js -> q8_weights.sh -> `--repo-key q8_25`, i.e. LTX-2.5's.+ // The gate and the action were about different packs, so after a+ // successful 30 GB install the menu kept offering the download forever.+ // Resolved by mirror-block presence rather than a hardcoded key so a third+ // generation does not reopen it: the 2.5-era packs are the mirrored ones.+ const q8Repo = repos.find(r => r.key === "q8_25") || repos.find(r => r.key === "q8")const base_ready = baseRepos.length > 0 && baseRepos.every(r => repoComplete(installRoot, r, minBytes))const q8_ready = q8Repo ? repoComplete(installRoot, q8Repo, minBytes) : false@@ -245,7 +252,7 @@ module.exports = {if (running.install) return [{ default: true, icon: "fa-solid fa-plug", text: "Installing", href: "install.js" }]if (running.update) return [{ default: true, icon: "fa-solid fa-rotate", text: "Updating", href: "update.js" }]if (running.reset) return [{ default: true, icon: "fa-solid fa-eraser", text: "Resetting", href: "reset.js" }]- if (running.q8download) return [{ default: true, icon: "fa-solid fa-download", text: "Downloading Q8 (~37 GB)", href: "download_q8.js" }]+ if (running.q8download) return [{ default: true, icon: "fa-solid fa-download", text: "Downloading Q8 weights (~30 GB)", href: "download_q8.js" }]if (running.sharp) return [{ default: true, icon: "fa-solid fa-wand-magic-sparkles", text: "Installing Sharp upscaler", href: "install_sharp.js" }]if (running.qwen) return [{ default: true, icon: "fa-solid fa-images", text: "Installing Qwen-Image-Edit (multi-ref)", href: "install_qwen.js" }]if (running.h3) return [{ default: true, icon: "fa-solid fa-comments", text: "Installing Hailuo H3 (~75 GB)", href: "install_h3.js" }]@@ -314,7 +321,10 @@ module.exports = {{ icon: "fa-solid fa-image", text: "Uploads", href: "panel_uploads?fs=true" },]if (!q8_ready) {- baseMenu.push({ icon: "fa-solid fa-download", text: "Download Q8 (~37 GB) — High quality + FFLF", href: "download_q8.js" })+ // ~30 GB and what it actually buys on 2.5: trained characters and voices.+ // High additionally needs the separate 29.5 GB add-on, which is offered+ // in Settings -> Models rather than here — one menu entry, one download.+ baseMenu.push({ icon: "fa-solid fa-download", text: "Download Q8 weights (~30 GB) — trained characters + voices", href: "download_q8.js" })}if (!sharp_ready) {baseMenu.push({ icon: "fa-solid fa-wand-magic-sparkles", text: "Install Sharp upscaler (PiperSR, optional)", href: "install_sharp.js" })diff --git a/required_files.json b/required_files.jsonindex 3050417..eff49f8 100644--- a/required_files.json+++ b/required_files.json@@ -3,13 +3,14 @@"_download_include_comment": "Y1.024 \u2014 `download_include` is the list of patterns passed as `--include` flags to `hf download`. Without it `hf download` grabs every file in the repo, which on dgrauet's LTX repos means duplicate transformer variants (transformer-distilled.safetensors AND transformer-distilled-1.1.safetensors AND transformer-dev.safetensors), duplicate distilled LoRAs (-384 and -384-1.1), the temporal upscaler we don't wire, and the x1.5 spatial upscaler we don't use \u2014 turning a declared 25 GB Q8 download into 82 GB on disk (and a 25 GB Q4 into 56 GB). With `download_include` we pull only what the panel actually loads. Pattern syntax: huggingface_hub fnmatch globs \u2014 bare filenames and wildcards both work. We pass `*.json` to keep all sidecar configs (split_model.json etc.) which are tiny and required at runtime.","repos": [{+ "_v40_comment": "kind flipped base -> optional in v4.0. `base` means an install WITHOUT it reads INCOMPLETE, so a fresh 2.5-only install showed the red 'Base models needed before you can render' block and Pinokio offered Resume Install — for a pack nothing renders with. From v4.0 a fresh install fetches 2.5 only and this is a normal in-panel offer, downloaded when the user wants to TRAIN a character. Existing installs that already hold it see no behaviour change: the files are there, the row reads Ready, and Storage still offers to reclaim it.","key": "q4",- "kind": "base",- "name": "LTX 2.3 \u2014 Q4 (base model, distilled)",- "blurb": "Required. Drives Quick / Balanced / Standard renders.",+ "kind": "optional",+ "name": "LTX-2.3 (previous generation)",+ "blurb": "Needed to TRAIN a character - the trainer runs against LTX-2.3, not 2.5. Nothing renders on it; your clips come from LTX-2.5 either way.","repo_id": "dgrauet/ltx-2.3-mlx-q4","local_dir": "mlx_models/ltx-2.3-mlx-q4",- "size_gb": 20,+ "size_gb": 20.48,"files": ["transformer-distilled.safetensors","connector.safetensors",@@ -34,7 +35,7 @@"key": "gemma","kind": "base","name": "Gemma 3 12B (4-bit text encoder)",- "blurb": "Required. Encodes the prompt for the diffusion model.",+ "blurb": "LTX-2.3's text encoder — and what Enhance and the Storyboard planner run on, whichever generation renders.","repo_id": "mlx-community/gemma-3-12b-it-4bit","local_dir": "mlx_models/gemma-3-12b-it-4bit","size_gb": 6,@@ -49,7 +50,7 @@"key": "q8","kind": "optional","name": "LTX 2.3 \u2014 Q8 (high-quality + FFLF)",- "blurb": "Optional. Unlocks High quality and keyframe (FFLF) interpolation.",+ "blurb": "The previous generation's high-quality weights. On LTX-2.5 the High tier uses the 2.5 Q8 pack plus the High add-on instead.","repo_id": "dgrauet/ltx-2.3-mlx-q8","local_dir": "mlx_models/ltx-2.3-mlx-q8","size_gb": 37,@@ -130,6 +131,165 @@"download_include": ["ltx-2.3-22b-ic-lora-union-control-ref0.5.safetensors"]+ },+ {+ "_comment": "LTX-2.5 Q4. Built by us (scripts/convert_ltx_mlx.py -> scripts/quantize_ltx.py) from the official Lightricks bf16 release, not by dgrauet. Mirrored through a GitHub release rather than HuggingFace, so deep-verify reads sha256 from the in-pack phosphene_quant_manifest.json (verify_source 'manifest') instead of the HF checksum API \u2014 which is why that manifest is listed as a required file. temporal_upscaler and duration_head ship because 2.5 has them and they are tiny; the x1.5 spatial upscaler does not exist for 2.5.",+ "_mirror_comment": "PUBLISHED 2026-08-12. `repo_id` names a HuggingFace repo that DOES NOT EXIST and never will \u2014 our HF token is read-only and this pack is our own quantisation of a gated upstream. It is kept only as the pack's stable identity string (the panel shows it, and `_expected_meta` never calls the HF API for a verify_source 'manifest' pack). The bytes come from the `mirror` block: GitHub release assets, sharded at 1.9 GB because the cap is 2 GiB, fetched + reassembled + sha256-verified by scripts/fetch_pack_release.py. `download_include` is inert on this lane (the release manifest is the allowlist) and is kept only so the entry stays shaped like every other.",+ "key": "q4_25",+ "kind": "base",+ "name": "LTX-2.5 base",+ "blurb": "The engine. Every render needs it.",+ "repo_id": "mrbizarro/ltx-2.5-mlx-q4",+ "local_dir": "mlx_models/ltx-2.5-mlx-q4",+ "size_gb": 20.74,+ "mirror": {+ "kind": "github-release",+ "release_repo": "mrbizarro/Phosphene",+ "tag": "weights-ltx25-v1",+ "manifest_asset": "q4_25__phosphene_release_manifest.json"+ },+ "files": [+ "transformer-distilled.safetensors",+ "connector.safetensors",+ "vae_decoder.safetensors",+ "vae_encoder.safetensors",+ "audio_vae.safetensors",+ "vocoder.safetensors",+ "spatial_upscaler_x2_v1_1.safetensors",+ "temporal_upscaler_x2_v1_0.safetensors",+ "duration_head.safetensors",+ "phosphene_quant_manifest.json"+ ],+ "download_include": [+ "*.json",+ "transformer-distilled.safetensors",+ "connector.safetensors",+ "vae_decoder.safetensors",+ "vae_encoder.safetensors",+ "audio_vae.safetensors",+ "vocoder.safetensors",+ "spatial_upscaler_x2_v1_1.safetensors",+ "temporal_upscaler_x2_v1_0.safetensors",+ "duration_head.safetensors"+ ]+ },+ {+ "_comment": "LTX-2.5 Q8 - the HQ tier, same relationship to q4_25 that the 2.3 q8 pack has to the 2.3 q4 pack. Built 2026-08-12 by scripts/quantize_ltx.py --bits 8 from the same MLX-layout bf16 transformer the q4 pack came from; 20,595,260,317 B against the 2.3 q8 pack's 20,597,189,549 B, and every byte of the -1,929,232 B difference is 2.5's 96 absent FFN biases (-1,966,080), its one extra keyframe embedding (+8,192) and header growth (+28,656). The eight non-transformer components are sha256-identical to the q4 pack's copies - verified file by file - because quantisation touches only transformer.transformer_blocks.*, exactly as in 2.3. Same GitHub-release mirror lane as q4_25, so verify_source is 'manifest' and phosphene_quant_manifest.json is a required file. 2026-08-12 THIRD PASS, THE SPLIT: transformer-dev.safetensors and ltx-2.5-22b-distilled-lora-450.safetensors were briefly listed HERE (e870061) and now live in the hq_25 add-on entry below. They are not part of this pack - they are a separate, later build (the dev transformer is 42 GB upstream and was still downloading), and listing them here made a pack that is COMPLETE ON DISK both unpublishable and un-installable. The gate e870061 bought by listing them is NOT lost: the panel asks hq_surface_missing(), which unions this pack with the add-on, so High / Extend / Keyframe / A2V still refuse by name. Only the owning download unit changed.",+ "key": "q8_25",+ "kind": "optional",+ "name": "LTX-2.5 Q8 weights",+ "blurb": "8-bit instead of 4-bit. Needed for trained characters and voices — on the base pack most of a trained face is lost before the first frame. Same speed, more memory.",+ "repo_id": "mrbizarro/ltx-2.5-mlx-q8",+ "local_dir": "mlx_models/ltx-2.5-mlx-q8",+ "size_gb": 30.02,+ "files": [+ "transformer-distilled.safetensors",+ "connector.safetensors",+ "vae_decoder.safetensors",+ "vae_encoder.safetensors",+ "audio_vae.safetensors",+ "vocoder.safetensors",+ "spatial_upscaler_x2_v1_1.safetensors",+ "temporal_upscaler_x2_v1_0.safetensors",+ "duration_head.safetensors",+ "phosphene_quant_manifest.json"+ ],+ "download_include": [+ "*.json",+ "transformer-distilled.safetensors",+ "connector.safetensors",+ "vae_decoder.safetensors",+ "vae_encoder.safetensors",+ "audio_vae.safetensors",+ "vocoder.safetensors",+ "spatial_upscaler_x2_v1_1.safetensors",+ "temporal_upscaler_x2_v1_0.safetensors",+ "duration_head.safetensors"+ ],+ "mirror": {+ "kind": "github-release",+ "release_repo": "mrbizarro/Phosphene",+ "tag": "weights-ltx25-v1",+ "manifest_asset": "q8_25__phosphene_release_manifest.json"+ }+ },+ {+ "_comment": "LTX-2.5 HQ add-on - the two-stage HQ FEATURE surface, not a model pack. High, Extend, Keyframe and A2V reach past model_dir and load these two files BY NAME; the panel names them per generation via MODEL_VERSIONS[...]['hq_weights'], because the number in the LoRA filename is its alpha/rank (2.3 ships 384, 2.5 ships 450) and the names are NOT interchangeable between generations. WHY A SEPARATE ENTRY AND NOT PART OF q8_25: it is a separate build that finishes later, and a download unit has to be publishable the moment its bytes exist. Folding these into q8_25 held a complete 20.6 GB pack hostage to a 42 GB download. WHY local_dir IS THE q8 DIRECTORY: these files are loaded out of the q8 pack BY NAME, so they must land beside it. Two entries, one directory, deliberately - the entry is a download unit, not a directory. MIRROR BLOCK LANDED 2026-08-12, in the same commit as the assets - the rule this entry was written to demonstrate. The dev transformer (20,595,256,595 B, ltx-dit q8) and the LoRA (8,899,889,568 B, verbatim bf16) are published to weights-ltx25-v1 and both carry sha256 rows in the in-pack phosphene_quant_manifest.json, so deep-verify (verify_source 'manifest') can check them. publish_scope 'files' keeps this add-on from claiming the q8 pack's sidecars.",+ "key": "hq_25",+ "kind": "optional",+ "name": "LTX-2.5 High add-on",+ "blurb": "Unlocks the High tier, Extend and Keyframes. Installs into the Q8 folder, so it needs Q8 first.",+ "repo_id": "mrbizarro/ltx-2.5-mlx-hq",+ "local_dir": "mlx_models/ltx-2.5-mlx-q8",+ "size_gb": 29.5,+ "publish_scope": "files",+ "mirror": {+ "kind": "github-release",+ "release_repo": "mrbizarro/Phosphene",+ "tag": "weights-ltx25-v1",+ "manifest_asset": "hq_25__phosphene_release_manifest.json"+ },+ "files": [+ "transformer-dev.safetensors",+ "ltx-2.5-22b-distilled-lora-450.safetensors"+ ],+ "download_include": [+ "transformer-dev.safetensors",+ "ltx-2.5-22b-distilled-lora-450.safetensors"+ ]+ },+ {+ "_comment": "LTX-2.5's text encoder is NOT the stock Gemma 3 the 2.3 pack uses: it is a custom Gemma 4 12B fine-tune declaring model_type gemma4_unified, and the DiT's dual text projection was moved out of connector.safetensors and into it (we route that back into the connector at conversion time). Falling back to Gemma 3 would load, run, and quietly encode wrongly, so the loader refuses instead.",+ "key": "gemma4_25",+ "kind": "base",+ "name": "LTX-2.5 text encoder (Gemma 4)",+ "blurb": "Reads your prompt. LTX-2.5 will not run on 2.3's encoder.",+ "repo_id": "mrbizarro/gemma4-12b-ltx25-q4",+ "local_dir": "mlx_models/gemma4-12b-ltx25-q4",+ "size_gb": 6.73,+ "mirror": {+ "kind": "github-release",+ "release_repo": "mrbizarro/Phosphene",+ "tag": "weights-ltx25-v1",+ "manifest_asset": "gemma4_25__phosphene_release_manifest.json"+ },+ "files": [+ "config.json",+ "tokenizer.json",+ "tokenizer_config.json",+ "model.safetensors.index.json",+ "model-00001-of-00001.safetensors"+ ],+ "download_include": [+ "*.json",+ "*.jinja",+ "model-*.safetensors"+ ]+ },+ {+ "_comment": "The tiny decoder behind LIVE PREVIEW. 22.4 MiB, MIT, ungated, from github.com/madebyollin/taehv (taeltx2_3.safetensors, 23,531,296 B, sha256 f0773b4e…be246 — verified byte count and hash before publishing). It turns the x0 estimate the denoise loop ALREADY HOLDS into a thumbnail, so nothing is recomputed and a render with the preview on is byte-identical to the same render with it off.",+ "_mirror_comment": "Mirrored onto the SAME release as the 2.5 packs rather than fetched from raw.githubusercontent at render time, so it rides the ordinary lane: files[] + download_include[], one manifest format, sha256-verified and resumable by scripts/fetch_pack_release.py, and no new fetch-lane code. `repo_id` names the upstream for attribution; the bytes come from the mirror block.",+ "key": "tae",+ "kind": "base",+ "name": "Live-preview decoder",+ "blurb": "22 MB. Draws the shot as it forms, so a wrong take can be stopped in seconds instead of minutes.",+ "repo_id": "madebyollin/taehv",+ "local_dir": "mlx_models/tae",+ "size_gb": 0.02,+ "mirror": {+ "kind": "github-release",+ "release_repo": "mrbizarro/Phosphene",+ "tag": "weights-ltx25-v1",+ "manifest_asset": "tae__phosphene_release_manifest.json"+ },+ "files": [+ "taeltx2_3.safetensors",+ "LICENSE-taehv"+ ],+ "download_include": [+ "taeltx2_3.safetensors",+ "LICENSE-taehv"+ ]}],"env": {diff --git a/scripts/assert_registry.py b/scripts/assert_registry.pynew file mode 100644index 0000000..e67107f--- /dev/null+++ b/scripts/assert_registry.py@@ -0,0 +1,476 @@+#!/usr/bin/env python3+"""Hard gate over the model-version registry, run against the REAL panel module.++WHY THIS FILE IS IN THE REPO+============================+It was written in a session scratchpad when the registry gained its first seam+(`ltx25_panel_seam.md` §7 nominated it as "the file to port into the repo first+if the registry grows a second entry"). The registry grew a second entry on+2026-08-12 and the file stayed in the scratchpad, where it rotted: by the time+anyone looked, **28 of its 71 assertions were failing** — every one of them+because `ltx23` had stopped being the default, not because anything was broken.+A gate nobody can read is worse than no gate: a real regression hides in the+noise, and this one did (see DEFECT-1 below, which had been live for a day).++So: expectations updated to current truth, and the file lives here now, where+`git log` shows when an expectation moved and why.++ ./ltx-2-mlx/env/bin/python3.11 scripts/assert_registry.py++Exit 0 = PASS. It touches no GPU, opens no socket, starts no server, and writes+only into an isolated LTX_STATE_DIR.++WHAT IT IS FOR+==============+The registry decides, for every generation, which weights load, which text+encoder conditions them, which surface the UI offers, and which files must be+present before a job is allowed to start. Every one of those has already been+wrong at least once, and NONE of them raised at the time:++ * `base_model_dir()` handed LTX-2.5 the 2.3 pack. Rendered in 44 s and looked+ fine.+ * The registry had no seam for the TEXT ENCODER, so the 2.5 DiT was+ conditioned on Gemma 3. Both towers project to 188160, so every shape+ agreed, nothing raised, and the output was merely wrong.+ * A `download_include` allowlist dropped one 1 GB upscaler, the loader built+ it from random initialisation, and the result was the rainbow "mosaic" —+ two weeks and three wrong theories before anyone read the file list.++None of those is catchable by a test that mocks the registry. They are only+catchable by asking the real module about the real install.+"""+from __future__ import annotations++import importlib.util+import json+import os+import sys+import tempfile+from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent+STATE = Path(tempfile.mkdtemp(prefix="phos-assert-registry-"))++# Isolate every piece of mutable state so importing the panel cannot touch a+# real install, and never let this gate phone home.+os.environ["LTX_STATE_DIR"] = str(STATE)+os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"+os.environ["PHOSPHENE_DISABLE_VERSION_CHECK"] = "1"+os.environ.setdefault("LTX_PORT", "8299")+sys.path.insert(0, str(ROOT))++spec = importlib.util.spec_from_file_location("panel", ROOT / "mlx_ltx_panel.py")+p = importlib.util.module_from_spec(spec)+sys.modules["panel"] = p+spec.loader.exec_module(p)++OK = FAIL = DEFECT = 0+_failures: list[str] = []+++def eq(label, got, want):+ global OK, FAIL+ if got == want:+ OK += 1+ else:+ FAIL += 1+ _failures.append(f"{label}\n got : {got!r}\n want: {want!r}")+++def raises(label, fn, needle):+ global OK, FAIL+ try:+ fn()+ except RuntimeError as exc:+ if needle in str(exc):+ OK += 1+ return+ FAIL += 1+ _failures.append(f"{label}: raised but the message lacks {needle!r}: {exc}")+ return+ except Exception as exc: # noqa: BLE001+ FAIL += 1+ _failures.append(f"{label}: wrong exception {type(exc).__name__}: {exc}")+ return+ FAIL += 1+ _failures.append(f"{label}: did not raise")+++def no_raise(label, fn):+ global OK, FAIL+ try:+ fn()+ OK += 1+ except Exception as exc: # noqa: BLE001+ FAIL += 1+ _failures.append(f"{label}: raised {type(exc).__name__}: {exc}")+++def known_defect(tag, label, got, current, should_be):+ """Pin a WRONG behaviour so the gate stays green and the bug stays visible.++ The alternative is to assert the correct value and leave the gate red, at+ which point everybody learns to ignore it — which is exactly how this file+ accumulated 28 failures and stopped being read.++ So the current, wrong value is asserted, a banner is printed every run, and+ **fixing the bug turns this red**, forcing whoever fixes it to come back+ here and delete the marker. A known defect that can be fixed without anyone+ noticing is not being tracked, it is being forgotten.+ """+ global OK, FAIL, DEFECT+ if got == current:+ OK += 1+ DEFECT += 1+ print(f" DEFECT {tag}: {label}")+ print(f" is : {got!r}")+ print(f" should be: {should_be}")+ else:+ FAIL += 1+ _failures.append(+ f"{tag} moved: {label}\n got : {got!r}\n pinned-as-broken: {current!r}\n"+ f" If you FIXED it — thank you: delete this known_defect() call and assert the\n"+ f" correct value. If you changed it by accident, this is the warning."+ )+++# =============================================================================+# 1. Registry shape — two generations, 2.5 is default AND active+# =============================================================================+eq("registered versions", [v["id"] for v in p.MODEL_VERSIONS], ["ltx23", "ltx25"])+eq("active version", p.ACTIVE_MODEL_VERSION, "ltx25")+eq("default version", p.default_model_version_id(), "ltx25")+eq("2.3 label", p.model_version("ltx23")["label"], "LTX-2.3")+eq("2.5 label", p.model_version("ltx25")["label"], "LTX-2.5")+eq("an unknown version falls back to the default", p.model_version("nope")["id"], "ltx25")+eq("both generations offer q4 + q8", p.version_quants("ltx23"), ("q4", "q8"))+eq("both generations offer q4 + q8 (2.5)", p.version_quants("ltx25"), ("q4", "q8"))+eq("cap tiers 2.3", p.version_cap_tiers("ltx23"), ("q4", "q8"))+eq("cap tiers 2.5", p.version_cap_tiers("ltx25"), ("q4", "q8"))++# The reverse lookup is what lets a repo key (which is what the download lane+# and /status speak) be turned back into a quant.+eq("repo key -> quant, 2.3 q4", p._quant_for_repo_key("q4", "ltx23"), "q4")+eq("repo key -> quant, 2.3 q8", p._quant_for_repo_key("q8", "ltx23"), "q8")+eq("repo key -> quant, 2.5 q4", p._quant_for_repo_key("q4_25", "ltx25"), "q4")+eq("repo key -> quant, 2.5 q8", p._quant_for_repo_key("q8_25", "ltx25"), "q8")+eq("an encoder repo is not a pack", p._quant_for_repo_key("gemma"), None)+eq("None is not a pack", p._quant_for_repo_key(None), None)++# =============================================================================+# 2. Each generation resolves its OWN pack — the §4.1 bug+# =============================================================================+# base_model_dir() handed 2.5 the 2.3 directory because it keyed off+# "am I the ACTIVE version" while ltx23 was both default and active. It now+# keys off PACK IDENTITY: a version gets MODEL_ID only when its own q4 pack+# path IS Q4_LOCAL_PATH. That is why the answer stopped moving when the+# default did, and it is the assertion that would have caught it.+eq("2.3 base dir is the 2.3 pack", Path(p.base_model_dir("ltx23")).name, "ltx-2.3-mlx-q4")+eq("2.5 base dir is the 2.5 pack", Path(p.base_model_dir("ltx25")).name, "ltx-2.5-mlx-q4")+eq("the default lane resolves 2.5", p.base_model_dir(), p.base_model_dir("ltx25"))+eq("2.3 keeps the env-aware MODEL_ID spelling", p.base_model_dir("ltx23"), str(p.MODEL_ID))+eq("2.3 q4 path", p.pack_path("q4", "ltx23"), p.Q4_LOCAL_PATH)+eq("2.3 q8 path", p.pack_path("q8", "ltx23"), p.Q8_LOCAL_PATH)+eq("2.5 q4 path", p.pack_path("q4", "ltx25").name, "ltx-2.5-mlx-q4")+eq("2.5 q8 path", p.pack_path("q8", "ltx25").name, "ltx-2.5-mlx-q8")+eq("an unregistered quant falls back to the models root", p.pack_path("q9"), p.MODELS_DIR)++# =============================================================================+# 3. Each generation names its own TEXT ENCODER — the §4.2 bug, the worse one+# =============================================================================+# Gemma 3 12B and Gemma 4 12B both project to 3840 x (48+1) = 188160, so a 2.5+# DiT conditioned on the 2.3 encoder raises nothing, agrees on every shape, and+# is merely wrong. The port's resolve_text_tower() refusal exists to prevent+# exactly this and could not, because the panel never handed it the 2.5+# encoder. A refusal only fires on a path something reaches.+eq("2.3 encoder is Gemma 3", Path(p.text_encoder_dir("ltx23")).name, "gemma-3-12b-it-4bit")+eq("2.5 encoder is Gemma 4", Path(p.text_encoder_dir("ltx25")).name, "gemma4-12b-ltx25-q4")+eq("the default lane uses Gemma 4", p.text_encoder_dir(), p.text_encoder_dir("ltx25"))+eq("2.3 names the GEMMA constant so LTX_GEMMA_PATH still works",+ p.model_version("ltx23")["text_encoder"]["repo_key"], "gemma")+eq("2.5 names its own encoder repo",+ p.model_version("ltx25")["text_encoder"]["repo_key"], "gemma4_25")+eq("the two encoders are different directories",+ p.text_encoder_dir("ltx23") != p.text_encoder_dir("ltx25"), True)++# =============================================================================+# 4. required_files.json is the single source of truth (never a copy)+# =============================================================================+_by_key = {r["key"]: r for r in p._REQUIRED["repos"]}+eq("every registered repo key exists in required_files.json",+ sorted(k for k in ("q4", "q8", "q4_25", "q8_25", "hq_25", "gemma", "gemma4_25")+ if k not in _by_key), [])+for vid, q, key in (("ltx23", "q4", "q4"), ("ltx23", "q8", "q8"),+ ("ltx25", "q4", "q4_25"), ("ltx25", "q8", "q8_25")):+ eq(f"{vid}/{q} pack repo IS the json entry", p.pack_repo(q, vid), _by_key[key])+eq("2.3 q4 file count", len(_by_key["q4"]["files"]), 7)+eq("2.3 q8 file count", len(_by_key["q8"]["files"]), 8)+eq("2.5 q4 file count", len(_by_key["q4_25"]["files"]), 10)+eq("2.5 q8 file count", len(_by_key["q8_25"]["files"]), 10)+eq("the June mosaic casualty is still in the 2.3 allowlist",+ "spatial_upscaler_x2_v1_1.safetensors" in _by_key["q4"]["download_include"], True)+eq("2.5 packs are BASE, not optional — the default lane needs them",+ [_by_key[k].get("kind") for k in ("q4_25", "gemma4_25")], ["base", "base"])++# The HQ add-on is a DOWNLOAD UNIT, not a directory: it shares q8_25's+# local_dir on purpose, because those two files are loaded out of it by name.+eq("2.5 declares an HQ add-on", p.model_version("ltx25").get("hq_addon_repo_key"), "hq_25")+eq("2.3 declares none, so the two-stage gates are inert for it",+ p.model_version("ltx23").get("hq_addon_repo_key"), None)+eq("the add-on is a guest in the q8 directory",+ _by_key["hq_25"].get("publish_scope"), "files")++# =============================================================================+# 5. Completeness — this install, and a synthetic incomplete one+# =============================================================================+eq("q8_missing_files delegates to the registry", p.q8_missing_files(), p.pack_missing_files("q8"))+eq("q8_available_anywhere delegates", p.q8_available_anywhere(), p.pack_available_anywhere("q8"))+eq("an unregistered quant invents no missing files", p.pack_missing_files("q9"), [])+for vid in ("ltx23", "ltx25"):+ for q in ("q4", "q8"):+ eq(f"this install is complete ({vid}/{q})", p.pack_missing_files(q, vid), [])+ eq(f"this install has {vid}'s text encoder", p.text_encoder_missing_files(vid), [])+eq("the HQ surface is complete on this box", p.hq_surface_missing("ltx25"), [])+eq("2.3 has no HQ surface of its own to be missing", p.hq_surface_missing("ltx23"), [])++# =============================================================================+# 6. cap_tier — the machine's RAM vs the version's ceiling+# =============================================================================+_ram_tier = "q8" if p.SYSTEM_CAPS.get("allows_q8") else "q4"+eq("the quant tier is a property of the MACHINE", p._resolve_quant_tier(), _ram_tier)+eq("neither shipped generation clamps below it",+ (p._resolve_cap_tier("ltx23"), p._resolve_cap_tier("ltx25")), (_ram_tier, _ram_tier))++_orig = p.MODEL_VERSIONS+_q4only = dict(p.model_version("ltx25"))+_q4only.update(id="ltx_q4only_test", cap_tiers=("q4",), packs=(p.version_pack("q4", "ltx25"),))+_q8only = dict(p.model_version("ltx25"))+_q8only.update(id="ltx_q8only_test", cap_tiers=("q8",))+p.MODEL_VERSIONS = _orig + (_q4only, _q8only)+try:+ eq("a q4-only version folds the surface DOWN on a q8 Mac",+ p._resolve_cap_tier("ltx_q4only_test"), "q4")+ eq("...without lying about the machine's own tier", p._resolve_quant_tier(), _ram_tier)+ eq("a q4-only version has no q8 pack", p.version_pack("q8", "ltx_q4only_test"), None)+ eq("a q8-only version is never folded UP past the machine",+ p._resolve_cap_tier("ltx_q8only_test"), _ram_tier)+finally:+ p.MODEL_VERSIONS = _orig+eq("the registry is restored", [v["id"] for v in p.MODEL_VERSIONS], ["ltx23", "ltx25"])++# =============================================================================+# 7. Job-time preflight — the anti-mosaic refusal+# =============================================================================+# DEFECT-1, FIXED (v4.0 step 7). `_canonical_layout()` compared MODEL_ID against+# `pack_path("q4")` with NO version_id — the DEFAULT generation. That was an+# identity while ltx23 was the only entry; from f1d2139 (2026-08-12) it compared+# the 2.3 install path against the 2.5 pack path, which are never equal, so it+# was False on every stock install. It is the SOLE gate on+# `ltx_pack_preflight()`, so the June-2026 mosaic guard was switched off in the+# field: an incomplete pack rendered a rainbow mosaic instead of naming the file.+#+# It now compares within a version, against ANY registered generation's own q4+# pack, which is what the expression meant before a second generation existed.+eq("the canonical layout is recognised on a stock install",+ p._canonical_layout(), True)+# And the property that made it rot: the answer must not depend on which+# generation is active. It is a question about THIS install's layout.+_saved_active_cl = p.ACTIVE_MODEL_VERSION+try:+ _seen_cl = {}+ for _vid in ("ltx25", "ltx23"):+ p.ACTIVE_MODEL_VERSION = _vid+ _seen_cl[_vid] = p._canonical_layout()+ eq("the layout check does not move with the active generation",+ _seen_cl["ltx25"], _seen_cl["ltx23"])+ eq("...and it is True from either", _seen_cl["ltx23"], True)+finally:+ p.ACTIVE_MODEL_VERSION = _saved_active_cl++# The refusal itself still works when it is reached — proven by driving it with+# the layout check forced, so the day DEFECT-1 is fixed the machinery is known+# good rather than merely re-enabled.+_saved_canon = p._canonical_layout+p._canonical_layout = lambda: True+try:+ for vid in ("ltx23", "ltx25"):+ no_raise(f"a complete pack passes ({vid}/q4)",+ lambda vid=vid: p.ltx_pack_preflight("q4", "X", vid))+ no_raise(f"a complete pack passes ({vid}/q8)",+ lambda vid=vid: p.ltx_pack_preflight("q8", "X", vid))+ no_raise("an unregistered quant is a no-op", lambda: p.ltx_pack_preflight("q9", "X"))++ with tempfile.TemporaryDirectory() as td:+ fake = Path(td) / "incomplete-q8"+ fake.mkdir()+ repo = p.pack_repo("q8", "ltx23")+ for f in repo["files"]:+ if f == "spatial_upscaler_x2_v1_1.safetensors":+ continue # the actual June 2026 casualty+ (fake / f).write_bytes(b"x" * 4096)+ pack = p.version_pack("q8", "ltx23")+ saved = pack["path"]+ pack["path"] = fake+ # `pack_available_anywhere` is a second, legitimate early return: a pack+ # that is incomplete in mlx_models but complete in the HF cache is not+ # broken. On a developer box the 2.3 q8 files ARE in the cache, so the+ # refusal would never be reached and this section would test nothing.+ # Forced off for the duration — the property under test is "missing+ # everywhere", not "missing here".+ _saved_anywhere = p.pack_available_anywhere+ p.pack_available_anywhere = lambda q, v=None: False+ try:+ eq("the missing file is NAMED", p.pack_missing_files("q8", "ltx23"),+ ["spatial_upscaler_x2_v1_1.safetensors"])+ for needle, what in (+ ("spatial_upscaler_x2_v1_1.safetensors", "names the file"),+ ("mosaic", "explains the mosaic"),+ ("Extend", "names the feature"),+ (repo["repo_id"], "names the repo to re-download"),+ ):+ raises(f"the refusal {what}",+ lambda: p.ltx_pack_preflight("q8", "Extend", "ltx23"), needle)+ # ...and the OTHER generation is untouched by it.+ no_raise("2.5 is unaffected by a broken 2.3 pack",+ lambda: p.ltx_pack_preflight("q8", "Extend", "ltx25"))+ finally:+ pack["path"] = saved+ p.pack_available_anywhere = _saved_anywhere+ eq("the 2.3 q8 path is restored", p.pack_path("q8", "ltx23"), p.Q8_LOCAL_PATH)+ no_raise("preflight is quiet again", lambda: p.ltx_pack_preflight("q8", "X", "ltx23"))+finally:+ p._canonical_layout = _saved_canon++# A non-canonical layout must never be second-guessed: we have no manifest for+# a bare HF repo id or a directory the user assembled, so a completeness claim+# about either would be a lie.+_saved_model_id = p.MODEL_ID+try:+ for spelling in ("dgrauet/ltx-2.3-mlx-q4", "/somewhere/custom/weights"):+ p.MODEL_ID = spelling+ eq(f"{spelling!r} is not the canonical layout", p._canonical_layout(), False)+ no_raise(f"{spelling!r} is never second-guessed",+ lambda: p.ltx_pack_preflight("q8", "Extend", "ltx23"))+finally:+ p.MODEL_ID = _saved_model_id++# =============================================================================+# 8. Deep-verify SHA sources — hf-api vs the shipped manifest+# =============================================================================+# The 2.5 packs are OUR quantisation, mirrored as GitHub release assets, so+# HuggingFace has no hashes for them and the pack ships its own manifest. The+# 2.3 packs are dgrauet's and are verified against the HF API. Getting this+# backwards means either a network call that returns nothing (and a silent+# fallback) or a pack that is never really verified.+eq("2.3 q4 verifies against hf-api", p._pack_verify_source("q4"), "hf-api")+eq("2.3 q8 verifies against hf-api", p._pack_verify_source("q8"), "hf-api")+eq("2.5 q4 verifies against its manifest", p._pack_verify_source("q4_25"), "manifest")+eq("2.5 q8 verifies against its manifest", p._pack_verify_source("q8_25"), "manifest")++# DEFECT-2, FIXED (v4.0 step 1). Those four answers used to be right with two of+# them right by accident: `_pack_verify_source(repo_key)` resolved+# `version_pack(quant)` with NO version_id — i.e. through whichever generation+# was DEFAULT — so the OTHER generation's repo key was not recognised as a pack+# at all and fell through to the "hf-api" default. Flipping the default to 2.3+# sent the 2.5 packs to a HuggingFace repo that does not exist and never will,+# surviving only on `_expected_meta`'s empty-answer fallback to the manifest:+# one silent step from "verified" meaning "not checked".+#+# The fix is `pack_for_repo_key()`, which searches every registered generation,+# because where a pack's checksums live is a property of the PACK. The assertion+# that matters is therefore the one that used to be impossible: the answers must+# not depend on which generation is active. Both directions, both generations.+eq("2.5 q4's verify source is a property of the pack, not of the session",+ p.pack_for_repo_key("q4_25")["quant"], "q4")+eq("2.3 q4 resolves to a pack too, from a 2.5-default process",+ p.pack_for_repo_key("q4")["quant"], "q4")+eq("2.3 q8 resolves to a pack", p.pack_for_repo_key("q8")["quant"], "q8")+eq("2.5 q8 resolves to a pack", p.pack_for_repo_key("q8_25")["quant"], "q8")+eq("a non-pack repo key is still not a pack", p.pack_for_repo_key("gemma"), None)+eq("the HQ add-on is a FEATURE surface, not a pack", p.pack_for_repo_key("hq_25"), None)+# The property under test, stated as itself: swing ACTIVE_MODEL_VERSION across+# both generations and every verify source must be unchanged. This is the+# assertion the known_defect marker stood in for, and it is red on the old code.+_saved_active = p.ACTIVE_MODEL_VERSION+try:+ _seen = {}+ for _vid in ("ltx25", "ltx23"):+ p.ACTIVE_MODEL_VERSION = _vid+ _seen[_vid] = {k: p._pack_verify_source(k)+ for k in ("q4", "q8", "q4_25", "q8_25", "gemma", "ic_colorize")}+ eq("verify sources do not move when the active generation does",+ _seen["ltx25"], _seen["ltx23"])+ eq("...and they are the right answers, from either generation",+ _seen["ltx23"],+ {"q4": "hf-api", "q8": "hf-api", "q4_25": "manifest", "q8_25": "manifest",+ "gemma": "hf-api", "ic_colorize": "hf-api"})+finally:+ p.ACTIVE_MODEL_VERSION = _saved_active+eq("an unknown repo defaults to hf-api", p._pack_verify_source("ic_colorize"), "hf-api")+eq("None defaults to hf-api", p._pack_verify_source(None), "hf-api")+eq("the 2.5 q4 pack really does carry a manifest",+ (p.pack_path("q4", "ltx25") / p.PACK_MANIFEST_NAME).exists(), True)+eq("the 2.3 q4 pack really does not",+ (p.pack_path("q4", "ltx23") / p.PACK_MANIFEST_NAME).exists(), False)++with tempfile.TemporaryDirectory() as td:+ base = Path(td)+ eq("no manifest -> {}", p._manifest_meta(base), {})+ (base / p.PACK_MANIFEST_NAME).write_text("{ not json")+ eq("malformed manifest -> {} (never 'corrupt')", p._manifest_meta(base), {})+ (base / p.PACK_MANIFEST_NAME).write_text('{"files": "wrong type"}')+ eq("wrong-shaped manifest -> {}", p._manifest_meta(base), {})+ (base / p.PACK_MANIFEST_NAME).write_text(json.dumps({+ "tool": "quantize_ltx.py", "tool_version": "1",+ "files": {+ "transformer-distilled.safetensors": {"sha256": "a" * 64, "bytes": 11322002285},+ "connector.safetensors": {"sha256": "b" * 64, "size": 42},+ "junk": "not a dict",+ "no_hash.safetensors": {"bytes": 0},+ },+ }))+ meta = p._manifest_meta(base)+ eq("manifest sha parsed", meta["transformer-distilled.safetensors"]["sha256"], "a" * 64)+ eq("manifest bytes parsed", meta["transformer-distilled.safetensors"]["size"], 11322002285)+ eq("'size' is accepted as well as 'bytes'", meta["connector.safetensors"]["size"], 42)+ eq("a non-dict entry is skipped", "junk" in meta, False)+ eq("a hash-less zero-byte entry is skipped", "no_hash.safetensors" in meta, False)++ # Drive the real _expected_meta on the DEFAULT generation's q4 pack, which+ # is the one `_pack_verify_source` actually resolves (see DEFECT-2). Its+ # repo key is what a caller passes; the network is spied, never called.+ _calls: list[str] = []+ _real = p._upstream_meta+ p._upstream_meta = lambda rid: (_calls.append(rid) or {})+ _key = p.pack_repo("q4")["key"] # "q4_25" while 2.5 is default+ _rid = p.pack_repo("q4")["repo_id"]+ _pk = p.version_pack("q4")+ _saved_src = _pk["verify_source"]+ try:+ _pk["verify_source"] = "manifest"+ eq("a manifest pack reads the manifest",+ p._expected_meta(_key, _rid, base)+ ["transformer-distilled.safetensors"]["sha256"], "a" * 64)+ eq("a manifest pack NEVER asks HuggingFace", _calls, [])+ _pk["verify_source"] = "hf-api"+ got = p._expected_meta(_key, _rid, base)+ eq("an hf-api pack asks HuggingFace first", _calls, [_rid])+ eq("an empty network answer falls back to the manifest",+ got["connector.safetensors"]["sha256"], "b" * 64)+ p._upstream_meta = lambda rid: {"connector.safetensors": {"sha256": "c" * 64, "size": 1}}+ eq("a real network answer still wins over the manifest",+ p._expected_meta(_key, _rid, base)["connector.safetensors"]["sha256"], "c" * 64)+ finally:+ p._upstream_meta = _real+ _pk["verify_source"] = _saved_src+eq("the verify source is restored", p._pack_verify_source("q4_25"), "manifest")++# =============================================================================+print()+for f in _failures:+ print("FAIL " + f)+print()+print(f"{OK} passed, {FAIL} failed, {DEFECT} known defect(s) pinned")+if DEFECT:+ print("A pinned defect is NOT a pass. See the DEFECT lines above.")+raise SystemExit(1 if FAIL else 0)diff --git a/scripts/assert_schedules.py b/scripts/assert_schedules.pynew file mode 100644index 0000000..27ebb8b--- /dev/null+++ b/scripts/assert_schedules.py@@ -0,0 +1,223 @@+#!/usr/bin/env python3+"""Every mode, every generation: the job dict the panel builds must produce a+schedule the engine will accept.++THE FAILURE THIS EXISTS FOR+---------------------------+`make_job` stamped ``stage1_steps=10`` onto every job from a form field that+does not exist, so the value was always 10 and every other lane's own default+was dead code behind it (``generate_restore`` reads ``p.get("stage1_steps", 8)``+and never once saw 8).++A step count THINS the checkpoint's own table, so asking for 10 asks a 9-point+table to pad, which `thin_sigmas` correctly refuses. Colorize and Restore loaded+models, worked for **218 seconds**, and died on::++ stage 1: cannot thin a 9-point schedule (8 steps) up to 10 steps++AND IT WAS NEVER 2.5-SPECIFIC — measured, not assumed. `distilled_presets_for`+returns a **9-point stage-1 table for BOTH generations**, and+`resolve_distilled_schedule(gen, stage1_steps=10)` raises identically on+``(2,3,0)`` and ``(2,5,0)``. The report that surfaced this called it a 2.5+break; it is generation-independent on the current pin, and Colorize/Restore+were broken on 2.3 too. That is worth knowing, because "it works on the old+generation" is exactly the belief that would have sent someone hunting in the+2.5 port.++A mode that burns four minutes of compute and then fails on a cryptic sampler+error, while the README says it works, is the June-2026 mosaic in a different+costume: a real refusal, correct in itself, reached far too late and impossible+to attribute from the outside.++WHAT THIS GATE ASSERTS+----------------------+For **every render mode the panel can submit** × **every registered+generation**: build the job dict through the REAL ``make_job``, resolve the+stage step counts the way the helper does, and hand them to the engine's own+``resolve_distilled_schedule``. It must not raise.++It is deliberately end-to-end through `make_job` rather than a unit test of the+clamp: the bug was not in the clamp (there wasn't one), it was in what the panel+asked for. A test of the asker's *output* is the only shape that would have+caught it.++No GPU, no network, no model load — this reads sigma tables, which are module+constants. ~1 s.+"""++from __future__ import annotations++import importlib.util+import os+import sys+import tempfile+from pathlib import Path++ROOT = Path(__file__).resolve().parents[1]+os.environ.setdefault("LTX_STATE_DIR", tempfile.mkdtemp(prefix="phos-sched-gate-"))+sys.path.insert(0, str(ROOT))++FAILS: list[str] = []+CHECKS = 0+++def check(label: str, fn) -> None:+ global CHECKS+ CHECKS += 1+ try:+ fn()+ except Exception as exc: # noqa: BLE001 — the point is to report, not raise+ FAILS.append(f"{label}: {type(exc).__name__}: {exc}")+++def load_panel(version_id: str | None):+ """Import mlx_ltx_panel with a given generation active."""+ if version_id:+ os.environ["LTX_MODEL_VERSION"] = version_id+ else:+ os.environ.pop("LTX_MODEL_VERSION", None)+ for mod in [m for m in sys.modules if m in ("panel_under_test",)]:+ del sys.modules[mod]+ spec = importlib.util.spec_from_file_location(+ "panel_under_test", str(ROOT / "mlx_ltx_panel.py"))+ mod = importlib.util.module_from_spec(spec)+ sys.modules["panel_under_test"] = mod+ spec.loader.exec_module(mod)+ return mod+++# The modes a user can actually submit from the panel, with the minimum form+# each one needs. Every one of these reaches a distilled two-stage schedule.+MODE_FORMS = {+ "t2v": {"mode": "t2v"},+ "t2v_high": {"mode": "t2v", "quality": "high"},+ "i2v": {"mode": "i2v"},+ "character": {"mode": "t2v", "character_id": "bizarrotrn"},+ "keyframe": {"mode": "keyframe"},+ "extend": {"mode": "extend", "video_path": "/tmp/x.mp4"},+ "restore": {"mode": "restore", "restore_video_path": "/tmp/x.mp4"},+ "colorize": {"mode": "restore", "restore_video_path": "/tmp/x.mp4",+ "restore_kind": "colorize"},+ "ingredients": {"mode": "ingredients"},+ "control": {"mode": "control", "video_path": "/tmp/x.mp4"},+ "hdr": {"mode": "t2v", "hdr": "on"},+ "a2v": {"mode": "a2v"},+ "lipdub": {"mode": "lipdub"},+}++# What each lane defaults to when the job dict carries nothing — mirrored from+# run_job_inner's own `p.get("stage1_steps", N)` calls — and WHICH SCHEDULE API+# it reaches. The distinction is the whole bug:+#+# thin ICLoraPipeline: `thin_sigmas(DISTILLED_SIGMAS, n)` over a FIXED+# 9-point table. Ceiling 8 steps; more is a pad request and raises.+# build res_2s / keyframe-dev: `ltx2_schedule(n)` COMPUTES a schedule of+# whatever length is asked. 10 and 20 here are graded values, and+# clamping them would silently change owner-approved output.+#+# Getting this backwards is how a fix for one lane breaks two others.+LANE = {+ "restore": (8, 3, "thin"),+ "colorize": (8, 3, "thin"),+ "control": (8, 3, "thin"),+ "ingredients": (8, 4, "thin"),+ "hdr": (10, 3, "thin"), # <- the stamp made this 10 too+ "t2v_high": (10, 3, "build"),+ # keyframe HARDCODES stage1_steps=20 in its job_spec — it never reads+ # params — so the stamp never reached it and this fix cannot move it.+ # Modelled as "fixed" so the gate does not pretend otherwise.+ "keyframe": (20, 3, "fixed"),+}+DEFAULT_LANE = (8, 2, "thin")+++def run() -> None:+ from ltx_pipelines_mlx.scheduler import ( # noqa: PLC0415+ DISTILLED_SIGMAS, STAGE_2_SIGMAS, resolve_distilled_schedule, thin_sigmas,+ )++ # The ceiling every thinning lane lives under, read from the table itself.+ CAP1 = len(DISTILLED_SIGMAS) - 1+ CAP2 = len(STAGE_2_SIGMAS) - 1++ for version_id in ("ltx23", "ltx25"):+ p = load_panel(version_id)+ gen = tuple(int(x) for x in+ str(p.model_version()["config_key"]).split("-")[-1].split("."))+ if len(gen) == 2:+ gen = gen + (0,)++ for label, form in MODE_FORMS.items():+ def _one(label=label, form=form, gen=gen, p=p):+ job = p.make_job({k: [v] for k, v in form.items()})+ prm = job["params"]+ s1, s2, kind = LANE.get(label, DEFAULT_LANE)+ if kind != "fixed":+ s1 = int(prm.get("stage1_steps", s1))+ s2 = int(prm.get("stage2_steps", s2))+ if kind == "thin":+ # ...as the helper clamps before dispatch.+ s1, s2 = min(s1, CAP1), min(s2, CAP2)+ thin_sigmas(DISTILLED_SIGMAS, s1, name="stage 1")+ thin_sigmas(STAGE_2_SIGMAS, s2, name="stage 2")+ resolve_distilled_schedule(+ gen, stage1_steps=s1, stage2_steps=s2)+ else:+ # The computed lanes must NOT be clamped — assert they can+ # still ask for their graded counts.+ if s1 < 1:+ raise AssertionError(f"computed lane lost its step count: {s1}")+ check(f"{version_id}/{label}", _one)++ # THE ASSERTION THAT WOULD HAVE CAUGHT THE BUG, stated directly: no+ # thinning lane's resolved count may exceed the fixed table. Without the+ # fix, `hdr` (10) and every lane behind the stamp (10) fail here.+ for label, (s1, s2, kind) in LANE.items():+ if kind != "thin":+ continue+ def _cap(label=label, s1=s1, s2=s2):+ thin_sigmas(DISTILLED_SIGMAS, min(s1, CAP1), name="stage 1")+ thin_sigmas(STAGE_2_SIGMAS, min(s2, CAP2), name="stage 2")+ check(f"{version_id}/lane-default:{label}", _cap)++ # And the unclamped ask must be recognised as the error it is, so this+ # gate cannot pass by accident if the clamp is deleted.+ def _pad_is_refused():+ try:+ thin_sigmas(DISTILLED_SIGMAS, CAP1 + 2, name="stage 1")+ except ValueError:+ return+ raise AssertionError(+ "thin_sigmas accepted a pad request — the engine's refusal is "+ "what this whole gate is built on")+ check(f"{version_id}/pad-still-refused", _pad_is_refused)++ # The panel must not be stamping a step count nobody asked for.+ def _no_stamp(p=p):+ job = p.make_job({"mode": ["t2v"]})+ leaked = [k for k in ("stage1_steps", "stage2_steps")+ if k in job["params"]]+ if leaked:+ raise AssertionError(+ f"make_job stamped {leaked} with no form field — every "+ f"lane's own default is dead code behind it")+ check(f"{version_id}/no-unrequested-stamp", _no_stamp)++ # ...while an explicit value the user really did send still survives.+ def _explicit(p=p):+ job = p.make_job({"mode": ["t2v"], "stage1_steps": ["6"]})+ if job["params"].get("stage1_steps") != 6:+ raise AssertionError("an explicit stage1_steps was dropped")+ check(f"{version_id}/explicit-value-survives", _explicit)+++if __name__ == "__main__":+ run()+ print()+ if FAILS:+ for f in FAILS:+ print(f" FAIL {f}")+ print(f"\n{CHECKS - len(FAILS)} passed, {len(FAILS)} FAILED")+ sys.exit(1)+ print(f"{CHECKS} passed, 0 failed — "+ f"every mode x every generation resolves a schedule the engine accepts")diff --git a/scripts/check_ltx_pin.js b/scripts/check_ltx_pin.jsnew file mode 100644index 0000000..be54ee5--- /dev/null+++ b/scripts/check_ltx_pin.js@@ -0,0 +1,139 @@+#!/usr/bin/env node+/*+ * Gate: the vendored LTX pin is stated in four places and they must agree.+ *+ * ---------------------------------------------------------------------------+ * WHY+ * ---------------------------------------------------------------------------+ * The pin is not one value, it is a value plus the version string the runtime+ * reports when that value is checked out. If they drift, one of two bad things+ * happens and NEITHER produces an error at install time:+ *+ * - pin moves, _LTX_EXPECTED_VERSION doesn't -> every boot prints VERSION+ * SKEW at users who are perfectly fine, and the one real skew that matters+ * hides in the noise.+ * - _LTX_EXPECTED_VERSION moves, pin doesn't -> the same, inverted.+ *+ * That is exactly the blindness `871694d` was created to remove: before it, the+ * fork carried the bare string "0.14.19", so a 2.5 runtime reported+ * `match: true` against the 2.3 pin. A skew gate blind to the one skew that+ * matters is worse than no gate.+ *+ * The four places:+ * scripts/pinokio/ltx_checkout.sh LTX_PIN=... the truth, and the+ * only value any+ * lane executes+ * mlx_warm_helper.py _LTX_EXPECTED_VERSION what the runtime+ * must report+ * install.js a documentation block naming both+ * scripts/post_update.sh must delegate, never inline a checkout+ *+ * The pin is a TAG of the form vX.Y.Z+ltx25.N and the expected version is the+ * same string without the leading "v" — that is not a coincidence to be+ * tolerated, it is the property that makes the two checkable against each+ * other, so it is asserted.+ *+ * Run: node scripts/check_ltx_pin.js exit 0 = PASS+ */+const fs = require("fs")+const path = require("path")++const root = path.resolve(__dirname, "..")+const read = (p) => fs.readFileSync(path.join(root, p), "utf8")+const failures = []+const ok = (msg) => console.log(" ok " + msg)+const fail = (msg) => { failures.push(msg); console.log(" FAIL " + msg) }++// ---- 1. The truth ----------------------------------------------------------+const checkoutSrc = read("scripts/pinokio/ltx_checkout.sh")+const pinMatch = checkoutSrc.match(/^LTX_PIN="([^"]+)"$/m)+if (!pinMatch) {+ console.log("FAIL scripts/pinokio/ltx_checkout.sh has no `LTX_PIN=\"...\"` line")+ process.exit(1)+}+const PIN = pinMatch[1]+console.log(`vendored pin: ${PIN}`)++// ---- 2. It is a tag, not a SHA and not a branch ----------------------------+// A 40-hex SHA on a branch is not a pin: v3.8.x fetched `feat/ltx-2.5` and+// checked out a SHA the branch head had already moved past, so one upstream+// rebase would have stranded every install with an un-fetchable pin.+if (/^[0-9a-f]{7,40}$/.test(PIN)) {+ fail(`the pin is a bare SHA (${PIN}). It must be an immutable TAG — a SHA on a branch stops being fetchable after a rebase and takes every existing install's Update button with it.`)+} else if (!/^v\d+\.\d+\.\d+\+ltx25\.\d+$/.test(PIN)) {+ fail(`the pin "${PIN}" is not of the form vX.Y.Z+ltx25.N`)+} else {+ ok("the pin is a tag of the expected shape")+}++// ---- 3. _LTX_EXPECTED_VERSION agrees ---------------------------------------+const helperSrc = read("mlx_warm_helper.py")+const expMatch = helperSrc.match(/^_LTX_EXPECTED_VERSION\s*=\s*"([^"]+)"$/m)+if (!expMatch) {+ fail("mlx_warm_helper.py has no `_LTX_EXPECTED_VERSION = \"...\"` line")+} else if (expMatch[1] !== PIN.replace(/^v/, "")) {+ fail(`_LTX_EXPECTED_VERSION is "${expMatch[1]}" but the pin is "${PIN}" (expected "${PIN.replace(/^v/, "")}"). Move them together or the skew gate cries wolf forever.`)+} else {+ ok(`_LTX_EXPECTED_VERSION == "${expMatch[1]}"`)+}++// ---- 4. install.js documents the same pin, and executes none of it ----------+const installSrc = read("install.js")+if (!installSrc.includes(PIN)) {+ fail(`install.js does not mention the pin "${PIN}" — its comment block is the one a human reads before bumping.`)+} else {+ ok("install.js documents the pin")+}+if (!installSrc.includes("bash scripts/pinokio/ltx_checkout.sh")) {+ fail("install.js no longer delegates to scripts/pinokio/ltx_checkout.sh — the two lanes must share one checkout implementation.")+} else {+ ok("install.js delegates the checkout")+}++// ---- 5. Nobody else checks out the vendored tree ----------------------------+// A second copy of the checkout is a fix that half-lands; that is precisely how+// v3.8.1's guard had to be written twice.+for (const f of ["install.js", "update.js", "scripts/post_update.sh"]) {+ const src = read(f)+ if (/git\s+checkout\s+[0-9a-f]{7,40}/.test(src)) {+ fail(`${f} checks out a bare SHA directly — call scripts/pinokio/ltx_checkout.sh instead.`)+ }+}+if (!read("scripts/post_update.sh").includes("scripts/pinokio/ltx_checkout.sh")) {+ fail("scripts/post_update.sh does not call scripts/pinokio/ltx_checkout.sh")+} else {+ ok("post_update.sh delegates the checkout")+}++// ---- 6. update.js stays THIN -----------------------------------------------+// It is read BEFORE the pull, so anything it does itself can only be fixed one+// click late. See the header of `scripts/post_update.sh`.+const updateSrc = read("update.js")+const banned = [+ [/uv\s+pip\s+install/, "a uv/pip install"],+ [/\bpip\s+install/, "a pip install"],+ [/patch_\w+\.py/, "a patch script"],+ [/\bhf\s+download/, "a weight download"],+ [/fetch_pack_release\.py/, "a weight download"],+ [/\brm\s+-f\b/, "a model trim"],+]+let thin = true+for (const [re, what] of banned) {+ // Comments are allowed to DISCUSS these; only executable strings count.+ const code = updateSrc.split("\n").filter((l) => !/^\s*\/\//.test(l)).join("\n")+ if (re.test(code)) {+ fail(`update.js contains ${what}. It must stay thin: pull, then delegate to scripts/post_update.sh, which ships WITH the pull and can therefore be fixed by shipping.`)+ thin = false+ }+}+if (thin) ok("update.js is thin — no installs, patches, downloads or trims")++if (!/git pull --ff-only \|\|/.test(updateSrc)) {+ fail("update.js's ff-only pull is not the bare form. `git pull --ff-only $UPSTREAM` passes \"origin/main\" as the REPOSITORY argument and has never once succeeded — every update silently took the reset --hard fallback.")+} else {+ ok("the ff-only pull uses the bare form")+}++console.log("")+console.log(failures.length ? `RESULT: FAIL (${failures.length})` : "RESULT: PASS")+process.exit(failures.length ? 1 : 0)diff --git a/scripts/check_post_update.js b/scripts/check_post_update.jsnew file mode 100644index 0000000..c3dab60--- /dev/null+++ b/scripts/check_post_update.js@@ -0,0 +1,112 @@+#!/usr/bin/env node+/*+ * Gate: scripts/post_update.sh keeps the two properties that were paid for in+ * blood, and that collapsing 18 Pinokio steps into one shell script can silently+ * take away.+ *+ * ---------------------------------------------------------------------------+ * 1. ORDER — the codec patch runs before anything optional+ * ---------------------------------------------------------------------------+ * On v3.8.1 the patch sat eleven steps down, behind litellm / smolagents /+ * mflux / three weight fetches. The owner's Pinokio run ended at step 7 of 18+ * — exit code 0, no error, the update presented as finished — and the patch+ * never executed. Every render on that install encoded 4:2:0. v3.8.2 moved the+ * patch to run immediately after the reinstall that replaces site-packages and+ * enforced the ordering with a gate rather than a convention. This is that+ * gate, re-pointed at the file the work now lives in.+ *+ * It must ALSO stay after the package reinstall: that step overwrites+ * site-packages, so a patch applied before it is thrown away.+ *+ * ---------------------------------------------------------------------------+ * 2. FATALITY — a failed load-bearing step fails the Update+ * ---------------------------------------------------------------------------+ * Under Pinokio each of these was its own step, so a non-zero exit aborted the+ * run for free. Inside one script it does not, and the first draft of+ * post_update.sh lost it: patch_ltx_codec.py printed its CODEC PATCH FAILURE+ * banner and the update carried on and reported success — reinstating the exact+ * silent-4:2:0 outcome the banner exists to prevent. Found by the v4.0 journey+ * sim. The four load-bearing steps must go through `require`.+ *+ * Run: node scripts/check_post_update.js exit 0 = PASS+ */+const fs = require("fs")+const path = require("path")++const file = path.resolve(__dirname, "post_update.sh")+const lines = fs.readFileSync(file, "utf8").split("\n")++// Executable lines only — the rationale above each step names these commands.+const code = lines.map((l, i) => ({ n: i + 1, t: l }))+ .filter((l) => l.t.trim() && !l.t.trim().startsWith("#"))++const failures = []+const find = (re) => code.find((l) => re.test(l.t))+const at = (re, label) => {+ const hit = find(re)+ if (!hit) { failures.push(`no line matching ${label}`); return Infinity }+ return hit.n+}++const reinstall = at(/uv pip install .*--reinstall .*\.\/packages\/ltx-core-mlx/, "the vendored package reinstall")+const patch = at(/patch_ltx_codec\.py/, "the codec patch")+const optional = [+ ["mflux", /mflux==/],+ ["litellm", /litellm>=/],+ ["smolagents", /smolagents>=/],+ ["the mosaic upscaler fetch", /spatial_upscaler_x2_v1_1/],+ ["the LTX-2.5 weight fetch", /fetch_pack_release\.py/],+ ["the model trim", /^rm -f /],+]++console.log(`package reinstall : line ${reinstall}`)+console.log(`codec patch : line ${patch}`)++if (patch < reinstall) {+ failures.push(`the codec patch (line ${patch}) runs BEFORE the package reinstall (line ${reinstall}) — the reinstall overwrites site-packages, so the patch would be thrown away.`)+} else {+ console.log(" ok patch runs after the reinstall that replaces site-packages")+}++for (const [label, re] of optional) {+ const n = at(re, label)+ if (n < patch) {+ failures.push(`${label} (line ${n}) runs BEFORE the codec patch (line ${patch}). Everything optional must come after it.`)+ } else {+ console.log(` ok patch(${patch}) < ${label}(${n})`)+ }+}++// --- fatality ---------------------------------------------------------------+if (!/^require\(\)/m.test(lines.join("\n"))) {+ failures.push("post_update.sh defines no `require()` helper — load-bearing steps have no way to fail the Update.")+}+const mustRequire = [+ ["the vendored pin move", /ltx_checkout\.sh/],+ ["the mlx pin", /mlx==0\.31\.1/],+ ["the vendored package reinstall", /--reinstall .*\.\/packages\/ltx-core-mlx/],+ ["the codec patch", /patch_ltx_codec\.py/],+]+for (const [label, re] of mustRequire) {+ const hit = code.find((l) => re.test(l.t) && !/^\s*require\(\)/.test(l.t))+ if (!hit) { failures.push(`no executable line for ${label}`); continue }+ if (!/^require\s/.test(hit.t.trim())) {+ failures.push(`${label} (line ${hit.n}) is not wrapped in \`require\` — it would print its error and let the Update report success.`)+ } else {+ console.log(` ok ${label} is fatal on failure`)+ }+}++// --- and the optional ones must NOT be fatal --------------------------------+// An Update that a network hiccup can brick is worse than one that warns.+for (const [label, re] of [["the IC-LoRA fetches", /IC-LoRA-Colorizer/], ["the LTX-2.5 weight fetch", /fetch_pack_release\.py/]]) {+ const hit = code.find((l) => re.test(l.t))+ const guarded = hit && (/\|\|/.test(hit.t) || /\|\|/.test((code[code.indexOf(hit) + 1] || {}).t || ""))+ if (!guarded) failures.push(`${label} (line ${hit && hit.n}) is not guarded with \`|| echo WARN\` — an Update must not be brickable by a network hiccup.`)+ else console.log(` ok ${label} is best-effort`)+}++console.log("")+console.log(failures.length ? `RESULT: FAIL (${failures.length})` : "RESULT: PASS")+for (const f of failures) console.log("FAIL " + f)+process.exit(failures.length ? 1 : 0)diff --git a/scripts/convert_ltx_mlx.py b/scripts/convert_ltx_mlx.pyindex 23bab8c..9b3d38e 100644--- a/scripts/convert_ltx_mlx.py+++ b/scripts/convert_ltx_mlx.py@@ -227,6 +227,66 @@ DEFAULT_ROUTES: tuple[Route, ...] = ()+# ---------------------------------------------------------------------------+# The OTHER video VAE+#+# LTX-2.5 ships two video VAEs, and they differ only in the decoder half:+#+# ltx-2.5-video-vae-conv-bf16.safetensors 170 tensors, legacy conv decoder+# ltx-2.5-video-vae-bf16.safetensors 396 tensors, NA diffusion decoder+#+# Both carry the SAME conv encoder and the SAME per-channel statistics, and both+# spell their decoder ``decoder.*``. Routing the second one with the default table+# would therefore produce a ``vae_decoder.safetensors`` full of transformer weights+# under a filename the conv decoder loads — a shape error at best, and at worst a+# silently wrong pack. So the decoder half of a diffusion VAE file goes to its own+# stem, and the file is identified the way the vendor identifies it: by one key.+# ---------------------------------------------------------------------------++DIFFUSION_DECODER_STEM = "vae_decoder_diffusion"++#: ComfyUI's own detection rule (``comfy/sd.py`` at the LTX-2.5 merge): the presence+#: of this key is what selects ``CausalDiffusionVAE`` over the conv ``VideoVAE``.+DIFFUSION_DECODER_MARKER = "decoder.conv_in_x_t.weight"+++def is_diffusion_vae_header(header: dict) -> bool:+ return any(k == DIFFUSION_DECODER_MARKER or k.endswith("." + DIFFUSION_DECODER_MARKER) for k in header)+++def diffusion_vae_routes(routes: tuple[Route, ...]) -> tuple[Route, ...]:+ """Re-point every decoder-bound route in ``routes`` at the diffusion stem.++ The encoder routes are left exactly as they are: the encoder in this file is the+ same conv encoder the conv VAE file carries, so it converts to the same bytes and+ the pack ends up with one ``vae_encoder.safetensors`` either way.+ """+ swapped: list[Route] = []+ for route in routes:+ if route.stem != "vae_decoder":+ swapped.append(route)+ continue+ # The conv decoder is the whole component, so its keys sit at the file root+ # (``vae_decoder.conv_in.*``). The diffusion decoder is a *decoder inside a+ # VAE wrapper* that also owns the per-channel statistics, so its keys keep the+ # ``decoder.`` level the checkpoint spells. Matching the module tree here is+ # what lets the loader run ``strict=True`` with no rename table at all.+ if route.target_prefix == "vae_decoder.":+ target = f"{DIFFUSION_DECODER_STEM}.decoder."+ else:+ target = route.target_prefix.replace("vae_decoder.", f"{DIFFUSION_DECODER_STEM}.", 1)+ swapped.append(+ Route(+ source_prefix=route.source_prefix,+ stem=DIFFUSION_DECODER_STEM,+ target_prefix=target,+ rename=route.rename,+ leaf_map=route.leaf_map,+ )+ )+ return tuple(swapped)++# ---------------------------------------------------------------------------# Convolution layout#@@ -407,10 +467,15 @@ def plan_conversion(for key, value in metadata.items():merged_metadata.setdefault(key, value)+ # Per-file: the diffusion video VAE re-points its decoder half at its own+ # stem. Decided from the file's own header, not from a flag, so the two video+ # VAE files cannot be converted into each other's filename by mistake.+ file_routes = diffusion_vae_routes(routes) if is_diffusion_vae_header(header) else routes+for key, entry in header.items():if key == "__metadata__":continue- matches = route_key(key, routes)+ matches = route_key(key, file_routes)if not matches and forced_stem:# Verbatim: a file pinned by name has told us nothing about its# module structure, so applying the DiT's rename table would bediff --git a/scripts/pinokio/README.md b/scripts/pinokio/README.mdindex 1f2a6e4..d7b1e80 100644--- a/scripts/pinokio/README.md+++ b/scripts/pinokio/README.md@@ -70,3 +70,15 @@ Anything bigger belongs here, behind one short `bash …` line.arguments. Never inline a SHA in this directory.- `{{cwd}}` is substituted by Pinokio in the *message*, so anything path-shapedmust be passed in as an argument rather than written here.++## What is here++| file | dispatched by | what it does |+|---|---|---|+| `ltx_checkout.sh` | `install.js`, `scripts/post_update.sh` | the vendored engine pin move — the ONE implementation, and the pin literal itself (its header argues the exception to the rule above) |+| `ltx_venv.sh` | `install.js` | the venv build that dispatched 1,417 chars and hung Pinokio 8.0.x |+| `ltx25_weights.sh` | `install.js` | LTX-2.5 base + Gemma 4 encoder (27.47 GB), the default generation. Fatal on failure: a panel that boots into a generation with no weights cannot render |+| `q8_weights.sh` | `download_q8.js` | the optional LTX-2.5 Q8 pack (30.02 GB) — what trained characters and voices need. NOT the High add-on, which is a separate 29.5 GB click |+| `mflux_pack.sh` | `install_qwen.js` | the image-engine pack (Ideogram 4 + Qwen-Edit) |+| `h3_preflight.sh` | `install_h3.js` | Hailuo H3 disk/RAM preflight |+| `h3_build_q8.sh` | `install_h3.js` | the H3 q8 DiT build |diff --git a/scripts/pinokio/ltx25_weights.sh b/scripts/pinokio/ltx25_weights.shnew file mode 100644index 0000000..fc084ee--- /dev/null+++ b/scripts/pinokio/ltx25_weights.sh@@ -0,0 +1,41 @@+#!/usr/bin/env bash+# Download LTX-2.5 — the DEFAULT generation — and stop the install if it fails.+#+# Lifted out of install.js (748-char dispatch). See scripts/pinokio/README.md.+#+# cwd : the app root+#+# SEMANTICS: was a "\n"-joined string, i.e. one shell, no `set -e`, exit code+# from the last command — with one deliberate `exit 1`. Unchanged.+#+# WHY NOT `hf download`: the packs are mirrored as assets on a release of the+# public repo (the same lane the sample-character LoRA takes) because our HF+# token is read-only and these are our own quantisation of a gated upstream.+# Files over GitHub's 2 GiB asset cap are published as 1.9 GB shards;+# fetch_pack_release.py downloads them, checks each shard's sha256,+# reassembles, and only renames a file into place once the whole-file sha256+# matches the published manifest. Resumable and idempotent, so Resume Install+# re-runs it for the price of a read pass.+#+# BOTH PACKS ARE REQUIRED, not optional. 2.5 conditions on its own Gemma 4+# fine-tune and cannot use the Gemma 3 encoder — the mismatch does not raise,+# it silently encodes wrongly — so they are fetched together and the install+# STOPS if either fails rather than marching on to a panel that cannot render.++PY=./ltx-2-mlx/env/bin/python3.11+# `tae` rides along: 22 MB, and it is what makes the live preview work. It is+# a `kind: base` row, so an install without it reads INCOMPLETE — fetching it+# here is what keeps that true rather than aspirational.+if $PY scripts/fetch_pack_release.py --repo-key q4_25 --repo-key gemma4_25 --repo-key tae; then+ echo 'LTX-2.5 weights ready (verified against the published manifest).'+else+ echo '=================================================================='+ echo 'PHOSPHENE COULD NOT DOWNLOAD THE LTX-2.5 WEIGHTS'+ echo 'These are the default model - the panel cannot generate without them.'+ echo 'This is almost always a network problem (no connection, a VPN or'+ echo 'proxy, or GitHub blocked) or a full disk: the two packs need 28 GB.'+ echo 'Fix that, then click Install again - nothing already downloaded is'+ echo 'downloaded twice.'+ echo '=================================================================='+ exit 1+fidiff --git a/scripts/pinokio/ltx_checkout.sh b/scripts/pinokio/ltx_checkout.shnew file mode 100644index 0000000..4d0e3f7--- /dev/null+++ b/scripts/pinokio/ltx_checkout.sh@@ -0,0 +1,146 @@+#!/usr/bin/env bash+# The vendored ltx-2-mlx pin move — the ONE implementation, shared by both+# lanes. install.js dispatches `bash scripts/pinokio/ltx_checkout.sh`;+# scripts/post_update.sh calls the same file. Before v4.0 the two lanes carried+# byte-identical copies of this block and the hotfix note had to say so; a+# duplicated fix is a fix that half-lands.+#+# Semantics preserved from the inline payload: NO `set -e`. The original was a+# "\n"-joined string whose exit code was the last command's. Every step here is+# individually load-bearing and reports for itself; the final `git rev-parse`+# is what the caller sees.+#+# =============================================================================+# THE PIN — and why it lives HERE and not in update.js+# =============================================================================+# scripts/pinokio/README.md's house rule is "the pin SHA stays in the .js".+# That rule was written for the INSTALL lane, where the .js and the .sh are+# cloned together and the rule is about documentation locality. In the UPDATE+# lane it inverts, and the sequencing wins:+#+# Pinokio loads update.js from disk BEFORE our step 1 pulls the repo, so+# whatever update.js says is the version the user had, not the version they+# just downloaded. A pin held in update.js therefore moves ONE CLICK LATE,+# forever — the exact failure class the thin updater exists to kill+# (cocktailpeanut's own diagnosis; see `scripts/post_update.sh`).+#+# So the pin lives in the POST-PULL tree, in this file, and both lanes read it+# from here. `scripts/check_ltx_pin.js` is the gate that keeps install.js's+# documentation block and this value from drifting apart.+#+# =============================================================================+# IT IS A TAG, NOT A SHA, AND NOT A BRANCH+# =============================================================================+# v3.8.0 through v3.8.3 pinned a bare SHA obtained via `git fetch fork+# feat/ltx-2.5`. That worked only for as long as the SHA stayed reachable from+# that branch: the branch head had ALREADY moved past it by the time this was+# checked, and a single force-push or rebase would have stranded+# every existing install with an un-fetchable pin and a dead Update button.+# A tag is the only form of this reference that an upstream history rewrite+# cannot take away.+#+# `v0.14.19+ltx25.3` on mrbizarro/ltx-2-mlx == v0.14.19 plus:+# - the LTX-2.5 port (versioned DiT config, duration head, Euler-ancestral+# sampler, the vendored Gemma 4 text tower, encoder keyed off the checkpoint)+# - unfused runtime LoRAs (c78cc71..3259338)+# - the opt-in diffusion video-VAE decoder (a9c3f32..cc23423)+# - isolated-modality guidance OFF by default on the 2.5 HQ path (25b9b8e)+# - the distilled schedule: 2-step refine on 2.5, and a step count that THINS+# the checkpoint's own table rather than the caller's preset (dfee6cf,+# a252325 — without a252325 the panel's explicit stage2_steps=3 RAISES on+# every 2.5 distilled job)+# - live preview + early abort, opt-in and inert when unused+#+# The three packages declare `0.14.19+ltx25.3`, and `_LTX_EXPECTED_VERSION` in+# mlx_warm_helper.py must equal that string. Move the two together or the+# version-skew gate reports a permanent false alarm.+#+# To bump: retag on the fork, change LTX_PIN here, change the documented value+# in install.js, bump the three pyprojects AND _LTX_EXPECTED_VERSION, run+# `node scripts/check_ltx_pin.js`, smoke-test on dev, push.+LTX_PIN="v0.14.19+ltx25.3"+LTX_FORK_URL="https://github.com/mrbizarro/ltx-2-mlx.git"++ROOT="$(cd "$(dirname "$0")/../.." && pwd)"+cd "$ROOT/ltx-2-mlx" || { echo "FATAL: no vendored ltx-2-mlx tree at $ROOT/ltx-2-mlx"; exit 1; }++echo "vendored engine -> $LTX_PIN"++# Upstream's own tags, for `git describe`. Best-effort: the pin does not live+# here and dgrauet being unreachable must not stop an Update.+git fetch --tags origin || echo "WARN: could not reach origin for upstream tags (not fatal - the pin lives on the fork)"++# An existing install has only dgrauet as `origin`, so the fork remote is added+# when absent — and its URL is RESET every run. `get-url || add` alone can never+# correct a remote that is already there and wrong, which is a silent way to+# fetch from nowhere and then check out whatever local ref happens to share the+# pin's name. Found by the v4.0 journey sim doing exactly that.+git remote get-url fork > /dev/null 2>&1 || git remote add fork "$LTX_FORK_URL"+git remote set-url fork "$LTX_FORK_URL"++# EXPLICIT FORCED REFSPEC, not `git fetch --force fork tag <name>`. The `tag`+# shorthand does not honour --force, so a pin that was RE-tagged upstream (a+# corrected release, the ordinary reason to retag) leaves the stale local tag in+# place and the checkout below silently lands on the WRONG COMMIT while printing+# the right name. Also measured in the journey sim.+#+# And the fetch is FATAL. Without the pin fetched there is nothing correct to+# check out; carrying on would either fail obscurely or, worse, succeed against+# a stale local tag. An Update that stops here has changed nothing.+if ! git fetch fork "+refs/tags/$LTX_PIN:refs/tags/$LTX_PIN"; then+ echo "FATAL: could not fetch the vendored engine pin '$LTX_PIN' from $LTX_FORK_URL."+ echo " Nothing has been changed. Check your connection and re-run."+ exit 1+fi++# --- 3.8.1 HOTFIX: discard local edits BEFORE the pin move -------------------+#+# On 3.8.0 this checkout failed for real users with+# error: Your local changes to the following files would be overwritten by+# checkout: packages/ltx-core-mlx/src/ltx_core_mlx/model/video_vae/video_vae.py+# and no retry could clear it — nothing in the flow ever un-dirtied the file,+# so the Update button was dead for good.+#+# WHY AN INSTALL IS DIRTY AT ALL. ltx-2-mlx is a uv WORKSPACE. Installing its+# members WITH deps and WITHOUT --reinstall links them EDITABLE: site-packages+# gets `_editable_impl_ltx_core_mlx.pth`, not a copy. patch_ltx_codec.py then+# finds no ltx_core_mlx directory in site-packages and patches the GIT-TRACKED+# source. (v4.0's install.js adds a --reinstall --no-deps pass so a FRESH+# install no longer ends this way — but every install made before it did, and+# this guard is what carries them across.)+#+# WHY reset --hard AND NOT `git checkout -- <file>`. This tree is APP-MANAGED+# end to end: models live in ../mlx_models, build constraints in+# ../pip-build-constraints.txt, and the only non-tracked thing inside it on a+# real install is the ignored env/ venv — which reset --hard does not touch, so+# the multi-GB venv survives. A surgical per-file revert fixes today's filename+# and breaks on the next one. The class is "app-managed checkout carries local+# edits across a pin move".+#+# The `-f` guard exists because Pinokio does not hard-fail a shell.run whose+# `path` is missing; without it a stray shell could run reset --hard in the+# panel repo.+if [ -f packages/ltx-core-mlx/pyproject.toml ]; then+ echo 'vendored tree is app-managed; discarding local edits before the pin move:'+ git status --porcelain | head -20+ git reset --hard HEAD+else+ echo 'WARN: not the vendored ltx-2-mlx tree - skipping reset'+fi++if ! git checkout "$LTX_PIN"; then+ echo "FATAL: could not check out the vendored engine pin '$LTX_PIN'."+ exit 1+fi++# Say what landed, and PROVE it is what was asked for. The whole point of a tag+# over a branch SHA is that this assertion can exist; a checkout that reports+# success while HEAD sits somewhere else is the failure mode the forced refspec+# above was added to close, and an assertion costs nothing.+WANT="$(git rev-parse "$LTX_PIN^{commit}")"+GOT="$(git rev-parse HEAD)"+if [ "$WANT" != "$GOT" ]; then+ echo "FATAL: HEAD is $GOT but the pin '$LTX_PIN' is $WANT."+ exit 1+fi+echo "vendored engine at $LTX_PIN ($(git rev-parse --short HEAD))"diff --git a/scripts/pinokio/q8_weights.sh b/scripts/pinokio/q8_weights.shnew file mode 100644index 0000000..aa0f554--- /dev/null+++ b/scripts/pinokio/q8_weights.sh@@ -0,0 +1,46 @@+#!/usr/bin/env bash+# Download the LTX-2.5 Q8 weights — the optional pack trained characters and+# voices need. Dispatched by download_q8.js. See scripts/pinokio/README.md.+#+# cwd : the app root+#+# WHY THIS FILE EXISTS AT ALL, AND WHY THE COPY ALONE WAS NOT THE FIX.+# Through v3.8.3 this step ran `hf download dgrauet/ltx-2.3-mlx-q8` and its+# notify said "~37 GB". Both halves were 2.3 facts. v4.0 makes 2.5 the+# generation the panel serves, so correcting only the copy would have produced+# a button that says "LTX-2.5 Q8 weights (~30 GB)" and then downloads 2.3's+# 37 GB pack — a worse lie than the stale one, and exactly the class of drift+# this release keeps closing. The LANE moves with the words.+#+# WHY NOT `hf download`: the 2.5 packs are OUR quantisation of a gated upstream+# and our HF token is read-only, so they are mirrored as GitHub release assets,+# sharded at 1.9 GB because the asset cap is 2 GiB. fetch_pack_release.py+# downloads each shard, verifies its sha256, reassembles, and only renames a+# file into place once the whole-file hash matches the published manifest. It+# is resumable and idempotent: re-running it costs a read pass over what is+# already there, which is what makes "click it again" the correct advice.+#+# THE HIGH ADD-ON IS NOT FETCHED HERE, deliberately. hq_25 is a separate 29.5 GB+# download that lands INSIDE this pack's directory, and folding it in would hold+# a complete 30 GB pack hostage to a 60 GB wait. Q8 alone is what characters and+# voices need; High is one more click in Settings → Models.+#+# A USER PINNED BACK TO 2.3 (LTX_MODEL_VERSION=ltx23) should use Settings →+# Models, which offers every registered pack of every generation. This button is+# the one-click path for the generation the panel actually boots into.++PY=./ltx-2-mlx/env/bin/python3.11+if $PY scripts/fetch_pack_release.py --repo-key q8_25; then+ echo 'LTX-2.5 Q8 weights ready (verified against the published manifest).'+else+ echo '=================================================================='+ echo 'PHOSPHENE COULD NOT DOWNLOAD THE LTX-2.5 Q8 WEIGHTS'+ echo 'Nothing is broken - this pack is optional. The panel keeps rendering'+ echo 'on the base weights; trained characters and voices are what need Q8.'+ echo 'This is almost always a network problem (no connection, a VPN or'+ echo 'proxy, or GitHub blocked) or a full disk: the pack needs 30 GB.'+ echo 'Fix that and click again - nothing already downloaded is fetched'+ echo 'twice, and a part-finished pack resumes where it stopped.'+ echo '=================================================================='+ exit 1+fidiff --git a/scripts/post_update.sh b/scripts/post_update.shnew file mode 100644index 0000000..c712be1--- /dev/null+++ b/scripts/post_update.sh@@ -0,0 +1,231 @@+#!/usr/bin/env bash+# =============================================================================+# post_update.sh — everything an Update does AFTER the panel repo has moved.+# =============================================================================+#+# WHY THIS FILE EXISTS+# --------------------+# Pinokio loads `update.js` from disk into memory and THEN runs it. Our step 1+# is what pulls the repo, so the repo moves to the new version MID-RUN and+# execution continues from the STALE in-memory script. cocktailpeanut hit this+# on his own machine and confirmed the sequencing with timestamps+# by timestamp: the fix an app ships to its own+# installer always lands ONE CLICK LATE, and the user sees a failure they have+# already downloaded the fix for.+#+# So `update.js` is now THIN and STABLE — pull, then delegate here — and+# everything that can break lives in this file, which is read AFTER the pull+# and therefore always ships with the version it belongs to. A broken update+# step becomes fixable by shipping, the normal way. That kills the class for+# every future version.+#+# A SECOND PROPERTY, AND IT IS NOT INCIDENTAL+# -------------------------------------------+# v3.8.2's disaster was a Pinokio RUN that ended after a step which exited 0,+# because that step's stdout carried pip's "ERROR: pip's dependency resolver…"+# block. Steps 8-17 of 18 never ran — including the codec patch — and the+# update still presented as finished. Inside ONE shell script Pinokio sees ONE+# step, so no amount of scary text in the middle can silently drop the tail.+# The pip→uv conversion below stays anyway: two independent defences, because+# the failure mode is invisible.+#+# CONTRACT+# --------+# $1 the app root, optional. Defaults to this file's parent's parent, so the+# script is correct however Pinokio's cwd resolves — the v3.8.2 lesson+# from patch_ltx_codec.py, which guessed from CWD and reported "MISSING"+# on an install whose file was sitting right there.+#+# SEMANTICS — and the one thing collapsing 18 steps into 1 would have BROKEN+# ------------------------------------------------------------------------+# Under Pinokio each of these was its own step, so a non-zero exit aborted the+# run. Inside one script that is no longer automatic, and the first version of+# this file lost it: a `patch_ltx_codec.py` that failed its own verification+# printed its banner and the update carried on to report success — reinstating+# the exact silent-4:2:0 outcome v3.8.2 exists to prevent. Caught by the+# journey sim, on a synthetic pin whose upstream moved the ffmpeg line the+# patch anchors on.+#+# So failure semantics are now EXPLICIT rather than inherited:+#+# require <what> -- <cmd...> load-bearing. A non-zero exit prints a FATAL+# banner naming the step and exits, so Pinokio+# marks the Update failed. Steps 1-4.+# plain invocation best-effort, guarded with `|| echo WARN`. An+# Update must never be brickable by a network+# hiccup, and every one of these has a one-click+# retry in the panel. Steps 5-9.+#+# That is stricter than what shipped (where the boundary was implicit in the+# step split) and it is deliberate: the difference between "this update did+# nothing" and "this update quietly broke your renders" is exactly this line.+# =============================================================================++ROOT="${1:-$(cd "$(dirname "$0")/.." && pwd)}"+cd "$ROOT" || { echo "FATAL: cannot enter app root $ROOT"; exit 1; }++require() {+ local what="$1"; shift+ [ "$1" = "--" ] && shift+ if ! "$@"; then+ echo ""+ echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"+ echo "!! PHOSPHENE UPDATE FAILED: $what"+ echo "!! This step is not optional — stopping here rather than reporting a"+ echo "!! successful update that did not happen. Nothing has been deleted."+ echo "!! Re-run Update; if it fails the same way, the message above it is"+ echo "!! the one to report."+ echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"+ exit 1+ fi+}++PY="$ROOT/ltx-2-mlx/env/bin/python3.11"+VENV_PY="$ROOT/ltx-2-mlx/env/bin/python"+HF="$ROOT/ltx-2-mlx/env/bin/hf"+export HF_HUB_ENABLE_HF_TRANSFER=1++echo "=== Phosphene post-update — app root: $ROOT ==="++# ---- 1. The vendored engine pin --------------------------------------------+# One implementation, shared with install.js. Carries the 3.8.1 hotfix+# (reset --hard before the checkout) and the v4.0 move from a branch SHA to an+# immutable tag. The pin literal lives in that file, deliberately: see its+# header for why a pin held in update.js can only ever move one click late.+require "the vendored engine pin move" -- bash "$ROOT/scripts/pinokio/ltx_checkout.sh"++# ---- 2. mlx pin -------------------------------------------------------------+# mlx 0.31.2 attenuates the vocoder by ~22 dB (measured: max_volume -42.8 dB vs+# -9.2 dB on 0.31.1, same weights, same seed). --reinstall --no-deps so ONLY+# mlx moves and nothing that depends on it is re-resolved.+require "the mlx 0.31.1 pin" -- uv pip install --python "$VENV_PY" --reinstall --no-deps 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1'++# ---- 3. Re-install the three vendored packages ------------------------------+# This is what actually moves an existing user's RUNTIME: a bare git checkout+# leaves the previous copy in site-packages. `--reinstall` also replaces the+# EDITABLE .pth links a pre-v4.0 install ended up with, which is what leaves+# the vendored tree clean for the next pin move.+#+# `--build-constraints` pins the build backend to hatchling<1.32. All three+# pyprojects declare `readme = "../../README.md"` — outside the package dir —+# which hatchling 1.32.0 made a hard error, so from the day it shipped every+# install and every Update died here on every pinned tag. uv, not pip: modern+# pip drops inherited constraints inside the isolated build env on purpose+# (`_PIP_IN_BUILD_IGNORE_CONSTRAINTS=1`), and its `--build-constraint` flag+# does not exist on the older pips this fleet was seeded with.+require "re-installing the three vendored packages" -- bash -c 'cd "$1/ltx-2-mlx" && uv pip install --python env/bin/python --reinstall --no-deps --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer' _ "$ROOT"++# ---- 4. The codec patch — IMMEDIATELY after the reinstall -------------------+# It MUST be here: step 3 overwrites site-packages, so a patch applied before+# it is thrown away, and everything below is optional and could once have ended+# the run. On v3.8.1 this sat eleven steps down and never executed on the+# owner's machine — every render on that install encoded 4:2:0 with no error+# anywhere. patch_ltx_codec.py now resolves the target through the INTERPRETER+# (importlib.util.find_spec), not the filesystem, and verifies its own work,+# exiting non-zero behind a banner if the file it was supposed to change did+# not change.+require "the codec patch (without it every render encodes 4:2:0 - blocky faces)" -- "$PY" "$ROOT/patch_ltx_codec.py"++# ---- 5. Trainer transitive deps ---------------------------------------------+# ltx-trainer went in with --no-deps above, so pyyaml/pydantic/tqdm/rich were+# never resolved; the trainer subprocess dies at `import yaml` without them.+( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python 'pyyaml>=6.0' 'pydantic>=2.0' 'tqdm>=4.65' 'rich>=13.0' )++# ---- 6. Optional runtime packages -------------------------------------------+# mlx-vlm --no-deps on purpose (its default deps fight our mflux/transformers/+# mlx pins; the panel imports it lazily). hf_transfer is HuggingFace's Rust+# accelerator — 5-10x on the big packs. certifi is load-bearing: start.js+# points SSL_CERT_FILE at its cacert.pem, and if it ever goes missing ALL panel+# stdlib HTTPS breaks. litellm is the agent's multi-provider chat client,+# floored at 1.83.14 because earlier 1.x was hit by the March 2026 PyPI+# supply-chain incident. smolagents needs uv rather than pip: it hard-pins+# huggingface-hub<1.0.0, which pip refuses to resolve against our >=1.5.0 floor+# (ResolutionImpossible — the "blue screen error flashing for a second every+# update"), while uv installs both and leaves it warned-but-functional.+( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python --no-deps 'mlx-vlm==0.4.4' )+uv pip install --python "$VENV_PY" --upgrade 'hf_transfer>=0.1.6'+uv pip install --python "$VENV_PY" --upgrade certifi+uv pip install --python "$VENV_PY" --upgrade 'litellm>=1.83.14'+uv pip install --python "$VENV_PY" --upgrade 'huggingface-hub>=1.5.0,<2.0' 'smolagents>=1.24.0'++# ---- 7. The mflux image-engine pack (Ideogram 4 + Qwen-Edit) ----------------+# STANDARD since 2026-06-13, for every user — this is what unblocked Ideogram 4+# for everyone who never ran the optional installer. Two-step (with deps, then+# --reinstall --no-deps) mirrors install_qwen.js so the full transitive set+# resolves and then the version locks. BEST-EFFORT: video is unaffected if it+# fails, and the panel offers a one-click reinstall.+echo 'Installing/refreshing the mflux image-engine pack (Ideogram 4 + Qwen-Edit)…'+( uv pip install --python "$VENV_PY" 'mflux==0.18.0' \+ && uv pip install --python "$VENV_PY" --reinstall --no-deps 'mflux==0.18.0' \+ && uv pip install --python "$VENV_PY" 'mlx-teacache==0.4.1' ) \+ || echo 'WARN: mflux image-engine install hit an error — video is unaffected; re-run Update, or use the Reinstall image engines action, to retry.'++# The FBCache patch has to follow the step that installs what it patches.+# Idempotent — skips when its marker is present.+"$PY" "$ROOT/patch_mflux_fbcache.py"++# ---- 8. Weight self-heal ----------------------------------------------------+# Every fetch here is BEST-EFFORT. An Update must not be brickable, and each of+# these has a one-click retry in the panel (Models page / Repair).++# The Q4 spatial upscaler — the mosaic fix (#23). The Y1.024 download allowlist+# dropped it, so affected Q4 installs ran a RANDOMLY-INITIALISED upsampler and+# produced the rainbow-grid garbage. ~1 GB, resumable, skipped when present.+# ONLY for an install that already HAS the 2.3 pack. From v4.0 a fresh install+# fetches 2.5 only and LTX-2.3 is an in-panel offer, so running this+# unconditionally would create a 2.3 directory holding exactly one 1 GB file —+# which the Models modal would then report "partial" and Storage would offer to+# reclaim. A self-heal must not conjure the thing it heals.+if [ -d "$ROOT/mlx_models/ltx-2.3-mlx-q4" ]; then+ echo 'Ensuring the Q4 spatial upscaler is present (mosaic fix)…'+ "$HF" download dgrauet/ltx-2.3-mlx-q4 --local-dir "$ROOT/mlx_models/ltx-2.3-mlx-q4" --include 'spatial_upscaler_x2_v1_1.safetensors' \+ || echo 'WARN: spatial upscaler fetch failed — open the panel and click Repair to retry (fixes the mosaic).'+else+ echo 'LTX-2.3 is not installed — skipping its spatial-upscaler self-heal (install it from Settings → Models if you want to train a character).'+fi++# LTX-2.5, the DEFAULT generation (~28 GB). Anyone who installed before+# 2026-08-12 has 2.3 weights only, and 2.5 is what the panel boots into — so+# without this an Update leaves them on a default lane with nothing behind it.+# Mirrored as GitHub release assets (our own quantisation of a gated upstream,+# read-only HF token), hence the fetcher rather than `hf download`. It verifies+# what it already has, so the steady state is a read pass.+echo 'Ensuring the LTX-2.5 weights are present (default generation)…'+"$PY" "$ROOT/scripts/fetch_pack_release.py" --repo-key q4_25 --repo-key gemma4_25 --repo-key tae \+ || echo 'WARN: LTX-2.5 weight fetch failed — open the panel, go to Models, and click Download for the LTX 2.5 rows to retry. It resumes.'++# The three IC-LoRAs the optional modes need. Colorize + Control are un-gated+# originals; Ingredients comes from DeepBeepMeep/LTX-2, which mirrors the+# BYTE-IDENTICAL gated file un-gated — and --include is CRITICAL there because+# that repo is ~708 GB.+echo 'Ensuring the Colorize IC-LoRA is present (restore mode, optional)…'+"$HF" download DoctorDiffusion/LTX-2.3-IC-LoRA-Colorizer --local-dir "$ROOT/mlx_models/loras/ic" --include 'LTX-2.3-22b-IC-LoRA-Colorizer-0.9.safetensors' \+ || echo 'WARN: Colorize IC-LoRA fetch failed — the Colorize mode will fetch it on first use, or click Repair.'++echo 'Ensuring the Ingredients IC-LoRA is present (multi-reference mode, optional)…'+"$HF" download DeepBeepMeep/LTX-2 --local-dir "$ROOT/mlx_models/loras/ic" --include 'ltx-2.3-22b-ic-lora-ingredients-0.9.safetensors' \+ || echo 'WARN: Ingredients IC-LoRA fetch failed — the Ingredients mode will fetch it on first use, or click Repair.'++echo 'Ensuring the Control IC-LoRA is present (Union, control mode, optional)…'+"$HF" download Lightricks/LTX-2.3-22b-IC-LoRA-Union-Control --local-dir "$ROOT/mlx_models/loras/ic" --include 'ltx-2.3-22b-ic-lora-union-control-ref0.5.safetensors' \+ || echo 'WARN: Control IC-LoRA fetch failed — the Control mode will fetch it on first use, or click Repair.'++# ---- 9. Trim variants we never load ----------------------------------------+# Pre-Y1.024 installs downloaded whole repos (Q4 56 GB instead of 20, Q8 82 GB+# instead of 37). `rm -f` is a no-op when the file is already gone.+# NOT trimmed, deliberately: ltx-2.3-mlx-q4/transformer-dev.safetensors — Train+# Character downloads that 11 GB file on demand, and removing it here would+# silently undo the training install on every update.+echo 'Trimming unused model variants from mlx_models/…'+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q4/transformer-distilled-1.1.safetensors"+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q4/ltx-2.3-22b-distilled-lora-384-1.1.safetensors"+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q4/spatial_upscaler_x1_5_v1_0.safetensors"+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q4/temporal_upscaler_x2_v1_0.safetensors"+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q8/transformer-distilled.safetensors"+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q8/transformer-distilled-1.1.safetensors"+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q8/ltx-2.3-22b-distilled-lora-384-1.1.safetensors"+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q8/spatial_upscaler_x1_5_v1_0.safetensors"+rm -f "$ROOT/mlx_models/ltx-2.3-mlx-q8/temporal_upscaler_x2_v1_0.safetensors"+echo 'Trim done.'++echo "=== post-update complete ==="diff --git a/scripts/publish_pack_release.py b/scripts/publish_pack_release.pyindex b63c4a2..4199692 100644--- a/scripts/publish_pack_release.py+++ b/scripts/publish_pack_release.py@@ -79,6 +79,18 @@ SCHEMA = "phosphene-release-manifest/1"SHARD_BYTES = 1_900_000_000CHUNK = 1 << 22+# Resume skips an asset whose byte count already matches, which is the only+# thing GitHub's asset API can tell us -- it publishes no checksum. That leaves+# one hole: a file whose CONTENT changed but whose size did not. It is not+# hypothetical for the small ones -- `phosphene_quant_manifest.json` was+# rewritten by a second agent between one publish and the next -- so anything+# at or under this size is always re-uploaded. `--clobber` makes that a no-op+# when the bytes really are the same, and at these sizes it costs nothing.+# Big shards keep the size-based skip; a shard that changed content without+# changing size would still be caught loudly, by the sha256 in the manifest+# failing on the fetcher's side rather than silently installing.+ALWAYS_REUPLOAD_MAX_BYTES = 16 << 20+LICENSE_ASSET = "LICENSE-LTX-2.x-Community-License.md"NOTICE_ASSET = "NOTICE.md"@@ -98,30 +110,74 @@ def utc_now() -> str:# --------------------------------------------------------------------------- ## Registry + pack contents# --------------------------------------------------------------------------- #+def load_registry(root: Path) -> dict:+ return json.loads((root / REQUIRED_FILES).read_text())++def load_repo_entry(repo_key: str, root: Path) -> dict:- data = json.loads((root / REQUIRED_FILES).read_text())- for repo in data.get("repos", []):+ for repo in load_registry(root).get("repos", []):if repo.get("key") == repo_key:return reporaise SystemExit(f"unknown repo key {repo_key!r}")-def pack_files(pack_dir: Path) -> list[str]:- """Every regular file in the pack, sorted -- the pack *as built*.+def files_owned_elsewhere(repo: dict, registry: dict) -> set[str]:+ """Files in this pack's DIRECTORY that belong to a different download unit.++ Two registry entries can share one ``local_dir`` on purpose: the LTX-2.5 HQ+ add-on (``hq_25``) is a separate, later build whose files are loaded out of+ the q8 pack BY NAME, so they have to land beside it. That makes "the+ directory" the wrong definition of "the pack" -- publishing it would put the+ 29 GB add-on inside the q8 manifest and force every q8 install to download+ weights it did not ask for, which is exactly the coupling the split removed.++ Caught the hard way: the add-on landed in the q8 directory mid-publish and+ the q8 run started uploading it under a ``q8_25__`` prefix.+ """+ mine = repo.get("key")+ here = repo.get("local_dir")+ owned: set[str] = set()+ for other in registry.get("repos", []):+ if other.get("key") == mine or other.get("local_dir") != here:+ continue+ owned.update(other.get("files") or [])+ return owned+++def pack_files(pack_dir: Path, repo: dict, registry: dict) -> list[str]:+ """The files of THIS download unit, sorted.Not just ``required_files.json``'s mandatory list: the loader also readssidecar JSON (``split_model.json``, the upscaler configs, the quantiser'sown manifest) that the mandatory list deliberately does not enumerate, andthe ``download_include`` allowlist pulls with ``*.json`` for exactly that- reason. Publishing the directory keeps the mirror a faithful copy.+ reason. So it is the directory -- minus anything another entry owns."""- out = []+ # An ADD-ON declares `publish_scope: "files"`: it owns exactly the files it+ # lists and nothing else. Directory-minus-foreign is the right rule for the+ # pack that owns the directory (it has to pick up sidecar JSON nobody+ # enumerates), and the wrong one for a guest -- a guest would sweep up its+ # host's sidecars and claim them in its own manifest.+ if repo.get("publish_scope") == "files":+ declared = list(repo.get("files") or [])+ log(f"[publish] {repo.get('key')} is an add-on: publishing exactly its "+ f"{len(declared)} declared file(s), not the directory")+ return sorted(declared)++ foreign = files_owned_elsewhere(repo, registry)+ out, skipped = [], []for p in sorted(pack_dir.iterdir()):if not p.is_file() or p.name.startswith("."):continueif p.name in SKIP_NAMES or p.name.endswith(SKIP_SUFFIXES):continue+ if p.name in foreign:+ skipped.append(p.name)+ continueout.append(p.name)+ if skipped:+ log(f"[publish] excluding {len(skipped)} file(s) owned by another download "+ f"unit in the same directory: {', '.join(skipped)}")return out@@ -212,7 +268,7 @@ def publish_file(src: Path, prefix: str, staging: Path, *, release_repo: str,name = asset_name(prefix, src.name, None)digest = sha256_file(src)shards.append({"asset": name, "bytes": size, "sha256": digest})- if upload and existing.get(name) != size:+ if upload and (existing.get(name) != size or size <= ALWAYS_REUPLOAD_MAX_BYTES):link = staging / namelink.unlink(missing_ok=True)try:@@ -330,7 +386,7 @@ def publish(repo_key: str, root: Path, *, tag: str | None, release_repo: str | Nstaging = staging_root / mirror["tag"]staging.mkdir(parents=True, exist_ok=True)- names = pack_files(pack_dir)+ names = pack_files(pack_dir, repo, load_registry(root))total = sum((pack_dir / n).stat().st_size for n in names)log(f"[publish] {repo_key}: {len(names)} file(s), {total / 1e9:.2f} GB from {pack_dir}")@@ -379,7 +435,7 @@ def publish(repo_key: str, root: Path, *, tag: str | None, release_repo: str | Ndigest = sha256_file(src)files[asset] = {"bytes": size, "sha256": digest,"shards": [{"asset": asset, "bytes": size, "sha256": digest}]}- if upload and existing.get(asset) != size:+ if upload and (existing.get(asset) != size or size <= ALWAYS_REUPLOAD_MAX_BYTES):staged = staging / assetstaged.unlink(missing_ok=True)shutil.copy2(src, staged)diff --git a/scripts/test_analytics_dryrun.py b/scripts/test_analytics_dryrun.pyindex d325a3d..e88287e 100644--- a/scripts/test_analytics_dryrun.py+++ b/scripts/test_analytics_dryrun.py@@ -474,12 +474,15 @@ class TestEventSchemas(AnalyticsTestCase):p = self.props_of("app_boot")self.assertEqual(set(p), {"version", "os_version", "chip_family", "ram_gb", "cap_tier",- "packs", "h3_chain_supported"})+ "model_version", "packs", "h3_chain_supported"})self.assertEqual(set(p["packs"]), {"h3", "sharp", "q8", "qwen"})for v in p["packs"].values():self.assertIsInstance(v, bool)self.assertIsInstance(p["ram_gb"], int)self.assertIn(p["cap_tier"], ("q4", "q8"))+ # A NEW field, not a redefinition of cap_tier: the capability+ # series has to stay comparable across the 2.5 cutover.+ self.assertIn(p["model_version"], ("ltx23", "ltx25"))# os_version is major.minor only — no patch level.self.assertLessEqual(len(p["os_version"].split(".")), 2)diff --git a/scripts/test_convert_ltx_mlx.py b/scripts/test_convert_ltx_mlx.pyindex 7140ded..35146e4 100644--- a/scripts/test_convert_ltx_mlx.py+++ b/scripts/test_convert_ltx_mlx.py@@ -584,3 +584,86 @@ class TestConvLayout:write_component(plans["vae_encoder"], tmp_path / "out")header, _ = read_header(tmp_path / "out" / "vae_encoder.safetensors")assert header["vae_encoder.conv_in.conv.weight"]["shape"] == [4, 3, 3, 3, 2]+++class TestDiffusionVideoVAE:+ """LTX-2.5 ships two video VAEs whose decoders share the ``decoder.`` prefix.++ Routing the diffusion one with the default table would write transformer+ weights into ``vae_decoder.safetensors`` — the filename the conv decoder+ loads. These pin that the file's own header decides, the way ComfyUI decides.+ """++ def diffusion_tensors(self) -> dict:+ return {+ # The marker key, and enough of the module tree to show the shape.+ "decoder.conv_in.weight": ("BF16", [8, 4], bf16(32)),+ "decoder.conv_in_x_t.weight": ("BF16", [8, 12], bf16(96)),+ "decoder.det_stages.0.0.attn.qkv.weight": ("BF16", [24, 8], bf16(192)),+ "decoder.diff_blocks.0.scale_shift_table": ("BF16", [7, 8], bf16(56)),+ "decoder.type_emb": ("BF16", [4], bf16(4)),+ "encoder.conv_in.conv.weight": ("BF16", [4, 2, 3, 3, 3], bf16(4 * 2 * 27)),+ "per_channel_statistics.mean-of-means": ("F32", [4], b"\0" * 16),+ "per_channel_statistics.std-of-means": ("F32", [4], b"\0" * 16),+ }++ def conv_tensors(self) -> dict:+ return {+ "decoder.conv_in.conv.weight": ("BF16", [8, 4, 3, 3, 3], bf16(8 * 4 * 27)),+ "per_channel_statistics.mean-of-means": ("F32", [4], b"\0" * 16),+ "per_channel_statistics.std-of-means": ("F32", [4], b"\0" * 16),+ }++ def test_the_marker_key_alone_re_points_the_decoder(self, tmp_path):+ src = write_safetensors(tmp_path / "diff_vae.safetensors", self.diffusion_tensors())+ plans, unmapped, _ = plan_conversion([src])+ assert unmapped == []+ assert "vae_decoder" not in plans, "diffusion decoder must not claim the conv decoder's filename"+ assert set(plans) == {"vae_decoder_diffusion", "vae_encoder"}++ def test_decoder_keys_keep_the_decoder_level_the_module_tree_has(self, tmp_path):+ src = write_safetensors(tmp_path / "diff_vae.safetensors", self.diffusion_tensors())+ plans, _, _ = plan_conversion([src])+ keys = {t.target_key for t in plans["vae_decoder_diffusion"].tensors}+ assert "vae_decoder_diffusion.decoder.conv_in.weight" in keys+ assert "vae_decoder_diffusion.decoder.conv_in_x_t.weight" in keys+ # The wrapper owns the statistics, so those sit one level up.+ assert "vae_decoder_diffusion.per_channel_statistics.mean" in keys+ assert "vae_decoder_diffusion.per_channel_statistics.std" in keys++ def test_type_emb_is_routed_not_dropped(self, tmp_path):+ """Neither reference implementation reads ``decoder.type_emb``; ComfyUI loads+ non-strictly and drops it silently. Carrying it is what lets our loader stay+ strict — and a dropped tensor is the failure mode this converter exists to+ prevent."""+ src = write_safetensors(tmp_path / "diff_vae.safetensors", self.diffusion_tensors())+ plans, unmapped, _ = plan_conversion([src])+ assert unmapped == []+ keys = {t.target_key for t in plans["vae_decoder_diffusion"].tensors}+ assert "vae_decoder_diffusion.decoder.type_emb" in keys++ def test_the_conv_video_vae_is_untouched_by_any_of_this(self, tmp_path):+ src = write_safetensors(tmp_path / "conv_vae.safetensors", self.conv_tensors())+ plans, unmapped, _ = plan_conversion([src])+ assert unmapped == []+ # The statistics fan out to the encoder too, as they always have.+ assert set(plans) == {"vae_decoder", "vae_encoder"}+ keys = {t.target_key for t in plans["vae_decoder"].tensors}+ assert "vae_decoder.conv_in.conv.weight" in keys+ assert "vae_decoder.per_channel_statistics.mean" in keys++ def test_both_video_vaes_in_one_run_do_not_collide(self, tmp_path):+ """They carry the same encoder and the same statistics; only the decoders+ differ. One pass over both must yield three components, not a conflict."""+ a = write_safetensors(tmp_path / "diff_vae.safetensors", self.diffusion_tensors())+ b = write_safetensors(tmp_path / "conv_vae.safetensors", self.conv_tensors())+ plans, unmapped, _ = plan_conversion([a, b])+ assert unmapped == []+ assert set(plans) == {"vae_decoder_diffusion", "vae_decoder", "vae_encoder"}++ def test_the_decoder_carries_no_conv_and_so_no_permutation(self, tmp_path):+ """Every tensor in this decoder is rank 1 or 2 — it is Linear all the way+ down. If a permutation ever fires here, something is misrouted."""+ src = write_safetensors(tmp_path / "diff_vae.safetensors", self.diffusion_tensors())+ plans, _, _ = plan_conversion([src])+ assert all(t.permute == () for t in plans["vae_decoder_diffusion"].tensors)diff --git a/scripts/test_pack_release.py b/scripts/test_pack_release.pyindex 48cfe42..def5fc0 100644--- a/scripts/test_pack_release.py+++ b/scripts/test_pack_release.py@@ -30,6 +30,7 @@ from __future__ import annotationsimport hashlibimport json+import reimport osimport shutilimport sys@@ -301,10 +302,16 @@ def test_the_shipped_registry_mirrors_are_well_formed():root = Path(__file__).resolve().parents[1]reg = json.loads((root / "required_files.json").read_text())mirrored = [r for r in reg["repos"] if r.get("mirror")]- # A release may legitimately ship no mirrored pack — v3.8.0 does, because- # the 2.5 packs are curated out until their mirror is published. What must- # never happen is a mirror block the fetcher cannot act on, so this asserts- # the SHAPE of whatever is declared rather than that something is.+ # This asserted `mirrored` was non-empty. A tree may legitimately declare+ # no mirrored pack — public v3.8.0 does, because the 2.5 entries are+ # curated out of a release until their mirror is published, and the 2.3+ # lane comes from HuggingFace. The assertion turned that correct state+ # into a red test. What must never happen is a mirror block the fetcher+ # cannot act on, so this asserts the SHAPE of whatever is declared rather+ # than that something is. (dev declares three today: q4_25, q8_25,+ # gemma4_25 — and `test_a_pack_with_no_mirror_yet_is_not_advertised_as_+ # fetchable` is what guards the other direction, a pack whose files exist+ # with no lane behind them.)for repo in mirrored:m = repo["mirror"]assert m["kind"] == "github-release"@@ -315,5 +322,118 @@ def test_the_shipped_registry_mirrors_are_well_formed():assert repo.get("files"), f"{repo['key']} declares no required files"+def _registry():+ root = Path(__file__).resolve().parents[1]+ return root, json.loads((root / "required_files.json").read_text())+++def test_the_hq_addon_is_its_own_download_unit_in_the_q8_directory():+ """The split: q8_25 is the pack, hq_25 is the two files loaded out of it.++ They share a directory on purpose -- the HQ weights are loaded from the q8+ pack BY NAME -- but they are separate download units, because they are+ separate builds and a unit has to be publishable the moment its bytes+ exist. Folding them together held a complete 20.6 GB pack hostage to a+ 42 GB download.+ """+ _, reg = _registry()+ q8 = next(r for r in reg["repos"] if r["key"] == "q8_25")+ hq = next(r for r in reg["repos"] if r["key"] == "hq_25")+ assert hq["local_dir"] == q8["local_dir"], "the add-on must land in the q8 pack"+ overlap = set(q8["files"]) & set(hq["files"])+ assert not overlap, f"a file must belong to exactly one download unit: {overlap}"+ for f in ("transformer-dev.safetensors", "ltx-2.5-22b-distilled-lora-450.safetensors"):+ assert f in hq["files"], f+ assert f not in q8["files"], f"{f} must not hold the q8 pack hostage"+++def test_the_addon_file_names_match_the_names_the_loader_asks_for():+ """The drift that would be invisible until a render.++ `hq_weights` in mlx_ltx_panel.py names the two files the pipeline loads;+ required_files.json names the two files the installer fetches. Rename one+ and not the other and the download succeeds, the pack reports complete, and+ High fails at load time with a file that was never asked for. Read out of+ the panel SOURCE rather than by importing it, the way the analytics+ coverage guard does.+ """+ root, reg = _registry()+ src = (root / "mlx_ltx_panel.py").read_text()+ block = re.search(r'"config_key":\s*"ltx-2\.5".*?"hq_weights":\s*\{(.*?)\}', src, re.S)+ assert block, "could not find the 2.5 hq_weights block"+ declared = set(re.findall(r'"([^"]+\.safetensors)"', block.group(1)))+ assert declared, "2.5 declares no hq_weights"+ hq = next(r for r in reg["repos"] if r["key"] == "hq_25")+ assert declared == set(hq["files"]), (+ f"panel loads {sorted(declared)}, installer fetches {sorted(hq['files'])}")+++def test_an_addon_publishes_only_its_own_files_not_its_hosts_directory(tmp_path, monkeypatch):+ """Two entries, one directory -- the guest must not claim the host's files.++ Caught in production, mid-publish: the HQ add-on's weights landed in the q8+ pack directory and the q8 run, which publishes "the directory", started+ uploading 29 GB of add-on under a `q8_25__` prefix. That would have put the+ add-on inside the q8 manifest and forced every q8 install to download+ weights it did not ask for -- the exact coupling the split removed.++ Both directions are asserted: the host excludes the guest's declared files,+ and the guest (`publish_scope: "files"`) publishes ONLY what it declares, so+ it cannot sweep up the sidecar JSON the host owns.+ """+ root = tmp_path / "app"+ root.mkdir()+ pack = _write_pack(root)+ (pack / "addon.safetensors").write_bytes(b"\xAA" * 300)+ reg = json.loads((root / "required_files.json").read_text())+ host = reg["repos"][0]+ reg["repos"].append({+ "key": "addon", "kind": "optional", "name": "Add-on",+ "repo_id": "nobody/addon", "local_dir": host["local_dir"],+ "size_gb": 1, "publish_scope": "files",+ "files": ["addon.safetensors"],+ "mirror": dict(host["mirror"],+ manifest_asset="addon__phosphene_release_manifest.json"),+ })+ (root / "required_files.json").write_text(json.dumps(reg))+ registry = publisher.load_registry(root)++ host_files = publisher.pack_files(pack, host, registry)+ assert "addon.safetensors" not in host_files, "the host published the guest's file"+ assert "config.json" in host_files, "the host must still pick up its own sidecars"++ guest = next(r for r in registry["repos"] if r["key"] == "addon")+ guest_files = publisher.pack_files(pack, guest, registry)+ assert guest_files == ["addon.safetensors"], guest_files+ assert "config.json" not in guest_files, "the guest claimed its host's sidecar"+++def test_small_assets_are_always_reuploaded_even_when_the_size_matches():+ """GitHub publishes no checksum for an asset, so resume can only compare+ size -- and a file whose content changed without its size changing would be+ skipped. Not hypothetical: the in-pack quant manifest was rewritten by+ another agent between two publishes. Anything small is re-uploaded rather+ than trusted."""+ assert publisher.ALWAYS_REUPLOAD_MAX_BYTES >= (1 << 20), "too small to cover sidecars"+ assert publisher.ALWAYS_REUPLOAD_MAX_BYTES < publisher.SHARD_BYTES, "would defeat resume"+++def test_a_pack_with_no_mirror_yet_is_not_advertised_as_fetchable():+ """hq_25 must not claim a mirror until its assets are published.++ A file in files[] with no download lane behind it is the June-2026 failure+ verbatim: the pack reports incomplete on arrival and nothing can fix it.+ When the dev build lands, the mirror block and the assets go live in the+ SAME commit -- so this test is expected to be UPDATED then, not deleted.+ """+ root, reg = _registry()+ hq = next(r for r in reg["repos"] if r["key"] == "hq_25")+ on_disk = all((root / hq["local_dir"] / f).exists() for f in hq["files"])+ if hq.get("mirror"):+ assert on_disk, "a mirror block was added before the files existed"+ else:+ assert not on_disk, "the files exist -- publish them and add the mirror block"++if __name__ == "__main__":sys.exit(pytest.main([__file__, "-q"]))diff --git a/storyboard.py b/storyboard.pyindex 97b6441..77ffbaf 100644--- a/storyboard.py+++ b/storyboard.py@@ -1,8 +1,6 @@#!/usr/bin/env python3.11"""Storyboard — plan a run of shots that share a character, then shoot them.-Design doc: ~/AI/projects/phosphene/decisions/director_architecture.md-WHAT THIS IS, IN PHOSPHENE'S OWN TERMS--------------------------------------Phosphene's thesis is "your trained character, in any scene." A storyboard is simply that at@@ -222,6 +220,16 @@ _H3_LENGTH_FRAMES = {"3s": 73, "5s": 124, "10s": 243, "15s": 362}# N windows stitched by the runner, and every window is asked for a prompt._H3_LENGTH_WINDOWS = {"3s": 1, "5s": 1, "10s": 2, "15s": 3}+# Does this shot have spoken lines? The planner writes dialogue in explicit+# <d>…</d> tags, so this is a DERIVATION rather than a guess — which is the only+# reason the storyboard lane is allowed to decide `no_voice` automatically at+# all.+#+# The lookahead is load-bearing: a bare `<d>\s*\S` matches `<d></d>`, because+# the `<` of the CLOSING tag is itself non-whitespace. An empty tag is a planner+# artefact and means silence, so it must not load the voice.+_HAS_DIALOGUE = re.compile(r"<d>\s*(?!</\s*d\s*>)\S", re.I)+# A pass's quality (the LTX vocabulary the policy speaks) -> H3's canvas axis.# quick 640x384 · standard 768x448 · high 1024x576 are the three offered canvases;# "native" (1344x768) is deliberately unreachable from a storyboard pass — it is a ~20 min@@ -804,6 +812,20 @@ def shot_to_job(shot: dict, policy_pass: dict, *,if shot.get("character_id"):job["character_id"] = shot["character_id"]+ # THE VOICE LOADS ONLY WHEN THERE ARE LINES TO SAY.+ #+ # Stacking a character's audio LoRA on a shot with no speech spends the+ # audio branch on nothing and, on some prompts, invites gibberish. The+ # panel already has the manual escape hatch (the "No voice" pill); this+ # makes the DEFAULT right in the one place it can be known EXACTLY+ # rather than guessed.+ #+ # And it is exact here: the planner's H3 dialect carries dialogue in+ # explicit <d>…</d> tags, so this is a derivation, not a heuristic. A+ # shot with a <d> tag that has any content speaks; one without does not.+ # (The Manual tab cannot know this and does not pretend to — it sets a+ # default and says it did.)+ job["no_voice"] = "off" if _HAS_DIALOGUE.search(prompt) else "on"if shot.get("seed") is not None:job["seed"] = shot["seed"]@@ -840,7 +862,7 @@ def new_storyboard(board_id: str, title: str, *, shots: list[dict] | None = None"created_at": int(time.time()),"cast": cast or [],"policy": policy or {- "draft": {"quality": "quick", "width": 640, "height": 480, "frames": 49},+ "draft": {"quality": "quick", "width": 640, "height": 448, "frames": 49},"final": {"quality": "balanced", "width": 1024, "height": 576, "frames": 121},},"shots": shots or [],diff --git a/update.js b/update.jsindex 44e079c..f06aa4a 100644--- a/update.js+++ b/update.js@@ -1,502 +1,102 @@+// =============================================================================+// update.js — THIN AND STABLE. Pull, then delegate to the post-pull tree.+// =============================================================================+//+// THIS FILE SHOULD IDEALLY NEVER BE EDITED AGAIN. Everything that can break+// lives in `scripts/post_update.sh`.+//+// WHY. Pinokio wires the menu item as { text: "Update", href: "update.js" } —+// it loads this file from disk INTO MEMORY and then executes its steps. Step 1+// below is what pulls the repo, so the repo moves to the new version MID-RUN+// and execution continues from the STALE in-memory copy. cocktailpeanut (who+// wrote Pinokio) hit this himself on 2026-08-12 and confirmed the sequencing+// with timestamps: the repo moved to v3.8.0 at 13:12:17 and the *old* script's+// command failed ~18 s later. His verdict was that it does not require updater+// restructuring — and it doesn't, on his side. On ours it means:+//+// an app can never deliver a fix to its own installer on the click that+// pulls that fix. It always lands one click late, and the user sees a+// failure they have already downloaded the cure for.+//+// `scripts/post_update.sh` is read AFTER the pull, so a broken update step is+// fixable by shipping — the normal way. So is THE VENDORED PIN, which is why+// it lives in `scripts/pinokio/ltx_checkout.sh` and not here: a pin held in+// this file would move one click late on every single bump, forever.+//+// Full analysis of the sequencing is in the header of+// `scripts/post_update.sh`, which exists because of it.+//+// RULES FOR EDITING THIS FILE+// ---------------------------+// - No pip/uv calls, no patches, no downloads, no trims. Those all belong in+// scripts/post_update.sh.+// - Assume the copy on the user's disk is ANY historical version. A change+// here gets the scrutiny of a schema migration.+// - Every dispatch stays under 500 chars — `node scripts/check_pinokio_scripts.js`.+// Step 1 CANNOT be moved into a .sh: it runs before the pull, so it may+// only reference files that already exist in the user's current tree.+//+// Note: fs.link is only declared in install.js, not here. Running it on every+// Update would migrate existing model folders into the drive without a Reset,+// conflating durability of model assets with routine code updates and adding a+// 36 GB merge step to a flow that should be fast.module.exports = {run: [- // Note: fs.link is only declared in install.js, not here. New users- // get the persistent drive on their first Install; users coming from- // pre-Y1.004 will get it whenever they next reinstall (which is the- // recommended recovery path anyway — see README). Running fs.link on- // every Update would technically migrate their existing real folders- // into the drive without a Reset, but it conflates two concerns- // (durability of model assets vs. routine code updates) and adds a- // 36 GB merge step to a flow that should be fast.-- // Resilient + branch-aware pull for the panel repo. Y1.015 made this- // branch-aware so the same update.js works for both the production- // panel (tracks `main`) and a local dev panel (tracks `dev`). The- // currently-checked-out branch is whatever the install was set up- // with; we pull origin/<that branch> rather than hardcoding `main`.+ // ---- 1. Move the panel repo -------------------------------------------+ // Branch- and remote-aware, because the same update.js serves the public+ // panel (origin/main) and the private dev clone (beta/main) — the+ // explicit-origin form `git pull origin <branch>` broke when public+ // origin/dev was deleted in the 2026-05-22 split.//- // Recovery from divergence (Y1.002) is preserved: if --ff-only- // refuses, we fall back to reset --hard origin/<branch>. A Pinokio- // panel install is never expected to carry local commits.+ // MUST be one joined string, not separate array elements. Pinokio runs each+ // element of a `message` array in its OWN shell, so shell variables do not+ // survive between them: as separate elements this block silently degraded+ // `git fetch $REMOTE` to a bare `git fetch` and the divergence recovery+ // `git reset --hard $UPSTREAM` to a bare `git reset --hard`, a no-op+ // against HEAD that cannot recover from divergence at all.+ //+ // v4.0 FIX — `git pull --ff-only $UPSTREAM` HAD NEVER ONCE SUCCEEDED.+ // `$UPSTREAM` expands to "origin/main", and `git pull --ff-only origin/main`+ // passes that as the REPOSITORY argument, not a refspec:+ // fatal: 'origin/main' does not appear to be a git repository+ // So the ff-only attempt always failed and EVERY Phosphene update since+ // Y1.002 silently took the reset --hard fallback, printing "history+ // diverged from upstream" on a repo that had never diverged. Harmless in+ // practice (a panel install carries no local commits, and neither+ // `git pull --ff-only` nor `git reset --hard` touches untracked files) but+ // it is alarming noise and it meant we had no real ff-only guard at all.+ // The bare form uses the configured upstream and fast-forwards correctly;+ // the reset --hard fallback is kept, and now only fires when it is true.+ // Measured against the real update path, not reasoned about.{method: "shell.run",params: {message: [- // Branch-aware + remote-aware fetch+pull. Resolves the- // current branch's upstream (could be origin/main on the- // prod clone, or beta/main on the private dev clone — see- // 2026-05-22 split into public + private repos). The- // explicit-origin form `git pull origin <branch>` broke- // when public origin/dev was deleted.- // MUST be one joined string, not seven array elements. Pinokio runs- // each element of a `message` array in its OWN shell — a fresh- // conda-base activation, a fresh process, terminated when the command- // returns. Shell variables therefore do NOT survive from one element- // to the next. As separate elements this block was silently broken:- // Pinokio's own log shows the echo printing- // updating branch: (upstream: )- // which means `git fetch $REMOTE` degraded to a bare `git fetch`,- // `git pull --ff-only $UPSTREAM` to a bare `git pull`, and worst of- // all the divergence recovery `git reset --hard $UPSTREAM` to a bare- // `git reset --hard` — a no-op against HEAD that cannot recover from- // divergence at all, which is the one job it exists to do.- // Joining with "\n" runs the whole block in a single shell, the way- // the other multi-command steps in this file already do."REMOTE=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null | cut -d/ -f1)",- "BRANCH=$(git rev-parse --abbrev-ref HEAD)","UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null)",- "echo \"updating branch: $BRANCH (upstream: $UPSTREAM)\"",+ "echo \"updating branch: $(git rev-parse --abbrev-ref HEAD) (upstream: $UPSTREAM)\"","git fetch $REMOTE",- "git pull --ff-only $UPSTREAM || (echo 'history diverged from upstream; falling back to reset --hard' && git reset --hard $UPSTREAM)",+ "git pull --ff-only || (echo 'not a fast-forward; resetting to upstream' && git reset --hard $UPSTREAM)","git rev-parse --short HEAD"].join("\n")}},- // ltx-2-mlx is PINNED to v0.14.19 (2026-08-11 catch-up from v0.14.8;- // dgrauet's original tag-pin request 2026-05-12 — he pushes breaking- // changes upstream to sync with the official Lightricks repo). Update- // no longer tracks main; it fetches tags and re-checks-out the pinned- // tag so a previously-installed user converges to a known-good state,- // never to a moving HEAD. The ltx-package re-install step below then- // force-copies the v0.14.19 source into site-packages (non-editable),- // so an existing user's runtime actually moves to 0.14.19 — a bare- // checkout alone would leave the old copy installed. To bump the pin:- // edit BOTH install.js and update.js to the new tag, bump- // _LTX_EXPECTED_VERSION in mlx_warm_helper.py, smoke-test on dev, push.- //- // The v0.14.19 bump needs NO model re-download. See install.js for the- // per-release notes; the one weight-adjacent change is that 0.14.13+- // prefers a versioned `transformer-distilled-*.safetensors` when one- // exists and falls back to the unversioned name — and the trim step at- // the bottom of this file removes the `-1.1` variants, so resolution- // lands on exactly the files v0.14.8 loaded.- // 2026-08-12: the pin is a FORK BUILD — mrbizarro/ltx-2-mlx- // `feat/ltx-2.5` @ 871694d (v0.14.19 + the LTX-2.5 port). An existing- // install has only dgrauet as `origin`, so Update adds the fork remote- // before it can check the SHA out. Both steps are idempotent: the remote- // is added only when absent, and re-checking-out the same SHA is a no-op.- // The ltx-package re-install step below is what actually moves the- // runtime — a bare checkout leaves the old copy in site-packages.- // See install.js for why this is a SHA and not a tag.- {- method: "shell.run",- params: {- path: "ltx-2-mlx",- message: [- "git fetch --tags origin",- "git remote get-url fork > /dev/null 2>&1 || git remote add fork https://github.com/mrbizarro/ltx-2-mlx.git",- "git fetch fork feat/ltx-2.5",- // 3.8.1 HOTFIX — DISCARD LOCAL EDITS BEFORE THE PIN MOVE.- //- // This checkout is the most fragile line in the updater, and on- // 3.8.0 it failed for real users with- // error: Your local changes to the following files would be- // overwritten by checkout:- // packages/ltx-core-mlx/src/ltx_core_mlx/model/video_vae/video_vae.py- // No retry could clear it — nothing in the flow ever un-dirties the- // file, so the Update button was dead for good.- //- // WHY EVERY INSTALL IS DIRTY. ltx-2-mlx is a uv WORKSPACE, and- // install.js installs its members WITH deps and WITHOUT --reinstall,- // so uv links them EDITABLE: site-packages gets- // `_editable_impl_ltx_core_mlx.pth`, not a copy. patch_ltx_codec.py- // then resolves through VENV_ROOTS, finds no ltx_core_mlx directory- // in site-packages, and falls through to `packages/ltx-core-mlx/src`- // — the GIT-TRACKED source. So a perfectly successful install ends- // with a modified tracked file, every single time. (An install that- // DIED at the package step lands in the same place for a different- // reason: nothing in site-packages at all.) The v0.14.8 -> 871694d- // diff rewrites the very ffmpeg lines that patch edits, so git- // refuses to move the pin. Same class, not the same SHA: ANY- // modified tracked file that differs across a pin move blocks it.- //- // WHY reset --hard AND NOT `git checkout -- <file>`. This tree is- // APP-MANAGED end to end: models live in ../mlx_models, the build- // constraints in ../pip-build-constraints.txt, and on a real install- // the only non-tracked thing inside it is the ignored env/ venv —- // which reset --hard does not touch, so the multi-GB venv survives.- // A surgical per-file revert would only fix today's filename.- //- // SAFE BECAUSE OF WHAT FOLLOWS. The uv step below reinstalls the- // three packages with --reinstall --no-deps, which REPLACES the- // editable .pth links with real copies in site-packages; the codec- // patch further down then re-applies there, so the runtime imports a- // patched video_vae.py and this tree stays clean for the NEXT pin- // move. Proven end to end, from a real v0.14.8 editable install.- // The guard stops reset --hard ever firing in a shell that did not- // land in the vendored tree.- "if [ -f packages/ltx-core-mlx/pyproject.toml ]; then echo 'vendored tree is app-managed; discarding local edits before the pin move:'; git status --porcelain | head -20; git reset --hard HEAD; else echo 'WARN: not the vendored ltx-2-mlx tree - skipping reset'; fi",- "git checkout 871694ddaa09c1598d663a49005a2f91ae6b4ed2",- "git rev-parse --short HEAD"- ]- }- },- // Force-downgrade mlx to 0.31.1 — fixes 22 dB audio regression on mlx- // 0.31.2. Existing users who installed before this commit have mlx 0.31.2- // and quiet audio; clicking Update reinstalls to the pinned version.- // --force-reinstall + --no-deps so we change ONLY mlx without disturbing- // ltx-* / transformers / etc. (some of which depend on mlx>=0.31.0).- // See install.js for the full diagnostic note.- {- method: "shell.run",- params: {- // 3.8.2: uv, not the venv's pip. Every plain-pip step in this file is- // now a uv step, for one reason: mlx-vlm is deliberately installed- // --no-deps, so its metadata is permanently unsatisfiable, and pip- // runs a dependency-consistency pass after ANY install that actually- // changes something. That pass prints- // ERROR: pip's dependency resolver does not currently take into- // account all the packages that are installed...- // even when the install succeeded and pip exits 0 (measured). The- // mflux step below already switched to uv for exactly this noise —- // "this is what made cocktailpeanut's update look broken even though- // mflux installed fine". On the owner's v3.8.1 run it was worse than- // cosmetic: the Pinokio run ENDED at the certifi step that emitted- // that block (session log: last `step: 7` of 18) and every remaining- // step was skipped in silence. uv does the same installs and emits- // none of it. One lane, one failure mode.- message: "uv pip install --python ./ltx-2-mlx/env/bin/python --reinstall --no-deps 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1'"- }- },- // Re-install ltx-core-mlx + ltx-pipelines-mlx + ltx-trainer-mlx from- // local packages. Critical for users who hit the dcd639e pin window- // (commits 157b259 through e02e288): their site-packages still has- // 0.1.0 installed even after `git checkout main` updates the source- // tree to 0.2.0+. Without this re-install they'd have working source- // but broken installed code (e.g. ExtendPipeline.extend_from_video- // missing cfg_scale kwarg). --force-reinstall guarantees overwrite;- // --no-deps avoids re-resolving (and re-pulling) mlx etc.- //- // 3.0: ltx-trainer added so existing v2 installs can run the new- // Train Character tab without re-installing from scratch. The- // trainer subprocess fails at `import yaml` without pyyaml, which- // is a transitive dep of ltx-trainer-mlx — installing the local- // package brings it cleanly.+ // ---- 2. Everything else, from the tree we just pulled ------------------+ // One step on purpose. v3.8.2's failure was a Pinokio RUN that stopped+ // after a step which exited 0, because that step's stdout carried pip's+ // "ERROR: pip's dependency resolver…" block — steps 8-17 of 18 never ran,+ // including the codec patch, and the update still presented as finished.+ // Inside one shell script Pinokio sees one step, so no amount of scary+ // text in the middle can silently drop the tail.//- // `--build-constraints` pins the wheel BUILD backend (hatchling<1.32).- // All three upstream pyprojects declare `readme = "../../README.md"` — a- // path outside the package dir — which hatchling 1.32.0 turned into a- // hard error ("Readme path must be within the project directory" →- // metadata-generation-failed). The build runs in an isolated env that- // pulls the newest backend from PyPI, so from the day 1.32.0 shipped- // EVERY Update click died here, on every pinned tag — a moving- // third-party dependency breaking a frozen source tree, not a pin- // regression. See pip-build-constraints.txt.- //- // THIS STEP USES uv, NOT pip, AND THAT IS THE FIX. The obvious spelling- // is `PIP_CONSTRAINT=... ./env/bin/pip install ...`, which is what the- // pip docs used to recommend. It does not work on current pip: when pip- // installs build dependencies it now spawns that sub-install with- // `_PIP_IN_BUILD_IGNORE_CONSTRAINTS=1`, deliberately ignoring the- // environment constraint (verified against pip 26.1 and 26.2.1 — the- // build env resolved hatchling 1.32.0 and the install failed with the- // readme error anyway, with the file at both a relative and an absolute- // path). pip's supported spelling is the newer `--build-constraint`- // flag, but that flag does not exist on older pips, and this step runs- // on installs whose venv was seeded years apart — passing it would turn- // a working Update into "no such option" for them. uv takes the- // constraint on every version we ship with, needs no pip at all, and is- // already assumed present by the uv steps further down this file. It is- // also now literally the same mechanism install.js uses, which is the- // point: one lane, one failure mode.- {- method: "shell.run",- params: {- path: "ltx-2-mlx",- message: "uv pip install --python env/bin/python --reinstall --no-deps --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer"- }- },- // ---- Re-apply the codec patch — HERE, not at the bottom (3.8.2) --------- //- // This step used to sit eleven steps down, after litellm / smolagents /- // mflux / the IC-LoRA fetches. On the owner's own machine the v3.8.1 run- // executed steps 0-7 and STOPPED — Pinokio's own session log records- // `step: 7` as the last one, the `certifi` step, whose plain-pip output- // carried pip's "ERROR: pip's dependency resolver does not currently take- // into account..." block (a side effect of mlx-vlm being installed- // --no-deps). Everything after it, including this patch, silently never- // ran, and the update still presented as finished. Corroborated on that- // install: no smolagents, no mflux, no mlx-teacache, and an UNPATCHED- // video_vae.py in site-packages — i.e. every render encoded 4:2:0.- //- // So: the patch runs IMMEDIATELY after the reinstall that replaces- // site-packages, before a single optional package step can end the run.- // Ordering is the fix; the pip->uv conversion below removes the trigger;- // and patch_ltx_codec.py now verifies its own work and exits non-zero- // with a banner if the file the runtime imports lacks the patch. Three- // independent lines of defence, because the failure is invisible: an- // unpatched install renders perfectly happily, just with blocky faces.- //- // It MUST stay after the uv reinstall above — that step overwrites- // site-packages, so a patch applied before it would be thrown away.- {- method: "shell.run",- params: { message: "./ltx-2-mlx/env/bin/python3.11 patch_ltx_codec.py" }- },- // 3.0: pyyaml + pydantic + tqdm + rich are ltx-trainer-mlx's- // transitive deps. We just installed ltx-trainer with --no-deps so- // those weren't resolved. Install them explicitly (idempotent — pip- // skips when already present).- {- method: "shell.run",- params: {- path: "ltx-2-mlx",- message: "uv pip install --python env/bin/python 'pyyaml>=6.0' 'pydantic>=2.0' 'tqdm>=4.65' 'rich>=13.0'"- }- },- // 3.0: auto-caption (Gemma 3 12B via mlx-vlm) needs mlx-vlm 0.4.4.- // --no-deps because mlx-vlm's heavy default deps fight our mflux /- // transformers / mlx pins. The runtime import is lazy so a partial- // install doesn't break the panel — but the Auto-caption button- // will fail noisily if mlx-vlm is missing. Install idempotently.- {- method: "shell.run",- params: {- path: "ltx-2-mlx",- message: "uv pip install --python env/bin/python --no-deps 'mlx-vlm==0.4.4'"- }- },- // Y1.022: hf_transfer is HuggingFace's Rust accelerator — 5-10× faster- // downloads on big repos (notably the ~25 GB Q8 bundle). Existing- // installs that pre-date Y1.022 don't have it, so a Q8 download was- // bottlenecked at ~50 KB/s on throttled HF anonymous tier. Update- // installs it idempotently. The panel sets HF_HUB_ENABLE_HF_TRANSFER=1- // when invoking hf download; if the package is missing for any reason- // the hf CLI just emits a warning and falls back to plain Python.- {- method: "shell.run",- params: {- message: "uv pip install --python ./ltx-2-mlx/env/bin/python --upgrade 'hf_transfer>=0.1.6'"- }- },- // 2026-05-31 review fix (E3): ensure certifi is present on every update.- // start.js points SSL_CERT_FILE at certifi's cacert.pem (v3.0.4 fix); if- // certifi is ever absent, that path vanishes and ALL panel stdlib HTTPS- // breaks. Naming it explicitly keeps the cert bundle guaranteed-present.+ // `bash <path>`, never `./<path>` — no execute bit, nothing depends on git+ // preserving the mode. The `-f` guard is the one concession to history: a+ // tree that somehow did not pull (offline, permissions) would otherwise hit+ // a bare "No such file" and say nothing useful.{method: "shell.run",params: {- message: "uv pip install --python ./ltx-2-mlx/env/bin/python --upgrade certifi"- }- },- // litellm: replaces the stdlib urllib chat client in agent/engine.py- // with a multi-provider router (free retries, normalized errors,- // single abstraction for OpenAI / Anthropic / Ollama / mlx-lm.server).- // Pinned to >=1.83.14 — earlier 1.x had a March 2026 PyPI supply-- // chain incident (post-install script stole SSH keys). engine.py- // falls back to stdlib urllib if litellm is missing — safe but the- // loop is less robust. Idempotent on repeat updates.- {- method: "shell.run",- params: {- message: "uv pip install --python ./ltx-2-mlx/env/bin/python --upgrade 'litellm>=1.83.14'"- }- },- // smolagents: powers the optional CodeAgent runtime in- // agent/runtime_smol.py (Phase 2 of the agent-layer refactor).- // Off by default; the panel uses it only when launched with- // PHOSPHENE_RUNTIME=smol.- //- // IMPORTANT: smolagents 1.24.0 hard-pins huggingface-hub<1.0.0 in its- // setup, which conflicts with our >=1.5.0 floor (transformers 5+,- // mflux, hf v1 CLI all need hub 1.x). Plain `pip install --upgrade`- // refuses to resolve and fails the entire update with- // ResolutionImpossible — Mr Bizarro saw this as a "blue screen error- // flashing for a second every update".- //- // Fix: match install.js and use `uv pip install`. uv allows the- // version-overlap conflict and installs both, leaving smolagents in- // a "warned but functional" state (verified CodeAgent +- // LocalPythonExecutor both work on hub 1.14.0).- {- method: "shell.run",- params: {- message: "uv pip install --python ./ltx-2-mlx/env/bin/python --upgrade 'huggingface-hub>=1.5.0,<2.0' 'smolagents>=1.24.0'"- }- },- // Pin mflux to the exact version our FBCache patch is line-targeted- // against (0.17.5). If a future bump is needed, change the pin here- // AND in install_qwen.js AND re-validate patch_mflux_fbcache.py.- //- // Two-step shape mirrors install_qwen.js (the previous single-step- // `--force-reinstall --no-deps` could leave mflux's transitive deps- // MISSING after this update ran — the panel would show Qwen as- // available, then runtime would ImportError on first call).- //- // Gated on "is mflux already installed?" because update.js runs for- // every user on every update — including ones who never opted into- // Qwen via install_qwen.js. Importing mflux is the cheapest probe- // we can do without touching pip. The patch step below is already- // idempotent (skips when its marker is present); the install step- // we gate is the one that materially adds packages to the venv.- {- method: "shell.run",- params: {- message: [- // 2026-06-13: the mflux image-engine pack (Ideogram 4 + Qwen-Edit) is- // now STANDARD — installed for EVERY user on update, not just those who- // once ran the optional installer. This is what unblocks Ideogram 4 for- // everyone who never opted in (cocktailpeanut hit exactly this: token- // saved, regions drawn, but family_installed:false because the mflux CLI- // was absent). Safe to bundle: the base install already pins- // huggingface-hub to a range mflux requires (see install.js), and mflux- // lives in the same venv as the LTX stack.- //- // BEST-EFFORT: wrapped in ( … ) || echo so a pip hiccup (network) does- // NOT fail the whole update — video is unaffected, and the panel- // surfaces a one-click reinstall path if mflux didn't land.- //- // Two-step (WITH deps then --force-reinstall --no-deps) mirrors- // install_qwen.js so the full transitive set (transformers, accelerate,- // sentencepiece, …) resolves, then the version is locked.- // uv, NOT plain pip: mlx-vlm is installed --no-deps, so plain pip dumps- // a scary "ERROR: pip's dependency resolver…" block about mlx-vlm's- // unsatisfied extras on every install (verified — this is what made- // cocktailpeanut's update look broken even though mflux installed fine).- // uv does the same install with zero such noise.- "echo 'Installing/refreshing the mflux image-engine pack (Ideogram 4 + Qwen-Edit) — now standard…' && \\",- "( uv pip install --python ./ltx-2-mlx/env/bin/python 'mflux==0.18.0' && \\",- " uv pip install --python ./ltx-2-mlx/env/bin/python --reinstall --no-deps 'mflux==0.18.0' && \\",- " uv pip install --python ./ltx-2-mlx/env/bin/python 'mlx-teacache==0.4.1' ) \\",- "|| echo 'WARN: mflux image-engine install hit an error — video is unaffected; re-run Update, or use the Reinstall image engines action, to retry.'"- ].join("\n")- }- },- // The mflux FBCache patch stays HERE — it has to, because it patches- // mflux, which is installed by the step directly above. (The codec patch- // that used to sit alongside it moved up to run right after the ltx- // package reinstall; see the 3.8.2 note there for why.) Idempotent —- // skips when its marker is already present. Pin to the venv's python3.11- // to match install.js: `python3` on Pinokio hosts isn't guaranteed to be- // 3.11, or even present on PATH.- {- method: "shell.run",- params: { message: "./ltx-2-mlx/env/bin/python3.11 patch_mflux_fbcache.py" }- },- // Y1.024: reclaim disk on existing installs by deleting model files- // we never load. dgrauet's LTX repos host duplicate transformer- // variants and unused upscalers; pre-Y1.024 `hf download` grabbed- // everything (Q4 → 56 GB instead of 20, Q8 → 82 GB instead of 37).- // New installs use --include filters so the bloat never lands. This- // step trims existing bloated installs. `rm -f` is silently a no-op- // if the file is already absent.- //- // Q4 trim: ~25 GB freed (transformer-distilled-1.1, distilled-lora-1.1,- // x1.5 upscaler, temporal upscaler)- // Q8 trim: ~45 GB freed (transformer-distilled, transformer-distilled-1.1,- // distilled-lora-384-1.1, x1.5 upscaler, temporal upscaler)- //- // Files chosen are those the panel never references at runtime —- // see required_files.json for the canonical list of what we DO load.- //- // IMPORTANT (3.0+): `mlx_models/ltx-2.3-mlx-q4/transformer-dev.safetensors`- // is no longer trimmed. Train Character downloads that 11 GB file on- // demand into the Q4 dir (see `_train_install_dev_transformer` in- // mlx_ltx_panel.py). Removing it here would silently undo the- // training install on every panel update — users who clicked- // Download Q8 dev for training and then Update would lose 11 GB of- // bandwidth and have to re-download.- // ---- Mosaic fix (2026-06-13) ------------------------------------------ // The Q4 render path is two-stage: it upscales the half-res latent with- // spatial_upscaler_x2_v1_1.safetensors. The Y1.024 download allowlist- // dropped that file, so affected Q4 installs silently ran a- // RANDOMLY-INITIALISED upsampler -> the "mosaic"/rainbow-grid (#23; root- // cause found by @dgrauet, who also made ltx-pipelines-mlx fail loud about- // it upstream). It's back in required_files.json (verify/repair flags it),- // and fetched here so existing users self-heal on Update without clicking- // Repair. ~1 GB, resumable; hf skips it when already present. BEST-EFFORT —- // a network hiccup must not fail the update.- {- method: "shell.run",- params: {- venv: "env",- path: "ltx-2-mlx",- env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },- message: [- "echo 'Ensuring the Q4 spatial upscaler is present (mosaic fix)…' && \\",- "hf download dgrauet/ltx-2.3-mlx-q4 --local-dir ../mlx_models/ltx-2.3-mlx-q4 --include 'spatial_upscaler_x2_v1_1.safetensors' \\",- "|| echo 'WARN: spatial upscaler fetch failed — open the panel and click Repair to retry (fixes the mosaic).'"- ].join("\n")- }- },-- // ---- Colorize IC-LoRA (restore mode, ~0.3 GB, un-gated) --------------- // Self-heal existing installs onto the Colorize restore feature. UN-GATED- // community weights (no HF token). BEST-EFFORT — a network hiccup must not- // fail the update; the worker falls back to the repo id, and the panel- // surfaces Repair. hf skips it when already present (fast verify).- {- method: "shell.run",- params: {- venv: "env",- path: "ltx-2-mlx",- env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },- message: [- "echo 'Ensuring the Colorize IC-LoRA is present (restore mode, optional)…' && \\",- "hf download DoctorDiffusion/LTX-2.3-IC-LoRA-Colorizer --local-dir ../mlx_models/loras/ic --include 'LTX-2.3-22b-IC-LoRA-Colorizer-0.9.safetensors' \\",- "|| echo 'WARN: Colorize IC-LoRA fetch failed — the Colorize mode will fetch it on first use, or click Repair.'"- ].join("\n")- }- },-- // ---- Ingredients IC-LoRA (multi-reference mode, ~1.3 GB, un-gated) ----- // Self-heal existing installs onto the flagship Ingredients feature. The- // official weight is GATED; DeepBeepMeep/LTX-2 mirrors the BYTE-IDENTICAL- // file un-gated (no HF token). BEST-EFFORT — must not fail the update; the- // worker self-heals via a targeted single-file fetch, and the panel- // surfaces Repair. CRITICAL: --include pulls ONLY the one ingredients file- // (DeepBeepMeep/LTX-2 is a ~708 GB mega-repo). hf skips it when already- // present (fast verify).- {- method: "shell.run",- params: {- venv: "env",- path: "ltx-2-mlx",- env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },- message: [- "echo 'Ensuring the Ingredients IC-LoRA is present (multi-reference mode, optional)…' && \\",- "hf download DeepBeepMeep/LTX-2 --local-dir ../mlx_models/loras/ic --include 'ltx-2.3-22b-ic-lora-ingredients-0.9.safetensors' \\",- "|| echo 'WARN: Ingredients IC-LoRA fetch failed — the Ingredients mode will fetch it on first use, or click Repair.'"- ].join("\n")- }- },-- // ---- Control (Union) IC-LoRA (control mode, ~0.65 GB, OFFICIAL un-gated)- // Self-heal existing installs onto the Control feature. This is the- // OFFICIAL Lightricks weight and it is UN-GATED + public (no HF token, no- // mirror, no mega-repo workaround) — a plain single-file fetch like the- // Colorize one above. BEST-EFFORT — must not fail the update; the worker- // falls back to the repo id, and the panel surfaces Repair. hf skips it- // when already present (fast verify).- {- method: "shell.run",- params: {- venv: "env",- path: "ltx-2-mlx",- env: { HF_HUB_ENABLE_HF_TRANSFER: "1" },- message: [- "echo 'Ensuring the Control IC-LoRA is present (Union, control mode, optional)…' && \\",- "hf download Lightricks/LTX-2.3-22b-IC-LoRA-Union-Control --local-dir ../mlx_models/loras/ic --include 'ltx-2.3-22b-ic-lora-union-control-ref0.5.safetensors' \\",- "|| echo 'WARN: Control IC-LoRA fetch failed — the Control mode will fetch it on first use, or click Repair.'"- ].join("\n")- }- },- {- method: "shell.run",- params: {- message: [- "echo 'Trimming unused model variants from mlx_models/ (saves up to ~70 GB on pre-Y1.024 installs)…'",- "rm -f mlx_models/ltx-2.3-mlx-q4/transformer-distilled-1.1.safetensors",- "rm -f mlx_models/ltx-2.3-mlx-q4/ltx-2.3-22b-distilled-lora-384-1.1.safetensors",- "rm -f mlx_models/ltx-2.3-mlx-q4/spatial_upscaler_x1_5_v1_0.safetensors",- "rm -f mlx_models/ltx-2.3-mlx-q4/temporal_upscaler_x2_v1_0.safetensors",- "rm -f mlx_models/ltx-2.3-mlx-q8/transformer-distilled.safetensors",- "rm -f mlx_models/ltx-2.3-mlx-q8/transformer-distilled-1.1.safetensors",- "rm -f mlx_models/ltx-2.3-mlx-q8/ltx-2.3-22b-distilled-lora-384-1.1.safetensors",- "rm -f mlx_models/ltx-2.3-mlx-q8/spatial_upscaler_x1_5_v1_0.safetensors",- "rm -f mlx_models/ltx-2.3-mlx-q8/temporal_upscaler_x2_v1_0.safetensors",- "echo 'Trim done.'"- ]+ message: "if [ -f scripts/post_update.sh ]; then bash scripts/post_update.sh; else echo 'FATAL: scripts/post_update.sh missing - the repo pull above did not land. Re-run Update.'; exit 1; fi"}}]