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(v3.8.0): Storyboard, and the install that had been failing for everyone new
mrbizarro1552a91a00ee
diff --git a/.gitignore b/.gitignoreindex fb86640..5b92ca5 100644--- a/.gitignore+++ b/.gitignore@@ -53,8 +53,31 @@ mlx_models/# Third-party — installed alongside, not part of this repo# =============================================================================ltx-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,+# and mlx_models/hailuo-h3 is fs.link-mapped from here). It is a separate git+# repo of its own, so to THIS repo it is just a permanently-untracked folder.+# Un-ignored it made `git status --porcelain` never empty, which the panel+# read as "local changes uncommitted" and used to suppress the whole update+# 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/.venv/+# =============================================================================+# Pinokio runtime dirs — created next to the app, never ours to commit+# =============================================================================+# ENVIRONMENT points HF_HOME / TORCH_HOME / GRADIO_TEMP_DIR at ./cache/*, and+# install_h3.js passes HF_HOME={{cwd}}/cache/HF_HOME explicitly, so installing+# the H3 pack always leaves content there. `logs/` is the panel's own run log+# dir (*.log alone doesn't cover the directory once it holds anything else).+# 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).+/cache/+/logs/+# =============================================================================# Legacy experimentation files (Comfy workflows, etc.) — not part of the panel# =============================================================================diff --git a/CLAUDE.md b/CLAUDE.mdindex 28e30db..f7c4753 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -197,9 +197,15 @@ 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 **`v0.14.8`** (commit `d2ad8e9`) | install.js + update.js do `git checkout v0.14.8` (2026-06-01 catch-up from v0.14.0). **STAY PINNED** — this is NOT "main HEAD". v0.14.8 is the tag the panel + helper + patch_ltx_codec.py were validated against (full modality matrix smoke-tested on dev). The bump pulled dgrauet's native `_pre_denoise_flush` (the Metal-watchdog fix that resolves the I2V "mosaic" on memory-pressured Macs, #17), budget-aware VAE decode tiling, and first-class `frame_rate` — which let us drop 6 of 7 runtime patches (codec-only now). 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. |+| `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. |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+`tests/` suite; `patch_ltx_codec.py` → `applied` with the installed tree+diverging from the tag in exactly one file and one hunk (the ffmpeg line);+and a real T2V draft render on a throwaway instance (isolated state ++output dirs, GPU lock held) producing video **and** audio.## 5. The patch system (`patch_ltx_codec.py`)@@ -210,7 +216,10 @@ broken pipeline). Each patch has an `OLD` text it expects to find and aAs of the **v0.14.8** pin (2026-06-01 catch-up) only ONE patch remains —upstream absorbed the other six natively, so we dropped them and cut our-divergence from 7 patches to 1 (the whole reason for the catch-up):+divergence from 7 patches to 1 (the whole reason for the catch-up). The+**v0.14.19** pin (2026-08-11) re-validated that: the `decode_and_stream`+ffmpeg line moved 482 → 487 but its text is character-identical, so the+patch applied with no edit to `PATCH_CODEC_OLD`:1. **Codec (`yuv444p crf 0` + `+faststart`)** — required.Patches `ltx_core_mlx/model/video_vae/video_vae.py`. Default ffmpeg@@ -238,8 +247,8 @@ divergence from 7 patches to 1 (the whole reason for the catch-up):The helper calls the new API defensively (`hasattr` guard on`generate`/`generate_from_image`, `inspect.signature` probing, and`_filter_unsupported_kwargs`), so nothing depends on the dropped patches.-Re-implementing any of them against v0.14.8 would only re-introduce the-divergence the catch-up removed.+Re-implementing any of them against the pinned tag would only re-introduce+the divergence the catch-up removed.The "upgrade" path in `apply_patch()` lets old patched installs receivenew patch versions without a venv rebuild — used when we addeddiff --git a/LICENSES/LTX-2.x-Community-License.md b/LICENSES/LTX-2.x-Community-License.mdnew file mode 100644index 0000000..8858b29--- /dev/null+++ b/LICENSES/LTX-2.x-Community-License.md@@ -0,0 +1,125 @@+# LTX-2.x Community License Agreement++*License date: August 11, 2026*++**By downloading, using, accessing or distributing any portion or element of LTX-2.x, you agree that you have read and accepted to be bound by this Agreement.**++**1. Definitions.**++> **1.1** **“Agreement”** means the terms and conditions for this LTX-2.x Community License Agreement and the exhibits, attachments, and Complementary Materials, as specified in this document.++> **1.2** **“Complementary Materials”** means the accompanying documentation, tutorials, examples, configuration files and other materials made available by Licensor together with the LTX-2.x model weights and parameters, in each case as distributed by Licensor.++> **1.3** **“Control”** means the direct or indirect ownership of more than fifty percent (50%) of the voting securities or other ownership interests, or the power to direct the management and policies of such Entity through voting rights, contract, or otherwise.++> **1.4** **“Data”** means a collection of information and/or content extracted from the dataset used with LTX-2.x, including to train, pretrain, or otherwise evaluate LTX-2.x. The Data is not licensed under this Agreement.++> **1.5** **“Derivatives of LTX-2.x”** means all modifications to LTX-2.x, works based on LTX-2.x, or any other model which is created or initialized by transfer of patterns of the weights, parameters, activations or output of LTX-2.x, to the other model, in order to cause the other model to perform similarly to LTX-2.x, including – but not limited to - distillation methods entailing the use of intermediate data representations or methods based on the generation of synthetic data by LTX-2.x for training the other model. For clarity, Derivatives of LTX-2.x include: (i) any fine-tuned or adapted weights, parameters, or checkpoints derived from LTX-2.x; (ii) derivative model architectures that incorporate or are based upon LTX-2.x’s architecture; and (iii) any modified or extended versions of the Complementary Materials.++> **1.6** **“Entity”** means any individual, corporation, partnership, limited liability company, or other legal entity. For purposes of this Agreement, an Entity shall be deemed to include, on an aggregative basis, all subsidiaries, affiliates, and other companies under common Control with such Entity. When determining whether an Entity meets any threshold under this Agreement (including revenue thresholds in Section 2.1), all subsidiaries, affiliates, and companies under common Control shall be considered collectively.++> **1.7** **“Harm”** includes but is not limited to physical, mental, psychological, financial and reputational damage, pain, or loss.++> **1.8** **“Licensor”** or **“LTX”** means the owner that is granting the license under this Agreement. For the purposes of this Agreement, the Licensor is Lightricks Ltd.++> **1.9** **“LTX-2.x”** means the large generative models, text/image/video/audio/3D generation models, and multimodal large language models and their software and algorithms, including trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code, accompanying source code, scripts, and all other elements of the foregoing distributed and made publicly available by LTX (including, for example, at [https://github.com/Lightricks/LTX-2](https://github.com/Lightricks/LTX-2)). This license is applicable to all LTX-2.5 versions released since August 11, 2026, and all future releases of LTX-2.x under this license.++> **1.10** **“Output”** means the results of operating LTX-2.x as embodied in informational content resulting therefrom.++> **1.11** **“you”** (or **“your”**) means an individual or legal Entity licensing LTX-2.x in accordance with this Agreement and/or otherwise downloading, accessing, distributing or using LTX-2.x for whichever purpose and in any field of use, including usage of LTX-2.x in an end-use application - e.g. chatbot, translator, image generator.++**2. Grant of License.**++> **2.1** Subject to your compliance with the terms and conditions of this Agreement, you are granted a non-exclusive, worldwide, non-transferable and royalty-free limited license under Licensor’s intellectual property or other rights owned by Licensor embodied in LTX-2.x to use, reproduce, prepare, distribute, publicly display, publicly perform, sublicense, copy, create derivative works of, and make modifications to LTX-2.x, for any purpose, subject to the restrictions set forth in Attachment A; **provided however, that Entities with annual revenues of at least $10,000,000 (the “Commercial Entities”) are required to obtain a paid license for any use (excluding use solely for a Non-Commercial Purpose as set forth in Section 2.2) of LTX-2.x and Derivatives of LTX-2.x (such paid license referred to herein as a “Commercial Use Agreement”), as will be provided by the Licensor. Commercial Entities interested in such a commercial license are required to [contact Licensor](mailto:[email protected]). Any use of LTX-2.x or Derivatives of LTX-2.x by Commercial Entities not in accordance with this Agreement and/or the Commercial Use Agreement is strictly prohibited and shall be deemed a material breach of this Agreement. In the event of such material breach, and without limiting Licensor’s right to terminate the Agreement or to pursue any other remedies available at law or in equity, you shall pay Licensor the license fees owed for the period such Commercial Entity used LTX-2.x (calculated at Licensor’s standard commercial license fees, in effect during the relevant period or, absent published standard fees, a reasonable market rate for a comparable license), within thirty (30) days of Licensor’s written demand.**++> **2.2** Notwithstanding the foregoing or anything to the contrary in this Agreement, a Commercial Entity may download and use LTX-2.x and Derivatives of LTX-2.x without obtaining the Commercial Use Agreement solely for a Non-Commercial Purpose. **“Non-Commercial Purpose”** means any of the following uses, but only so far as such Commercial Entity does not receive any direct or indirect payment arising from the use of LTX-2.x or Derivatives of LTX-2.x: (i) use by an individual acting in a personal capacity for research, experimentation, learning, private study, hobby or recreational projects, or personal entertainment, in each case where such use is not connected, directly or indirectly, to any commercial activity, business operation, or the performance of duties for an employer or any other Entity; and (ii) use by a Commercial Entity for testing, evaluation, or non-commercial research and development in a non-production or development environment. For clarity, use (a) for revenue-generating activity in any manner, whether direct or indirect, (b) in direct interactions with or that has impact on end users, or (c) to train, fine-tune, or distill any model (including any Derivative of LTX-2.x) for commercial use, in each case, is not a Non-Commercial Purpose and requires all Commercial Entities to obtain a paid license under the Commercial Use Agreement prior to such use. For the avoidance of doubt, the permission granted under this Section 2.2 is a limited right of use only and does not convey or transfer any ownership right, title, or interest in or to LTX-2.x or any Derivatives of LTX-2.x, and all Derivatives of LTX-2.x created or used pursuant to this Section 2.2 remain subject to the terms of this Agreement, including Section 1.5.++**3. Distribution and Redistribution.** You may host for third parties remote access purposes (e.g. software-as-a-service), reproduce and distribute copies of LTX-2.x or Derivatives of LTX-2.x thereof in any medium, with or without modifications, provided that you meet the following conditions:++> **3.1** Use-based restrictions as referenced in Section 4 and all provisions of Attachment A MUST be included as an enforceable provision by you in any type of legal agreement (e.g. a license) governing the use and/or distribution of LTX-2.x or Derivatives of LTX-2.x, and you shall give notice to subsequent users you distribute to, that LTX-2.x or Derivatives of LTX-2.x are subject to Section 4 and Attachment A in their entirety, including all use restrictions and acceptable use policies;++> **3.2** You must provide any third-party recipients of LTX-2.x or Derivatives of LTX-2.x a copy of this Agreement, including all attachments and use policies. Any Derivative of LTX-2.x (as defined in Section 1.5, including but not limited to fine-tuned weights, modified training code, models trained on Outputs, or any other derivative) must be distributed exclusively under the terms of this Agreement, subject to Section 3.6, with a complete copy of this Agreement included;++> **3.3** You must cause any modified files to carry prominent notices stating that you changed the files;++> **3.4** You must retain all copyright, patent, trademark, and attribution notices excluding those notices that do not pertain to any part of LTX-2.x, Derivatives of LTX-2.x.++> **3.5** Transfer of Derivatives. No transfer of any Derivative of LTX-2.x (including any fine-tuned weights, LoRA adapters, or similar adaptations) to a third party shall grant such third party any right, title, license, or authorization to access, use, reproduce, distribute, or exploit LTX-2.x, or any Derivative of LTX-2.x beyond the rights granted under this Agreement. If the transferee is a Commercial Entity (as defined in Section 2), it must obtain a paid license from Licensor prior to any use of any Derivative of LTX-2.x, regardless of who created such Derivative. Prior to or at the time of any such transfer, you shall notify the transferee in writing that (i) use of such Derivative of LTX-2.x is subject to the terms of this Agreement, and (ii) if the transferee is a Commercial Entity, it must obtain a separate paid license to LTX-2.x from Licensor. You shall not transfer any Derivative of LTX-2.x to a Commercial Entity unless such Commercial Entity has obtained the required paid license from Licensor prior to any use, and unless the proposed transferee has been so informed. You and the transferee shall each be responsible for ensuring the transferee obtains the required license from Licensor prior to any use of LTX-2.x or Derivative of LTX-2.x. Nothing in this Section 3.5 shall require a Commercial Entity to obtain a paid license for use solely for a Non-Commercial Purpose as permitted under Section 2.2.++> **3.6** You may add your own copyright statement to your modifications and may provide additional license terms and conditions - **respecting Section 3.1** - for use, reproduction, or distribution of your modifications, or for any such Derivatives of LTX-2.x as a whole, provided your use, reproduction, and distribution of LTX-2.x otherwise complies with the conditions stated in this Agreement, and you provide a complete copy of this Agreement with any such use, reproduction and distribution of LTX-2.x and any Derivatives thereof; provided that any such additional terms shall be additive only and shall not derogate from, conflict with, waive, or purport to modify any term of this Agreement, and this Agreement shall govern in the event of any conflict.++**4. Use-based restrictions.** The restrictions set forth in Attachment A are considered Use-based restrictions. Therefore, you cannot use LTX-2.x and the Derivatives of LTX-2.x in violation of the specified restricted uses. You may use LTX-2.x subject to this Agreement, only for lawful purposes and in accordance with the Agreement. **“Use”** may include creating any content with, fine-tuning, updating, running, training, evaluating and/or re-parametrizing LTX-2.x. You shall require all of your users who use LTX-2.x or a Derivative of LTX-2.x to comply with the terms of this Section 4.++**5. The Output You Generate.** Except as set forth herein, Licensor claims no rights in the Output you generate using LTX-2.x. You are accountable for input you insert into LTX-2.x, the Output you generate and its subsequent uses. No use of the Output can contravene any provision as stated in the Agreement.++**6. Updates and Runtime Restrictions; AI Regulations.** To the maximum extent permitted by law, Licensor reserves the right to restrict (remotely or otherwise) usage of LTX-2.x in violation of this Agreement, update LTX-2.x through electronic means, or modify the Output of LTX-2.x based on updates. You shall undertake reasonable efforts to use the latest version of LTX-2.x. Any use of the non-current version of LTX-2.x is done solely at your risk. To the extent applicable to you, you shall comply with all laws and regulations governing artificial intelligence that apply to your use, deployment, or distribution of LTX-2.x, Derivatives of LTX-2.x, or Outputs, including Regulation (EU) 2024/1689 (the “EU AI Act”) and the California AI Transparency Act (Cal. Bus. & Prof. Code § 22757 et seq.), each as amended from time to time and any other applicable laws, regulations, or binding guidance relating to artificial intelligence, transparency, content provenance, or synthetic media, together with any documentation made available by Licensor regarding compliance with the same (collectively, “AI Regulations”). You shall maintain (including within any application or service through which LTX-2.x, any Derivative of LTX-2.x, or any Output is made available), and shall not remove, disable, alter, or circumvent, any safety or security measures, disclosures, metadata, watermarking, content provenance, latent disclosure, or other transparency features or functionalities included or embedded within LTX-2.x or any Derivative of LTX-2.x, or applied to any Output, in furtherance of AI Regulations, including any capability of LTX-2.x to include latent disclosures in Outputs, and you shall include equivalent obligations in any agreement governing your distribution of LTX-2.x or any Derivative of LTX-2.x. You are solely responsible for any transparency, disclosure, marking, or labeling obligations applicable to you under AI Regulations as a provider or deployer of LTX-2.x, any Derivative of LTX-2.x, or any system incorporating any of the foregoing, including any obligation to disclose that content is artificially generated or manipulated. If Licensor knows or reasonably believes that you have modified LTX-2.x or any Derivative of LTX-2.x such that it is no longer capable of including any disclosure required by AI Regulations in Outputs, or that you have otherwise removed, disabled, or circumvented any feature or functionality described in this Section, Licensor may in its sole discretion revoke the license granted under this Agreement effective immediately upon notice to you, and upon such revocation you shall immediately cease all use of LTX-2.x and Derivatives of LTX-2.x. Licensor makes no representation or warranty that LTX-2.x, any Derivative of LTX-2.x, or any Output complies with any AI Regulations applicable to your specific use case or deployment, and you are solely responsible for determining the applicability of, and ensuring your compliance with, all AI Regulations. You shall indemnify, defend, and hold harmless Licensor and its affiliates from and against any and all claims, liabilities, losses, damages, costs, and expenses (including reasonable attorneys’ fees) arising out of or relating to your use, deployment, distribution, or modification of LTX-2.x, any Derivative of LTX-2.x, or any Output in violation of, or your other failure to comply with, any AI Regulations.++> For purposes of the EU AI Act, Licensor makes LTX-2.x openly available under this community license and intends that LTX-2.x be treated as a free and open-source general purpose AI model within the meaning of Article 53(2) of the EU AI Act. You acknowledge and agree that (a) to the extent the free and open source derogations under Article 53(2) of the EU AI Act apply, Licensor’s obligations under the EU AI Act with respect to LTX-2.x are limited to those applicable to providers of free and open source general purpose AI models (it being acknowledged that such derogations do not extend to the obligations under Article 53(1)(c) and (d)), (b) you acknowledge that LTX-2.x is not intended to be integrated into a high risk AI system, and shall be fully and solely responsible for any obligation resulting from such integration, (c) if you integrate LTX-2.x or any Derivative of LTX-2.x into a high-risk AI system you shall be solely responsible for all provider obligations that would otherwise apply to Licensor under the EU AI Act, and (d) you shall not take any action, or omit to take any action, that would cause Licensor to lose the benefit of the free and open source derogations under the EU AI Act, and you shall indemnify and hold Licensor harmless from any liability, costs, or expenses arising from your breach of this Section.++**7. Export Controls and Sanctions Compliance.** You acknowledge that LTX-2.x, Derivatives of LTX-2.x may be subject to export control laws and regulations, including but not limited to the U.S. Export Administration Regulations and sanctions programs administered by the Office of Foreign Assets Control (OFAC). You represent and warrant that you and any users of LTX-2.x are not (i) located in, organized under the laws of, or ordinarily resident in any country or territory subject to comprehensive sanctions; (ii) identified on any U.S. government restricted party list, including the Specially Designated Nationals and Blocked Persons List; or (iii) otherwise prohibited from receiving LTX-2.x under applicable law. You shall not export, re-export, or transfer LTX-2.x, directly or indirectly, in violation of any applicable export control or sanctions laws or regulations. You agree to comply with all applicable trade control laws and shall indemnify and hold Licensor harmless from any claims arising from your failure to comply with such laws.++**8. Trademarks; Reservation of Rights.** Nothing in this Agreement permits you to make use of Licensor’s trademarks, trade names, logos or to otherwise suggest endorsement or misrepresent the relationship between the parties; and any rights not expressly granted herein are reserved by the Licensor. Except as expressly set forth in this Agreement, Licensor does not grant, directly or by implication, estoppel, statute or otherwise, any right or license in its, or its affiliates’, intellectual property rights or other proprietary rights. For avoidance of doubt, all intellectual property rights in Derivatives of LTX-2.x shall be subject to the terms of this Agreement, and you acquire no right, title, or interest in or to LTX-2.x itself, which is and remains the exclusive property of Licensor. You shall not assert any ownership or other right in LTX-2.x or any Derivative of LTX-2.x in any manner that restricts, encumbers, or is inconsistent with the rights retained by Licensor or granted to other licensees under this Agreement.++**9. Disclaimer of Warranty.** Unless required by applicable law or agreed to in writing, Licensor provides LTX-2.x on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing LTX-2.x and Derivatives of LTX-2.x and assume any risks associated with your exercise of permissions under this Agreement.++**10. Limitation of Liability.** To the fullest extent permitted by applicable law, in no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall Licensor be liable to you or any other individual or Entity for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this Agreement or out of the use of, or inability to use LTX-2.x or any Derivative of LTX-2.x (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if Licensor has been advised of the possibility of such damages.++**11. Accepting Warranty or Additional Liability.** While redistributing LTX-2.x and Derivatives of LTX-2.x, you may, provided you do not violate the terms of this Agreement, choose to offer and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations. However, in accepting such obligations, you may act only on your own behalf and on your sole responsibility, not on behalf of Licensor, and only if you agree to indemnify, defend, and hold Licensor harmless for any liability incurred by, or claims asserted against Licensor, by reason of your accepting any such warranty or additional liability.++**12. Governing Law.** This Agreement and all relations, disputes, claims and other matters arising hereunder (including non-contractual disputes or claims) will be governed exclusively by, and construed exclusively in accordance with, the laws of the State of New York and applicable U.S. federal law. To the extent permitted by law, choice of laws rules and the United Nations Convention on Contracts for the International Sale of Goods will not apply. The prevailing party in any claim or dispute between the parties under this Agreement will be entitled to reimbursement of its reasonable attorneys’ fees and costs.++**13. Term and Termination.** This Agreement is effective upon your acceptance and continues until terminated. Licensor may terminate this Agreement immediately upon written notice to you if you breach any provision of this Agreement, including but not limited to violations of the use restrictions in Attachment A or unauthorized commercial use. This Agreement also terminates immediately and automatically, without notice, upon any material breach of this Agreement, including any use in violation of applicable AI Regulations or any unauthorized commercial use of LTX-2.x or Derivatives of LTX-2.x by a Commercial Entity. Upon termination: (a) all rights granted to you under this Agreement will immediately cease; (b) you must immediately cease all use of LTX-2.x and Derivatives of LTX-2.x; (c) you must delete or destroy all copies of LTX-2.x and Derivatives of LTX-2.x in your possession or control; and (d) you must notify any third parties to whom you distributed LTX-2.x or Derivatives of LTX-2.x of the termination. Sections 2, 3, 4, 6-16 and Attachment A shall survive termination of this Agreement. Termination does not relieve you of any obligations incurred prior to termination, including payment obligations under Section 2 and adhering to the restrictions under Section 3. In addition, if You commence a lawsuit or other proceedings (including a cross-claim or counterclaim in a lawsuit) against Licensor or any person or entity alleging that LTX-2.x or any Output, or any portion of any of the foregoing, infringe any intellectual property or other right owned or licensable by you, then all licenses granted to you under this Agreement shall terminate as of the date such lawsuit or other proceeding is filed.++**14. Disputes and Arbitration; Waiver of Jury Trial; Class Action Waiver.** **IF YOU ARE NOT ACTING AS A CONSUMER UNDER APPLICABLE LAW, YOU HEREBY WAIVE THE RIGHT TO A TRIAL BY JURY, TO PARTICIPATE IN A CLASS OR REPRESENTATIVE ACTION (INCLUDING IN ARBITRATION), OR TO COMBINE INDIVIDUAL PROCEEDINGS IN COURT OR IN ARBITRATION WITHOUT THE CONSENT OF ALL PARTIES.** All disputes arising in connection with this Agreement shall be finally settled by arbitration under the Rules of Arbitration of the International Chamber of Commerce (“ICC Rules”), by one (1) arbitrator appointed in accordance with the ICC Rules. The seat of arbitration shall be New York, NY, USA, and the proceedings shall be conducted in English. The arbitrator shall be empowered to grant any relief that a court could grant. Judgment on the arbitration award may be entered by any court having jurisdiction thereof. Notwithstanding the foregoing, either party may seek injunctive or other equitable relief in respect of any actual or threatened breach of the license restrictions under this Agreement (including Attachment A and the Acceptable Use Policy) or any actual or threatened infringement, misappropriation, or violation of Licensor’s intellectual property rights, in the state or federal courts located in the County of New York, State of New York, and each party irrevocably consents to the jurisdiction of, and venue in, such courts for that limited purpose. The foregoing waivers do not apply to, and are not enforceable against, any licensee acting as a consumer under the mandatory consumer-protection laws of its jurisdiction of residence (including, without limitation, the European Union, the United Kingdom, and the State of California), and nothing in this Agreement limits any rights under such laws that cannot be waived or limited by contract. If any waiver in this Section is held invalid or unenforceable as to a particular licensee or dispute, such waiver shall be severed to that extent only and shall not affect the validity or enforceability of the remainder of this Section.++**15.** In the event of any exception to the application of binding arbitration, all disputes, claims, and other matters arising hereunder shall be brought exclusively in the state or federal courts located in the County of New York, State of New York. You waive all defenses of lack of personal jurisdiction and forum non conveniens with respect to venue and jurisdiction in such courts, and consent to their exclusive jurisdiction and venue.++**16. Severability.** If any provision of this Agreement is held to be invalid, illegal or unenforceable, the remaining provisions shall be unaffected thereby and remain valid as if such provision had not been set forth herein.++**END OF TERMS AND CONDITIONS**++# Attachment A++*Use Restrictions*++When using the Outputs, LTX-2.x and any Derivatives thereof, you agree to comply with the [Acceptable Use Policy](https://static.lightricks.com/legal/ltx-acceptable-use-policy.pdf) which is hereby incorporated into and made part of this Agreement by reference. Licensor may update it from time to time, and the version in effect at the time of your use governs; continued use after an update constitutes acceptance. Licensor shall post each version of the Acceptable Use Policy with its effective date, and no update shall apply retroactively to use occurring before that effective date. In addition, you agree not to use the Outputs, LTX-2.x or its Derivatives in any of the following ways:++> **1)** In any way that violates any applicable national, federal, state, local or international law or regulation;++> **2)** For the purpose of exploiting, Harming or attempting to exploit or Harm minors in any way;++> **3)** Knowingly generate or disseminate verifiably false information and/or content with the intent to deceive, defraud, or otherwise unlawfully Harm others;++> **4)** To generate or disseminate personal identifiable information that can be used to Harm an individual;++> **5)** To generate or disseminate information and/or content (e.g. images, code, posts, articles), and place the information and/or content in any context (e.g. bot generating tweets) without expressly and intelligibly disclaiming that the information and/or content is machine generated;++> **6)** To defame others, or to engage in the unlawful harassment of others;++> **7)** To impersonate or attempt to impersonate (e.g. deepfakes) others without their consent;++> **8)** For fully automated decision making that adversely impacts an individual’s legal rights or otherwise creates or modifies a binding, enforceable obligation;++> **9)** For any use intended to or which has the effect of discriminating against or Harming individuals or groups based on online or offline social behavior or known or predicted personal or personality characteristics;++> **10)** To exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological Harm;++> **11)** For any use intended to or which has the effect of discriminating against individuals or groups based on legally protected characteristics or categories;++> **12)** To provide medical advice and medical results interpretation;++> **13)** To generate or disseminate information for the purpose to be used for administration of justice, law enforcement, immigration or asylum processes, such as predicting an individual will commit fraud/crime commitment (e.g. by text profiling, drawing causal relationships between assertions made in documents, indiscriminate and arbitrarily-targeted use);++> **14)** To generate and/or disseminate malware (including – but not limited to – ransomware) or any other content to be used for the purpose of harming electronic systems;++> **15)** To engage in, promote, incite, or facilitate discrimination or other unlawful or harmful conduct in the provision of employment, employment benefits, credit, housing, or other essential goods and services;++> **16)** To engage in, promote, incite, or facilitate the harassment, abuse, threatening, or bullying of individuals or groups of individuals;++> **17)** For military, warfare, nuclear industries or applications, weapons development, or any use in connection with activities that may cause death, personal injury, or severe physical or environmental damage;++> **18)** For commercial use only: To train, improve, or fine-tune any other machine learning model, artificial intelligence system, or competing model, except for Derivatives of LTX-2.x as expressly permitted under this Agreement;++> **19)** To circumvent, disable, or interfere with any technical limitations, safety features, content filters, watermarking, content provenance or latent disclosure functionalities, or use restrictions implemented in LTX-2.x by Licensor;++> **20)** To use LTX-2.x or Derivatives of LTX-2.x in any product, service, or application that directly competes with Licensor’s commercial products or services, or is designed to replace or substitute Licensor’s offerings in the market, without obtaining a separate commercial license from Licensor.diff --git a/LICENSES/NOTICE-ltx25-weights.md b/LICENSES/NOTICE-ltx25-weights.mdnew file mode 100644index 0000000..383724a--- /dev/null+++ b/LICENSES/NOTICE-ltx25-weights.md@@ -0,0 +1,88 @@+# NOTICE — Phosphene's LTX-2.5 weight packs++These files are a **Derivative of LTX-2.x** as defined in section 1.5 of the+**LTX-2.x Community License Agreement**, and they are distributed **exclusively+under that Agreement**. A complete copy of the Agreement — including Attachment+A, the acceptable-use policy — is published alongside these weights as+`LICENSE-LTX-2.x-Community-License.md` and is installed into the same directory+as the weights themselves. Read it before you use them.++## Attribution++| | |+|---|---|+| Original model | **LTX-2.5** |+| Licensor / copyright | **Lightricks Ltd.** |+| Upstream source | <https://huggingface.co/Lightricks/LTX-2.5> (bf16 release) |+| Upstream project | <https://github.com/Lightricks/LTX-2> |+| MLX inference port | `dgrauet/ltx-2-mlx` (MIT) — the runtime these packs are laid out for |+| This derivative | Phosphene — <https://github.com/mrbizarro/Phosphene> |++All copyright, patent, trademark and attribution notices carried by the upstream+release are retained. The safetensors metadata of every converted file preserves+the upstream `__metadata__` block verbatim.++## Statement of changes (License §3.3)++**Every weight file in these packs has been modified.** Nothing here is a+byte-for-byte copy of a Lightricks file. What was done, and nothing else:++1. **Layout conversion.** The official PyTorch-layout checkpoint was rewritten+ into the flat, single-file-per-component MLX layout the `ltx-2-mlx` runtime+ loads (`scripts/convert_ltx_mlx.py`). Tensor **names** change; tensor values+ do not.+2. **Quantisation.** The diffusion transformer's block linears were quantised+ from bf16 to **4-bit** (`ltx-2.5-mlx-q4`) or **8-bit** (`ltx-2.5-mlx-q8`),+ group size 64, by `scripts/quantize_ltx.py`. AdaLN modulation, patch+ embedding and output projections stay bf16 — the same recipe the community+ 2.3 packs use. The text encoder pack (`gemma4-12b-ltx25-q4`) is the LTX-2.5+ Gemma 4 text tower quantised the same way.+3. **Provenance metadata added.** Each converted file carries an extra+ `phosphene_quant` key in its safetensors metadata recording the tool,+ version, recipe and bit width. No timestamps, so two builds are byte-identical.+4. **Sidecar config files generated.** `quantize_config.json`,+ `split_model.json`, `model.safetensors.index.json` and the per-upscaler+ configs are written by our tooling to describe the layout above.+5. **Sharding for transport only.** Files larger than 1.9 GB are published as+ ordered shards because a GitHub release asset is capped at 2 GiB. Shards are+ a pure byte split; `scripts/fetch_pack_release.py` reassembles them and+ verifies the sha256 of every shard **and** of every reassembled file against+ the published manifest. The reassembled bytes are exactly the bytes we built.++No training, fine-tuning, distillation or capability change was performed. No+safety, watermarking, provenance or use restriction implemented by the Licensor+has been removed, disabled or circumvented.++## Terms passed on to you (License §3.1, §3.2)++By downloading or using these weights you accept the LTX-2.x Community License+Agreement in full, **including the use restrictions in Section 4 and Attachment+A**, which apply to you exactly as they apply to us and which you must pass on+in turn to anyone you distribute these weights — or any derivative of them — to.+Any derivative you make of these weights must itself be distributed exclusively+under that Agreement, with a complete copy of it included.++## Commercial Entities (License §2.1, §3.5)++The Agreement defines a **Commercial Entity** as an Entity with annual revenues+of at least **US $10,000,000** (counted across subsidiaries, affiliates and+companies under common control).++**A Commercial Entity must obtain a paid licence from Lightricks Ltd. before any+use of LTX-2.x or any Derivative of it**, including these packs — except use+solely for a Non-Commercial Purpose as defined in Section 2.2 (personal+research, learning, hobby use; or testing/evaluation in a non-production+environment). Receiving these files from us grants no such licence and no right+beyond the Agreement. Contact <[email protected]>.++If you pass these weights on to anyone else, you must tell them the same two+things in writing: that their use is subject to this Agreement, and that a+Commercial Entity needs a separate paid licence from Lightricks.++## Phosphene's own contribution++The conversion and quantisation tooling, the sharding and reassembly format, the+manifest, and the panel that loads these packs are Phosphene's own work and are+covered by Phosphene's licence. That is an **additive** term under §3.6: it does+not modify, waive or conflict with any term of the LTX-2.x Community License+Agreement, which governs the weights and prevails in the event of any conflict.diff --git a/README.md b/README.mdindex c03f25f..b77a04b 100644--- a/README.md+++ b/README.md@@ -32,11 +32,11 @@ Key differences from the standard A2V path:</p>-> **Current release: v3.0.6.** Latest on the v3.0 line — character training, Audio-to-Video, the Image Studio tab, hardware capability tiering, and a run of stabilization fixes since launch.+> **Current release: v3.8.0.** Storyboard — describe a film in a sentence, get a shot list you can edit before anything renders. Also fixes the install failure that had been breaking every fresh install and every Update since hatchling 1.32.0 shipped. 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, no telemetry.+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.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.@@ -129,11 +129,15 @@ If you have a Hugging Face token, paste it under **Settings** in the panel. Down### Manual install```bash-# 1. Clone Phosphene + the upstream MLX port (pinned to v0.14.8).+# 1. Clone Phosphene + the MLX port (pinned to our LTX-2.5 fork build).git clone https://github.com/mrbizarro/phosphene.gitcd phosphenegit clone https://github.com/dgrauet/ltx-2-mlx.git ltx-2-mlx-cd ltx-2-mlx && git checkout v0.14.8 && cd ..+cd ltx-2-mlx+git remote add fork https://github.com/mrbizarro/ltx-2-mlx.git+git fetch fork feat/ltx-2.5+git checkout 871694ddaa09c1598d663a49005a2f91ae6b4ed2+cd ..# 2. Create the Python 3.11 venv inside ltx-2-mlx (uv-managed).cd ltx-2-mlx@@ -143,7 +147,11 @@ uv venv --python 3.11 --seed env# 0.31.2 attenuates the LTX vocoder by 22 dB../env/bin/uv pip install --python env/bin/python \'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1'+# --build-constraints pins hatchling below 1.32, which rejects upstream's+# `readme = "../../README.md"` and fails metadata generation. See+# pip-build-constraints.txt../env/bin/uv pip install --python env/bin/python \+ --build-constraints ../pip-build-constraints.txt \./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer./env/bin/uv pip install --python env/bin/python \pyyaml pydantic tqdm rich@@ -177,7 +185,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 `v0.14.8` — we track a known-good tag, never upstream `main`. `mflux 0.17.5` is the version `patch_mflux_fbcache.py` is line-targeted against.+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.## Interface@@ -229,7 +237,7 @@ Behavioral changes worth noting in 3.0:- `mlx_ltx_panel.py` is the panel HTTP server. One file, around 22k lines, with HTML, CSS, and JS inlined as the page string. Worker thread plus helper subprocess management plus capability tier detection.- `mlx_warm_helper.py` is the long-running inference subprocess. Holds T2V, I2V, Extend, HQ, and Keyframe pipelines. Reads job specs from stdin, emits events to stdout.- `image_engine.py` dispatches the Image tab. Backends `hidream`, `mflux`, `mock`. Each spawns its own subprocess with `start_new_session=True` so `/stop` kills the whole tree.-- `patch_ltx_codec.py` applies one idempotent runtime patch: lossless H.264 output (yuv444p). As of the v0.14.8 pin the memory-frees, VAE streaming, Metal-watchdog and frame_rate patches are all native upstream.+- `patch_ltx_codec.py` applies one idempotent runtime patch: lossless H.264 output (yuv444p). As of the v0.14.8 pin the memory-frees, VAE streaming, Metal-watchdog and frame_rate patches are all native upstream; the v0.14.19 pin keeps that shape — one edit, one line.- `lora_lab/` is vendored from the [`lora-lab`](https://github.com/mrbizarro/lora-lab) authoring tree. Training works out of the box; set `LTX_LORA_LAB_ROOT` to iterate against an external clone.- `mlx_models/` and `mlx_outputs/` both persist across Pinokio Reset via fs.link.@@ -269,4 +277,8 @@ Phosphene is free and open source.## Network note-Phosphene runs locally. No telemetry. A clean production install checks GitHub every 30 minutes for an update badge, and only touches Hugging Face or CivitAI when you download models or LoRAs. Disable the update check with `PHOSPHENE_DISABLE_VERSION_CHECK=1`. The panel binds to `127.0.0.1` with no auth. It's not designed for LAN exposure or tunneling.+Phosphene renders locally — no prompt, model input or output is ever uploaded. A clean production install makes three kinds of outbound request, and no others: it checks GitHub every 30 minutes for an update badge (disable with `PHOSPHENE_DISABLE_VERSION_CHECK=1`); it touches Hugging Face or CivitAI when you download models or LoRAs; and it sends anonymous usage counts — one event per panel start and one per finished render, carrying the panel version, a hardware class such as `M4 Max / 64 GB`, and render stats like engine, tier and a bucketed duration. Never content of any kind.++That last one is **on by default and the build ships a working key**, so a fresh clone does report. Every event and field is specified in [docs/ANALYTICS.md](docs/ANALYTICS.md), mirrored in plain text to `state/usage-log.jsonl` so you can read exactly what was sent, and switched off in one click in Settings → *Anonymous usage analytics* (or with `PHOSPHENE_ANALYTICS_DISABLED=1`).++The panel binds to `127.0.0.1` with no auth. It's not designed for LAN exposure or tunneling.diff --git a/VERSION b/VERSIONindex 7c69a55..1981190 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-3.7.0+3.8.0diff --git a/docs/ANALYTICS.md b/docs/ANALYTICS.mdindex 87f30f4..37bc813 100644--- a/docs/ANALYTICS.md+++ b/docs/ANALYTICS.md@@ -16,16 +16,38 @@ character names.| | ||---|---|| **What identifies you** | One random UUID, generated on your Mac, tied to nothing |-| **How often** | Once per panel start, plus once per finished render. No heartbeats |+| **How often** | Once ever when the install is new, once per panel start, plus once per finished render. No heartbeats || **Where it goes** | PostHog (`us.i.posthog.com`), or a self-hosted endpoint you choose |-| **How to turn it off** | Settings → *Anonymous usage analytics* → **Turn off** |-| **Default** | ON |-| **What you can inspect** | `state/usage-log.jsonl` — a plain-text copy of everything the panel would send |+| **Location** | None sent, and every event tells the receiver not to derive one from your IP — [details](#location) |+| **How to turn it off** | Settings → *Anonymous usage analytics* → **Turn off**, or `PHOSPHENE_ANALYTICS_DISABLED=1` |+| **Default** | ON, and the shipped build carries a working key — see below |+| **What you can inspect** | `state/usage-log.jsonl` — a plain-text copy of everything the panel sends || **Effect on renders** | None. Background thread, 2 s timeout, all failures ignored |-If no PostHog project key is configured, **the panel opens no network-connection at all** and only writes the local log. The public repo ships with-no key, so a fresh clone sends nothing until its owner configures one.+**The build you install ships a project key.** Phosphene is distributed as+source — you `git clone` it through Pinokio — so a key left empty in the+repository would never reach anyone and these counts would not exist. What is+committed, in `mlx_ltx_panel.py` as `ANALYTICS_KEY_DEFAULT`, is a PostHog+**project key** (`phc_…`): write-only and client-side by design. It can send+events. It cannot read one back, list anything, or change the project. Reading+the data needs a separate *personal* key, which is **not** in this repository.+Shipping a client key in the source is what PostHog documents these keys for —+so the thing worth checking is not that a key exists, it's what the panel does+with it, which is the rest of this page.++**A fresh clone therefore does send.** Clone it, run it, and it sends exactly+the events listed below and nothing else. The first time it ever runs, it says+so — one line, in the panel log, before you have read anything:++> `Phosphene sends anonymous usage counts (version, hardware class, render+> stats, error signatures - never your prompts or media). Disable in Settings.`++**Turning it off is the toggle, not the key.** Settings → *Anonymous usage+analytics* → **Turn off** stops the network calls *and* the local log;+`PHOSPHENE_ANALYTICS_DISABLED=1` does the same and beats the setting. Emptying+the project-key field does **not** silence the panel: that field is an override+for forks and self-hosters, and an empty override falls back to the shipped+key. Use the toggle.---@@ -33,7 +55,8 @@ no key, so a fresh clone sends nothing until its owner configures one.**Settings → Anonymous usage analytics → Turn off.** One click; no confirmstep. Turning it off stops the network calls *and* stops writing the local-log.+log — `_analytics_capture()` returns before it builds a payload, so there is+nothing left to send or mirror.Before the panel has ever written a settings file — or if you'd rather set itin your environment — use:@@ -44,6 +67,10 @@ PHOSPHENE_ANALYTICS_DISABLED=1That env var wins over the setting, always.+**Clearing the project key is not an off switch.** It is an override field: an+empty override resolves back to the key this build ships with. The two things+above are the off switches, and they are the only two.+---## What identifies you@@ -57,16 +84,70 @@ key (or the file) and this install becomes a brand-new anonymous install withno way to correlate it to the old one. The panel shows you the exact value inSettings.-**One caveat, stated plainly:** like any HTTP request, the ping arrives at-PostHog from your IP address, and PostHog derives a coarse country from it by-default. The panel neither adds location data nor suppresses that default. If-that matters to you, turn analytics off — or self-host the endpoint (below).+---++## Location++The panel sends no location field of any kind — no country, no city, no region,+no timezone, no coordinates, no locale. It never has.++That on its own is not the whole promise, because a receiver can *derive* a+location from where a request came from, and PostHog does that by default. So+every event now also carries two instructions telling it not to:++| Property | Value | What it does |+|---|---|---|+| `$geoip_disable` | `true` | PostHog's GeoIP step returns immediately instead of deriving country, city, subdivision, timezone and the city's coordinates |+| `$ip` | `"0.0.0.0"` | PostHog copies the connecting address into the event's `$ip` property only when the event didn't bring its own. Bringing one keeps the real address off the stored event |++**What that does not do, said plainly:** the request still arrives over TCP from+a real address, and nothing inside a request body can change that — that is how+HTTP works, for this panel and for every other program on your Mac. What the+two flags control is what the receiver is instructed to *derive* from that+address and *store* on the event. Discarding it at the edge as well is a+setting on the receiving project, not something this source tree can promise+you, so this page does not.++If you want the connection itself gone: turn analytics off, or point+`PHOSPHENE_ANALYTICS_HOST` at a receiver you run (below).++**A note on `0.0.0.0`, since it looks arbitrary.** The obvious spelling —+sending `$ip: null` — does nothing at all: PostHog's ingest fills the property+in when the event's value is *falsy*, so a null is silently replaced by your+real address. It has to be a non-empty string. `127.0.0.1` would be the natural+choice and is the wrong one: PostHog rewrites loopback and `192.168.*` to a real+address in Sweden as a local-development convenience, which would invent a+location the day the disable flag ever went missing.---## Events-Six event types. That's the whole list.+Five events. That's the whole list. (A sixth is described at the end because+people expect it — it is documented as the thing we deliberately don't send.)++### `app_installed`++Once per install, **ever** — fired on the first boot that an install id+reports, immediately before its first `app_boot`.++| Field | Type | Example | Notes |+|---|---|---|---|+| `version` | string | `"3.7.0"` | Which release a new install actually landed on |+| `chip_family` | string | `"M4 Max"` | Same hardware *class* as on `app_boot` |+| `ram_gb` | int | `64` | Unified memory, rounded to whole GB |++**Why it exists:** it is the denominator. Without it, "new installs over time"+has to be reverse-engineered from first-sightings of unique install ids, which+is both fiddly and worse for you — it is the shape of question that tempts+someone to start profiling ids. One counter answers it instead.++**Once-ever, and how:** a boolean `analytics_install_reported` is written to+`state/panel_settings.json` the moment the event is captured, and it is checked+before every subsequent boot. Rebooting the panel never re-counts. Deleting+your install id (or the settings file) makes a genuinely new install, which+reports its own `app_installed` once — that is the same "no way to correlate it+to the old one" property described above, not a loophole in it.### `app_boot`@@ -172,8 +253,9 @@ code path that reads a rendered file for analytics purposes.## The local log-Every captured event is also appended to **`state/usage-log.jsonl`**, whether-or not a PostHog key is configured. One JSON object per line:+Every captured event is appended to **`state/usage-log.jsonl`** *before* the+network is touched, and independently of whether the send then succeeds. One+JSON object per line:```json{"event":"render_completed","props":{"engine":"ltx","mode":"t2v","tier":"standard","duration_bucket":"2-5m","resolution":"1216x704","frames":121},"install_id":"…","ts":1754400000.0,"at":"2026-08-05 17:40:00","utc":"2026-08-05T14:40:00Z"}@@ -181,7 +263,8 @@ or not a PostHog key is configured. One JSON object per line:Two reasons it exists: it's the "this machine" data source for the Usagesection of the stats dashboard, and it means you never have to take this-document's word for anything — you can read exactly what the panel would send.+document's word for anything — you can read exactly what the panel sent, line+for line, after the fact.The file is capped at **5 MB**; at the cap the oldest half is dropped. It'sgitignored (both via `state/` and by basename) and never leaves your Mac.@@ -190,21 +273,26 @@ gitignored (both via `state/` and by basename) and never leaves your Mac.## Owner setup — activating this-Both keys are pasted in **Settings → Anonymous usage analytics → Maintainer /-self-hosting keys**. Neither is committed; both live in-`state/panel_settings.json` (mode `0600`).+Both key fields live in **Settings → Anonymous usage analytics → Maintainer /+self-hosting keys**, and are stored in `state/panel_settings.json` (mode+`0600`). One of the two keys is committed and one must never be — that+asymmetry is the whole design.-### 1. Turn the pings on — PostHog **Project API key**+### 1. The capture key — PostHog **Project API key** (shipped)-PostHog → *Project settings* → *Project API key* (starts `phc_…`). This key is-write-only and safe to hold on disk.+PostHog → *Project settings* → *Project API key* (starts `phc_…`). Write-only:+it can send events and do nothing else, which is why it is safe to hold on disk+and safe to commit. **Phosphene's own project key is already in the source** as+`ANALYTICS_KEY_DEFAULT`, and it is what a stock install reports with.-Paste it into **PostHog project key (capture)**. Until this is set,-`ANALYTICS_KEY_DEFAULT` is `""` and the panel opens **no socket at all**.+Paste a different one into **PostHog project key (capture)** to point a fork at+its own project. That field *overrides* the shipped key; clearing it falls back+to the shipped key rather than switching capture off. To send nothing, use the+toggle or `PHOSPHENE_ANALYTICS_DISABLED=1`.Env override: `PHOSPHENE_ANALYTICS_KEY`.-### 2. Turn the fleet dashboard on — PostHog **Personal API key**+### 2. The read key — PostHog **Personal API key** (never committed)PostHog → *Personal settings* → *Personal API keys* → create one with **read**scope on the project (starts `phx_…`).@@ -256,11 +344,19 @@ data with a visible warning.**Why default ON.** An opt-in version of this shipped on 2026-05-21 and wasreverted the next day (`da1d6f5`). It was off by default, which meant it wouldhave told us nothing even if it had stayed. The trade this version makes-instead: default ON, but a far smaller payload, a visible one-line disclosure-in the boot log the first time it runs, a one-click off switch, a readable-local copy of every event, and — crucially — **inert in the public tree**, so-anyone who clones the repo and never configures a key is unaffected either-way.+instead: default ON *with a key that really ships*, paid for by a far smaller+payload, a one-line disclosure in the boot log the first time it runs, a+one-click off switch that stops the local log too, and a plain-text copy on+your own disk of every event that leaves.++**A correction, recorded rather than quietly fixed.** Until 2026-08-12 this+page said the public repo shipped no key and that a fresh clone sent nothing.+That stopped being true on 2026-08-09 (`acfbdc7`), when the project key was+committed on purpose — and the page kept saying it for three days. Nothing+extra was ever collected; the page was simply wrong about the default, which+for a page whose entire job is being checkable is the worse kind of wrong.+Adding an event or a field is a documentation change first: if `ANALYTICS.md`+and the dry-run suite aren't in the same commit, the commit is incomplete.**Why it can't break a render.** `_analytics_capture()` builds the payload,starts a daemon thread and returns. Delivery has a 2-second timeout and a bare@@ -283,10 +379,14 @@ passes through, so a future engine is counted for free.python3 scripts/test_analytics_dryrun.py```-35 tests covering: inert-without-a-key, nothing-written-when-disabled, the-exact field set of every event, prompt/path non-leakage (including a prompt-quoted inside an exception), forbidden-key dropping, bucketing, log rotation-and the local aggregates.+43 tests covering: the shipped key is a write-only `phc_` project key and is+really the one that goes on the wire, the toggle and the env kill-switch each+produce zero sockets *and* zero log lines, the exact field set of every event,+every event name the panel can fire is documented on this page, prompt/path+non-leakage (including a prompt quoted inside an exception), forbidden-key+dropping, the geo-disable and `$ip` flags riding on *every* event type and+being un-overridable by a call site, bucketing, log rotation and the local+aggregates.To watch it live, tail the local log while you render:diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.mdindex e22e526..9791add 100644--- a/docs/RELEASE_CHECKLIST.md+++ b/docs/RELEASE_CHECKLIST.md@@ -43,6 +43,44 @@ mosaic was a missing `spatial_upscaler_x2_v1_1.safetensors` in the Q4 downloadif you touch `required_files.json` / `install.js` / `update.js` model lists,re-confirm a fresh Q4 install pulls it.+## 3b. Weight mirror — the packs GitHub carries, not HuggingFace++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, so+unlike an `hf download` repo **nothing publishes them but us** — and a pack that+is 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.++If you touched a mirrored pack's contents, its file list, or its `tag`:++```+python3 scripts/publish_pack_release.py --repo-key <key> --dry-run # rehearse+python3 scripts/publish_pack_release.py --repo-key <key> \+ --tag <tag> --release-repo mrbizarro/Phosphene --target <PUBLIC-MAIN-SHA> \+ --license LICENSES/LTX-2.x-Community-License.md \+ --notice LICENSES/NOTICE-ltx25-weights.md+```++**The tag goes on a PUBLIC `main` commit, never a dev/beta one** — check with+`gh api repos/mrbizarro/Phosphene/commits/main --jq .sha` first. The publisher+refuses a pack missing anything `required_files.json` calls mandatory; do not+work around that refusal, it is the guard against shipping a pack the panel+reports incomplete on arrival.++Then prove it from zero, into an **empty** directory, against the real release:++```+ltx-2-mlx/env/bin/python3.11 scripts/fetch_pack_release.py \+ --repo-key <key> --dest /tmp/from-zero/<pack>+ltx-2-mlx/env/bin/python3.11 scripts/fetch_pack_release.py \+ --repo-key <key> --dest /tmp/from-zero/<pack> --check-only+```++Exit 0 on both. For a DiT pack, finish with a real loader round-trip on the+reassembled transformer (`verify_load_ltx_dit` in `scripts/quantize_ltx.py`) —+sha256 proves the bytes arrived, only the loader proves they are a model.+## 4. Version + compile```diff --git a/docs/STATE.md b/docs/STATE.mdindex d23f10f..eaa22a3 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,6 +1,26 @@# Phosphene — project state, history, open work-**Public release: `v3.1.1`.** 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: `v3.8.0`** (see the v3.8.0 CHANGELOG entry 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.++> **🌍 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.+>+> - **`$geoip_disable: True` — real, and the only payload-level mechanism there is.** Verified against PostHog's own ingest source rather than assumed: the GeoIP transformation's first statement is `if (event.properties?.$geoip_disable or empty(event.properties?.$ip))`, and `$geoip_disable` is the same property `posthog-python` sets for `disable_geoip=True` (it is on that SDK's `$`-property allowlist).+> - **`$ip: None` — THE SPEC WAS WRONG, and it is the finding worth remembering.** The spec (§2.8) and the Phase 0 handoff both prescribed `"$ip": None`. **It does nothing.** PostHog's ingest fills the property from the socket with `if (!properties['$ip'] && event.ip) properties['$ip'] = event.ip` — `null` is *falsy*, so it is the default with extra steps and the real address lands on the event anyway. There is also **no top-level `ip` field** to set: `RawEvent` in `rust/common/types/src/event.rs` has `token / distinct_id / uuid / event / properties / timestamp / offset / $set / $set_once` and nothing else, so an `"ip"` key beside `"event"` is deserialised into the void. The working version is a **truthy** placeholder: `ANALYTICS_IP_PLACEHOLDER = "0.0.0.0"`, which occupies the property so the connecting address is never written onto the stored event.+> - **Why `0.0.0.0` and not `127.0.0.1`.** The GeoIP transformation rewrites loopback and `192.168.*` to a real address in Sweden as a local-dev convenience — a loopback placeholder would *manufacture* a location the day the disable flag went missing. The constant carries that reasoning inline so nobody "tidies" it.+> - **What is NOT claimed anywhere.** The request still arrives over TCP from a real address and no field inside a body changes that. `docs/ANALYTICS.md` now has a **Location** section that says exactly that, in those words, and stops: the flags control what the receiver is instructed to *derive* and *store*, and discarding it at the edge is a project-side setting this source tree cannot promise. Phase 0's lesson — never document more than the code does — applied to its own follow-up.+> - **Suite 38 → 43 GREEN, and it fires EVERY event type.** New `TestReceiverDirectives`: all three directives intact on `app_installed` / `app_boot` / `pack_state_change` / `render_completed` / `render_failed`, with a coverage guard that re-reads `_analytics_capture("…")` call sites out of the source so a sixth event type cannot be added and go unchecked; no `$geoip_*` key but the disable flag and no `country`/`city`/`latitude`/`timezone` substring anywhere in a body; the placeholder is truthy and is neither trap value; a call site passing `$geoip_disable: False` loses; and the local mirror stays free of transport plumbing. `props_of()` now fails on any **undeclared** `$` key rather than ignoring it.+> - **Mutation-tested — 7/7 red.** Drop `$geoip_disable`; `$ip = None`; `$ip = "127.0.0.1"`; drop `$ip`; drop `$process_person_profile`; spread the directives FIRST so props win; smuggle a `$geoip_country_code` onto a payload. Each turns the matching test red and the suite restores clean.+> - **Owner action, deliberately not claimed as done:** PostHog project settings → *IP data capture* → **discard** (org-level default also exists), so the promise survives a payload flag ever being missed; and eyeball one live event for absent `$geoip_*`. Nothing in the repo asserts either.+> - **Still open** (schema v2): `error_class` replacing free-text `error_signature` (migrate `top_errors` in the same commit), version/chip context on render events, `update_state`, `wall_sec_bucket`, Phases 5–8.++> **🔦 2026-08-12 — ANALYTICS TRUTH PASS: the transparency doc had been lying for three days, and the guard suite that was supposed to stop that was RED.** No behaviour changed — this is docs, comments and tests only. `acfbdc7` (2026-08-09) committed the live `phc_` project key on purpose and correctly; what it did not do was update the page whose entire value is that a suspicious user can check it. So `docs/ANALYTICS.md` still promised *"The public repo ships with no key, so a fresh clone sends nothing until its owner configures one"* while every fresh clone reported from first boot. **README.md was worse** — "No telemetry", twice, on the front page, where a reader who never opens `ANALYTICS.md` would stop.+>+> - **The claim is extinct repo-wide** (11 sites): `docs/ANALYTICS.md` (the short-version paragraph, the owner-setup section, the design note), `README.md` ×2, seven comment/copy sites in `mlx_ltx_panel.py` — the module header's `INERT BY DEFAULT IN THE PUBLIC TREE` bullet, `_analytics_key()`'s docstring, `_analytics_enabled()`'s docstring, both settings-default comments, `update_settings()`'s "returns the panel to fully-inert", the `_analytics_post` early return, the `__main__` call-site — plus the Settings modal `<details>` copy. A grep sweep for the claim's whole vocabulary (`inert`, `no key`, `opens no`, `no socket`, `sends nothing`, `no telemetry`, `public tree`) returns only true statements and the one paragraph that describes the correction.+> - **A SECOND false claim was nearly shipped, and is the finding worth remembering.** The analytics spec's own replacement draft said *"Clear the key in Settings and the panel opens no socket at all."* **It doesn't.** `_analytics_key()` resolves `saved or ANALYTICS_KEY_DEFAULT`, so an empty Settings field is *no override*, not *off*, and a user who "cleared the key" is still reporting. Verified empirically before anything was written (sockets counted against a spied `urlopen`). Every surface now says the same thing: **the toggle and `PHOSPHENE_ANALYTICS_DISABLED=1` are the off switches, and they are the only two.** If that fallback is ever changed to make an empty field mean off, the doc changes in the same commit — there is now a test pinning it.+> - **`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.> **🎬 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."*>@@ -80,12 +100,12 @@>> **Public hotfix?** Judgement: **ride v3.4.1**, don't emergency-patch v3.4.0. It is a discoverability/labelling failure, not data loss (nothing is deleted, no render is corrupted), the workaround is one sidebar click, and H3 is a 64 GB-only opt-in pack so the blast radius is small. But v3.4.1 should ship **soon** rather than waiting to accumulate — every affected user currently reads this as "I lost my 75 GB download".-> **📈 2026-08-05 — anonymous usage analytics on `dev`/`beta` (NOT public, and INERT until a key is pasted).** The counterpart to the H3-vanish fix above: that bug existed in the field for days and we only learned about it because one user wrote in. `pack_state_change` is the detector for exactly that class — a pack going `true → false` between boots is a broken install, and the Usage section of `/stats` now surfaces the count in red.+> **📈 2026-08-05 — anonymous usage analytics on `dev`/`beta` (NOT public, and INERT until a key is pasted).** ⚠️ **THIS WHOLE ENTRY IS SUPERSEDED** — the "inert / no key / a fresh clone sends nothing" posture below was true when written and was deliberately reversed by `acfbdc7` on 2026-08-09. Read the 2026-08-12 truth-pass entry at the top of this file for what is true now, including the 35/35 validation line further down (the suite is 38/38 and its no-key tests were rewritten). The counterpart to the H3-vanish fix above: that bug existed in the field for days and we only learned about it because one user wrote in. `pack_state_change` is the detector for exactly that class — a pack going `true → false` between boots is a broken install, and the Usage section of `/stats` now surfaces the count in red.>> **Read `docs/ANALYTICS.md`** — it is the complete schema (every event, every field) and the owner-activation instructions.>> - **Five events, counts only.** `app_boot` (version, os_version major.minor, chip_family parsed to `M4 Max`, ram_gb, cap_tier, `packs{h3,sharp,q8,qwen}`, h3_chain_supported) · `render_completed` / `render_failed` (engine, mode, tier, bucketed duration, resolution, frames, + a scrubbed `error_signature` on failure) · `pack_state_change` (pack, from, to). No prompts, filenames, paths, media, seeds, LoRA or character names. `engine_selected` was deliberately **dropped** — it would add a request path to a click that currently has none, and `engine` on every render event answers the same question.-> - **Inert in the public tree.** `ANALYTICS_KEY_DEFAULT = ""`, and an empty key means **no socket is ever opened** — not "a request that fails". A fresh clone sends nothing, forever, until the owner pastes a PostHog project key. This is the property that makes shipping it defensible after the 2026-05 opt-in module was reverted (`da1d6f5`, "not going to be well accepted in the open source world").+> - **Inert in the public tree.** `ANALYTICS_KEY_DEFAULT = ""`, and an empty key means **no socket is ever opened** — not "a request that fails". A fresh clone sends nothing, forever, until the owner pastes a PostHog project key. This is the property that makes shipping it defensible after the 2026-05 opt-in module was reverted (`da1d6f5`, "not going to be well accepted in the open source world"). — **⚠️ SUPERSEDED 2026-08-09 by `acfbdc7`**, which committed the live `phc_` key on purpose: a stock install now reports, and the off switch is the Settings toggle (clearing the key field falls back to the shipped default). True as written on 2026-08-05; left standing as the record, corrected in the 2026-08-12 truth-pass entry at the top of this file.> - **Cannot touch a render.** Capture builds the payload, starts a daemon thread, returns. 2 s timeout, bare `except: pass` around the whole delivery path, no retries, no queue, no heartbeats, no background timers. Wired at exactly two call sites: `_analytics_boot()` in `__main__` (never at import time) and `_analytics_render_event()` in `worker_loop`'s `finally` — the one point every job from every engine passes through.> - **Visible + reversible.** One-line ASCII disclosure in the boot log on first run; Settings → *Anonymous usage analytics*, default **ON**, one click off (no confirm dance — turning it off must be easier than leaving it on). `PHOSPHENE_ANALYTICS_DISABLED=1` beats the setting. A legacy `analytics_enabled: false` from the reverted May module is preserved by `setdefault`, so that user's opt-out is honoured rather than silently flipped back on.> - **Local mirror + the dashboard.** Every captured event also appends to gitignored `state/usage-log.jsonl` (5 MB cap, oldest half dropped) — the always-works "this machine" data source *and* a plain-text record of exactly what the panel would transmit. New `GET /stats/usage` (127.0.0.1-only like the rest) serves local aggregates, and upgrades to fleet-wide numbers when a PostHog **personal** API key is configured (ten read-only HogQL SELECTs, cached to `state/usage-fleet.json` for 6 h, per-query failure isolated). New **Usage** section in `panel_assets/stats.html` in the same card/KPI language as the GitHub sections: 4 headline tiles, top-5 error signatures, version/chip/memory distributions, and the pack-regression alert.@@ -95,7 +115,7 @@> **🎛 2026-08-05 — H3 selectable sampler depth on `dev`/`beta` (`ae298da`): Steps pills Auto / 12 / 16 / 20.** Asked for by @ivanfioravanti ("Have you updated UI too (selectable number of steps?)"), who runs the official 20-step recipe. Tiers keep baking the validated 9-step point as **Auto**; a pinned depth rides the SAME params path the tier default does — `make_job` parses `h3_steps` (auto/garbage → 0-sentinel, ints clamped 4–30), stamps the resolved count into `steps`, and keeps `h3_steps` alongside so the ⓘ modal can print "tier default overridden". `run_h3_job_inner` needed **zero** changes (it already read `p["steps"] or tier["steps"]`). UI: a Steps row under Export in the H3 strip (same pill language), time-cost multipliers in the tooltips (~×1.4/×1.9/×2.4 = (N−1)/8 forwards), survives tier switches + engine swaps + reloads (`phos_h3_steps` localStorage, restored in `_restoreH3TierEarly`), mirrored into the shared hidden `steps` so the queue card/estimate stay honest, shown in the Customize summary only when pinned. Validated: `py_compile`, `node --check` on the extracted inline script, and 8/8 `make_job` unit cases (override / auto / absent / clamp-high / clamp-low / garbage / chained-tier override / LTX isolation). Live click-through deferred with the other panel gates (Codex GPU campaign holds the box). This is the first slice of the promised Ivan "advanced mode" — larger canvases stay with the quality campaign.-> **📦 2026-08-05 — v3.4.2 SHIPPED PUBLIC** (same-day follow-up to v3.4.1): H3 **Steps pills** (Auto/12/16/20 — asked by @ivanfioravanti, who runs the official 20-step recipe), the whole triage sweep below (#45 #44 #48 #36 #35 fixes), the LTX/H3 venv **self-heal** hardening from the field-regression class, and the analytics groundwork — **fully inert in the public build**: `ANALYTICS_KEY_DEFAULT=""` means no socket is ever opened; nothing is sent by any public install unless a maintainer key is deliberately baked in. Deferred (GPU still owned by the quality campaign): live click-throughs of the steps pills, #44 fallback on a real M1, #48 end-to-end extend chain, and the fresh-Pinokio-install pass — same owner-accepted residual-risk posture as v3.4.1; treat any fresh-install report as hotfix priority.+> **📦 2026-08-05 — v3.4.2 SHIPPED PUBLIC** (same-day follow-up to v3.4.1): H3 **Steps pills** (Auto/12/16/20 — asked by @ivanfioravanti, who runs the official 20-step recipe), the whole triage sweep below (#45 #44 #48 #36 #35 fixes), the LTX/H3 venv **self-heal** hardening from the field-regression class, and the analytics groundwork — **fully inert in the public build**: `ANALYTICS_KEY_DEFAULT=""` means no socket is ever opened; nothing is sent by any public install unless a maintainer key is deliberately baked in. (**⚠️ SUPERSEDED** — true of v3.4.2 as shipped; `acfbdc7` deliberately baked the key in on 2026-08-09. See the 2026-08-12 truth-pass entry at the top.) Deferred (GPU still owned by the quality campaign): live click-throughs of the steps pills, #44 fallback on a real M1, #48 end-to-end extend chain, and the fresh-Pinokio-install pass — same owner-accepted residual-risk posture as v3.4.1; treat any fresh-install report as hotfix priority.> **🧹 2026-08-05 — FULL GitHub triage sweep (5 parallel agents, 6 commits on `dev`/`beta`, all 12 open issues handled).** Every open issue answered as the maintainer; 4 closed (#43 #34 stale-blank, #45 fixed, #47 answered, #36 implemented), 8 kept open with substantive replies. Commits, in order:> - `2f5ab92` **#45 LoRA strength bar** — `#genForm` ID-specificity beat the compact row styles (readout became an unreadable sliver behind the spin button) + the range never got the chrome reset. CLOSED.@@ -715,6 +735,65 @@ Reconciled against the deep review (2026-05-31). Everything that was a recent fi### CHANGELOG (historical — what was fixed, newest first)+> **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.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.+- **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.+#### 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`).- **CivitAI token-leak fix** — downloader leaked the API token on redirect + used a weak `endswith("civitai.com")` host check. Exact-host allowlist + redirect handler that strips `Authorization`; prefer header over `?token=`.diff --git a/install.js b/install.jsindex f995272..b8e5429 100644--- a/install.js+++ b/install.js@@ -106,19 +106,37 @@ module.exports = {next: null},- // ---- ltx-2-mlx version: PIN to v0.14.8 (2026-06-01 catch-up). dgrauet asked on 2026-05-12- // to lock onto a tag because he's about to push breaking changes+ // ---- ltx-2-mlx version: PIN to v0.14.19 (2026-08-11 catch-up). dgrauet asked on+ // 2026-05-12 to lock onto a tag because he pushes breaking changes// upstream to sync with the official Lightricks repo. Without a// tag pin, every fresh install (and every Update) would pull the// next breaking push and Phosphene would fail to start.//- // v0.14.8 is the pinned tag against which the current panel +- // helper + patch_ltx_codec.py were validated (2026-06-01 catch-up- // from v0.14.0). The bump pulled dgrauet's native fixes —- // `_pre_denoise_flush` (the Metal-watchdog fix that resolves the- // I2V "mosaic" on memory-pressured Macs, #17), budget-aware VAE- // decode tiling, and first-class `frame_rate` — which let us DROP- // 6 of our 7 runtime patches (only the lossless-codec patch remains).+ // v0.14.19 is the pinned tag against which the current panel ++ // helper + patch_ltx_codec.py are validated (2026-08-11 catch-up+ // from v0.14.8, 11 releases). What it brings, in the order it+ // matters to us:+ // - 0.14.11 — the AV cross-attention gate is finally read FROM the+ // checkpoint (`av_ca_timestep_scale_multiplier` 1000, not the+ // dataclass default 1). Audio/dialogue weighting changes for+ // every render, toward upstream parity. This also lands+ // `LTXModelConfig.from_checkpoint_dir()` — a metadata-driven+ // config path we need for any second model generation.+ // - 0.14.15 — `frame_rate` forwarded at the A2V/lipdub call sites+ // (our `_install_a2v_frame_rate_patch` shim is now inert there),+ // and muxed video is no longer truncated to the shortest stream.+ // - 0.14.16 — quantized transformers load at ANY group_size, not+ // just 64; ic-lora dev mode fuses the distilled LoRA correctly.+ // - 0.14.19 — macOS GPU-watchdog kills are explained instead of+ // dying cryptically; the DiT is freed before VAE decode in+ // low-memory mode; the Gemma encoder stops widening a stricter+ // cache limit.+ // Weight layout is UNCHANGED by this bump. 0.14.13+ prefers a+ // versioned `transformer-distilled-*.safetensors` when one exists+ // and falls back to the unversioned name — our shipped model dirs+ // have no `-1.1` files (update.js trims them), so resolution is+ // byte-identical to v0.14.8. No re-download, no manifest change.+ //// STAY PINNED here: do not auto-track upstream main. Tag-bumps are a// deliberate decision — read his release notes, smoke-test the full// modality matrix on dev, bump `_LTX_EXPECTED_VERSION` in@@ -126,13 +144,36 @@ 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+ // 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+ // go back to a tag.+ //+ // This is what lets LTX-2.5 render THROUGH the panel. v0.14.19 could+ // register the 2.5 packs but never load them: it does not build+ // keyframes_abs_pos_embedding and cannot construct a Gemma 4 tower.+ //+ // 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.+ //+ // The packages report `0.14.19+ltx25.1`, 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.{method: "shell.run",params: {path: "ltx-2-mlx",message: ["git fetch --tags origin",- "git checkout v0.14.8",+ "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",+ "git checkout 871694ddaa09c1598d663a49005a2f91ae6b4ed2","git rev-parse --short HEAD"]}@@ -290,7 +331,17 @@ module.exports = {// the venv, the trainer subprocess fails at `import yaml` because// pyyaml is a transitive dep of ltx-trainer (declared in its// pyproject). Codex pre-ship review 2026-05-18 caught this.- "uv pip install --python env/bin/python ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer",+ //+ // `--build-constraints ../pip-build-constraints.txt` pins the wheel+ // BUILD backend (hatchling<1.32). Upstream's three pyprojects all+ // 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). 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.+ "uv pip install --python env/bin/python --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)diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex c39541f..ded18b8 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -56,6 +56,15 @@ import image_engine as agent_image_engine# serializer (ideoBuildCaption / ideoSynthDesc / ideoRectToBbox).import ideogram_caption+# Storyboard — the layer ABOVE the video modes: one concept in, a film's worth+# of shots out. `storyboard` is the spine (schema, validation, scheduling,+# durable state) and is deliberately pure-stdlib and model-free, so it unit-tests+# with no GPU and no weights. `storyboard_planner` is the brain and spawns a+# short-lived child that loads a small LLM, writes the plan and dies — it never+# loads a model in THIS process. Both are 3.9-compatible because the panel is.+import storyboard+import storyboard_planner+# --- Paths -------------------------------------------------------------------# Everything below is overridable via env vars so the panel can be cloned and# run from any directory without source edits. Defaults assume the repo layout:@@ -239,6 +248,229 @@ _REQUIRED = _load_required_files()_MIN_FILE_BYTES = int(_REQUIRED.get("min_size_bytes", 1024))+# ---- model-version registry --------------------------------------------------+# ONE entry per LTX generation. Everything that needs to know "which weights,+# in which folder, complete or not, and what can this generation actually do"+# reads THIS table — job dispatch, the download/completeness checks, and the+# env the warm helper is spawned with. Registering LTX-2.5 is meant to be one+# entry here plus its `required_files.json` repos, not a scavenger hunt.+#+# WHY this exists (the June-2026 mosaic, in one paragraph): the panel was built+# around exactly one model version. `MODEL_ID` was a module-level singleton+# resolved at import; the Q8 folder was reached by a bare `Q8_LOCAL_PATH`+# constant at eight job-spec sites; the Q4 folder was reached at four more by+# the *string literal* "ltx-2.3-mlx-q4"; and "is it installed" was a q8-keyed+# special case inside `repo_status_list()`. A single 1 GB upscaler dropped out+# of one `download_include` list produced a randomly-initialised module and two+# weeks of rainbow-grid renders across three wrong theories. A second version+# multiplies every one of those surfaces, so they are funnelled through here+# first.+#+# Field contract per version:+# id stable key. Wire format — goes in sidecars and env, so it+# may never be renamed once a render has carried it.+# label what a human sees ("LTX-2.3"). Mirrors the ENGINES label.+# engine_id which entry in ENGINES serves this version.+# config_key the vendored ltx-2-mlx model-config generation key. 2.5+# makes the vendored lib metadata-driven; this is the value+# handed to it (and the thing to grep for when a checkpoint+# loads with the wrong hyperparameters).+# default exactly one version carries True.+# cap_tiers which FEATURE tiers this version can serve. This is the+# generalisation of the old binary `cap_tier`: a version that+# ships q4 weights only declares ("q4",) and the whole Q8+# surface (FFLF / Extend / High) folds away for it, on ANY+# machine, without a second CSS system.+# packs one per quantisation. `repo_key` points into+# required_files.json — deliberately a REFERENCE, not a copy:+# that file stays the single source of truth for the file list+# AND the `download_include` allowlist, so the two can never+# disagree the way they did in June. `path` is the resolved+# on-disk directory (honouring the same env overrides the old+# constants did). `serves_cap_tiers` is which feature tiers may+# load this pack. `verify_source` is where /models/verify-deep+# gets the expected SHA-256 for this pack (see below).+#+# verify_source — "hf-api" | "manifest"+# "hf-api" the pack lives on HuggingFace and its LFS metadata carries the+# published sha256. This is how every 2.3 pack has always been+# verified and it is the default for anything not registered.+# "manifest" the pack is mirrored somewhere with no checksum API of its own+# — GitHub releases, the lane the 2.5 packs take because their+# upstream is gated and we publish our own quantisation. The+# expected hashes travel WITH the weights in+# `phosphene_quant_manifest.json`, which scripts/quantize_ltx.py+# already emits (deterministically — that is what makes a+# published manifest meaningful). Without this a mirrored pack+# would report every file "unverified", which is exactly the+# blind spot the mosaic lived in for two weeks.+#+# The two path constants above (Q4_LOCAL_PATH / Q8_LOCAL_PATH) remain the+# INPUTS to the 2.3 entry rather than being replaced by it, so every existing+# env override (LTX_MODEL, LTX_Q8_LOCAL) keeps working byte-for-byte.+MODEL_VERSIONS: tuple[dict, ...] = (+ {+ "id": "ltx23",+ "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,+ "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+ # fine-tune. Naming it here for the same reason the DiT packs are+ # named here: the alternative is a module-level constant that+ # silently describes whichever generation happened to be first.+ "text_encoder": {"repo_key": "gemma", "path": GEMMA},+ # The two files the dev-transformer feature surface (High / Extend /+ # Keyframe / A2V) loads BY NAME out of the hq pack.+ #+ # `dev_transformer` is generation-invariant only because WE choose it:+ # scripts/convert_ltx_mlx.py's --transformer-stem names the output, and+ # we name both generations' dev file the same thing. It is stated here+ # anyway so a generation that renames it has one place to say so.+ #+ # `distilled_lora` is NOT invariant, and that is the whole reason this+ # block exists. The number in the filename is the LoRA's alpha/rank+ # (2.3's file declares lora_alpha == lora_rank == 384; 2.5's declares+ # 450), so the name changes with the generation. Until now the panel+ # never passed it and the vendored TI2VidTwoStagesPipeline's own+ # default — the literal 2.3 string — supplied it. That default is an+ # upstream constant we do not control, aimed at a file a 2.5 pack does+ # not contain, and the failure is a FileNotFoundError mid-render, after+ # the user has waited for Gemma. Naming it per generation here is the+ # same seam `model_dir` already is.+ "hq_weights": {+ "dev_transformer": "transformer-dev.safetensors",+ "distilled_lora": "ltx-2.3-22b-distilled-lora-384.safetensors",+ },+ "packs": (+ {+ "quant": "q4",+ "role": "base",+ "repo_key": "q4",+ "path": Q4_LOCAL_PATH,+ "hf_repo_id": "dgrauet/ltx-2.3-mlx-q4",+ "serves_cap_tiers": ("q4", "q8"),+ "verify_source": "hf-api",+ },+ {+ "quant": "q8",+ "role": "hq",+ "repo_key": "q8",+ "path": Q8_LOCAL_PATH,+ "hf_repo_id": MODEL_ID_HQ,+ "serves_cap_tiers": ("q8",),+ "verify_source": "hf-api",+ },+ ),+ },+ # --- 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.+)++# Which version this panel is driving. Env override exists so a 2.5 pack can+# be exercised side-by-side before it becomes the default; an unknown value+# falls back to the registry default rather than taking the panel down.+_MODEL_VERSION_ENV = (os.environ.get("LTX_MODEL_VERSION", "") or "").strip()+++def default_model_version_id() -> str:+ for v in MODEL_VERSIONS:+ if v.get("default"):+ return v["id"]+ return MODEL_VERSIONS[0]["id"]+++def model_version(version_id: str | None = None) -> dict:+ """The registry entry for `version_id` (None → the active version)."""+ wanted = version_id or ACTIVE_MODEL_VERSION+ for v in MODEL_VERSIONS:+ if v["id"] == wanted:+ return v+ for v in MODEL_VERSIONS:+ if v.get("default"):+ return v+ return MODEL_VERSIONS[0]+++ACTIVE_MODEL_VERSION = (+ _MODEL_VERSION_ENV+ if any(v["id"] == _MODEL_VERSION_ENV for v in MODEL_VERSIONS)+ else default_model_version_id()+)+if _MODEL_VERSION_ENV and _MODEL_VERSION_ENV != ACTIVE_MODEL_VERSION:+ sys.stderr.write(+ f"WARN: LTX_MODEL_VERSION={_MODEL_VERSION_ENV!r} is not a registered "+ f"model version; falling back to {ACTIVE_MODEL_VERSION!r}. Known: "+ f"{', '.join(v['id'] for v in MODEL_VERSIONS)}\n"+ )+++def version_pack(quant: str, version_id: str | None = None) -> dict | None:+ """The pack entry for one quantisation of one version, or None."""+ for p in model_version(version_id).get("packs", ()):+ if p["quant"] == quant:+ return p+ return None+++def pack_path(quant: str, version_id: str | None = None) -> Path:+ """On-disk directory for (version, quant). Falls back to the models root+ so a caller that asks for a pack this version doesn't ship still gets a+ path it can report rather than a None it will crash on."""+ pack = version_pack(quant, version_id)+ return Path(pack["path"]) if pack else MODELS_DIR+++def pack_repo(quant: str, version_id: str | None = None) -> dict | None:+ """The required_files.json repo entry backing (version, quant)."""+ pack = version_pack(quant, version_id)+ if not pack:+ return None+ for r in _REQUIRED.get("repos", []):+ if r.get("key") == pack["repo_key"]:+ return r+ return None+++def _quant_for_repo_key(repo_key: str | None,+ version_id: str | None = None) -> str | None:+ """Reverse lookup: which pack of this version does a required_files.json+ repo key back? None for repos that aren't model packs at all (gemma, the+ IC-LoRAs). Lets repo-shaped code ask the registry without knowing the+ version's pack names."""+ if not repo_key:+ return None+ for p in model_version(version_id).get("packs", ()):+ if p.get("repo_key") == repo_key:+ return p["quant"]+ return None+++def version_cap_tiers(version_id: str | None = None) -> tuple[str, ...]:+ return tuple(model_version(version_id).get("cap_tiers", ("q4",)))+++def version_quants(version_id: str | None = None) -> tuple[str, ...]:+ return tuple(p["quant"] for p in model_version(version_id).get("packs", ()))++# ---- panel settings: user-controllable preferences -------------------------# Persisted to panel_settings.json so the user's choice survives restarts.# Read at startup, exposed via /settings GET, mutated via /settings POST.@@ -323,6 +555,23 @@ SETTINGS_FILE = STATE_DIR / "panel_settings.json"_SETTINGS_LOCK = threading.Lock()+# ---- Storyboard preferences ------------------------------------------------+# The shot-count chips the brief offers, and the qualities each pass may take.+# Kept beside the settings defaults because _validate_settings_patch is the+# only thing that enforces them and both run before anything else is imported.+STORYBOARD_SHOT_CHOICES = (6, 12, 24, 36)+# The chips above are what the brief OFFERS. This is what the feature ACCEPTS —+# any count in the band the planner's token budget can actually serve. They are+# different questions, and conflating them is how a brief asking for 4 shots+# silently became a 12-shot film.+STORYBOARD_MAX_SHOTS = 48+STORYBOARD_DRAFT_QUALITIES = ("quick", "balanced", "standard")+STORYBOARD_FINAL_QUALITIES = ("balanced", "standard", "high")+# The film-level engine choice. See storyboard.ENGINE_MODES for what each means+# and why it is a PLANNING input rather than a post-hoc filter.+STORYBOARD_ENGINE_MODES = ("auto", "h3", "ltx")++def _settings_defaults() -> dict:preset = OUTPUT_PRESETS[DEFAULT_OUTPUT_PRESET]return {@@ -358,8 +607,9 @@ def _settings_defaults() -> dict:# ---- 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.- # Short version: counts only, never content, and completely inert- # until a PostHog key is configured.+ # Short version: counts only, never content, ON by default, and the+ # build ships a working project key — so this toggle, not the key+ # field below, is the off switch.## Default ON. This is a change of posture from the 2026-05 opt-in# experiment that was reverted (da1d6f5) — that one was OFF by@@ -372,9 +622,10 @@ def _settings_defaults() -> dict:# Random UUID4, generated on first use and never derived from# anything about the machine. The only identifier we send."analytics_install_id": "",- # PostHog PROJECT key (write-only, safe to hold on disk). Empty =- # analytics opens no sockets at all. Maintainer pastes this in- # Settings to switch the fleet on; PHOSPHENE_ANALYTICS_KEY overrides.+ # PostHog PROJECT key (write-only, safe to hold on disk). This is an+ # OVERRIDE of the shipped ANALYTICS_KEY_DEFAULT, not the on switch:+ # empty means "no override" and capture falls back to the shipped+ # key. A fork pastes its own here; PHOSPHENE_ANALYTICS_KEY beats both."analytics_key": "",# PostHog PERSONAL API key (read-only, maintainer-only). Powers the# fleet view on /stats/usage. Never used for capture.@@ -384,6 +635,14 @@ def _settings_defaults() -> dict:"analytics_last_packs": {},# Whether the one-line boot disclosure has already been printed."analytics_disclosed": False,+ # ---- Storyboard --------------------------------------------------+ # The brief's shot-count chip, and the quality each of the film's two+ # passes runs at. Same store as every other preference; the Storyboard+ # tab reads them on entry and writes them back through POST /settings.+ "storyboard_shots": 12,+ "storyboard_draft_quality": "quick",+ "storyboard_final_quality": "standard",+ "storyboard_engine": "auto",}@@ -624,14 +883,37 @@ def _validate_settings_patch(patch: dict) -> tuple[dict, str | None]:("analytics_query_key", "PostHog personal API key")):if _akey in patch:val = str(patch[_akey]).strip()- # Empty is legal and meaningful: it clears the key and (for- # analytics_key) returns the panel to fully-inert.+ # Empty is legal: it clears the override. For analytics_key that+ # restores the SHIPPED default key (it does not stop sending —+ # the analytics_enabled toggle does); for analytics_query_key it+ # genuinely turns the fleet view off, since nothing ships there.if val and not (8 <= len(val) <= 256):return {}, f"{_alabel} length looks wrong (expected 8-256 chars)"if any(c.isspace() for c in val):return {}, f"{_alabel} cannot contain whitespace"out[_akey] = val+ # ---- Storyboard defaults ------------------------------------------------+ # The brief's shot-count chip and the film's two quality passes persist HERE+ # rather than in a private file, because that is the store every other panel+ # preference already uses.+ if "storyboard_shots" in patch:+ try:+ n = int(str(patch["storyboard_shots"]).strip())+ except (TypeError, ValueError):+ return {}, "storyboard_shots must be a number"+ if not (1 <= n <= STORYBOARD_MAX_SHOTS):+ return {}, f"storyboard_shots must be between 1 and {STORYBOARD_MAX_SHOTS}"+ out["storyboard_shots"] = n+ for _skey, _allowed in (("storyboard_draft_quality", STORYBOARD_DRAFT_QUALITIES),+ ("storyboard_final_quality", STORYBOARD_FINAL_QUALITIES),+ ("storyboard_engine", STORYBOARD_ENGINE_MODES)):+ if _skey in patch:+ q = str(patch[_skey]).strip().lower()+ if q not in _allowed:+ return {}, f"{_skey} must be one of: {list(_allowed)}"+ out[_skey] = q+return out, None@@ -2823,8 +3105,24 @@ def _detect_local_install_state() -> None:detect runs after every Update."""sha = _git_capture(["rev-parse", "HEAD"])branch = _git_capture(["rev-parse", "--abbrev-ref", "HEAD"]) or "(unknown)"- # `git status --porcelain` empty = clean tree.- porcelain = _git_capture(["status", "--porcelain"])+ # `git status --porcelain -uno` empty = no MODIFIED TRACKED files.+ #+ # -uno (untracked-files=no) is load-bearing, not a tidy-up. Plain+ # --porcelain also lists `??` untracked paths, and an install grows+ # those by design: the optional H3 pack clones minimax-h3-mlx/ into+ # this directory, Pinokio fills cache/ and logs/. That made the tree+ # permanently "dirty" for every H3 user, which suppressed the update+ # check outright — @Morac2 reported the pill stuck on "Update check+ # is paused: local changes uncommitted" with nothing but `?? minimax-+ # h3-mlx/` in his status (#52). .gitignore now covers those three+ # paths, but only for users who already got the new .gitignore, which+ # they can't without updating. -uno is what actually fixes it, and it+ # is the honest question anyway: untracked files are exactly the ones+ # a fast-forward pull (and the reset --hard fallback) leave alone. The+ # one case where an untracked file DOES matter — an incoming commit+ # adding a file at the same path — git refuses on its own, and that+ # error is surfaced verbatim by the /version/pull handler.+ porcelain = _git_capture(["status", "--porcelain", "-uno"])dirty = bool(porcelain and porcelain.strip())local_version = _read_local_version()# 2026-05-21 — capture HEAD commit date so the dev pill can show@@ -2987,8 +3285,10 @@ def get_version_state() -> dict:# Runs the stdlib-only fetcher script as a subprocess once per 24h, appending# a JSON line to state/stats-data.jsonl. Dashboard at /stats reads this file.# 127.0.0.1-only by design (state/ is gitignored, file lives on the user's-# Mac only). Skipped silently if no GitHub token is resolvable — no telemetry-# is the floor, this is opt-in via "have a token configured".+# Mac only). Skipped silently if no GitHub token is resolvable — this fetcher+# is opt-in via "have a token configured". It only READS GitHub's API and+# sends nothing anywhere; the panel's outbound usage analytics is a separate+# module entirely (see "Anonymous usage analytics" / docs/ANALYTICS.md).# ---------------------------------------------------------------------------_STATS_POLL_INTERVAL_SEC = 24 * 60 * 60 # daily@@ -3277,32 +3577,218 @@ def base_missing() -> list[str]:return out+def pack_missing_files(quant: str, version_id: str | None = None) -> list[str]:+ """Files missing for ONE pack of ONE model version (bare filenames).++ This is the anti-mosaic primitive. The file list comes from the pack's+ `required_files.json` entry (reached through the registry by repo key,+ never by a literal), and the directory comes from the registry's resolved+ pack path — so the answer is always about the exact weights the job is+ going to load, and a second model version cannot inherit the first one's+ answer.++ Directory resolution keeps the pre-registry behaviour exactly: a pack+ under ROOT is checked ROOT-relative via `_repo_missing`; a pack an env+ var moved outside ROOT (LTX_Q8_LOCAL) is checked absolutely. Returns []+ for a quant this version doesn't ship, which is the honest answer — the+ caller's job is to notice the pack isn't registered, not to see phantom+ missing files."""+ repo = pack_repo(quant, version_id)+ if not repo:+ return []+ base = pack_path(quant, version_id)+ if base.is_relative_to(ROOT):+ override = repo.copy()+ override["local_dir"] = str(base.relative_to(ROOT))+ return _repo_missing(override)+ missing = []+ for fname in repo.get("files", []):+ p = base / fname+ try:+ if not p.exists() or p.stat().st_size < _MIN_FILE_BYTES:+ missing.append(fname)+ except OSError:+ missing.append(fname)+ return missing+++def pack_available_anywhere(quant: str, version_id: str | None = None) -> bool:+ """True if (version, quant) is complete in EITHER its local dir OR the HF+ cache — the cache-aware form of `pack_missing_files`. Same reasoning as+ q8_available_anywhere below, generalised to any registered pack."""+ repo = pack_repo(quant, version_id)+ if not repo:+ return False+ for entry in repo_status_list():+ if entry.get("key") == repo.get("key"):+ return bool(entry.get("complete"))+ return False+++def base_model_dir(version_id: str | None = None) -> str:+ """Model directory for a version's BASE (distilled) pipeline, as a job+ spec wants it.++ Every version resolves to its own registry q4 pack, with ONE exception:+ the version whose q4 pack is literally `Q4_LOCAL_PATH` gets `MODEL_ID`+ instead. That is not a special case for "the default" — it is a special+ case for **2.3 specifically**, because `MODEL_ID` is the env-aware+ spelling of that one install: `LTX_MODEL` overrides it, and it degrades+ to the bare HF repo id `dgrauet/ltx-2.3-mlx-q4` when the directory is+ absent. Those two shapes have to keep working byte-for-byte.++ KEYING THIS OFF PACK IDENTITY RATHER THAN DEFAULT-NESS IS LOAD-BEARING.+ Two earlier spellings both broke, in mirror image:++ `== ACTIVE_MODEL_VERSION` — read correctly only while ltx23 was the+ sole generation and so always both default and active. The day+ LTX_MODEL_VERSION=ltx25 made a second version active, 2.5 asked for its+ base pipeline and was handed MODEL_ID — the 2.3 pack — and rendered 2.3+ weights under 2.5 code, silently, at full speed. Caught by reading the+ helper's `ready` line, not by any test.++ `== default_model_version_id()` — correct until 2.5 BECAME the default,+ at which point it hands the 2.5 generation the 2.3 pack again.++ A pack's own path cannot drift out from under it, so this spelling+ survives the default moving in either direction."""+ wanted = version_id or ACTIVE_MODEL_VERSION+ pack = version_pack("q4", wanted)+ if pack is not None and Path(pack["path"]) == Q4_LOCAL_PATH:+ return str(MODEL_ID)+ return str(pack_path("q4", wanted))+++def text_encoder_dir(version_id: str | None = None) -> str:+ """Text-encoder directory for a version, as the helper's env wants it.++ Each version names its own encoder in the registry, and 2.3's entry names+ the `GEMMA` constant itself — so `LTX_GEMMA_PATH` and every existing+ install layout are honoured byte-for-byte without a branch here. Like+ base_model_dir(), this deliberately does NOT ask which version is the+ default; that answer changes, and the encoder a generation needs does not.++ This exists because the conditioning half of the pipeline had no seam at+ all. `MODEL_VERSIONS` described which DiT weights a generation loads while+ the encoder stayed a module-level constant pointing at Gemma 3, so+ selecting 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."""+ te = model_version(version_id).get("text_encoder") or {}+ return str(te.get("path") or GEMMA)+++def text_encoder_missing_files(version_id: str | None = None) -> list[str]:+ """Anti-mosaic primitive for the encoder, mirroring pack_missing_files().++ An encoder that is half-downloaded fails the same way a half-downloaded+ DiT does: it loads what is there, leaves the rest at whatever the module+ constructor produced, and renders something that looks like a bad model+ rather than a missing file."""+ te = model_version(version_id).get("text_encoder") or {}+ key = te.get("repo_key")+ if not key:+ return []+ repo = None+ for r in _REQUIRED.get("repos", []):+ if r.get("key") == key:+ repo = r+ break+ if not repo:+ return []+ base = Path(text_encoder_dir(version_id))+ return [f for f in (repo.get("files") or []) if not (base / f).exists()]+++_HQ_WEIGHTS_FALLBACK = {+ "dev_transformer": "transformer-dev.safetensors",+ "distilled_lora": "ltx-2.3-22b-distilled-lora-384.safetensors",+}+++def hq_weights(version_id: str | None = None) -> dict:+ """The dev transformer + distilled LoRA FILENAMES a version's two-stage HQ+ surface loads out of its hq pack.++ High, Extend, Keyframe and A2V all reach past `model_dir` and name a file+ inside it. `model_dir` alone is therefore not the whole seam: point a job+ at the 2.5 pack while the filename still says 2.3 and the loader looks for+ something that is not there.++ The fallback is the 2.3 pair rather than an empty dict on purpose — an+ unknown or malformed registry entry must behave exactly like the code did+ before this function existed, which is what makes adding it a no-op for+ every generation that does not override it."""+ names = model_version(version_id).get("hq_weights") or {}+ return {k: str(names.get(k) or v) for k, v in _HQ_WEIGHTS_FALLBACK.items()}+++def ltx_model_dir(quant: str, version_id: str | None = None) -> str:+ """Pack directory for a job spec, with the fallback the IC-LoRA / HDR+ sites hand-rolled four times: if the pack directory isn't on disk, hand+ the helper the models root and let its own resolution take over rather+ than naming a path that doesn't exist."""+ p = pack_path(quant, version_id)+ return str(p) if p.is_dir() else str(MODELS_DIR)+++def _canonical_layout() -> bool:+ """True when this panel is driving the canonical Pinokio model layout.++ False for the two shapes we must never second-guess: LTX_MODEL set to a+ bare HF repo id (weights resolve through the HF cache) and LTX_MODEL+ pointed 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"))+++def ltx_pack_preflight(quant: str, feature: str,+ version_id: str | None = None) -> None:+ """Refuse a render whose weights are incomplete, and NAME the file.++ This is the June-2026 lesson turned into four lines of control flow. One+ 1 GB spatial upscaler fell out of a `download_include` allowlist; the+ pack still had every other file, the loader still built the module, and+ it built it from random initialisation. Output was a rainbow mosaic with+ no error anywhere -- two weeks and three wrong theories (Metal watchdog,+ corrupt download, an MLX 4-bit kernel bug) before anyone looked at the+ file list. A second model version multiplies that surface by the number+ of packs, so every pack a job is about to load gets asked first.++ Conservative by construction -- it can only fire where we have ground+ truth: the canonical layout, a registered pack, and the files absent+ from BOTH the pack directory and the HF cache. Anything else returns+ silently and the job proceeds exactly as it did before."""+ if not _canonical_layout():+ return+ repo = pack_repo(quant, version_id)+ if not repo:+ return+ if pack_available_anywhere(quant, version_id):+ return+ missing = pack_missing_files(quant, version_id)+ if not missing:+ return+ ver = model_version(version_id)+ shown = ", ".join(missing[:3]) + (" …" if len(missing) > 3 else "")+ raise RuntimeError(+ f"{feature} can't run: the {ver['label']} {quant.upper()} model is "+ f"incomplete. Missing {len(missing)} file(s) in "+ f"{pack_path(quant, version_id)}: {shown}. "+ f"Rendering anyway produces garbled 'mosaic' output rather than an "+ f"error, which is why this stops here. Use the Repair banner in "+ f"Settings → Model files, or re-download {repo['repo_id']}."+ )++def q8_missing_files() -> list[str]:- """Files missing for the Q8 repo (bare filenames). Honors $LTX_Q8_LOCAL.+ """Files missing for the active version's Q8 pack (bare filenames).+ Honors $LTX_Q8_LOCAL via the registry's pack path.- When LTX_Q8_LOCAL is set, it overrides the Q8 repo's local_dir — we- re-route the check there. Other overrides (e.g. moving Q4 elsewhere)- aren't supported via env var; users with custom layouts should adjust- required_files.json directly."""- for r in _repos():- if r.get("key") == "q8":- override = r.copy()- override["local_dir"] = str(Q8_LOCAL_PATH.relative_to(ROOT)) \- if Q8_LOCAL_PATH.is_relative_to(ROOT) else str(Q8_LOCAL_PATH)- # _repo_missing uses ROOT-relative; if Q8_LOCAL_PATH is absolute- # outside ROOT, build a temporary repo with absolute base.- if Path(override["local_dir"]).is_absolute():- missing = []- for fname in r.get("files", []):- p = Path(override["local_dir"]) / fname- try:- if not p.exists() or p.stat().st_size < _MIN_FILE_BYTES:- missing.append(fname)- except OSError:- missing.append(fname)- return missing- return _repo_missing(override)- return []+ Kept as a named function because ~10 job-time gates and /status read it;+ the logic now lives in `pack_missing_files` so a second model version+ asks the same question about its OWN pack."""+ return pack_missing_files("q8")def q8_available_anywhere() -> bool:@@ -3321,10 +3807,7 @@ def q8_available_anywhere() -> bool:cache. This helper is the single source of truth so the FFLF gatematches the model browser."""- for repo in repo_status_list():- if repo.get("key") == "q8":- return bool(repo.get("complete"))- return False+ return pack_available_anywhere("q8")def repo_status_list() -> list[dict]:@@ -3345,9 +3828,20 @@ 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.local_dir = str(Q8_LOCAL_PATH)- local_missing = q8_missing_files() if r.get("key") == "q8" else _repo_missing(r)+ # Completeness is asked of the registry when this repo backs a+ # registered pack, so the answer is per-(version, pack) and a second+ # model version gets its own answer instead of inheriting 2.3's.+ _quant = _quant_for_repo_key(r.get("key"))+ local_missing = pack_missing_files(_quant) if _quant else _repo_missing(r)total = len(r.get("files", []))local_present = total - len(local_missing)@@ -3773,6 +4267,67 @@ def _sha256_file(path: Path) -> str:return h.hexdigest()+# The sidecar our own quantiser writes next to the weights it produces+# (scripts/quantize_ltx.py). Shape: {"files": {"<name>": {"sha256", "bytes"}}}.+PACK_MANIFEST_NAME = "phosphene_quant_manifest.json"+++def _manifest_meta(base: Path) -> dict:+ """filename -> {"sha256", "size"} read from a pack's own manifest.++ The second source of truth for /models/verify-deep. HuggingFace publishes+ an LFS sha256 per file, which is where every expected hash has come from+ so far — but a pack mirrored through GitHub releases (the lane the 2.5+ packs take, because their upstream is gated and we publish our own+ quantisation) has no such API. Its hashes ride along in the pack instead.++ Returns {} on anything unexpected. The caller reads a missing entry as+ 'unverifiable', never as corrupt, so a malformed or absent manifest can+ never trigger a spurious multi-GB re-download."""+ try:+ with open(base / PACK_MANIFEST_NAME, "r") as fh:+ data = json.load(fh)+ except (OSError, ValueError):+ return {}+ files = data.get("files")+ if not isinstance(files, dict):+ return {}+ out: dict = {}+ for name, entry in files.items():+ if not isinstance(entry, dict):+ continue+ sha = entry.get("sha256") or ""+ size = int(entry.get("bytes") or entry.get("size") or 0)+ if sha or size:+ out[name] = {"sha256": sha, "size": size}+ return out+++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 {}+ return pack.get("verify_source") or "hf-api"+++def _expected_meta(repo_key: str | None, repo_id: str, base: Path) -> dict:+ """filename -> {"sha256", "size"} for one installed repo, from whichever+ source its registry entry declares.++ A "hf-api" pack additionally falls back to a manifest if one is sitting in+ the directory and the network lookup came back empty. That fallback is+ inert for every 2.3 pack — dgrauet's repos carry no manifest — and turns+ "unverified because the network blinked" into a real answer where we do+ ship one."""+ if _pack_verify_source(repo_key) == "manifest":+ return _manifest_meta(base)+ meta = _upstream_meta(repo_id) if repo_id else {}+ return meta or _manifest_meta(base)++def _deep_verify_thread() -> None:"""Hash every installed weight + compare to upstream. Result mirrors_model_integrity's shape ({ok, bad:[{repo,file,reason}], checked}) so the@@ -3788,7 +4343,13 @@ def _deep_verify_thread() -> None:repo_def = defs.get(r["key"], {})repo_id = repo_def.get("repo_id", "")base = Path(r.get("location") or (ROOT / r["local_dir"]))- up = {k: v["sha256"] for k, v in _upstream_meta(repo_id).items() if v.get("sha256")}+ # Expected hashes come from whichever source the registry+ # declares for this pack: HuggingFace LFS metadata (every 2.3+ # pack, unchanged) or the pack's own manifest (a mirrored pack+ # with no checksum API, which is how the 2.5 packs ship).+ up = {k: v["sha256"]+ for k, v in _expected_meta(r["key"], repo_id, base).items()+ if v.get("sha256")}for fname in repo_def.get("files", []):if not fname.endswith(".safetensors"):continue@@ -3826,10 +4387,11 @@ def _deep_verify_thread() -> None:exp_meta: dict = {}for r in _repos():repo_id = r.get("repo_id", "")- base = Q8_LOCAL_PATH if r.get("key") == "q8" else (ROOT / r["local_dir"])- if not repo_id or not any(_placed_size(base / f) for f in r.get("files", [])):+ _q = _quant_for_repo_key(r.get("key"))+ base = pack_path(_q) if _q else (ROOT / r["local_dir"])+ if not any(_placed_size(base / f) for f in r.get("files", [])):continue # not installed here — don't ask upstream- for fname, m in _upstream_meta(repo_id).items():+ for fname, m in _expected_meta(r.get("key"), repo_id, base).items():exp_meta[(r["key"], fname)] = malready = {(b["repo"], b["file"]) for b in result["bad"]}for p in _placement_errors(expected=exp_meta, hasher=_sha256_file):@@ -3912,40 +4474,73 @@ def _download_thread(repo: dict) -> None:download in a 3-attempt retry loop with exponential backoff. hf isresumable, so retries pick up from where the previous attemptstopped. User cancellations (DOWNLOAD["active"] flipping to False)- break the loop early."""+ break the loop early.++ 2026-08-12 - TWO LANES, ONE RETRY LOOP. A pack whose registry entry carries+ a `mirror` block is not on HuggingFace at all: the LTX-2.5 packs are our own+ quantisation of a gated upstream, our HF token is read-only, and they are+ published as GitHub release assets instead (the lane the sample-character+ LoRA already takes). For those we spawn `scripts/fetch_pack_release.py`+ instead of `hf`. Only the COMMAND differs -- the retry/backoff, the+ line-streaming into the panel log, the single download slot and+ cancel-by-killing-the-process-group are all shared, because the alternative+ is a second downloader that drifts from this one."""repo_id = repo["repo_id"]target = ROOT / repo["local_dir"]target.mkdir(parents=True, exist_ok=True)- cmd = [str(HF_BIN), "download", repo_id, "--local-dir", str(target)]- # Y1.024 — apply --include filter when the repo entry declares one. Without- # it `hf download` grabs every file in the upstream repo. dgrauet's LTX- # repos host duplicate transformer variants (-distilled, -distilled-1.1,- # -dev), duplicate distilled LoRAs, and unused upscalers — turning a- # declared 25 GB Q8 into 82 GB on disk and a 25 GB Q4 into 56 GB.- # `download_include` is the explicit allowlist of patterns we ship to- # the user; everything else stays on the Hub. See required_files.json- # for the comment block on this.- include_patterns = repo.get("download_include") or []- for pat in include_patterns:- cmd.extend(["--include", pat])- if include_patterns:- push(f"[hf] filtering {repo_id} download to {len(include_patterns)} pattern(s) — only the files the panel actually loads.")- push(f"[hf] {repo_id} → {target} (~{repo.get('size_gb','?')} GB) — resumable")-- # Build the env once. HF_HUB_ENABLE_HF_TRANSFER=1 turns on the Rust- # downloader; if hf_transfer isn't installed the hf CLI logs a warning- # and falls back to the Python downloader (slower but still works).- # HF_TOKEN unlocks faster throughput for users who configured a token- # in Settings — anonymous HF is throttled hard.+ mirror = repo.get("mirror") or {}+ is_release_mirror = mirror.get("kind") == "github-release"env = os.environ.copy()- env["HF_HUB_ENABLE_HF_TRANSFER"] = "1"- hf_token = _active_hf_token()- if hf_token:- env["HF_TOKEN"] = hf_token- env["HUGGING_FACE_HUB_TOKEN"] = hf_token- push(f"[hf] using authenticated download (HF token configured) — ~10× faster than anonymous.")++ if is_release_mirror:+ # sys.executable, not HF_BIN: the fetcher is stdlib-only and runs under+ # the panel's own interpreter. No hf, no token, no Hub. It shards, it+ # resumes, and it refuses to rename a file into place until the+ # reassembled sha256 matches the published manifest.+ dl_tag = "mirror"+ cmd = [sys.executable, str(ROOT / "scripts" / "fetch_pack_release.py"),+ "--repo-key", str(repo.get("key") or ""), "--root", str(ROOT)]+ push(f"[mirror] {repo.get('key')} → {target} (~{repo.get('size_gb','?')} GB) "+ f"from the {mirror.get('release_repo')} release "+ f"{mirror.get('tag')} — sharded, sha256-verified, resumable")else:- push(f"[hf] no HF token configured — downloads run on the throttled anonymous tier. Set one in Settings → Hugging Face token for ~10× faster downloads.")+ dl_tag = "hf"+ cmd = [str(HF_BIN), "download", repo_id, "--local-dir", str(target)]+ # Y1.024 - apply --include filter when the repo entry declares one.+ # Without it `hf download` grabs every file in the upstream repo.+ # dgrauet's LTX repos host duplicate transformer variants (-distilled,+ # -distilled-1.1, -dev), duplicate distilled LoRAs, and unused+ # upscalers - turning a declared 25 GB Q8 into 82 GB on disk and a+ # 25 GB Q4 into 56 GB. `download_include` is the explicit allowlist of+ # patterns we ship to the user; everything else stays on the Hub. See+ # required_files.json for the comment block on this.+ include_patterns = repo.get("download_include") or []+ for pat in include_patterns:+ cmd.extend(["--include", pat])+ if include_patterns:+ push(f"[hf] filtering {repo_id} download to {len(include_patterns)} pattern(s) — only the files the panel actually loads.")+ push(f"[hf] {repo_id} → {target} (~{repo.get('size_gb','?')} GB) — resumable")++ # HF_HUB_ENABLE_HF_TRANSFER=1 turns on the Rust downloader; if+ # hf_transfer isn't installed the hf CLI logs a warning and falls back+ # to the Python downloader (slower but still works). HF_TOKEN unlocks+ # faster throughput for users who configured a token in Settings -+ # anonymous HF is throttled hard. Neither applies to the mirror lane,+ # which is why they live inside this branch.+ env["HF_HUB_ENABLE_HF_TRANSFER"] = "1"+ hf_token = _active_hf_token()+ if hf_token:+ env["HF_TOKEN"] = hf_token+ env["HUGGING_FACE_HUB_TOKEN"] = hf_token+ push(f"[hf] using authenticated download (HF token configured) — ~10× faster than anonymous.")+ else:+ push(f"[hf] no HF token configured — downloads run on the throttled anonymous tier. Set one in Settings → Hugging Face token for ~10× faster downloads.")++ # What to call this download in the log. A mirrored pack has no meaningful+ # `repo_id` (it names an HF repo that does not exist), so it is identified+ # by registry key + release tag instead.+ dl_label = (f"{repo.get('key')} ({mirror.get('tag')})"+ if is_release_mirror else repo_id)max_attempts = 3backoff_sec = 5@@ -3953,10 +4548,10 @@ def _download_thread(repo: dict) -> None:for attempt in range(1, max_attempts + 1):with DOWNLOAD_LOCK:if not DOWNLOAD["active"]:- push(f"[hf] {repo_id} cancelled before attempt {attempt}.")+ push(f"[{dl_tag}] {dl_label} cancelled before attempt {attempt}.")breakif attempt > 1:- push(f"[hf] {repo_id} attempt {attempt}/{max_attempts} — resuming from where the previous attempt stopped.")+ push(f"[{dl_tag}] {dl_label} attempt {attempt}/{max_attempts} — resuming from where the previous attempt stopped.")try:proc = subprocess.Popen(cmd,@@ -3968,7 +4563,7 @@ def _download_thread(repo: dict) -> None:start_new_session=True,)except Exception as exc:- push(f"[hf] failed to spawn hf: {exc}")+ push(f"[{dl_tag}] failed to spawn the downloader: {exc}")breakwith DOWNLOAD_LOCK:DOWNLOAD["proc"] = proc@@ -3990,22 +4585,22 @@ def _download_thread(repo: dict) -> None:if line:with DOWNLOAD_LOCK:DOWNLOAD["last_line"] = line[:200]- push(f"[hf:{repo['key']}] {line[:300]}")+ push(f"[{dl_tag}:{repo['key']}] {line[:300]}")else:buf += chif buf.strip():- push(f"[hf:{repo['key']}] {buf.strip()[:300]}")+ push(f"[{dl_tag}:{repo['key']}] {buf.strip()[:300]}")rc = proc.wait()if rc == 0:- push(f"[hf] {repo_id} downloaded successfully.")+ push(f"[{dl_tag}] {dl_label} downloaded successfully.")breakwith DOWNLOAD_LOCK:still_active = DOWNLOAD["active"]if not still_active:- push(f"[hf] {repo_id} cancelled (exit {rc}).")+ push(f"[{dl_tag}] {dl_label} cancelled (exit {rc}).")breakif attempt < max_attempts:- push(f"[hf] {repo_id} attempt {attempt} failed (exit {rc}). Retrying in {backoff_sec}s — hf will resume from the last completed file.")+ push(f"[{dl_tag}] {dl_label} attempt {attempt} failed (exit {rc}). Retrying in {backoff_sec}s — the downloader resumes from where it stopped.")# Sleep in 1-second slices so a cancel during backoff is responsive.for _ in range(backoff_sec):time.sleep(1)@@ -4014,9 +4609,9 @@ def _download_thread(repo: dict) -> None:breakbackoff_sec = min(backoff_sec * 2, 60) # 5 → 10 → 20s cap by attempt 3else:- push(f"[hf] {repo_id} FAILED after {max_attempts} attempts (last exit {rc}). Click Download again to keep retrying — hf will resume.")+ push(f"[{dl_tag}] {dl_label} FAILED after {max_attempts} attempts (last exit {rc}). Click Download again to keep retrying — it resumes.")except Exception as exc:- push(f"[hf] {repo_id} crashed: {exc}")+ push(f"[{dl_tag}] {dl_label} crashed: {exc}")finally:with DOWNLOAD_LOCK:DOWNLOAD["active"] = False@@ -5162,6 +5757,36 @@ 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 = " ||| "+# 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+# no size ON PURPOSE — repointing LTX_STORYBOARD_PLANNER at a different planner+# must not turn this copy into a lie.+STORYBOARD_RAM_HELP = (+ "On a Mac the planner and the renderer share one pool of memory, so they "+ "never run at the same time. Phosphene plans the whole film in one go, in a "+ "separate process that exits when it's done, and only then starts rendering. "+ "That is also why the plan is worth reading before you start — nothing "+ "rewrites itself halfway through.")+# What decides a shot's engine, on the same Python-owned path. This used to open+# "There is no engine switch on a film" — written before the film-level control+# existed, and then printed by the `?` sitting a few centimetres to its right.+# It describes the control that is actually there now.+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, "+ "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. "+ "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."# 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@@ -7013,11 +7638,16 @@ def _engine_css() -> str:# "not going to be well accepted in the open source world." What ships now# is deliberately a different animal, and the differences are the point:#-# * INERT BY DEFAULT IN THE PUBLIC TREE. ANALYTICS_KEY_DEFAULT is "" and-# an empty key is a hard no-op — no socket is ever opened. The panel-# starts pinging only after the maintainer pastes a PostHog project key-# into Settings (or sets PHOSPHENE_ANALYTICS_KEY). A fork that never-# pastes a key never sends anything, forever, with no code change.+# * IT SHIPS A KEY, AND SAYS SO. ANALYTICS_KEY_DEFAULT carries the live+# phc_ project key (since acfbdc7), so a stock install reports out of+# the box. That is deliberate: Phosphene is distributed AS SOURCE, so a+# key that stayed empty in the tree could never reach anyone and the+# fleet counts would not exist. A phc_ key is WRITE-ONLY — it cannot+# read an event back. The off switch is the Settings toggle (or+# PHOSPHENE_ANALYTICS_DISABLED=1), NOT clearing the key field: an empty+# `analytics_key` setting resolves back to this default. Read+# docs/ANALYTICS.md before changing any of that; the doc and this+# module are meant to be diffable by a suspicious user.# * IT NEVER SEES CONTENT. No prompts, no filenames, no paths, no media,# no LoRA/character names, no seeds. The event list in docs/ANALYTICS.md# is the WHOLE schema. _analytics_clean_props() drops known-dangerous@@ -7045,8 +7675,9 @@ def _engine_css() -> str:# only way anonymous fleet counts work at all. The earlier stance here treated a# client key like a secret; it isn't. Reading the fleet still requires the# separate PERSONAL key (analytics_query_key), which is NOT committed.-# Empty string would disable analytics at the source (no socket opened);-# PHOSPHENE_ANALYTICS_KEY still overrides at runtime.+# Blanking this constant is the only way to make a build that never opens a+# socket — the per-user off switch is the analytics_enabled toggle, not an+# empty key field. PHOSPHENE_ANALYTICS_KEY still overrides at runtime.ANALYTICS_KEY_DEFAULT = "phc_shvL6mr1NB8fmcCqGUtAbpr8d4TgA2ebEIxwoLxeezn"# PostHog ingestion host (capture). Override for a self-hosted receiver.ANALYTICS_HOST_DEFAULT = "https://us.i.posthog.com"@@ -7056,6 +7687,27 @@ ANALYTICS_API_HOST_DEFAULT = "https://us.posthog.com"ANALYTICS_TIMEOUT_SEC = 2.0ANALYTICS_STR_MAX = 120+# The value we put in the event's own $ip property so PostHog never writes the+# connecting address there. It has to be a TRUTHY string: PostHog's ingest fills+# properties.$ip from the socket only when the event didn't carry one+# (`if (!properties['$ip'] && event.ip)`), so `None` — the obvious spelling — is+# falsy and gets silently replaced by the real address. 0.0.0.0 is also chosen+# over the more natural 127.0.0.1: the GeoIP transformation rewrites loopback+# and 192.168.* to a real Swedish address for local-dev convenience, which would+# manufacture a location if the disable flag below were ever dropped.+ANALYTICS_IP_PLACEHOLDER = "0.0.0.0"++# Instructions to the receiver, attached to every event next to our own+# properties. They are spread LAST in _analytics_post so no call site can+# override them, and the dry-run suite asserts this exact set on every event+# the panel can fire — a new $-prefixed key cannot appear without a test+# turning red. See _analytics_post for what each one does and does not buy.+_ANALYTICS_RECEIVER_DIRECTIVES = {+ "$process_person_profile": False,+ "$geoip_disable": True,+ "$ip": ANALYTICS_IP_PLACEHOLDER,+}+# Local mirror. Written for every captured event whether or not a PostHog# key is configured, so /stats always has a "this machine" view and so# there is an auditable record of what the panel would transmit. Lives in@@ -7115,9 +7767,11 @@ def _analytics_enabled() -> bool:for users who want it off before the panel ever writes a settings file— PHOSPHENE_ANALYTICS_DISABLED=1 wins over everything.- Note this is independent of whether a key is configured: with the- toggle ON and no key, capture still writes the local mirror (which- never leaves the Mac) but opens no socket."""+ This is the ONLY off switch, and the one docs/ANALYTICS.md points users+ at. It is independent of the key: because a working project key ships+ in ANALYTICS_KEY_DEFAULT, returning False here is what stops a stock+ install from sending — and it stops the local mirror too, since capture+ returns before it builds a payload."""if _optional_bool_env("PHOSPHENE_ANALYTICS_DISABLED") is True:return Falsereturn bool(get_settings().get("analytics_enabled", True))@@ -7127,8 +7781,15 @@ def _analytics_key() -> str:"""Resolve the PostHog PROJECT key used for capture, in priority order:1. PHOSPHENE_ANALYTICS_KEY env var (maintainer / CI override)2. `analytics_key` in panel_settings.json (Settings modal)- 3. ANALYTICS_KEY_DEFAULT — "" in the public tree- Empty result means "never open a socket"."""+ 3. ANALYTICS_KEY_DEFAULT — the live phc_ key this build ships with++ NOTE the fallback: an EMPTY setting is not an off switch, it just means+ "no override", so a user who clears the Settings field is still+ reporting under the shipped key. Turning analytics off is+ _analytics_enabled() — the toggle or PHOSPHENE_ANALYTICS_DISABLED.+ docs/ANALYTICS.md says this in the same words; keep them in step. An+ empty RESULT (only reachable if a fork blanks the constant) means+ "never open a socket"."""env = (os.environ.get("PHOSPHENE_ANALYTICS_KEY") or "").strip()if env:return env@@ -7366,14 +8027,35 @@ def _usage_log_append(record: dict) -> None:def _analytics_post(payload: dict) -> None:"""Single-event POST to the PostHog capture API. Never raises.- `$process_person_profile: false` tells PostHog not to build a person- record for the install id — we want counts, not people. The IP the- request arrives from is whatever the backend sees; PostHog derives a- coarse country from it by default and we neither add to nor suppress- that (documented in docs/ANALYTICS.md)."""+ Every event carries _ANALYTICS_RECEIVER_DIRECTIVES — three instructions+ to the receiver, verified against PostHog's ingest source rather than+ assumed:++ $process_person_profile: False+ Don't build a person record for the install id. We want counts,+ not people.+ $geoip_disable: True+ PostHog's GeoIP transformation returns immediately instead of+ deriving country, city, subdivision, timezone and the city's+ coordinates. Its first statement is literally+ `if (event.properties?.$geoip_disable or empty(...$ip))`, and this+ is the same property posthog-python sets for disable_geoip=True.+ $ip: ANALYTICS_IP_PLACEHOLDER+ Ingest copies the connecting address into properties.$ip only when+ the event didn't bring its own, so sending one is the only way to+ keep the real address off the stored event. It must be truthy —+ see ANALYTICS_IP_PLACEHOLDER for why `None` silently does nothing.++ What this does NOT do, and what docs/ANALYTICS.md is careful not to+ claim: the request still arrives over TCP from a real address, and no+ field inside a request body can change that. What the panel controls is+ what the receiver is instructed to derive from it and store on the+ event. Discarding it at the edge as well is a project-side setting, not+ something this code can assert."""key = _analytics_key()if not key:- return # no key => inert, and this is the only guard that matters+ return # only reachable if a fork blanks the shipped key; the guard+ # users actually rely on is _analytics_enabled(), upstreambody = json.dumps({"api_key": key,"event": payload["event"],@@ -7381,7 +8063,7 @@ def _analytics_post(payload: dict) -> None:"timestamp": payload["utc"],"properties": {**payload["props"],- "$process_person_profile": False,+ **_ANALYTICS_RECEIVER_DIRECTIVES, # last: not overridable},}).encode("utf-8")req = urllib.request.Request(@@ -8612,6 +9294,11 @@ def list_outputs(# at …" button would need a /sidecar fetch on every gallery click.engine = Noneh3_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+ # nothing, and it is what puts an S03 badge on a gallery card. None for+ # every clip that isn't part of a storyboard, which is most of them.+ sb_tag = Nonesidecar = p.with_suffix(p.suffix + ".json")has_sidecar = sidecar.exists()if has_sidecar:@@ -8636,6 +9323,7 @@ def list_outputs(_tier = h3_resolve_tier(_sc_params.get("h3_tier"))if _tier:h3_tier = _tier+ sb_tag = _sb_tag_from(_sc_params.get("session_tag"))# Clip LENGTH, derived — frames/frame_rate are already in the# sidecar params for both engines, so the card can lead with# what the file IS (a 10 s clip) instead of only how long it@@ -8681,6 +9369,10 @@ def list_outputs("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),+ # Storyboard provenance, or None. One badge on the card, one click+ # back to the film it belongs to — and invisible for every clip+ # that isn't part of one.+ "sb": sb_tag,"hidden": is_hidden,# 'kind' lets the right-pane viewer + filter chips branch# without re-parsing the filename. Mirrors isPhotoOutput() on@@ -8785,8 +9477,19 @@ class WarmHelper:returnenv = os.environ.copy()env["PATH"] = f"{FFMPEG_BIN}:{env.get('PATH', '')}"- env["LTX_MODEL"] = MODEL_ID- env["LTX_GEMMA"] = str(GEMMA)+ env["LTX_MODEL"] = base_model_dir()+ # The Q8 pack directory, stated rather than string-derived. The+ # helper's _upscaler_dir() otherwise guesses it by swapping the+ # trailing folder name of LTX_MODEL for the literal+ # "ltx-2.3-mlx-q8" — a guess that is wrong for any second model+ # version and for anyone who moved the pack with LTX_Q8_LOCAL.+ # Same value as the guess on a default install.+ env["LTX_Q8_LOCAL"] = str(pack_path("q8"))+ # 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.+ env["LTX_GEMMA"] = text_encoder_dir()env["LTX_IDLE_TIMEOUT"] = str(HELPER_IDLE_TIMEOUT)env["LTX_LOW_MEMORY"] = HELPER_LOW_MEMORYenv["LTX_ENABLE_MODEL_UPSCALE"] = "1" if MODEL_UPSCALE_ENABLED else "0"@@ -9837,6 +10540,918 @@ def _new_job_id() -> str:return f"j-{int(time.time()*1000):x}-{n:03d}"+# =============================================================================+# STORYBOARD — the server side+# =============================================================================+# One concept in, a film's worth of shots out. A layer ABOVE the video modes,+# not a second app: a shot is an ORDINARY panel job, so the queue, the worker,+# the progress machinery, the outputs folder, the sidecars, the player, the+# gallery and the lightbox are all reused unchanged.+#+# THE ONE HARDWARE FACT THAT SHAPES ALL OF IT: `_free_all_but(keep_kind)` holds+# exactly one pipeline at a time, and a language model occupies the same slot.+# PLAN and RENDER can therefore never overlap. Everything below is downstream of+# that — the planner runs in a short-lived child that exits before a single job+# is enqueued, and the render dispatcher refuses to start while one is planning.+#+# Board files live at state/storyboards/<id>/storyboard.json (storyboard.py owns+# the format), beside panel_queue.json, in a directory /sidecar already serves.+# -----------------------------------------------------------------------------++# Planner + render bookkeeping, keyed by board id. Guarded by _SB_LOCK, which is+# ALWAYS taken before LOCK when both are needed (there is exactly one such place,+# _sb_render_thread, and it takes them in that order every time).+_SB_LOCK = threading.RLock()+_SB_PLANNERS: dict = {} # board_id -> {"session", "thread", "cancelled"}+_SB_RENDERS: dict = {} # board_id -> {"thread", "stop", "pass", "queued"}+_SB_TAG_RX = re.compile(r"^sb:([^#]+)#(\d+)$")+++def _sb_tag_from(session_tag) -> dict | None:+ """`"sb:<board>#3"` -> `{"id": "<board>", "n": 3}`. Anything else -> None.++ One parser, used by the gallery badge, the queue badge and the reconciler,+ so the wire format is stated exactly once.+ """+ m = _SB_TAG_RX.match(str(session_tag or "").strip())+ if not m:+ return None+ try:+ return {"id": m.group(1), "n": int(m.group(2))}+ except (TypeError, ValueError):+ return None+++def _sb_known_character_ids() -> list:+ try:+ return [c["id"] for c in list_characters()]+ except Exception:+ return []+++def _sb_h3_available() -> bool:+ """Can this machine actually render an H3 shot right now?"""+ try:+ return bool(h3_capable() and not h3_paths()["missing"])+ except Exception:+ return False+++def _sb_h3_cost(quality_key: str, length_key: str):+ """The MEASURED wall clock for one H3 cell, in seconds — the hook+ storyboard.estimate() takes so the cost model lives in exactly one place.++ H3_TIERS carries a per-cell `eta_min` that is measured where a measurement+ exists (H3_MEASURED_ETA) and derived from the same forward-cost model where+ it doesn't. Turbo's number is used when Turbo is actually installed, because+ that is what the render will do.+ """+ try:+ key = h3_compose_tier(quality_key, length_key)+ if not key:+ return None+ cell = H3_TIERS[key]+ turbo = False+ try:+ turbo = bool(h3_turbo_status().get("available"))+ except Exception:+ turbo = False+ minutes = cell.get("turbo_min") if turbo else cell.get("eta_min")+ return float(minutes) * 60.0 if minutes else None+ except Exception:+ return None+++def _sb_max_dim() -> int:+ try:+ return int(tier_max_dim("t2v"))+ except Exception:+ return 1024+++def _sb_disk() -> dict:+ try:+ free = shutil.disk_usage(str(OUTPUT)).free+ except Exception:+ return {"free_gb": None}+ return {"free_gb": round(free / (1000 ** 3), 1)}+++def _sb_job_index() -> dict:+ """Every job the panel currently knows about, by id. One snapshot, one lock."""+ idx: dict = {}+ with LOCK:+ cur = STATE.get("current")+ if cur and cur.get("id"):+ idx[cur["id"]] = {"status": cur.get("status") or "running",+ "output_path": cur.get("output_path"),+ "error": cur.get("error")}+ for j in (STATE.get("queue") or []):+ if j.get("id"):+ idx[j["id"]] = {"status": j.get("status") or "queued",+ "output_path": None, "error": None}+ for j in (STATE.get("history") or []):+ if j.get("id") and j["id"] not in idx:+ idx[j["id"]] = {"status": j.get("status"),+ "output_path": j.get("output_path"),+ "error": j.get("error")}+ return idx+++def _sb_sidecar_seed(path) -> int | None:+ """The seed a finished clip ACTUALLY used, from its sidecar.++ Written back onto the shot when its seed was -1, so "Finish keepers"+ re-renders the take that was approved rather than a fresh roll of the dice.+ With the character LoRA that is the whole continuity mechanism in v1.+ """+ try:+ p = Path(str(path))+ meta = json.loads((p.parent / (p.name + ".json")).read_text(encoding="utf-8"))+ except Exception:+ return None+ for holder in (meta, meta.get("params") or {}):+ v = holder.get("seed_used")+ if isinstance(v, int):+ return v+ if isinstance(v, str) and v.strip().lstrip("-").isdigit():+ return int(v)+ return None+++def _sb_reconcile(board: dict) -> bool:+ """Walk each shot's job id and fold the queue's truth back into the board.++ Returns True when anything changed, so the caller can save once. This is why+ a panel restart mid-render loses nothing: panel_queue.json already re-queues+ an interrupted job, and this is what re-attaches it to its shot.+ """+ idx = _sb_job_index()+ changed = False+ for s in (board.get("shots") or []):+ if not isinstance(s, dict):+ continue+ for key, out_key in (("draft_job_id", "draft_output"),+ ("final_job_id", "final_output")):+ jid = s.get(key)+ if not jid:+ continue+ job = idx.get(jid)+ if not job:+ # The job is gone from queue AND history (history is capped).+ # Leave the shot alone: if it has an output it is done, and if+ # it doesn't, it is renderable again.+ continue+ st = (job.get("status") or "").lower()+ if st == "done" and job.get("output_path"):+ if s.get(out_key) != job["output_path"]:+ s[out_key] = job["output_path"]+ changed = True+ if s.get("status") != "done":+ s["status"] = "done"+ s["error"] = None+ changed = True+ if not isinstance(s.get("seed"), int) or s.get("seed") == -1:+ seed = _sb_sidecar_seed(job["output_path"])+ if isinstance(seed, int):+ s["seed"] = seed+ changed = True+ elif st in ("failed", "error", "cancelled"):+ if s.get("status") != "failed":+ s["status"] = "failed"+ changed = True+ if s.get("error") != job.get("error"):+ s["error"] = job.get("error")+ changed = True+ elif st == "running":+ if s.get("status") != "rendering":+ s["status"] = "rendering"+ changed = True+ elif st == "queued":+ if s.get("status") not in ("queued", "done"):+ s["status"] = "queued"+ changed = True+ # `status` is the shot's MOST RECENT state, not a record of which passes+ # it has been through — the OUTPUTS are that record, and they are what+ # the scheduler reads. But the UI reads `status`, so a shot waiting on+ # its delivery render must not keep showing "done" from its draft.+ fj = s.get("final_job_id")+ if fj and not s.get("final_output"):+ fst = ((idx.get(fj) or {}).get("status") or "").lower()+ if fst in ("queued", "running"):+ want = "rendering" if fst == "running" else "queued"+ if s.get("status") != want:+ s["status"] = want+ changed = True+ return changed+++def _sb_normalize(board: dict) -> dict:+ """Make a board internally consistent before it is validated or saved.++ Renumbers 1..N with no gaps, forces the mode/character pair to agree,+ re-injects every character trigger mechanically (never trusted to a model —+ a prompt that lost its trigger renders a stranger), and forces `engine` to+ LTX for a cast shot or on a machine with no H3 pack, so a plan can never be+ saved in a state that cannot render.+ """+ known = set(_sb_known_character_ids())+ h3_ok = _sb_h3_available()+ mode = (board.get("engine_mode") or storyboard.DEFAULT_ENGINE_MODE).strip().lower()+ if mode not in storyboard.ENGINE_MODES:+ mode = storyboard.DEFAULT_ENGINE_MODE+ board["engine_mode"] = mode+ shots = [s for s in (board.get("shots") or []) if isinstance(s, dict)]+ for i, s in enumerate(shots, start=1):+ s["n"] = i+ smode = s.get("mode")+ if smode not in storyboard.VALID_MODES:+ smode = "text"+ cid = (s.get("character_id") or "").strip() or None+ if cid and known and cid not in known:+ # Keep the id — the validator's job is to say so, not ours — but do+ # not pretend the pair is coherent.+ pass+ if cid:+ smode = "character" if smode in ("text", "character") else smode+ trig = (s.get("trigger") or cid).strip()+ s["trigger"] = trig+ s["prompt"] = storyboard.ensure_trigger(s.get("prompt") or "", trig)+ else:+ s.pop("character_id", None)+ s.pop("trigger", None)+ if smode == "character":+ smode = "text"+ if (s.get("engine") or "").strip().lower() not in storyboard.VALID_ENGINES:+ s["engine"] = "h3" if h3_ok else "ltx"+ # ONE decision point for what actually renders — the film's engine mode,+ # the cast rule and the "is the pack even here" rule, in that order.+ s["engine"] = storyboard.resolve_engine(s, engine_mode=mode, h3_available=h3_ok)+ s["mode"] = smode+ if not isinstance(s.get("refs"), list):+ s["refs"] = []+ try:+ d = float(s.get("duration_s") or 5.0)+ except (TypeError, ValueError):+ d = 5.0+ s["duration_s"] = max(1.0, min(60.0, d))+ if s.get("status") not in ("pending", "queued", "rendering", "done",+ "failed", "skipped"):+ s["status"] = "pending"+ board["shots"] = shots+ board["updated_at"] = int(time.time())+ return board+++def _sb_payload(board: dict) -> dict:+ """Everything the plan screen renders from, in one reply.++ The errors are the STRUCTURED form; the UI keys its own human copy off+ `code` rather than regexing English out of `message`, which is what stops+ the panel's wording from drifting away from the check that produced it.+ """+ pass_name = "final" if _sb_pass_done(board, "draft") else "draft"+ errors = storyboard.validate_storyboard_detail(+ board,+ known_character_ids=_sb_known_character_ids(),+ ref_root=OUTPUT,+ max_dim=_sb_max_dim(),+ )+ # Price and bucket the film the way it will ACTUALLY render. With no H3 pack+ # `shot_to_job` forces every shot to LTX, so estimating off a stored+ # engine="h3" would put an H3 bucket in the run strip and an H3 price on the+ # summary for a render that is going to be all LTX. Only ever a copy — the+ # board on disk keeps what the planner wrote, so installing the pack later+ # restores the intent without a re-plan.+ h3_ok = _sb_h3_available()+ emode = board.get("engine_mode") or storyboard.DEFAULT_ENGINE_MODE+ costed = board+ if any(storyboard.shot_engine(s)+ != storyboard.resolve_engine(s, engine_mode=emode, h3_available=h3_ok)+ for s in (board.get("shots") or []) if isinstance(s, dict)):+ import copy as _copy+ costed = _copy.deepcopy(board)+ for s in costed.get("shots") or []:+ if isinstance(s, dict):+ s["engine"] = storyboard.resolve_engine(+ s, engine_mode=emode, h3_available=h3_ok)+ est = storyboard.estimate(costed, pass_name=pass_name, h3_cost=_sb_h3_cost)+ per_shot = storyboard.per_shot_estimate(costed, pass_name=pass_name,+ h3_cost=_sb_h3_cost)+ with _SB_LOCK:+ rendering = board.get("id") in _SB_RENDERS+ planning = board.get("id") in _SB_PLANNERS+ return {+ "ok": True,+ "board": board,+ "errors": errors,+ "estimate": est,+ "per_shot_est": per_shot,+ "pass": pass_name,+ "disk": _sb_disk(),+ "planner": board.get("planner") or {"state": "idle"},+ "rendering": rendering,+ "planning": planning,+ "h3_available": h3_ok,+ "engine_mode": board.get("engine_mode") or storyboard.DEFAULT_ENGINE_MODE,+ "characters": [+ {"id": c.get("id"), "trigger": c.get("trigger") or c.get("id"),+ "name": c.get("name") or c.get("id"),+ "preview": c.get("preview_url") or c.get("thumb") or None}+ for c in (list_characters() or [])+ ],+ }+++def _sb_pass_done(board: dict, pass_name: str) -> bool:+ """Has every renderable shot got a clip from this pass?"""+ key = "draft_output" if pass_name == "draft" else "final_output"+ live = [s for s in (board.get("shots") or [])+ if isinstance(s, dict) and s.get("status") != "skipped"]+ return bool(live) and all(s.get(key) for s in live)+++def _sb_board_summary(board: dict) -> dict:+ shots = [s for s in (board.get("shots") or []) if isinstance(s, dict)]+ with _SB_LOCK:+ running = board.get("id") in _SB_RENDERS+ planning = board.get("id") in _SB_PLANNERS+ return {+ "id": board.get("id"),+ "title": board.get("title") or "",+ "shots": len(shots),+ "done": sum(1 for s in shots if s.get("status") == "done"),+ "failed": sum(1 for s in shots if s.get("status") == "failed"),+ "running": running,+ "planning": planning,+ }+++def _sb_all_summaries() -> list:+ """The one-line-per-board payload /status carries.++ It is what drives the queue badge's `S03/12` denominator, the tab count+ during an overnight run, and whether `To film` is visible at all. Cheap: one+ read per board file, and boards are few.+ """+ out = []+ try:+ rows = storyboard.list_storyboards(STATE_DIR)+ except Exception:+ return out+ for r in rows:+ try:+ board = storyboard.load_storyboard(STATE_DIR, r["id"])+ except Exception:+ continue+ out.append(_sb_board_summary(board))+ return out+++def storyboard_status() -> dict:+ """Compact Storyboard snapshot for the page bootstrap.++ `planner_present` answers the only question that could make the feature+ unusable — and it is almost always yes, because the planner runs on the same+ weights /prompt/enhance already loads. Nothing is ever downloaded.+ """+ model = ""+ present = False+ try:+ model = str(storyboard_planner.DEFAULT_MODEL_PATH or "")+ present = bool(model) and Path(model).is_dir()+ except Exception:+ pass+ s = get_settings()+ return {+ "available": True,+ "planner_model": model,+ "planner_model_name": Path(model).name if model else "",+ "planner_present": present,+ "ram_help": STORYBOARD_RAM_HELP,+ "engine_help": STORYBOARD_ENGINE_HELP,+ "engine_note": STORYBOARD_ENGINE_NOTE,+ "engine_note_no_h3": STORYBOARD_ENGINE_NOTE_NO_H3,+ "shot_choices": list(STORYBOARD_SHOT_CHOICES),+ "engine_modes": list(STORYBOARD_ENGINE_MODES),+ "draft_qualities": list(STORYBOARD_DRAFT_QUALITIES),+ "final_qualities": list(STORYBOARD_FINAL_QUALITIES),+ "defaults": {+ "shots": s.get("storyboard_shots", 12),+ "draft_quality": s.get("storyboard_draft_quality", "quick"),+ "final_quality": s.get("storyboard_final_quality", "standard"),+ "engine": s.get("storyboard_engine", "auto"),+ },+ "boards": _sb_all_summaries(),+ }+++def _sb_policy_for(draft_quality: str, final_quality: str) -> dict:+ """The board's two passes, in the panel's own geometry vocabulary, clamped+ to what this Mac can actually render."""+ cap = _sb_max_dim()+ table = {+ "quick": (640, 480),+ "balanced": (768, 432),+ "standard": (1024, 576),+ "high": (1024, 576),+ }++ def cell(q, default):+ q = (q or default).strip().lower()+ w, h = table.get(q, table[default])+ if max(w, h) > cap:+ scale = cap / float(max(w, h))+ w = max(64, int(w * scale) // 8 * 8)+ h = max(64, int(h * scale) // 8 * 8)+ return {"quality": q, "width": w, "height": h,+ "frames": storyboard.ltx_frames_for(5)}++ return {"draft": cell(draft_quality, "quick"),+ "final": cell(final_quality, "standard")}+++def _sb_claim_planner(board_id: str):+ """Take the ONE planner slot, or say why it can't be taken.++ Global on purpose. `_free_all_but(keep_kind)` holds exactly one pipeline and+ a language model occupies that same slot, so two planners is not "slower",+ it is two 7.7 GB children at once (15.1 GB measured) — and on a 48 GB Mac,+ which is H3's own floor, an OOM. The guard used to be per board, so two+ different films could plan simultaneously and a third could start rendering+ underneath them. Returns None on success, else the sentence to show.+ """+ with _SB_LOCK:+ if _SB_PLANNERS:+ return ("Another film is already being planned. The planner and the "+ "renderer share one pool of memory, so they take turns.")+ if _SB_RENDERS:+ return ("The renderer is using the memory. Planning can start when "+ "the queue is empty.")+ _SB_PLANNERS[board_id] = {"cancelled": False}+ return None+++def _sb_release_planner(*board_ids) -> None:+ """Hand the planner slot back. Used on every early return AFTER a claim."""+ with _SB_LOCK:+ for bid in board_ids:+ _SB_PLANNERS.pop(bid, None)+++def _sb_release_stranded_claim(action: str) -> None:+ """A raise between claiming the planner slot and starting its thread would+ strand the slot for the life of the process — nothing could ever plan again.+ Only the two routes that claim it can strand it, and a claim with no live+ thread is by definition stranded."""+ if action not in ("plan", "replan-shots"):+ return+ with _SB_LOCK:+ for bid, entry in list(_SB_PLANNERS.items()):+ th = entry.get("thread")+ if th is None or not th.is_alive():+ _SB_PLANNERS.pop(bid, None)+++def _sb_error_kind(err: dict) -> str:+ """The planner's structured error -> the copy the failure screen shows.++ Note what is NOT here: a "download" kind. The planner runs on the weights+ /prompt/enhance already loads and fetches nothing, so "the model didn't+ finish downloading" would be a sentence that can never be true. A child that+ exits mid-plan is, in practice, jetsam — two MLX processes competing for+ unified memory, which is the one thing this feature's whole architecture is+ arranged around — so that maps to the memory copy, not to a shrug.+ """+ kind = (err.get("kind") or "").lower()+ msg = (err.get("message") or "").lower()+ if kind == "invalid_plan":+ return "invalid"+ if any(w in msg for w in ("exited", "closed its output", "died", "memory", "killed")):+ return "oom"+ if "timed out" in msg:+ return "busy"+ return "other"+++def _sb_set_planner(board: dict, **kw) -> None:+ p = board.get("planner")+ if not isinstance(p, dict):+ p = {"state": "idle", "stage": None, "error": None, "error_kind": None,+ "raw": None, "warnings": []}+ p.update(kw)+ board["planner"] = p+++def _sb_plan_thread(board_id: str, brief: dict, previous: dict | None) -> None:+ """Plan a film, then GIVE THE MEMORY BACK — in that order, always.++ `plan_film()` blocks for 20-40 s in a child process. We create the session+ ourselves so `/storyboard/cancel` can kill that child from another thread,+ which means WE own releasing it: `plan_film()` only auto-releases sessions it+ created. Hence the `finally`.++ The stages written onto `board["planner"]["stage"]` are exactly the+ transitions this layer can actually observe. There is no progress callback+ inside plan_film(), and inventing finer granularity than the module reports+ would be a progress bar that lies.+ """+ session = None+ board = None+ try:+ board = storyboard.load_storyboard(STATE_DIR, board_id)+ _sb_set_planner(board, state="running", stage="load", error=None,+ error_kind=None, raw=None, warnings=[])+ storyboard.save_storyboard(STATE_DIR, board)++ session = storyboard_planner.PlannerSession()+ with _SB_LOCK:+ entry = _SB_PLANNERS.get(board_id) or {}+ entry["session"] = session+ _SB_PLANNERS[board_id] = entry++ board["planner"]["stage"] = "write"+ storyboard.save_storyboard(STATE_DIR, board)+ push(f"[storyboard] planning {brief.get('n_shots')} shots — "+ f"the renderer's memory is borrowed for about a minute")++ result = storyboard_planner.plan_film(+ brief.get("concept") or "",+ n_shots=int(brief.get("n_shots") or 12),+ style=brief.get("style") or "",+ characters=brief.get("characters") or None,+ must_include=brief.get("must") or None,+ feedback=brief.get("feedback") or None,+ previous=previous,+ # The film's own choice, and it is a PLANNING input: the planner+ # writes H3's three-field dialect or LTX prose depending on it, so+ # this cannot be applied after the fact. With no H3 pack installed+ # there is only one answer it could honestly give.+ engine=(brief.get("engine_mode") or "auto") if _sb_h3_available() else "ltx",+ board_id=board_id,+ known_character_ids=_sb_known_character_ids(),+ max_dim=_sb_max_dim(),+ session=session,+ )++ with _SB_LOCK:+ cancelled = (_SB_PLANNERS.get(board_id) or {}).get("cancelled")+ if cancelled:+ return++ board = storyboard.load_storyboard(STATE_DIR, board_id)+ meta = (result or {}).get("_planner") or {}+ if storyboard_planner.is_plan_error(result):+ err = result.get("error") or {}+ # A board whose first plan failed must not sit in the list titled+ # "Planning…" forever — name it from its own concept so the row+ # reads as the film the user asked for and Try again is obvious.+ if not (board.get("shots") or []) and board.get("title") in ("", "Planning…", None):+ words = (board.get("concept") or "").split()+ board["title"] = " ".join(words[:6]) or "Untitled film"+ _sb_set_planner(board, state="failed", stage=None,+ error=err.get("message") or "the planner failed",+ error_kind=_sb_error_kind(err),+ raw=err.get("raw_excerpt") or None,+ hint=err.get("hint") or None)+ storyboard.save_storyboard(STATE_DIR, board)+ push(f"[storyboard] the planner couldn't write a usable plan: "+ f"{err.get('message')}")+ return++ # `check`, then `repair` only when the module says a retry actually+ # happened — advertising a failure that usually doesn't occur is worse+ # than saying nothing.+ board["planner"]["stage"] = "repair" if int(meta.get("attempts") or 1) > 1 else "check"++ board["title"] = result.get("title") or board.get("title") or "Untitled film"+ # What each shot had BEFORE the plan replaced it. A re-rolled shot is a+ # brand-new dict, so its previous take has to be read from here — off+ # the new dict it is always None.+ _prev_out = {}+ for _s in (board.get("shots") or []):+ if isinstance(_s, dict) and _s.get("n") is not None:+ _prev_out[_s["n"]] = (_s.get("draft_output") or _s.get("final_output")+ or _s.get("stale_output"))+ board["shots"] = result.get("shots") or []+ # A rewritten shot must go back to being UN-RENDERED. Without this it+ # kept `status: "done"` with no output, and since shooting_order() and+ # estimate() both exclude "done" the film skipped it forever — the user+ # asked for a rewrite precisely because they wanted it rendered again.+ # The old clip is kept on `stale_output` so the card can show it under+ # the "old take" wash until the new one lands (design spec 8.3); the+ # file itself is never deleted.+ for _n in (brief.get("reroll_ns") or []):+ for _s in board["shots"]:+ if not isinstance(_s, dict) or _s.get("n") != _n:+ continue+ _old = _prev_out.get(_n)+ if _old:+ _s["stale_output"] = _old+ _s["status"] = "pending"+ _s["grade"] = None+ for _k in ("draft_output", "final_output",+ "draft_job_id", "final_job_id", "error"):+ _s.pop(_k, None)+ board["cast"] = result.get("cast") or board.get("cast") or []+ # The POLICY is the panel's, not the planner's: the user picked the two+ # passes in the film-level Quality control and a re-plan must not silently+ # reset them.+ board.setdefault("policy", result.get("policy") or storyboard.new_storyboard("x", "x")["policy"])+ _sb_normalize(board)+ _sb_set_planner(board, state="done", stage="unload", error=None,+ warnings=list(meta.get("warnings") or []),+ model=meta.get("model"), elapsed_s=meta.get("elapsed_s"),+ attempts=meta.get("attempts"),+ first_try_clean=meta.get("first_try_clean"))+ storyboard.save_storyboard(STATE_DIR, board)+ push(f"[storyboard] plan ready — {len(board['shots'])} shots, "+ f"{round(float(meta.get('elapsed_s') or 0))}s, memory given back")+ except Exception as exc: # noqa: BLE001+ try:+ if board is None:+ board = storyboard.load_storyboard(STATE_DIR, board_id)+ with _SB_LOCK:+ cancelled = (_SB_PLANNERS.get(board_id) or {}).get("cancelled")+ _sb_set_planner(board,+ state=("cancelled" if cancelled else "failed"),+ stage=None, error=str(exc),+ error_kind=("busy" if cancelled else "other"))+ storyboard.save_storyboard(STATE_DIR, board)+ except Exception:+ pass+ if not str(exc).lower().startswith("planner session released"):+ push(f"[storyboard] planning failed: {exc}")+ finally:+ # A caller that supplies a session OWNS releasing it. There is no path+ # out of this function that leaves a model resident.+ try:+ if session is not None:+ session.release()+ except Exception:+ pass+ with _SB_LOCK:+ _SB_PLANNERS.pop(board_id, None)+ _SB_PLANNERS.pop("-pending-", None)+++def _sb_enqueue(job_form: dict) -> str:+ """Enqueue one shot exactly the way /queue/add does. No private path."""+ job = make_job(job_form)+ with QUEUE_COND:+ STATE["queue"].append(job)+ QUEUE_COND.notify_all()+ persist_queue()+ return job["id"]+++def _sb_render_thread(board_id: str, pass_name: str, only: list | None) -> None:+ """Submit the film ONE BUCKET AT A TIME, then wait for it.++ Not all N jobs at once, and the difference matters: it is what makes editing+ a shot that hasn't started yet actually take effect, it is what lets `stop`+ be seen mid-film, and it is what keeps the grouping honest when a later+ bucket's shots were edited while an earlier one rendered. The panel's own+ dispatcher still owns execution — /queue/pause keeps working; this thread+ only waits.+ """+ key = "draft_job_id" if pass_name == "draft" else "final_job_id"+ out_key = "draft_output" if pass_name == "draft" else "final_output"+ queued_total = 0+ try:+ while True:+ with _SB_LOCK:+ entry = _SB_RENDERS.get(board_id)+ if not entry or entry.get("stop"):+ return+ # Re-read from disk every round so edits to not-yet-submitted shots+ # are honoured.+ board = storyboard.load_storyboard(STATE_DIR, board_id)+ _sb_reconcile(board)++ # PASS-AWARE. Without the pass name this scheduled the draft pass no+ # matter what was asked for, and since the reconciler marks a shot+ # "done" when its DRAFT lands, the delivery pass found nothing to do+ # and answered 202 with an empty queue — every film, every time.+ pending = storyboard.shooting_order(board.get("shots") or [], pass_name)+ if only:+ pending = [s for s in pending if s.get("n") in only]+ # A shot already carrying a live job id for this pass is in flight.+ pending = [s for s in pending+ if s.get("status") not in ("queued", "rendering") or not s.get(key)]+ if not pending:+ break++ bucket = storyboard.bucket_key(pending[0])+ batch = [s for s in pending if storyboard.bucket_key(s) == bucket]+ policy = (board.get("policy") or {}).get(pass_name) or {}+ h3_ok = _sb_h3_available()+ # Does THIS install's runner take `--chain-prompts`? A pack cloned+ # before that flag landed renders 10 s fine and cannot be told what+ # each window should do, so asking would be an argparse failure.+ try:+ chain_ok = bool(h3_ok and h3_supports_chain_prompts())+ except Exception:+ chain_ok = False+ ids = []+ for shot in batch:+ form = storyboard.shot_to_job(+ shot, policy,+ board_id=board_id, board_title=board.get("title") or "",+ h3_available=h3_ok,+ engine_mode=board.get("engine_mode") or "auto",+ h3_chain_prompts=chain_ok)+ # make_job reads a form: every value is a string (or a list of+ # them). Normalise here so a bool/int never reaches f().+ job_form = {k: ("" if v is None else str(v)) for k, v in form.items()}+ try:+ jid = _sb_enqueue(job_form)+ except Exception as exc: # noqa: BLE001+ push(f"[storyboard] shot {shot.get('n')} could not be queued: {exc}")+ shot["status"] = "failed"+ shot["error"] = str(exc)+ continue+ shot[key] = jid+ shot["status"] = "queued"+ shot["error"] = None+ ids.append(jid)+ queued_total += 1+ storyboard.save_storyboard(STATE_DIR, board)+ with _SB_LOCK:+ entry = _SB_RENDERS.get(board_id)+ if entry is not None:+ entry["queued"] = queued_total+ push(f"[storyboard] queued {len(ids)} shot(s) on "+ f"{bucket[0].upper()} — {board.get('title')}")++ # Wait for this bucket to go terminal before submitting the next.+ while ids:+ with _SB_LOCK:+ entry = _SB_RENDERS.get(board_id)+ if not entry or entry.get("stop"):+ return+ idx = _sb_job_index()+ live = [j for j in ids+ if (idx.get(j) or {}).get("status") in ("queued", "running")]+ if not live:+ break+ time.sleep(5.0)++ try:+ board = storyboard.load_storyboard(STATE_DIR, board_id)+ if _sb_reconcile(board):+ storyboard.save_storyboard(STATE_DIR, board)+ except Exception:+ pass+ except Exception as exc: # noqa: BLE001+ push(f"[storyboard] render dispatch stopped: {exc}")+ finally:+ with _SB_LOCK:+ _SB_RENDERS.pop(board_id, None)+ try:+ board = storyboard.load_storyboard(STATE_DIR, board_id)+ if _sb_reconcile(board):+ storyboard.save_storyboard(STATE_DIR, board)+ # Delivered shots don't need their draft's Stage-A cache any more.+ _sb_sweep_stage_a(board)+ except Exception:+ pass+++def _sb_boot_reconcile() -> None:+ """Boot hook — no planner survives a panel restart, so no board may claim one.++ The planner lives in a child of THIS process. If the panel was killed (or+ updated, or crashed) mid-plan, that child died with it — but the board on+ disk still says `planner.state = "running"`, and the tab would sit on the+ planning screen forever waiting for a stage that can never advance. Caught+ live: the owner started a plan seconds before a restart.++ Render state needs no equivalent, and that is the whole point of riding the+ normal queue: panel_queue.json already re-queues an interrupted job, and+ _sb_reconcile() re-attaches it to its shot on the next read.+ """+ try:+ rows = storyboard.list_storyboards(STATE_DIR)+ except Exception:+ return+ for r in rows:+ try:+ board = storyboard.load_storyboard(STATE_DIR, r["id"])+ except Exception:+ continue+ p = board.get("planner") or {}+ if p.get("state") != "running":+ continue+ if not (board.get("shots") or []) and board.get("title") in ("", "Planning…", None):+ words = (board.get("concept") or "").split()+ board["title"] = " ".join(words[:6]) or "Untitled film"+ _sb_set_planner(board, state="failed", stage=None,+ error="the panel restarted while the planner was running",+ error_kind="restarted")+ try:+ storyboard.save_storyboard(STATE_DIR, board)+ push(f"[storyboard] {board.get('title')!r} was mid-plan when the panel "+ f"stopped — press Try again when you're ready")+ except Exception:+ pass+++def _sb_sweep_stage_a(board: dict) -> int:+ """Drop the Stage-A latent caches a film no longer has a use for.++ Every H3 DRAFT drops a `<clip>.stage_a.npz` beside its output — **8.5 MB a+ shot**, ~300 MB across a 36-shot film, on a disk the summary bar is already+ calling tight. It exists so a later hires-refine pass can sharpen THAT take+ rather than re-rolling it, and nothing in the panel consumes it yet.++ So the rule is decided by whether the draft can still be refined:+ * CUT (`status: "skipped"`) -> it never will be. Delete.+ * DELIVERED (`final_output` set) -> it already has its finished version.+ Delete.+ * anything else -> the draft is still awaiting a verdict.+ KEEP, which is the whole window a future finish-from-cache would use.++ Never touches a clip, and never touches a cache belonging to another film.+ """+ freed = 0+ for s in (board.get("shots") or []):+ if not isinstance(s, dict):+ continue+ draft = s.get("draft_output")+ if not draft:+ continue+ if not (s.get("status") == "skipped" or s.get("final_output")):+ continue+ try:+ cache = Path(draft).with_suffix(".stage_a.npz")+ if cache.is_file() and cache.parent.resolve() == OUTPUT.resolve():+ cache.unlink()+ freed += 1+ except OSError:+ continue+ if freed:+ push(f"[storyboard] released {freed} Stage-A cache file(s) — "+ f"about {freed * 8.5:.0f} MB")+ return freed+++def _sb_slug(text: str, words: int = 5) -> str:+ parts = re.sub(r"[^a-z0-9]+", " ", (text or "").lower()).split()+ return "-".join(parts[:words]) or "shot"+++def _sb_export(board: dict) -> dict:+ """A folder and a manifest. No editor, no timeline, no assembly UI.++ Clips are COPIED, never moved — the gallery keeps them.+ """+ title = board.get("title") or "storyboard"+ day = time.strftime("%Y-%m-%d", time.localtime(board.get("created_at") or time.time()))+ dest = OUTPUT / "storyboards" / f"{day}_{_sb_slug(title, 6)}"+ dest.mkdir(parents=True, exist_ok=True)+ rows, cut, files = [], [], []+ for s in sorted((board.get("shots") or []), key=lambda x: x.get("n") or 0):+ if not isinstance(s, dict):+ continue+ n = s.get("n") or 0+ if s.get("status") == "skipped":+ cut.append(f"- **S{n:02d}** — {(s.get('prompt') or '')[:120]}")+ continue+ src = s.get("final_output") or s.get("draft_output")+ if not src or not Path(src).is_file():+ continue+ which = "delivery" if s.get("final_output") else "draft"+ name = f"S{n:02d}_{_sb_slug(s.get('title') or s.get('prompt') or '')}.mp4"+ try:+ shutil.copy2(src, dest / name)+ except Exception as exc: # noqa: BLE001+ push(f"[storyboard] could not copy shot {n}: {exc}")+ continue+ files.append(name)+ rows.append(f"| {n:02d} | {name} | {s.get('duration_s')} s | "+ f"{s.get('seed')} | {which} | "+ f"{(s.get('prompt') or '')[:90].replace('|', '/')}… |")+ delivered = sum(1 for s in (board.get("shots") or [])+ if isinstance(s, dict) and s.get("final_output"))+ runtime = sum(float(s.get("duration_s") or 0) for s in (board.get("shots") or [])+ if isinstance(s, dict) and s.get("status") != "skipped")+ cast = ", ".join(sorted({str(s.get("character_id")) for s in (board.get("shots") or [])+ if isinstance(s, dict) and s.get("character_id")})) or "none"+ md = [f"# {title}", "",+ f"{len(board.get('shots') or [])} shots planned · {delivered} delivered · "+ f"{round(runtime)} s", "",+ f"Rendered with Phosphene {_read_local_version() or 'dev'} · character: {cast}", "",+ "| # | file | length | seed | pass | prompt |",+ "|---|---|---|---|---|---|"] + rows+ if cut:+ md += ["", "## Cut", ""] + cut+ (dest / "storyboard.md").write_text("\n".join(md) + "\n", encoding="utf-8")+ (dest / "storyboard.json").write_text(+ json.dumps(board, indent=2, ensure_ascii=False), encoding="utf-8")+ return {"ok": True, "dir": str(dest), "files": files}++def _validate_character_quality(form: dict[str, list[str]] | dict[str, str]) -> str | None:"""Character mode is available on Q4 — LoRAs fuse into the distilledbase (identity match is mediocre per 2026-05-17 empirical test with@@ -9884,6 +11499,30 @@ def _validate_character_quality(form: dict[str, list[str]] | dict[str, str]) ->return None+def _safe_float(raw, default: float = 0.0, *,+ minimum: float | None = None,+ maximum: float | None = None) -> float:+ """Parse a form value as a float without ever raising.++ make_job's existing float fields do `float(f(name, "1.0") or 1.0)`, which+ is fine for the ones backed by range sliders — a slider cannot emit+ "abc". Free-form number inputs can, and /queue/add is a plain POST that+ anything may call, so a typo should land on the default rather than+ turning the submit into a 500. Optional clamps keep out-of-range values+ from reaching a pipeline that would silently swallow them."""+ try:+ val = float(raw)+ except (TypeError, ValueError):+ return default+ if val != val or val in (float("inf"), float("-inf")): # NaN / inf+ return default+ if minimum is not None:+ val = max(minimum, val)+ if maximum is not None:+ val = min(maximum, val)+ return val++def make_job(form: dict[str, list[str]] | dict[str, str], *,override_prompt: str | None = None) -> dict:def f(name: str, default: str = "") -> str:@@ -10552,6 +12191,22 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,# explicitly to "full" or "off" via this form field."stage2_image_conditioning": f("stage2_image_conditioning", "") or "","audio_conditioning_scale": float(f("audio_conditioning_scale", "1.0") or 1.0),+ # Where in the source file A2V starts reading. Both pipelines+ # (a2vid_two_stage / a2vid_distilled) have taken this since they+ # landed, and mlx_warm_helper forwards it on both actions — the+ # panel was the only layer that never put a value on the job, so+ # it fell through to 0.0 and every A2V render used the first N+ # seconds of the file no matter what (#46, @blackest). This+ # allowlist entry is load-bearing: a form field that isn't named+ # here silently no-ops on /queue/add, which is exactly the class+ # of bug this file warns about repeatedly.+ #+ # Parsed defensively, unlike its float siblings above: those are+ # all backed by range sliders that can only emit numbers, while+ # this one is a free-form number input (and /queue/add is a public+ # POST). A stray non-numeric value should start the clip at 0,+ # not 500 the submit.+ "audio_start_time": _safe_float(f("audio_start_time", "0"), 0.0, minimum=0.0),},"command": None,"raw_path": None,@@ -11790,6 +13445,62 @@ def run_train_job_inner(job: dict) -> None:push(f"[train.audio] done: {audio_lora_path} (elapsed {audio_elapsed}s)")+def _h3_fit_first_frame(src: Path, width: int, height: int, job_id: str) -> Path:+ """Cover-crop `src` onto the H3 canvas and return the path to use.++ Why the panel does this instead of the runner: upstream's+ `prepare_keyframe_image(image, height, width, stretch=index == 0)`+ HARD-STRETCHES the FIRST keyframe onto the canvas — `image.resize((width,+ height))`, aspect thrown away — because upstream treats keyframe 0 as the+ geometry anchor. A *second* keyframe is cover-cropped instead. So a 4:3+ photo into a 16:9 canvas comes back visibly widened, which is the+ distortion @Morac2 opened #53 with, and no combination of panel settings+ could avoid it: the panel only ever sends keyframe 0.++ The bypass is in the same function, one line above the stretch:++ if image.size == (width, height):+ return image++ An image that already IS the canvas is returned untouched, with no+ resampling pass at all. So pre-fitting here removes the stretch entirely+ without touching the engine, and costs the render nothing — it replaces+ upstream's resize with ours rather than adding a second one.++ The arithmetic below is a deliberate line-for-line port of upstream's own+ non-stretch branch (`packing.py`): max-scale so the image covers the+ canvas, LANCZOS, centre crop with floor division. Faithfulness is the+ point — the panel is standing in for the runner's cover-crop, so it should+ produce what a second keyframe would have produced, not a lookalike.+ `ImageOps.fit` is close but rounds and centres differently.++ Best-effort by construction: any failure returns the ORIGINAL path, so the+ worst case is the stretch we have today rather than a render that dies on+ a reference image."""+ try:+ from PIL import Image+ with Image.open(src) as im:+ im = im.convert("RGB")+ if im.size == (width, height):+ return src # runner's own early-return handles it+ scale = max(width / im.size[0], height / im.size[1])+ resized_size = (max(width, round(im.size[0] * scale)),+ max(height, round(im.size[1] * scale)))+ left = max(0, (resized_size[0] - width) // 2)+ top = max(0, (resized_size[1] - height) // 2)+ fitted = im.resize(resized_size, Image.Resampling.LANCZOS).crop(+ (left, top, left + width, top + height))+ UPLOADS.mkdir(parents=True, exist_ok=True)+ out = UPLOADS / f".h3_{job_id}_firstframe_{width}x{height}.png"+ fitted.save(out, format="PNG")+ return out+ except Exception as exc: # noqa: BLE001 - never fatal+ push(f"[h3] warn: couldn't pre-fit the reference to {width}x{height} "+ f"({exc}); passing it through — the runner will stretch it onto "+ f"the canvas.")+ return src++def run_h3_job_inner(job: dict) -> None:"""Render one job on the Hailuo H3 engine (optional subprocess pack).@@ -12040,7 +13751,15 @@ def run_h3_job_inner(job: dict) -> None:raise RuntimeError("This Hailuo H3 checkout has no `--first-frame` support "f"({paths['runner']}). Update the H3 pack, or use Text mode.")- first_frame = Path(src)+ # Pre-fit to the canvas so upstream's first-keyframe STRETCH never+ # runs (#53). See _h3_fit_first_frame for the mechanism; it returns+ # the original path unchanged when the image is already the canvas+ # size or when anything goes wrong.+ first_frame = _h3_fit_first_frame(Path(src), width, height, job["id"])+ if str(first_frame) != src:+ push(f"[h3] reference cover-cropped to {width}x{height} before "+ f"conditioning (keeps its proportions — the runner would "+ f"stretch the first keyframe onto the canvas).")# Seed: the panel keeps "-1" = random. H3's runner has no random mode, so# resolve it here and record what we used (matches the LTX seed_used@@ -12586,7 +14305,7 @@ def run_job_inner(job: dict) -> None:ext_missing = q8_missing_files()if ext_missing:raise RuntimeError(- f"Extend requires the full Q8 model at {Q8_LOCAL_PATH}. "+ 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)."@@ -12660,7 +14379,11 @@ def run_job_inner(job: dict) -> None:# Y1.036: explicit model_dir → Q8. Helper's get_pipe("extend")# caches per-model-dir so this rebuilds the pipe only when# the dir actually flips.- "model_dir": str(Q8_LOCAL_PATH),+ "model_dir": str(pack_path("q8")),+ # Naming the dev transformer per generation rather than+ # inheriting the vendored RetakePipeline default. Same string+ # today for both generations; stated so it cannot drift.+ "dev_transformer": hq_weights()["dev_transformer"],"prompt": p["prompt"],"negative_prompt": p.get("negative_prompt", ""),"video_path": src,@@ -12688,7 +14411,7 @@ def run_job_inner(job: dict) -> None:# the panel's nominal MODEL_ID (which tracks the Q4 distilled# used by T2V/I2V/Standard). Record the actual path so the# /info modal and historical analyzers don't misreport.- "fps": FPS, "model": str(Q8_LOCAL_PATH), "queue_id": job["id"],+ "fps": FPS, "model": str(pack_path("q8")), "queue_id": job["id"],"helper_elapsed_sec": result.get("elapsed_sec"),"output_codec": output_codec_settings(),# Lineage for issue #48. `extend_picked` is what the user chose in@@ -12790,9 +14513,8 @@ def run_job_inner(job: dict) -> None:# Force the Q4 distilled folder — same rule HDR / Colorize / Ingredients# use. The Union-Control IC-LoRA was trained against the distilled# checkpoint.- control_model_dir = (str(MODELS_DIR / "ltx-2.3-mlx-q4")- if (MODELS_DIR / "ltx-2.3-mlx-q4").is_dir()- else str(MODELS_DIR))+ control_model_dir = ltx_model_dir("q4")+ ltx_pack_preflight("q4", "Control")job_spec = {"action": "generate_restore","id": job["id"],@@ -12896,9 +14618,8 @@ def run_job_inner(job: dict) -> None:job["raw_path"] = str(final_out)# Force the Q4 distilled folder — same rule HDR uses. The Colorize# IC-LoRA was trained against transformer-distilled.safetensors.- restore_model_dir = (str(MODELS_DIR / "ltx-2.3-mlx-q4")- if (MODELS_DIR / "ltx-2.3-mlx-q4").is_dir()- else str(MODELS_DIR))+ restore_model_dir = ltx_model_dir("q4")+ ltx_pack_preflight("q4", "Restore")job_spec = {"action": "generate_restore","id": job["id"],@@ -13073,9 +14794,8 @@ def run_job_inner(job: dict) -> None:job["raw_path"] = str(final_out)# Force Q4 distilled — the Ingredients LoRA was trained against# transformer-distilled.safetensors (same rule HDR / Colorize use).- ing_model_dir = (str(MODELS_DIR / "ltx-2.3-mlx-q4")- if (MODELS_DIR / "ltx-2.3-mlx-q4").is_dir()- else str(MODELS_DIR))+ ing_model_dir = ltx_model_dir("q4")+ ltx_pack_preflight("q4", "Ingredients")# IC reference STRENGTH — the composition lever. This is the second# element of each video_conditioning tuple, and it sets how clean the# reference latent is held during denoise (VideoConditionByReferenceLatent@@ -13190,10 +14910,11 @@ def run_job_inner(job: dict) -> None:kf_missing = q8_missing_files()if kf_missing:raise RuntimeError(- f"Keyframe mode requires the full Q8 model at {Q8_LOCAL_PATH}. "+ f"Keyframe mode requires the full Q8 model at {pack_path('q8')}. "f"Missing {len(kf_missing)} file(s): {', '.join(kf_missing[:3])}"f"{' …' if len(kf_missing) > 3 else ''}. "- f"Run: hf download {MODEL_ID_HQ} --local-dir {Q8_LOCAL_PATH}"+ f"Run: hf download {(pack_repo('q8') or {}).get('repo_id', MODEL_ID_HQ)} "+ f"--local-dir {pack_path('q8')}")# Multi-keyframe path: agent submits a JSON-encoded list of# {image_path, frame_index} pairs. Layer 1 of the SDK shipped the@@ -13287,7 +15008,12 @@ def run_job_inner(job: dict) -> None:"action": "generate_keyframe","id": job["id"],"params": {- "model_dir": str(Q8_LOCAL_PATH),+ "model_dir": str(pack_path("q8")),+ # Keyframe REQUIRES both by name — the pipeline raises without+ # them, and the distilled-only path hallucinates unrelated+ # content mid-interpolation. Per generation: see hq_weights().+ "dev_transformer": hq_weights()["dev_transformer"],+ "distilled_lora": hq_weights()["distilled_lora"],"prompt": p["prompt"],"negative_prompt": p.get("negative_prompt", ""),"output_path": str(out_path),@@ -13353,14 +15079,15 @@ def run_job_inner(job: dict) -> None:uses_q8 = Falseif uses_q8:action = "generate_a2v"- model_dir = str(Q8_LOCAL_PATH)+ model_dir = str(pack_path("q8"))default_stage1 = 20default_stage2 = 3else:action = "generate_a2v_distilled"- model_dir = str(Q4_LOCAL_PATH)+ model_dir = str(pack_path("q4"))default_stage1 = 8default_stage2 = 3+ ltx_pack_preflight("q8" if uses_q8 else "q4", "Audio to Video")audio_src = (p.get("audio") or "").strip()if not audio_src or not Path(audio_src).exists():raise RuntimeError(f"audio file not found: {audio_src}")@@ -13406,6 +15133,11 @@ def run_job_inner(job: dict) -> None:})a2v_params = {"model_dir": model_dir,+ # Only the Q8 branch builds A2VidPipelineTwoStage and reads these;+ # the Q4 distilled branch ignores them, which is why they can be+ # set unconditionally. Per generation: see hq_weights().+ "dev_transformer": hq_weights()["dev_transformer"],+ "distilled_lora": hq_weights()["distilled_lora"],"prompt": p["prompt"],"negative_prompt": p.get("negative_prompt", ""),"output_path": str(out_path),@@ -13419,18 +15151,30 @@ def run_job_inner(job: dict) -> None:"stage1_steps": int(p.get("stage1_steps", default_stage1)),"stage2_steps": int(p.get("stage2_steps", default_stage2)),"audio_conditioning_scale": float(p.get("audio_conditioning_scale", 1.0)),+ # Offset into the source audio. The helper reads this key on both+ # the Q8 and the Q4-distilled action and hands it to+ # load_audio(start_time=…); it defaulted to 0.0 here only because+ # the key was absent (#46).+ "audio_start_time": max(0.0, float(p.get("audio_start_time", 0.0) or 0.0)),}if uses_q8:a2v_params["cfg_scale"] = float(p.get("cfg_scale", 3.0))a2v_params["stg_scale"] = float(p.get("stg_scale", 1.0))a2v_params["loras"] = a2v_lorasjob_spec = {"action": action, "id": job["id"], "params": a2v_params}+ # Only mention the offset when it is actually non-zero — a "start=0.00s"+ # on every line would be noise, but when it IS set the log is the only+ # place a user can confirm the panel honoured it.+ _start_note = ""+ if a2v_params["audio_start_time"]:+ _start_note = " start=%.2fs" % a2v_params["audio_start_time"]push(f"Run A2V ({'Q8' if uses_q8 else 'Q4-distilled'}) via helper: "f"id={job['id']} {width}x{height} {frames}f · "f"audio={Path(audio_src).name}"f"{' image=' + Path(ref_image_path).name if ref_image_path else ''}"f" scale={a2v_params['audio_conditioning_scale']}"+ f"{_start_note}")result = HELPER.run(job_spec)if "seed_used" in result:@@ -13622,6 +15366,7 @@ def run_job_inner(job: dict) -> None:"path": CURATED_LORAS["hdr"]["repo_id"],"strength": float(CURATED_LORAS["hdr"]["default_strength"]),}]+ ltx_pack_preflight("q4", "HDR")job_spec = {"action": "generate_hdr","id": job["id"],@@ -13629,9 +15374,7 @@ def run_job_inner(job: dict) -> None:# Force distilled folder. The Q4 dir holds# transformer-distilled.safetensors which is what the# IC-LoRA was trained against.- "model_dir": str(MODELS_DIR / "ltx-2.3-mlx-q4")- if (MODELS_DIR / "ltx-2.3-mlx-q4").is_dir()- else str(MODELS_DIR),+ "model_dir": ltx_model_dir("q4"),"prompt": p["prompt"],"negative_prompt": p.get("negative_prompt", ""),"output_path": str(raw_out),@@ -13683,10 +15426,11 @@ def run_job_inner(job: dict) -> None:hq_missing = q8_missing_files()if hq_missing:raise RuntimeError(- f"High quality requires the full Q8 model at {Q8_LOCAL_PATH}. "+ f"High quality requires the full Q8 model at {pack_path('q8')}. "f"Missing {len(hq_missing)} file(s): {', '.join(hq_missing[:3])}"f"{' …' if len(hq_missing) > 3 else ''}. "- f"Run: hf download {MODEL_ID_HQ} --local-dir {Q8_LOCAL_PATH}"+ f"Run: hf download {(pack_repo('q8') or {}).get('repo_id', MODEL_ID_HQ)} "+ f"--local-dir {pack_path('q8')}")# HQ is the only inference path that runs the dev transformer with# CFG and the full sigma schedule — which is exactly what character@@ -13704,7 +15448,14 @@ def run_job_inner(job: dict) -> None:"action": "generate_hq","id": job["id"],"params": {- "model_dir": str(Q8_LOCAL_PATH),+ "model_dir": str(pack_path("q8")),+ # High is the two-stage HQ pipeline: dev transformer + CFG at+ # half res, then a refine pass driven by the distilled LoRA.+ # Until now neither filename was passed and the vendored+ # class's 2.3-named defaults supplied both. Per generation:+ # see hq_weights().+ "dev_transformer": hq_weights()["dev_transformer"],+ "distilled_lora": hq_weights()["distilled_lora"],"prompt": p["prompt"],"negative_prompt": p.get("negative_prompt", ""),"output_path": str(raw_out),@@ -13782,10 +15533,19 @@ 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")job_spec = {"action": "generate","id": job["id"],"params": {+ # The base render finally states WHICH weights it wants+ # instead of inheriting whatever LTX_MODEL the helper was+ # spawned with. base_model_dir() resolves to MODEL_ID for the+ # active version, so this is the same directory the helper+ # 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(),"mode": mode,"prompt": p["prompt"],"negative_prompt": p.get("negative_prompt", ""),@@ -13960,7 +15720,11 @@ def run_job_inner(job: dict) -> None:"started": job.get("started_at"),"elapsed_sec": round(time.time() - job["started_ts"], 2) if job.get("started_ts") else None,"video_duration_sec": video_duration(frames),- "fps": FPS, "model": MODEL_ID, "queue_id": job["id"],+ # 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"],"helper_elapsed_sec": result.get("elapsed_sec"),"output_codec": output_codec_settings(),"memory_policy": memory_plan,@@ -14809,6 +16573,13 @@ class Handler(BaseHTTPRequestHandler):payload["outputs"] = _outspayload["outputs_total"] = _outs_totalpayload["hidden_count"] = hidden_count+ # Storyboards — one line per board. Three jobs, all of them cheap:+ # the `S03/12` badge on a queue card needs the denominator, the tab+ # count during an overnight run needs `running`, and `To film` in+ # the player overlay stays hidden until this list is non-empty+ # (rule 5 — with no film in progress the panel looks exactly as it+ # did yesterday).+ payload["storyboards"] = _sb_all_summaries()payload["memory"] = get_memory()payload["comfy_pids"] = find_comfy_pids()payload["server_now"] = time.time()@@ -14893,7 +16664,7 @@ class Handler(BaseHTTPRequestHandler):_q8_available = q8_available_anywhere()payload["q8_available"] = _q8_availablepayload["q8_missing"] = [] if _q8_available else _q8_missing- payload["q8_path"] = str(Q8_LOCAL_PATH)+ payload["q8_path"] = str(pack_path("q8"))payload["base_available"] = not _base_missingpayload["base_missing"] = _base_missing# Repo-level counts for the header pill — granular view that@@ -15667,6 +17438,28 @@ class Handler(BaseHTTPRequestHandler):self._json({"characters": list_characters()})return+ # ---- Storyboard reads ------------------------------------------+ if parsed.path == "/storyboard/list":+ self._json({"ok": True, "boards": _sb_all_summaries()})+ return+ if parsed.path == "/storyboard/get":+ bid = (parse_qs(parsed.query).get("id") or [""])[0].strip()+ try:+ board = storyboard.load_storyboard(STATE_DIR, bid)+ except Exception as exc: # noqa: BLE001+ self._json({"ok": False, "error": str(exc)}, 404)+ return+ # Reconcile job ids -> shot status BEFORE replying, and save if the+ # queue told us something the board didn't know. This is what makes+ # a panel restart mid-render invisible to the user.+ try:+ if _sb_reconcile(board):+ storyboard.save_storyboard(STATE_DIR, board)+ except Exception:+ pass+ self._json(_sb_payload(board))+ return+# Progress poll for the one-click sample-character download.if parsed.path == "/characters/download-sample/status":with _sample_char_lock:@@ -16263,6 +18056,497 @@ class Handler(BaseHTTPRequestHandler):self.send_error(404)+ # ---- Storyboard writes ---------------------------------------------+ # One method rather than fourteen `if path ==` blocks in do_POST, because+ # every one of them shares the same three opening moves (find the board,+ # normalise it, reply with the full payload the plan screen repaints from).+ # Called from do_POST AFTER the body/form parse — the routes below read+ # both, and /storyboard/save posts JSON rather than a form.+ def _storyboard_post(self, action: str, body: str, form: dict) -> None:+ def f(name: str, default: str = "") -> str:+ v = form.get(name, default)+ if isinstance(v, list):+ v = v[0] if v else default+ return (v or "").strip() or default++ def load(bid: str):+ return storyboard.load_storyboard(STATE_DIR, bid)++ try:+ # ---- plan / re-plan -----------------------------------------+ if action == "plan":+ concept = f("concept", "")+ bid = f("id", "")+ notes = f("notes", "")+ if not concept and not bid:+ self._json({"ok": False,+ "error": "Write a couple of sentences about the "+ "film first."}, 400)+ return+ # Constraint 1, enforced server-side: a stale tab must not be+ # able to start a planner while the renderer holds the memory.+ with LOCK:+ busy = bool(STATE.get("running")) or bool(STATE.get("queue"))+ if busy:+ self._json({"ok": False, "busy": True,+ "error": "The renderer is using the memory. "+ "Planning can start when the queue is "+ "empty."}, 409)+ return+ # Take the ONE planner slot first. Everything below writes to+ # disk, and a refusal after that leaves a dead "Planning…" board+ # claiming state=running forever.+ err = _sb_claim_planner(bid or "-pending-")+ if err:+ self._json({"ok": False, "busy": True, "error": err}, 409)+ return+ previous = None+ if bid:+ try:+ board = load(bid)+ previous = {k: board.get(k) for k in+ ("schema", "id", "title", "cast", "policy", "shots")}+ concept = concept or board.get("concept") or ""+ except Exception:+ bid = ""+ if not bid:+ bid = "sb_%s_%s" % (time.strftime("%Y%m%d"),+ hashlib.sha1(+ (concept + str(time.time())).encode()+ ).hexdigest()[:6])+ board = storyboard.new_storyboard(bid, "Planning…")+ # Offer the number or refuse it — never quietly render a+ # different film. A brief that asked for 4 shots used to come+ # back as a 12-shot board with no message anywhere. The four+ # chips are what the UI OFFERS; they were never meant to be the+ # only counts the API accepts.+ _raw_shots = f("shots", "")+ if _raw_shots:+ try:+ shots_n = int(str(_raw_shots).strip())+ except (TypeError, ValueError):+ _sb_release_planner(bid, "-pending-")+ self._json({"ok": False,+ "error": f"shots must be a whole number "+ f"(got {_raw_shots!r})."}, 400)+ return+ if not (1 <= shots_n <= STORYBOARD_MAX_SHOTS):+ _sb_release_planner(bid, "-pending-")+ self._json({"ok": False,+ "error": f"shots must be between 1 and "+ f"{STORYBOARD_MAX_SHOTS} (got {shots_n})."}, 400)+ return+ else:+ shots_n = int(get_settings().get("storyboard_shots", 12) or 12)+ must = [x.strip() for x in (f("must", "") or "").splitlines() if x.strip()]+ emode = (f("engine", "") or board.get("engine_mode")+ or get_settings().get("storyboard_engine", "auto")).strip().lower()+ if emode not in storyboard.ENGINE_MODES:+ emode = storyboard.DEFAULT_ENGINE_MODE+ # An H3-only film cannot carry a trained character: H3 has no+ # LoRA path, so the trigger would do nothing and a stranger's+ # face would render. Refuse the pair here rather than plan a+ # film that can't keep its promise.+ cid = f("character_id", "")+ if emode == "h3" and cid:+ _sb_release_planner(bid, "-pending-")+ 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)+ return+ chars = [c for c in (list_characters() or []) if c.get("id") == cid] if cid else []+ board["engine_mode"] = emode+ board["concept"] = concept+ board["style"] = f("style", "")+ board["must"] = must+ board["shots_target"] = shots_n+ board["cast"] = [{"id": c.get("id"),+ "trigger": c.get("trigger") or c.get("id")}+ for c in chars]+ board.setdefault("policy", _sb_policy_for(+ get_settings().get("storyboard_draft_quality", "quick"),+ get_settings().get("storyboard_final_quality", "standard")))+ _sb_set_planner(board, state="running", stage="load", error=None)+ storyboard.save_storyboard(STATE_DIR, board)+ # The slot was claimed under a placeholder before the id existed+ # (a brand-new board mints its id above); move it onto the real+ # one now that nothing else can fail.+ with _SB_LOCK:+ _SB_PLANNERS.pop("-pending-", None)+ _SB_PLANNERS.setdefault(bid, {"cancelled": False})+ th = threading.Thread(+ target=_sb_plan_thread, daemon=True, name=f"phos-sb-plan-{bid}",+ args=(bid, {"concept": concept, "n_shots": shots_n,+ "style": board["style"], "characters": chars,+ "must": must, "feedback": notes or None,+ "engine_mode": emode},+ previous if notes else None))+ with _SB_LOCK:+ _SB_PLANNERS[bid]["thread"] = th+ th.start()+ self._json({"ok": True, "id": bid}, 202)+ return++ if action == "cancel":+ bid = f("id", "")+ with _SB_LOCK:+ entry = _SB_PLANNERS.get(bid)+ if entry:+ entry["cancelled"] = True+ sess = entry.get("session")+ else:+ sess = None+ # release() from another thread kills the child and makes the+ # blocked plan_film() call raise into its own finally.+ if sess is not None:+ try:+ sess.release()+ except Exception:+ pass+ try:+ board = load(bid)+ # Same rename the failed path does: a cancelled board must+ # not sit in the list called "Planning…" forever, where it+ # is indistinguishable from one that really is planning.+ if (not (board.get("shots") or [])+ and board.get("title") in ("", "Planning…", None)):+ _w = (board.get("concept") or "").split()+ board["title"] = " ".join(_w[:6]) or "Untitled film"+ _sb_set_planner(board, state="cancelled", stage=None)+ storyboard.save_storyboard(STATE_DIR, board)+ except Exception:+ pass+ self._json({"ok": True})+ return++ # ---- edit ----------------------------------------------------+ if action == "save":+ try:+ payload = json.loads(body or "{}")+ except json.JSONDecodeError as exc:+ self._json({"ok": False, "error": f"bad JSON: {exc}"}, 400)+ return+ bid = str(payload.get("id") or "").strip()+ incoming = payload.get("board")+ if not isinstance(incoming, dict):+ self._json({"ok": False, "error": "no board"}, 400)+ return+ board = load(bid)+ # Only the fields the plan screen can edit. Everything else on+ # disk (job ids, outputs, planner metadata) is the server's and+ # a stale tab must not be able to roll it back.+ for k in ("title", "concept", "style", "must", "shots_target", "policy"):+ if k in incoming:+ board[k] = incoming[k]+ if isinstance(incoming.get("shots"), list):+ bad = [i for i, x in enumerate(incoming["shots"])+ if not isinstance(x, dict)]+ if bad:+ # Silently dropping these turned 6 shots into 5 with a+ # 200. Refuse instead of quietly editing the film.+ self._json({"ok": False,+ "error": f"shots {bad} are not objects"}, 400)+ return+ keep = {"draft_job_id", "final_job_id", "draft_output",+ "final_output", "error"}+ by_n = {s.get("n"): s for s in (board.get("shots") or [])+ if isinstance(s, dict)}+ merged = []+ for s in incoming["shots"]:+ if not isinstance(s, dict):+ continue+ old = by_n.get(s.get("n")) or {}+ for k in keep:+ if k in old and k not in s:+ s[k] = old[k]+ merged.append(s)+ board["shots"] = merged+ _sb_normalize(board)+ storyboard.save_storyboard(STATE_DIR, board)+ self._json(_sb_payload(board))+ return++ if action == "grade":+ board = load(f("id", ""))+ try:+ n = int(f("n", "0"))+ except (TypeError, ValueError):+ n = 0+ grade = f("grade", "") or None+ if grade not in (None, "keep", "reroll", "cut"):+ self._json({"ok": False, "error": "bad grade"}, 400)+ return+ for s in (board.get("shots") or []):+ if isinstance(s, dict) and s.get("n") == n:+ s["grade"] = grade+ if "note" in form:+ s["note"] = f("note", "")+ # CUT is the one verdict that changes scheduling:+ # shooting_order() and estimate() already exclude+ # "skipped", so no new filtering logic anywhere.+ if grade == "cut":+ s["status"] = "skipped"+ elif s.get("status") == "skipped":+ s["status"] = "done" if s.get("draft_output") else "pending"+ break+ board["updated_at"] = int(time.time())+ storyboard.save_storyboard(STATE_DIR, board)+ # A CUT draft will never be refined — let its Stage-A cache go.+ _sb_sweep_stage_a(board)+ self._json(_sb_payload(board))+ return++ if action == "estimate":+ board = load(f("id", ""))+ pass_name = f("pass", "draft")+ only = [int(x) for x in (f("only", "") or "").split(",") if x.strip().isdigit()]+ if only:+ import copy as _copy+ board = _copy.deepcopy(board)+ for s in (board.get("shots") or []):+ if isinstance(s, dict) and s.get("n") not in only:+ s["status"] = "skipped"+ for s in (board.get("shots") or []):+ if isinstance(s, dict) and s.get("n") in only:+ s["status"] = "pending"+ self._json({"ok": True,+ "estimate": storyboard.estimate(board, pass_name=pass_name,+ h3_cost=_sb_h3_cost)})+ return++ # ---- render --------------------------------------------------+ if action == "render":+ bid = f("id", "")+ board = load(bid)+ pass_name = "final" if f("pass", "draft") == "final" else "draft"+ only = [int(x) for x in (f("only", "") or "").split(",") if x.strip().isdigit()]+ errs = storyboard.validate_storyboard_detail(+ board, known_character_ids=_sb_known_character_ids(),+ ref_root=OUTPUT, max_dim=_sb_max_dim())+ if errs:+ # Never render a plan the validator rejected — that is the+ # entire reason the validator exists.+ self._json({"ok": False, "errors": errs}, 400)+ return+ with _SB_LOCK:+ # GLOBAL, not per board: the planner and the renderer share+ # one pool of memory, so ANY plan in flight blocks a render,+ # not just this film's. The other direction is checked in+ # _sb_claim_planner().+ if _SB_PLANNERS:+ self._json({"ok": False, "busy": True,+ "error": "A film is still being planned. "+ "Rendering can start when it's "+ "finished."}, 409)+ return+ _live = _SB_RENDERS.get(bid)+ if _live and not _live.get("stop"):+ self._json({"ok": False,+ "error": "This film is already rendering."}, 409)+ return+ if _live:+ # Stopped, but the dispatch thread hasn't woken from its+ # 5 s wait to release the slot yet. Saying "already+ # rendering" here is a sentence about a thread, not+ # about the film.+ self._json({"ok": False,+ "error": "Still stopping the previous run — "+ "try again in a moment."}, 409)+ return+ _SB_RENDERS[bid] = {"stop": False, "pass": pass_name, "queued": 0}+ # A final pass re-renders at the draft's seed, which is already+ # pinned onto the shot by the reconciler.+ if pass_name == "final":+ for s in (board.get("shots") or []):+ if isinstance(s, dict) and (not only or s.get("n") in only):+ s.pop("final_job_id", None)+ storyboard.save_storyboard(STATE_DIR, board)+ th = threading.Thread(target=_sb_render_thread, daemon=True,+ name=f"phos-sb-render-{bid}",+ args=(bid, pass_name, only or None))+ with _SB_LOCK:+ _SB_RENDERS[bid]["thread"] = th+ th.start()+ self._json({"ok": True, "queued": len(only) if only else None}, 202)+ return++ if action == "stop":+ bid = f("id", "")+ with _SB_LOCK:+ entry = _SB_RENDERS.get(bid)+ if entry:+ entry["stop"] = True+ board = load(bid)+ # Remove ONLY this board's queued jobs, through the same code+ # path removeJob(id) uses. Never /queue/clear — another+ # feature's jobs may be in there.+ mine = set()+ for s in (board.get("shots") or []):+ if not isinstance(s, dict):+ continue+ for k in ("draft_job_id", "final_job_id"):+ if s.get(k):+ mine.add(s[k])+ removed = 0+ with QUEUE_COND:+ before = len(STATE["queue"])+ STATE["queue"] = [j for j in STATE["queue"] if j.get("id") not in mine]+ removed = before - len(STATE["queue"])+ QUEUE_COND.notify_all()+ persist_queue()+ for s in (board.get("shots") or []):+ if isinstance(s, dict) and s.get("status") in ("queued",):+ s["status"] = "pending"+ storyboard.save_storyboard(STATE_DIR, board)+ push(f"[storyboard] stopped — {removed} queued shot(s) removed; "+ f"the shot in flight finishes")+ self._json({"ok": True, "removed": removed})+ return++ if action == "replan-shots":+ bid = f("id", "")+ board = load(bid)+ ns = [int(x) for x in (f("ns", "") or "").split(",") if x.strip().isdigit()]+ if not ns:+ self._json({"ok": False, "error": "no shots named"}, 400)+ return+ with LOCK:+ busy = bool(STATE.get("running")) or bool(STATE.get("queue"))+ if busy:+ self._json({"ok": False, "busy": True,+ "error": "The renderer is using the memory. "+ "Planning can start when the queue is "+ "empty."}, 409)+ return+ err = _sb_claim_planner(bid)+ if err:+ self._json({"ok": False, "busy": True, "error": err}, 409)+ return+ notes = []+ for s in (board.get("shots") or []):+ if isinstance(s, dict) and s.get("n") in ns:+ notes.append("shot %d: %s" % (s["n"], (s.get("note") or "").strip()+ or "the director rejected this shot — "+ "write a different one"))+ previous = {k: board.get(k) for k in+ ("schema", "id", "title", "cast", "policy", "shots")}+ chars = [c for c in (list_characters() or [])+ if c.get("id") in {x.get("id") for x in (board.get("cast") or [])}]+ th = threading.Thread(+ target=_sb_plan_thread, daemon=True, name=f"phos-sb-reroll-{bid}",+ args=(bid, {"concept": board.get("concept") or "",+ "n_shots": len(board.get("shots") or []),+ "style": board.get("style") or "",+ "characters": chars,+ "must": board.get("must") or [],+ "feedback": "\n".join(notes),+ "engine_mode": board.get("engine_mode") or "auto",+ "reroll_ns": ns},+ previous))+ with _SB_LOCK:+ _SB_PLANNERS[bid]["thread"] = th+ th.start()+ self._json({"ok": True}, 202)+ return++ # ---- shared state --------------------------------------------+ if action == "add-shot":+ bid = f("id", "")+ clip = f("path", "")+ p = Path(clip)+ if not p.is_file() or OUTPUT.resolve() not in p.resolve().parents:+ self._json({"ok": False, "error": "no such clip"}, 400)+ return+ try:+ meta = json.loads((p.parent / (p.name + ".json")).read_text(encoding="utf-8"))+ except Exception:+ meta = {}+ params = meta.get("params") or {}+ if bid in ("", "new"):+ bid = "sb_%s_%s" % (time.strftime("%Y%m%d"),+ hashlib.sha1(str(time.time()).encode()).hexdigest()[:6])+ board = storyboard.new_storyboard(bid, "Untitled film")+ board["policy"] = _sb_policy_for(+ get_settings().get("storyboard_draft_quality", "quick"),+ get_settings().get("storyboard_final_quality", "standard"))+ else:+ board = load(bid)+ cid = params.get("character_id") or ""+ try:+ dur = round(float(params.get("frames") or 121)+ / float(params.get("frame_rate") or 24.0), 1)+ except Exception:+ dur = 5.0+ shot = {+ "n": len(board.get("shots") or []) + 1,+ "title": p.stem[:60],+ "mode": "character" if cid else "text",+ "engine": (params.get("engine") or "ltx"),+ "prompt": params.get("prompt") or "",+ "duration_s": max(1.0, min(60.0, dur)),+ "seed": (meta.get("seed_used") if isinstance(meta.get("seed_used"), int)+ else params.get("seed_used") if isinstance(params.get("seed_used"), int)+ else -1),+ "refs": [], "status": "done",+ "draft_output": str(p),+ }+ if cid:+ shot["character_id"] = cid+ shot["trigger"] = params.get("trigger") or cid+ board.setdefault("shots", []).append(shot)+ _sb_normalize(board)+ storyboard.save_storyboard(STATE_DIR, board)+ self._json({"ok": True, "id": bid, "n": shot["n"],+ "title": board.get("title") or ""})+ return++ # ---- export / housekeeping -----------------------------------+ if action == "export":+ board = load(f("id", ""))+ self._json(_sb_export(board))+ return++ if action == "reveal":+ board = load(f("id", ""))+ title = board.get("title") or "storyboard"+ day = time.strftime("%Y-%m-%d",+ time.localtime(board.get("created_at") or time.time()))+ d = OUTPUT / "storyboards" / f"{day}_{_sb_slug(title, 6)}"+ if not d.is_dir():+ self._json({"ok": False, "error": "nothing exported yet"}, 404)+ return+ try:+ subprocess.Popen(["open", str(d)])+ except Exception as exc: # noqa: BLE001+ self._json({"ok": False, "error": str(exc)}, 500)+ return+ self._json({"ok": True})+ return++ if action == "delete":+ bid = f("id", "")+ with _SB_LOCK:+ if bid in _SB_RENDERS or bid in _SB_PLANNERS:+ self._json({"ok": False,+ "error": "Stop the film first."}, 409)+ return+ d = storyboard.board_dir(STATE_DIR, bid)+ if d.is_dir() and d.resolve().parent == (STATE_DIR / "storyboards").resolve():+ shutil.rmtree(d, ignore_errors=True)+ # Deletes the plan. The clips it rendered stay in mlx_outputs/.+ self._json({"ok": True})+ return++ self._json({"ok": False, "error": f"unknown storyboard action: {action}"}, 404)+ except storyboard.StoryboardError as exc:+ _sb_release_stranded_claim(action)+ self._json({"ok": False, "error": str(exc)}, 404)+ except Exception as exc: # noqa: BLE001+ _sb_release_stranded_claim(action)+ push(f"[storyboard] {action} failed: {exc}")+ self._json({"ok": False, "error": str(exc)}, 500)+def do_POST(self) -> None:if not self._is_local_request():self.send_error(403, "non-local request rejected")@@ -17310,6 +19594,14 @@ class Handler(BaseHTTPRequestHandler):self._json({"ok": True, "id": job["id"]})return+ # ====== Storyboard — plan a film, then shoot it ====================+ # Sits with the /queue/* cluster on purpose: every one of these routes+ # ends up going through the SAME make_job -> STATE["queue"] contract+ # above, and none of them has a private execution path.+ if path.startswith("/storyboard/"):+ self._storyboard_post(path[len("/storyboard/"):], body, form)+ return+# ====== Characters — thin wrapper around /queue/add ================# 2026-05-16 rewrite (Mr Bizarro): the prior version translated the user's# request through a 25-field "locked recipe" composer + an auto@@ -18362,16 +20654,20 @@ class Handler(BaseHTTPRequestHandler):),}, 409)return- # `git status --porcelain` is empty iff the working tree is- # clean. The UI's clean-check uses the same probe.- dirty = (_git_capture(["status", "--porcelain"]) or "").strip()+ # `git status --porcelain -uno` is empty iff no TRACKED file is+ # modified. Same probe (and same -uno reasoning) as+ # _detect_local_install_state — see the long note there: the+ # installers legitimately leave untracked dirs in this tree+ # (minimax-h3-mlx/, cache/, logs/) and refusing to pull because+ # of them is what left every H3 user unable to update (#52).+ dirty = (_git_capture(["status", "--porcelain", "-uno"]) or "").strip()if dirty:self._json({"ok": False,"error": ("refusing to pull: local working tree has "- "uncommitted changes. Commit, stash, or discard "- "them, then click Update again."+ "uncommitted changes to tracked files. Commit, "+ "stash, or discard them, then click Update again."),"dirty_files": dirty.splitlines()[:20],}, 409)@@ -18821,7 +21117,10 @@ class Handler(BaseHTTPRequestHandler):if not repo:self._json({"error": f"unknown repo key: {key!r}. Valid keys: "f"{[r['key'] for r in _repos()]}"}, 400); return- if HF_BIN is None:+ # A GitHub-release-mirrored pack does not go through `hf` at all+ # (scripts/fetch_pack_release.py is stdlib-only), so a missing hf+ # binary must not block the one lane that never needed it.+ if HF_BIN is None and (repo.get("mirror") or {}).get("kind") != "github-release":self._json({"error": "hf binary not found. Reinstall Phosphene ""or install huggingface_hub>=1.0 in the venv."}, 500); returnwith DOWNLOAD_LOCK:@@ -18889,7 +21188,7 @@ class Handler(BaseHTTPRequestHandler):if not bad:self._json({"ok": True, "nothing_to_repair": True,"note": f"no corrupt files detected for {key!r}"}); return- if HF_BIN is None:+ if HF_BIN is None and (repo.get("mirror") or {}).get("kind") != "github-release":self._json({"error": "hf binary not found. Reinstall Phosphene."}, 500); returntarget = Q8_LOCAL_PATH if key == "q8" else (ROOT / repo["local_dir"])deleted = []@@ -19445,34 +21744,84 @@ def _compute_progress(current: dict | None, log_lines: list[str]) -> dict | None# ---- HTML ---------------------------------------------------------------------def _resolve_cap_tier() -> str:- """Capability tier the Manual surface organizes around.+def _resolve_quant_tier() -> str:+ """QUANTISATION LEVEL this Mac can run. A statement about RAM, nothing+ else: "q8" on Comfortable+ (>= 48 GB, the dev transformer fits), "q4"+ on Compact (< 48 GB).- "q8" — Comfortable+ machines (>= 48 GB RAM, Q8 weights installable).- Manual surface offers character / FFLF / extend / lip-dub.- Q4 still available as a per-render compute fallback for- plain Text/Image renders.- "q4" — Compact tier (< 48 GB). Manual surface only shows what- actually works: Text + Image, style LoRAs, HDR, joint audio.- Character / FFLF / Extend are hidden entirely because the- dev transformer doesn't fit in RAM.+ This is one half of what the single `cap_tier` string used to mean. It+ is deliberately model-version-blind — a Mac's memory does not change+ when a new checkpoint generation ships.`LTX_FORCE_CAP_TIER=q4|q8` overrides — useful for testing the Q4surface on a high-RAM dev machine (Mr Bizarro's M4 Max defaults to q8;- `LTX_FORCE_CAP_TIER=q4 ./run.sh` reveals the low-RAM layout)."""+ `LTX_FORCE_CAP_TIER=q4 ./run.sh` reveals the low-RAM layout). The env+ var keeps its old name because it is documented, in the notes, and in+ people's shell history."""override = (os.environ.get("LTX_FORCE_CAP_TIER", "") or "").strip().lower()if override in ("q4", "q8"):return overridereturn "q8" if SYSTEM_CAPS.get("allows_q8") else "q4"+def _resolve_cap_tier(version_id: str | None = None) -> str:+ """FEATURE TIER the Manual surface organizes around — the other half.++ "q8" — Manual surface offers character / FFLF / extend / lip-dub.+ Q4 still available as a per-render compute fallback for+ plain Text/Image renders.+ "q4" — Manual surface only shows what actually works: Text + Image,+ style LoRAs, HDR, joint audio. Character / FFLF / Extend are+ hidden entirely.++ WHY THE SPLIT: the one string used to answer both questions, and the+ two answers were only ever the same because there was exactly one model+ version and it shipped both quantisations. The moment a version ships+ q4 weights only (which is exactly how LTX-2.5 lands -- distilled q4+ first, q8 in a second wave), a 128 GB Mac still resolves "q8" from RAM+ and the panel offers Extend, Keyframe and High against weights that do+ not exist. That is a job-time RuntimeError at best and a wrong-base+ render at worst.++ So the feature tier is now the machine's quant tier CLAMPED to what the+ active model version declares it can serve (registry `cap_tiers`). For+ LTX-2.3, which declares both, the clamp is a no-op and this returns+ exactly what it always did.++ Note this is the OFFER, not the guarantee: a version can declare a q8+ surface while that pack is still downloading. Presence stays the job of+ q8_missing_files() / pack_missing_files(), which every gate already+ calls -- one asks "can this generation do it at all", the other asks+ "are the bytes here"."""+ quant = _resolve_quant_tier()+ tiers = version_cap_tiers(version_id)+ if quant in tiers:+ return quant+ # The version can't serve this machine's quant tier. Fold DOWN to the+ # richest surface it can serve that this Mac can still run — never up,+ # or a Compact machine gets offered a q8-only generation it has no RAM+ # for. `order` is poorest → richest.+ order = ("q4", "q8")+ reachable = [t for t in order+ if t in tiers and order.index(t) <= order.index(quant)]+ if reachable:+ return reachable[-1]+ # Nothing this version ships is runnable here. Report the machine's own+ # tier so the surface is at least honest about the hardware; the pack+ # gates refuse the job with the real reason.+ return quant++def page() -> str:cap_tier = _resolve_cap_tier()bootstrap = json.dumps({"presets": PRESETS, "aspects": ASPECTS,"default_image": str(REFERENCE),"default_audio": str(AUDIO_DEFAULT),- "fps": FPS, "model": MODEL_ID,+ # Same fix as the sidecar: the model chip should name the generation+ # actually loaded. Identical bytes for the default version, so a 2.3+ # user's page.html is unchanged.+ "fps": FPS, "model": base_model_dir(),"profile": PROFILE,"model_upscale_enabled": MODEL_UPSCALE_ENABLED,"pipersr_upscale_enabled": PIPERSR_UPSCALE_ENABLED,@@ -19501,6 +21850,10 @@ 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(),+ # 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.+ "storyboard": storyboard_status(),# The engine registry (see ENGINES). The header switcher, the mode# gate, the surface swap and the accent tints are all rendered from# this list — adding an engine is one entry there, not a UI rewrite.@@ -19998,6 +22351,595 @@ HTML = r"""<!doctype html>body[data-workflow="audio"] #trainSection { display: none !important; }body[data-workflow="audio"] #audioSectionTab { display: block; }+ /* =========================================================+ STORYBOARD — the workflow fold + its own surfaces+ =========================================================+ Same shape as the audio fold above, plus one extra move: the shot+ list takes the GALLERY's slot in the stage column and the player+ stays where it is. That is what makes shared state free — clicking a+ shot's thumbnail calls the existing selectOutput() and the existing+ player, Params/Extend/Expand overlay and lightbox all work unchanged.++ Everything below is built from existing tokens. No new colours, no+ fonts, no libraries — the panel is offline-capable and dark-only. */+ body[data-workflow="storyboard"] #modelsInline,+ body[data-workflow="storyboard"] #modeGroup,+ body[data-workflow="storyboard"] aside.form-pane > h2,+ body[data-workflow="storyboard"] #genForm,+ body[data-workflow="storyboard"] #studioSection,+ body[data-workflow="storyboard"] #trainSection,+ body[data-workflow="storyboard"] #audioSectionTab { display: none !important; }+ body[data-workflow="storyboard"] #sbSectionTab { display: block; }+ /* form-pane children get no padding by default (the sticky-footer pin+ math depends on it) — match #genForm's. */+ .form-pane > #sbSectionTab { padding: 0 18px; }++ body[data-workflow="storyboard"] .stage-pane > .carousel-wrap,+ body[data-workflow="storyboard"] .ideo-stage-bar,+ body[data-workflow="storyboard"] .ideo-canvas-host { display: none !important; }+ /* #modelTag names the ONE model the current surface renders on, which is+ what makes it a lie here: a film picks its engine per shot, so a footer+ reading "ltx-2.3-mlx-q4" is read as "LTX is selected" — reported by the+ owner on first contact with this tab. It folds away for exactly the same+ reason #engineSwitch does (see _currentSurface), and #sbEngineNote below+ says what actually decides. */+ body[data-workflow="storyboard"] #modelTag { display: none !important; }+ body[data-workflow="storyboard"] #sbStage { display: flex; }+ /* Plan-only phases want the whole column — the same trick the Ideogram+ layout editor uses, so there is one mechanism for "this surface needs+ the stage" rather than two. */+ body[data-workflow="storyboard"].sb-full .stage-pane > .player-surface { display: none; }++ #sbStage {+ display: none;+ flex: 1 1 auto;+ flex-direction: column;+ /* Never collapse to a sliver: the gallery this replaces is a short+ horizontal strip and is happy with 130px, a shot list is not. */+ min-height: 240px;+ overflow-y: auto;+ padding-right: 2px;+ }+ /* .player-surface is width-driven (`width:100%` + aspect-ratio), so in the+ wide stage column it grows to ~690px and leaves the shot list a sliver.+ Flip it to height-driven while the list is sharing the column — the SAME+ idiom .player-surface[data-orient="vertical"] already uses for the same+ reason, so there is one mechanism here, not two. When the list has the+ column to itself (body.sb-full) the player is hidden anyway. */+ body[data-workflow="storyboard"]:not(.sb-full) .stage-pane > .player-surface {+ width: auto;+ max-width: 100%;+ height: min(46vh, calc(100vh - 420px));+ max-height: min(46vh, calc(100vh - 420px));+ }+ /* ---- the brief (left column) ---------------------------------- */+ .sb-brief { margin-bottom: 12px; }+ .sb-concept { min-height: 92px; }+ .sb-input, .sb-textarea {+ width: 100%; padding: 8px 10px;+ background: var(--panel-2); border: 1px solid var(--border);+ border-radius: var(--r-sm); color: var(--text);+ font-size: 12.5px; font-family: inherit; line-height: 1.5;+ }+ .sb-textarea { resize: vertical; min-height: 68px; }+ .sb-input:focus, .sb-textarea:focus {+ outline: none; border-color: var(--accent);+ box-shadow: 0 0 0 3px var(--accent-dim);+ }+ #sbSectionTab .cz-control { margin-bottom: 14px; }+ .sb-ramline {+ font-size: 11.5px; line-height: 1.45; color: var(--muted);+ margin-bottom: 9px; display: flex; align-items: center; gap: 6px;+ }+ .sb-boards { margin: 12px 0 14px; }+ .sb-boards-head {+ font-size: 11px; font-weight: 600; color: var(--muted);+ text-transform: uppercase; letter-spacing: 0.06em; margin-bottom: 6px;+ }+ .sb-boards[hidden] { display: none !important; }++ /* ---- planning -------------------------------------------------- */+ .sb-planning {+ flex: 1 1 auto;+ display: flex; flex-direction: column; align-items: center;+ justify-content: center; gap: 12px; text-align: center;+ padding: 40px 20px;+ }+ .sb-planning[hidden] { display: none !important; }+ .sb-planning-mark {+ width: 54px; height: 44px; position: relative; opacity: 0.75;+ }+ .sb-planning-mark i {+ position: absolute; left: 0; right: 0; height: 12px;+ border: 1px solid var(--accent); border-radius: 3px;+ background: var(--accent-dim);+ animation: sbFrames 1.8s ease-in-out infinite;+ }+ .sb-planning-mark i:nth-child(1) { top: 0; animation-delay: 0s; }+ .sb-planning-mark i:nth-child(2) { top: 16px; animation-delay: 0.25s; }+ .sb-planning-mark i:nth-child(3) { top: 32px; animation-delay: 0.5s; }+ @keyframes sbFrames {+ 0%, 100% { opacity: 0.25; transform: translateX(0); }+ 50% { opacity: 1; transform: translateX(4px); }+ }+ .sb-planning-title { font-size: 15px; font-weight: 600; color: var(--text); }+ .sb-planning-sub { font-size: 12px; color: var(--muted); }+ .sb-planning-steps {+ display: flex; flex-direction: column; gap: 7px;+ margin-top: 8px; text-align: left;+ }+ .sb-step {+ display: flex; align-items: center; gap: 9px;+ font-size: 12px; color: var(--muted); opacity: 0.55;+ transition: opacity var(--t-base), color var(--t-base);+ }+ .sb-step[hidden] { display: none !important; }+ .sb-step-dot {+ width: 8px; height: 8px; border-radius: 50%;+ border: 1px solid var(--border-strong); flex: 0 0 auto;+ }+ .sb-step.is-now { opacity: 1; color: var(--text); }+ .sb-step.is-now .sb-step-dot {+ border-color: var(--accent); background: var(--accent);+ animation: sbPulse 1.2s ease-in-out infinite;+ }+ .sb-step.is-done { opacity: 0.9; }+ .sb-step.is-done .sb-step-dot {+ border-color: var(--success); background: var(--success);+ }+ @keyframes sbPulse { 0%,100% { opacity: 1; } 50% { opacity: 0.35; } }++ /* ---- empty state ---------------------------------------------- */+ .sb-empty {+ flex: 1 1 auto;+ display: flex; flex-direction: column; align-items: center;+ justify-content: center; gap: 10px; text-align: center;+ padding: 36px 24px; max-width: 520px; margin: 0 auto;+ }+ .sb-empty[hidden] { display: none !important; }+ .sb-empty-icon { color: var(--text); opacity: 0.35; }+ .sb-empty-title { font-size: 16px; font-weight: 600; color: var(--text); }+ .sb-empty-sub { font-size: 12.5px; line-height: 1.6; color: var(--muted); }+ .sb-empty-steps {+ list-style: none; padding: 0; margin: 10px 0 0;+ display: flex; flex-direction: column; gap: 7px;+ text-align: left; font-size: 12px; color: var(--muted); line-height: 1.5;+ }+ .sb-empty-steps b { color: var(--text); font-weight: 600; }++ /* ---- plan review ----------------------------------------------- */+ .sb-plan { flex: 1 1 auto; display: flex; flex-direction: column; min-height: 0; }+ .sb-plan[hidden] { display: none !important; }+ .sb-plan-head { position: relative; z-index: 4; }+ .sb-title {+ flex: 1 1 auto; min-width: 120px;+ background: transparent; border: 1px solid transparent;+ border-radius: var(--r-sm);+ color: var(--text); font-size: 14px; font-weight: 600;+ padding: 4px 7px; font-family: inherit;+ }+ .sb-title:hover { border-color: var(--border); }+ .sb-title:focus {+ outline: none; border-color: var(--accent);+ box-shadow: 0 0 0 3px var(--accent-dim); background: var(--panel-2);+ }+ .sb-plan-status {+ font-size: 11px; color: var(--muted); white-space: nowrap;+ font-family: var(--ph-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);+ }+ #sbStageToggle {+ display: inline-flex; gap: 4px; padding: 3px;+ background: var(--bg-2); border: 1px solid var(--border);+ border-radius: 10px; flex: 0 0 auto;+ }+ #sbStageToggle[hidden] { display: none !important; }+ #sbStageToggle .smt-btn {+ appearance: none; border: 0; background: transparent;+ color: var(--muted); font: inherit; font-size: 12px; font-weight: 600;+ padding: 4px 12px; border-radius: 7px; cursor: pointer;+ transition: background var(--t-fast), color var(--t-fast);+ white-space: nowrap; width: auto;+ }+ #sbStageToggle .smt-btn:hover { color: var(--text); }+ #sbStageToggle .smt-btn.active { background: var(--accent); color: #fff; }++ .sb-summary {+ position: sticky; top: 0; z-index: 3;+ display: flex; align-items: stretch; gap: 8px; flex-wrap: wrap;+ padding: 10px 0 12px;+ background: linear-gradient(180deg, var(--bg) 0%, var(--bg) 62%,+ rgba(0, 6, 26, 0) 100%);+ }+ .sb-sum-cell {+ flex: 1 1 118px; min-width: 0;+ display: flex; flex-direction: column; gap: 2px;+ padding: 8px 10px;+ background: var(--panel); border: 1px solid var(--border);+ border-radius: var(--r-md);+ }+ .sb-sum-cell b {+ font-size: 13px; font-weight: 600; color: var(--text);+ white-space: nowrap; overflow: hidden; text-overflow: ellipsis;+ }+ .sb-sum-cell span { font-size: 10.5px; color: var(--muted); line-height: 1.4; }+ .sb-sum-cell.is-warn { border-color: rgba(210,153,34,0.45); }+ .sb-sum-cell.is-warn b { color: var(--warning); }+ .sb-runstrip { flex: 1 1 100%; display: flex; gap: 4px; }+ .sb-runstrip[hidden] { display: none !important; }+ .sb-runseg {+ display: flex; align-items: center; gap: 7px;+ padding: 5px 9px; min-width: 0;+ background: var(--panel-2); border: 1px solid var(--border);+ border-radius: var(--r-sm);+ font-size: 10.5px; color: var(--muted); cursor: default;+ }+ .sb-runseg:hover { border-color: var(--border-strong); }+ .sb-runseg-load {+ text-transform: uppercase; letter-spacing: 0.07em; font-weight: 700;+ font-size: 8.5px; color: var(--accent-bright);+ padding: 1px 5px; border-radius: var(--r-pill);+ background: var(--accent-dim); flex: 0 0 auto;+ }+ .sb-runseg-name {+ color: var(--text); font-weight: 500;+ overflow: hidden; text-overflow: ellipsis; white-space: nowrap;+ }+ .sb-runseg-shots {+ margin-left: auto; flex: 0 0 auto;+ font-family: var(--ph-font-mono, ui-monospace, Menlo, monospace);+ }+ .sb-errors {+ margin: 0 0 10px; padding: 9px 11px;+ border: 1px solid rgba(248,81,73,0.35); border-radius: var(--r-md);+ background: rgba(248,81,73,0.06);+ font-size: 11.5px; line-height: 1.55; color: var(--text);+ display: flex; flex-direction: column; gap: 5px;+ }+ .sb-errors[hidden] { display: none !important; }+ .sb-errors b, .sb-shot-err b { color: var(--text); font-weight: 600; }++ .sb-shots { list-style: none; margin: 0; padding: 0 0 8px; }+ .sb-shot {+ background: var(--panel);+ border: 1px solid var(--border-strong);+ border-left: 2px solid var(--border-strong);+ border-radius: var(--r-lg);+ padding: 10px 11px;+ margin-bottom: 9px;+ box-shadow: var(--shadow-1);+ transition: border-color var(--t-base), box-shadow var(--t-base);+ }+ .sb-shot:focus-within {+ border-color: var(--accent);+ box-shadow: 0 0 0 3px var(--accent-dim), var(--shadow-1);+ }+ .sb-shot.is-lit { border-color: var(--accent); }+ .sb-shot.has-error { border-left-color: var(--danger); }+ .sb-shot.is-dragging { opacity: 0.4; }+ .sb-shot.is-locked { opacity: 0.92; }+ .sb-shot.sb-drop-before { box-shadow: 0 -2px 0 0 var(--accent-bright); }+ .sb-shot.sb-drop-after { box-shadow: 0 2px 0 0 var(--accent-bright); }+ .sb-shot-head {+ display: flex; align-items: center; gap: 6px; flex-wrap: wrap;+ margin-bottom: 8px;+ }+ .sb-shot-n {+ font-family: var(--ph-font-mono, ui-monospace, Menlo, monospace);+ font-size: 12px; font-weight: 700; color: var(--accent-bright);+ flex: 0 0 auto;+ }+ .sb-seg {+ display: inline-flex; gap: 2px; padding: 2px;+ background: var(--bg-2); border: 1px solid var(--border);+ border-radius: var(--r-sm); flex: 0 0 auto;+ }+ .sb-seg-btn {+ width: auto; appearance: none; border: 0; background: transparent;+ color: var(--muted); font: inherit; font-size: 11px; font-weight: 600;+ padding: 3px 9px; border-radius: 5px; cursor: pointer;+ transition: background var(--t-fast), color var(--t-fast);+ }+ .sb-seg-btn:hover { color: var(--text); }+ .sb-seg-btn.active { background: var(--accent-dim); color: var(--accent-bright); }+ .sb-select {+ width: auto; padding: 3px 6px; font-size: 11px;+ background: var(--panel-2); border: 1px solid var(--border);+ border-radius: var(--r-sm); color: var(--text); font-family: inherit;+ max-width: 150px;+ }+ .sb-chip {+ font-size: 9px; font-weight: 700; letter-spacing: 0.07em;+ text-transform: uppercase; padding: 2px 7px;+ border-radius: var(--r-pill);+ border: 1px solid var(--border); color: var(--muted);+ flex: 0 0 auto; cursor: default;+ }+ /* The engine chip is a small .eng-seg: same glyph, same label, same accent+ variables, rendered from the SAME ENGINES registry row the header+ switcher is rendered from. No colours are typed here — a third engine+ lands with one table entry and this chip already knows how to wear it. */+ .sb-chip-engine {+ display: inline-flex; align-items: center; gap: 4px;+ letter-spacing: 0.04em; text-transform: none;+ color: var(--eng-accent, var(--muted));+ border-color: var(--eng-soft, var(--border));+ background: var(--eng-dim, transparent);+ }+ .sb-chip-engine .ph { width: 11px; height: 11px; }+ /* One quiet line saying what decides the engine, in the panel's own+ help-dot idiom (#h3WinHelpBtn + .h3-winhelp), Python-owned copy. */+ .sb-enginenote {+ display: flex; align-items: center; gap: 6px; flex: 1 1 100%;+ font-size: 11.5px; line-height: 1.45; color: var(--muted);+ padding: 0 2px;+ }+ .sb-enginenote[hidden] { display: none !important; }+ .sb-enginenote b { color: var(--text); font-weight: 600; }+ /* The film-level engine picker. .pill-group.cols-3 of .pill-btn — the same+ segmented grammar #qualityGroup and #sbDraftQuality use — with the+ engine's own glyph and accent from the ENGINES registry, so an active+ Hailuo pill is the same pink as its chip and its header segment. */+ #sbEngineGroup .pill-btn, #sbReplanEngineGroup .pill-btn {+ gap: 3px; padding: 8px 6px;+ }+ #sbEngineGroup .pill-btn .eng-mark .ph,+ #sbReplanEngineGroup .pill-btn .eng-mark .ph { width: 13px; height: 13px; }+ #sbEngineGroup .pill-btn.active, #sbReplanEngineGroup .pill-btn.active {+ color: var(--eng-accent, var(--accent-bright));+ border-color: var(--eng-soft, var(--accent));+ background: var(--eng-dim, var(--accent-dim));+ }+ /* Not installed is not dead — it is the install, exactly as the High+ quality chip's .needs-install state reads. */+ #sbEngineGroup .pill-btn.needs-install,+ #sbReplanEngineGroup .pill-btn.needs-install {+ opacity: 1; border-style: dashed;+ }+ #sbEngineGroup .pill-btn:disabled,+ #sbReplanEngineGroup .pill-btn:disabled { opacity: 0.4; cursor: not-allowed; }+ .sb-enginepick-note {+ font-size: 11px; line-height: 1.5; color: var(--muted);+ padding: 4px 2px 0;+ }+ .sb-enginepick-note:empty { display: none; }+ .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); }+ .sb-shot-est {+ font-size: 10.5px; color: var(--muted); flex: 0 0 auto;+ font-family: var(--ph-font-mono, ui-monospace, Menlo, monospace);+ }+ .sb-shot-spacer { flex: 1 1 auto; }+ .sb-icon {+ width: 22px; height: 22px; padding: 0; flex: 0 0 auto;+ display: inline-flex; align-items: center; justify-content: center;+ background: transparent; border: 1px solid transparent;+ border-radius: var(--r-sm); color: var(--muted);+ font-size: 11px; cursor: pointer; transition: var(--t-fast);+ }+ .sb-icon:hover:not(:disabled) {+ color: var(--text); border-color: var(--border); background: var(--panel-2);+ }+ .sb-icon:disabled { opacity: 0.3; cursor: not-allowed; }+ /* A pinned seed is a state worth seeing without a number taking a slot in+ the header row — the die lights, and the number is one click (or one+ hover) away. */+ .sb-icon.is-set { color: var(--accent-bright); }+ .sb-icon-danger:hover:not(:disabled) {+ color: var(--danger); border-color: rgba(248,81,73,0.4);+ background: rgba(248,81,73,0.08);+ }+ .sb-grip { color: var(--muted); opacity: 0.5; cursor: grab; font-size: 12px; }+ .sb-shot-prompt {+ width: 100%; min-height: 62px; resize: vertical;+ background: var(--bg-2); border: 1px solid var(--border);+ border-radius: var(--r-sm); color: var(--text);+ font-family: inherit; font-size: 12.5px; line-height: 1.55;+ padding: 7px 9px;+ }+ .sb-shot-prompt:focus {+ outline: none; border-color: var(--accent);+ box-shadow: 0 0 0 3px var(--accent-dim);+ }+ .sb-shot-prompt[readonly] { opacity: 0.7; cursor: default; }+ .sb-shot-err {+ margin-top: 7px; font-size: 11.5px; line-height: 1.5; color: var(--text);+ display: flex; flex-direction: column; gap: 5px;+ }+ .sb-shot-err[hidden] { display: none !important; }+ .sb-err-row { display: flex; align-items: flex-start; gap: 7px; }+ .sb-err-dot {+ width: 6px; height: 6px; border-radius: 50%; margin-top: 6px;+ background: var(--danger); flex: 0 0 auto;+ }+ .sb-err-fix {+ width: auto; flex: 0 0 auto; margin-left: 4px;+ padding: 2px 8px; font-size: 10.5px;+ background: var(--panel-2); border: 1px solid var(--border);+ border-radius: var(--r-sm); color: var(--text); cursor: pointer;+ }+ .sb-err-fix:hover { border-color: var(--accent); color: var(--accent-bright); }+ .sb-seedwrap { display: inline-flex; align-items: center; gap: 4px; }+ .sb-seedwrap[hidden] { display: none !important; }+ .sb-seed {+ width: 78px; padding: 3px 6px; font-size: 11px;+ background: var(--panel-2); border: 1px solid var(--border);+ border-radius: var(--r-sm); color: var(--text);+ font-family: var(--ph-font-mono, ui-monospace, Menlo, monospace);+ }+ .sb-shot-out { margin-top: 9px; }+ .sb-shot-out[hidden] { display: none !important; }+ .sb-shot-out .info {+ display: flex; align-items: baseline; gap: 8px;+ padding: 6px 8px; font-size: 11px;+ }+ .sb-shot-out .info .name {+ color: var(--text); overflow: hidden;+ text-overflow: ellipsis; white-space: nowrap;+ }+ .sb-shot-out .info .sub { color: var(--muted); margin-left: auto; flex: 0 0 auto; }+ .sb-shot-out.is-stale { opacity: 0.5; }+ .sb-stale-tag {+ font-size: 9px; text-transform: uppercase; letter-spacing: 0.07em;+ color: var(--warning); font-weight: 700;+ }+ .sb-grade { display: flex; gap: 4px; padding: 0 8px 7px; }+ .sb-grade-btn {+ flex: 1 1 0; width: auto; padding: 5px 4px;+ font-size: 11px; font-weight: 600; letter-spacing: 0.07em;+ text-transform: uppercase;+ background: transparent; border: 1px solid var(--border);+ border-radius: var(--r-sm); color: var(--muted); cursor: pointer;+ transition: var(--t-fast);+ }+ .sb-grade-btn:hover { color: var(--text); border-color: var(--border-strong); }+ .sb-grade-btn[data-g="keep"].active {+ color: var(--success); border-color: rgba(63,185,80,0.5);+ background: rgba(63,185,80,0.16);+ }+ .sb-grade-btn[data-g="reroll"].active {+ color: var(--warning); border-color: rgba(210,153,34,0.5);+ background: rgba(210,153,34,0.16);+ }+ .sb-grade-btn[data-g="cut"].active {+ color: var(--danger); border-color: rgba(248,81,73,0.5);+ background: rgba(248,81,73,0.16);+ }+ .sb-note {+ width: calc(100% - 16px); margin: 0 8px 8px; resize: vertical;+ background: var(--bg-2); border: 1px solid var(--border);+ border-radius: var(--r-sm); color: var(--text);+ font-family: inherit; font-size: 11.5px; padding: 6px 8px;+ }+ .sb-note[hidden] { display: none !important; }+ .sb-addrow { padding: 2px 0 10px; }++ .sb-actionbar {+ position: sticky; bottom: 0; z-index: 4;+ display: flex; align-items: center; gap: 9px;+ padding: 11px 0 12px;+ border-top: 1px solid var(--border);+ background: linear-gradient(180deg, rgba(0,6,26,0) 0%,+ rgba(0,6,26,0.85) 22%, var(--bg) 50%, var(--bg) 100%);+ backdrop-filter: blur(8px); -webkit-backdrop-filter: blur(8px);+ }+ .sb-actionbar[hidden] { display: none !important; }+ .sb-actionbar-spacer { flex: 1 1 auto; }+ .sb-actionbar-note {+ font-size: 11px; color: var(--muted);+ font-family: var(--ph-font-mono, ui-monospace, Menlo, monospace);+ }+ .sb-actionbar .primary, .sb-actionbar .ghost-btn { width: auto; flex: 0 0 auto; }+ .sb-actionbar .primary { padding: 8px 16px; font-size: 13px; }+ #sbTallyText b { color: var(--success); }+ .sb-export-note {+ font-size: 11px; line-height: 1.5; color: var(--muted);+ padding: 0 0 10px;+ }+ .sb-export-note[hidden] { display: none !important; }++ /* ---- run bar ---------------------------------------------------- */+ .sb-runbar {+ display: flex; align-items: center; gap: 10px; flex-wrap: wrap;+ margin: 0 0 11px; padding: 9px 0 9px 10px;+ }+ .sb-runbar[hidden] { display: none !important; }+ .sb-runbar-slot {+ width: 96px; aspect-ratio: 16/9; flex: 0 0 auto;+ border-radius: var(--r-sm); background: var(--bg-2);+ border: 1px solid var(--border); overflow: hidden;+ display: flex; align-items: center; justify-content: center;+ color: var(--text);+ }+ .sb-runbar-slot img { width: 100%; height: 100%; object-fit: cover; }+ .sb-runbar-text { display: flex; flex-direction: column; gap: 2px; min-width: 0; }+ .sb-runbar-text b { font-size: 13px; color: var(--text); font-weight: 600; }+ .sb-runbar-text span {+ font-size: 11px; color: var(--muted);+ overflow: hidden; text-overflow: ellipsis; white-space: nowrap;+ }+ .sb-runbar-dots {+ display: flex; gap: 4px; flex-wrap: wrap; flex: 1 1 auto;+ align-items: center; min-width: 60px;+ }+ .sb-dot {+ width: 8px; height: 8px; border-radius: 50%; padding: 0;+ border: 1px solid var(--border-strong); background: transparent;+ cursor: pointer; flex: 0 0 auto;+ }+ .sb-dot.is-done { background: var(--success); border-color: var(--success); }+ .sb-dot.is-running {+ background: var(--accent); border-color: var(--accent);+ animation: sbPulse 1.2s ease-in-out infinite;+ }+ .sb-dot.is-failed { background: var(--danger); border-color: var(--danger); }+ .sb-dot.is-cut { opacity: 0.35; }+ .sb-runbar .qchip { flex: 0 0 auto; }+ .sb-runbar .sb-danger { color: var(--danger); border-color: rgba(248,81,73,0.4); }++ /* ---- board list -------------------------------------------------- */+ .sb-boardlist li { grid-template-columns: 1fr auto auto auto; cursor: pointer; }+ .sb-boardlist li .badge { color: var(--muted); background: rgba(255,255,255,0.05); }+ .sb-boardlist li.is-live .badge {+ color: var(--accent-bright); background: var(--accent-dim);+ border-color: var(--accent);+ }+ .sb-badge {+ color: var(--accent-bright);+ background: var(--accent-dim);+ border: 1px solid var(--accent) !important;+ }+ /* A queue / Recent row that carries film tags grows ONE column rather than+ reflowing — .row-list li is a 4-column grid and a fifth child would+ otherwise wrap onto a second line. The film badge and the engine chip+ share that one cell (.sb-rowtags), so adding the engine cost no layout.+ Scoped with :has() so every row without a badge is byte-identical. */+ .row-list li:has(.sb-rowtags) {+ grid-template-columns: auto 1fr auto auto auto;+ }+ .sb-rowtags { display: inline-flex; align-items: center; gap: 5px; }+ .sb-rowtags .sb-chip-engine { font-size: 8.5px; padding: 1px 6px; }+ .sb-rowtags .sb-chip-engine .ph { width: 9px; height: 9px; }+ .car-card .sb-badge {+ font-size: 8.5px; letter-spacing: 0.07em; text-transform: uppercase;+ font-weight: 700; padding: 1px 6px; border-radius: var(--r-pill);+ cursor: pointer;+ }+ /* The High delivery pill can't exist on a Q4 machine — put the rule+ right beside the one that hides #qualityGroup's, so the two can never+ disagree about what this Mac can render. */+ body[data-cap-tier="q4"] #sbFinalQuality [data-q="high"] { display: none !important; }++ /* The panel has no layout breakpoint today. Storyboard adds one, scoped+ to itself so nothing else can regress. */+ @media (max-width: 900px) {+ /* One column, and — the part that matters — the panes stop being+ independent scroll boxes. main.layout's `minmax(0,1fr)` row would+ otherwise squeeze the brief into a ~360px scroller with its own sticky+ footer floating mid-form. Stacked, the PAGE scrolls. */+ body[data-workflow="storyboard"] main.layout {+ grid-template-columns: minmax(0, 1fr);+ grid-template-rows: auto auto auto;+ height: auto;+ min-height: 0;+ overflow: visible;+ }+ body[data-workflow="storyboard"] main.layout > aside.form-pane {+ grid-column: 1; grid-row: 1;+ max-height: none; overflow: visible;+ }+ body[data-workflow="storyboard"] main.layout > .stage-pane {+ grid-column: 1; grid-row: 2;+ max-height: none; overflow: visible;+ }+ body[data-workflow="storyboard"] main.layout > #bottomPane { grid-column: 1; grid-row: 3; }+ body[data-workflow="storyboard"] #sbStage { max-height: none; overflow: visible; }+ body[data-workflow="storyboard"] #sbSectionTab .form-action-footer { position: static; }+ .sb-shot-head { flex-wrap: wrap; }+ .sb-summary { flex-direction: column; align-items: stretch; gap: 8px; }+ .sb-runbar { flex-wrap: wrap; }+ }+/* =========================================================CAPABILITY TIER (Q4 vs Q8) — Codex C+ recommendation, 2026-05-17=========================================================@@ -26280,6 +29222,7 @@ HTML = r"""<!doctype html><symbol id="ph-caret-down-bold" viewBox="0 0 256 256"><polyline points="208 96 128 176 48 96" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="24"/></symbol><symbol id="ph-check-bold" viewBox="0 0 256 256"><polyline points="40 144 96 200 224 72" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="24"/></symbol><symbol id="ph-download-simple" viewBox="0 0 256 256"><line x1="128" y1="144" x2="128" y2="32" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><polyline points="216 144 216 208 40 208 40 144" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><polyline points="168 104 128 144 88 104" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/></symbol>+<symbol id="ph-film-slate" viewBox="0 0 256 256"><path d="M216,112H40a8,8,0,0,0-8,8v88a8,8,0,0,0,8,8H216a8,8,0,0,0,8-8V120A8,8,0,0,0,216,112Z" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><path d="M32,112,50.6,44.7a8,8,0,0,1,9.8-5.6L213.3,80.4a8,8,0,0,1,5.6,9.8L213,112" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="110.1" y1="59.5" x2="83.2" y2="112" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="163.9" y1="74" x2="137" y2="112" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/></symbol><symbol id="ph-film-strip" viewBox="0 0 256 256"><rect x="32" y="48" width="192" height="160" rx="8" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="128" y1="48" x2="128" y2="208" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="32" y1="80" x2="224" y2="80" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="32" y1="176" x2="224" y2="176" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="80" y1="48" x2="80" y2="80" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="176" y1="48" x2="176" y2="80" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="80" y1="176" x2="80" y2="208" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><line x1="176" y1="176" x2="176" y2="208" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/></symbol><symbol id="ph-gear-six" viewBox="0 0 256 256"><circle cx="128" cy="128" r="40" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><path d="M130.05,206.11c-1.34,0-2.69,0-4,0L94,224a104.61,104.61,0,0,1-34.11-19.2l-.12-36c-.71-1.12-1.38-2.25-2-3.41L25.9,147.24a99.15,99.15,0,0,1,0-38.46l31.84-18.1c.65-1.15,1.32-2.29,2-3.41l.16-36A104.58,104.58,0,0,1,94,32l32,17.89c1.34,0,2.69,0,4,0L162,32a104.61,104.61,0,0,1,34.11,19.2l.12,36c.71,1.12,1.38,2.25,2,3.41l31.85,18.14a99.15,99.15,0,0,1,0,38.46l-31.84,18.1c-.65,1.15-1.32,2.29-2,3.41l-.16,36A104.58,104.58,0,0,1,162,224Z" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/></symbol><symbol id="ph-image" viewBox="0 0 256 256"><rect x="32" y="48" width="192" height="160" rx="8" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><circle cx="156" cy="100" r="12"/><path d="M147.31,164,173,138.34a8,8,0,0,1,11.31,0L224,178.06" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/><path d="M32,168.69l54.34-54.35a8,8,0,0,1,11.32,0L191.31,208" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/></symbol>@@ -26430,6 +29373,12 @@ HTML = r"""<!doctype html><nav class="workflow-tabs" id="workflowTabs"><button data-workflow="manual" class="active"><svg class="ph wf-icon" aria-hidden="true"><use href="#ph-film-strip"/></svg>Video</button><button data-workflow="studio"><svg class="ph wf-icon" aria-hidden="true"><use href="#ph-image"/></svg>Images</button>+ <!-- Storyboard sits next to the video surfaces; Audio and Train are the+ two "go elsewhere and come back" tabs. No NEW badge on purpose —+ with no film in progress the panel must look exactly as it did+ yesterday, plus one calm word. The count span is filled only while+ a storyboard render is actually in flight. -->+ <button data-workflow="storyboard"><svg class="ph wf-icon" aria-hidden="true"><use href="#ph-film-slate"/></svg>Storyboard<span class="new-badge sb-live" id="sbTabCount" hidden></span></button><button data-workflow="audio"><svg class="ph wf-icon" aria-hidden="true"><use href="#ph-music-notes"/></svg>Audio<span class="new-badge">NEW</span></button><button data-workflow="train"><svg class="ph wf-icon" aria-hidden="true"><use href="#ph-user-plus"/></svg>Train Character</button></nav>@@ -28639,6 +31588,96 @@ HTML = r"""<!doctype html></div>+ <!-- ============== STORYBOARD — the brief (own workflow tab) ========+ One concept in, a film's worth of shots out. Every element here+ mirrors one that already exists: the concept box is the Video tab's+ composer, the shot chips are #h3LengthGroup's, the cast picker is+ the Manual tab's character strip reading the same _manualCharacters+ array, and the footer is the sticky Generate footer. Nothing new is+ invented that could have been borrowed. -->+ <div id="sbSectionTab" style="display:none">++ <!-- Saved boards. Hidden while the list is empty — with no film in+ progress this tab is a concept box and a button, nothing else. -->+ <div class="sb-boards" id="sbBoards" hidden>+ <div class="sb-boards-head">Your storyboards</div>+ <ul class="row-list sb-boardlist" id="sbBoardListMini"></ul>+ </div>++ <div class="composer-card sb-brief" id="sbBrief">+ <textarea class="composer-prompt sb-concept" id="sbConcept" rows="4"+ oninput="sbConceptInput()"+ placeholder="A retired boxer walks his old neighbourhood at dawn and remembers a fight he lost."></textarea>+ </div>++ <div class="cz-control" id="sbLengthRow">+ <div class="cz-label">Shots <span class="cz-label-hint">how many, roughly</span></div>+ <div class="quality-strip pill-group cols-4" id="sbLengthGroup">+ <button type="button" class="q-chip pill-btn" data-sb-shots="6">+ <span class="ql-name">6</span><span class="q-spec ql-spec sub">a scene</span></button>+ <button type="button" class="q-chip pill-btn active" data-sb-shots="12">+ <span class="ql-name">12</span><span class="q-spec ql-spec sub">a short</span></button>+ <button type="button" class="q-chip pill-btn" data-sb-shots="24">+ <span class="ql-name">24</span><span class="q-spec ql-spec sub">a film</span></button>+ <button type="button" class="q-chip pill-btn" data-sb-shots="36">+ <span class="ql-name">36</span><span class="q-spec ql-spec sub">long</span></button>+ </div>+ </div>++ <!-- The film-level engine. It is a PLANNING input, not a label: the two+ engines want prompts written differently, so this is asked before the+ plan exists and changing it means re-planning (the Re-plan modal+ carries the same control). Per-shot override stays cut for v1. -->+ <div class="cz-control" id="sbEngineRow">+ <div class="cz-label">Engine <span class="cz-label-hint">who renders the shots</span></div>+ <div class="pill-group cols-3" id="sbEngineGroup"></div>+ <div class="sb-enginepick-note" id="sbEnginePickNote"></div>+ </div>++ <div class="cz-control" id="sbStyleRow">+ <div class="cz-label">Look <span class="cz-label-hint">goes on every shot</span></div>+ <input type="text" id="sbStyle" class="sb-input"+ placeholder="16mm, cold morning light, handheld, muted greens">+ </div>++ <div class="cz-control" id="sbCastRow">+ <div class="cz-label">Who's in it <span class="cz-label-hint">optional</span></div>+ <div class="chars-strip"><div class="chars-avatar-row" id="sbCharsList"></div></div>+ <div class="chars-strip-empty" id="sbCharsEmpty" hidden>+ No trained characters yet —+ <a href="#" onclick="workflowSwitch('train'); return false;">train one in the Train tab</a>, or+ <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>++ <details class="customize-section" id="sbMustSection">+ <summary class="cz-summary">+ <span class="cz-chevron"><svg class="ph" aria-hidden="true"><use href="#ph-caret-down"/></svg></span>+ <span class="cz-title">Shots it must include</span>+ <span class="cz-meta" id="sbMustMeta">none</span>+ </summary>+ <div class="cz-body">+ <div class="cz-control">+ <div class="cz-label">One per line</div>+ <textarea id="sbMust" class="sb-textarea" rows="4" oninput="sbMustInput()"+ placeholder="close-up on his hands wrapping the empty gym at the end"></textarea>+ </div>+ </div>+ </details>++ <div class="form-action-footer">+ <div class="sb-ramline" id="sbRamLine">+ <span>Planning borrows the memory for about a minute, then gives it back.</span>+ <button type="button" class="help-dot" id="sbRamHelpBtn" aria-expanded="false"+ aria-controls="sbRamHelpNote" title="Why?" onclick="sbToggleRamHelp()">?</button>+ </div>+ <div class="h3-winhelp" id="sbRamHelpNote" hidden></div>+ <button type="button" class="primary" id="sbPlanBtn" onclick="sbPlan()">Plan film</button>+ </div>+ </div>+<!-- ============== AUDIO → VIDEO (own workflow tab) ==============Routes to the helper's `generate_a2v` action which loadsA2VidPipelineTwoStage (Q8 dev + distilled LoRA stage 2). The@@ -28731,14 +31770,36 @@ HTML = r"""<!doctype html><span class="mf-label">Seed</span><input type="number" id="audioStudioSeed" value="-1" placeholder="-1 = random"></div>+ <!-- Start offset into the source file. The pipelines and the render+ helper have always taken this; the panel had no control for it,+ so every A2V render used the first N seconds of the file and the+ only workaround was trimming the audio beforehand (#46). -->+ <div class="mf-cell">+ <span class="mf-label">Audio start</span>+ <input type="number" id="audioStudioStart" value="0" min="0" step="0.5"+ title="Seconds into the audio file where the clip starts reading. 0 = from the beginning.">+ </div>+ </div>+ <div class="hint" style="margin-top:4px">+ Audio start is an offset into the file you loaded — set it to 30 to drive the clip from 0:30 onward.</div><div class="mf-cell" style="margin-top:8px"><span class="mf-label">Duration</span><div class="range-strip"><input type="range" id="audioStudioDuration" min="1" max="30" step="1" value="7"- oninput="document.getElementById('audioStudioDurationVal').textContent=this.value + ' s'">+ oninput="audioStudioDurationChanged(this.value)"><span id="audioStudioDurationVal" class="range-val">7 s</span></div>+ <!-- Length warning. Deliberately a warning and NOT a hard cap: the+ evidence for where A2V gives out is two independent field+ reports converging on ~257 frames (#46 — @blackest hit it here+ and on a separate MLX pipeline), not a measurement made here,+ and the diagnostic that would tell us whether it is a length+ ceiling at all is still outstanding. Silently deleting 11-30 s+ from the slider would be asserting a number nobody has measured.+ Showing the frame count and the reported wall lets the user+ decide with the same information the maintainer has. -->+ <div class="hint" id="audioStudioDurationWarn" style="margin-top:4px; display:none"></div></div><div class="mf-cell" style="margin-top:8px"><span class="mf-label">Audio conditioning strength</span>@@ -28891,6 +31952,19 @@ HTML = r"""<!doctype html></svg><span class="po-act-label">Extend</span></button>+ <!-- Pull a good accident from the Video tab into a film. Hidden until+ at least one board exists on disk — nothing about Storyboard shows+ up in the rest of the panel until there is a film to show it for. -->+ <button id="sbAddBtn" class="po-act" type="button" onclick="sbAddActiveToBoard()"+ style="display:none" title="Add this clip to a storyboard as a shot">+ <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">+ <path d="M2 4 H14 M2 8 H14 M2 12 H9" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>+ </svg>+ <span class="po-act-label">To film</span>+ </button>+ <select id="sbAddSelect" class="po-finish-select" style="display:none"+ title="Which film should this clip join?"+ onchange="sbAddActiveToBoard(this.value)"></select><button id="animateBtn" class="po-act" type="button"onclick="animateActive()" style="display:none" title="Animate this still as an i2v render"><svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">@@ -28939,6 +32013,155 @@ HTML = r"""<!doctype html><div class="name" id="playerName"></div><div class="actions-bar"></div></div>+ <!-- ============== STORYBOARD — the stage surface ===================+ Takes the GALLERY's slot, not the player's. That is deliberate: the+ player stays exactly where it is, so a shot's thumbnail can call the+ existing selectOutput() and the whole Params / Extend / Expand /+ lightbox apparatus keeps working with no storyboard-specific code.+ Four states live here — board list, empty, planning, plan review —+ and exactly one is visible at a time. -->+ <div id="sbStage">++ <!-- Empty: no board open, none on disk. -->+ <div class="sb-empty" id="sbEmpty" hidden>+ <div class="sb-empty-icon">+ <svg width="56" height="56" viewBox="0 0 256 256" aria-hidden="true"><use href="#ph-film-slate"/></svg>+ </div>+ <div class="sb-empty-title">One idea in, a film's worth of shots out.</div>+ <div class="sb-empty-sub">Describe the film on the left and Phosphene writes the shot list — every shot with its own prompt, length and cast. You read it, fix it, then render the lot as cheap drafts overnight.</div>+ <ul class="sb-empty-steps">+ <li><b>Plan</b> — a small language model writes the shot list. About a minute.</li>+ <li><b>Read it</b> — change any prompt, drop a shot, add one. Nothing has rendered yet.</li>+ <li><b>Draft</b> — every shot small and fast, so you can watch the whole thing before committing.</li>+ <li><b>Finish</b> — only the shots you keep, at full size, on the same seeds.</li>+ </ul>+ </div>++ <!-- Board list: boards exist, none open. -->+ <div class="sb-plan" id="sbList" hidden>+ <header class="carousel-head">+ <h3>Storyboards</h3>+ <span class="ch-spacer"></span>+ </header>+ <ul class="row-list sb-boardlist" id="sbBoardList"></ul>+ </div>++ <!-- Planning: 30-90 s, and it says what it costs. -->+ <div class="sb-planning" id="sbPlanning" hidden>+ <div class="sb-planning-mark" aria-hidden="true"><i></i><i></i><i></i></div>+ <div class="sb-planning-title" id="sbPlanningTitle" aria-live="polite">Writing the plan…</div>+ <div class="sb-planning-sub" id="sbPlanningSub">About a minute. Nothing renders yet.</div>+ <div class="sb-planning-steps" id="sbPlanningSteps">+ <div class="sb-step" data-step="load"><span class="sb-step-dot"></span>Loading the planner</div>+ <div class="sb-step" data-step="write"><span class="sb-step-dot"></span>Writing the plan</div>+ <div class="sb-step" data-step="check"><span class="sb-step-dot"></span>Checking it</div>+ <div class="sb-step" data-step="repair" hidden><span class="sb-step-dot"></span>Fixing what didn't validate</div>+ <div class="sb-step" data-step="unload"><span class="sb-step-dot"></span>Giving the memory back</div>+ </div>+ <button type="button" class="ghost-btn" id="sbPlanCancel" onclick="sbCancelPlan()">Cancel</button>+ </div>++ <!-- Planner failed. Does NOT discard the brief — it is still on the left. -->+ <div class="sb-empty" id="sbPlanFail" hidden>+ <div class="sb-empty-title">The planner couldn't write a usable plan.</div>+ <div class="sb-empty-sub" id="sbPlanFailMsg"></div>+ <div style="display:flex;gap:8px;margin-top:6px">+ <button type="button" class="primary" style="width:auto;padding:8px 16px" onclick="sbTryAgain()">Try again</button>+ <button type="button" class="ghost-btn" id="sbPlanFailRaw" onclick="sbShowRaw()" hidden>Show what it returned</button>+ </div>+ </div>++ <!-- Plan review — the core screen. Becomes the grading screen once+ clips exist; it is the same list, not a second one. -->+ <div class="sb-plan" id="sbPlan" hidden>+ <header class="carousel-head sb-plan-head">+ <input class="sb-title" id="sbTitle" value="" spellcheck="false"+ onblur="sbTitleSave()" aria-label="Film title">+ <span class="sb-plan-status" id="sbPlanStatus">Draft plan · not rendered</span>+ <div class="stage-mode-toggle" id="sbStageToggle" role="group" aria-label="Stage view" hidden>+ <button type="button" class="smt-btn active" data-sb-stage="list" onclick="sbSetStage('list')">Shot list</button>+ <button type="button" class="smt-btn" data-sb-stage="player" onclick="sbSetStage('player')">Player</button>+ </div>+ <button type="button" class="ghost-btn" onclick="sbBackToList()">All storyboards</button>+ </header>++ <div class="sb-runbar engine-hint" id="sbRunBar" hidden>+ <div class="sb-runbar-slot" id="sbRunThumb"></div>+ <div class="sb-runbar-text">+ <b id="sbRunTitle">Shot 1</b>+ <span id="sbRunSub"></span>+ </div>+ <div class="sb-runbar-dots" id="sbRunDots"></div>+ <button type="button" class="qchip" id="sbPauseBtn" onclick="togglePause()"+ title="The shot that's rendering finishes. The rest wait.">Pause</button>+ <button type="button" class="qchip" id="sbStopShotBtn" onclick="sbStopShot()"+ title="Stops the shot that's rendering. The rest of the film carries on.">Stop shot</button>+ <button type="button" class="qchip sb-danger" id="sbStopBtn" onclick="sbStopFilm()">Stop film</button>+ </div>++ <div class="sb-summary" id="sbSummary">+ <div class="sb-sum-cell"><b id="sbSumShots">—</b><span id="sbSumRuntime"></span></div>+ <div class="sb-sum-cell"><b id="sbSumTime">—</b><span id="sbSumTimeSub">drafts, this Mac</span></div>+ <div class="sb-sum-cell"><b id="sbSumLoads">—</b><span id="sbSumLoadsSub"></span></div>+ <div class="sb-sum-cell" id="sbSumDiskCell"><b id="sbSumDisk">—</b><span id="sbSumDiskSub">clips land in mlx_outputs/</span></div>+ <div class="sb-runstrip" id="sbRunStrip" hidden></div>+ <div class="sb-enginenote" id="sbEngineNote">+ <span id="sbEngineNoteText"></span>+ <button type="button" class="help-dot" id="sbEngineHelpBtn" aria-expanded="false"+ aria-controls="sbEngineHelpNote" title="Why?" onclick="sbToggleEngineHelp()">?</button>+ </div>+ <div class="h3-winhelp" id="sbEngineHelpNote" style="flex:1 1 100%" hidden></div>+ </div>++ <details class="customize-section" id="sbQualitySection">+ <summary class="cz-summary">+ <span class="cz-chevron"><svg class="ph" aria-hidden="true"><use href="#ph-caret-down"/></svg></span>+ <span class="cz-title">Quality</span>+ <span class="cz-meta" id="sbQualityMeta"></span>+ </summary>+ <div class="cz-body">+ <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" 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>+ </div>+ <div class="cz-control">+ <div class="cz-label">Delivery pass <span class="cz-label-hint">what you keep</span></div>+ <div class="pill-group cols-3" id="sbFinalQuality">+ <button type="button" class="pill-btn" data-q="balanced">Balanced<span class="sub">1024×576</span></button>+ <button type="button" class="pill-btn active" data-q="standard">Standard<span class="sub">1024×576</span></button>+ <button type="button" class="pill-btn" data-q="high" id="sbFinalHigh">High<span class="sub">1024×576 · Q8</span></button>+ </div>+ </div>+ </div>+ </details>++ <div class="sb-errors" id="sbErrors" hidden></div>+ <ol class="sb-shots" id="sbShots"></ol>+ <div class="sb-addrow"><button type="button" class="ghost-btn" onclick="sbAddShot()">+ Add a shot</button></div>++ <div class="sb-actionbar" id="sbActionBar">+ <button type="button" class="ghost-btn" onclick="sbOpenReplan()">Re-plan…</button>+ <span class="sb-actionbar-spacer"></span>+ <span class="sb-actionbar-note" id="sbActionNote"></span>+ <button type="button" class="primary" id="sbRenderBtn" onclick="sbRenderDrafts()">Render all drafts</button>+ </div>++ <div class="sb-actionbar sb-tally" id="sbTally" hidden title="Focus a shot and press K, R or C">+ <span id="sbTallyText">nothing graded yet</span>+ <span class="sb-actionbar-spacer"></span>+ <button type="button" class="ghost-btn" id="sbExportBtn" onclick="sbExport()" hidden>Export</button>+ <button type="button" class="ghost-btn" id="sbRewriteBtn" onclick="sbRewrite()" hidden>Rewrite</button>+ <button type="button" class="ghost-btn" id="sbResumeBtn" onclick="sbRenderRemaining()" hidden>Render remaining</button>+ <button type="button" class="primary" id="sbFinishBtn" onclick="sbFinish()">Finish keepers</button>+ </div>+ <div class="sb-export-note" id="sbExportNote" hidden>Assembling these into a single cut is a script for now — <code>scripts/</code> has the After Effects pass. One-click assembly is not in this version.</div>+ </div>+ </div>+<!-- Combined filter + title row. One row, three regions: title +count, kind chips (All/Videos/Photos), visible/hidden segmentedtoggle on the right. Replaces the previous two-row stack. -->@@ -29240,10 +32463,14 @@ HTML = r"""<!doctype html>Maintainer / self-hosting keys</summary><div class="hint" style="margin:8px 0">- Without a project key this panel opens no network connection at- all — analytics is inert and only the local log is written. Point- <code>PHOSPHENE_ANALYTICS_HOST</code> at your own receiver to- self-host.+ This build ships Phosphene's own project key, which is why the+ counts above are sent by default. It is a write-only+ <code>phc_</code> key — it can send events, it can't read any+ back. Pasting your own key here <b>overrides</b> it; clearing+ this field falls back to the shipped key rather than switching+ sending off, so use the <b>Turn off</b> button above for that.+ Point <code>PHOSPHENE_ANALYTICS_HOST</code> at your own receiver+ to self-host. Full schema: <code>docs/ANALYTICS.md</code>.</div><div class="token-row"><div class="token-label">@@ -29261,7 +32488,8 @@ HTML = r"""<!doctype html>onclick="clearAnalyticsKey('analytics_key')" style="display:none">clear</button></div><div class="hint">- Write-only project key. Pasting one turns the pings on.+ Write-only project key. Pasting one redirects the pings to your+ own PostHog project.</div></div><div class="token-row">@@ -29528,6 +32756,45 @@ Third prompt."></textarea></div></div>+<!-- Re-plan. The one storyboard surface that needs a modal, because it needs a+ text field. Written HERE, at column 0, as a direct child of <body> and+ present at boot on purpose: the global _phosModalScaffold IIFE registers+ its observers once at boot, so a modal injected later loses Esc-to-close,+ the focus trap and the body.modal-open scroll lock. -->+<div class="modal-bg" id="sbReplanModal" onclick="if(event.target===this)sbCloseReplan()">+ <div class="modal">+ <h3>Re-plan this film</h3>+ <div class="hint">The concept and the look stay. Say what was wrong and the planner writes a new shot list. This replaces every shot — clips already rendered stay in your gallery.</div>+ <textarea class="batch" id="sbReplanNotes" rows="4"+ placeholder="Too much walking. Start inside the gym. Fewer wide shots."></textarea>+ <!-- Same control as the brief. This is where changing the engine on an+ EXISTING film belongs, because the change is a re-plan: an H3 shot and+ an LTX shot are written in different dialects, so a flip has to rewrite+ the prompts, not relabel them. -->+ <div class="cz-control" style="margin-top:12px">+ <div class="cz-label">Engine <span class="cz-label-hint">who renders the shots</span></div>+ <div class="pill-group cols-3" id="sbReplanEngineGroup"></div>+ <div class="sb-enginepick-note" id="sbReplanEngineNote"></div>+ </div>+ <div class="hint" style="margin-top:6px">Loads the planner again (~1 min). Nothing renders while it does.</div>+ <div class="modal-actions">+ <button class="small" onclick="sbCloseReplan()">Cancel</button>+ <button class="small primary" style="padding:6px 14px" onclick="sbReplan()">Re-plan</button>+ </div>+ </div>+</div>++<!-- The raw planner reply, for a bug report. Never shown by default. -->+<div class="modal-bg" id="sbRawModal" onclick="if(event.target===this)document.getElementById('sbRawModal').classList.remove('show')">+ <div class="modal">+ <h3>What the planner returned</h3>+ <pre id="sbRawText" style="max-height:50vh;overflow:auto;font-size:11px;white-space:pre-wrap"></pre>+ <div class="modal-actions">+ <button class="small" onclick="document.getElementById('sbRawModal').classList.remove('show')">Close</button>+ </div>+ </div>+</div>+<script>const BOOT = __BOOTSTRAP__;const ASPECTS = BOOT.aspects;@@ -32209,6 +35476,46 @@ function audioStudioRenderSlots() {}}+// Duration slider readout + length warning.+//+// The frame arithmetic here is the same one the submit path uses (24 fps,+// 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.+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 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) {+ 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.';+ } else {+ warn.style.display = 'none';+ warn.textContent = '';+ }+}+async function audioStudioEnhancePrompt() {const ta = document.getElementById('audioStudioPrompt');const original = ta.value.trim();@@ -32246,10 +35553,13 @@ async function audioStudioGenerate() {const h = Math.max(32, Math.round(parseInt(document.getElementById('audioStudioHeight').value || '576', 10) / 32) * 32);// Duration from slider → frames at 8k+1 cadence the model expects.const dur = parseInt(document.getElementById('audioStudioDuration').value || '7', 10);- const targetFrames = Math.max(1, Math.round(dur * 24));- const frames = ((targetFrames - 1 + 7) >> 3 << 3) + 1; // round up to 8k+1+ const frames = _a2vFramesForSeconds(dur);const seed = parseInt(document.getElementById('audioStudioSeed').value || '-1', 10);const audioConditioningScale = parseFloat(document.getElementById('audioConditioningScale').value || '1.0');+ // Offset into the source file. Clamped at 0 here as well as server-side —+ // a negative start would be silently swallowed by load_audio.+ const audioStartEl = document.getElementById('audioStudioStart');+ const audioStart = Math.max(0, parseFloat((audioStartEl && audioStartEl.value) || '0') || 0);AUDIO_STUDIO.busy = true;if (btn) btn.disabled = true;@@ -32270,6 +35580,7 @@ async function audioStudioGenerate() {fd.set('frames', String(frames));fd.set('seed', String(seed));fd.set('audio_conditioning_scale', String(audioConditioningScale));+ fd.set('audio_start_time', String(audioStart));fd.set('quality', 'high'); // A2V is always pipeline-class (Q8 dev or Q4 distilled)// No accel, no enhance — A2V uses A2VidPipelineTwoStage's own walks.fd.set('accel', 'off');@@ -34602,7 +37913,11 @@ function engineServesMode(e, mode) {// offering a choice that changes nothing.function _currentSurface() {const wf = (document.body.dataset.workflow || 'manual').toLowerCase();- return ({ manual: 'video', studio: 'image', audio: 'audio', train: 'train' })[wf] || 'video';+ // 'storyboard' MUST be in this map. Without it the `|| 'video'` fallback+ // leaves the engine switcher visible in a tab that has no engine choice to+ // offer — the film decides per shot, not a global toggle.+ return ({ manual: 'video', studio: 'image', audio: 'audio', train: 'train',+ storyboard: 'storyboard' })[wf] || 'video';}function engineOnSurface(e) {return (e.surfaces || ['video']).indexOf(_currentSurface()) !== -1;@@ -36891,6 +40206,43 @@ async function repairModel(key) {} catch (e) { alert('Repair failed: ' + e); }}+// Translate a cryptic engine error into actionable user guidance. Extracted+// from the Now card 2026-08-11 so a storyboard shot's failure reads EXACTLY+// like a manual one — one if/else, two callers, no way for the two to drift.+// "helper died mid-job (no event)" is the SIGKILL-by-jetsam signature on+// memory-pressured Macs: the helper subprocess gets killed by the OS for using+// too much RAM and we never get an event back. Tell the user how to recover+// instead of leaving them with the engine wording.+function friendlyJobError(raw) {+ raw = raw || 'unknown error';+ const rawLower = String(raw).toLowerCase();+ if (rawLower.includes('sigkill')) {+ return { friendly: 'Helper killed by the OS — out of memory (jetsam).',+ hint: 'Close memory-heavy apps (Chrome, Slack, iOS Simulator) and try again, ' ++ 'or switch Quality to Quick (about half the RAM).' };+ }+ if (rawLower.includes('sigsegv') || rawLower.includes('sigbus')) {+ return { friendly: 'Helper crashed at the native level (MLX/Metal fault).',+ hint: 'Share the crashlog at ~/Library/Logs/DiagnosticReports/python3.11_*.crash ' ++ 'on github.com/mrbizarro/phosphene/issues so we can fix it.' };+ }+ if (rawLower.includes('sigabrt')) {+ return { friendly: 'Helper hit a C-level assertion and aborted.',+ hint: 'Share the crashlog at ~/Library/Logs/DiagnosticReports/python3.11_*.crash ' ++ 'on github.com/mrbizarro/phosphene/issues.' };+ }+ if (rawLower.includes('helper exited from') || rawLower.includes('helper pipe closed') ||+ rawLower.includes('helper died') || rawLower.includes('helper exited')) {+ return { friendly: 'Helper exited unexpectedly.',+ hint: 'Check the log for the last "step:*" breadcrumb (tells us which ' ++ 'phase died). If memory-pressured, close other apps and retry.' };+ }+ if (rawLower.includes('q8') || rawLower.includes('keyframe')) {+ return { friendly: 'This mode needs the Q8 model.', hint: raw };+ }+ return { friendly: 'Job failed.', hint: raw };+}+async function poll() {// Reflect HDR-vs-character mutual exclusion every poll cycle. character_id// gets set from multiple code paths (manual chip click, load-params,@@ -37206,33 +40558,7 @@ async function poll() {// killed by the OS for using too much RAM and we never get an// event back. Tell the user how to recover instead of leaving them// with the engine wording.- const raw = (last.error || 'unknown error');- const rawLower = raw.toLowerCase();- let friendly, hint;- if (rawLower.includes('sigkill')) {- friendly = 'Helper killed by the OS — out of memory (jetsam).';- hint = 'Close memory-heavy apps (Chrome, Slack, iOS Simulator) and try again, ' +- 'or switch Quality to Quick (about half the RAM).';- } else if (rawLower.includes('sigsegv') || rawLower.includes('sigbus')) {- friendly = 'Helper crashed at the native level (MLX/Metal fault).';- hint = 'Share the crashlog at ~/Library/Logs/DiagnosticReports/python3.11_*.crash ' +- 'on github.com/mrbizarro/phosphene/issues so we can fix it.';- } else if (rawLower.includes('sigabrt')) {- friendly = 'Helper hit a C-level assertion and aborted.';- hint = 'Share the crashlog at ~/Library/Logs/DiagnosticReports/python3.11_*.crash ' +- 'on github.com/mrbizarro/phosphene/issues.';- } else if (rawLower.includes('helper exited from') || rawLower.includes('helper pipe closed') ||- rawLower.includes('helper died') || rawLower.includes('helper exited')) {- friendly = 'Helper exited unexpectedly.';- hint = 'Check the log for the last "step:*" breadcrumb (tells us which ' +- 'phase died). If memory-pressured, close other apps and retry.';- } else if (rawLower.includes('q8') || rawLower.includes('keyframe')) {- friendly = 'This mode needs the Q8 model.';- hint = raw;- } else {- friendly = 'Job failed.';- hint = raw;- }+ const { friendly, hint } = friendlyJobError(last.error || 'unknown error');nowCard.querySelector('.ttl').innerHTML =`<span style="color: var(--danger, #f85149)"><svg class="ph" aria-hidden="true" style="margin-right:4px;vertical-align:-2px"><use href="#ph-warning-fill"/></svg>${escapeHtml(friendly)}</span>`;nowCard.querySelector('.meta').innerHTML =@@ -37311,10 +40637,22 @@ async function poll() {const params = (j.params.mode === 'image')? `image · ${j.params.aspect || '?'} · n=${j.params.n || '?'}`: `${j.params.mode} · ${j.params.width}×${j.params.height} · ${j.params.frames}f`;+ // Which film this job is a shot of. A pure function of immutable params,+ // so the qSig memoisation above needs no change.+ const sb = /^sb:([^#]+)#(\d+)$/.exec(j.params.session_tag || '');+ const sbTotal = sb ? ((SB.boards.find(b => b.id === sb[1]) || {}).shots || '?') : '';+ // A queued shot wears the film badge AND its engine: a film's jobs are+ // not all on one engine, and the queue is where you find out what is+ // about to run. Same chip, same registry row, as the card and the header.+ const sbBadge = sb+ ? `<span class="sb-rowtags"><span class="badge sb-badge" title="${escapeHtml(j.params.label || '')}">S${sb[2].padStart(2,'0')}/${sbTotal}</span>`+ + sbEngineChip(j.params.engine || 'ltx') + `</span>`+ : '';return `<li><span class="pos">#${i+1}</span><span class="ttl" title="${escapeHtml(j.params.prompt)}">${escapeHtml(j.params.label || snippet(j.params.prompt, 60))}</span>+ ${sbBadge}<span class="params">${params}</span><button title="Remove" onclick="removeJob('${j.id}')"><svg class="ph" aria-hidden="true"><use href="#ph-x-bold"/></svg></button></li>`;@@ -37401,10 +40739,19 @@ async function poll() {title="Re-submit this job with the same params"onclick='retryJob(${JSON.stringify(j.id)})'>Retry</button>`: '';+ // Same film badge the queue rows carry, so a shot is identifiable+ // wherever the bottom pane shows it.+ const hsb = /^sb:([^#]+)#(\d+)$/.exec((j.params || {}).session_tag || '');+ const hsbTotal = hsb ? ((SB.boards.find(b => b.id === hsb[1]) || {}).shots || '?') : '';+ const hsbBadge = hsb+ ? `<span class="sb-rowtags"><span class="badge sb-badge" title="${escapeHtml(j.params.label || '')}">S${hsb[2].padStart(2,'0')}/${hsbTotal}</span>`+ + sbEngineChip((j.params || {}).engine || 'ltx') + `</span>`+ : '';return `<li class="${j.status}"><span class="badge">${j.status}</span><span class="ttl" title="${titleAttr}">${titleHtml}</span>+ ${hsbBadge}<span class="params">${fmtMin(j.elapsed_sec)} · ${j.finished_at ? j.finished_at.slice(11) : ''}</span><span>${actionHtml}</span></li>`;@@ -37505,6 +40852,11 @@ async function poll() {}}}++ // Storyboard — ONE call, no new timer. It sets the tab count during an+ // overnight run, gates Plan film on the worker being idle, and decides+ // whether `To film` exists at all. All three are inert with no boards.+ if (typeof sbPollHook === 'function') { try { sbPollHook(s); } catch (e) {} }}// Balanced chip subtitle — kept in sync with current mode + frames so the@@ -37903,7 +41255,8 @@ function renderCarousel() {<div class="info"><div class="name" title="${escapeHtml(o.name)}">${escapeHtml(o.name)}</div><div class="sub" title="Render time · file size">- ${_outputDurationLabel(o)} · ${o.size_mb.toFixed(1)} MB+ ${o.sb ? `<span class="badge sb-badge" title="Shot ${o.sb.n} of a storyboard — click to open it"+ onclick="event.stopPropagation(); sbOpenFromClip('${escapeHtml(o.sb.id)}')">S${String(o.sb.n).padStart(2,'0')}</span> · ` : ''}${_outputDurationLabel(o)} · ${o.size_mb.toFixed(1)} MB</div></div></div>`;@@ -38605,6 +41958,13 @@ async function loadParams() {// Say it out loud. This whole function ran silently before — the form// changed somewhere off-screen and the click read as a dead button._flashActionDone('loadParamsBtn', 'Loaded');+ // On the Storyboard surface the Video form isn't on screen at all, so the+ // flash happens somewhere the user can't see and the click reads as dead.+ // Take them to the form that just changed.+ if (document.body.dataset.workflow === 'storyboard') {+ phosToast('Loaded into the Video form.', { kind: 'success' });+ if (typeof workflowSwitch === 'function') workflowSwitch('manual');+ }}// Momentary "it worked" state on an action button. The panel has no toast@@ -42255,7 +45615,7 @@ async function refreshModelsModal({ silent = false } = {}) {const repos = data.repos || [];const active = data.active_download;hint.innerHTML = data.hf_available- ? `Each row shows what's on disk. Click <b>Download</b> to fetch missing files via <code>hf download</code>; progress streams to the log at the bottom of the page.`+ ? `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.`;const rows = repos.map(r => {let cls, icon, statusText, btnHtml;@@ -42766,6 +46126,1551 @@ document.querySelectorAll('#modeGroup .pill-btn').forEach(b => b.addEventListene// surfaces: the manual generate form, the Characters tab (LoRA pair +// prompt + ship), and Train (character LoRA training).+// ============================================================================+// STORYBOARD+// ============================================================================+// One concept in, a film's worth of shots out. Everything here talks to+// /storyboard/*; nothing here renders, queues, or tracks progress on its own —+// a shot is an ordinary job and the bottom pane already knows how to show one.+//+// The board poller lives here and ONLY runs while the tab is open (2 s, its own+// timer). poll() at 1.5 s is already doing a lot and this must not ride on it.+// The single cross-tab cost is one call at the end of poll(): sbPollHook().++let SB = {+ id: '', // the open board, '' = list/empty+ payload: null, // the last /storyboard/get reply+ timer: null, // the 2 s board poller+ saveTimer: null,+ saveInFlight: false,+ saveAgain: false,+ stageMode: 'auto', // 'auto' | 'list' | 'player'+ primed: false, // brief defaults are read from BOOT once, not per entry+ boards: [], // /status.storyboards, refreshed by poll()+ lastUndo: null,+};+const SB_BOOT = (typeof BOOT !== 'undefined' && BOOT.storyboard) ? BOOT.storyboard : {};++// The validator's structured errors, in human. Keyed on `code`, never on the+// message text — that is the whole reason validate_storyboard_detail() exists.+// `fix` names an action sbFixError() knows how to run.+const SB_ERR_COPY = {+ schema_version: { html: '<b>This storyboard was written by a different version of Phosphene.</b> Nothing here can be rendered safely. Plan a new one.' },+ board_id_empty: { html: '<b>This storyboard file is damaged</b> and can\'t be repaired from the panel.' },+ no_shots: { html: '<b>No shots.</b> Re-plan, or add one by hand.', fix: 'add', label: 'Add a shot' },+ shot_not_object: { html: (e) => `<b>Shot ${e.n} is unreadable.</b> Delete it and add a new one.`, fix: 'delete', label: 'Delete shot' },+ shot_number: { html: (e) => `<b>Shot ${e.n} lost its number.</b>`, fix: 'renumber', label: 'Renumber all shots' },+ shot_duplicate: { html: (e) => `<b>Two shots are both numbered ${e.n}.</b>`, fix: 'renumber', label: 'Renumber all shots' },+ bad_mode: { html: (e) => `<b>Shot ${e.n} asks for a shot type this build doesn't have.</b> Set it to Text or Character.`, fix: 'text', label: 'Make it Text' },+ empty_prompt: { html: (e) => `<b>Shot ${e.n} has no prompt.</b> Write what happens in it.`, fix: 'focus', label: 'Write it' },+ unknown_character: { html: (e) => `<b>Shot ${e.n} casts <code>${escapeHtml(e.data.character_id || '')}</code>, who isn't on this Mac.</b> Pick someone installed, or train them first.`, fix: 'pickchar', label: 'Pick someone' },+ missing_trigger: { html: (e) => `<b>Shot ${e.n}'s prompt doesn't say <code>${escapeHtml(e.data.trigger || '')}</code>,</b> so the trained face won't load and a stranger renders instead.`, fix: 'trigger', label: 'Put it back' },+ character_without_id:{ html: (e) => `<b>Shot ${e.n} is a Character shot with nobody cast.</b>`, fix: 'pickchar', label: 'Pick someone' },+ bad_duration: { html: (e) => `<b>Shot ${e.n} is ${escapeHtml(String(e.data.duration_s))} seconds long.</b> Pick something between 1 and 60.`, fix: 'dur5', label: 'Make it 5 s' },+ refs_not_list: { html: (e) => `<b>Shot ${e.n}'s reference images are damaged.</b>`, fix: 'clearrefs', label: 'Clear them' },+ ref_missing: { html: (e) => `<b>Shot ${e.n} wants a reference image that isn't there any more:</b> <code>${escapeHtml(e.data.name || '')}</code>`, fix: 'clearrefs', label: 'Clear them' },+ remix_needs_ref: { html: (e) => `<b>Shot ${e.n} is a Remix shot with no reference image.</b>`, fix: 'text', label: 'Make it Text' },+ over_cap: { html: (e) => `<b>${e.data.pass_name === 'final' ? 'Delivery' : 'Draft'} is set to ${e.data.width}×${e.data.height}; this Mac caps at ${e.data.max_dim}.</b> It'll shrink to fit unless you lower it.`, fix: 'cap', label: 'Use 1024×576' },+};++function sbEl(id) { return document.getElementById(id); }++// Wall clock, at the scale a film is measured in. Wraps fmtMin so it never+// shows seconds when the answer is hours.+function sbFmtWall(secs) {+ if (!secs || secs < 0) return '—';+ if (secs < 90) return `${Math.round(secs)} s`;+ const m = Math.round(secs / 60);+ if (m < 90) return `about ${m} m`;+ const h = Math.floor(m / 60), rem = m % 60;+ return rem ? `about ${h} h ${rem} m` : `about ${h} h`;+}+function sbFmtRuntime(secs) {+ if (!secs) return '';+ if (secs <= 90) return `${Math.round(secs)} s of film`;+ const m = Math.floor(secs / 60), s = Math.round(secs % 60);+ return `${m} m ${s} s of film`;+}+function sbShotEst(secs) {+ if (!secs) return '';+ return secs < 90 ? `~${Math.round(secs)} s` : `~${Math.round(secs / 60)} m`;+}++// ---- tab lifecycle ---------------------------------------------------------+function sbInit() {+ const help = sbEl('sbRamHelpNote');+ if (help && !help.textContent) help.textContent = SB_BOOT.ram_help || '';+ // Draft restore — a restart must not eat what someone typed.+ try {+ const draft = localStorage.getItem('phos_sb_draft');+ const box = sbEl('sbConcept');+ if (draft && box && !box.value) box.value = draft;+ } catch (e) {}+ // Defaults are read from the bootstrap ONCE. sbInit() runs on every tab entry,+ // and SB_BOOT was captured at page load — re-applying it on re-entry silently+ // reset Shots and Engine to stale values while disk held the real ones, and+ // the UI is what sbPlan() submits. After the first entry the in-session choice+ // IS the truth.+ if (!SB.primed) {+ const d = SB_BOOT.defaults || {};+ _sbShots = Number(d.shots) || 12;+ _sbEngineMode = d.engine || 'auto';+ SB.primed = true;+ }+ sbSetShots(_sbShots, false);+ sbRenderEnginePicker();+ if (typeof refreshManualCharacters === 'function') {+ Promise.resolve(refreshManualCharacters()).then(sbRenderCast).catch(() => sbRenderCast());+ } else { sbRenderCast(); }+ sbConceptInput();+ sbMustInput();+ // Restore the last board the user was on, same idiom as phos_workflow.+ let last = '';+ try { last = localStorage.getItem('phos_sb_open') || ''; } catch (e) {}+ sbRefreshBoards().then(() => {+ if (last && SB.boards.some(b => b.id === last)) sbOpen(last);+ else if (SB.boards.length) sbShow('list');+ else sbShow('empty');+ });+ if (SB.timer) clearInterval(SB.timer);+ SB.timer = setInterval(sbTick, 2000);+}++function sbTeardown() {+ if (SB.timer) { clearInterval(SB.timer); SB.timer = null; }+}++async function sbRefreshBoards() {+ try {+ const r = await (await fetch('/storyboard/list')).json();+ SB.boards = r.boards || [];+ } catch (e) { SB.boards = []; }+ sbRenderBoardLists();+ return SB.boards;+}++// ---- the editing guard -----------------------------------------------------+// The shot list is innerHTML-rebuilt on every repaint, and the board poller+// repaints every 2 s. Without these two guards, typing into a prompt loses+// focus and then loses the text: the tick lands INSIDE the 800 ms save debounce,+// replaces the textarea with the server's copy, and the debounce then writes the+// reverted value back to disk. Measured 5/5 by the validator, and "change any+// prompt" is one of the four promises printed on the empty state.+//+// Two different questions, deliberately:+// sbTypingInShots() — is the user mid-word? Blocks the DOM rebuild only. A+// click on ↑ / a select / a grade button must still repaint, and by then the+// focused element is a button or a closed select, not a text field.+// sbHoldingShots() — is the card busy at all (text OR an open select menu)?+// Blocks the POLL, so nothing is fetched-and-repainted under an open menu+// and no server copy can clobber an edit that hasn't been saved yet.+function sbTypingInShots() {+ const a = document.activeElement;+ if (!a || !a.closest || !a.closest('#sbShots')) return false;+ const t = (a.tagName || '').toUpperCase();+ return t === 'TEXTAREA' || (t === 'INPUT' && a.type !== 'button');+}+function sbHoldingShots() {+ const a = document.activeElement;+ if (a && a.closest && a.closest('#sbShots')) {+ const t = (a.tagName || '').toUpperCase();+ if (t === 'TEXTAREA' || t === 'SELECT' || t === 'INPUT') return true;+ }+ // An edit typed but not yet flushed is exactly as unsafe to overwrite.+ return !!SB.saveTimer || SB.saveInFlight;+}++async function sbTick() {+ if (document.body.dataset.workflow !== 'storyboard') return;+ // The global poll skips hidden tabs; this one should too.+ if (document.hidden) return;+ if (sbHoldingShots()) {+ // Don't fetch over someone's typing. The run bar is the one thing that+ // moves on its own, and it lives outside #sbShots, so keep it live.+ if (SB.id && SB.payload) { try { sbRenderRunBar(SB.payload); } catch (e) {} }+ return;+ }+ if (SB.id) await sbLoad(SB.id, true);+ else await sbRefreshBoards();+}++// ---- the brief -------------------------------------------------------------+let _sbDraftTimer = null;+function sbConceptInput() {+ const box = sbEl('sbConcept');+ const btn = sbEl('sbPlanBtn');+ if (btn) {+ const empty = !box || !box.value.trim();+ btn.disabled = empty || btn.dataset.busy === '1';+ if (empty) btn.title = 'Write a couple of sentences about the film first.';+ else if (btn.dataset.busy !== '1') btn.title = '';+ }+ if (_sbDraftTimer) clearTimeout(_sbDraftTimer);+ _sbDraftTimer = setTimeout(() => {+ try { localStorage.setItem('phos_sb_draft', (box && box.value) || ''); } catch (e) {}+ }, 400);+}++function sbMustInput() {+ const box = sbEl('sbMust');+ const meta = sbEl('sbMustMeta');+ if (!meta) return;+ const n = ((box && box.value) || '').split('\n').filter(x => x.trim()).length;+ meta.textContent = n === 0 ? 'none' : (n === 1 ? '1 shot' : `${n} shots`);+}++let _sbShots = 12;+function sbSetShots(n, persist) {+ _sbShots = Number(n) || 12;+ document.querySelectorAll('#sbLengthGroup .q-chip').forEach(b =>+ b.classList.toggle('active', Number(b.dataset.sbShots) === _sbShots));+ if (persist !== false) sbSaveSetting('storyboard_shots', _sbShots);+}+function sbShotsValue() {+ const on = document.querySelector('#sbLengthGroup .q-chip.active');+ return on ? Number(on.dataset.sbShots) : _sbShots;+}+async function sbSaveSetting(key, value) {+ try {+ const fd = new URLSearchParams(); fd.set(key, String(value));+ await fetch('/settings', { method: 'POST', body: fd });+ } catch (e) {}+}++function sbToggleRamHelp() {+ const btn = sbEl('sbRamHelpBtn'), note = sbEl('sbRamHelpNote');+ if (!btn || !note) return;+ const open = btn.getAttribute('aria-expanded') === 'true';+ btn.setAttribute('aria-expanded', open ? 'false' : 'true');+ note.hidden = open;+}+function sbToggleEngineHelp() {+ const btn = sbEl('sbEngineHelpBtn'), note = sbEl('sbEngineHelpNote');+ if (!btn || !note) return;+ const open = btn.getAttribute('aria-expanded') === 'true';+ btn.setAttribute('aria-expanded', open ? 'false' : 'true');+ note.hidden = open;+ if (!note.textContent) note.textContent = SB_BOOT.engine_help || '';+}++// A small .eng-seg: same glyph, same label, same accent variables, read off the+// SAME ENGINES registry row the header switcher renders from — so a shot card+// and the header can never disagree about what an engine looks like.+function sbEngineChip(id) {+ const e = (typeof ENGINES !== 'undefined' ? ENGINES : []).find(x => x.id === id)+ || { id: id, label: (id || 'ltx').toUpperCase(), mark: 'eng-mark-ltx',+ 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.';+ 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>`;+}++// Mirrors _renderManualCharactersList() against the same _manualCharacters+// array. Single select in v1; click the lit avatar to deselect.+let _sbCastId = '';+function sbRenderCast() {+ const wrap = sbEl('sbCharsList'), empty = sbEl('sbCharsEmpty');+ if (!wrap) return;+ const list = (typeof _manualCharacters !== 'undefined' && _manualCharacters) || [];+ if (!list.length) {+ wrap.innerHTML = '';+ if (empty) empty.hidden = false;+ return;+ }+ if (empty) empty.hidden = true;+ wrap.innerHTML = list.map(c => {+ const active = c.id === _sbCastId;+ const name = c.name || c.trigger || c.id;+ const avatar = c.sample_image_url+ ? `<img class="chars-avatar-img" src="${escapeHtml(c.sample_image_url)}" alt="">`+ : `<span class="chars-avatar-ph">${escapeHtml((name || '?').charAt(0).toUpperCase())}</span>`;+ return `<button type="button" class="chars-avatar-chip ${active ? 'active' : ''}"+ onclick="sbPickCast(${JSON.stringify(c.id).replace(/"/g, '"')})"+ title="${escapeHtml(name)}${active ? ' · click to deselect' : ''}">+ ${avatar}<span class="chars-avatar-name">${escapeHtml(name)}</span></button>`;+ }).join('');+}+function sbPickCast(id) {+ _sbCastId = (_sbCastId === id) ? '' : id;+ // Casting under an H3-only film is a promise the engine can't keep, so the+ // 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.',+ {duration: 6000});+ }+ sbRenderCast();+ sbRenderEnginePicker();+}++// ---- the film-level engine -------------------------------------------------+// The owner's question, verbatim: "I don't get why I cannot select in the+// storyboard if I'm going to send to LTX or to Hailuo." So he can. Three+// options, once per film, asked BEFORE the plan exists — because the planner+// writes H3's three-field dialect or LTX prose depending on the answer, and a+// prompt written for one engine is not a prompt for the other. Changing it on+// an existing film is therefore a re-plan, and the Re-plan modal carries the+// same control.+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' },+];++function sbH3Installed() {+ const p = (window._ENGINE_PROBES || {}).h3 || {};+ return { capable: !!p.capable, available: !!p.available };+}++function sbEnginePickerHtml(active) {+ const h3 = sbH3Installed();+ return SB_ENGINE_OPTS.map(o => {+ const e = o.engine ? (ENGINES || []).find(x => x.id === o.engine) : null;+ const blocked = (o.key === 'h3') && !h3.available;+ const offer = blocked && h3.capable;+ const cls = 'pill-btn' + (o.key === active ? ' 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.'+ : 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.';+ 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)}">+ ${glyph}${escapeHtml(o.label)}<span class="sub">${escapeHtml(o.sub)}</span></button>`;+ }).join('');+}++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.';+ }+ 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>.';+}++function sbRenderEnginePicker() {+ const g = sbEl('sbEngineGroup');+ if (g) g.innerHTML = sbEnginePickerHtml(_sbEngineMode);+ const n = sbEl('sbEnginePickNote');+ if (n) n.innerHTML = sbEnginePickerNote(_sbEngineMode);+}++function sbSetEngineMode(key, persist) {+ const h3 = sbH3Installed();+ if (key === 'h3' && !h3.available) {+ // Not installed is not dead — the click IS the install, same as the High+ // quality chip's needs-install state.+ // The registry names the install affordance (ENGINES[h3].install_card), so+ // this opens the SAME card the header switcher opens.+ const card = ((ENGINES || []).find(x => x.id === 'h3') || {}).install_card;+ if (h3.capable && card && typeof window[card] === 'function') { try { window[card](); } catch (e) {} }+ else if (h3.capable) phosToast('Install Hailuo H3 from the Phosphene sidebar in Pinokio.', {duration: 6000});+ return;+ }+ if (key === 'h3' && _sbCastId) {+ _sbCastId = '';+ sbRenderCast();+ phosToast('Cast cleared — Hailuo H3 can’t load a trained character.', {duration: 6000});+ }+ _sbEngineMode = key;+ sbRenderEnginePicker();+ if (persist !== false) sbSaveSetting('storyboard_engine', key);+}++// The Re-plan modal's copy of the control. Separate value so opening the modal+// and cancelling can't change the brief.+let _sbReplanEngineMode = 'auto';+function sbRenderReplanEnginePicker() {+ const g = sbEl('sbReplanEngineGroup');+ if (g) g.innerHTML = sbEnginePickerHtml(_sbReplanEngineMode);+ const n = sbEl('sbReplanEngineNote');+ if (n) n.innerHTML = sbEnginePickerNote(_sbReplanEngineMode);+}++// ---- plan ------------------------------------------------------------------+async function sbPlan() {+ const concept = (sbEl('sbConcept') || {}).value || '';+ if (!concept.trim()) { phosToast('Write a couple of sentences about the film first.'); return; }+ const btn = sbEl('sbPlanBtn');+ if (btn) { btn.dataset.busy = '1'; btn.disabled = true; btn.textContent = 'Planning…'; }+ const fd = new URLSearchParams();+ fd.set('concept', concept);+ fd.set('shots', String(sbShotsValue()));+ fd.set('style', (sbEl('sbStyle') || {}).value || '');+ fd.set('must', (sbEl('sbMust') || {}).value || '');+ fd.set('engine', _sbEngineMode);+ if (_sbCastId) fd.set('character_id', _sbCastId);+ let r;+ try {+ r = await (await fetch('/storyboard/plan', { method: 'POST', body: fd })).json();+ } catch (e) { r = { ok: false, error: String(e) }; }+ if (!r.ok) {+ sbPlanBtnReset();+ phosToast(r.error || 'Planning could not start.', { kind: 'danger', duration: 6000 });+ return;+ }+ SB.id = r.id;+ try { localStorage.setItem('phos_sb_open', SB.id); } catch (e) {}+ sbShow('planning');+ sbSetPlanningStage('load');+ sbLoad(SB.id);+}+function sbPlanBtnReset() {+ const btn = sbEl('sbPlanBtn');+ if (!btn) return;+ delete btn.dataset.busy;+ btn.textContent = 'Plan film';+ sbConceptInput();+}++async function sbCancelPlan() {+ const fd = new URLSearchParams(); fd.set('id', SB.id);+ try { await fetch('/storyboard/cancel', { method: 'POST', body: fd }); } catch (e) {}+ phosToast('Planning cancelled.');+ sbPlanBtnReset();+ sbLoad(SB.id);+}++function sbSetPlanningStage(stage) {+ const map = {+ load: ['Loading the planner', 'About a minute. Nothing renders yet.'],+ write: ['Writing the plan', 'About a minute. Nothing renders yet.'],+ check: ['Checking the plan', 'About a minute. Nothing renders yet.'],+ repair: ['Fixing the plan', 'It came back slightly malformed. One retry.'],+ unload: ['Giving the memory back', 'The renderer gets it now.'],+ };+ const order = ['load', 'write', 'check', 'repair', 'unload'];+ const at = order.indexOf(stage);+ const t = map[stage] || map.load;+ const ttl = sbEl('sbPlanningTitle'), sub = sbEl('sbPlanningSub');+ if (ttl) ttl.textContent = t[0];+ if (sub) sub.textContent = t[1];+ document.querySelectorAll('#sbPlanningSteps .sb-step').forEach(el => {+ const i = order.indexOf(el.dataset.step);+ el.classList.toggle('is-now', i === at);+ el.classList.toggle('is-done', i >= 0 && at >= 0 && i < at);+ // The repair row is revealed only when the retry actually fired —+ // advertising a failure that usually doesn't happen is worse than silence.+ if (el.dataset.step === 'repair') el.hidden = (stage !== 'repair');+ });+}++function sbOpenReplan() {+ _sbReplanEngineMode = ((SB.payload || {}).engine_mode) || 'auto';+ sbRenderReplanEnginePicker();+ sbEl('sbReplanModal').classList.add('show');+}+function sbCloseReplan() { sbEl('sbReplanModal').classList.remove('show'); }+async function sbReplan() {+ const notes = (sbEl('sbReplanNotes') || {}).value || '';+ sbCloseReplan();+ const b = (SB.payload || {}).board || {};+ const fd = new URLSearchParams();+ fd.set('id', SB.id);+ fd.set('concept', b.concept || '');+ fd.set('style', b.style || '');+ fd.set('shots', String(b.shots_target || (b.shots || []).length || 12));+ fd.set('must', (b.must || []).join('\n'));+ fd.set('notes', notes);+ fd.set('engine', _sbReplanEngineMode);+ const cast = (b.cast || [])[0];+ // An H3-only film carries no cast — the server refuses the pair, so don't+ // send one it would have to reject.+ if (cast && cast.id && _sbReplanEngineMode !== 'h3') fd.set('character_id', cast.id);+ let r;+ try { r = await (await fetch('/storyboard/plan', { method: 'POST', body: fd })).json(); }+ catch (e) { r = { ok: false, error: String(e) }; }+ if (!r.ok) { phosToast(r.error || 'Re-plan could not start.', { kind: 'danger', duration: 6000 }); return; }+ sbShow('planning'); sbSetPlanningStage('load'); sbLoad(SB.id);+}++// Try again re-plans THIS board from the brief the board itself stores. It used+// to call sbPlan(), which sends no id and reads the left-hand form — so a failed+// "deep-sea welder" board plus an unrelated concept still sitting in the brief+// produced a second, different film and left the failed one as a dead row.+async function sbTryAgain() {+ const b = ((SB.payload || {}).board) || {};+ if (!SB.id) return sbPlan();+ const emode = b.engine_mode || 'auto';+ const fd = new URLSearchParams();+ fd.set('id', SB.id);+ fd.set('concept', b.concept || '');+ fd.set('shots', String(b.shots_target || (b.shots || []).length || 12));+ fd.set('style', b.style || '');+ fd.set('must', (b.must || []).join('\n'));+ fd.set('engine', emode);+ const cast = (b.cast || [])[0];+ if (cast && cast.id && emode !== 'h3') fd.set('character_id', cast.id);+ let r;+ try { r = await (await fetch('/storyboard/plan', { method: 'POST', body: fd })).json(); }+ catch (e) { r = { ok: false, error: String(e) }; }+ if (!r.ok) { phosToast(r.error || 'Planning could not start.', { kind: 'danger', duration: 6000 }); return; }+ sbShow('planning'); sbSetPlanningStage('load'); sbLoad(SB.id);+}++function sbShowRaw() {+ const raw = ((SB.payload || {}).planner || {}).raw || '';+ sbEl('sbRawText').textContent = raw || '(nothing captured)';+ sbEl('sbRawModal').classList.add('show');+}++// ---- board open / load -----------------------------------------------------+function sbOpen(id) {+ SB.id = id;+ try { localStorage.setItem('phos_sb_open', id); } catch (e) {}+ sbLoad(id);+}+function sbBackToList() {+ SB.id = '';+ SB.payload = null;+ try { localStorage.removeItem('phos_sb_open'); } catch (e) {}+ sbRefreshBoards().then(() => sbShow(SB.boards.length ? 'list' : 'empty'));+}++async function sbLoad(id, quiet) {+ let r;+ try {+ r = await (await fetch('/storyboard/get?id=' + encodeURIComponent(id))).json();+ } catch (e) { return; }+ if (!r || !r.ok) {+ if (!quiet) phosToast('That storyboard is gone.', { kind: 'danger' });+ sbBackToList();+ return;+ }+ if (SB.payload && SB.payload.board && r.board && sbTypingInShots()) {+ // A refresh that lands mid-word keeps what is on screen.+ sbAdoptLiveEdits(r);+ }+ SB.payload = r;+ const st = (r.planner || {}).state;+ if (r.planning || st === 'running') {+ sbShow('planning');+ sbSetPlanningStage((r.planner || {}).stage || 'load');+ return;+ }+ if (st === 'failed') {+ sbPlanBtnReset();+ sbShow('planfail');+ sbRenderPlanFail(r.planner || {});+ return;+ }+ sbPlanBtnReset();+ sbShow('plan');+ sbRenderPlan(r);+ // The player keeps whatever was last selected globally, so opening a film+ // showed an unrelated Video-tab render under the film's own title. Put the+ // film's newest clip up — but only when the current one isn't already one of+ // this film's, so it never yanks a shot the user just clicked.+ const mine = (r.board.shots || [])+ .map(x => x.final_output || x.draft_output).filter(Boolean);+ if (mine.length && mine.indexOf(activePath) === -1) {+ try { selectOutput(mine[mine.length - 1]); } catch (e) {}+ }+}++function sbRenderPlanFail(p) {+ const map = {+ download: 'The planner model didn\'t finish downloading. Check your connection and try again — it resumes where it stopped.',+ oom: 'Not enough free memory to load the planner. Close some apps and try again.',+ invalid: 'It produced something this build can\'t read, twice. Trying again usually works — the model isn\'t deterministic. If it keeps failing, shorten the concept.',+ busy: 'Something else is using the GPU. Wait for the queue to empty and try again.',+ // The planner never got to finish, so "it couldn't write a usable plan"+ // would be untrue. The heal path writes this kind at boot.+ restarted: 'The panel restarted while the planner was running, so the plan never finished. Nothing was lost — press Try again.',+ };+ // An unmapped kind falls back to what the server actually said rather than to+ // a shrug: the sentence was written, it just had nowhere to appear.+ sbEl('sbPlanFailMsg').textContent = map[p.error_kind]+ || (p.error ? ('Something went wrong while planning: ' + p.error + '. Try again.')+ : 'Something went wrong while planning. Try again.');+ const ttl = document.querySelector('#sbPlanFail .sb-empty-title');+ if (ttl) ttl.textContent = (p.error_kind === 'restarted')+ ? 'The plan didn\'t finish.' : 'The planner couldn\'t write a usable plan.';+ sbEl('sbPlanFailRaw').hidden = !p.raw;+}++// Exactly one of the five stage states is visible at a time, and body.sb-full+// is on while there is nothing for the player to show — the same trick the+// Ideogram layout editor uses to take the whole column.+function sbShow(which) {+ const states = { empty: 'sbEmpty', list: 'sbList', planning: 'sbPlanning',+ planfail: 'sbPlanFail', plan: 'sbPlan' };+ Object.keys(states).forEach(k => {+ const el = sbEl(states[k]);+ if (el) el.hidden = (k !== which);+ });+ // The brief's board list is a way BACK to another film while one is open.+ // While the stage is already showing the list, it would be the same list+ // twice in one screen — so it folds away.+ const boards = sbEl('sbBoards');+ if (boards) boards.hidden = !SB.boards.length || which === 'list' || which === 'empty';+ sbSyncStage();+}++function sbHasClip() {+ const shots = (((SB.payload || {}).board) || {}).shots || [];+ return shots.some(s => s.draft_output || s.final_output);+}++function sbSyncStage() {+ const on = document.body.dataset.workflow === 'storyboard';+ const hasClip = on && sbHasClip();+ let full;+ if (!on) full = false;+ else if (SB.stageMode === 'list') full = true;+ else if (SB.stageMode === 'player') full = false;+ else full = !hasClip;+ document.body.classList.toggle('sb-full', !!full);+ const tog = sbEl('sbStageToggle');+ if (tog) {+ tog.hidden = !hasClip;+ tog.querySelectorAll('.smt-btn').forEach(b =>+ b.classList.toggle('active', b.dataset.sbStage === (full ? 'list' : 'player')));+ }+}+function sbSetStage(mode) { SB.stageMode = mode; sbSyncStage(); }++// ---- the plan screen -------------------------------------------------------+function sbRenderPlan(r) {+ const b = r.board || {};+ const est = r.estimate || {};+ const shots = b.shots || [];+ const title = sbEl('sbTitle');+ if (title && document.activeElement !== title) title.value = b.title || '';++ // --- summary ---+ // Per PASS, not per `status`: during delivery, `status === 'done'` still+ // reads true from the draft that already landed.+ const outKey = r.pass === 'final' ? 'final_output' : 'draft_output';+ const done = shots.filter(s => s[outKey]).length;+ const failed = shots.filter(s => s.status === 'failed').length;+ const rendering = !!r.rendering;+ let status;+ if (r.pass === 'final') {+ // "Delivery rendering · 4 of 4" is a sentence about a thread that hasn't+ // released its slot yet, not about the film. Once every shot has its+ // delivery clip the film is finished, whatever the dispatcher is doing.+ status = (rendering && done < shots.length)+ ? `Delivery rendering · ${done} of ${shots.length}`+ : `Finished · ${done} shot${done === 1 ? '' : 's'}`;+ } else if (rendering) {+ status = `Drafts rendering · ${done} of ${shots.length}`;+ } else if (done && done + failed >= shots.length) {+ status = failed ? `Drafts done · ${done} of ${shots.length}, ${failed} failed`+ : `Drafts done · ${done} of ${shots.length}`;+ } else if (done) {+ // Partway through and NOT running — stopped, or a single shot retried.+ // "Drafts rendering" here would be a sentence that isn't true.+ status = `Drafts · ${done} of ${shots.length}`;+ } else {+ status = 'Draft plan · not rendered';+ }+ sbEl('sbPlanStatus').textContent = status;++ // The first two cells describe the work THIS PASS still has to do. With none+ // left they were reading "0 shots" and "—", which says nothing about the film+ // you are looking at — so at zero they switch to describing the film itself.+ const nothingLeft = !est.shots;+ const runtimeAll = shots.reduce((a, s) => a + (Number(s.duration_s) || 0), 0);+ sbEl('sbSumShots').textContent = nothingLeft+ ? (shots.length === 1 ? '1 shot' : `${shots.length} shots`)+ : (est.shots === 1 ? '1 shot' : `${est.shots} shots`);+ sbEl('sbSumRuntime').textContent = sbFmtRuntime(nothingLeft ? runtimeAll : est.runtime_secs);+ sbEl('sbSumTime').textContent = nothingLeft ? 'all rendered' : sbFmtWall(est.total_secs);+ sbEl('sbSumTimeSub').textContent = nothingLeft+ ? 'nothing left to render'+ : (r.pass === 'final' ? 'delivery' : 'drafts') + ', this Mac';+ const loads = est.pipeline_loads || 0;+ sbEl('sbSumLoads').textContent = loads === 1 ? '1 model load' : `${loads} model loads`;+ let loadsSub = loads === 1 ? 'every shot renders back to back' : 'grouped, not in story order';+ if (est.saved_secs > 0) loadsSub += ` — rendering grouped saves ${sbFmtWall(est.saved_secs).replace('about ', '')}`;+ sbEl('sbSumLoadsSub').textContent = loadsSub;+ const freeGb = (r.disk || {}).free_gb;+ sbEl('sbSumDisk').textContent = (freeGb == null) ? '—' : `${freeGb} GB free`;+ const tight = (freeGb != null && freeGb < 20);+ sbEl('sbSumDiskCell').classList.toggle('is-warn', tight);+ sbEl('sbSumDiskSub').textContent = tight+ ? 'clips land in mlx_outputs/ — this is tight' : 'clips land in mlx_outputs/';++ // Run strip — one segment per bucket, sized by shot count. A single band+ // explaining nothing is chrome, so it hides below 4 shots on one bucket.+ const strip = sbEl('sbRunStrip');+ const buckets = est.buckets || [];+ const NAMES = { t2v: 'Text & Character', remix: 'Remix', keyframe: 'Keyframes',+ extend: 'Extend', a2v: 'Audio' };+ if (buckets.length <= 1 && shots.length < 4) {+ strip.hidden = true;+ } else {+ strip.hidden = false;+ strip.innerHTML = buckets.map(bk => {+ const ns = bk.shots || [];+ // "2–6" for [2,4,6] would claim five shots that aren't in this bucket.+ // A range only when the run really is contiguous; otherwise say which.+ const contiguous = ns.length > 1 && ns[ns.length - 1] - ns[0] === ns.length - 1;+ const range = !ns.length ? ''+ : ns.length === 1 ? `${ns[0]}`+ : contiguous ? `${ns[0]}–${ns[ns.length - 1]}`+ : (ns.length > 4 ? `${ns.length} shots` : ns.join(', '));+ const label = (bk.engine === 'h3' ? 'H3 · ' : '') + (NAMES[bk.kind] || bk.kind);+ return `<div class="sb-runseg" style="flex-grow:${ns.length}" data-shots="${ns.join(',')}">+ ${bk.engine === 'h3' ? '' : '<span class="sb-runseg-load" title="One model load, about 90 s">load</span>'}+ <span class="sb-runseg-name">${escapeHtml(label)}</span>+ <span class="sb-runseg-shots">${range}</span></div>`;+ }).join('');+ }++ // --- quality ---+ const pol = b.policy || {};+ const dq = (pol.draft || {}).quality || 'quick';+ const fq = (pol.final || {}).quality || 'standard';+ document.querySelectorAll('#sbDraftQuality .pill-btn').forEach(x =>+ x.classList.toggle('active', x.dataset.q === dq));+ document.querySelectorAll('#sbFinalQuality .pill-btn').forEach(x =>+ x.classList.toggle('active', x.dataset.q === fq));+ sbEl('sbQualityMeta').textContent =+ `Draft ${(pol.draft || {}).width}×${(pol.draft || {}).height} · ` ++ `Delivery ${(pol.final || {}).width}×${(pol.final || {}).height}`;++ // --- board-level errors ---+ const errs = r.errors || [];+ const boardErrs = errs.filter(e => !e.n);+ const errBox = sbEl('sbErrors');+ errBox.hidden = !boardErrs.length;+ errBox.innerHTML = boardErrs.map(sbErrRow).join('');++ // --- shot cards ---+ // Rebuilding the list under a cursor is what makes editing impossible, so a+ // repaint that arrives mid-word repaints everything EXCEPT the cards. The+ // next repaint after blur (<=2 s) brings the server's copy in.+ if (!sbTypingInShots()) {+ sbEl('sbShots').innerHTML = shots.map(s => sbShotCard(s, r, errs)).join('');+ }++ // --- which engine, and why ---+ // There is NO engine selection on this tab, and saying so out loud is the+ // fix for the first thing the owner asked about it. The line states the rule;+ // the ? carries the Python-owned paragraph; the chips on the cards carry the+ // per-shot answer.+ const mix = est.engine_mix || {};+ const mode = r.engine_mode || 'auto';+ let engText;+ if (!r.h3_available) {+ engText = SB_BOOT.engine_note_no_h3 || '';+ } 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.';+ } 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>`;+ 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>`;+ }+ if (r.h3_available && mode !== 'auto') engText += ' Change it in Re-plan.';+ sbEl('sbEngineNoteText').innerHTML = engText;++ // --- run bar / action bar ---+ sbRenderRunBar(r);+ const graded = shots.filter(s => s.grade).length;+ const anyClip = sbHasClip();+ sbEl('sbActionBar').hidden = anyClip;+ sbEl('sbTally').hidden = !anyClip;+ const btn = sbEl('sbRenderBtn');+ btn.disabled = errs.length > 0 || rendering;+ btn.title = errs.length ? `Fix the ${errs.length} problem${errs.length > 1 ? 's' : ''} above first.` : '';+ sbEl('sbActionNote').textContent =+ `${est.shots || 0} shot${est.shots === 1 ? '' : 's'} · ${sbFmtWall(est.total_secs)}`;+ if (anyClip) sbRenderTally(shots, r);+ if (!sbTypingInShots()) sbAutoGrowPrompts();+ sbSyncStage();+}++// 3-10 rows, sized to the text. A planner prompt is 70-140 words and a fixed+// 3-row box hides most of it behind a scrollbar — which matters here, because+// reading the plan before spending render hours is the entire point.+function sbAutoGrowPrompts(one) {+ const els = one ? [one] : document.querySelectorAll('#sbShots .sb-shot-prompt');+ els.forEach(el => {+ const line = 19.4; // 12.5px * 1.55 line-height+ el.style.height = 'auto';+ const want = Math.min(Math.max(el.scrollHeight, line * 3), line * 10 + 16);+ el.style.height = Math.ceil(want) + 'px';+ });+}++function sbErrRow(e) {+ const copy = SB_ERR_COPY[e.code];+ const html = !copy ? escapeHtml(e.message)+ : (typeof copy.html === 'function' ? copy.html(e) : copy.html);+ const fix = copy && copy.fix+ ? `<button type="button" class="sb-err-fix" onclick="sbFixError('${copy.fix}',${e.n || 0},'${escapeHtml(e.code)}')">${escapeHtml(copy.label)}</button>`+ : '';+ return `<div class="sb-err-row"><span class="sb-err-dot"></span><span>${html}</span>${fix}</div>`;+}++function sbShotCard(s, r, errs) {+ const n = s.n;+ const mine = errs.filter(e => e.n === n);+ const est = (r.per_shot_est || {})[String(n)];+ const chars = r.characters || [];+ const locked = (s.status === 'rendering' || s.status === 'queued' || s.status === 'done');+ // The chip says what will ACTUALLY render, not what the plan wrote. With no+ // H3 pack the server forces every shot to LTX at enqueue, so a pink Hailuo+ // chip on a machine that has no Hailuo would be the UI contradicting itself.+ const engine = r.h3_available ? (s.engine || 'ltx') : 'ltx';+ const clip = s.final_output || s.draft_output;+ // A shot whose prompt was just rewritten has no clip of its own yet, but the+ // take it replaced is still on disk. Show it under the "old take" wash so the+ // card isn't suddenly blank — and NOT gradeable, because it is not the shot+ // the plan now describes.+ const stale = !clip ? (s.stale_output || '') : '';+ const shots = (r.board || {}).shots || [];+ const isChar = !!s.character_id;+ const opts = ['<option value="">— nobody —</option>'].concat(chars.map(c =>+ `<option value="${escapeHtml(c.id)}" ${c.id === s.character_id ? 'selected' : ''}>${escapeHtml(c.name || c.id)}</option>`)).join('');+ // 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('');+ const passLabel = r.pass === 'final' ? 'Delivery' : 'Draft';+ const seedSet = (s.seed != null && s.seed !== -1);++ const outBlock = stale ? `+ <div class="sb-shot-out car-card is-stale">+ <div class="car-thumb-wrap" onclick="selectOutput('${escapeHtml(stale)}')">+ <video class="car-thumb" preload="metadata" muted playsinline+ src="/file?path=${encodeURIComponent(stale)}"></video>+ </div>+ <div class="info"><span class="name">${escapeHtml(stale.split('/').pop())}</span>+ <span class="sub"><span class="sb-stale-tag">old take</span> · rewritten, not rendered yet</span></div>+ </div>` : clip ? `+ <div class="sb-shot-out car-card">+ <div class="car-thumb-wrap" onclick="sbOpenShotClip(${n})">+ <video class="car-thumb" preload="metadata" muted playsinline+ src="/file?path=${encodeURIComponent(clip)}"+ onmouseenter="this.currentTime=0;this.playbackRate=0.6;this.play().catch(()=>{})"+ onmouseleave="this.pause();this.currentTime=2.5"></video>+ </div>+ <div class="info"><span class="name">${escapeHtml(clip.split('/').pop())}</span>+ <span class="sub">${s.final_output ? 'delivery' : 'draft'}</span></div>+ <div class="sb-grade" role="group" aria-label="Grade shot ${n}">+ <button type="button" class="sb-grade-btn ${s.grade === 'keep' ? 'active' : ''}" data-act="grade" data-g="keep" aria-pressed="${s.grade === 'keep'}">KEEP</button>+ <button type="button" class="sb-grade-btn ${s.grade === 'reroll' ? 'active' : ''}" data-act="grade" data-g="reroll" aria-pressed="${s.grade === 'reroll'}">RE-ROLL</button>+ <button type="button" class="sb-grade-btn ${s.grade === 'cut' ? 'active' : ''}" data-act="grade" data-g="cut" aria-pressed="${s.grade === 'cut'}">CUT</button>+ </div>+ <textarea class="sb-note" rows="2" data-act="note" ${s.grade === 'reroll' ? '' : 'hidden'}+ placeholder="What should change? (goes back to the planner)">${escapeHtml(s.note || '')}</textarea>+ </div>` : '';++ const failBlock = (s.status === 'failed') ? (() => {+ const fe = friendlyJobError(s.error || '');+ return `<div class="sb-shot-err"><div class="sb-err-row"><span class="sb-err-dot"></span>+ <span><b>Shot ${n} failed.</b> ${escapeHtml(fe.friendly)} — ${escapeHtml(fe.hint)}</span>+ <button type="button" class="sb-err-fix" data-act="retry">Retry this shot</button>+ <button type="button" class="sb-err-fix" data-act="cut">Cut it</button></div></div>`;+ })() : '';++ return `<li class="sb-shot ${mine.length ? 'has-error' : ''} ${locked ? 'is-locked' : ''}"+ data-n="${n}" draggable="${locked ? 'false' : 'true'}" tabindex="0">+ <div class="sb-shot-head">+ <span class="sb-shot-n">${String(n).padStart(2, '0')}</span>+ <div class="sb-seg" role="group" aria-label="Shot type">+ <button type="button" class="sb-seg-btn ${isChar ? '' : 'active'}" data-act="mode" data-mode="text" ${locked ? 'disabled' : ''}>Text</button>+ <button type="button" class="sb-seg-btn ${isChar ? 'active' : ''}" data-act="mode" data-mode="character"+ ${locked || noCast ? 'disabled' : ''} ${noCast ? 'title="No trained characters on this Mac yet — train one in the Train tab."' : ''}>Character</button>+ </div>+ <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)}+ <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>+ <span class="sb-seedwrap" hidden>+ <input type="number" class="sb-seed" data-act="seed" value="${seedSet ? s.seed : ''}"+ aria-label="Seed for shot ${n}" ${locked ? 'disabled' : ''}></span>+ <button type="button" class="sb-icon" data-act="up" title="Move up" aria-label="Move shot ${n} up" ${n === 1 || locked ? 'disabled' : ''}>↑</button>+ <button type="button" class="sb-icon" data-act="down" title="Move down" aria-label="Move shot ${n} down" ${n === shots.length || locked ? 'disabled' : ''}>↓</button>+ <button type="button" class="sb-icon ${seedSet ? 'is-set' : ''}" data-act="seedtoggle"+ title="${seedSet ? `Seed ${s.seed} — same number, same roll of the dice. Fix it so the delivery render matches the draft you approved.` : 'Seed — same number, same roll of the dice. Fix it so the delivery render matches the draft you approved.'}"+ aria-label="Seed for shot ${n}">🎲</button>+ <button type="button" class="sb-icon sb-icon-danger" data-act="del" title="${locked ? "This one's already rendering." : 'Delete this shot'}" aria-label="Delete shot ${n}" ${locked && s.status !== 'done' ? 'disabled' : ''}>✕</button>+ <span class="sb-grip" title="Drag to reorder" aria-hidden="true">⠿</span>+ </div>+ <textarea class="sb-shot-prompt" rows="3" spellcheck="false" data-act="prompt"+ ${locked ? 'readonly' : ''} title="${escapeHtml(s.title || '')}">${escapeHtml(s.prompt || '')}</textarea>+ ${mine.length ? `<div class="sb-shot-err">${mine.map(sbErrRow).join('')}</div>` : ''}+ ${failBlock}+ ${outBlock}+ </li>`;+}++function sbRenderTally(shots, r) {+ const keep = shots.filter(s => s.grade === 'keep').length;+ const rr = shots.filter(s => s.grade === 'reroll').length;+ const cut = shots.filter(s => s.grade === 'cut').length;+ const graded = keep + rr + cut;+ const un = shots.length - graded;+ sbEl('sbTallyText').innerHTML = graded === 0 ? 'nothing graded yet'+ : `<b>${keep} keep</b> · ${rr} re-roll · ${cut} cut${un ? ` · ${un} ungraded` : ''}`;+ // The tally bar REPLACES the action bar the moment a clip exists — which,+ // after a Stop or a single retry, would leave no way to render the shots+ // that never got a draft. So it carries that button when there are any.+ const pending = shots.filter(s => s.status !== 'skipped' && !s.draft_output).length;+ const resume = sbEl('sbResumeBtn');+ resume.hidden = !pending || !!(r && r.rendering);+ resume.textContent = `Render ${pending} remaining`;+ const rw = sbEl('sbRewriteBtn');+ rw.hidden = !rr;+ rw.textContent = rr === 1 ? 'Rewrite 1 shot' : `Rewrite ${rr} shots`;+ const fin = sbEl('sbFinishBtn');+ fin.textContent = keep ? `Finish ${keep} keeper${keep === 1 ? '' : 's'}` : 'Finish keepers';+ fin.disabled = !keep;+ fin.title = keep ? '' : 'Mark at least one shot KEEP first.';+ const canExport = shots.some(s => s.final_output);+ sbEl('sbExportBtn').hidden = !canExport;+ sbEl('sbExportNote').hidden = !canExport;+}++// The shots that never got a draft — after a Stop, or when a shot was added by+// hand to a film that already rendered.+function sbRenderRemaining() {+ const shots = (((SB.payload || {}).board) || {}).shots || [];+ const ns = shots.filter(s => s.status !== 'skipped' && !s.draft_output).map(s => s.n);+ if (!ns.length) return;+ const est = (SB.payload || {}).estimate || {};+ if (!confirm(+ `Render ${ns.length} draft${ns.length === 1 ? '' : 's'}?\n\n` ++ `${sbFmtWall(est.total_secs).replace(/^about /, 'About ')} on this Mac. ` ++ 'The shots you already have are untouched.\n\n' ++ 'You can pause or stop after any shot.')) return;+ sbRenderPass('draft', ns);+}++function sbRenderRunBar(r) {+ const bar = sbEl('sbRunBar');+ const shots = (r.board || {}).shots || [];+ if (!r.rendering) { bar.hidden = true; return; }+ bar.hidden = false;+ const cur = (LAST_STATUS && LAST_STATUS.current) || null;+ const tag = cur ? _sbTagOf(cur) : null;+ const active = (tag && tag.id === SB.id) ? shots.find(s => s.n === tag.n) : null;+ const outKey = (r.pass === 'final') ? 'final_output' : 'draft_output';+ const done = shots.filter(s => s[outKey]).length;+ const paused = LAST_STATUS && LAST_STATUS.paused;+ sbEl('sbRunTitle').textContent = paused+ ? `Paused · ${done} of ${shots.length} done`+ : (active ? `Shot ${active.n} of ${shots.length}` : `${done} of ${shots.length} done`);+ let sub = '';+ if (active) sub = `S${String(active.n).padStart(2, '0')} · ${snippet(active.prompt, 40)}`;+ // The remaining time is a SERVER number. /status.eta_sec is the sum of+ // per-job ETAs and is trustworthy when every queued job is this film's.+ const q = (LAST_STATUS && LAST_STATUS.queue) || [];+ const allMine = q.length && q.every(j => { const t = _sbTagOf(j); return t && t.id === SB.id; });+ if (allMine && LAST_STATUS.eta_sec) sub += ` · ${sbFmtWall(LAST_STATUS.eta_sec)} left`;+ sbEl('sbRunSub').textContent = sub;+ sbEl('sbPauseBtn').textContent = paused ? 'Resume' : 'Pause';+ sbEl('sbRunDots').innerHTML = shots.map(s => {+ const cls = s[outKey] ? 'is-done'+ : s.status === 'failed' ? 'is-failed'+ : s.status === 'rendering' ? 'is-running'+ : s.status === 'skipped' ? 'is-cut' : '';+ return `<button type="button" class="sb-dot ${cls}" onclick="sbScrollToShot(${s.n})"+ title="S${String(s.n).padStart(2, '0')} · ${escapeHtml(snippet(s.prompt, 40))}"+ aria-label="Shot ${s.n}"></button>`;+ }).join('');+ // Designed now, empty today: fill from the server's preview_url the day one+ // exists. No layout shift either way — the box is always the same size.+ const pv = ((cur || {}).progress || {}).preview_url;+ sbEl('sbRunThumb').innerHTML = pv+ ? `<img src="${escapeHtml(pv)}?t=${Date.now()}" alt="">`+ : `<svg width="26" height="26" viewBox="0 0 256 256" style="opacity:.18" aria-hidden="true"><use href="#ph-film-slate"/></svg>`;+}++function _sbTagOf(job) {+ const m = /^sb:([^#]+)#(\d+)$/.exec(((job || {}).params || {}).session_tag || '');+ return m ? { id: m[1], n: Number(m[2]) } : null;+}+function sbScrollToShot(n) {+ const el = document.querySelector(`.sb-shot[data-n="${n}"]`);+ if (el) el.scrollIntoView({ behavior: 'smooth', block: 'center' });+}+function sbOpenShotClip(n) {+ const s = (((SB.payload || {}).board) || {}).shots.find(x => x.n === n);+ const clip = s && (s.final_output || s.draft_output);+ if (!clip) return;+ if (SB.stageMode === 'list') SB.stageMode = 'auto';+ sbSyncStage();+ selectOutput(clip);+}++// ---- editing ---------------------------------------------------------------+function sbShotById(n) {+ return (((SB.payload || {}).board) || {}).shots.find(s => s.n === n);+}++// Every edit patches the board client-side then POSTs it. The server+// re-validates, re-injects triggers, renumbers and returns a fresh estimate —+// there is NO client-side validation at all, which is what stops the panel's+// copy from drifting away from storyboard.py.+function sbQueueSave(immediate) {+ if (SB.saveTimer) clearTimeout(SB.saveTimer);+ SB.saveTimer = setTimeout(() => { SB.saveTimer = null; sbFlushSave(); },+ immediate ? 0 : 600);+}++// While a save is in flight the user can keep typing, and the reply carries the+// board as it was when we SENT it. Replacing SB.payload with that reply would+// silently roll those keystrokes back — the same class of bug as the tick+// clobbering the textarea. So: whatever is in a focused editor right now is the+// truth, and it is re-applied over the reply (and re-saved).+function sbAdoptLiveEdits(payload) {+ let dirty = false;+ document.querySelectorAll('#sbShots .sb-shot').forEach(li => {+ const n = Number(li.dataset.n);+ const shot = (payload.board.shots || []).find(x => x.n === n);+ if (!shot) return;+ const box = li.querySelector('textarea[data-act="prompt"]');+ if (box && document.activeElement === box && box.value !== shot.prompt) {+ shot.prompt = box.value; dirty = true;+ }+ const note = li.querySelector('textarea[data-act="note"]');+ if (note && document.activeElement === note && note.value !== (shot.note || '')) {+ shot.note = note.value; dirty = true;+ }+ });+ return dirty;+}++async function sbFlushSave() {+ if (SB.saveInFlight) { SB.saveAgain = true; return; }+ const board = ((SB.payload || {}).board);+ if (!board) return;+ SB.saveInFlight = true;+ try {+ const r = await (await fetch('/storyboard/save', {+ method: 'POST', headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ id: SB.id, board: board }),+ })).json();+ if (r && r.ok) {+ SB.payload = r;+ if (sbAdoptLiveEdits(r)) SB.saveAgain = true;+ sbRenderPlan(r);+ }+ } catch (e) {+ } finally {+ SB.saveInFlight = false;+ if (SB.saveAgain) { SB.saveAgain = false; sbQueueSave(true); }+ }+}++function sbShotAction(n, act, el, ev) {+ const board = ((SB.payload || {}).board);+ const s = sbShotById(n);+ if (!board || !s) return;+ switch (act) {+ case 'mode': {+ const m = el.dataset.mode;+ if (m === 'character') {+ // Nobody cast — take the first installed character rather than saving+ // an incoherent shot. The server injects the trigger on save.+ if (!s.character_id) {+ const first = ((SB.payload.characters || [])[0] || {}).id;+ if (!first) { phosToast('No trained characters on this Mac yet.'); return; }+ s.character_id = first;+ }+ s.mode = 'character';+ } else {+ // Text clears the cast but LEAVES THE PROMPT ALONE — deleting someone's+ // words is never the right default.+ delete s.character_id; delete s.trigger;+ s.mode = 'text';+ }+ break;+ }+ case 'char': {+ const v = el.value;+ if (v) { s.character_id = v; s.mode = 'character'; }+ else { delete s.character_id; delete s.trigger; s.mode = 'text'; }+ break;+ }+ case 'dur': s.duration_s = Number(el.value); break;+ case 'prompt': s.prompt = el.value; break;+ case 'seed': s.seed = el.value === '' ? -1 : Number(el.value); break;+ case 'seedtoggle': {+ const wrap = el.closest('.sb-shot-head').querySelector('.sb-seedwrap');+ if (wrap) { wrap.hidden = !wrap.hidden; if (!wrap.hidden) wrap.querySelector('.sb-seed').focus(); }+ return;+ }+ case 'pass':+ sbEl('sbQualitySection').open = true;+ sbEl('sbQualitySection').scrollIntoView({ behavior: 'smooth', block: 'center' });+ phosToast('Quality is set for the whole film.');+ return;+ case 'up': case 'down': {+ const i = board.shots.indexOf(s);+ const j = act === 'up' ? i - 1 : i + 1;+ if (j < 0 || j >= board.shots.length) return;+ board.shots.splice(j, 0, board.shots.splice(i, 1)[0]);+ board.shots.forEach((x, k) => { x.n = k + 1; });+ break;+ }+ case 'del': {+ if (s.draft_output || s.final_output) {+ if (!confirm(`Remove shot ${n} from the film?\n\nThe clip stays in mlx_outputs/.`)) return;+ } else {+ SB.lastUndo = { index: board.shots.indexOf(s), shot: JSON.parse(JSON.stringify(s)) };+ const t = phosToast(`Shot ${n} removed.`, { kind: 'success', duration: 6000 });+ if (t) {+ const u = document.createElement('button');+ u.className = 'phos-toast-undo'; u.textContent = 'Undo';+ u.style.pointerEvents = 'auto';+ u.onclick = () => { sbUndoDelete(); t.remove(); };+ t.appendChild(u);+ }+ }+ board.shots = board.shots.filter(x => x !== s);+ board.shots.forEach((x, k) => { x.n = k + 1; });+ break;+ }+ case 'grade': {+ const g = (s.grade === el.dataset.g) ? null : el.dataset.g;+ sbGrade(n, g, s.note || '');+ return;+ }+ case 'note': s.note = el.value; sbGrade(n, s.grade, el.value); return;+ case 'retry': sbRenderPass(SB.payload.pass || 'draft', [n]); return;+ case 'cut': sbGrade(n, 'cut', s.note || ''); return;+ default: return;+ }+ sbRenderPlan(SB.payload);+ sbQueueSave(act !== 'prompt');+}++function sbUndoDelete() {+ const board = ((SB.payload || {}).board);+ if (!board || !SB.lastUndo) return;+ board.shots.splice(SB.lastUndo.index, 0, SB.lastUndo.shot);+ board.shots.forEach((x, k) => { x.n = k + 1; });+ SB.lastUndo = null;+ sbRenderPlan(SB.payload);+ sbQueueSave(true);+}++function sbAddShot() {+ const board = ((SB.payload || {}).board);+ if (!board) return;+ // Follow the film's own rule rather than hardcoding LTX: in an Auto film on a+ // machine with the H3 pack, an uncast shot belongs on H3 like every other+ // uncast shot — otherwise the card contradicts the note printed above it.+ const em = (SB.payload || {}).engine_mode || 'auto';+ const eng = !((SB.payload || {}).h3_available) ? 'ltx' : (em === 'ltx' ? 'ltx' : 'h3');+ board.shots.push({ n: board.shots.length + 1, mode: 'text', engine: eng,+ prompt: '', duration_s: 5, seed: -1, refs: [], status: 'pending' });+ sbRenderPlan(SB.payload);+ sbQueueSave(true);+ const last = document.querySelector('.sb-shot:last-child .sb-shot-prompt');+ if (last) last.focus();+}++function sbTitleSave() {+ const board = ((SB.payload || {}).board);+ if (!board) return;+ board.title = sbEl('sbTitle').value;+ sbQueueSave(true);+}++async function sbGrade(n, grade, note) {+ const fd = new URLSearchParams();+ fd.set('id', SB.id); fd.set('n', String(n));+ if (grade) fd.set('grade', grade);+ fd.set('note', note || '');+ try {+ const r = await (await fetch('/storyboard/grade', { method: 'POST', body: fd })).json();+ if (r && r.ok) { SB.payload = r; sbRenderPlan(r); }+ } catch (e) {}+}++function sbFixError(fix, n, code) {+ const board = ((SB.payload || {}).board);+ if (!board) return;+ const s = n ? sbShotById(n) : null;+ if (fix === 'add') return sbAddShot();+ if (fix === 'renumber') {+ board.shots.forEach((x, k) => { x.n = k + 1; });+ } else if (fix === 'delete' && n) {+ board.shots.splice(n - 1, 1);+ board.shots.forEach((x, k) => { x.n = k + 1; });+ } else if (fix === 'text' && s) {+ s.mode = 'text'; delete s.character_id; delete s.trigger; s.refs = [];+ } else if (fix === 'focus' && n) {+ const el = document.querySelector(`.sb-shot[data-n="${n}"] .sb-shot-prompt`);+ if (el) el.focus();+ return;+ } else if (fix === 'pickchar' && n) {+ const el = document.querySelector(`.sb-shot[data-n="${n}"] .sb-shot-char`);+ if (el) { el.focus(); if (el.showPicker) { try { el.showPicker(); } catch (e) {} } }+ return;+ } else if (fix === 'trigger' && s) {+ // The server owns ensure_trigger(); a save with the character still set is+ // all it takes, and the canonical text comes back in the reply.+ sbQueueSave(true);+ return;+ } else if (fix === 'dur5' && s) {+ s.duration_s = 5;+ } else if (fix === 'clearrefs' && s) {+ s.refs = [];+ } else if (fix === 'cap') {+ ['draft', 'final'].forEach(k => {+ const p = (board.policy || {})[k];+ if (p && Math.max(p.width, p.height) > 1024) { p.width = 1024; p.height = 576; }+ });+ }+ sbRenderPlan(SB.payload);+ sbQueueSave(true);+}++// ---- render ----------------------------------------------------------------+function sbRenderDrafts() {+ const est = (SB.payload || {}).estimate || {};+ const nshots = est.shots || 0;+ const loads = est.pipeline_loads || 1;+ if (!confirm(+ `Render ${nshots} draft${nshots === 1 ? '' : 's'}?\n\n` ++ `${sbFmtWall(est.total_secs).replace(/^about /, 'About ')} on this Mac. ` ++ `${loads === 1 ? 'One model load, then every shot back to back.' : `${loads} model loads, grouped.`}\n` ++ 'Clips land in mlx_outputs/ and show up in your gallery like any other render.\n\n' ++ 'You can pause or stop after any shot.')) return;+ sbRenderPass('draft', null);+}++async function sbRenderPass(passName, only) {+ const fd = new URLSearchParams();+ fd.set('id', SB.id); fd.set('pass', passName);+ if (only && only.length) fd.set('only', only.join(','));+ let r;+ try { r = await (await fetch('/storyboard/render', { method: 'POST', body: fd })).json(); }+ catch (e) { r = { ok: false, error: String(e) }; }+ if (!r.ok) {+ phosToast(r.error || 'Could not start the render.', { kind: 'danger', duration: 6000 });+ return;+ }+ sbLoad(SB.id);+ poll();+}++async function sbFinish() {+ const shots = (((SB.payload || {}).board) || {}).shots || [];+ const keep = shots.filter(s => s.grade === 'keep').map(s => s.n);+ if (!keep.length) return;+ const fd = new URLSearchParams();+ fd.set('id', SB.id); fd.set('pass', 'final'); fd.set('only', keep.join(','));+ let est = {};+ try { est = ((await (await fetch('/storyboard/estimate', { method: 'POST', body: fd })).json()) || {}).estimate || {}; }+ catch (e) {}+ const pol = (((SB.payload || {}).board) || {}).policy || {};+ const f = pol.final || {};+ if (!confirm(+ `Finish ${keep.length} shot${keep.length === 1 ? '' : 's'}?\n\n` ++ `Delivery pass, ${f.width}×${f.height}, ${(f.quality || '').replace(/^./, c => c.toUpperCase())}. ` ++ `${sbFmtWall(est.total_secs).replace(/^about /, 'About ')} on this Mac.\n` ++ "Each shot re-renders at its draft's seed, so you get the take you approved — bigger.\n" ++ 'The drafts stay in your gallery.')) return;+ sbRenderPass('final', keep);+}++async function sbRewrite() {+ const shots = (((SB.payload || {}).board) || {}).shots || [];+ const ns = shots.filter(s => s.grade === 'reroll').map(s => s.n);+ if (!ns.length) return;+ if (!confirm(+ `Rewrite ${ns.length} shot${ns.length === 1 ? '' : 's'}?\n\n` ++ `The planner loads again (~1 min) and rewrites just ${ns.length === 1 ? 'this one' : 'these'}, using your notes.\n` ++ 'The rest of the film is untouched. Nothing renders while it runs.')) return;+ const fd = new URLSearchParams();+ fd.set('id', SB.id); fd.set('ns', ns.join(','));+ let r;+ try { r = await (await fetch('/storyboard/replan-shots', { method: 'POST', body: fd })).json(); }+ catch (e) { r = { ok: false, error: String(e) }; }+ if (!r.ok) { phosToast(r.error || 'Could not start the rewrite.', { kind: 'danger', duration: 6000 }); return; }+ sbShow('planning'); sbSetPlanningStage('load'); sbLoad(SB.id);+}++function sbStopShot() { api('/stop', 'POST').then(poll); }++async function sbStopFilm() {+ const shots = (((SB.payload || {}).board) || {}).shots || [];+ const waiting = shots.filter(s => s.status === 'queued').length;+ if (!confirm('Stop this storyboard?\n\n' ++ `The shot that's rendering will finish. The ${waiting} shot${waiting === 1 ? '' : 's'} still waiting ${waiting === 1 ? 'is' : 'are'} removed from the queue.\n` ++ 'Everything already rendered stays.')) return;+ const fd = new URLSearchParams(); fd.set('id', SB.id);+ try { await fetch('/storyboard/stop', { method: 'POST', body: fd }); } catch (e) {}+ sbLoad(SB.id); poll();+}++async function sbExport() {+ const fd = new URLSearchParams(); fd.set('id', SB.id);+ let r;+ try { r = await (await fetch('/storyboard/export', { method: 'POST', body: fd })).json(); }+ catch (e) { r = { ok: false, error: String(e) }; }+ if (!r.ok) { phosToast(r.error || 'Export failed.', { kind: 'danger' }); return; }+ phosToast(`Exported ${r.files.length} clips + a shot list to ${r.dir}`,+ { kind: 'success', duration: 6000 });+ const btn = sbEl('sbExportBtn');+ const prev = btn.textContent;+ btn.textContent = 'Show in Finder';+ btn.onclick = () => fetch('/storyboard/reveal', { method: 'POST', body: fd });+ setTimeout(() => { btn.textContent = prev; btn.onclick = sbExport; }, 10000);+}++// ---- board lists -----------------------------------------------------------+function sbBoardChip(b) {+ if (b.planning) return 'planning';+ if (b.running) return 'rendering';+ if (b.failed) return `${b.failed} failed`;+ if (!b.done) return 'plan only';+ if (b.done >= b.shots) return 'drafts done';+ // Partway and idle — stopped, or one shot retried. Saying "rendering" here+ // would be the chip claiming something the machine isn't doing.+ return `${b.done} of ${b.shots}`;+}+function sbRenderBoardLists() {+ const rows = SB.boards.map(b => `+ <li data-id="${escapeHtml(b.id)}" class="${b.running || b.planning ? 'is-live' : ''}"+ onclick="sbOpen('${escapeHtml(b.id)}')">+ <span class="ttl">${escapeHtml(b.title || 'Untitled film')}</span>+ <span class="params">${b.shots} shots · ${b.done} rendered</span>+ <span class="badge">${escapeHtml(sbBoardChip(b))}</span>+ <button title="Delete this storyboard" onclick="event.stopPropagation();sbDeleteBoard('${escapeHtml(b.id)}','${escapeHtml((b.title || '').replace(/'/g, ''))}')"><svg class="ph" aria-hidden="true"><use href="#ph-x-bold"/></svg></button>+ </li>`).join('');+ const full = sbEl('sbBoardList');+ if (full) full.innerHTML = rows || '<li class="empty-state"><span></span><span>No storyboards yet</span><span></span><span></span></li>';+ const mini = sbEl('sbBoardListMini');+ if (mini) mini.innerHTML = rows;+}+async function sbDeleteBoard(id, title) {+ if (!confirm(`Delete "${title || 'this storyboard'}"?\n\nDeletes the plan. The clips it already rendered stay in mlx_outputs/.`)) return;+ const fd = new URLSearchParams(); fd.set('id', id);+ const r = await (await fetch('/storyboard/delete', { method: 'POST', body: fd })).json();+ if (!r.ok) { phosToast(r.error || 'Could not delete.', { kind: 'danger' }); return; }+ if (SB.id === id) { SB.id = ''; SB.payload = null; try { localStorage.removeItem('phos_sb_open'); } catch (e) {} }+ await sbRefreshBoards();+ sbShow(SB.boards.length ? 'list' : 'empty');+}++// ---- shared state: pull a normal generation INTO a film ---------------------+async function sbAddActiveToBoard(chosen) {+ if (!activePath) return;+ const sel = sbEl('sbAddSelect');+ if (!chosen && SB.boards.length > 1 && sel && sel.style.display === 'none') {+ sel.innerHTML = SB.boards.map(b =>+ `<option value="${escapeHtml(b.id)}">${escapeHtml(b.title || 'Untitled film')}</option>`).join('')+ + '<option value="new">— new storyboard —</option>';+ sel.style.display = '';+ return;+ }+ const id = chosen || (SB.boards.length === 1 ? SB.boards[0].id : (SB.boards[0] || {}).id) || 'new';+ if (sel) sel.style.display = 'none';+ const fd = new URLSearchParams();+ fd.set('id', id); fd.set('path', activePath);+ let r;+ try { r = await (await fetch('/storyboard/add-shot', { method: 'POST', body: fd })).json(); }+ catch (e) { r = { ok: false, error: String(e) }; }+ if (!r.ok) { phosToast(r.error || 'Could not add the clip.', { kind: 'danger' }); return; }+ phosToast(`Added to "${r.title || 'the film'}" as shot ${r.n}.`, { kind: 'success' });+ _flashActionDone('sbAddBtn', 'Added');+ sbRefreshBoards();+}++// One badge, one click, no new surface: a gallery card that is a shot of a film+// opens that film.+function sbOpenFromClip(id) {+ workflowSwitch('storyboard');+ setTimeout(() => sbOpen(id), 30);+}++// ---- the one cross-tab hook, called at the end of poll() -------------------+function sbPollHook(s) {+ SB.boards = s.storyboards || [];+ const live = SB.boards.filter(b => b.running);+ const count = sbEl('sbTabCount');+ if (count) {+ if (live.length) {+ const b = live[0];+ count.hidden = false;+ count.textContent = `${b.done}/${b.shots}`;+ } else { count.hidden = true; count.textContent = ''; }+ }+ const add = sbEl('sbAddBtn');+ if (add) add.style.display = SB.boards.length ? '' : 'none';+ // Plan film is blocked while the worker is busy — constraint 1, made visible.+ const btn = sbEl('sbPlanBtn');+ if (btn && btn.dataset.busy !== '1') {+ const busy = !!s.running || !!(s.queue || []).length;+ const empty = !((sbEl('sbConcept') || {}).value || '').trim();+ btn.disabled = busy || empty;+ btn.title = busy ? 'The renderer is using the memory. Planning can start when the queue is empty.'+ : empty ? 'Write a couple of sentences about the film first.' : '';+ }+ if (document.body.dataset.workflow === 'storyboard' && SB.id) sbRenderRunBar(SB.payload || {});+}++// ---- wiring ----------------------------------------------------------------+document.addEventListener('click', (ev) => {+ const chip = ev.target.closest && ev.target.closest('#sbLengthGroup .q-chip');+ if (chip) { sbSetShots(Number(chip.dataset.sbShots)); return; }+ const eng = ev.target.closest && ev.target.closest('#sbEngineGroup [data-sb-engine]');+ if (eng) { sbSetEngineMode(eng.dataset.sbEngine); return; }+ const reng = ev.target.closest && ev.target.closest('#sbReplanEngineGroup [data-sb-engine]');+ if (reng) {+ const h3 = sbH3Installed();+ if (reng.dataset.sbEngine === 'h3' && !h3.available) { sbSetEngineMode('h3'); return; }+ _sbReplanEngineMode = reng.dataset.sbEngine;+ sbRenderReplanEnginePicker();+ return;+ }+ const q = ev.target.closest && ev.target.closest('#sbDraftQuality .pill-btn, #sbFinalQuality .pill-btn');+ if (q) {+ 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 dims = table[q.dataset.q] || [1024, 576];+ board.policy = board.policy || {};+ board.policy[which] = Object.assign({}, board.policy[which],+ { quality: q.dataset.q, width: dims[0], height: dims[1] });+ sbSaveSetting(which === 'draft' ? 'storyboard_draft_quality' : 'storyboard_final_quality', q.dataset.q);+ sbRenderPlan(SB.payload);+ sbQueueSave(true);+ return;+ }+ const act = ev.target.closest && ev.target.closest('#sbShots [data-act]');+ if (act) {+ const li = act.closest('.sb-shot');+ if (li) sbShotAction(Number(li.dataset.n), act.dataset.act, act, ev);+ return;+ }+ const seg = ev.target.closest && ev.target.closest('.sb-runseg');+ if (seg) {+ const ns = (seg.dataset.shots || '').split(',');+ document.querySelectorAll('.sb-shot').forEach(el =>+ el.classList.toggle('is-lit', ns.indexOf(el.dataset.n) !== -1));+ }+});+document.addEventListener('mouseover', (ev) => {+ const seg = ev.target.closest && ev.target.closest('.sb-runseg');+ if (!seg) return;+ const ns = (seg.dataset.shots || '').split(',');+ document.querySelectorAll('.sb-shot').forEach(el =>+ el.classList.toggle('is-lit', ns.indexOf(el.dataset.n) !== -1));+});+document.addEventListener('mouseout', (ev) => {+ if (ev.target.closest && ev.target.closest('.sb-runseg'))+ document.querySelectorAll('.sb-shot.is-lit').forEach(el => el.classList.remove('is-lit'));+});+document.addEventListener('change', (ev) => {+ const el = ev.target.closest && ev.target.closest('#sbShots [data-act]');+ if (!el) return;+ const li = el.closest('.sb-shot');+ if (li) sbShotAction(Number(li.dataset.n), el.dataset.act, el, ev);+});+// Leaving a card is the moment the guard lifts — repaint straight away rather+// than leaving the user looking at a stale card for up to 2 s.+document.addEventListener('focusout', (ev) => {+ if (!ev.target.closest || !ev.target.closest('#sbShots')) return;+ setTimeout(() => {+ if (sbTypingInShots() || !SB.payload) return;+ if (document.body.dataset.workflow !== 'storyboard') return;+ try { sbRenderPlan(SB.payload); } catch (e) {}+ }, 60);+});++let _sbPromptTimer = null;+document.addEventListener('input', (ev) => {+ const el = ev.target.closest && ev.target.closest('#sbShots textarea[data-act="prompt"]');+ if (!el) return;+ const li = el.closest('.sb-shot');+ const s = sbShotById(Number(li.dataset.n));+ if (!s) return;+ s.prompt = el.value;+ sbAutoGrowPrompts(el);+ if (_sbPromptTimer) clearTimeout(_sbPromptTimer);+ _sbPromptTimer = setTimeout(() => sbQueueSave(true), 800);+});+// Grade keys: K / R / C with a card focused. Surfaced in the tally bar's title,+// not as visible chrome.+document.addEventListener('keydown', (ev) => {+ if (document.body.dataset.workflow !== 'storyboard') return;+ const li = document.activeElement && document.activeElement.closest+ && document.activeElement.closest('.sb-shot');+ if (!li || /^(INPUT|TEXTAREA|SELECT)$/.test((ev.target.tagName || ''))) return;+ const g = { k: 'keep', r: 'reroll', c: 'cut' }[ev.key.toLowerCase()];+ if (!g) return;+ const n = Number(li.dataset.n);+ const s = sbShotById(n);+ if (!s || !(s.draft_output || s.final_output)) return;+ ev.preventDefault();+ sbGrade(n, s.grade === g ? null : g, s.note || '');+});+// Drag to reorder — ~20 lines, no library. The ↑ / ↓ buttons are the primary+// affordance (keyboard- and touch-reachable); drag is the enhancement.+let _sbDragN = null;+document.addEventListener('dragstart', (ev) => {+ const li = ev.target.closest && ev.target.closest('.sb-shot');+ if (!li || li.getAttribute('draggable') === 'false') return;+ _sbDragN = Number(li.dataset.n);+ li.classList.add('is-dragging');+ try { ev.dataTransfer.setData('text/plain', String(_sbDragN)); } catch (e) {}+});+document.addEventListener('dragover', (ev) => {+ const li = ev.target.closest && ev.target.closest('.sb-shot');+ if (!li || _sbDragN == null) return;+ ev.preventDefault();+ const r = li.getBoundingClientRect();+ const after = (ev.clientY - r.top) > r.height / 2;+ document.querySelectorAll('.sb-shot').forEach(el =>+ el.classList.remove('sb-drop-before', 'sb-drop-after'));+ li.classList.add(after ? 'sb-drop-after' : 'sb-drop-before');+});+document.addEventListener('drop', (ev) => {+ const li = ev.target.closest && ev.target.closest('.sb-shot');+ if (!li || _sbDragN == null) return;+ ev.preventDefault();+ const board = ((SB.payload || {}).board);+ const from = board.shots.findIndex(s => s.n === _sbDragN);+ let to = board.shots.findIndex(s => s.n === Number(li.dataset.n));+ const r = li.getBoundingClientRect();+ if ((ev.clientY - r.top) > r.height / 2) to += 1;+ if (from < 0 || to < 0) return;+ const moved = board.shots.splice(from, 1)[0];+ board.shots.splice(to > from ? to - 1 : to, 0, moved);+ board.shots.forEach((x, k) => { x.n = k + 1; });+ sbRenderPlan(SB.payload);+ sbQueueSave(true);+});+document.addEventListener('dragend', () => {+ _sbDragN = null;+ document.querySelectorAll('.sb-shot').forEach(el =>+ el.classList.remove('is-dragging', 'sb-drop-before', 'sb-drop-after'));+});+document.getElementById('sbStyle') && document.getElementById('sbStyle')+ .addEventListener('input', () => {});+function workflowSwitch(name) {// 2026-05-17 — Characters is no longer its own top-level tab. The// chip strip is integrated into Manual (T2V). If we get a stale@@ -42778,6 +47683,7 @@ function workflowSwitch(name) {const studio = document.getElementById('studioSection');const train = document.getElementById('trainSection');const audioTab = document.getElementById('audioSectionTab');+ const sbTab = document.getElementById('sbSectionTab');const characters = document.getElementById('charactersSection'); // dead HTML; hide defensively// Set body data attribute so CSS can switch the layout per workflow.document.body.setAttribute('data-workflow', name);@@ -42785,8 +47691,22 @@ function workflowSwitch(name) {if (studio) studio.classList.remove('show');if (train) train.classList.remove('show');if (audioTab) audioTab.style.display = 'none';+ if (sbTab) sbTab.style.display = 'none';if (characters) characters.classList.remove('show');- if (name === 'studio') {+ // The board poller is the Storyboard tab's only timer and it stops on exit —+ // no new polling loop runs while the tab is closed.+ if (name !== 'storyboard') {+ if (typeof sbTeardown === 'function') sbTeardown();+ document.body.classList.remove('sb-full');+ }+ if (name === 'storyboard') {+ // Storyboard is a layer ABOVE the video modes, not one of them: it submits+ // a brief to a planner and its output is a plan, not a clip. Hence a+ // workflow tab rather than a 6th chip in #modeGroup.+ if (manual) manual.style.display = 'none';+ if (sbTab) sbTab.style.display = 'block';+ if (typeof sbInit === 'function') sbInit();+ } else if (name === 'studio') {// Studio is its own top-level tab now (was a mode chip inside// Manual). The setMode('image') logic still wires up the studio// pane + portals the LoRA picker into the studio composer; just@@ -42837,7 +47757,10 @@ try {// 2026-05-17 — Characters tab removed; 'characters' now snaps to// 'manual' (workflowSwitch handles the alias). 'studio' is new.// 2026-05-18 — 'audio' is the Audio → Video workflow tab.- if (saved === 'studio' || saved === 'train' || saved === 'characters' || saved === 'audio') {+ // 2026-08-11 — 'storyboard' is the plan-a-film workflow tab. It MUST be in+ // this list or the tab simply never restores across a reload.+ if (saved === 'studio' || saved === 'train' || saved === 'characters' ||+ saved === 'audio' || saved === 'storyboard') {workflowSwitch(saved);}// Clear any stale agent-fullscreen flag from the removed chat surface.@@ -42937,6 +47860,7 @@ if __name__ == "__main__":# BEFORE worker_loop starts, or the resumed job races an orphan that is# still holding 40 GiB of the same GPU.reap_orphan_subprocesses()+ _sb_boot_reconcile()load_hidden()load_queue()threading.Thread(target=worker_loop, daemon=True).start()@@ -42952,8 +47876,10 @@ if __name__ == "__main__":# Anonymous usage analytics — one app_boot event plus any optional-pack# transitions since the last boot, then nothing until a job finishes.# Deliberately here in __main__ and not at import time, so `import- # mlx_ltx_panel` from a script or a test never emits anything. Inert- # unless a PostHog key is configured; see the analytics section above.+ # mlx_ltx_panel` from a script or a test never emits anything. A stock+ # install DOES report (the project key ships); the Settings toggle and+ # PHOSPHENE_ANALYTICS_DISABLED are the off switches. See the analytics+ # section above and docs/ANALYTICS.md._analytics_boot()# Pre-flight: bind in a try/except so a busy port surfaces an actionable# one-liner instead of a 6-frame Python traceback. The bare OSErrordiff --git a/mlx_warm_helper.py b/mlx_warm_helper.pyindex 93908f2..8b3029c 100644--- a/mlx_warm_helper.py+++ b/mlx_warm_helper.py@@ -266,6 +266,7 @@ _hq_model_dir = None # remember which model the HQ pipe was built against_a2v_pipe = None # A2VidPipelineTwoStage (Q8 dev + distilled LoRA stage 2)_a2v_model_dir = None # which model the A2V pipe was built against_a2v_lora_key: tuple | None = None # LoRA fingerprint for current A2V cache+_a2v_weight_key: tuple[str, str] | None = None # (dev_transformer, distilled_lora) names_a2v_distilled_pipe = None # A2VidDistilledPipeline (Q4 distilled, no CFG)_a2v_distilled_model_dir = None_pipe_lock = threading.Lock()@@ -392,6 +393,10 @@ def release_pipelines(keep_kind=None):_t2v_lora_key: tuple | None = None_i2v_lora_key: tuple | None = None_extend_lora_key: tuple | None = None+# Dev-transformer filename the cached Extend pipe was built with. Named per+# generation by the panel; same string for 2.3 and 2.5 today, in the cache key+# so a future rename cannot be served by a stale pipe.+_extend_dev_name: str | None = Nonedef _lora_fingerprint(loras: list[dict] | None) -> tuple:@@ -604,8 +609,16 @@ def _install_a2v_frame_rate_patch() -> None:because their explicit kwarg overrides the default.Why a wrapper instead of editing the vendored file: the ltx-2-mlx- checkout is pinned to v0.14.8 and any direct edit gets clobbered on+ checkout is pinned to a tag and any direct edit gets clobbered onre-clone. The patch is idempotent so repeated helper boots are safe.++ As of the v0.14.19 pin this shim is INERT on the paths it was written+ for — upstream 0.14.15 (#56) forwards ``frame_rate`` from the A2V and+ lipdub call sites. It stays as a belt-and-braces default because+ ``frame_rate`` is still keyword-only *required* on+ ``combined_image_conditionings``, so any future caller that forgets it+ would again die mid-render rather than degrade. Do not read its+ presence as evidence the upstream bug is still live."""global _A2V_FRAME_RATE_PATCH_INSTALLEDif _A2V_FRAME_RATE_PATCH_INSTALLED:@@ -839,10 +852,16 @@ def _attach_loras(pipe, loras: list[dict] | None) -> None:_extend_model_dir: str | None = None+# The base pipelines cache their model_dir the same way Extend does, so a+# job that names a different model version rebuilds instead of silently+# rendering on the previous one's weights.+_t2v_model_dir: str | None = None+_i2v_model_dir: str | None = Nonedef get_pipe(kind: str, loras: list[dict] | None = None,- model_dir: str | None = None):+ model_dir: str | None = None,+ dev_transformer: str | None = None):"""kind in {'t2v','i2v','extend'}; loras is an optional list of{path, strength} dicts. When the requested LoRA set differs fromthe cached pipeline's, the pipeline is rebuilt — LoRA fusion is a@@ -854,10 +873,27 @@ def get_pipe(kind: str, loras: list[dict] | None = None,carried a copy of `transformer-dev.safetensors` (download bloat) so Extendsilently loaded from there; the Y1.024 download filter pruned the dupe andexposed that Extend is structurally Q8-class. Cached alongside the LoRA- fingerprint so a model_dir flip rebuilds the pipe."""+ fingerprint so a model_dir flip rebuilds the pipe.++ 2026-08-11 — `model_dir` now applies to T2V and I2V too. It used to be+ Extend-only, which meant the BASE render was pinned to whatever+ LTX_MODEL this helper process was spawned with: a module-level+ singleton, chosen once, unreachable per job. That is fine while there+ is exactly one LTX generation on disk and fatal the moment there are+ two — the panel would have had to kill and respawn the helper to+ switch versions, mid-queue, with the weights still resident. Passing+ None keeps the old behaviour exactly (fall back to MODEL_ID), which is+ what every caller that has not been taught about versions still does.++ The helper stays version-AGNOSTIC on purpose: it takes a directory,+ never a version id. Which generation a directory holds is the+ checkpoint's business (2.5 makes the vendored config metadata-driven),+ and the panel's registry is the thing that knows which directory to+ name."""global _t2v_pipe, _i2v_pipe, _extend_pipeglobal _t2v_lora_key, _i2v_lora_key, _extend_lora_key- global _extend_model_dir+ global _extend_model_dir, _t2v_model_dir, _i2v_model_dir+ global _extend_dev_nametry:from ltx_core_mlx.utils.memory import aggressive_cleanup as _acexcept Exception:@@ -901,26 +937,36 @@ def get_pipe(kind: str, loras: list[dict] | None = None,# one-pipeline-at-a-time policy keeps memory bounded.release_pipelines(keep_kind=kind)if kind == "i2v":- if _i2v_pipe is None or _i2v_lora_key != fp:- if _i2v_pipe is not None and _i2v_lora_key != fp:+ i2v_dir = model_dir or MODEL_ID+ if (_i2v_pipe is None or _i2v_lora_key != fp+ or _i2v_model_dir != i2v_dir):+ if _i2v_pipe is not None:+ why = ("LoRA set changed" if _i2v_lora_key != fp+ else "model_dir changed")emit({"event": "log",- "line": f"LoRA set changed; reloading I2V pipeline."})+ "line": f"{why}; reloading I2V pipeline."})_i2v_pipe = None_ac()emit({"event": "log","line": "Loading I2V pipeline (first job is the slow one)..."})pipe = ImageToVideoPipeline(- model_dir=MODEL_ID, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,+ model_dir=i2v_dir, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,)_attach_loras(pipe, loras)_i2v_pipe = pipe_i2v_lora_key = fp+ _i2v_model_dir = i2v_dirreturn _i2v_pipeif kind == "extend":ext_dir = model_dir or MODEL_ID+ # Named by the panel per generation; None keeps RetakePipeline's+ # own default, which is the same string today. Part of the cache+ # key for the same reason model_dir is.+ ext_dev = dev_transformer or "transformer-dev.safetensors"if (_extend_pipe is Noneor _extend_lora_key != fp- or _extend_model_dir != ext_dir):+ or _extend_model_dir != ext_dir+ or _extend_dev_name != ext_dev):if _extend_pipe is not None:why = "LoRA set changed" if _extend_lora_key != fp else "model_dir changed"emit({"event": "log",@@ -931,34 +977,48 @@ def get_pipe(kind: str, loras: list[dict] | None = None,"line": f"Loading Extend pipeline (heavier — uses dev transformer at {ext_dir})..."})pipe = ExtendPipeline(model_dir=ext_dir, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,+ dev_transformer=ext_dev,)_attach_loras(pipe, loras)_extend_pipe = pipe_extend_lora_key = fp_extend_model_dir = ext_dir+ _extend_dev_name = ext_devreturn _extend_pipe# t2v- if _t2v_pipe is None or _t2v_lora_key != fp:- if _t2v_pipe is not None and _t2v_lora_key != fp:+ t2v_dir = model_dir or MODEL_ID+ if (_t2v_pipe is None or _t2v_lora_key != fp+ or _t2v_model_dir != t2v_dir):+ if _t2v_pipe is not None:+ why = ("LoRA set changed" if _t2v_lora_key != fp+ else "model_dir changed")emit({"event": "log",- "line": f"LoRA set changed; reloading T2V pipeline."})+ "line": f"{why}; reloading T2V pipeline."})_t2v_pipe = None_ac()emit({"event": "log","line": "Loading T2V pipeline (first job is the slow one)..."})pipe = TextToVideoPipeline(- model_dir=MODEL_ID, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,+ model_dir=t2v_dir, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,)_attach_loras(pipe, loras)_t2v_pipe = pipe_t2v_lora_key = fp+ _t2v_model_dir = t2v_dirreturn _t2v_pipe_hq_lora_key: str | None = None+# (dev_transformer, distilled_lora) the cached HQ pipe was built with. A+# generation switch changes the distilled LoRA filename, and a pipe reused+# across that switch would refine stage 2 with the previous generation's LoRA+# — which fuses, renders, and is wrong with nothing to attribute it to.+_hq_weight_key: tuple[str | None, str | None] | None = None-def get_hq_pipe(model_dir: str, loras: list[dict] | None = None):+def get_hq_pipe(model_dir: str, loras: list[dict] | None = None,+ dev_transformer: str | None = None,+ distilled_lora: str | None = None):"""Returns the TwoStageHQPipeline lazily — Q8 model, res_2s sampler, CFG anchor.Same class handles both T2V (image=None) and I2V via the `image` kwarg of@@ -972,8 +1032,20 @@ def get_hq_pipe(model_dir: str, loras: list[dict] | None = None):silently dropped LoRAs (fixed) but the result is still wrong because thedeltas were learned against dev neuron states, not distilled. RoutingLoRA renders to HQ is the only way to get a faithful character replay.++ 2026-08-12 — `dev_transformer` / `distilled_lora` are the panel's per-job+ names for the two files this pipeline loads out of `model_dir`. Passing+ None keeps the vendored class's own defaults, which are the 2.3 filenames;+ that is the byte-identical legacy behaviour for any caller that has not+ been taught about generations. The panel now always names them, because+ 2.5's distilled LoRA is `...-450` where 2.3's is `...-384` and the vendored+ default would send the loader looking for a file the pack does not hold.++ Cached alongside model_dir and the LoRA fingerprint: a filename flip is a+ different pipeline, and a pipeline reused across a generation switch would+ quietly refine with the wrong LoRA."""- global _hq_pipe, _hq_model_dir, _hq_lora_key+ global _hq_pipe, _hq_model_dir, _hq_lora_key, _hq_weight_key# Upstream `ltx-2-mlx` refactor 2026-05-09 (commits d6cc3d1, 493aec2,# 32280b9 — `refactor!: rename pipeline classes to match upstream# verbatim`) renamed TwoStageHQPipeline → TI2VidTwoStagesHQPipeline.@@ -998,23 +1070,40 @@ def get_hq_pipe(model_dir: str, loras: list[dict] | None = None):from ltx_core_mlx.utils.memory import aggressive_cleanup as _acexcept Exception:_ac = lambda: None+ weight_key = (dev_transformer, distilled_lora)with _pipe_lock:release_pipelines(keep_kind="hq")if (_hq_pipe is Noneor _hq_model_dir != model_dir- or _hq_lora_key != fp):+ or _hq_lora_key != fp+ or _hq_weight_key != weight_key):if _hq_pipe is not None:- why = "LoRA set changed" if _hq_lora_key != fp else "model_dir changed"+ if _hq_lora_key != fp:+ why = "LoRA set changed"+ elif _hq_weight_key != weight_key:+ why = "HQ weight filenames changed"+ else:+ why = "model_dir changed"emit({"event": "log", "line": f"{why}; reloading HQ pipeline."})_hq_pipe = None_ac()emit({"event": "log", "line": f"Loading HQ pipeline (Q8 dev model — {model_dir})..."})+ # Only pass what the caller named: an explicit None would override+ # the vendored default with nothing, and `distilled_lora=None`+ # makes _fuse_distilled_lora resolve the stem of None.+ hq_kwargs = {}+ if dev_transformer:+ hq_kwargs["dev_transformer"] = dev_transformer+ if distilled_lora:+ hq_kwargs["distilled_lora"] = distilled_lora_hq_pipe = TwoStageHQPipeline(model_dir=model_dir, gemma_model_id=GEMMA_PATH, low_memory=LOW_MEMORY,+ **hq_kwargs,)_attach_loras(_hq_pipe, loras)_hq_model_dir = model_dir_hq_lora_key = fp+ _hq_weight_key = weight_keyreturn _hq_pipe@@ -1022,17 +1111,24 @@ def get_hq_pipe(model_dir: str, loras: list[dict] | None = None):# interpolates between. Uses Q8 dev transformer + distilled LoRA stage 2._kf_pipe = None_kf_model_dir = None+_kf_weight_key: tuple[str, str] | None = None-def get_kf_pipe(model_dir: str):+def get_kf_pipe(model_dir: str, dev_transformer: str | None = None,+ distilled_lora: str | None = None):"""Returns the KeyframeInterpolationPipeline lazily.Keyframe REQUIRES explicit dev_transformer + distilled_lora at init time.The distilled-only path "hallucinates unrelated content during- interpolation" — pipeline raises if you skip these. Names match the files- inside dgrauet/ltx-2.3-mlx-q8.+ interpolation" — pipeline raises if you skip these.++ The names used to be the two literals from dgrauet/ltx-2.3-mlx-q8, written+ here. They now come from the panel per job, because the distilled LoRA's+ filename carries its alpha/rank and that number changes with the+ generation (2.3: 384, 2.5: 450). The literals remain as the fallback so a+ caller that does not name them behaves exactly as before."""- global _kf_pipe, _kf_model_dir+ global _kf_pipe, _kf_model_dir, _kf_weight_keyfrom ltx_pipelines_mlx.keyframe_interpolation import KeyframeInterpolationPipeline# Install the same runtime patches that get_pipe / get_hq_pipe / get_a2v_pipe@@ -1045,19 +1141,23 @@ def get_kf_pipe(model_dir: str):_install_video_decoder_patch()_install_a2v_frame_rate_patch()+ dev_name = dev_transformer or "transformer-dev.safetensors"+ lora_name = distilled_lora or "ltx-2.3-22b-distilled-lora-384.safetensors"+ weight_key = (dev_name, lora_name)with _pipe_lock:release_pipelines(keep_kind="keyframe")- if _kf_pipe is None or _kf_model_dir != model_dir:+ if _kf_pipe is None or _kf_model_dir != model_dir or _kf_weight_key != weight_key:emit({"event": "log", "line": f"Loading Keyframe pipeline (Q8 dev model — {model_dir})..."})_kf_pipe = KeyframeInterpolationPipeline(model_dir=model_dir,gemma_model_id=GEMMA_PATH,low_memory=LOW_MEMORY,- dev_transformer="transformer-dev.safetensors",- distilled_lora="ltx-2.3-22b-distilled-lora-384.safetensors",+ dev_transformer=dev_name,+ distilled_lora=lora_name,distilled_lora_strength=1.0,)_kf_model_dir = model_dir+ _kf_weight_key = weight_keyreturn _kf_pipe@@ -1069,16 +1169,22 @@ def get_kf_pipe(model_dir: str):# "Image + Audio" (audio + still + prompt → audio-driven video that opens on# the reference frame). The upstream pipeline writes the original audio (not# VAE-decoded) onto the final mp4, so no panel-side mux is needed.-def get_a2v_pipe(model_dir: str, loras: list[dict] | None = None):+def get_a2v_pipe(model_dir: str, loras: list[dict] | None = None,+ dev_transformer: str | None = None,+ distilled_lora: str | None = None):"""Returns A2VidPipelineTwoStage lazily.A2V REQUIRES dev_transformer + distilled_lora at init time (same pattern- as Keyframe). The pipeline inherits from TI2VidTwoStagesPipeline so LoRA- fusion goes through the same `_pending_loras` hook the patched load()- consumes. Cached on (model_dir, lora_fingerprint) so a LoRA swap or a- model-dir flip rebuilds; otherwise reuses.+ as Keyframe), and like Keyframe those names now come from the panel per+ job — the distilled LoRA's filename carries its alpha/rank, which changes+ with the generation. The 2.3 literals remain as the fallback.++ The pipeline inherits from TI2VidTwoStagesPipeline so LoRA fusion goes+ through the same `_pending_loras` hook the patched load() consumes. Cached+ on (model_dir, lora_fingerprint, weight filenames) so a LoRA swap, a+ model-dir flip or a generation switch rebuilds; otherwise reuses."""- global _a2v_pipe, _a2v_model_dir, _a2v_lora_key+ global _a2v_pipe, _a2v_model_dir, _a2v_lora_key, _a2v_weight_keyfrom ltx_pipelines_mlx.a2vid_two_stage import A2VidPipelineTwoStage_install_lora_fusion_patches()@@ -1090,13 +1196,22 @@ def get_a2v_pipe(model_dir: str, loras: list[dict] | None = None):from ltx_core_mlx.utils.memory import aggressive_cleanup as _acexcept Exception:_ac = lambda: None+ dev_name = dev_transformer or "transformer-dev.safetensors"+ lora_name = distilled_lora or "ltx-2.3-22b-distilled-lora-384.safetensors"+ weight_key = (dev_name, lora_name)with _pipe_lock:release_pipelines(keep_kind="a2v")if (_a2v_pipe is Noneor _a2v_model_dir != model_dir- or _a2v_lora_key != fp):+ or _a2v_lora_key != fp+ or _a2v_weight_key != weight_key):if _a2v_pipe is not None:- why = "LoRA set changed" if _a2v_lora_key != fp else "model_dir changed"+ if _a2v_lora_key != fp:+ why = "LoRA set changed"+ elif _a2v_weight_key != weight_key:+ why = "HQ weight filenames changed"+ else:+ why = "model_dir changed"emit({"event": "log", "line": f"{why}; reloading A2V pipeline."})_a2v_pipe = None_ac()@@ -1106,13 +1221,14 @@ def get_a2v_pipe(model_dir: str, loras: list[dict] | None = None):model_dir=model_dir,gemma_model_id=GEMMA_PATH,low_memory=LOW_MEMORY,- dev_transformer="transformer-dev.safetensors",- distilled_lora="ltx-2.3-22b-distilled-lora-384.safetensors",+ dev_transformer=dev_name,+ distilled_lora=lora_name,distilled_lora_strength=1.0,)_attach_loras(_a2v_pipe, loras)_a2v_model_dir = model_dir_a2v_lora_key = fp+ _a2v_weight_key = weight_keyreturn _a2v_pipe@@ -1799,7 +1915,19 @@ def configure_acceleration(mode: str) -> str:# the pin Phosphene's patches are written against, and makes ANY skew loud +# visible in the ready event (so every remote bug report carries it) instead# of letting it surface as an un-triageable TypeError mid-render.-_LTX_EXPECTED_VERSION = "0.14.8"+#+# 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.+#+# 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"def _detect_ltx_version() -> dict:@@ -1966,7 +2094,10 @@ for line in sys.__stdin__:else:emit({"event": "log","line": f"step:get_pipe kind={('i2v' if needs_image else 't2v')}"})- pipe = get_pipe("i2v" if needs_image else "t2v", loras=loras)+ # The panel names the pack on the job spec now; None keeps the+ # pre-2026-08 behaviour (this helper's spawn-time LTX_MODEL).+ pipe = get_pipe("i2v" if needs_image else "t2v", loras=loras,+ model_dir=p.get("model_dir"))emit({"event": "log", "line": "step:get_pipe done"})_log_memory_pressure()accel_mode = configure_acceleration(p.get("accel", "off"))@@ -2134,7 +2265,8 @@ for line in sys.__stdin__:# passes the resolved Q8 path via params.model_dir; falling back# to the helper's MODEL_ID is the legacy behavior.ext_model_dir = p.get("model_dir")- pipe = get_pipe("extend", loras=loras, model_dir=ext_model_dir)+ pipe = get_pipe("extend", loras=loras, model_dir=ext_model_dir,+ dev_transformer=p.get("dev_transformer"))video_path = p["video_path"]if not os.path.exists(video_path):raise RuntimeError(f"source video not found: {video_path}")@@ -2239,7 +2371,9 @@ for line in sys.__stdin__:if hq_loras:emit({"event": "log","line": f"step:get_pipe kind=hq loras={len(hq_loras)}"})- pipe = get_hq_pipe(model_dir, loras=hq_loras)+ pipe = get_hq_pipe(model_dir, loras=hq_loras,+ dev_transformer=p.get("dev_transformer"),+ distilled_lora=p.get("distilled_lora"))# Y1.037: short-clip VAE-streaming opt-out (HQ T2V/I2V path)._apply_vae_streaming_decision(int(p["frames"]))kwargs = dict(@@ -2428,7 +2562,9 @@ for line in sys.__stdin__:kf_indices = [0, num_frames - 1]kf_mode_label = "FFLF"- pipe = get_kf_pipe(model_dir)+ pipe = get_kf_pipe(model_dir,+ dev_transformer=p.get("dev_transformer"),+ distilled_lora=p.get("distilled_lora"))# Y1.037: short-clip VAE-streaming opt-out (Keyframe path)._apply_vae_streaming_decision(num_frames)kwargs = dict(@@ -2498,7 +2634,9 @@ for line in sys.__stdin__:raise RuntimeError(f"audio file not found: {audio_path}")num_frames = int(p["frames"])loras = p.get("loras") or []- pipe = get_a2v_pipe(model_dir, loras=loras)+ pipe = get_a2v_pipe(model_dir, loras=loras,+ dev_transformer=p.get("dev_transformer"),+ distilled_lora=p.get("distilled_lora"))_apply_vae_streaming_decision(num_frames)kwargs = dict(prompt=p["prompt"],@@ -2868,7 +3006,7 @@ for line in sys.__stdin__:"does not accept it — it would silently run two-stage and ""produce a static copy of the reference sheet. Upgrade/repair ""the ltx-2-mlx pipeline (need a build with skip_stage_2; "- "v0.14.8+ has it)."+ "v0.14.8+ has it; the current pin is v0.14.19).")out_path = pipe.generate_and_save(**kwargs)# Drop the pipeline aggressively — restore jobs are rare and thediff --git a/patch_ltx_codec.py b/patch_ltx_codec.pyindex 77de49b..3cce8ec 100644--- a/patch_ltx_codec.py+++ b/patch_ltx_codec.py@@ -3,7 +3,10 @@History: through ltx-2-mlx **v0.14.0** this script carried SEVEN patches,working around upstream gaps. As of the **v0.14.8** pin (2026-06-01 catch-up)-dgrauet has absorbed all but one of them upstream, so they were DROPPED:+dgrauet has absorbed all but one of them upstream, so they were DROPPED+(and the **v0.14.19** pin, 2026-08-11, keeps exactly this shape — the+`decode_and_stream` ffmpeg line moved from 482 to 487 but its text is+character-identical, so the patch applies unchanged):- I2V OOM / pre-denoise / base-load memory frees (old Patches 2,3,4)→ native `low_memory` path. v0.14.8 frees generation components via@@ -28,7 +31,7 @@ dgrauet has absorbed all but one of them upstream, so they were DROPPED:The helper already calls the new API defensively (`hasattr` guard on`generate`/`generate_from_image`, `inspect.signature` probing, and`_filter_unsupported_kwargs`), so nothing depends on the dropped patches.-Re-implementing them against v0.14.8 would only re-introduce divergence — the+Re-implementing them against the pinned tag would only re-introduce divergence — thewhole point of the catch-up was to let pinned-upstream own this behaviour.What REMAINS is the one preference upstream doesn't share:@@ -173,7 +176,7 @@ def apply_patch(target: Path, old: str, new: str, marker: str, label: str,def main() -> int:- print("Applying LTX23MLX codec patch (ltx-2-mlx v0.14.8 — only the codec edit remains):")+ print("Applying LTX23MLX codec patch (ltx-2-mlx 871694d / 0.14.19+ltx25.1 — 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 47dea16..5f3eb6b 100644--- a/pinokio.js+++ b/pinokio.js@@ -20,11 +20,11 @@ const fs = require("fs")const os = require("os")const path = require("path")-// Hailuo H3 (optional second video engine) needs ~40 GiB resident at peak, so-// the menu entry only appears on 64 GB+ Macs. A 64 GB machine reports ~63.x GB-// after firmware reservations, hence the 60 GB floor — the same number-// h3_capable() uses in mlx_ltx_panel.py. Keep them in sync.-const H3_MIN_BYTES = 60 * 1000 * 1000 * 1000+// Hailuo H3 (optional second video engine): since v3.7.0 the Q8 DiT lane runs+// in ~27 GiB peak, so the floor is 46 GB — the same number install_h3.js's+// preflight and H3_MIN_RAM_GB_Q8 in mlx_ltx_panel.py use. Keep all three in+// sync. (A 48 GB Mac reports ~47.x GB after firmware reservations.)+const H3_MIN_BYTES = 46 * 1000 * 1000 * 1000function h3Capable() {try {diff --git a/pip-build-constraints.txt b/pip-build-constraints.txtnew file mode 100644index 0000000..9bd179c--- /dev/null+++ b/pip-build-constraints.txt@@ -0,0 +1,42 @@+# Build-backend constraints for the vendored ltx-2-mlx wheels.+#+# WHY THIS FILE EXISTS+# --------------------+# `packages/ltx-{core,pipelines,trainer}*/pyproject.toml` all declare+# readme = "../../README.md"+# i.e. a path OUTSIDE the package directory (they share the repo-root README).+# hatchling accepted that for years. **hatchling 1.32.0 made it a hard error:**+#+# ValueError: Readme path must be within the project directory: ../../README.md+# error: metadata-generation-failed+#+# Both installer paths build those three packages from source, and both create+# an isolated build env that resolves the build backend fresh from PyPI — so+# from the day 1.32.0 landed, EVERY fresh install (install.js) and EVERY+# Update click (update.js) fails at that step, on every pinned tag. It is not+# a pin-bump regression; it is a moving third-party dependency breaking a+# frozen source tree.+#+# HOW IT IS WIRED+# ---------------+# install.js → uv pip install --build-constraints ../pip-build-constraints.txt ...+# update.js → uv pip install --build-constraints ../pip-build-constraints.txt ...+#+# Both are relative to the `ltx-2-mlx` working directory those steps run in.+#+# NOT `PIP_CONSTRAINT=... ./env/bin/pip install ...`. That was the documented+# trick for years, and current pip breaks it on purpose: the sub-install that+# populates the isolated build env is spawned with+# `_PIP_IN_BUILD_IGNORE_CONSTRAINTS=1`, so the environment constraint is+# dropped and hatchling 1.32.0 gets resolved anyway (verified on pip 26.1 and+# 26.2.1, relative and absolute paths alike). pip's replacement is the+# `--build-constraint` flag, which older pips reject outright — and Update+# runs on venvs seeded across many uv versions. uv honours the constraint on+# all of them, so both installer paths use uv and share one failure mode.+#+# WHEN TO REMOVE IT+# -----------------+# When a pinned upstream tag stops pointing `readme` outside the package dir+# (or hatchling relaxes the rule). Until then this stays: dropping it silently+# re-breaks install AND update for everyone.+hatchling<1.32diff --git a/required_files.json b/required_files.jsonindex 36b7c0c..3050417 100644--- a/required_files.json+++ b/required_files.json@@ -1,13 +1,11 @@{"_comment": "Single source of truth for what counts as a complete install. Read by pinokio.js (sidebar menu), mlx_ltx_panel.py (/status, /models, run-time job validation), and consumed indirectly by install.js + download_q8.js (whose `hf download` calls land files at the local_dir paths listed below). When the upstream model layout changes, edit ONE file.",-- "_download_include_comment": "Y1.024 — `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 — 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 — 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.",-+ "_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": [{"key": "q4","kind": "base",- "name": "LTX 2.3 — Q4 (base model, distilled)",+ "name": "LTX 2.3 \u2014 Q4 (base model, distilled)","blurb": "Required. Drives Quick / Balanced / Standard renders.","repo_id": "dgrauet/ltx-2.3-mlx-q4","local_dir": "mlx_models/ltx-2.3-mlx-q4",@@ -50,7 +48,7 @@{"key": "q8","kind": "optional",- "name": "LTX 2.3 — Q8 (high-quality + FFLF)",+ "name": "LTX 2.3 \u2014 Q8 (high-quality + FFLF)","blurb": "Optional. Unlocks High quality and keyframe (FFLF) interpolation.","repo_id": "dgrauet/ltx-2.3-mlx-q8","local_dir": "mlx_models/ltx-2.3-mlx-q8",@@ -81,7 +79,7 @@"key": "ic_colorize","kind": "optional","name": "Colorize IC-LoRA (community)",- "blurb": "Optional. Powers the Colorize restore mode — adds natural color to a B&W source clip. Un-gated community weights (no HF token).",+ "blurb": "Optional. Powers the Colorize restore mode \u2014 adds natural color to a B&W source clip. Un-gated community weights (no HF token).","repo_id": "DoctorDiffusion/LTX-2.3-IC-LoRA-Colorizer","local_dir": "mlx_models/loras/ic","size_gb": 1,@@ -96,11 +94,11 @@]},{- "_comment": "Ingredients (flagship multi-reference) IC-LoRA. BYTE-IDENTICAL to the gated official Lightricks/LTX-2.3-22b-IC-LoRA-Ingredients (same 1308778338-byte size, sha256 515e4e139001ac6282357a5b35372e42e98b3affd5fcc886a52242abeed19559), mirrored un-gated. WARNING: DeepBeepMeep/LTX-2 is a ~708 GB mega-repo (71 safetensors) — the download_include here pulls ONLY the one ingredients file (1.3 GB), and the worker fallback uses hf_hub_download for the exact filename, NEVER a bare snapshot_download of the whole repo.",+ "_comment": "Ingredients (flagship multi-reference) IC-LoRA. BYTE-IDENTICAL to the gated official Lightricks/LTX-2.3-22b-IC-LoRA-Ingredients (same 1308778338-byte size, sha256 515e4e139001ac6282357a5b35372e42e98b3affd5fcc886a52242abeed19559), mirrored un-gated. WARNING: DeepBeepMeep/LTX-2 is a ~708 GB mega-repo (71 safetensors) \u2014 the download_include here pulls ONLY the one ingredients file (1.3 GB), and the worker fallback uses hf_hub_download for the exact filename, NEVER a bare snapshot_download of the whole repo.","key": "ic_ingredients","kind": "optional","name": "Ingredients IC-LoRA",- "blurb": "Optional. Powers the Ingredients mode — composes 2-8 reference images (face + prop + location) into one new video. Un-gated mirror of the official weight (no HF token).",+ "blurb": "Optional. Powers the Ingredients mode \u2014 composes 2-8 reference images (face + prop + location) into one new video. Un-gated mirror of the official weight (no HF token).","repo_id": "DeepBeepMeep/LTX-2","local_dir": "mlx_models/loras/ic","size_gb": 2,@@ -115,11 +113,11 @@]},{- "_comment": "Control (Union) IC-LoRA — drives a render's motion/structure/composition from a control video. This is the OFFICIAL Lightricks weight and it is UN-GATED + public (gated:false, single 654465352-byte safetensors), so it downloads token-less exactly like the community Colorizer — NO mrbizarro mirror, NO HF token, NO mega-repo workaround. reference_downscale_factor=2 (the IC encoder halves the control clip; handled in iclora_utils).",+ "_comment": "Control (Union) IC-LoRA \u2014 drives a render's motion/structure/composition from a control video. This is the OFFICIAL Lightricks weight and it is UN-GATED + public (gated:false, single 654465352-byte safetensors), so it downloads token-less exactly like the community Colorizer \u2014 NO mrbizarro mirror, NO HF token, NO mega-repo workaround. reference_downscale_factor=2 (the IC encoder halves the control clip; handled in iclora_utils).","key": "ic_union_control","kind": "optional","name": "Control IC-LoRA (Union, official)",- "blurb": "Optional. Powers the Control mode — drives motion/structure/composition from a control video. Official un-gated Lightricks weight (no HF token).",+ "blurb": "Optional. Powers the Control mode \u2014 drives motion/structure/composition from a control video. Official un-gated Lightricks weight (no HF token).","repo_id": "Lightricks/LTX-2.3-22b-IC-LoRA-Union-Control","local_dir": "mlx_models/loras/ic","size_gb": 1,@@ -134,9 +132,8 @@]}],-"env": {- "_comment": "Marker that the venv exists. SHIP-BLOCKER history: we used to point at `bin/python3.11` but uv creates that as a symlink chain (python3.11 -> python -> ~/pinokio/cache/.../uv/python/.../python3.11). Pinokio's info.exists() check returned false on that chain, so the menu rendered Install instead of Start even after a complete install — confirmed by cocktailpeanut. Use `pyvenv.cfg` instead: it's a tiny ASCII file uv writes to every venv root, never a symlink, never moves. `bin/activate` is the same kind of plain file; we keep it as a secondary check. The bin/python3.11 entries stay last as a final fallback for older installs.",+ "_comment": "Marker that the venv exists. SHIP-BLOCKER history: we used to point at `bin/python3.11` but uv creates that as a symlink chain (python3.11 -> python -> ~/pinokio/cache/.../uv/python/.../python3.11). Pinokio's info.exists() check returned false on that chain, so the menu rendered Install instead of Start even after a complete install \u2014 confirmed by cocktailpeanut. Use `pyvenv.cfg` instead: it's a tiny ASCII file uv writes to every venv root, never a symlink, never moves. `bin/activate` is the same kind of plain file; we keep it as a secondary check. The bin/python3.11 entries stay last as a final fallback for older installs.","marker_paths": ["ltx-2-mlx/env/pyvenv.cfg","ltx-2-mlx/.venv/pyvenv.cfg",@@ -146,6 +143,5 @@"ltx-2-mlx/.venv/bin/python3.11"]},-"min_size_bytes": 1024}diff --git a/scripts/STATS_DASHBOARD.md b/scripts/STATS_DASHBOARD.mdindex b8a9b59..282cf14 100644--- a/scripts/STATS_DASHBOARD.md+++ b/scripts/STATS_DASHBOARD.md@@ -2,7 +2,10 @@A tiny, stdlib-only pipeline that snapshots GitHub repo metrics into a localJSONL on the maintainer's Mac and serves a dashboard through the Phosphene-panel itself. Nothing public, no GitHub Pages, no telemetry, no cloud.+panel itself. Nothing public, no GitHub Pages, no cloud — this pipeline only+reads GitHub's API and uploads nothing. (Not to be confused with the panel's+anonymous usage analytics, which does send: see `docs/ANALYTICS.md`. The+dashboard's *Usage* section displays that data; it is not what collects it.)**Open the dashboard:** the Phosphene panel must be running, then visit**<http://127.0.0.1:8199/stats>**.diff --git a/scripts/build_gemma4_te_pack.py b/scripts/build_gemma4_te_pack.pynew file mode 100644index 0000000..35d1b4a--- /dev/null+++ b/scripts/build_gemma4_te_pack.py@@ -0,0 +1,239 @@+#!/usr/bin/env python3+"""Turn LTX-2.5's single-file Gemma-4 text encoder into a loadable MLX pack.++LTX-2.3's encoder was a stock, ungated ``gemma-3-12b-it-4bit`` repo: weights,+``config.json`` and ``tokenizer.json`` as ordinary sibling files. LTX-2.5 ships+one 26 GB safetensors instead, and puts three different kinds of thing inside+it:++ 1. the Gemma-4 text tower ``model.*``+ 2. the DiT's dual text projection ``text_embedding_projection.*``+ 3. the tokenizer and its config, **as U8 tensors**+ (``tokenizer_json``, ``hf_asset__*.json``, ``hf_asset__*.jinja``)++plus vision/audio decoys from the unified-multimodal packaging that the text+tower must never load.++Only (1) belongs in the encoder pack. (2) belongs beside the connector and is+routed there by ``convert_ltx_mlx.py`` — do not also write it here, or the+projection exists twice and the two copies can drift. (3) are not weights at+all: they are extracted to real files, because ``mlx_lm.tokenizer_utils.load``+reads a directory, and because a tokenizer smuggled through a weights dict+would reach ``load_weights`` and fail as a phantom parameter.++The architecture lives in the header's ``gemma_config`` metadata rather than a+sibling ``config.json``; this writes it out so the pack is readable by the+ordinary path.++Same three rules as the pack converter: never load the file, plan before+writing, and never drop a key silently — every dropped tensor is named on+stdout and counted in the summary.++Usage+-----+ python3 scripts/build_gemma4_te_pack.py \\+ --input mlx_models/_incoming_ltx25/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \\+ --output mlx_models/gemma4-12b-ltx25-bf16+"""++from __future__ import annotations++import argparse+import hashlib+import json+import os+import struct+import sys+import tempfile+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parent))++from convert_ltx_mlx import human, read_header, tensor_nbytes # noqa: E402++#: Kept, with keys verbatim. ``sanitize_weights`` strips the ``model.`` prefix.+TOWER_PREFIXES: tuple[str, ...] = ("model.",)++#: Dropped on purpose. These are the encoder-free multimodal packaging's other+#: towers; the text tower never allocates them. Named here rather than implied+#: by a fallthrough, so the summary can prove what left.+DECOY_PREFIXES: tuple[str, ...] = (+ "vision_model.",+ "vision_tower.",+ "audio_tower.",+ "audio_projector.",+ "multi_modal_projector.",+)++#: Belongs to the LTX pack's connector, written by convert_ltx_mlx.py.+ELSEWHERE_PREFIXES: tuple[str, ...] = ("text_embedding_projection.",)++#: U8 byte blobs that are files, not tensors: source key -> filename on disk.+ASSET_FILENAMES: dict[str, str] = {+ "tokenizer_json": "tokenizer.json",+ "hf_asset__tokenizer_config.json": "tokenizer_config.json",+ "hf_asset__generation_config.json": "generation_config.json",+ "hf_asset__processor_config.json": "processor_config.json",+ "hf_asset__chat_template.jinja": "chat_template.jinja",+}++_CHUNK = 8 * 1024 * 1024+++def asset_filename(key: str) -> str | None:+ if key in ASSET_FILENAMES:+ return ASSET_FILENAMES[key]+ if key.startswith("hf_asset__"):+ return key[len("hf_asset__") :]+ return None+++def classify(key: str) -> str:+ if asset_filename(key) is not None:+ return "asset"+ if key.startswith(ELSEWHERE_PREFIXES):+ return "elsewhere"+ if key.startswith(DECOY_PREFIXES):+ return "decoy"+ if key.startswith(TOWER_PREFIXES):+ return "tower"+ return "unknown"+++def build(input_path: Path, out_dir: Path, *, dry_run: bool = False) -> dict:+ header, data_offset = read_header(input_path)+ metadata = header.get("__metadata__") or {}++ buckets: dict[str, list[str]] = {"tower": [], "asset": [], "decoy": [], "elsewhere": [], "unknown": []}+ for key in header:+ if key == "__metadata__":+ continue+ buckets[classify(key)].append(key)++ if buckets["unknown"]:+ preview = "\n ".join(sorted(buckets["unknown"])[:20])+ raise SystemExit(+ f"error: {len(buckets['unknown'])} tensors match no known category:\n {preview}\n\n"+ "Refusing to guess. Add them to TOWER_PREFIXES, DECOY_PREFIXES or "+ "ASSET_FILENAMES — an unclassified tensor is either a parameter that "+ "would go missing or a phantom that would break a strict load."+ )++ tower = sorted(buckets["tower"])+ planned = sum(tensor_nbytes(header[k]) for k in tower)++ report = {+ "tower_tensors": len(tower),+ "tower_bytes": planned,+ "assets": {k: asset_filename(k) for k in sorted(buckets["asset"])},+ "dropped_decoys": sorted(buckets["decoy"]),+ "written_elsewhere": sorted(buckets["elsewhere"]),+ "files": [],+ }+ if dry_run:+ return report++ out_dir.mkdir(parents=True, exist_ok=True)++ # --- config.json, from the header's own metadata -----------------------+ raw_config = metadata.get("gemma_config") or metadata.get("config")+ if not raw_config:+ raise SystemExit("error: the encoder header carries no gemma_config; cannot write config.json")+ config = json.loads(raw_config) if isinstance(raw_config, str) else dict(raw_config)+ (out_dir / "config.json").write_text(json.dumps(config, indent=2, sort_keys=True))+ report["files"].append("config.json")++ # --- assets: byte blobs out to real files ------------------------------+ with open(input_path, "rb") as fh:+ for key in sorted(buckets["asset"]):+ name = asset_filename(key)+ begin, end = header[key]["data_offsets"]+ fh.seek(data_offset + begin)+ (out_dir / name).write_bytes(fh.read(end - begin))+ report["files"].append(name)+ print(f" asset {name} {human(end - begin)}")++ # --- the tower, streamed ----------------------------------------------+ out_header: dict = {}+ cursor = 0+ for key in tower:+ entry = header[key]+ nbytes = tensor_nbytes(entry)+ out_header[key] = {"dtype": entry["dtype"], "shape": entry["shape"], "data_offsets": [cursor, cursor + nbytes]}+ cursor += nbytes+ quant = config.get("quantization")+ if quant:+ out_header["__metadata__"] = {"quantization": json.dumps(quant)}++ blob = json.dumps(out_header, separators=(",", ":")).encode()+ blob += b" " * ((-len(blob)) % 8)++ target = out_dir / "model.safetensors"+ digest = hashlib.sha256()+ written = 0+ fd, tmp = tempfile.mkstemp(prefix=".model.", suffix=".partial", dir=str(out_dir))+ try:+ with os.fdopen(fd, "wb") as out, open(input_path, "rb") as src:+ out.write(struct.pack("<Q", len(blob)))+ out.write(blob)+ digest.update(struct.pack("<Q", len(blob)))+ digest.update(blob)+ for i, key in enumerate(tower):+ begin, end = header[key]["data_offsets"]+ src.seek(data_offset + begin)+ remaining = end - begin+ while remaining:+ chunk = src.read(min(_CHUNK, remaining))+ if not chunk:+ raise IOError(f"{input_path.name}: truncated reading {key}")+ out.write(chunk)+ digest.update(chunk)+ written += len(chunk)+ remaining -= len(chunk)+ if i % 100 == 0:+ print(f" [{i + 1}/{len(tower)}] {human(written)}", flush=True)+ out.flush()+ os.fsync(out.fileno())+ if written != planned:+ raise IOError(f"wrote {written} bytes, planned {planned}")+ os.replace(tmp, target)+ except BaseException:+ try:+ os.unlink(tmp)+ except OSError:+ pass+ raise++ report["files"].append("model.safetensors")+ report["sha256"] = digest.hexdigest()+ report["bytes"] = target.stat().st_size+ (out_dir / "te_pack_manifest.json").write_text(json.dumps(report, indent=2))+ return report+++def main(argv=None) -> int:+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ ap.add_argument("--input", required=True, type=Path)+ ap.add_argument("--output", required=True, type=Path)+ ap.add_argument("--dry-run", action="store_true")+ args = ap.parse_args(argv)++ if not args.input.exists():+ print(f"error: {args.input} does not exist", file=sys.stderr)+ return 2++ report = build(args.input, args.output, dry_run=args.dry_run)++ print()+ print(f"tower {report['tower_tensors']:5d} tensors {human(report['tower_bytes'])}")+ print(f"assets {len(report['assets']):5d} files -> {', '.join(sorted(report['assets'].values()))}")+ print(f"dropped decoys {len(report['dropped_decoys']):5d} tensors {', '.join(report['dropped_decoys'][:4])}"+ f"{' ...' if len(report['dropped_decoys']) > 4 else ''}")+ print(f"written elsewhere{len(report['written_elsewhere']):5d} tensors (connector, by convert_ltx_mlx.py)")+ if args.dry_run:+ print("\n(dry run — nothing written)")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/scripts/convert_ltx_mlx.py b/scripts/convert_ltx_mlx.pynew file mode 100644index 0000000..23bab8c--- /dev/null+++ b/scripts/convert_ltx_mlx.py@@ -0,0 +1,857 @@+#!/usr/bin/env python3+"""Convert an official LTX safetensors release into the MLX pack layout.++This is the missing link between "the bf16 weights finished downloading" and+`scripts/quantize_ltx.py`. Keep the boundary sharp, because conflating the two+is how packs get silently wrong:++ convert_ltx_mlx.py changes KEY NAMES and FILE LAYOUT. Never numbers.+ quantize_ltx.py changes NUMBERS. Never key names.++Input is whichever shape the vendor shipped:++ * a **monolithic** checkpoint — the whole model in one file under+ ``model.diffusion_model.*`` (the ComfyUI single-file layout), or+ * a set of **already-split** component files (the Diffusers-style repo).++Output is the flat, one-file-per-component pack the vendored loader consumes,+because that layout — not any tidier scheme — is the compatibility contract:++ transformer-distilled.safetensors keys prefixed ``transformer.``+ connector.safetensors keys prefixed ``connector.``+ vae_encoder.safetensors ``vae_encoder.``+ vae_decoder.safetensors ``vae_decoder.``+ audio_vae.safetensors ``audio_vae.``+ vocoder.safetensors ``vocoder.``+ duration_head.safetensors ``duration_head.`` (2.5, optional)+ config.json / embedded_config.json / split_model.json+ manifest.json sha256 + size for every file written++Three properties this script treats as non-negotiable, each bought with real+scar tissue:++**It never loads the file.** A 42 GB transformer is streamed tensor by tensor+through a bounded buffer. Peak RSS is one tensor, not one checkpoint — the+same discipline that lets `quantize_ltx.py` run in 1.6 GB.++**It plans before it writes.** The source header (8-byte LE length + JSON) is+parsed first, so every output tensor's name, dtype, shape and byte count is+known in closed form before a single weight byte moves. That gives an exact+disk preflight, a header that can be written first, and a final+``wrote N bytes, planned M`` assertion that makes a truncated pack impossible+to publish.++**An unmapped key is an ERROR, not a skip.** The June 2026 "mosaic" was one+missing 1 GB upscaler producing a randomly-initialised module and a rainbow+grid — chased for two weeks through three wrong theories. A converter that+quietly drops a key it does not recognise recreates that failure exactly. So+anything unrouted or unrenamed aborts the run and names itself. ``--allow-+unmapped`` exists for exploration and is refused for a real conversion unless+paired with ``--i-know-what-im-dropping``.++Usage+-----+ # the whole 2.5 pack in ONE run — every input is planned together, so a+ # component fed by two files (the connector: blocks from the DiT, text+ # projection from the encoder) is written once, complete.+ python3 scripts/convert_ltx_mlx.py \\+ --input ~/dl/ltx-2.5-22b-distilled-transformer-bf16.safetensors \\+ --input ~/dl/ltx-2.5-video-vae-conv-bf16.safetensors \\+ --input ~/dl/ltx-2.5-audio-vae-bf16.safetensors \\+ --input ~/dl/ltx-2.5-duration-head-bf16.safetensors \\+ --input ~/dl/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors=spatial_upscaler_x2_v1_1 \\+ --output mlx_models/ltx-2.5-mlx-bf16 \\+ --transformer-stem transformer-distilled++ # see the routing decision without writing anything+ python3 scripts/convert_ltx_mlx.py --input X.safetensors --output OUT --dry-run++Run it in one invocation, not several: separate runs would each rewrite+``connector.safetensors`` from scratch and the last one would win.+"""++from __future__ import annotations++import argparse+import hashlib+import json+import os+import struct+import sys+import tempfile+from dataclasses import dataclass, field+from pathlib import Path++# ---------------------------------------------------------------------------+# safetensors header primitives — deliberately dependency-free.+#+# `mx.load` would pull the whole file into memory, and `safetensors.safe_open`+# is not guaranteed present in the Pinokio venv. The format is small enough to+# own: 8-byte little-endian header length, then that many bytes of JSON, then+# a contiguous data blob addressed by per-tensor [begin, end) byte offsets.+# ---------------------------------------------------------------------------++DTYPE_SIZES = {+ "BOOL": 1, "U8": 1, "I8": 1, "F8_E4M3": 1, "F8_E5M2": 1,+ "U16": 2, "I16": 2, "F16": 2, "BF16": 2,+ "U32": 4, "I32": 4, "F32": 4,+ "U64": 8, "I64": 8, "F64": 8,+}+++def read_header(path: Path) -> tuple[dict, int]:+ """Return ``(header_dict, data_offset)`` for a safetensors file."""+ with open(path, "rb") as fh:+ raw_len = fh.read(8)+ if len(raw_len) != 8:+ raise ValueError(f"{path}: too short to be safetensors")+ (header_len,) = struct.unpack("<Q", raw_len)+ header = json.loads(fh.read(header_len))+ return header, 8 + header_len+++def tensor_nbytes(entry: dict) -> int:+ size = DTYPE_SIZES.get(entry["dtype"])+ if size is None:+ raise ValueError(f"unknown safetensors dtype {entry['dtype']!r}")+ n = size+ for dim in entry["shape"]:+ n *= dim+ return n+++# ---------------------------------------------------------------------------+# Key renaming+#+# These rules are not invented here — they mirror ``LTXV_LORA_COMFY_RENAMING_MAP``+# in the vendored ltx-core-mlx loader, which is the rename table the library+# already trusts for ComfyUI-shaped LTX weights. Reusing it means a LoRA and a+# base checkpoint cannot disagree about what a layer is called.+# ---------------------------------------------------------------------------++RENAME_RULES: tuple[tuple[str, str], ...] = (+ (".to_out.0.", ".to_out."),+ (".ff.net.0.proj.", ".ff.proj_in."),+ (".ff.net.2.", ".ff.proj_out."),+ (".audio_ff.net.0.proj.", ".audio_ff.proj_in."),+ (".audio_ff.net.2.", ".audio_ff.proj_out."),+ (".linear_1.", ".linear1."),+ (".linear_2.", ".linear2."),+)++# Per-channel latent statistics are spelled three different ways by three+# different consumers, and the SAME two source tensors feed all of them. The+# video VAE ships one copy that both the encoder and the decoder need, under+# leaf names that differ between the two. Getting this wrong does not raise —+# it denormalises latents with random stats and yields plausible-looking mush.+_STATS_ENCODER = (("mean-of-means", "_mean_of_means"), ("std-of-means", "_std_of_means"))+_STATS_DECODER = (("mean-of-means", "mean"), ("std-of-means", "std"))+++# Source-key prefixes that identify a component. Longest prefix wins; when+# several routes share that longest prefix, ALL of them fire — that is how one+# source tensor fans out into two components.+@dataclass(frozen=True)+class Route:+ source_prefix: str+ stem: str+ target_prefix: str+ rename: bool = True+ """Apply RENAME_RULES. False for components whose on-disk contract keeps the+ PyTorch spelling — the embeddings connector is the one that matters: its+ attention output stays list-wrapped (``to_out.0.*``) and its feed-forward+ stays ``ff.net.0.proj`` / ``ff.net.2``, because the vendored+ ``ConnectorAttention`` builds exactly those names. Renaming them the way the+ DiT blocks are renamed produces a connector that cannot load."""+ leaf_map: tuple[tuple[str, str], ...] = ()+ """Exact trailing-segment substitutions applied after prefixing."""+++DEFAULT_ROUTES: tuple[Route, ...] = (+ Route("model.diffusion_model.duration_head.", "duration_head", "duration_head."),+ Route("duration_head.", "duration_head", "duration_head."),+ # The 2.5 DiT packs both connectors in-file; 2.3 shipped them as a separate+ # connector.safetensors. Either way they land in connector.safetensors, and+ # neither is subject to the DiT rename rules.+ Route(+ "model.diffusion_model.video_embeddings_connector.",+ "connector",+ "connector.video_embeddings_connector.",+ rename=False,+ ),+ Route(+ "model.diffusion_model.audio_embeddings_connector.",+ "connector",+ "connector.audio_embeddings_connector.",+ rename=False,+ ),+ # 2.5 relocated the dual text projection out of the connector and into the+ # text-encoder file. Our pack layout still wants it beside the connector,+ # because that is where GemmaFeatureExtractor looks for it.+ Route("text_embedding_projection.", "connector", "connector.text_embedding_projection.", rename=False),+ Route("connector.", "connector", "connector.", rename=False),+ Route("vae.encoder.", "vae_encoder", "vae_encoder."),+ Route("vae.decoder.", "vae_decoder", "vae_decoder."),+ Route("vae_encoder.", "vae_encoder", "vae_encoder."),+ Route("vae_decoder.", "vae_decoder", "vae_decoder."),+ # One source copy, two destinations, different leaf names in each.+ Route(+ "per_channel_statistics.",+ "vae_encoder",+ "vae_encoder.per_channel_statistics.",+ leaf_map=_STATS_ENCODER,+ ),+ Route(+ "per_channel_statistics.",+ "vae_decoder",+ "vae_decoder.per_channel_statistics.",+ leaf_map=_STATS_DECODER,+ ),+ Route("encoder.", "vae_encoder", "vae_encoder."),+ Route("decoder.", "vae_decoder", "vae_decoder."),+ Route(+ "audio_vae.per_channel_statistics.",+ "audio_vae",+ "audio_vae.per_channel_statistics.",+ leaf_map=_STATS_ENCODER,+ ),+ Route("audio_vae.", "audio_vae", "audio_vae."),+ # 2.5 nests the base vocoder one level deeper than 2.3 did; bwe_generator+ # and mel_stft sit at the top level in both. Collapse only the doubled+ # segment, and let the shorter route carry the other two through.+ Route("vocoder.vocoder.", "vocoder", "vocoder."),+ Route("vocoder.", "vocoder", "vocoder."),+ Route("model.diffusion_model.", "transformer", "transformer."),+ Route("diffusion_model.", "transformer", "transformer."),+ Route("transformer.", "transformer", "transformer."),+)+++# ---------------------------------------------------------------------------+# Convolution layout+#+# MLX puts the input-channel axis LAST; PyTorch puts it second. Every LTX+# release before 2.5 reached us already permuted, because `mlx-forge` did it+# during conversion — which is why the vendored package says flatly that all+# weights must be in MLX format on disk and that a PyTorch-format tensor is a+# converter bug, not something to work around at load time. 2.5 is the first+# checkpoint we convert ourselves, so the permutation has to live here.+#+# The DiT and the connector are pure Linear (rank <= 2) and are untouched;+# every affected tensor is in the VAEs, the vocoder and the upscalers. The+# table below is not inferred from module names — it was derived by diffing+# every shared key of the freshly converted 2.5 pack against the shipped 2.3+# pack, which is ground truth for MLX layout. All 768 differing tensors are+# explained by exactly four permutations, with no exceptions and no leftovers.+# ---------------------------------------------------------------------------++CONV_PERMUTATIONS: dict[int, tuple[int, ...]] = {+ 3: (0, 2, 1), # Conv1d (O, I, K) -> (O, K, I)+ 4: (0, 2, 3, 1), # Conv2d (O, I, H, W) -> (O, H, W, I)+ 5: (0, 2, 3, 4, 1), # Conv3d (O, I, D, H, W) -> (O, D, H, W, I)+}++#: ConvTranspose1d stores (I, O, K) and needs (O, K, I) — a different rank-3+#: permutation from Conv1d's. In the LTX vocoder these are exactly the+#: upsampling stacks: 11 tensors, all ``*.ups.<n>.weight``, and no Conv1d+#: weight anywhere in the pack matches that pattern.+CONV_TRANSPOSE_1D_PERM: tuple[int, ...] = (1, 2, 0)+_CONV_TRANSPOSE_MARKER = ".ups."+++def conv_permutation(key: str, shape: list) -> tuple[int, ...] | None:+ """The axis permutation this tensor needs, or ``None`` to copy verbatim.++ Rank alone decides. Restricting this to ``*.weight`` looks safer and is+ wrong: the vocoder's anti-aliasing resamplers carry their kernels as+ ``*.filter`` buffers, 402 of them, in the very same channel layout as a+ Conv1d weight. In the 2.3 pack — ground truth — **every** tensor of rank 3,+ 4 or 5 is permuted and none is left alone, so a name-based predicate can+ only ever be a way to miss some.+ """+ if len(shape) not in CONV_PERMUTATIONS:+ return None+ if len(shape) == 3 and _CONV_TRANSPOSE_MARKER in key:+ return CONV_TRANSPOSE_1D_PERM+ return CONV_PERMUTATIONS[len(shape)]+++def permuted_shape(shape: list, perm: tuple[int, ...]) -> list:+ return [shape[i] for i in perm]+++def permute_bytes(raw: bytes, shape: list, perm: tuple[int, ...], itemsize: int) -> bytes:+ """Reorder axes without interpreting the element type.++ Views the payload as raw bytes with a trailing element axis, so bf16 —+ which numpy has no native dtype for — permutes exactly like anything else.+ A permutation moves numbers; it never changes one.+ """+ import numpy as np++ arr = np.frombuffer(raw, dtype=np.uint8).reshape(*shape, itemsize)+ return np.ascontiguousarray(arr.transpose(*perm, len(shape))).tobytes()+++def rename_key(key: str) -> str:+ for old, new in RENAME_RULES:+ key = key.replace(old, new)+ return key+++def apply_leaf_map(key: str, leaf_map: tuple[tuple[str, str], ...]) -> str:+ for old, new in leaf_map:+ if key.endswith(old):+ return key[: -len(old)] + new+ return key+++def route_key(key: str, routes: tuple[Route, ...]) -> list[Route]:+ """Longest-prefix match, returning EVERY route that ties for longest.++ Returns an empty list when nothing claims the key. Ties are meaningful:+ two routes sharing a source prefix duplicate one source tensor into two+ output components (the video VAE's per-channel statistics need exactly+ that, under a different leaf name in each).+ """+ best = -1+ winners: list[Route] = []+ for route in routes:+ if key.startswith(route.source_prefix):+ length = len(route.source_prefix)+ if length > best:+ best, winners = length, [route]+ elif length == best:+ winners.append(route)+ return winners+++# ---------------------------------------------------------------------------+# Planning+# ---------------------------------------------------------------------------+++@dataclass+class PlannedTensor:+ target_key: str+ source_key: str+ source_path: Path+ source_begin: int+ source_end: int+ dtype: str+ shape: list+ permute: tuple = ()+ """Axis permutation from the source's layout to MLX's. Empty = verbatim."""++ @property+ def nbytes(self) -> int:+ # A permutation reorders bytes; it never adds or removes any.+ return self.source_end - self.source_begin++ @property+ def target_shape(self) -> list:+ return permuted_shape(self.shape, self.permute) if self.permute else self.shape+++@dataclass+class ComponentPlan:+ stem: str+ tensors: list[PlannedTensor] = field(default_factory=list)+ metadata: dict = field(default_factory=dict)++ @property+ def nbytes(self) -> int:+ return sum(t.nbytes for t in self.tensors)+++class UnmappedKeys(RuntimeError):+ """Raised when the converter cannot account for every source tensor."""+++def plan_conversion(+ inputs: list[Path] | list[tuple[Path, str | None]],+ routes: tuple[Route, ...] = DEFAULT_ROUTES,+ *,+ transformer_stem: str = "transformer",+ allow_unmapped: bool = False,+) -> tuple[dict[str, ComponentPlan], list[str], dict]:+ """Decide every output byte before reading a single weight.++ Each input is either a path (routed by key prefix) or a ``(path, stem)``+ pair. An explicit stem is a **fallback for keys the route table does not+ claim**, not an override: routed keys still go where the table says.++ That fallback is what makes two otherwise-impossible files convertible.+ The latent upscalers ship bare, unprefixed keys (``final_conv.*``,+ ``res_blocks.*``) that are byte-identical between the spatial and the+ temporal file — nothing in the key can say which component it is, only the+ filename can. And the text encoder ships the DiT's text projection+ (``text_embedding_projection.*``, which belongs in the connector) sitting+ beside a 26 GB Gemma tower (which does not belong in this pack at all);+ because the fallback yields to the route table, one pass puts each where it+ goes.++ Returns ``(plans_by_stem, unmapped_source_keys, source_metadata)``.+ """+ plans: dict[str, ComponentPlan] = {}+ unmapped: list[str] = []+ merged_metadata: dict = {}++ normalised: list[tuple[Path, str | None]] = [+ item if isinstance(item, tuple) else (item, None) for item in inputs+ ]++ for path, forced_stem in normalised:+ header, data_offset = read_header(path)+ metadata = header.get("__metadata__") or {}+ for key, value in metadata.items():+ merged_metadata.setdefault(key, value)++ for key, entry in header.items():+ if key == "__metadata__":+ continue+ matches = route_key(key, 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 be+ # a guess. Verified correct for the upscalers, whose 2.5 keys+ # are identical to the 2.3 pack's once the stem prefix is added.+ matches = [Route("", forced_stem, f"{forced_stem}.", rename=False)]+ if not matches:+ unmapped.append(f"{path.name}::{key}")+ continue++ expected = tensor_nbytes(entry)+ begin, end = entry["data_offsets"]+ actual = end - begin+ if expected != actual:+ raise ValueError(+ f"{path.name}::{key} header is self-inconsistent: "+ f"{entry['dtype']}{entry['shape']} needs {expected} bytes, "+ f"offsets span {actual}. Refusing to convert a corrupt file."+ )++ for route in matches:+ stem = transformer_stem if route.stem == "transformer" else route.stem+ suffix = key[len(route.source_prefix) :]+ target_key = route.target_prefix + suffix+ if route.rename:+ target_key = rename_key(target_key)+ target_key = apply_leaf_map(target_key, route.leaf_map)++ plan = plans.setdefault(stem, ComponentPlan(stem=stem))+ if not plan.metadata and metadata:+ # Which file a component came from decides its config. The+ # upscalers each carry their own and they are NOT the same+ # shape as each other, so a single merged blob cannot serve+ # them: the spatial one is mid_channels 1024, the temporal+ # 512, and building either at the other's width fails to+ # load with a shape error that names no cause.+ plan.metadata = dict(metadata)+ plan.tensors.append(+ PlannedTensor(+ target_key=target_key,+ source_key=key,+ source_path=path,+ source_begin=data_offset + begin,+ source_end=data_offset + end,+ dtype=entry["dtype"],+ shape=list(entry["shape"]),+ permute=conv_permutation(target_key, list(entry["shape"])) or (),+ )+ )++ if unmapped and not allow_unmapped:+ preview = "\n ".join(unmapped[:20])+ more = f"\n ... and {len(unmapped) - 20} more" if len(unmapped) > 20 else ""+ raise UnmappedKeys(+ f"{len(unmapped)} source tensors matched no output component:\n "+ f"{preview}{more}\n\n"+ "Dropping them would produce a pack that LOADS and renders garbage — "+ "that is the June 2026 mosaic, exactly. Add a Route for these keys, "+ "or re-run with --allow-unmapped --i-know-what-im-dropping if you "+ "genuinely mean to discard them."+ )++ for plan in plans.values():+ plan.tensors.sort(key=lambda t: t.target_key)++ return plans, unmapped, merged_metadata+++def duplicate_target_keys(plan: ComponentPlan) -> list[str]:+ seen: dict[str, int] = {}+ for tensor in plan.tensors:+ seen[tensor.target_key] = seen.get(tensor.target_key, 0) + 1+ return sorted(k for k, n in seen.items() if n > 1)+++# ---------------------------------------------------------------------------+# Writing+# ---------------------------------------------------------------------------++_COPY_CHUNK = 8 * 1024 * 1024+++def write_component(+ plan: ComponentPlan,+ out_dir: Path,+ *,+ metadata: dict | None = None,+ chunk_size: int = _COPY_CHUNK,+) -> tuple[Path, str, int]:+ """Stream one component to disk atomically. Returns (path, sha256, size).++ Written to a temp file in the destination directory and ``os.replace``d+ into position, so a killed run never leaves a half-written pack that a+ later verify would happily checksum.+ """+ dupes = duplicate_target_keys(plan)+ if dupes:+ raise ValueError(+ f"{plan.stem}: {len(dupes)} target keys collide, e.g. {dupes[:5]}. "+ "Two source tensors renamed onto the same name — one would silently "+ "overwrite the other."+ )++ header: dict = {}+ cursor = 0+ for tensor in plan.tensors:+ header[tensor.target_key] = {+ "dtype": tensor.dtype,+ "shape": tensor.target_shape,+ "data_offsets": [cursor, cursor + tensor.nbytes],+ }+ cursor += tensor.nbytes+ if metadata:+ header["__metadata__"] = {k: str(v) for k, v in metadata.items()}++ header_bytes = json.dumps(header, separators=(",", ":")).encode()+ # safetensors requires the data blob to start 8-byte aligned.+ pad = (-len(header_bytes)) % 8+ header_bytes += b" " * pad++ out_dir.mkdir(parents=True, exist_ok=True)+ target = out_dir / f"{plan.stem}.safetensors"+ digest = hashlib.sha256()+ written = 0++ fd, tmp_path = tempfile.mkstemp(prefix=f".{plan.stem}.", suffix=".partial", dir=str(out_dir))+ try:+ with os.fdopen(fd, "wb") as out:+ out.write(struct.pack("<Q", len(header_bytes)))+ out.write(header_bytes)+ digest.update(struct.pack("<Q", len(header_bytes)))+ digest.update(header_bytes)++ # Group by source file so each is opened once, in offset order.+ by_source: dict[Path, list[PlannedTensor]] = {}+ for tensor in plan.tensors:+ by_source.setdefault(tensor.source_path, []).append(tensor)++ # Emission order must match the header, so walk the planned order+ # and seek — sequential within a file in practice, because the+ # vendor writes tensors in roughly the same order we sort them.+ handles = {path: open(path, "rb") for path in by_source}+ try:+ for tensor in plan.tensors:+ fh = handles[tensor.source_path]+ fh.seek(tensor.source_begin)+ if tensor.permute:+ # Bounded: the largest permuted tensor in the 2.5 pack+ # is the spatial upscaler's 75 MB Conv2d. Still one+ # tensor resident, never one checkpoint.+ raw = fh.read(tensor.nbytes)+ if len(raw) != tensor.nbytes:+ raise IOError(+ f"{tensor.source_path.name}: truncated reading {tensor.source_key}"+ )+ itemsize = DTYPE_SIZES[tensor.dtype]+ buf = permute_bytes(raw, tensor.shape, tensor.permute, itemsize)+ if len(buf) != tensor.nbytes:+ raise IOError(+ f"{tensor.target_key}: permutation changed the byte count "+ f"({len(buf)} vs {tensor.nbytes})"+ )+ out.write(buf)+ digest.update(buf)+ written += len(buf)+ del raw, buf+ continue+ remaining = tensor.nbytes+ while remaining:+ chunk = fh.read(min(chunk_size, remaining))+ if not chunk:+ raise IOError(+ f"{tensor.source_path.name}: truncated while reading "+ f"{tensor.source_key} ({remaining} bytes short)"+ )+ out.write(chunk)+ digest.update(chunk)+ written += len(chunk)+ remaining -= len(chunk)+ finally:+ for fh in handles.values():+ fh.close()++ out.flush()+ os.fsync(out.fileno())++ if written != plan.nbytes:+ raise IOError(f"{plan.stem}: wrote {written} bytes, planned {plan.nbytes}")+ os.replace(tmp_path, target)+ except BaseException:+ try:+ os.unlink(tmp_path)+ except OSError:+ pass+ raise++ return target, digest.hexdigest(), target.stat().st_size+++def write_json_sidecars(out_dir: Path, metadata: dict, plans: dict[str, ComponentPlan]) -> list[Path]:+ """Emit the JSON files the vendored loader looks for beside the weights.++ 2.5 carries its architecture in the safetensors ``__metadata__``; the+ vendored ``LTXModelConfig.from_checkpoint_dir`` reads ``config.json`` /+ ``embedded_config.json``. Materialising both from the header keeps a 2.5+ pack readable by code that predates header-config support.+ """+ written: list[Path] = []++ def parse(raw):+ if not raw:+ return {}+ try:+ return json.loads(raw) if isinstance(raw, str) else dict(raw)+ except (json.JSONDecodeError, TypeError):+ return {}++ config = parse(metadata.get("config"))+ if "model_version" in metadata and "model_version" not in config:+ config["model_version"] = metadata["model_version"]++ # embedded_config.json is the UNION of every component's own config, keyed+ # by the section names the components already use ("transformer", "vae",+ # "audio_vae", "vocoder", "scheduler") — the same shape the 2.3 pack ships.+ # 2.5 splits that blob across the component files; reassembling it here is+ # what keeps a 2.5 pack readable by the ordinary config path.+ embedded = dict(config)+ for plan in plans.values():+ for key, value in parse(plan.metadata.get("config")).items():+ embedded.setdefault(key, value)++ if config:+ (out_dir / "config.json").write_text(json.dumps(config, indent=2))+ written.append(out_dir / "config.json")+ if embedded:+ (out_dir / "embedded_config.json").write_text(json.dumps(embedded, indent=2))+ written.append(out_dir / "embedded_config.json")++ # Per-component sidecar for anything the pipeline builds from a+ # "<stem>_config.json" beside the weights. Today that is the latent+ # upscalers, and the file itself says so via _class_name — so this keys off+ # the checkpoint's own declaration rather than off a filename convention.+ for stem, plan in sorted(plans.items()):+ own = parse(plan.metadata.get("config"))+ if own.get("_class_name") != "LatentUpsampler":+ continue+ path = out_dir / f"{stem}_config.json"+ path.write_text(json.dumps({"config": own}, indent=2))+ written.append(path)++ split = {+ "components": sorted(plans),+ "quantized": False,+ "quantization_bits": None,+ "model_version": config.get("model_version"),+ }+ path = out_dir / "split_model.json"+ path.write_text(json.dumps(split, indent=2))+ written.append(path)+ return written+++def write_manifest(out_dir: Path, entries: list[dict]) -> Path:+ path = out_dir / "manifest.json"+ path.write_text(json.dumps({"files": entries}, indent=2))+ return path+++def sha256_file(path: Path, chunk_size: int = _COPY_CHUNK) -> str:+ digest = hashlib.sha256()+ with open(path, "rb") as fh:+ while chunk := fh.read(chunk_size):+ digest.update(chunk)+ return digest.hexdigest()+++# ---------------------------------------------------------------------------+# CLI+# ---------------------------------------------------------------------------+++def human(n: int) -> str:+ for unit in ("B", "KiB", "MiB", "GiB", "TiB"):+ if abs(n) < 1024 or unit == "TiB":+ return f"{n:.2f} {unit}" if unit != "B" else f"{n} B"+ n /= 1024.0+ return f"{n}"+++def parse_input_spec(raw: str) -> tuple[Path, str | None]:+ """``PATH`` or ``PATH=STEM``.++ The stem form pins a whole file to one output component. Split on the last+ ``=`` only when the right-hand side looks like a stem rather than part of a+ path, so a directory containing ``=`` still works.+ """+ if "=" in raw:+ head, _, tail = raw.rpartition("=")+ if head and tail and "/" not in tail and not tail.endswith(".safetensors"):+ return Path(head), tail+ return Path(raw), None+++def convert(+ inputs: list[tuple[Path, str | None]],+ out_dir: Path,+ *,+ transformer_stem: str = "transformer",+ allow_unmapped: bool = False,+ dry_run: bool = False,+ skip_stems: tuple[str, ...] = (),+) -> dict:+ plans, unmapped, metadata = plan_conversion(+ inputs, transformer_stem=transformer_stem, allow_unmapped=allow_unmapped+ )++ # A skipped stem is PLANNED and reported, then not written — for components+ # another tool owns. That is categorically different from --allow-unmapped:+ # the keys are still accounted for by name, so nothing can go missing+ # unnoticed. It exists because the text encoder's Gemma tower travels in the+ # same file as the connector's text projection but belongs in its own pack.+ skipped = {stem: plans.pop(stem) for stem in skip_stems if stem in plans}++ total = sum(plan.nbytes for plan in plans.values())+ report = {+ "components": {+ stem: {+ "tensors": len(p.tensors),+ "bytes": p.nbytes,+ "permuted": sum(1 for t in p.tensors if t.permute),+ }+ for stem, p in sorted(plans.items())+ },+ "skipped": {stem: {"tensors": len(p.tensors), "bytes": p.nbytes} for stem, p in sorted(skipped.items())},+ "total_bytes": total,+ "unmapped": unmapped,+ "metadata_keys": sorted(metadata),+ "files": [],+ }++ if dry_run:+ return report++ free = os.statvfs(out_dir if out_dir.exists() else out_dir.parent)+ available = free.f_bavail * free.f_frsize+ if available < total * 1.02:+ raise IOError(+ f"not enough space in {out_dir}: need ~{human(int(total * 1.02))}, "+ f"have {human(available)}"+ )++ entries = []+ for stem, plan in sorted(plans.items()):+ component_metadata = metadata if stem == transformer_stem else None+ path, digest, size = write_component(plan, out_dir, metadata=component_metadata)+ entries.append({"file": path.name, "sha256": digest, "bytes": size, "tensors": len(plan.tensors)})+ print(f" wrote {path.name} {len(plan.tensors)} tensors {human(size)}")++ for path in write_json_sidecars(out_dir, metadata, plans):+ entries.append({"file": path.name, "sha256": sha256_file(path), "bytes": path.stat().st_size})++ write_manifest(out_dir, entries)+ report["files"] = entries+ return report+++def main(argv=None) -> int:+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ parser.add_argument(+ "--input",+ action="append",+ required=True,+ help="source safetensors, repeatable. Use PATH=STEM to pin a whole file "+ "to one output component (needed for the latent upscalers, whose keys "+ "carry no component name).",+ )+ parser.add_argument("--output", required=True, type=Path, help="destination pack directory")+ parser.add_argument(+ "--transformer-stem",+ default="transformer-distilled",+ help="output filename stem for the DiT (default: transformer-distilled; "+ "use transformer-dev for the full/trainable checkpoint)",+ )+ parser.add_argument("--dry-run", action="store_true", help="plan and report, write nothing")+ parser.add_argument(+ "--skip-stem",+ action="append",+ default=[],+ help="plan and report this component but do not write it (repeatable). "+ "For components another tool owns — unlike --allow-unmapped, the keys "+ "are still named in the report, so nothing vanishes unnoticed.",+ )+ parser.add_argument("--allow-unmapped", action="store_true", help="do not abort on unroutable keys")+ parser.add_argument(+ "--i-know-what-im-dropping",+ action="store_true",+ help="required alongside --allow-unmapped for a real (non-dry-run) conversion",+ )+ args = parser.parse_args(argv)++ specs = [parse_input_spec(raw) for raw in args.input]+ for path, _ in specs:+ if not path.exists():+ print(f"error: {path} does not exist", file=sys.stderr)+ return 2++ if args.allow_unmapped and not args.dry_run and not args.i_know_what_im_dropping:+ print(+ "error: --allow-unmapped on a real conversion also needs "+ "--i-know-what-im-dropping. Silently discarded weights are the "+ "single most expensive class of bug in this project's history.",+ file=sys.stderr,+ )+ return 2++ try:+ report = convert(+ specs,+ args.output,+ transformer_stem=args.transformer_stem,+ allow_unmapped=args.allow_unmapped,+ dry_run=args.dry_run,+ skip_stems=tuple(args.skip_stem),+ )+ except UnmappedKeys as exc:+ print(f"error: {exc}", file=sys.stderr)+ return 3++ print()+ for stem, info in report["components"].items():+ perm = f" ({info['permuted']} conv-permuted)" if info.get("permuted") else ""+ print(f"{stem:34s} {info['tensors']:6d} tensors {human(info['bytes'])}{perm}")+ print(f"{'TOTAL':34s} {'':6s} {human(report['total_bytes'])}")+ for stem, info in report.get("skipped", {}).items():+ print(f"{'(skipped) ' + stem:34s} {info['tensors']:6d} tensors {human(info['bytes'])}")+ if report["unmapped"]:+ print(f"\nWARNING: {len(report['unmapped'])} unmapped source tensors were dropped.", file=sys.stderr)+ if args.dry_run:+ print("\n(dry run — nothing written)")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/scripts/fetch_pack_release.py b/scripts/fetch_pack_release.pynew file mode 100644index 0000000..802dc3f--- /dev/null+++ b/scripts/fetch_pack_release.py@@ -0,0 +1,418 @@+#!/usr/bin/env python3+"""Fetch a Phosphene weight pack that is mirrored as **GitHub release assets**.++WHY THIS EXISTS+---------------+Every weight pack Phosphene has ever shipped came from HuggingFace, so+``install.js`` and the panel's Download button both just shell out to+``hf download``. The LTX-2.5 packs cannot take that lane: their upstream is+gated, we publish *our own* quantisation of it, and our HF token is read-only.+LTX-2.5 is nonetheless the **default** generation -- which meant that until this+script existed, a fresh install had **no weights at all** for the default lane.++So the 2.5 packs are mirrored the way the sample character LoRA already is: as+assets on a release of the public repo (see ``SAMPLE_CHARACTER`` in+``mlx_ltx_panel.py``). This is the downloader for that lane.++WHAT MAKES IT MORE THAN A CURL LOOP+-----------------------------------+A GitHub release asset is capped at **2 GiB** and the 2.5 q4 transformer alone is+11.32 GB. So every file over the cap is published as ordered **shards**, and the+reassembly instructions -- per-shard *and* per-file sha256 -- travel in a release+manifest that is a strict **superset of the in-pack**+``phosphene_quant_manifest.json`` (same ``files: {name: {bytes, sha256}}`` shape,+plus a ``shards`` list per file). One manifest format, not two: the panel's+existing ``_manifest_meta()`` deep-verify reader can consume either.++Guarantees, all of which the sample-character downloader also makes:++* **atomic** -- a file only appears under its real name after its whole-file+ sha256 matches; a killed download never leaves something the loader would pick+ up;+* **verified twice** -- every shard is checked against its own sha256 as it+ lands, and the reassembled file against the file sha256. A silent CDN+ truncation cannot survive both;+* **resumable at two levels** -- a partial shard resumes with an HTTP Range+ request, and a partly-assembled file resumes at shard granularity from a+ sidecar; re-running after a kill re-downloads only what is missing;+* **idempotent** -- a complete, hash-correct file is left alone, so+ ``install.js`` can re-run this on every Resume Install for the cost of a+ read pass;+* **frugal with disk** -- shards are appended into the output and deleted one at+ a time, so peak extra space is *one shard* (1.9 GB), not a second copy of the+ pack.++USAGE+-----+::++ python scripts/fetch_pack_release.py --repo-key q4_25+ python scripts/fetch_pack_release.py --repo-key q4_25 --repo-key gemma4_25+ python scripts/fetch_pack_release.py --repo-key q4_25 --dest /tmp/from-zero/pack+ python scripts/fetch_pack_release.py --repo-key q4_25 --check-only++Exit code 0 means every declared file is present and hash-correct.++Stdlib only, on purpose: this runs from ``install.js`` before anything optional+is installed, and from the panel, which is stdlib-only by house rule.+"""++from __future__ import annotations++import argparse+import hashlib+import json+import os+import shutil+import sys+import time+import urllib.error+import urllib.request+from pathlib import Path++ROOT = Path(__file__).resolve().parents[1]+REQUIRED_FILES = "required_files.json"+PARTS_DIRNAME = ".phosphene_parts"+USER_AGENT = "Phosphene"+CHUNK = 1 << 20+# Report at most this often, so a 6-shard 11 GB file does not spam the panel log.+PROGRESS_EVERY_SEC = 2.5+++def log(msg: str) -> None:+ print(msg, flush=True)+++# --------------------------------------------------------------------------- #+# Registry+# --------------------------------------------------------------------------- #+def load_repo_entry(repo_key: str, root: Path) -> dict:+ """The ``required_files.json`` entry for ``repo_key``.++ That file stays the single source of truth for what a complete pack is --+ the same reason the panel's registry points at it by reference instead of+ copying the file list.+ """+ data = json.loads((root / REQUIRED_FILES).read_text())+ for repo in data.get("repos", []):+ if repo.get("key") == repo_key:+ return repo+ known = ", ".join(r.get("key", "?") for r in data.get("repos", []))+ raise SystemExit(f"unknown repo key {repo_key!r} (known: {known})")+++def mirror_of(repo: dict) -> dict:+ """The GitHub-release mirror block, or a hard error naming the reason.++ A pack with no ``mirror`` block belongs to the HuggingFace lane and must be+ fetched with ``hf download`` -- silently doing nothing here would look like+ a successful install with no weights, which is the exact failure this whole+ script exists to end.+ """+ mirror = repo.get("mirror") or {}+ if mirror.get("kind") != "github-release":+ raise SystemExit(+ f"repo {repo.get('key')!r} is not mirrored through a GitHub release "+ f"(mirror.kind={mirror.get('kind')!r}) -- use `hf download` for it"+ )+ for field in ("release_repo", "tag", "manifest_asset"):+ if not mirror.get(field):+ raise SystemExit(f"repo {repo.get('key')!r} mirror block is missing {field!r}")+ return mirror+++def asset_url(mirror: dict, asset: str) -> str:+ return (f"https://github.com/{mirror['release_repo']}"+ f"/releases/download/{mirror['tag']}/{asset}")+++# --------------------------------------------------------------------------- #+# HTTP+# --------------------------------------------------------------------------- #+def _open(url: str, offset: int, timeout: int):+ """Open ``url``, asking to start at ``offset``.++ Returns ``(response, resumed)``. ``resumed`` is False when the server+ ignored the Range header (some proxies do) -- the caller then restarts the+ shard from zero rather than assuming a byte position it cannot verify.+ """+ req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})+ if offset:+ req.add_header("Range", f"bytes={offset}-")+ resp = urllib.request.urlopen(req, timeout=timeout)+ return resp, bool(offset) and resp.status == 206+++def download_shard(url: str, dest: Path, expect_bytes: int, expect_sha: str,+ *, attempts: int, timeout: int, label: str) -> None:+ """Fetch one shard to ``dest``, resuming a partial file, and verify it.++ Raises on a hash mismatch after the last attempt. The shard is deleted on a+ mismatch so the next attempt cannot inherit corrupt bytes -- an important+ difference from a plain resume, which would happily append to garbage.+ """+ last_err: Exception | None = None+ for attempt in range(1, attempts + 1):+ try:+ have = dest.stat().st_size if dest.exists() else 0+ if have > expect_bytes: # overshoot => the file is not ours+ dest.unlink()+ have = 0+ if have < expect_bytes:+ resp, resumed = _open(url, have, timeout)+ mode = "ab" if resumed else "wb"+ if not resumed:+ have = 0+ with resp, open(dest, mode) as fh:+ last = 0.0+ while True:+ chunk = resp.read(CHUNK)+ if not chunk:+ break+ fh.write(chunk)+ have += len(chunk)+ now = time.time()+ if now - last > PROGRESS_EVERY_SEC:+ pct = (100.0 * have / expect_bytes) if expect_bytes else 100.0+ log(f"[fetch] {label} {have >> 20} / {expect_bytes >> 20} MB ({pct:.1f}%)")+ last = now+ got = sha256_file(dest)+ if got != expect_sha:+ dest.unlink(missing_ok=True)+ raise RuntimeError(f"shard sha256 mismatch (expected {expect_sha[:12]}…, got {got[:12]}…)")+ size = dest.stat().st_size+ if size != expect_bytes:+ dest.unlink(missing_ok=True)+ raise RuntimeError(f"shard size mismatch (expected {expect_bytes}, got {size})")+ return+ except (urllib.error.URLError, urllib.error.HTTPError, OSError, RuntimeError) as e:+ last_err = e+ if attempt < attempts:+ back = 5 * attempt+ log(f"[fetch] {label} attempt {attempt}/{attempts} failed ({e}) — retrying in {back}s")+ time.sleep(back)+ raise RuntimeError(f"{label}: giving up after {attempts} attempts — {last_err}")+++def fetch_json(url: str, *, attempts: int, timeout: int) -> dict:+ last_err: Exception | None = None+ for attempt in range(1, attempts + 1):+ try:+ req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})+ with urllib.request.urlopen(req, timeout=timeout) as resp:+ return json.loads(resp.read().decode("utf-8"))+ except (urllib.error.URLError, urllib.error.HTTPError, OSError, ValueError) as e:+ last_err = e+ if attempt < attempts:+ time.sleep(5 * attempt)+ raise SystemExit(f"could not read the release manifest at {url} — {last_err}")+++# --------------------------------------------------------------------------- #+# Hashing+# --------------------------------------------------------------------------- #+def sha256_file(path: Path) -> str:+ h = hashlib.sha256()+ with open(path, "rb") as fh:+ for block in iter(lambda: fh.read(1 << 22), b""):+ h.update(block)+ return h.hexdigest()+++# --------------------------------------------------------------------------- #+# Assembly+# --------------------------------------------------------------------------- #+def _progress_path(partial: Path) -> Path:+ return partial.with_suffix(partial.suffix + ".progress")+++def _read_progress(partial: Path) -> int:+ """How many shards of ``partial`` are already appended, per its sidecar.++ The sidecar is authoritative only when it agrees with the file's actual+ length; any disagreement (a kill between the write and the fsync, a manual+ truncation) resets to zero rather than trusting a number that would splice+ shards at the wrong offset.+ """+ try:+ rec = json.loads(_progress_path(partial).read_text())+ done, size = int(rec["shards_done"]), int(rec["bytes"])+ except (OSError, ValueError, KeyError, TypeError):+ return 0+ if not partial.exists() or partial.stat().st_size != size:+ return 0+ return done+++def _write_progress(partial: Path, shards_done: int) -> None:+ _progress_path(partial).write_text(json.dumps({+ "shards_done": shards_done,+ "bytes": partial.stat().st_size,+ }))+++def assemble_file(name: str, spec: dict, dest_dir: Path, mirror: dict,+ *, attempts: int, timeout: int) -> None:+ """Download + reassemble one declared file into ``dest_dir``.++ Shards are appended to ``<name>.partial`` and deleted as they land, so the+ peak extra disk cost is one shard rather than a second copy of the pack --+ the difference between +1.9 GB and +11.3 GB on the transformer, on machines+ that are already tight enough that we quantised the model for them.+ """+ target = dest_dir / name+ want_sha = spec["sha256"]+ want_bytes = int(spec["bytes"])++ if target.exists():+ if target.stat().st_size == want_bytes and sha256_file(target) == want_sha:+ log(f"[fetch] {name} — already complete and verified, skipping")+ return+ log(f"[fetch] {name} — present but does not match the manifest, refetching")++ parts_dir = dest_dir / PARTS_DIRNAME+ parts_dir.mkdir(parents=True, exist_ok=True)+ partial = dest_dir / (name + ".partial")+ shards = spec["shards"]+ done = _read_progress(partial)+ if done:+ log(f"[fetch] {name} — resuming after shard {done}/{len(shards)}")+ elif partial.exists():+ partial.unlink()++ for idx, shard in enumerate(shards):+ if idx < done:+ continue+ asset = shard["asset"]+ label = f"{name} [{idx + 1}/{len(shards)}]"+ shard_path = parts_dir / asset+ download_shard(asset_url(mirror, asset), shard_path,+ int(shard["bytes"]), shard["sha256"],+ attempts=attempts, timeout=timeout, label=label)+ with open(partial, "ab") as out, open(shard_path, "rb") as src:+ shutil.copyfileobj(src, out, CHUNK)+ out.flush()+ os.fsync(out.fileno())+ shard_path.unlink(missing_ok=True)+ _write_progress(partial, idx + 1)++ size = partial.stat().st_size+ if size != want_bytes:+ raise RuntimeError(f"{name}: assembled {size} bytes, manifest declares {want_bytes}")+ got = sha256_file(partial)+ if got != want_sha:+ raise RuntimeError(f"{name}: assembled sha256 {got[:12]}… != manifest {want_sha[:12]}…")+ partial.replace(target)+ _progress_path(partial).unlink(missing_ok=True)+ log(f"[fetch] {name} — {size >> 20} MB, sha256 verified")+++# --------------------------------------------------------------------------- #+# One pack+# --------------------------------------------------------------------------- #+def check_pack(manifest: dict, dest_dir: Path) -> list[str]:+ """Names of declared files that are missing or do not match the manifest."""+ bad: list[str] = []+ for name, spec in manifest["files"].items():+ path = dest_dir / name+ if not path.exists() or path.stat().st_size != int(spec["bytes"]):+ bad.append(name)+ continue+ if sha256_file(path) != spec["sha256"]:+ bad.append(name)+ return bad+++def fetch_pack(repo_key: str, root: Path, dest: Path | None,+ *, attempts: int, timeout: int, check_only: bool) -> int:+ repo = load_repo_entry(repo_key, root)+ mirror = mirror_of(repo)+ dest_dir = dest or (root / repo["local_dir"])+ url = asset_url(mirror, mirror["manifest_asset"])++ log(f"[fetch] {repo_key}: {repo.get('name', repo_key)} → {dest_dir}")+ log(f"[fetch] manifest {url}")+ manifest = fetch_json(url, attempts=attempts, timeout=timeout)+ files = manifest.get("files")+ if not isinstance(files, dict) or not files:+ raise SystemExit(f"release manifest for {repo_key} declares no files")++ # The manifest is the mirror's word for what a pack is; required_files.json+ # is the app's. They must not drift, and a drift found HERE (before 21 GB is+ # pulled) is worth far more than one found by a loader at render time.+ missing = [f for f in repo.get("files", []) if f not in files]+ if missing:+ raise SystemExit(+ f"release manifest for {repo_key} is missing files that "+ f"required_files.json declares mandatory: {', '.join(missing)}"+ )++ dest_dir.mkdir(parents=True, exist_ok=True)+ if check_only:+ bad = check_pack(manifest, dest_dir)+ if bad:+ log(f"[fetch] {repo_key}: INCOMPLETE — {len(bad)} file(s): {', '.join(bad)}")+ return 1+ log(f"[fetch] {repo_key}: complete, {len(files)} file(s) verified")+ return 0++ total_gb = sum(int(s["bytes"]) for s in files.values()) / 1e9+ log(f"[fetch] {len(files)} file(s), {total_gb:.2f} GB — resumable, sha256-verified")++ # One bad file does NOT abandon the rest of the pack. A poisoned shard in+ # the middle of an 11 GB transformer used to stop the loop dead, so a user+ # who retried started the other 10 GB from nothing. Every file gets its own+ # attempt; the failures are collected and reported together, and the next+ # run skips everything that already verified.+ failed: list[str] = []+ for name, spec in files.items():+ try:+ assemble_file(name, spec, dest_dir, mirror, attempts=attempts, timeout=timeout)+ except Exception as e: # noqa: BLE001 — a cause, not a traceback+ failed.append(name)+ log(f"[fetch] {name}: FAILED — {e}")++ parts_dir = dest_dir / PARTS_DIRNAME+ if parts_dir.is_dir() and not any(parts_dir.iterdir()):+ parts_dir.rmdir()+ if failed:+ log(f"[fetch] {repo_key}: {len(failed)} of {len(files)} file(s) FAILED "+ f"({', '.join(failed)}) — run this again, it resumes and re-checks "+ f"only what is missing")+ return 1+ log(f"[fetch] {repo_key}: done — {len(files)} file(s) verified against the manifest")+ return 0+++def main(argv: list[str] | None = None) -> int:+ ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])+ ap.add_argument("--repo-key", action="append", required=True,+ help="key in required_files.json (repeatable), e.g. q4_25")+ ap.add_argument("--dest", type=Path, default=None,+ help="override the destination dir (single --repo-key only; for from-zero tests)")+ ap.add_argument("--root", type=Path, default=ROOT, help="app root holding required_files.json")+ ap.add_argument("--attempts", type=int, default=4)+ ap.add_argument("--timeout", type=int, default=60)+ ap.add_argument("--check-only", action="store_true",+ help="verify what is on disk against the published manifest; download nothing")+ args = ap.parse_args(argv)++ if args.dest and len(args.repo_key) > 1:+ ap.error("--dest applies to a single --repo-key")++ rc = 0+ for key in args.repo_key:+ try:+ rc |= fetch_pack(key, args.root, args.dest,+ attempts=args.attempts, timeout=args.timeout,+ check_only=args.check_only)+ except SystemExit:+ raise+ except Exception as e: # noqa: BLE001 — the installer needs a cause, not a traceback+ log(f"[fetch] {key}: FAILED — {e}")+ rc = 1+ return rc+++if __name__ == "__main__":+ sys.exit(main())diff --git a/scripts/ltx_pack_diff.py b/scripts/ltx_pack_diff.pynew file mode 100644index 0000000..c9c458f--- /dev/null+++ b/scripts/ltx_pack_diff.py@@ -0,0 +1,351 @@+#!/usr/bin/env python3+"""Diff one LTX pack's tensor CONTRACT against a reference pack's.++This is the standing gate the LTX-2.5 build kept re-deriving by hand. Every+time a pack was built, the thing that actually caught the bugs was not a test+written alongside the code — it was diffing the new pack's key set, shapes and+dtypes against the shipped LTX-2.3 pack, which is ground truth for MLX layout.+Three of the four conversion bugs on weights day were invisible to the+converter's own routing report and visible here. So it lives in ``scripts/``+with a test, not in a scratchpad someone remembers to run.++ convert_ltx_mlx.py changes KEY NAMES and FILE LAYOUT.+ quantize_ltx.py changes NUMBERS.+ ltx_pack_diff.py changes NOTHING. It reads headers and refuses.++**Header-only.** It parses the 8-byte length + JSON header of each safetensors+file and never touches a weight byte, so diffing a 44 GB pack costs+milliseconds and a few MB of RAM. That is deliberate: a gate that is expensive+does not get run.++What it compares, per file present in both packs:++ * key sets → ``only in new`` / ``only in ref``+ * shapes on shared keys → **always a failure**+ * dtypes on shared keys → **always a failure**++Key-set differences are *reported* by default and *enforced* the moment you+declare what you expect. Pass ``--allow-only-new`` / ``--allow-only-ref`` with+collapsed patterns (``transformer_blocks.N.…`` stands for every numbered+block) and any key difference NOT covered by a pattern becomes a failure. That+turns "read the output and squint" into a contract the CI-shaped thing can+assert. The 2.5-vs-2.3 DiT contract, for the record, is exactly:++ --allow-only-new transformer.keyframes_abs_pos_embedding \\+ --allow-only-ref transformer.transformer_blocks.N.ff.proj_in.bias \\+ --allow-only-ref transformer.transformer_blocks.N.ff.proj_out.bias++Usage+-----+ # whole pack against the 2.3 pack of the same bit width+ python3 scripts/ltx_pack_diff.py \\+ mlx_models/ltx-2.3-mlx-q8 mlx_models/ltx-2.5-mlx-q8++ # a file that changed names between generations (ref=new)+ python3 scripts/ltx_pack_diff.py REF NEW \\+ --map transformer-dev.safetensors=transformer-distilled.safetensors++ # the same pack twice, to prove two variants share one architecture+ python3 scripts/ltx_pack_diff.py PACK PACK \\+ --map transformer-distilled.safetensors=transformer-dev.safetensors \\+ --strict-keys++Exit codes: ``0`` clean · ``1`` a mismatch or an undeclared key difference ·+``2`` bad invocation (no comparable files, missing directory).+"""++from __future__ import annotations++import argparse+import json+import re+import struct+import sys+from collections import Counter+from pathlib import Path++__all__ = [+ "collapse_key",+ "collapse_keys",+ "diff_file",+ "diff_packs",+ "pair_files",+ "read_header",+]+++# ---------------------------------------------------------------------------+# safetensors header — deliberately dependency-free, same primitive the+# converter and the quantizer own. `mx.load` would read the whole file.+# ---------------------------------------------------------------------------+++def read_header(path: Path) -> dict:+ """Return the tensor index of a safetensors file, without ``__metadata__``.++ Raises ``ValueError`` on a file too short or with an unparseable header —+ a truncated download must not read as "a pack with no tensors".+ """+ with open(path, "rb") as fh:+ raw_len = fh.read(8)+ if len(raw_len) != 8:+ raise ValueError(f"{path}: too short to be safetensors")+ (header_len,) = struct.unpack("<Q", raw_len)+ blob = fh.read(header_len)+ if len(blob) != header_len:+ raise ValueError(f"{path}: header truncated ({len(blob)} of {header_len} bytes)")+ index = json.loads(blob)+ if not isinstance(index, dict):+ raise ValueError(f"{path}: header is not a JSON object")+ index.pop("__metadata__", None)+ return index+++_NUMBERED = re.compile(r"\.\d+\.")+++def collapse_key(key: str) -> str:+ """``…transformer_blocks.7.ff.proj_in.bias`` → ``…transformer_blocks.N.ff.proj_in.bias``.++ 48 blocks' worth of the same structural difference is one fact, not 48.+ Collapsing is what lets a human-writable ``--allow-*`` pattern cover a+ whole stack without a wildcard language.+ """+ return _NUMBERED.sub(".N.", key)+++def collapse_keys(keys) -> list[tuple[str, int]]:+ """Collapsed patterns with their counts, sorted by pattern."""+ return sorted(Counter(collapse_key(k) for k in keys).items())+++# ---------------------------------------------------------------------------+# the diff+# ---------------------------------------------------------------------------+++def diff_file(ref: Path, new: Path) -> dict:+ """Compare two safetensors files by header alone."""+ a, b = read_header(ref), read_header(new)+ ka, kb = set(a), set(b)+ shared = ka & kb+ return {+ "ref": ref.name,+ "new": new.name,+ "n_ref": len(ka),+ "n_new": len(kb),+ "shared": len(shared),+ "only_new": sorted(kb - ka),+ "only_ref": sorted(ka - kb),+ "shape_mm": [+ (k, a[k]["shape"], b[k]["shape"]) for k in sorted(shared) if a[k]["shape"] != b[k]["shape"]+ ],+ "dtype_mm": [+ (k, a[k]["dtype"], b[k]["dtype"]) for k in sorted(shared) if a[k]["dtype"] != b[k]["dtype"]+ ],+ }+++def pair_files(ref_dir: Path, new_dir: Path, mapping: dict[str, str] | None = None) -> list[tuple[Path, Path]]:+ """Which files to compare.++ Explicit ``--map ref=new`` pairs first, in the order given, then every+ ``*.safetensors`` in the new pack that has a same-named sibling in the+ reference pack. A file present in only one pack is not a mismatch — it is+ what ``--strict-files`` is for, and callers usually want the shared subset.+ """+ pairs: list[tuple[Path, Path]] = []+ seen: set[Path] = set()+ for ref_name, new_name in (mapping or {}).items():+ pairs.append((ref_dir / ref_name, new_dir / (new_name or ref_name)))+ seen.add(new_dir / (new_name or ref_name))+ for path in sorted(new_dir.glob("*.safetensors")):+ if path in seen:+ continue+ sibling = ref_dir / path.name+ if sibling.exists():+ pairs.append((sibling, path))+ return pairs+++def _uncovered(keys, patterns: list[str]) -> list[tuple[str, int]]:+ """Collapsed key patterns not named by any allow pattern."""+ allowed = set(patterns)+ return [(pat, count) for pat, count in collapse_keys(keys) if pat not in allowed]+++def diff_packs(+ ref_dir: Path,+ new_dir: Path,+ *,+ mapping: dict[str, str] | None = None,+ allow_only_new: list[str] | None = None,+ allow_only_ref: list[str] | None = None,+ strict_keys: bool = False,+) -> dict:+ """Diff every comparable file and decide pass/fail.++ ``ok`` is False when any shape or dtype disagrees on a shared key — that is+ unconditional, because a shape difference means the two packs cannot be+ loaded by the same code and no allowlist should be able to wave it through.++ Key-set differences fail only when a contract was declared: any+ ``--allow-*`` pattern, or ``--strict-keys`` (which declares the empty+ contract, i.e. the key sets must be identical).+ """+ allow_only_new = list(allow_only_new or [])+ allow_only_ref = list(allow_only_ref or [])+ enforce = strict_keys or bool(allow_only_new) or bool(allow_only_ref)++ pairs = pair_files(ref_dir, new_dir, mapping)+ files, mismatches, undeclared = [], 0, 0+ for ref, new in pairs:+ entry = diff_file(ref, new)+ entry["uncovered_new"] = _uncovered(entry["only_new"], allow_only_new) if enforce else []+ entry["uncovered_ref"] = _uncovered(entry["only_ref"], allow_only_ref) if enforce else []+ mismatches += len(entry["shape_mm"]) + len(entry["dtype_mm"])+ undeclared += sum(c for _, c in entry["uncovered_new"]) + sum(c for _, c in entry["uncovered_ref"])+ files.append(entry)++ return {+ "ref_dir": str(ref_dir),+ "new_dir": str(new_dir),+ "compared": len(files),+ "files": files,+ "mismatches": mismatches,+ "undeclared_keys": undeclared,+ "enforced": enforce,+ "ok": mismatches == 0 and undeclared == 0,+ }+++# ---------------------------------------------------------------------------+# CLI+# ---------------------------------------------------------------------------+++def render(report: dict) -> str:+ lines = []+ for entry in report["files"]:+ lines.append(f"\n=== {entry['new']} vs ref {entry['ref']} ===")+ lines.append(f" keys: ref {entry['n_ref']} new {entry['n_new']} shared {entry['shared']}")+ lines.append(f" shape mismatches on shared tensors: {len(entry['shape_mm'])}")+ lines.append(f" dtype mismatches on shared tensors: {len(entry['dtype_mm'])}")+ for key, sa, sb in entry["shape_mm"][:12]:+ lines.append(f" SHAPE {key}: ref {sa} new {sb}")+ for key, da, db in entry["dtype_mm"][:12]:+ lines.append(f" DTYPE {key}: ref {da} new {db}")+ for label, bucket, uncovered in (+ ("ONLY in new", entry["only_new"], entry["uncovered_new"]),+ ("ONLY in ref", entry["only_ref"], entry["uncovered_ref"]),+ ):+ if not bucket:+ continue+ lines.append(f" {label} ({len(bucket)}):")+ undeclared = {pat for pat, _ in uncovered}+ for pat, count in collapse_keys(bucket):+ flag = " <- UNDECLARED" if pat in undeclared else ""+ lines.append(f" {count:5d} {pat}{flag}")+ lines.append(+ f"\ncompared {report['compared']} file(s): "+ f"{report['mismatches']} shape+dtype mismatch(es), "+ f"{report['undeclared_keys']} undeclared key difference(s)"+ + ("" if report["enforced"] else " (key sets reported only — pass --strict-keys or --allow-* to enforce)")+ )+ lines.append("RESULT: " + ("PASS" if report["ok"] else "FAIL"))+ return "\n".join(lines)+++def main(argv=None) -> int:+ parser = argparse.ArgumentParser(+ description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter+ )+ parser.add_argument("ref_dir", type=Path, help="reference pack directory (ground truth, e.g. the 2.3 pack)")+ parser.add_argument("new_dir", type=Path, help="pack directory under test")+ parser.add_argument(+ "--map",+ action="append",+ default=[],+ metavar="REF=NEW",+ help="compare differently-named files, repeatable (e.g. "+ "transformer-dev.safetensors=transformer-distilled.safetensors)",+ )+ parser.add_argument(+ "--allow-only-new",+ action="append",+ default=[],+ metavar="PATTERN",+ help="collapsed key pattern expected to exist only in the NEW pack. "+ "Declaring any pattern turns key-set checking into a hard gate.",+ )+ parser.add_argument(+ "--allow-only-ref",+ action="append",+ default=[],+ metavar="PATTERN",+ help="collapsed key pattern expected to exist only in the REFERENCE pack.",+ )+ parser.add_argument(+ "--strict-keys",+ action="store_true",+ help="the key sets must be identical (the empty contract)",+ )+ parser.add_argument(+ "--strict-files",+ action="store_true",+ help="also fail when the two packs do not hold the same set of .safetensors files",+ )+ parser.add_argument("--json", action="store_true", help="emit the report as JSON instead of text")+ args = parser.parse_args(argv)++ for directory in (args.ref_dir, args.new_dir):+ if not directory.is_dir():+ print(f"error: {directory} is not a directory", file=sys.stderr)+ return 2++ mapping: dict[str, str] = {}+ for raw in args.map:+ ref_name, _, new_name = raw.partition("=")+ if not ref_name:+ print(f"error: --map needs REF=NEW, got {raw!r}", file=sys.stderr)+ return 2+ mapping[ref_name] = new_name or ref_name++ report = diff_packs(+ args.ref_dir,+ args.new_dir,+ mapping=mapping,+ allow_only_new=args.allow_only_new,+ allow_only_ref=args.allow_only_ref,+ strict_keys=args.strict_keys,+ )++ if args.strict_files:+ ref_files = {p.name for p in args.ref_dir.glob("*.safetensors")}+ new_files = {p.name for p in args.new_dir.glob("*.safetensors")}+ report["only_new_files"] = sorted(new_files - ref_files)+ report["only_ref_files"] = sorted(ref_files - new_files)+ if report["only_new_files"] or report["only_ref_files"]:+ report["ok"] = False++ if not report["compared"]:+ print(+ f"error: no comparable .safetensors between {args.ref_dir} and {args.new_dir}. "+ "A diff that compares nothing must not report success.",+ file=sys.stderr,+ )+ return 2++ if args.json:+ print(json.dumps(report, indent=2))+ else:+ print(render(report))+ for label in ("only_new_files", "only_ref_files"):+ if report.get(label):+ print(f"{label}: {', '.join(report[label])}")++ return 0 if report["ok"] else 1+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/scripts/publish_pack_release.py b/scripts/publish_pack_release.pynew file mode 100644index 0000000..b63c4a2--- /dev/null+++ b/scripts/publish_pack_release.py@@ -0,0 +1,433 @@+#!/usr/bin/env python3+"""Publish a Phosphene weight pack as **GitHub release assets** + a release manifest.++WHY THIS EXISTS+---------------+The LTX-2.5 packs are quantised by us (``scripts/quantize_ltx.py``) from the+official Lightricks bf16 release. We cannot push them to HuggingFace -- the token+is read-only -- and 2.5 is the *default* generation, so without a mirror a fresh+install has no weights for the lane it boots into. The owner's call was to mirror+through GitHub releases on the public repo, the lane the ``bizarrotrn_v2`` sample+character already takes.++THE ONE HARD CONSTRAINT+-----------------------+A GitHub release asset is capped at **2 GiB**. The 2.5 q4 transformer is+11.32 GB, its connector 6.34 GB, the Gemma 4 encoder 6.70 GB. So anything over+the cap is published as ordered **shards** of at most 1.9 GB, and the reassembly+instructions travel in a release manifest.++THE MANIFEST IS NOT A NEW FORMAT+--------------------------------+It is the in-pack ``phosphene_quant_manifest.json`` with two additions: a+``release`` block and a ``shards`` list inside each file entry. The+``files: {name: {bytes, sha256}}`` shape is preserved exactly, which is what+lets the panel's existing ``_manifest_meta()`` deep-verify reader consume it+unchanged, and what keeps the quantiser as the origin of the numbers rather+than a second, drifting source of truth. Where the in-pack manifest and the real+file disagree (sidecar JSONs rewritten after the quantiser ran), the **file on+disk wins** and the drift is reported -- a published hash that does not match+the published bytes is worse than no hash.++DISK DISCIPLINE+---------------+Shards are written **one at a time**, uploaded, and deleted, so publishing a+21 GB pack costs 1.9 GB of scratch rather than a second copy of the pack. Files+that already fit under the cap are hard-linked into the staging dir under their+asset name (zero bytes copied) and unlinked after upload.++RESUME+------+Re-running skips any asset already on the release with a matching byte count, so+an upload killed at hour two picks up where it stopped. The manifest is uploaded+**last**, so a half-published release never advertises a pack that isn't there.++USAGE+-----+::++ # build + inspect the manifest, upload nothing+ python scripts/publish_pack_release.py --repo-key q4_25 --dry-run++ # publish (creates the release if needed; safe to re-run)+ python scripts/publish_pack_release.py --repo-key q4_25 \+ --tag weights-ltx25-v1 --target <public-main-sha>++Requires the ``gh`` CLI authenticated for the repo that owns the release.+"""++from __future__ import annotations++import argparse+import hashlib+import json+import os+import shutil+import subprocess+import sys+import time+from datetime import datetime, timezone+from pathlib import Path++ROOT = Path(__file__).resolve().parents[1]+REQUIRED_FILES = "required_files.json"+QUANT_MANIFEST = "phosphene_quant_manifest.json"+SCHEMA = "phosphene-release-manifest/1"++# 1.9 GB decimal. The GitHub cap is 2 GiB (2,147,483,648 B); this leaves ~12 %+# headroom and produces a round number in every log line and asset name.+SHARD_BYTES = 1_900_000_000+CHUNK = 1 << 22++LICENSE_ASSET = "LICENSE-LTX-2.x-Community-License.md"+NOTICE_ASSET = "NOTICE.md"++# Never shipped: scratch from an interrupted quantise or publish run.+SKIP_SUFFIXES = (".partial", ".progress")+SKIP_NAMES = {".DS_Store"}+++def log(msg: str) -> None:+ print(msg, flush=True)+++def utc_now() -> str:+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")+++# --------------------------------------------------------------------------- #+# Registry + pack contents+# --------------------------------------------------------------------------- #+def load_repo_entry(repo_key: str, root: Path) -> dict:+ data = json.loads((root / REQUIRED_FILES).read_text())+ for repo in data.get("repos", []):+ if repo.get("key") == repo_key:+ return repo+ raise 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*.++ Not just ``required_files.json``'s mandatory list: the loader also reads+ sidecar JSON (``split_model.json``, the upscaler configs, the quantiser's+ own manifest) that the mandatory list deliberately does not enumerate, and+ the ``download_include`` allowlist pulls with ``*.json`` for exactly that+ reason. Publishing the directory keeps the mirror a faithful copy.+ """+ out = []+ for p in sorted(pack_dir.iterdir()):+ if not p.is_file() or p.name.startswith("."):+ continue+ if p.name in SKIP_NAMES or p.name.endswith(SKIP_SUFFIXES):+ continue+ out.append(p.name)+ return out+++def sha256_file(path: Path) -> str:+ h = hashlib.sha256()+ with open(path, "rb") as fh:+ for block in iter(lambda: fh.read(CHUNK), b""):+ h.update(block)+ return h.hexdigest()+++def asset_name(prefix: str, filename: str, shard_idx: int | None) -> str:+ """Deterministic asset names.++ ``<repo_key>__<filename>`` for a whole file, ``…partNNN`` for a shard. Only+ ASCII alphanumerics, dot, dash and underscore, because GitHub rewrites+ anything else in an asset name and a rewritten name breaks the manifest's+ URLs silently.+ """+ base = f"{prefix}__{filename}"+ return base if shard_idx is None else f"{base}.part{shard_idx:03d}"+++# --------------------------------------------------------------------------- #+# gh+# --------------------------------------------------------------------------- #+def gh(*args: str, check: bool = True, capture: bool = True) -> subprocess.CompletedProcess:+ return subprocess.run(["gh", *args], check=check,+ capture_output=capture, text=True)+++def release_assets(release_repo: str, tag: str) -> dict[str, int]:+ """``{asset name: size}`` already on the release; ``{}`` if it doesn't exist."""+ p = gh("release", "view", tag, "-R", release_repo, "--json", "assets", check=False)+ if p.returncode != 0:+ return {}+ try:+ data = json.loads(p.stdout)+ except ValueError:+ return {}+ return {a["name"]: int(a.get("size") or 0) for a in data.get("assets", [])}+++def ensure_release(release_repo: str, tag: str, target: str, title: str, notes_file: Path) -> None:+ p = gh("release", "view", tag, "-R", release_repo, "--json", "tagName", check=False)+ if p.returncode == 0:+ log(f"[publish] release {tag} exists on {release_repo}")+ return+ log(f"[publish] creating release {tag} on {release_repo} @ {target[:12]}")+ gh("release", "create", tag, "-R", release_repo,+ "--target", target, "--title", title,+ "--notes-file", str(notes_file), "--latest=false")+++def upload_asset(release_repo: str, tag: str, path: Path, *, attempts: int = 3) -> None:+ for attempt in range(1, attempts + 1):+ p = gh("release", "upload", tag, str(path), "-R", release_repo,+ "--clobber", check=False)+ if p.returncode == 0:+ return+ log(f"[publish] upload {path.name} attempt {attempt}/{attempts} failed: "+ f"{(p.stderr or '').strip()[:300]}")+ if attempt < attempts:+ time.sleep(10 * attempt)+ raise RuntimeError(f"could not upload {path.name} after {attempts} attempts")+++# --------------------------------------------------------------------------- #+# Publishing one file+# --------------------------------------------------------------------------- #+def publish_file(src: Path, prefix: str, staging: Path, *, release_repo: str,+ tag: str, existing: dict[str, int], upload: bool) -> dict:+ """Shard (if needed), upload, and return the manifest entry for one file.++ One read pass: the whole-file hash and every shard hash are computed from+ the same stream. Shards are written, uploaded and deleted one at a time.+ """+ size = src.stat().st_size+ if size == 0:+ # A zero-byte file in a pack is the exact corruption the panel's+ # integrity scan exists to catch (min_size_bytes). Publishing one would+ # mirror the corruption to every user, so refuse loudly instead.+ raise SystemExit(f"{src.name} is zero bytes — refusing to publish a corrupt pack")+ file_h = hashlib.sha256()+ shards: list[dict] = []++ if size <= SHARD_BYTES:+ 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:+ link = staging / name+ link.unlink(missing_ok=True)+ try:+ os.link(src, link) # zero-copy when same filesystem+ except OSError:+ shutil.copy2(src, link)+ log(f"[publish] ↑ {name} ({size >> 20} MB)")+ upload_asset(release_repo, tag, link)+ link.unlink(missing_ok=True)+ elif upload:+ log(f"[publish] = {name} already uploaded ({size >> 20} MB)")+ return {"bytes": size, "sha256": digest, "shards": shards}++ n_shards = (size + SHARD_BYTES - 1) // SHARD_BYTES+ log(f"[publish] {src.name}: {size / 1e9:.2f} GB → {n_shards} shards")+ with open(src, "rb") as fh:+ for idx in range(n_shards):+ name = asset_name(prefix, src.name, idx)+ shard_path = staging / name+ shard_h = hashlib.sha256()+ written = 0+ want = min(SHARD_BYTES, size - idx * SHARD_BYTES)+ # A dry run hashes the same stream but writes nothing: the manifest+ # it produces is the manifest the real run would produce, at zero+ # disk cost, which is what makes --dry-run a usable rehearsal.+ out = open(shard_path, "wb") if upload else None+ try:+ while written < want:+ block = fh.read(min(CHUNK, want - written))+ if not block:+ break+ if out is not None:+ out.write(block)+ shard_h.update(block)+ file_h.update(block)+ written += len(block)+ finally:+ if out is not None:+ out.close()+ if written != want:+ raise RuntimeError(f"{src.name}: short read on shard {idx} ({written} != {want})")+ shards.append({"asset": name, "bytes": written, "sha256": shard_h.hexdigest()})+ if upload and existing.get(name) != written:+ log(f"[publish] ↑ {name} ({written >> 20} MB, shard {idx + 1}/{n_shards})")+ upload_asset(release_repo, tag, shard_path)+ elif upload:+ log(f"[publish] = {name} already uploaded ({written >> 20} MB)")+ shard_path.unlink(missing_ok=True) # peak scratch stays one shard++ digest = file_h.hexdigest()+ return {"bytes": size, "sha256": digest, "shards": shards}+++# --------------------------------------------------------------------------- #+# Manifest+# --------------------------------------------------------------------------- #+def in_pack_manifest(pack_dir: Path) -> dict:+ try:+ return json.loads((pack_dir / QUANT_MANIFEST).read_text())+ except (OSError, ValueError):+ return {}+++def build_manifest(repo_key: str, repo: dict, pack_dir: Path, files: dict,+ mirror: dict, drift: list[str]) -> dict:+ quant = in_pack_manifest(pack_dir)+ return {+ "schema": SCHEMA,+ "pack": pack_dir.name,+ "repo_key": repo_key,+ "name": repo.get("name", repo_key),+ "written_utc": utc_now(),+ "shard_bytes": SHARD_BYTES,+ "release": {+ "release_repo": mirror["release_repo"],+ "tag": mirror["tag"],+ "asset_prefix": f"{repo_key}__",+ },+ "license": {+ "name": "LTX-2.x Community License Agreement",+ "licensor": "Lightricks Ltd.",+ "asset": LICENSE_ASSET,+ "notice_asset": NOTICE_ASSET,+ },+ # Provenance from the quantiser, so a published pack still points at the+ # run that produced it even though the file list is re-hashed here.+ "quantizer": {k: quant.get(k) for k in+ ("tool", "tool_version", "recipe", "bits", "group_size",+ "source_pack", "written_utc") if quant.get(k) is not None},+ "quant_manifest_drift": drift,+ "files": files,+ }+++# --------------------------------------------------------------------------- #+# Main+# --------------------------------------------------------------------------- #+def publish(repo_key: str, root: Path, *, tag: str | None, release_repo: str | None,+ target: str | None, upload: bool, staging_root: Path,+ license_path: Path | None, notice_path: Path | None,+ notes_file: Path | None, title: str | None) -> dict:+ repo = load_repo_entry(repo_key, root)+ declared = repo.get("mirror") or {}+ mirror = {+ "release_repo": release_repo or declared.get("release_repo"),+ "tag": tag or declared.get("tag"),+ }+ if not mirror["release_repo"] or not mirror["tag"]:+ raise SystemExit("need --tag and --release-repo (or a mirror block in required_files.json)")++ pack_dir = root / repo["local_dir"]+ if not pack_dir.is_dir():+ raise SystemExit(f"pack dir not found: {pack_dir}")++ staging = staging_root / mirror["tag"]+ staging.mkdir(parents=True, exist_ok=True)++ names = pack_files(pack_dir)+ 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}")++ missing = [f for f in repo.get("files", []) if f not in names]+ if missing:+ raise SystemExit(f"pack is incomplete — required_files.json wants: {', '.join(missing)}")++ if upload:+ if not target:+ raise SystemExit("--target (a commit sha on the PUBLIC default branch) is required to create a release")+ notes = notes_file+ if notes is None:+ notes = staging / "_notes.md"+ notes.write_text(+ f"Weight packs for Phosphene, mirrored as release assets.\n\n"+ f"Fetched and reassembled by `scripts/fetch_pack_release.py`; every shard "+ f"and every reassembled file is sha256-verified against "+ f"`<key>__phosphene_release_manifest.json`.\n\n"+ f"See `{NOTICE_ASSET}` and `{LICENSE_ASSET}`.\n")+ ensure_release(mirror["release_repo"], mirror["tag"], target,+ title or f"Weights: {repo.get('name', repo_key)}", notes)+ existing = release_assets(mirror["release_repo"], mirror["tag"]) if upload else {}++ files: dict[str, dict] = {}+ drift: list[str] = []+ quant = in_pack_manifest(pack_dir).get("files") or {}+ for name in names:+ entry = publish_file(pack_dir / name, repo_key, staging,+ release_repo=mirror["release_repo"], tag=mirror["tag"],+ existing=existing, upload=upload)+ files[name] = entry+ q = quant.get(name) or {}+ if q.get("sha256") and q["sha256"] != entry["sha256"]:+ drift.append(name)+ if drift:+ log(f"[publish] NOTE: in-pack quant manifest disagrees with the bytes on disk "+ f"for {len(drift)} file(s): {', '.join(drift)} — the published hashes are "+ f"the files', not the stale manifest's.")++ # Licence + notice ride along as pack files, so the terms land on the user's+ # disk next to the weights (§3.2), not only on a web page.+ for src, asset in ((license_path, LICENSE_ASSET), (notice_path, NOTICE_ASSET)):+ if not src:+ continue+ size = src.stat().st_size+ digest = sha256_file(src)+ files[asset] = {"bytes": size, "sha256": digest,+ "shards": [{"asset": asset, "bytes": size, "sha256": digest}]}+ if upload and existing.get(asset) != size:+ staged = staging / asset+ staged.unlink(missing_ok=True)+ shutil.copy2(src, staged)+ log(f"[publish] ↑ {asset} ({size} B)")+ upload_asset(mirror["release_repo"], mirror["tag"], staged)+ staged.unlink(missing_ok=True)++ manifest = build_manifest(repo_key, repo, pack_dir, files, mirror, drift)+ man_name = f"{repo_key}__{QUANT_MANIFEST.replace('quant', 'release')}"+ man_path = staging / man_name+ man_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")+ log(f"[publish] manifest → {man_path} ({man_path.stat().st_size} B)")+ if upload:+ # Last, always: until this lands the release cannot be consumed, which+ # is exactly the behaviour we want from a half-finished upload.+ upload_asset(mirror["release_repo"], mirror["tag"], man_path)+ log(f"[publish] {repo_key}: published as {man_name}")+ return manifest+++def main(argv: list[str] | None = None) -> int:+ ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])+ ap.add_argument("--repo-key", required=True)+ ap.add_argument("--root", type=Path, default=ROOT)+ ap.add_argument("--tag", default=None)+ ap.add_argument("--release-repo", default=None)+ ap.add_argument("--target", default=None,+ help="commit sha the tag is created on — MUST be public main")+ ap.add_argument("--title", default=None)+ ap.add_argument("--notes-file", type=Path, default=None)+ ap.add_argument("--license", dest="license_path", type=Path, default=None)+ ap.add_argument("--notice", dest="notice_path", type=Path, default=None)+ ap.add_argument("--staging", type=Path, default=None)+ ap.add_argument("--dry-run", action="store_true", help="build the manifest, upload nothing")+ ap.add_argument("--manifest-out", type=Path, default=None)+ args = ap.parse_args(argv)++ staging_root = args.staging or (args.root / "mlx_models" / "_release_staging")+ manifest = publish(args.repo_key, args.root, tag=args.tag,+ release_repo=args.release_repo, target=args.target,+ upload=not args.dry_run, staging_root=staging_root,+ license_path=args.license_path, notice_path=args.notice_path,+ notes_file=args.notes_file, title=args.title)+ if args.manifest_out:+ args.manifest_out.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")+ log(f"[publish] manifest copy → {args.manifest_out}")+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/scripts/quantize_ltx.py b/scripts/quantize_ltx.pynew file mode 100644index 0000000..031b630--- /dev/null+++ b/scripts/quantize_ltx.py@@ -0,0 +1,1046 @@+#!/usr/bin/env python3+"""Phosphene's own bf16 -> q4/q8 quantizer for LTX (and LTX-shaped) weight packs.++WHY THIS EXISTS+---------------+Every quantized LTX pack a Phosphene user has ever downloaded was built by the+upstream MLX port author (``dgrauet``). We had *zero* weight-conversion tooling+of our own -- verified by the LTX-2.5 port plan (risk #1). If upstream does not+publish ``ltx-2.5-mlx-q4/q8``, we must build the packs ourselves, and the+install path depends on them. This script is that pipeline.++WHAT IT DOES+------------+Takes a **bf16 component already in MLX layout** (a DiT ``transformer-*.safetensors``,+a Gemma text encoder, an upscaler...) and writes a quantized pack in *exactly* the+on-disk layout the vendored loader consumes -- key names, per-file key prefixes,+``config.json`` / ``quantize_config.json`` / ``split_model.json``, and (for sharded+components) a correct ``model.safetensors.index.json``.++It is NOT the PyTorch->MLX converter. Input keys must already be MLX-layout.+That conversion is a separate, later step (port plan §2.2).++HOW IT WORKS+------------+One tensor at a time, start to finish:++* the source safetensors **header** is parsed directly (8-byte LE length + JSON),+ so the whole plan -- every output tensor's name, dtype, shape and byte count --+ is known in closed form *before a single byte is read*;+* each tensor is ``pread``-ed at its own offset, quantized on the **CPU stream**+ (``mx.stream(mx.cpu)`` -- the GPU quant stream is not bit-deterministic across+ runs; see the H3 rebuild findings this script's streaming design is adapted from),+ written straight to the output file, then dropped;+* the output safetensors is written **by hand** as a byte stream (header first,+ because the offsets are all known up front), so peak RSS is one tensor, not one+ pack. ``mx.save_safetensors`` would have to hold the entire 11-23 GB result in+ memory -- impossible on the 48 GB Macs the q4 pack is FOR.++Safety rails, all on by default:++* **disk preflight** -- refuses to start unless free space covers the planned+ output plus a margin;+* **atomic writes** -- everything lands as ``<name>.partial.safetensors`` and is+ ``os.replace``-d into place only after the full byte stream + fsync+ (``.partial.safetensors``, not ``.partial``: ``mx.load`` dispatches on the+ extension and rejects unknown ones, so a crashed run leaves a file that is+ still *loadable for inspection* but never mistaken for the real thing);+* **resume** -- ``--resume`` skips any output whose sha256 already matches the+ manifest; ``.partial.*`` leftovers are always deleted at start (clean restart);+* **self-validation** -- closed-form shape check on every quantized triple, a+ dequantize probe against the source (max abs / relative error), a strict+ ``safetensors.safe_open`` re-read, and an optional full loader round-trip;+* **manifest** -- ``phosphene_quant_manifest.json`` with per-file sha256, size,+ recipe, and tool version, so a published pack is verifiable after upload and+ can feed the panel's existing deep-verify path.++RECIPES+-------+A recipe says which modules get quantized and which stay bf16. The LTX one was+read off the shipped 2.3 packs, not guessed -- see ``RECIPES`` below.++USAGE+-----+Single component::++ python scripts/quantize_ltx.py \+ --src /path/to/ltx-2.5-mlx-bf16/transformer-distilled.safetensors \+ --out-dir /path/to/ltx-2.5-mlx-q4 \+ --recipe ltx-dit --bits 4++Whole pack (the real job)::++ python scripts/quantize_ltx.py \+ --from-pack /path/to/ltx-2.5-mlx-bf16 \+ --out-dir /path/to/ltx-2.5-mlx-q4 \+ --recipe ltx-dit --bits 4 --variants distilled++Sharded component (text encoder)::++ python scripts/quantize_ltx.py \+ --src /path/to/gemma4-12b-mlx-bf16 \+ --out-dir /path/to/gemma4-12b-mlx-q4 \+ --recipe ltx-te-gemma --bits 4 --layout sharded+"""++from __future__ import annotations++import argparse+import dataclasses+import hashlib+import json+import os+import re+import resource+import shutil+import struct+import sys+import time+from dataclasses import dataclass, field+from pathlib import Path+from typing import Any++import mlx.core as mx+import numpy as np++TOOL = "phosphene/quantize_ltx.py"+TOOL_VERSION = "1.0.0"++# safetensors dtype string -> (mlx dtype, bytes per element)+DTYPES: dict[str, tuple[Any, int]] = {+ "BF16": (mx.bfloat16, 2),+ "F16": (mx.float16, 2),+ "F32": (mx.float32, 4),+ "F64": (None, 8),+ "I64": (mx.int64, 8),+ "U64": (mx.uint64, 8),+ "I32": (mx.int32, 4),+ "U32": (mx.uint32, 4),+ "I16": (mx.int16, 2),+ "U16": (mx.uint16, 2),+ "I8": (mx.int8, 1),+ "U8": (mx.uint8, 1),+ "BOOL": (mx.bool_, 1),+}+MX_TO_ST = {+ mx.bfloat16: "BF16",+ mx.float16: "F16",+ mx.float32: "F32",+ mx.uint32: "U32",+ mx.int32: "I32",+ mx.uint8: "U8",+ mx.int8: "I8",+ mx.bool_: "BOOL",+}+QUANTIZABLE_SOURCE_DTYPES = {"BF16", "F16", "F32"}++# 128 MiB read/write chunk for verbatim copies + hashing.+CHUNK = 128 * 1024 * 1024+++# --------------------------------------------------------------------------- #+# Recipes+# --------------------------------------------------------------------------- #+@dataclass(frozen=True)+class Recipe:+ """Which modules get quantized, and how.++ A module is quantized when **all** of these hold:+ * its key ends in ``.weight``+ * the tensor is 2-D (Linear / Embedding weight)+ * the source dtype is a float type+ * the key starts with one of ``include_prefixes``+ * the key contains none of ``exclude_substrings``+ * ``in_features % group_size == 0`` (MLX requirement)++ Everything else is copied through byte-for-byte at its source dtype --+ norms, biases, scale/shift tables, patch/out projections, AdaLN.+ """++ name: str+ description: str+ include_prefixes: tuple[str, ...]+ exclude_substrings: tuple[str, ...] = ()+ group_size: int = 64+ # dtype the scales/biases are stored at in the shipped packs+ scales_dtype: str = "BF16"+ # per-file key prefix the vendored loader strips (documentation + assertion)+ loader_prefix: str | None = None+ # extra keys written into quantize_config.json's "quantization" block+ quant_config_extra: dict[str, Any] = field(default_factory=dict)+++RECIPES: dict[str, Recipe] = {+ # ---------------------------------------------------------------- LTX DiT+ # Extracted from the SHIPPED packs, not guessed:+ # mlx_models/ltx-2.3-mlx-q4/transformer-distilled.safetensors+ # mlx_models/ltx-2.3-mlx-q8/transformer-dev.safetensors+ # Both: 7450 tensors, 1632 quantized modules == 48 blocks x 34 linears,+ # group_size 64, scales/biases BF16, `.bias` kept BF16 alongside `.biases`,+ # every scale_shift_table left F32, and every module OUTSIDE+ # `transformer.transformer_blocks.` (patchify_proj, proj_out, all eight+ # *adaln_single* stacks) left BF16. That is exactly+ # quantize_config.json's `"only_transformer_blocks": true`.+ "ltx-dit": Recipe(+ name="ltx-dit",+ description="LTX-2.x DiT — quantize the 34 linears inside each transformer block; everything else bf16.",+ include_prefixes=("transformer.transformer_blocks.",),+ loader_prefix="transformer.",+ quant_config_extra={"only_transformer_blocks": True},+ ),+ # ------------------------------------------------------- LTX text encoder+ # Recipe read off mlx_models/gemma-3-12b-it-4bit (what 2.3 ships today):+ # group_size 64, bits 4, quantized set = every language-tower attention and+ # MLP projection PLUS embed_tokens; the vision tower is untouched (and we+ # never load it). For 2.5's custom Gemma 4 the tower dims are identical, so+ # the same prefixes apply -- add `model.language_model.` if the checkpoint+ # nests one level deeper.+ "ltx-te-gemma": Recipe(+ name="ltx-te-gemma",+ description="Gemma text tower — attention + MLP projections + embed_tokens; vision/audio towers untouched.",+ include_prefixes=(+ "language_model.model.layers.",+ "language_model.model.embed_tokens",+ "model.layers.",+ "model.embed_tokens",+ ),+ exclude_substrings=("vision_tower.", "audio_tower.", "vision_model."),+ ),+ # ------------------------------------------------------------- H3 (proof)+ # Not a shipping recipe. The LTX-shaped recipe transposed onto the H3+ # pruned DiT so the pipeline can be proven end-to-end at LTX scale+ # (38.5 GB quantizable) before the gated 2.5 weights land: quantize the+ # linears INSIDE the stacked blocks, leave the refiner (H3's analogue of+ # LTX's never-quantized connector), the patch/out projections and every+ # AdaLN projection alone -- the same shape of decision, key-for-key.+ "h3-dit-probe": Recipe(+ name="h3-dit-probe",+ description="PROOF ONLY — LTX-style recipe transposed onto the H3 pruned DiT.",+ include_prefixes=("blocks.",),+ exclude_substrings=("adaln",),+ ),+ # -------------------------------------------------------------- generic+ "all-linear": Recipe(+ name="all-linear",+ description="Every 2-D float .weight in the file. Use only when a real recipe does not exist yet.",+ include_prefixes=("",),+ ),+}+++def load_recipe(name_or_path: str) -> Recipe:+ """Resolve a built-in recipe name, or a JSON file overriding one."""+ if name_or_path in RECIPES:+ return RECIPES[name_or_path]+ p = Path(name_or_path)+ if not p.exists():+ raise SystemExit(f"unknown recipe {name_or_path!r}; known: {', '.join(sorted(RECIPES))} (or a .json path)")+ blob = json.loads(p.read_text())+ base = RECIPES.get(blob.get("base", ""), None)+ fields = dataclasses.asdict(base) if base else {}+ fields.update({k: v for k, v in blob.items() if k != "base"})+ for key in ("include_prefixes", "exclude_substrings"):+ if key in fields and fields[key] is not None:+ fields[key] = tuple(fields[key])+ fields.setdefault("name", p.stem)+ fields.setdefault("description", f"loaded from {p}")+ fields.setdefault("include_prefixes", ())+ return Recipe(**fields)+++# --------------------------------------------------------------------------- #+# safetensors primitives+# --------------------------------------------------------------------------- #+def read_header(path: Path) -> tuple[dict[str, dict], dict | None, int]:+ """Return (tensor_index, __metadata__, data_start_offset). Reads the header only."""+ with open(path, "rb") as f:+ raw_len = f.read(8)+ if len(raw_len) != 8:+ raise SystemExit(f"{path}: not a safetensors file (short read)")+ n = struct.unpack("<Q", raw_len)[0]+ head = json.loads(f.read(n))+ meta = head.pop("__metadata__", None)+ return head, meta, 8 + n+++def _nelems(shape: list[int]) -> int:+ out = 1+ for s in shape:+ out *= s+ return out+++def read_tensor(fh, data_start: int, entry: dict) -> mx.array:+ """Read ONE tensor's raw bytes and reinterpret them as an mx.array.++ Deliberately not ``mx.load`` — an explicit seek+read is the only way to+ make "peak RSS is one tensor" a property of the code rather than a hope+ about mmap and page-cache eviction.+ """+ off0, off1 = entry["data_offsets"]+ fh.seek(data_start + off0)+ buf = fh.read(off1 - off0)+ if len(buf) != off1 - off0:+ raise SystemExit(f"short read: wanted {off1 - off0} bytes, got {len(buf)}")+ mx_dtype, _ = DTYPES[entry["dtype"]]+ if mx_dtype is None:+ raise SystemExit(f"unsupported source dtype {entry['dtype']}")+ flat = mx.array(np.frombuffer(buf, dtype=np.uint8))+ return flat.view(mx_dtype).reshape(entry["shape"])+++def tensor_bytes(arr: mx.array) -> memoryview:+ """Raw little-endian byte buffer of an evaluated mx.array (no copy).++ ``.cast("B")`` flattens to 1-D bytes — a bare ``memoryview`` of a 2-D array+ reports ``len()`` as the ROW COUNT and a dtype-dependent format, which+ silently miscounts written bytes.+ """+ mv = memoryview(arr)+ if not mv.contiguous: # never happens for fresh reads / quantize outputs+ raise SystemExit("non-contiguous array reached the writer")+ return mv.cast("B")+++# --------------------------------------------------------------------------- #+# Planning+# --------------------------------------------------------------------------- #+@dataclass+class OutTensor:+ """One tensor in the output file, fully described before any byte is read."""++ key: str+ dtype: str+ shape: list[int]+ nbytes: int+ kind: str # "copy" | "q_weight" | "q_scales" | "q_biases"+ src_key: str+++@dataclass+class Plan:+ src: Path+ outputs: list[OutTensor]+ quantized_modules: list[str]+ skipped_unaligned: list[tuple[str, list[int]]]+ src_index: dict[str, dict]+ src_meta: dict | None+ data_start: int++ @property+ def total_bytes(self) -> int:+ return sum(t.nbytes for t in self.outputs)+++def build_plan(src: Path, recipe: Recipe, bits: int, limit: int | None = None) -> Plan:+ index, meta, data_start = read_header(src)+ gs = recipe.group_size+ scales_st = recipe.scales_dtype+ _, scales_width = DTYPES[scales_st]++ keys = sorted(index)+ if limit is not None:+ keys = keys[:limit]++ outputs: list[OutTensor] = []+ quantized: list[str] = []+ unaligned: list[tuple[str, list[int]]] = []++ for key in keys:+ entry = index[key]+ shape = list(entry["shape"])+ dtype = entry["dtype"]+ base = key[: -len(".weight")] if key.endswith(".weight") else None++ eligible = (+ base is not None+ and len(shape) == 2+ and dtype in QUANTIZABLE_SOURCE_DTYPES+ and any(base.startswith(p) for p in recipe.include_prefixes)+ and not any(x in key for x in recipe.exclude_substrings)+ )+ if eligible:+ out_f, in_f = shape+ if in_f % gs != 0:+ # MLX cannot group this row; the shipped packs leave such+ # layers bf16 too. Record it — silence here is how a pack+ # silently loses a layer.+ unaligned.append((key, shape))+ else:+ n_groups = in_f // gs+ packed_cols = in_f * bits // 32+ outputs.append(OutTensor(key, "U32", [out_f, packed_cols], out_f * packed_cols * 4, "q_weight", key))+ outputs.append(+ OutTensor(+ f"{base}.scales", scales_st, [out_f, n_groups], out_f * n_groups * scales_width, "q_scales", key+ )+ )+ outputs.append(+ OutTensor(+ f"{base}.biases", scales_st, [out_f, n_groups], out_f * n_groups * scales_width, "q_biases", key+ )+ )+ quantized.append(base)+ continue++ _, width = DTYPES[dtype]+ outputs.append(OutTensor(key, dtype, shape, _nelems(shape) * width, "copy", key))++ return Plan(src, outputs, quantized, unaligned, index, meta, data_start)+++# --------------------------------------------------------------------------- #+# Streaming writer+# --------------------------------------------------------------------------- #+def _partial_path(final: Path) -> Path:+ """``foo.safetensors`` -> ``foo.partial.safetensors``.++ The extension is preserved on purpose: ``mx.load`` dispatches on it and+ refuses unknown suffixes, so a crashed run leaves something inspectable+ rather than something opaque — and it can never be confused for the+ finished file, because the loader asks for the exact final name.+ """+ return final.with_name(f"{final.stem}.partial{final.suffix}")+++def sha256_file(path: Path) -> str:+ h = hashlib.sha256()+ with open(path, "rb") as f:+ while chunk := f.read(CHUNK):+ h.update(chunk)+ return h.hexdigest()+++def _peak_rss_gb() -> float:+ return resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1e9+++def _clear_cache() -> None:+ """Return MLX's pooled buffers to the OS between tensors."""+ fn = getattr(mx, "clear_cache", None)+ if fn is not None:+ fn()+++def write_quantized(+ plan: Plan,+ out_path: Path,+ recipe: Recipe,+ bits: int,+ *,+ stamp_metadata: bool,+ verbose: bool = True,+) -> tuple[str, dict]:+ """Stream the plan into ``out_path``. Returns (sha256, stats)."""+ partial = _partial_path(out_path)+ partial.unlink(missing_ok=True)++ # --- header, fully determined before the first byte of data ------------+ header: dict[str, Any] = {}+ if plan.src_meta or stamp_metadata:+ meta = dict(plan.src_meta or {})+ if stamp_metadata:+ # Deterministic ONLY. No timestamps here — two runs must be+ # byte-identical. Time goes in the sidecar manifest instead.+ meta["phosphene_quant"] = json.dumps(+ {+ "tool": TOOL,+ "tool_version": TOOL_VERSION,+ "recipe": recipe.name,+ "bits": bits,+ "group_size": recipe.group_size,+ "source_file": plan.src.name,+ },+ separators=(",", ":"),+ sort_keys=True,+ )+ header["__metadata__"] = meta++ cursor = 0+ for t in plan.outputs:+ header[t.key] = {"dtype": t.dtype, "shape": t.shape, "data_offsets": [cursor, cursor + t.nbytes]}+ cursor += t.nbytes++ header_bytes = json.dumps(header, separators=(",", ":")).encode()+ hasher = hashlib.sha256()+ t0 = time.time()+ written = 0+ n_q = 0++ # Group the plan by source key so each source tensor is read exactly once.+ by_src: dict[str, list[OutTensor]] = {}+ order: list[str] = []+ for t in plan.outputs:+ if t.src_key not in by_src:+ by_src[t.src_key] = []+ order.append(t.src_key)+ by_src[t.src_key].append(t)++ quantize_kwargs: dict[str, Any] = {"group_size": recipe.group_size, "bits": bits}+ scales_mx, _ = DTYPES[recipe.scales_dtype]++ with open(plan.src, "rb") as fsrc, open(partial, "wb") as fout:++ def emit(buf) -> None:+ nonlocal written+ fout.write(buf)+ hasher.update(buf)+ written += len(buf)++ emit(struct.pack("<Q", len(header_bytes)))+ emit(header_bytes)++ for i, src_key in enumerate(order):+ group = by_src[src_key]+ src_arr = read_tensor(fsrc, plan.data_start, plan.src_index[src_key])++ if group[0].kind == "copy":+ mx.eval(src_arr)+ emit(tensor_bytes(src_arr))+ else:+ # CPU stream: bit-deterministic across runs. The GPU quant+ # stream is not — that is the whole reason this is here.+ with mx.stream(mx.cpu):+ w, sc, bi = mx.quantize(src_arr, **quantize_kwargs)+ sc = sc.astype(scales_mx)+ bi = bi.astype(scales_mx)+ mx.eval(w, sc, bi)+ produced = {"q_weight": w, "q_scales": sc, "q_biases": bi}+ for t in group:+ arr = produced[t.kind]+ if list(arr.shape) != t.shape:+ raise SystemExit(+ f"{t.key}: planned shape {t.shape} != produced {list(arr.shape)} — plan/mlx disagree"+ )+ if MX_TO_ST.get(arr.dtype) != t.dtype:+ raise SystemExit(f"{t.key}: planned dtype {t.dtype} != produced {arr.dtype}")+ emit(tensor_bytes(arr))+ del w, sc, bi, produced+ n_q += 1++ del src_arr, group+ # MLX pools freed buffers; without this the pool grows to the size+ # of the largest few tensors x the allocator's high-water mark and+ # "RAM-bounded" stops meaning much on a 48 GB machine.+ _clear_cache()+ if verbose and (i % 200 == 0 or i == len(order) - 1):+ pct = 100.0 * written / max(1, len(header_bytes) + 8 + plan.total_bytes)+ print(+ f" [{i + 1}/{len(order)}] {pct:5.1f}% {written / 1e9:6.2f} GB "+ f"peakRSS {_peak_rss_gb():.2f} GB {time.time() - t0:6.0f}s",+ flush=True,+ )++ fout.flush()+ os.fsync(fout.fileno())++ expected = 8 + len(header_bytes) + plan.total_bytes+ if written != expected:+ partial.unlink(missing_ok=True)+ raise SystemExit(f"wrote {written} bytes, planned {expected} — refusing to publish a truncated pack")++ os.replace(partial, out_path)+ stats = {+ "seconds": round(time.time() - t0, 1),+ "bytes": written,+ "tensors_out": len(plan.outputs),+ "modules_quantized": n_q,+ "peak_rss_gb": round(_peak_rss_gb(), 2),+ }+ return hasher.hexdigest(), stats+++def copy_verbatim(src: Path, dst: Path, verbose: bool = True) -> tuple[str, int]:+ """Stream-copy a never-quantized component, hashing as we go."""+ partial = _partial_path(dst) if dst.suffix else dst.with_suffix(dst.suffix + ".partial")+ partial.unlink(missing_ok=True)+ h = hashlib.sha256()+ total = 0+ with open(src, "rb") as fi, open(partial, "wb") as fo:+ while chunk := fi.read(CHUNK):+ fo.write(chunk)+ h.update(chunk)+ total += len(chunk)+ fo.flush()+ os.fsync(fo.fileno())+ os.replace(partial, dst)+ if verbose:+ print(f" copied {dst.name} ({total / 1e9:.2f} GB)", flush=True)+ return h.hexdigest(), total+++# --------------------------------------------------------------------------- #+# Validation+# --------------------------------------------------------------------------- #+def validate_pack_file(+ src: Path,+ out_path: Path,+ plan: Plan,+ recipe: Recipe,+ bits: int,+ *,+ probes: int = 8,+) -> dict:+ """Re-open the written file and prove it means what the source meant.++ Three independent checks:+ 1. strict reader — ``safetensors.safe_open`` (the Rust validator, which+ enforces contiguous non-overlapping offsets) must accept the file;+ 2. header parity — every planned key/shape/dtype is present;+ 3. dequant probe — dequantize N quantized modules and compare against+ the ORIGINAL source tensor.+ """+ from safetensors import safe_open++ with safe_open(str(out_path), framework="numpy") as f:+ strict_keys = set(f.keys())++ out_index, _, _ = read_header(out_path)+ planned = {t.key: t for t in plan.outputs}+ missing = set(planned) - set(out_index)+ extra = set(out_index) - set(planned)+ if missing or extra:+ raise SystemExit(f"header parity failed — missing={sorted(missing)[:5]} extra={sorted(extra)[:5]}")+ if strict_keys != set(planned):+ raise SystemExit("safetensors strict reader disagrees with our header")+ for k, t in planned.items():+ got = out_index[k]+ if list(got["shape"]) != t.shape or got["dtype"] != t.dtype:+ raise SystemExit(f"{k}: shape/dtype mismatch {got} vs {t}")++ q_modules = plan.quantized_modules+ if not q_modules:+ return {"probes": 0, "note": "no quantized modules in this file"}++ step = max(1, len(q_modules) // max(1, probes))+ chosen = q_modules[::step][:probes]+ worst_abs, worst_rel, worst_key = 0.0, 0.0, ""+ with open(src, "rb") as fsrc, open(out_path, "rb") as fout:+ out_start = read_header(out_path)[2]+ for base in chosen:+ ref = read_tensor(fsrc, plan.data_start, plan.src_index[base + ".weight"]).astype(mx.float32)+ w = read_tensor(fout, out_start, out_index[base + ".weight"])+ sc = read_tensor(fout, out_start, out_index[base + ".scales"]).astype(mx.float32)+ bi = read_tensor(fout, out_start, out_index[base + ".biases"]).astype(mx.float32)+ with mx.stream(mx.cpu):+ deq = mx.dequantize(w, sc, bi, group_size=recipe.group_size, bits=bits)+ err = mx.abs(deq - ref)+ a = float(mx.max(err))+ scale = float(mx.mean(mx.abs(ref))) or 1.0+ r = float(mx.mean(err)) / scale+ if a > worst_abs:+ worst_abs, worst_key = a, base+ worst_rel = max(worst_rel, r)+ del ref, w, sc, bi, deq, err+ _clear_cache()++ # Empirical ceilings for affine group quantization of a normal-ish weight+ # matrix: q4 keeps ~4 bits of a 64-wide group, q8 ~8. A blown budget here+ # means the wrong tensor was read or the group size is wrong — not noise.+ limit = 0.35 if bits == 4 else 0.12+ if worst_rel > limit:+ raise SystemExit(f"dequant probe: mean relative error {worst_rel:.4f} > {limit} — refusing to accept pack")+ return {+ "probes": len(chosen),+ "worst_max_abs_err": round(worst_abs, 6),+ "worst_mean_rel_err": round(worst_rel, 6),+ "worst_module": worst_key,+ "rel_err_limit": limit,+ }+++def add_vendored_to_path() -> None:+ """Make the vendored ltx-2-mlx packages importable without installing them."""+ for pkg in ("ltx-core-mlx", "ltx-pipelines-mlx"):+ p = str(_vendored_src(pkg))+ if p not in sys.path:+ sys.path.insert(0, p)+++def _pack_config(out_path: Path) -> Any:+ """The written pack's own architecture, or ``None`` if it declares none.++ Prefers the safetensors header (LTX-2.5 carries ``__metadata__["config"]``+ with the weights) and falls back to the sibling ``config.json`` /+ ``embedded_config.json`` that 2.3-era packs use. Returning ``None`` keeps+ the pre-2.5 behaviour — hardcoded defaults — for a checkpoint that says+ nothing about itself.+ """+ from ltx_core_mlx.model.transformer.model import LTXModelConfig++ for reader, arg in (+ (getattr(LTXModelConfig, "from_checkpoint_file", None), out_path),+ (getattr(LTXModelConfig, "from_checkpoint_dir", None), out_path.parent),+ ):+ if reader is None:+ continue+ try:+ cfg = reader(arg)+ except Exception:+ continue+ if cfg is not None:+ return cfg+ return None+++def verify_load_ltx_dit(out_path: Path, config: Any = None) -> dict:+ """Full round-trip through the VENDORED loader.++ Mirrors ``ltx_pipelines_mlx.utils._orchestration.load_transformer`` exactly+ (``load_split_safetensors`` -> ``apply_quantization`` -> ``load_weights``+ -> ``mx.eval``, lines 102-115). The ONLY difference is that ``config`` may+ be supplied, so a tiny synthetic pack can be round-tripped without+ instantiating the real 48-layer / 4096-dim DiT. Pass ``None`` for the+ production shape.+ """+ add_vendored_to_path()+ from ltx_core_mlx.model.transformer.model import LTXModel, LTXModelConfig+ from ltx_core_mlx.utils.weights import _detect_quantization_bits, apply_quantization, load_split_safetensors++ weights = load_split_safetensors(out_path, prefix="transformer.")+ if config is None:+ # Build the reference model from the CHECKPOINT's architecture, not+ # from the dataclass defaults. The defaults are LTX-2.3's, and the+ # generation-varying flags are exactly the ones that decide which+ # parameters exist — so defaulting here would fail a correct 2.5 pack+ # and, worse, would pass a 2.5 pack that had silently lost them.+ config = _pack_config(out_path)+ dit = LTXModel(config) if config is not None else LTXModel()+ detected = _detect_quantization_bits(weights)+ apply_quantization(dit, weights)+ dit.load_weights(list(weights.items()))+ mx.eval(dit.parameters())+ return {"loaded": True, "n_weights": len(weights), "loader_detected_bits": detected}+++def _vendored_src(pkg: str) -> Path:+ """Where to import the LTX packages from.++ Defaults to the app's own checkout, which is pinned to a released tag and+ must stay that way — ``install.js`` and ``update.js`` both ``git checkout``+ it, and the live panel runs out of that venv.++ ``LTX_MLX_SRC`` points this at a different working tree. That is not a+ convenience: a checkpoint generation newer than the pinned tag cannot be+ round-tripped against the pinned tag at all. LTX-2.5 ships+ ``keyframes_abs_pos_embedding``, which a v0.14.19 ``LTXModel`` does not+ build, so the verification would report a "parameter not in model" error+ that says nothing about the pack — the pack is fine, the reference model is+ simply older than the weights.+ """+ override = os.environ.get("LTX_MLX_SRC")+ root = Path(override).expanduser() if override else Path(__file__).resolve().parents[1] / "ltx-2-mlx"+ return root / "packages" / pkg / "src"+++# --------------------------------------------------------------------------- #+# Pack-level artifacts+# --------------------------------------------------------------------------- #+MANIFEST_NAME = "phosphene_quant_manifest.json"+++def load_manifest(out_dir: Path) -> dict:+ p = out_dir / MANIFEST_NAME+ if p.exists():+ return json.loads(p.read_text())+ return {"tool": TOOL, "tool_version": TOOL_VERSION, "files": {}}+++def save_manifest(out_dir: Path, manifest: dict) -> None:+ manifest["written_utc"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())+ (out_dir / MANIFEST_NAME).write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")+++def write_quantize_config(out_dir: Path, recipe: Recipe, bits: int) -> None:+ """Emit ``quantize_config.json`` in the shipped 2.3 shape."""+ block: dict[str, Any] = {"bits": bits, "group_size": recipe.group_size}+ block.update(recipe.quant_config_extra)+ (out_dir / "quantize_config.json").write_text(json.dumps({"quantization": block}, indent=2) + "\n")+++def patch_split_model(out_dir: Path, bits: int) -> None:+ """Mark ``split_model.json`` as quantized at these bits (2.3 pack does this)."""+ p = out_dir / "split_model.json"+ if not p.exists():+ return+ blob = json.loads(p.read_text())+ blob["quantized"] = True+ blob["quantization_bits"] = bits+ p.write_text(json.dumps(blob, indent=2, ensure_ascii=False) + "\n")+++def write_shard_index(out_dir: Path, weight_map: dict[str, str], total_size: int) -> None:+ """Emit ``model.safetensors.index.json`` for a sharded component.++ NOTE: ``mlx_models/gemma-3-12b-it-4bit`` ships a STALE index inherited from+ its bf16 parent — it names five shards that do not exist and a total_size of+ 24 GB against an 8 GB pack. Ours is generated from what we actually wrote.+ """+ (out_dir / "model.safetensors.index.json").write_text(+ json.dumps({"metadata": {"total_size": total_size}, "weight_map": weight_map}, indent=2) + "\n"+ )+++def preflight_disk(out_dir: Path, need_bytes: int, margin_gb: float = 5.0) -> None:+ out_dir.mkdir(parents=True, exist_ok=True)+ free = shutil.disk_usage(out_dir).free+ need = need_bytes + int(margin_gb * 1e9)+ if free < need:+ raise SystemExit(+ f"disk preflight FAILED: need {need / 1e9:.1f} GB "+ f"(output {need_bytes / 1e9:.1f} GB + {margin_gb:.0f} GB margin), "+ f"free {free / 1e9:.1f} GB on {out_dir}"+ )+ print(f"disk preflight OK: need {need / 1e9:.1f} GB, free {free / 1e9:.1f} GB", flush=True)+++def clean_partials(out_dir: Path) -> int:+ n = 0+ if out_dir.exists():+ for p in out_dir.glob("*.partial*"):+ p.unlink()+ n += 1+ return n+++# --------------------------------------------------------------------------- #+# Drivers+# --------------------------------------------------------------------------- #+def quantize_one(+ src: Path,+ out_dir: Path,+ out_name: str,+ recipe: Recipe,+ bits: int,+ args: argparse.Namespace,+ manifest: dict,+) -> None:+ out_path = out_dir / out_name+ plan = build_plan(src, recipe, bits, limit=args.limit)++ print(f"\n=== {src.name} -> {out_name} [{recipe.name} q{bits} g{recipe.group_size}] ===", flush=True)+ print(+ f" source {src.stat().st_size / 1e9:.2f} GB, {len(plan.src_index)} tensors; "+ f"plan {len(plan.outputs)} out-tensors, {len(plan.quantized_modules)} modules quantized, "+ f"{plan.total_bytes / 1e9:.2f} GB out",+ flush=True,+ )+ if plan.skipped_unaligned:+ print(+ f" NOTE: {len(plan.skipped_unaligned)} eligible weights left bf16 "+ f"(in_features not a multiple of {recipe.group_size}): "+ f"{', '.join(k for k, _ in plan.skipped_unaligned[:3])}",+ flush=True,+ )++ prev = manifest["files"].get(out_name)+ if args.resume and out_path.exists() and prev and prev.get("sha256"):+ if sha256_file(out_path) == prev["sha256"]:+ print(" resume: existing file matches manifest sha256 — skipping", flush=True)+ return+ print(" resume: sha mismatch — rewriting", flush=True)++ if not args.no_preflight:+ preflight_disk(out_dir, plan.total_bytes)++ sha, stats = write_quantized(plan, out_path, recipe, bits, stamp_metadata=not args.no_stamp)+ print(+ f" wrote {out_name}: {stats['bytes'] / 1e9:.2f} GB in {stats['seconds']}s "+ f"(peak RSS {stats['peak_rss_gb']} GB)",+ flush=True,+ )++ val = validate_pack_file(src, out_path, plan, recipe, bits, probes=args.probes)+ print(f" validate: {json.dumps(val)}", flush=True)++ if args.verify_load == "ltx-dit":+ print(f" loader round-trip: {json.dumps(verify_load_ltx_dit(out_path))}", flush=True)++ manifest["files"][out_name] = {+ "sha256": sha,+ "bytes": stats["bytes"],+ "source": src.name,+ "source_sha256_prefix": None,+ "recipe": recipe.name,+ "bits": bits,+ "group_size": recipe.group_size,+ "modules_quantized": stats["modules_quantized"],+ "tensors": stats["tensors_out"],+ "seconds": stats["seconds"],+ "peak_rss_gb": stats["peak_rss_gb"],+ "validation": val,+ }+ save_manifest(out_dir, manifest)+++def quantize_sharded(+ src_dir: Path,+ out_dir: Path,+ recipe: Recipe,+ bits: int,+ args: argparse.Namespace,+ manifest: dict,+) -> None:+ """Sharded component (text encoder): one output shard per input shard."""+ shards = sorted(src_dir.glob("*.safetensors"))+ if not shards:+ raise SystemExit(f"no .safetensors in {src_dir}")+ plans = [(s, build_plan(s, recipe, bits, limit=args.limit)) for s in shards]+ total = sum(p.total_bytes for _, p in plans)+ if not args.no_preflight:+ preflight_disk(out_dir, total)++ weight_map: dict[str, str] = {}+ written_total = 0+ for i, (s, plan) in enumerate(plans, 1):+ name = f"model-{i:05d}-of-{len(plans):05d}.safetensors"+ print(f"\n=== {s.name} -> {name} [{recipe.name} q{bits}] ===", flush=True)+ sha, stats = write_quantized(plan, out_dir / name, recipe, bits, stamp_metadata=not args.no_stamp)+ val = validate_pack_file(s, out_dir / name, plan, recipe, bits, probes=args.probes)+ print(f" wrote {name} {stats['bytes'] / 1e9:.2f} GB; validate {json.dumps(val)}", flush=True)+ for t in plan.outputs:+ weight_map[t.key] = name+ written_total += stats["bytes"]+ manifest["files"][name] = {+ "sha256": sha,+ "bytes": stats["bytes"],+ "source": s.name,+ "recipe": recipe.name,+ "bits": bits,+ "group_size": recipe.group_size,+ "validation": val,+ }++ write_shard_index(out_dir, weight_map, written_total)+ # mlx-lm reads the quantization block out of config.json, not a sidecar.+ cfg_path = src_dir / "config.json"+ if cfg_path.exists():+ cfg = json.loads(cfg_path.read_text())+ cfg["quantization"] = {"group_size": recipe.group_size, "bits": bits}+ (out_dir / "config.json").write_text(json.dumps(cfg, indent=2) + "\n")+ for extra in ("tokenizer.json", "tokenizer_config.json", "special_tokens_map.json", "tokenizer.model"):+ p = src_dir / extra+ if p.exists():+ sha, n = copy_verbatim(p, out_dir / extra)+ manifest["files"][extra] = {"sha256": sha, "bytes": n, "source": extra, "recipe": "verbatim"}+ save_manifest(out_dir, manifest)+++TRANSFORMER_RE = re.compile(r"^transformer(-(?P<variant>[a-z0-9_]+))?\.safetensors$")+++def from_pack(src_dir: Path, out_dir: Path, recipe: Recipe, bits: int, args: argparse.Namespace) -> None:+ """Build a whole quantized LTX pack from a bf16 MLX-layout pack directory."""+ out_dir.mkdir(parents=True, exist_ok=True)+ manifest = load_manifest(out_dir)+ manifest["recipe"] = recipe.name+ manifest["bits"] = bits+ manifest["group_size"] = recipe.group_size+ manifest["source_pack"] = str(src_dir)++ variants = set(args.variants.split(",")) if args.variants else None+ transformers: list[Path] = []+ passthrough: list[Path] = []+ for p in sorted(src_dir.iterdir()):+ if p.is_dir() or p.name.startswith("."):+ continue+ m = TRANSFORMER_RE.match(p.name)+ if m:+ v = m.group("variant") or "default"+ if variants is None or v in variants:+ transformers.append(p)+ else:+ print(f"skipping transformer variant {v!r} (not in --variants)", flush=True)+ continue+ passthrough.append(p)++ if not transformers:+ raise SystemExit(f"no transformer*.safetensors selected in {src_dir}")++ plans_bytes = sum(build_plan(p, recipe, bits, limit=args.limit).total_bytes for p in transformers)+ copy_bytes = sum(p.stat().st_size for p in passthrough)+ if not args.no_preflight:+ preflight_disk(out_dir, plans_bytes + copy_bytes)++ for p in transformers:+ quantize_one(p, out_dir, p.name, recipe, bits, args, manifest)++ print("\n=== verbatim components (never quantized in the shipped packs) ===", flush=True)+ for p in passthrough:+ dst = out_dir / p.name+ prev = manifest["files"].get(p.name)+ if args.resume and dst.exists() and prev and prev.get("sha256") == sha256_file(dst):+ print(f" resume: {p.name} already present", flush=True)+ continue+ sha, n = copy_verbatim(p, dst)+ manifest["files"][p.name] = {"sha256": sha, "bytes": n, "source": p.name, "recipe": "verbatim"}++ write_quantize_config(out_dir, recipe, bits)+ patch_split_model(out_dir, bits)+ for extra in ("quantize_config.json", "split_model.json"):+ pp = out_dir / extra+ if pp.exists():+ manifest["files"][extra] = {+ "sha256": sha256_file(pp),+ "bytes": pp.stat().st_size,+ "recipe": "generated",+ }+ save_manifest(out_dir, manifest)+ print(f"\nPACK COMPLETE -> {out_dir}", flush=True)+++# --------------------------------------------------------------------------- #+def main(argv: list[str] | None = None) -> None:+ ap = argparse.ArgumentParser(+ description="Quantize MLX-layout LTX weights to a loader-ready q4/q8 pack.",+ formatter_class=argparse.RawDescriptionHelpFormatter,+ epilog="recipes: " + "\n ".join(f"{k:14s} {v.description}" for k, v in RECIPES.items()),+ )+ g = ap.add_mutually_exclusive_group(required=True)+ g.add_argument("--src", type=Path, help="single bf16 component (.safetensors) or a sharded dir with --layout sharded")+ g.add_argument("--from-pack", type=Path, help="a bf16 MLX-layout pack dir; quantize transformers, copy the rest")+ ap.add_argument("--out-dir", type=Path, required=True)+ ap.add_argument("--out-name", help="output filename for --src (default: same as source)")+ ap.add_argument("--recipe", default="ltx-dit", help="built-in recipe name or path to a recipe .json")+ ap.add_argument("--bits", type=int, default=4, choices=[2, 3, 4, 5, 6, 8])+ ap.add_argument("--group-size", type=int, default=None, help="override the recipe group size")+ ap.add_argument("--layout", choices=["single", "sharded"], default="single")+ ap.add_argument("--variants", default=None, help="comma list of transformer variants for --from-pack, e.g. distilled")+ ap.add_argument("--limit", type=int, default=None, help="only the first N source tensors (determinism/subset runs)")+ ap.add_argument("--probes", type=int, default=8, help="how many modules to dequant-probe during validation")+ ap.add_argument("--verify-load", choices=["none", "ltx-dit"], default="none", help="full vendored-loader round trip")+ ap.add_argument("--resume", action="store_true", help="skip outputs whose sha256 already matches the manifest")+ ap.add_argument("--no-preflight", action="store_true")+ ap.add_argument("--no-stamp", action="store_true", help="do not add phosphene provenance to safetensors metadata")+ args = ap.parse_args(argv)++ recipe = load_recipe(args.recipe)+ if args.group_size:+ recipe = dataclasses.replace(recipe, group_size=args.group_size)++ args.out_dir.mkdir(parents=True, exist_ok=True)+ n = clean_partials(args.out_dir)+ if n:+ print(f"cleaned {n} leftover .partial file(s)", flush=True)++ t0 = time.time()+ if args.from_pack:+ from_pack(args.from_pack, args.out_dir, recipe, args.bits, args)+ elif args.layout == "sharded":+ manifest = load_manifest(args.out_dir)+ manifest.update({"recipe": recipe.name, "bits": args.bits, "group_size": recipe.group_size})+ quantize_sharded(args.src, args.out_dir, recipe, args.bits, args, manifest)+ else:+ manifest = load_manifest(args.out_dir)+ manifest.update({"recipe": recipe.name, "bits": args.bits, "group_size": recipe.group_size})+ quantize_one(args.src, args.out_dir, args.out_name or args.src.name, recipe, args.bits, args, manifest)+ if recipe.quant_config_extra or recipe.name.startswith("ltx-"):+ write_quantize_config(args.out_dir, recipe, args.bits)+ patch_split_model(args.out_dir, args.bits)+ save_manifest(args.out_dir, manifest)++ print(f"\nDONE in {time.time() - t0:.0f}s — peak RSS {_peak_rss_gb():.2f} GB", flush=True)+++if __name__ == "__main__":+ main()diff --git a/scripts/test_analytics_dryrun.py b/scripts/test_analytics_dryrun.pyindex 9679abb..d325a3d 100644--- a/scripts/test_analytics_dryrun.py+++ b/scripts/test_analytics_dryrun.py@@ -9,21 +9,34 @@ run on a machine that is mid-render without touching anything.What it is actually here to prove, in priority order:- 1. NOTHING FIRES WITH NO KEY. The public tree ships ANALYTICS_KEY_DEFAULT- = "", and that must mean zero sockets — not "a request that fails".+ 1. THE OFF SWITCH IS THE OFF SWITCH. Since acfbdc7 the tree ships a live+ phc_ project key, so a stock install reports by default — which makes+ the toggle (and PHOSPHENE_ANALYTICS_DISABLED) the only thing standing+ between a user who said no and a socket. Both must produce zero+ sockets AND zero local-log lines. Clearing the key field is NOT an+ opt-out and is asserted not to be mistaken for one.2. NOTHING LEAKS. No prompt, path, filename or media string may appear inany outgoing payload, including via the one free-text field(error_signature) and including when a caller is careless.3. THE SCHEMA IS THE SCHEMA. Each event's property set is asserted- field-by-field against docs/ANALYTICS.md, so the doc can't silently- drift from the code.+ field-by-field against docs/ANALYTICS.md, and every event name the+ panel can fire is asserted to appear in that page — app_installed+ shipped undocumented for two releases and this is the guard for it.4. IT CANNOT BREAK A RENDER. Capture never raises, even on garbage inputand even when the transport blows up.++A note for whoever edits this file next: the three assertions that used to+sit under a heading called "inert without a key" were correct until+2026-08-09 and false afterwards, and a RED suite protects nothing. They+were rewritten (not deleted) on 2026-08-12 to pin the posture that actually+shipped. If a future commit changes the posture again, rewrite them again —+deleting a guard is how the drift goes unnoticed the next time."""from __future__ import annotationsimport jsonimport os+import reimport sysimport tempfileimport threading@@ -105,7 +118,10 @@ def drain(timeout: float = 5.0) -> None:class AnalyticsTestCase(unittest.TestCase):- """Common fixture: clean state dir, spy installed, analytics ON, no key."""+ """Common fixture: clean state dir, spy installed, analytics ON, and no+ key OVERRIDE — which is the stock-install case, since an empty+ `analytics_key` falls back to the shipped ANALYTICS_KEY_DEFAULT.+ Subclasses that want a predictable key on the wire set their own."""def setUp(self):self.spy = Spy()@@ -133,24 +149,68 @@ class AnalyticsTestCase(unittest.TestCase):# ---------------------------------------------------------------------------# 1. Inert without a key+# 1. The shipped key, and the two things that switch it off# ---------------------------------------------------------------------------class TestInertWithoutKey(AnalyticsTestCase):-- def test_shipped_default_key_is_empty(self):- """The public tree must never carry a real key."""- self.assertEqual(P.ANALYTICS_KEY_DEFAULT, "")-- def test_no_key_means_no_socket(self):+class TestShippedKeyAndOptOut(AnalyticsTestCase):++ def test_shipped_key_is_a_write_only_project_key(self):+ """What ships must be a phc_ PROJECT key: write-only, able to send+ events and nothing else, which is what makes committing it to a+ source-distributed app defensible (docs/ANALYTICS.md says exactly+ this to users). The failure this guards is not "a key exists" — it+ is a READ-capable personal key (phx_/phs_) reaching the tree, which+ would hand every cloner the whole project's data."""+ key = P.ANALYTICS_KEY_DEFAULT+ self.assertTrue(key.startswith("phc_"),+ f"shipped capture key is not a phc_ project key: {key[:8]!r}...")+ self.assertGreaterEqual(len(key), 32, "shipped key looks truncated")+ for readable in ("phx_", "phs_"):+ self.assertFalse(key.startswith(readable),+ "a READ-capable personal key must never be committed")+ # The stock-install path: no env override, no saved override.+ self.assertEqual(P._analytics_key(), key,+ "an empty analytics_key setting must fall back to the "+ "shipped key — it is an override field, not a switch")++ def test_opt_out_is_the_toggle_not_the_key(self):+ """The whole post-acfbdc7 contract in one test, in the order a user+ would discover it: a stock install really does send under the+ shipped key; clearing the key field really does NOT stop that; the+ toggle really does, for the socket and the local mirror alike."""+ # 1. Stock install -> exactly one POST, carrying the shipped key.P._analytics_capture("app_boot", {"version": "3.4.1"})drain()- self.assertEqual(self.spy.calls, [],- "analytics opened a socket with no key configured")+ self.assertEqual(len(self.spy.calls), 1,+ "a stock install must report — the project key ships")+ self.assertEqual(self.spy.bodies[0]["api_key"], P.ANALYTICS_KEY_DEFAULT,+ "the shipped key must be the one on the wire")- def test_no_key_still_writes_the_local_mirror(self):- """The local log is the always-on debugging view; it does not- depend on a PostHog key."""+ # 2. Clearing the key field is not an opt-out, and the doc says so.+ self.configure(analytics_key="")+ P._analytics_capture("app_boot", {"version": "3.4.1"})+ drain()+ self.assertEqual(len(self.spy.calls), 2,+ "an empty analytics_key means 'no override', not 'off'; "+ "if this ever becomes an off switch, fix docs/ANALYTICS.md "+ "in the same commit")++ # 3. The toggle is. Nothing on the wire, nothing in the mirror —+ # _analytics_capture() returns before it builds a payload.+ rows_before = len(self.log_lines())+ self.configure(analytics_enabled=False)+ P._analytics_capture("app_boot", {"version": "3.4.1"})+ P._analytics_render_event({"status": "done", "params": {"mode": "t2v"}})+ drain()+ self.assertEqual(len(self.spy.calls), 2,+ "opt-out must open no socket, shipped key or not")+ self.assertEqual(len(self.log_lines()), rows_before,+ "opt-out must stop the local log too")++ def test_every_capture_writes_the_local_mirror(self):+ """The local log is the always-on audit view: it is written before+ the network is touched, so the user can read back exactly what left+ (or would have left, when the endpoint was down)."""P._analytics_capture("app_boot", {"version": "3.4.1"})drain()rows = self.log_lines()@@ -158,6 +218,8 @@ class TestInertWithoutKey(AnalyticsTestCase):self.assertEqual(rows[0]["event"], "app_boot")def test_disabled_writes_nothing_anywhere(self):+ """Same guarantee as above via _analytics_boot()'s three call sites,+ with the shipped key live — this is the stock user who said no."""self.configure(analytics_enabled=False)P._analytics_capture("app_boot", {"version": "3.4.1"})P._analytics_render_event({"status": "done", "params": {"mode": "t2v"}})@@ -388,10 +450,21 @@ class TestEventSchemas(AnalyticsTestCase):self.configure(analytics_key="phc_fake_key_for_tests")def props_of(self, event: str) -> dict:+ """This event's own properties, with the receiver directives removed.++ The $-prefixed keys are instructions to PostHog, not part of an+ event's schema — they are asserted as a set, on every event, in+ TestReceiverDirectives. Anything else beginning with $ is a key+ nobody declared, so fail on it here rather than let it ride along+ into the next schema that gets written."""for body in self.spy.bodies:if body["event"] == event:p = dict(body["properties"])- p.pop("$process_person_profile", None)+ for k in P._ANALYTICS_RECEIVER_DIRECTIVES:+ p.pop(k, None)+ stray = sorted(k for k in p if k.startswith("$"))+ self.assertEqual(stray, [], f"undeclared receiver key(s) on "+ f"{event}: {stray}")return pself.fail(f"no {event} event was captured")@@ -428,7 +501,7 @@ class TestEventSchemas(AnalyticsTestCase):P._analytics_render_event({"status": "failed", "error": "OOM during VAE decode","elapsed_sec": 61.0,- "params": {"mode": "i2v", "engine": "h3", "h3_tier": "5s",+ "params": {"mode": "i2v", "engine": "h3", "h3_tier": "hq_5s","width": 1280, "height": 720, "frames": 90},})drain()@@ -436,9 +509,38 @@ class TestEventSchemas(AnalyticsTestCase):self.assertEqual(set(p), {"engine", "mode", "tier", "duration_bucket", "resolution","frames", "error_signature"})- self.assertEqual(p["tier"], "5s", "H3 jobs report h3_tier as tier")+ # h3_tier is the wire format, and every legacy key still resolves to+ # the cell it means: the quality x length refactor renamed hq_5s to+ # standard_5s, and a job replayed from an older sidecar must land in+ # that bucket rather than inventing one. (The fixture here used to be+ # "5s", which is a LENGTH and was never a tier key — see+ # test_unrecognised_h3_tier_collapses_to_unknown for where it goes.)+ self.assertEqual(p["tier"], "standard_5s",+ "a legacy h3_tier must resolve to its current cell")self.assertEqual(p["duration_bucket"], "<2m")+ def test_app_installed_fields(self):+ """Fires once per install, ever, immediately before its first+ app_boot. Documented in docs/ANALYTICS.md since 2026-08-12 — it had+ been shipping and firing unnamed there, which by that page's own+ opening rule was a bug."""+ self.configure(analytics_install_reported=False)+ P._analytics_boot()+ drain()+ p = self.props_of("app_installed")+ self.assertEqual(set(p), {"version", "chip_family", "ram_gb"})+ self.assertIsInstance(p["ram_gb"], int)+ self.assertEqual([b["event"] for b in self.spy.bodies][:2],+ ["app_installed", "app_boot"],+ "app_installed must precede the first app_boot")+ # Once ever: the flag is persisted, so a reboot never re-counts.+ self.assertTrue(P.get_settings().get("analytics_install_reported"))+ self.spy.calls.clear()+ P._analytics_boot()+ drain()+ self.assertNotIn("app_installed", [b["event"] for b in self.spy.bodies],+ "app_installed re-fired on a second boot")+def test_cancelled_jobs_are_not_reported(self):P._analytics_render_event({"status": "cancelled", "params": {"mode": "t2v"}})drain()@@ -489,9 +591,150 @@ class TestBucketsAndParsing(unittest.TestCase):got = P._analytics_chip_family()self.assertRegex(got, r"^(M\d+( (Pro|Max|Ultra))?|unknown|non-apple-silicon)$")+ def test_unrecognised_h3_tier_collapses_to_unknown(self):+ """Closed vocabulary: a tier key the panel does not recognise becomes+ "unknown" rather than riding through as free text. Every string we+ transmit has to be drawn from a set defined in the source, or the+ "no free text" promise is only true of the fields we remembered."""+ for bogus in ("5s", "not_a_tier_at_all", "", None):+ self.assertEqual(+ P._analytics_render_tier({"h3_tier": bogus}, "h3"), "unknown",+ f"unrecognised h3_tier {bogus!r} escaped the vocabulary")+++class TestDocumentationParity(unittest.TestCase):+ """docs/ANALYTICS.md opens with "If the panel ever sends something that+ isn't listed here, that's a bug." app_installed was exactly that bug, for+ two releases, because nothing checked. This makes the promise executable:+ every event name the panel can capture must be named on that page."""++ def test_every_event_the_panel_fires_is_documented(self):+ src = (REPO / "mlx_ltx_panel.py").read_text(encoding="utf-8")+ fired = set(re.findall(r'_analytics_capture\(\s*"([a-z_]+)"', src))+ self.assertTrue(fired, "no literal event names found — did the call "+ "sites stop passing string literals?")+ doc = (REPO / "docs" / "ANALYTICS.md").read_text(encoding="utf-8")+ for name in sorted(fired):+ self.assertIn(f"`{name}`", doc,+ f"{name} is captured by the panel but docs/"+ f"ANALYTICS.md never names it")+++# --------------------------------------------------------------------------+# 5. Receiver directives — the things every event tells PostHog NOT to do+# --------------------------------------------------------------------------++class TestReceiverDirectives(AnalyticsTestCase):+ """The panel sends no location field. It also has to stop the receiver+ deriving one, which is a different promise and needs its own guard.++ Three $-prefixed keys ride on every payload: no person profile, no GeoIP+ enrichment, and an $ip the panel supplies itself so the connecting+ address is never written onto the stored event. All three are attached+ centrally in _analytics_post — which is exactly why this fires EVERY+ event type rather than a representative one. A refactor that built a+ payload anywhere else would drop all three at once, silently, and+ nothing else in this suite would notice."""++ def setUp(self):+ super().setUp()+ self.configure(analytics_key="phc_fake_key_for_tests",+ analytics_install_reported=False)++ def fire_every_event(self) -> dict[str, dict]:+ """One of each event the panel can emit → {event: properties}."""+ packs = dict(P._analytics_pack_state())+ self.configure(analytics_last_packs=dict(packs, h3=not packs["h3"]))+ P._analytics_boot() # app_installed + app_boot + pack_state_change+ P._analytics_render_event({+ "status": "done", "elapsed_sec": 120.0,+ "params": {"mode": "t2v", "engine": "ltx", "quality": "standard",+ "width": 1216, "height": 704, "frames": 121}})+ P._analytics_render_event({+ "status": "failed", "error": "OOM during VAE decode",+ "elapsed_sec": 30.0,+ "params": {"mode": "i2v", "engine": "h3", "h3_tier": "hq_5s"}})+ drain()+ seen = {b["event"]: b["properties"] for b in self.spy.bodies}+ # Coverage, read off the source rather than trusted: if someone adds a+ # sixth event type, this test must be taught to fire it instead of+ # quietly checking five out of six.+ src = (REPO / "mlx_ltx_panel.py").read_text(encoding="utf-8")+ firable = set(re.findall(r'_analytics_capture\(\s*"([a-z_]+)"', src))+ self.assertEqual(sorted(firable - set(seen)), [],+ "an event type exists that this test never fires, so "+ "its payload goes unchecked — add it above")+ return seen++ def test_every_event_carries_every_receiver_directive(self):+ for event, props in self.fire_every_event().items():+ self.assertEqual(+ {k: props.get(k) for k in P._ANALYTICS_RECEIVER_DIRECTIVES},+ dict(P._ANALYTICS_RECEIVER_DIRECTIVES),+ f"{event} reached the wire without the directives intact")+ self.assertIs(props["$geoip_disable"], True,+ f"{event} would be geolocated by the receiver")+ self.assertIs(props["$process_person_profile"], False,+ f"{event} would build a person profile")++ def test_no_location_property_is_sent_or_invited(self):+ """We add no location field, and $geoip_disable is the only $geoip_*+ key that may appear — everything else in that namespace is something+ the receiver would have derived."""+ for event, props in self.fire_every_event().items():+ geo = sorted(k for k in props+ if k.startswith("$geoip_") and k != "$geoip_disable")+ self.assertEqual(geo, [], f"{event} carried location data: {geo}")+ raw = self.spy.raw().lower()+ for word in ("country", "city", "latitude", "longitude", "timezone",+ "time_zone", "subdivision", "locale", "continent"):+ self.assertNotIn(word, raw, f"a payload mentions {word!r}")++ def test_the_ip_placeholder_is_truthy_and_not_a_spoof_trigger(self):+ """Both ways of writing this so that it does nothing.++ PostHog's ingest fills properties.$ip from the socket only when the+ event did not bring one — `if (!properties['$ip'] && event.ip)`. Any+ falsy value (None, "", 0) is therefore not suppression, it is the+ default with extra steps, and the real address lands on the event+ anyway. Separately, the GeoIP transformation rewrites 127.0.0.1 and+ 192.168.* to a real address in Sweden as a local-dev convenience, so+ a loopback placeholder would manufacture a location the day the+ disable flag got dropped. Hence: truthy, and neither of those."""+ ip = P.ANALYTICS_IP_PLACEHOLDER+ self.assertIsInstance(ip, str)+ self.assertTrue(ip, "a falsy $ip is silently replaced by the real one")+ self.assertNotEqual(ip, "127.0.0.1")+ self.assertFalse(ip.startswith("192.168."))+ P._analytics_capture("app_boot", {"version": "3.7.0"})+ drain()+ self.assertEqual(self.spy.bodies[0]["properties"]["$ip"], ip,+ "the placeholder never reached the wire")++ def test_a_call_site_cannot_override_a_directive(self):+ """The directives are spread last for this reason. A props dict is+ built from job params in places this module does not own."""+ P._analytics_capture("app_boot", {"$geoip_disable": False,+ "$ip": "203.0.113.7",+ "$process_person_profile": True})+ drain()+ props = self.spy.bodies[0]["properties"]+ self.assertIs(props["$geoip_disable"], True)+ self.assertIs(props["$process_person_profile"], False)+ self.assertEqual(props["$ip"], P.ANALYTICS_IP_PLACEHOLDER)++ def test_the_local_mirror_records_only_our_own_properties(self):+ """The directives are transport, not data: state/usage-log.jsonl is+ the user's readable copy of what the panel MEANT, and padding it with+ receiver plumbing would make the page harder to check, not easier."""+ P._analytics_capture("app_boot", {"version": "3.7.0"})+ drain()+ props = self.log_lines()[0]["props"]+ self.assertEqual(sorted(k for k in props if k.startswith("$")), [])+# ---------------------------------------------------------------------------# 5. Local aggregation + the /stats/usage payload+# 6. Local aggregation + the /stats/usage payload# --------------------------------------------------------------------------class TestUsageReport(AnalyticsTestCase):diff --git a/scripts/test_convert_ltx_mlx.py b/scripts/test_convert_ltx_mlx.pynew file mode 100644index 0000000..7140ded--- /dev/null+++ b/scripts/test_convert_ltx_mlx.py@@ -0,0 +1,586 @@+#!/usr/bin/env python3+"""Tests for scripts/convert_ltx_mlx.py — the PyTorch/Comfy → MLX pack converter.++Everything here runs on synthetic safetensors at tiny dims, built from the+2.5-style key names taken from the merged ComfyUI implementation (commit+57ce8e1a) and from the real 2.3 MLX pack headers. No 42 GB checkpoint, no+gated download, no GPU.++That is not a compromise. The converter's whole job is naming and layout, and+naming and layout are exactly what a 4-tensor file can prove. What it cannot+prove is covered honestly in the port note: that the vendor's real key set+contains no key our Route table has never seen. The unmapped-keys abort is+what turns that unknown into a loud failure instead of a silent one.++Run: ./ltx-2-mlx/env/bin/python -m pytest scripts/test_convert_ltx_mlx.py -q+"""++from __future__ import annotations++import json+import os+import struct+import sys+from pathlib import Path++import pytest++sys.path.insert(0, str(Path(__file__).resolve().parent))++from convert_ltx_mlx import ( # noqa: E402+ DEFAULT_ROUTES,+ ComponentPlan,+ PlannedTensor,+ UnmappedKeys,+ apply_leaf_map,+ convert,+ parse_input_spec,+ plan_conversion,+ read_header,+ rename_key,+ route_key,+ tensor_nbytes,+ write_component,+)+++# --------------------------------------------------------------------------+# Minimal safetensors writer — deliberately independent of the converter's+# own writer, so a bug in one cannot hide a bug in the other.+# --------------------------------------------------------------------------+++def write_safetensors(path: Path, tensors: dict, metadata: dict | None = None) -> Path:+ """`tensors`: {key: (dtype, shape, bytes)}."""+ header = {}+ cursor = 0+ blob = bytearray()+ for key, (dtype, shape, payload) in tensors.items():+ header[key] = {"dtype": dtype, "shape": list(shape), "data_offsets": [cursor, cursor + len(payload)]}+ blob += payload+ cursor += len(payload)+ if metadata:+ header["__metadata__"] = metadata+ raw = json.dumps(header, separators=(",", ":")).encode()+ raw += b" " * ((-len(raw)) % 8)+ path.parent.mkdir(parents=True, exist_ok=True)+ with open(path, "wb") as fh:+ fh.write(struct.pack("<Q", len(raw)))+ fh.write(raw)+ fh.write(bytes(blob))+ return path+++def bf16(n: int, fill: int = 0xAB) -> bytes:+ return bytes([fill]) * (n * 2)+++def comfy_dit_tensors(num_blocks: int = 2) -> dict:+ """A miniature monolithic DiT in ComfyUI single-file key layout."""+ t = {+ "model.diffusion_model.patchify_proj.weight": ("BF16", [8, 4], bf16(32)),+ "model.diffusion_model.patchify_proj.bias": ("BF16", [8], bf16(8)),+ "model.diffusion_model.proj_out.weight": ("BF16", [4, 8], bf16(32)),+ "model.diffusion_model.scale_shift_table": ("F32", [2, 8], b"\x01" * (2 * 8 * 4)),+ "model.diffusion_model.adaln_single.linear.weight": ("BF16", [72, 8], bf16(576)),+ "model.diffusion_model.adaln_single.emb.timestep_embedder.linear_1.weight": ("BF16", [8, 4], bf16(32)),+ "model.diffusion_model.adaln_single.emb.timestep_embedder.linear_2.weight": ("BF16", [8, 8], bf16(64)),+ # 2.5: no keyframes marker unless the checkpoint ships it+ "model.diffusion_model.keyframes_abs_pos_embedding": ("BF16", [1, 8], bf16(8)),+ }+ for i in range(num_blocks):+ p = f"model.diffusion_model.transformer_blocks.{i}."+ t[p + "attn1.to_q.weight"] = ("BF16", [8, 8], bf16(64))+ t[p + "attn1.to_out.0.weight"] = ("BF16", [8, 8], bf16(64))+ t[p + "attn1.q_norm.weight"] = ("BF16", [8], bf16(8))+ # LTX-2.5: ff carries NO bias — only the two weights+ t[p + "ff.net.0.proj.weight"] = ("BF16", [32, 8], bf16(256))+ t[p + "ff.net.2.weight"] = ("BF16", [8, 32], bf16(256))+ t[p + "audio_ff.net.0.proj.weight"] = ("BF16", [16, 4], bf16(64))+ t[p + "audio_ff.net.2.weight"] = ("BF16", [4, 16], bf16(64))+ t[p + "scale_shift_table"] = ("F32", [9, 8], b"\x02" * (9 * 8 * 4))+ return t+++class TestHeaderPrimitives:+ def test_round_trips_a_header(self, tmp_path):+ path = write_safetensors(tmp_path / "x.safetensors", {"a": ("BF16", [2, 3], bf16(6))})+ header, offset = read_header(path)+ assert header["a"]["shape"] == [2, 3]+ assert offset % 8 == 0++ def test_nbytes_matches_dtype_and_shape(self):+ assert tensor_nbytes({"dtype": "BF16", "shape": [4, 8]}) == 64+ assert tensor_nbytes({"dtype": "F32", "shape": [2, 8]}) == 64+ assert tensor_nbytes({"dtype": "U32", "shape": [4096, 512]}) == 4096 * 512 * 4++ def test_unknown_dtype_raises(self):+ with pytest.raises(ValueError, match="unknown safetensors dtype"):+ tensor_nbytes({"dtype": "F4_MADEUP", "shape": [1]})++ def test_metadata_survives_the_read(self, tmp_path):+ path = write_safetensors(+ tmp_path / "m.safetensors",+ {"a": ("BF16", [1], bf16(1))},+ metadata={"model_version": "2.5", "config": '{"transformer":{"ff_bias":false}}'},+ )+ header, _ = read_header(path)+ assert header["__metadata__"]["model_version"] == "2.5"+++class TestRenaming:+ """Rules mirror LTXV_LORA_COMFY_RENAMING_MAP in the vendored loader."""++ @pytest.mark.parametrize(+ ("src", "want"),+ [+ ("transformer.transformer_blocks.0.attn1.to_out.0.weight", "transformer.transformer_blocks.0.attn1.to_out.weight"),+ ("transformer.transformer_blocks.0.ff.net.0.proj.weight", "transformer.transformer_blocks.0.ff.proj_in.weight"),+ ("transformer.transformer_blocks.0.ff.net.2.weight", "transformer.transformer_blocks.0.ff.proj_out.weight"),+ ("transformer.transformer_blocks.0.audio_ff.net.0.proj.weight", "transformer.transformer_blocks.0.audio_ff.proj_in.weight"),+ ("transformer.adaln_single.emb.timestep_embedder.linear_1.weight", "transformer.adaln_single.emb.timestep_embedder.linear1.weight"),+ ("transformer.patchify_proj.weight", "transformer.patchify_proj.weight"),+ ],+ )+ def test_rules(self, src, want):+ assert rename_key(src) == want++ def test_renaming_is_idempotent(self):+ """Running the table twice must not corrupt an already-renamed key."""+ once = rename_key("transformer.transformer_blocks.0.ff.net.0.proj.weight")+ assert rename_key(once) == once+++def only(routes):+ """A key that must route to exactly one component."""+ assert len(routes) == 1, f"expected a single route, got {[r.stem for r in routes]}"+ return routes[0]+++class TestRouting:+ def test_longest_prefix_wins(self):+ """duration_head must not be swallowed by model.diffusion_model."""+ route = only(route_key("model.diffusion_model.duration_head.mlp_out.bias", DEFAULT_ROUTES))+ assert route.stem == "duration_head"+ assert route.target_prefix == "duration_head."++ def test_connector_subtrees_land_in_one_file(self):+ video = only(route_key("model.diffusion_model.video_embeddings_connector.x", DEFAULT_ROUTES))+ audio = only(route_key("model.diffusion_model.audio_embeddings_connector.x", DEFAULT_ROUTES))+ assert video.stem == audio.stem == "connector"+ assert video.target_prefix.startswith("connector.")++ def test_dit_falls_through_to_transformer(self):+ route = only(route_key("model.diffusion_model.transformer_blocks.0.attn1.to_q.weight", DEFAULT_ROUTES))+ assert route.stem == "transformer"++ def test_unknown_prefix_returns_no_route(self):+ assert route_key("some.vendor.module.weight", DEFAULT_ROUTES) == []+++class TestRealLTX25Shapes:+ """Pinned against the key sets of the actual Lightricks 2.5 release.++ Every assertion here failed against the route table as first written. Each+ one is a way the pack would have loaded and rendered wrongly rather than+ erroring — which is why they are tests and not a changelog line.+ """++ def test_connector_keeps_its_pytorch_spelling(self):+ """The vendored ConnectorAttention builds ``to_out.0`` and ``ff.net.*``.++ The DiT renames are correct for DiT blocks and wrong here. Applying them+ to the connector yields a file whose keys no shipped module claims.+ """+ route = only(+ route_key("model.diffusion_model.video_embeddings_connector.transformer_1d_blocks.0.attn1.to_out.0.weight", DEFAULT_ROUTES)+ )+ assert route.rename is False+ suffix = "transformer_1d_blocks.0.attn1.to_out.0.weight"+ assert route.target_prefix + suffix == (+ "connector.video_embeddings_connector.transformer_1d_blocks.0.attn1.to_out.0.weight"+ )++ def test_dit_blocks_still_get_renamed(self):+ route = only(route_key("model.diffusion_model.transformer_blocks.0.ff.net.0.proj.weight", DEFAULT_ROUTES))+ assert route.rename is True++ def test_video_vae_statistics_fan_out_to_both_halves(self):+ """One shipped copy; the encoder and decoder spell the leaves differently."""+ routes = route_key("per_channel_statistics.mean-of-means", DEFAULT_ROUTES)+ assert {r.stem for r in routes} == {"vae_encoder", "vae_decoder"}+ produced = {+ apply_leaf_map(r.target_prefix + "mean-of-means", r.leaf_map) for r in routes+ }+ assert produced == {+ "vae_encoder.per_channel_statistics._mean_of_means",+ "vae_decoder.per_channel_statistics.mean",+ }++ def test_audio_vae_statistics_get_the_underscore_spelling(self):+ route = only(route_key("audio_vae.per_channel_statistics.std-of-means", DEFAULT_ROUTES))+ assert route.stem == "audio_vae"+ assert (+ apply_leaf_map(route.target_prefix + "std-of-means", route.leaf_map)+ == "audio_vae.per_channel_statistics._std_of_means"+ )++ def test_vocoder_doubled_segment_is_collapsed(self):+ """2.5 nests the base vocoder one level deeper than 2.3."""+ base = only(route_key("vocoder.vocoder.resblocks.0.convs1.0.bias", DEFAULT_ROUTES))+ assert base.target_prefix + "resblocks.0.convs1.0.bias" == "vocoder.resblocks.0.convs1.0.bias"++ def test_vocoder_siblings_pass_through_unchanged(self):+ """bwe_generator and mel_stft are already at the right depth."""+ for tail in ("bwe_generator.conv_pre.bias", "mel_stft.window"):+ route = only(route_key(f"vocoder.{tail}", DEFAULT_ROUTES))+ assert route.target_prefix + tail == f"vocoder.{tail}"++ def test_upscalers_need_an_explicit_stem(self, tmp_path):+ """Spatial and temporal upscalers ship byte-identical key sets.++ Nothing in the key says which is which, so an unpinned run must refuse+ rather than guess — and a pinned run must land the whole file.+ """+ bare = {+ "final_conv.bias": ("BF16", [4], bf16(4)),+ "res_blocks.0.norm1.weight": ("BF16", [4], bf16(4)),+ }+ path = write_safetensors(tmp_path / "spatial.safetensors", bare)+ _, unmapped, _ = plan_conversion([path], allow_unmapped=True)+ assert len(unmapped) == 2++ plans, unmapped, _ = plan_conversion([(path, "spatial_upscaler_x2_v1_1")])+ assert unmapped == []+ assert {t.target_key for t in plans["spatial_upscaler_x2_v1_1"].tensors} == {+ "spatial_upscaler_x2_v1_1.final_conv.bias",+ "spatial_upscaler_x2_v1_1.res_blocks.0.norm1.weight",+ }++ def test_explicit_stem_does_not_rename(self, tmp_path):+ """A pinned file is copied verbatim; DiT rules must not reach into it."""+ path = write_safetensors(+ tmp_path / "u.safetensors",+ {"res_blocks.0.ff.net.2.weight": ("BF16", [4], bf16(4))},+ )+ plans, _, _ = plan_conversion([(path, "temporal_upscaler_x2_v1_0")])+ assert {t.target_key for t in plans["temporal_upscaler_x2_v1_0"].tensors} == {+ "temporal_upscaler_x2_v1_0.res_blocks.0.ff.net.2.weight"+ }+++class TestPlanning:+ def test_plans_a_monolithic_dit(self, tmp_path):+ path = write_safetensors(tmp_path / "dit.safetensors", comfy_dit_tensors())+ plans, unmapped, _ = plan_conversion([path])+ assert unmapped == []+ assert set(plans) == {"transformer"}+ assert all(t.target_key.startswith("transformer.") for t in plans["transformer"].tensors)++ def test_renames_are_applied_in_the_plan(self, tmp_path):+ path = write_safetensors(tmp_path / "dit.safetensors", comfy_dit_tensors(num_blocks=1))+ plans, _, _ = plan_conversion([path])+ keys = {t.target_key for t in plans["transformer"].tensors}+ assert "transformer.transformer_blocks.0.ff.proj_in.weight" in keys+ assert "transformer.transformer_blocks.0.attn1.to_out.weight" in keys+ assert not any(".net." in k or ".to_out.0." in k for k in keys)++ def test_the_keyframe_marker_survives(self, tmp_path):+ """A 2.5-only tensor must not be quietly dropped."""+ path = write_safetensors(tmp_path / "dit.safetensors", comfy_dit_tensors())+ plans, _, _ = plan_conversion([path])+ keys = {t.target_key for t in plans["transformer"].tensors}+ assert "transformer.keyframes_abs_pos_embedding" in keys++ def test_multiple_inputs_merge_into_one_pack(self, tmp_path):+ dit = write_safetensors(tmp_path / "dit.safetensors", comfy_dit_tensors(num_blocks=1))+ vae = write_safetensors(+ tmp_path / "vae.safetensors",+ {+ "encoder.conv_in.weight": ("BF16", [4, 4], bf16(16)),+ "decoder.conv_out.weight": ("BF16", [4, 4], bf16(16)),+ },+ )+ head = write_safetensors(+ tmp_path / "head.safetensors", {"duration_head.mlp_out.bias": ("BF16", [1], bf16(1))}+ )+ plans, unmapped, _ = plan_conversion([dit, vae, head])+ assert unmapped == []+ assert set(plans) == {"transformer", "vae_encoder", "vae_decoder", "duration_head"}++ def test_unmapped_keys_abort_by_default(self, tmp_path):+ path = write_safetensors(+ tmp_path / "odd.safetensors",+ {"brand.new.module.weight": ("BF16", [2, 2], bf16(4))},+ )+ with pytest.raises(UnmappedKeys, match="matched no output component"):+ plan_conversion([path])++ def test_the_abort_message_names_the_mosaic(self, tmp_path):+ """Whoever hits this must understand why it is not a warning."""+ path = write_safetensors(tmp_path / "odd.safetensors", {"x.y.z": ("BF16", [1], bf16(1))})+ with pytest.raises(UnmappedKeys) as excinfo:+ plan_conversion([path])+ assert "mosaic" in str(excinfo.value)+ assert "--allow-unmapped" in str(excinfo.value)++ def test_allow_unmapped_reports_instead_of_raising(self, tmp_path):+ path = write_safetensors(+ tmp_path / "odd.safetensors",+ {+ "brand.new.module.weight": ("BF16", [2, 2], bf16(4)),+ "model.diffusion_model.proj_out.weight": ("BF16", [2, 2], bf16(4)),+ },+ )+ plans, unmapped, _ = plan_conversion([path], allow_unmapped=True)+ assert len(unmapped) == 1+ assert "brand.new.module.weight" in unmapped[0]+ assert set(plans) == {"transformer"}++ def test_a_self_inconsistent_header_is_refused(self, tmp_path):+ """Offsets that disagree with dtype*shape mean a corrupt download."""+ path = tmp_path / "bad.safetensors"+ # Routable key, so the run reaches the consistency check rather than+ # tripping the unmapped-keys abort first.+ header = {"transformer.w": {"dtype": "BF16", "shape": [4, 4], "data_offsets": [0, 8]}} # needs 32+ raw = json.dumps(header).encode()+ raw += b" " * ((-len(raw)) % 8)+ with open(path, "wb") as fh:+ fh.write(struct.pack("<Q", len(raw)))+ fh.write(raw)+ fh.write(b"\x00" * 8)+ with pytest.raises(ValueError, match="self-inconsistent"):+ plan_conversion([path])+++class TestWriting:+ def test_bytes_survive_the_round_trip(self, tmp_path):+ payload = bytes(range(256)) * 4+ src = write_safetensors(tmp_path / "src.safetensors", {"transformer.w": ("BF16", [8, 64], payload)})+ plans, _, _ = plan_conversion([src])+ out, digest, size = write_component(plans["transformer"], tmp_path / "pack")++ header, offset = read_header(out)+ assert list(header) == ["transformer.w"]+ begin, end = header["transformer.w"]["data_offsets"]+ with open(out, "rb") as fh:+ fh.seek(offset + begin)+ assert fh.read(end - begin) == payload+ assert len(digest) == 64+ assert size == out.stat().st_size++ def test_no_partial_file_is_left_behind_on_failure(self, tmp_path):+ out_dir = tmp_path / "pack"+ out_dir.mkdir()+ missing = tmp_path / "gone.safetensors"+ plan = ComponentPlan(+ stem="transformer",+ tensors=[PlannedTensor("transformer.w", "w", missing, 0, 16, "BF16", [8])],+ )+ with pytest.raises(Exception):+ write_component(plan, out_dir)+ assert list(out_dir.iterdir()) == [], "a failed write must leave nothing behind"++ def test_colliding_target_keys_are_refused(self, tmp_path):+ src = tmp_path / "s.safetensors"+ write_safetensors(src, {"transformer.w": ("BF16", [1], bf16(1))})+ plan = ComponentPlan(+ stem="transformer",+ tensors=[+ PlannedTensor("transformer.w", "a", src, 0, 2, "BF16", [1]),+ PlannedTensor("transformer.w", "b", src, 0, 2, "BF16", [1]),+ ],+ )+ with pytest.raises(ValueError, match="collide"):+ write_component(plan, tmp_path / "pack")++ def test_data_blob_is_eight_byte_aligned(self, tmp_path):+ src = write_safetensors(tmp_path / "s.safetensors", {"transformer.a": ("BF16", [3], bf16(3))})+ plans, _, _ = plan_conversion([src])+ out, _, _ = write_component(plans["transformer"], tmp_path / "pack")+ _, offset = read_header(out)+ assert offset % 8 == 0+++class TestEndToEnd:+ def test_converts_a_monolith_into_a_pack(self, tmp_path):+ src = write_safetensors(+ tmp_path / "ltx-2.5-distilled.safetensors",+ comfy_dit_tensors(num_blocks=2)+ | {+ "model.diffusion_model.duration_head.mlp_out.bias": ("BF16", [1], bf16(1)),+ "encoder.conv_in.weight": ("BF16", [4, 4], bf16(16)),+ "decoder.conv_out.weight": ("BF16", [4, 4], bf16(16)),+ },+ metadata={+ "model_version": "2.5",+ "config": json.dumps(+ {+ "model_version": "2.5",+ "transformer": {"ff_bias": False, "use_prompt_adaln_single": False, "num_layers": 2},+ }+ ),+ },+ )+ out_dir = tmp_path / "ltx-2.5-mlx-bf16"+ report = convert([src], out_dir, transformer_stem="transformer-distilled")++ names = {p.name for p in out_dir.iterdir()}+ assert "transformer-distilled.safetensors" in names+ assert "duration_head.safetensors" in names+ assert {"config.json", "embedded_config.json", "split_model.json", "manifest.json"} <= names++ manifest = json.loads((out_dir / "manifest.json").read_text())+ assert len(manifest["files"]) == len(report["files"])+ for entry in manifest["files"]:+ path = out_dir / entry["file"]+ assert path.stat().st_size == entry["bytes"]+ assert len(entry["sha256"]) == 64++ def test_metadata_rides_on_the_transformer_and_becomes_config_json(self, tmp_path):+ config = {"model_version": "2.5", "transformer": {"ff_bias": False}}+ src = write_safetensors(+ tmp_path / "dit.safetensors",+ comfy_dit_tensors(num_blocks=1),+ metadata={"model_version": "2.5", "config": json.dumps(config)},+ )+ out_dir = tmp_path / "pack"+ convert([src], out_dir, transformer_stem="transformer-distilled")++ header, _ = read_header(out_dir / "transformer-distilled.safetensors")+ assert header["__metadata__"]["model_version"] == "2.5"++ on_disk = json.loads((out_dir / "config.json").read_text())+ assert on_disk["transformer"]["ff_bias"] is False++ def test_the_vendored_config_reader_accepts_the_result(self, tmp_path):+ """The real proof: our pack is readable by the code that will load it.++ Needs an ``ltx_core_mlx`` that carries the 2.5 config work (the+ ``feat/ltx-2.5`` branch of the fork). The app's vendored checkout is+ pinned to a released tag and does not, so this skips there rather than+ failing — the converter is not what is missing in that case.+ """+ pytest.importorskip("mlx.core")+ port_src = Path(+ os.environ.get(+ "LTX25_PORT_SRC",+ Path.home() / "AI/projects/phosphene/ltx25-port/ltx-2-mlx/packages/ltx-core-mlx/src",+ )+ )+ if port_src.exists():+ sys.path.insert(0, str(port_src))+ from ltx_core_mlx.model.transformer.model import LTXModelConfig++ if not hasattr(LTXModelConfig(), "ff_bias"):+ pytest.skip(+ "the importable ltx_core_mlx predates the 2.5 config work; "+ "set LTX25_PORT_SRC to a checkout of feat/ltx-2.5 to run this"+ )++ config = {+ "model_version": "2.5",+ "transformer": {+ "ff_bias": False,+ "audio_ff_bias": False,+ "use_prompt_adaln_single": False,+ "num_layers": 2,+ },+ }+ src = write_safetensors(+ tmp_path / "dit.safetensors",+ comfy_dit_tensors(num_blocks=1),+ metadata={"model_version": "2.5", "config": json.dumps(config)},+ )+ out_dir = tmp_path / "pack"+ convert([src], out_dir, transformer_stem="transformer-distilled")++ from_dir = LTXModelConfig.from_checkpoint_dir(out_dir)+ assert from_dir.ff_bias is False+ assert from_dir.use_prompt_adaln_single is False+ assert from_dir.num_layers == 2++ from_file = LTXModelConfig.from_checkpoint_file(out_dir / "transformer-distilled.safetensors")+ assert from_file is not None+ assert from_file.model_version == (2, 5)++ def test_dry_run_writes_nothing(self, tmp_path):+ src = write_safetensors(tmp_path / "dit.safetensors", comfy_dit_tensors(num_blocks=1))+ out_dir = tmp_path / "pack"+ report = convert([src], out_dir, dry_run=True)+ assert report["total_bytes"] > 0+ assert not out_dir.exists()++ def test_total_bytes_equals_the_sum_of_sources(self, tmp_path):+ tensors = comfy_dit_tensors(num_blocks=2)+ expected = sum(len(payload) for _, _, payload in tensors.values())+ src = write_safetensors(tmp_path / "dit.safetensors", tensors)+ report = convert([src], tmp_path / "pack", dry_run=True)+ assert report["total_bytes"] == expected+++class TestConvLayout:+ """MLX puts input channels last; PyTorch puts them second.++ Derived by diffing every shared key of the converted 2.5 pack against the+ shipped 2.3 pack (ground truth for MLX layout): 768 tensors differ, and+ exactly four permutations explain all of them with no exceptions. Before+ this, the VAE encoder failed to load with+ "Expected shape (128, 3, 3, 3, 48) but received shape (128, 48, 3, 3, 3)".+ """++ @pytest.mark.parametrize(+ ("key", "shape", "want"),+ [+ ("vae_encoder.conv_in.conv.weight", [128, 48, 3, 3, 3], (0, 2, 3, 4, 1)),+ ("audio_vae.decoder.conv_in.conv.weight", [512, 8, 3, 3], (0, 2, 3, 1)),+ # A resampler kernel, not a weight — and it needs Conv1d layout+ # just the same. 402 of these were left unpermuted by an+ # earlier ``*.weight``-only predicate.+ ("vocoder.act_post.downsample.lowpass.filter", [1, 1, 12], (0, 2, 1)),+ ("vocoder.resblocks.0.convs1.0.weight", [512, 512, 3], (0, 2, 1)),+ ("vocoder.ups.0.weight", [1536, 768, 11], (1, 2, 0)),+ ("vocoder.bwe_generator.ups.0.weight", [512, 256, 12], (1, 2, 0)),+ ("vocoder.mel_stft.mel_basis", [64, 513], None),+ ("transformer.transformer_blocks.0.attn1.to_q.weight", [4096, 4096], None),+ ("transformer.scale_shift_table", [2, 4096], None),+ ("vae_encoder.conv_in.conv.bias", [128], None),+ ],+ )+ def test_permutation_rule(self, key, shape, want):+ from convert_ltx_mlx import conv_permutation++ assert conv_permutation(key, shape) == want++ def test_rank_decides_not_the_suffix(self):+ """Non-``.weight`` tensors of conv rank are permuted; rank 1/2 never are."""+ from convert_ltx_mlx import conv_permutation++ assert conv_permutation("vocoder.r.0.upsample.filter", [1, 1, 12]) == (0, 2, 1)+ assert conv_permutation("vocoder.ups.0.bias", [1536]) is None+ assert conv_permutation("vocoder.mel_stft.mel_basis", [64, 513]) is None++ def test_permutation_preserves_bytes_and_reorders_axes(self):+ import numpy as np++ from convert_ltx_mlx import permute_bytes, permuted_shape++ shape, perm = [2, 3, 4], (0, 2, 1)+ src = np.arange(24, dtype=np.uint16)+ out = permute_bytes(src.tobytes(), shape, perm, 2)+ assert len(out) == len(src.tobytes())+ assert permuted_shape(shape, perm) == [2, 4, 3]+ expect = src.reshape(shape).transpose(perm)+ assert np.array_equal(np.frombuffer(out, dtype=np.uint16).reshape(2, 4, 3), expect)++ def test_conv_weight_lands_permuted_in_the_written_file(self, tmp_path):+ """End to end: plan -> write -> header carries the MLX shape."""+ src = write_safetensors(+ tmp_path / "vae.safetensors",+ {"encoder.conv_in.conv.weight": ("BF16", [4, 2, 3, 3, 3], bf16(4 * 2 * 27))},+ )+ plans, unmapped, _ = plan_conversion([src])+ assert unmapped == []+ 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]diff --git a/scripts/test_ltx_pack_diff.py b/scripts/test_ltx_pack_diff.pynew file mode 100644index 0000000..44e268d--- /dev/null+++ b/scripts/test_ltx_pack_diff.py@@ -0,0 +1,324 @@+#!/usr/bin/env python3+"""Tests for scripts/ltx_pack_diff.py — the standing pack-contract gate.++Stdlib only: no mlx, no GPU, no weights. Every fixture is a hand-written+safetensors file of a few bytes, because the thing under test reads headers and+nothing else.++The cases that matter are the ones that bit us for real:++ * a shape mismatch on a shared key must FAIL, and must fail even when the+ caller declared an allowlist — an allowlist is about which keys exist, never+ about whether a shared key means the same thing;+ * the real 2.5-vs-2.3 DiT delta (96 absent ff biases, one extra keyframe+ embedding) must PASS when declared and FAIL when not;+ * a diff that compares nothing must not report success. "0 mismatches" over+ an empty set is how a gate turns into decoration.++Run: python3 -m pytest scripts/test_ltx_pack_diff.py -q+ or: python3 scripts/test_ltx_pack_diff.py+"""++from __future__ import annotations++import json+import struct+import sys+from pathlib import Path++import pytest++sys.path.insert(0, str(Path(__file__).resolve().parent))++from ltx_pack_diff import ( # noqa: E402+ collapse_key,+ collapse_keys,+ diff_file,+ diff_packs,+ main,+ pair_files,+ read_header,+)++DTYPE_SIZES = {"BF16": 2, "F32": 4, "U32": 4}+++def write_safetensors(path: Path, tensors: dict[str, tuple[str, list[int]]], metadata: dict | None = None) -> Path:+ """Write a real (if tiny) safetensors file: {name: (dtype, shape)}."""+ index: dict = {}+ offset = 0+ for name, (dtype, shape) in tensors.items():+ nbytes = DTYPE_SIZES[dtype]+ for dim in shape:+ nbytes *= dim+ index[name] = {"dtype": dtype, "shape": shape, "data_offsets": [offset, offset + nbytes]}+ offset += nbytes+ if metadata:+ index["__metadata__"] = metadata+ blob = json.dumps(index).encode()+ path.parent.mkdir(parents=True, exist_ok=True)+ with open(path, "wb") as fh:+ fh.write(struct.pack("<Q", len(blob)))+ fh.write(blob)+ fh.write(b"\0" * offset)+ return path+++def dit(prefix: str, blocks: int = 3, *, ff_bias: bool, keyframes: bool) -> dict:+ """A miniature of the real LTX DiT key set — enough structure that the+ collapsed patterns in the tests are the same strings the real pack yields."""+ tensors: dict[str, tuple[str, list[int]]] = {f"{prefix}patchify_proj.weight": ("BF16", [8, 4])}+ for i in range(blocks):+ base = f"{prefix}transformer_blocks.{i}"+ tensors[f"{base}.attn1.to_q.weight"] = ("BF16", [8, 8])+ tensors[f"{base}.ff.proj_in.weight"] = ("BF16", [16, 8])+ tensors[f"{base}.ff.proj_out.weight"] = ("BF16", [8, 16])+ tensors[f"{base}.scale_shift_table"] = ("F32", [6, 8])+ if ff_bias:+ tensors[f"{base}.ff.proj_in.bias"] = ("BF16", [16])+ tensors[f"{base}.ff.proj_out.bias"] = ("BF16", [8])+ if keyframes:+ tensors[f"{prefix}keyframes_abs_pos_embedding"] = ("BF16", [1, 8])+ return tensors+++def packs(tmp_path: Path):+ """A 2.3-shaped reference pack and a 2.5-shaped candidate, plus a shared+ verbatim component that must diff to nothing."""+ ref, new = tmp_path / "ref", tmp_path / "new"+ write_safetensors(ref / "transformer-dev.safetensors", dit("transformer.", ff_bias=True, keyframes=False))+ write_safetensors(new / "transformer-dev.safetensors", dit("transformer.", ff_bias=False, keyframes=True))+ for root in (ref, new):+ write_safetensors(root / "vae_encoder.safetensors", {"vae_encoder.conv.weight": ("BF16", [4, 3, 3, 3, 2])})+ return ref, new+++# ---------------------------------------------------------------------------+# header reading+# ---------------------------------------------------------------------------+++def test_header_read_drops_metadata_and_keeps_tensors(tmp_path):+ path = write_safetensors(+ tmp_path / "x.safetensors", {"a.weight": ("BF16", [2, 2])}, metadata={"config": "{}"}+ )+ index = read_header(path)+ assert set(index) == {"a.weight"}+ assert index["a.weight"]["shape"] == [2, 2]+++def test_truncated_file_raises_rather_than_reading_as_empty(tmp_path):+ """A half-downloaded pack must not diff clean against anything."""+ path = write_safetensors(tmp_path / "x.safetensors", {"a.weight": ("BF16", [2, 2])})+ raw = path.read_bytes()+ path.write_bytes(raw[:6])+ with pytest.raises(ValueError):+ read_header(path)++ path.write_bytes(struct.pack("<Q", 4096) + b"{}")+ with pytest.raises(ValueError):+ read_header(path)+++# ---------------------------------------------------------------------------+# collapsing+# ---------------------------------------------------------------------------+++def test_collapse_folds_block_indices_but_not_trailing_numbers():+ assert collapse_key("t.transformer_blocks.41.ff.proj_in.bias") == "t.transformer_blocks.N.ff.proj_in.bias"+ # a trailing digit is part of the name (to_out.0), not a stack index+ assert collapse_key("t.attn1.to_out.0") == "t.attn1.to_out.0"+++def test_collapse_counts_every_member_of_a_stack():+ keys = [f"t.transformer_blocks.{i}.ff.proj_in.bias" for i in range(48)]+ assert collapse_keys(keys) == [("t.transformer_blocks.N.ff.proj_in.bias", 48)]+++# ---------------------------------------------------------------------------+# the diff itself+# ---------------------------------------------------------------------------+++def test_identical_files_diff_to_nothing(tmp_path):+ tensors = dit("transformer.", ff_bias=True, keyframes=False)+ a = write_safetensors(tmp_path / "a" / "t.safetensors", tensors)+ b = write_safetensors(tmp_path / "b" / "t.safetensors", tensors)+ d = diff_file(a, b)+ assert (d["only_new"], d["only_ref"], d["shape_mm"], d["dtype_mm"]) == ([], [], [], [])+ assert d["shared"] == d["n_ref"] == d["n_new"]+++def test_shape_mismatch_is_reported_with_both_shapes(tmp_path):+ a = write_safetensors(tmp_path / "a" / "t.safetensors", {"k.weight": ("BF16", [4, 8])})+ b = write_safetensors(tmp_path / "b" / "t.safetensors", {"k.weight": ("BF16", [8, 4])})+ (key, ref_shape, new_shape), = diff_file(a, b)["shape_mm"]+ assert (key, ref_shape, new_shape) == ("k.weight", [4, 8], [8, 4])+++def test_dtype_mismatch_is_reported_separately_from_shape(tmp_path):+ a = write_safetensors(tmp_path / "a" / "t.safetensors", {"k.scale_shift_table": ("F32", [6, 8])})+ b = write_safetensors(tmp_path / "b" / "t.safetensors", {"k.scale_shift_table": ("BF16", [6, 8])})+ d = diff_file(a, b)+ assert d["shape_mm"] == []+ assert d["dtype_mm"] == [("k.scale_shift_table", "F32", "BF16")]+++# ---------------------------------------------------------------------------+# pairing+# ---------------------------------------------------------------------------+++def test_pairing_defaults_to_same_named_files_present_in_both(packs):+ ref, new = packs+ names = [(r.name, n.name) for r, n in pair_files(ref, new)]+ assert names == [+ ("transformer-dev.safetensors", "transformer-dev.safetensors"),+ ("vae_encoder.safetensors", "vae_encoder.safetensors"),+ ]+++def test_explicit_map_compares_files_that_changed_name(tmp_path):+ """2.3 ships transformer-dev; 2.5 shipped only transformer-distilled until+ the dev pack existed. Comparing them is the whole point of --map."""+ write_safetensors(tmp_path / "ref" / "transformer-dev.safetensors", {"transformer.a": ("BF16", [2, 2])})+ write_safetensors(tmp_path / "new" / "transformer-distilled.safetensors", {"transformer.a": ("BF16", [2, 2])})+ pairs = pair_files(+ tmp_path / "ref",+ tmp_path / "new",+ {"transformer-dev.safetensors": "transformer-distilled.safetensors"},+ )+ assert [(r.name, n.name) for r, n in pairs] == [+ ("transformer-dev.safetensors", "transformer-distilled.safetensors")+ ]+++def test_a_mapped_file_is_not_also_paired_by_name(tmp_path):+ """The mapped file must be compared once, against what the caller said."""+ write_safetensors(tmp_path / "ref" / "a.safetensors", {"k": ("BF16", [2])})+ write_safetensors(tmp_path / "ref" / "b.safetensors", {"k": ("BF16", [2])})+ write_safetensors(tmp_path / "new" / "b.safetensors", {"k": ("BF16", [2])})+ pairs = pair_files(tmp_path / "ref", tmp_path / "new", {"a.safetensors": "b.safetensors"})+ assert [(r.name, n.name) for r, n in pairs] == [("a.safetensors", "b.safetensors")]+++# ---------------------------------------------------------------------------+# pass/fail policy+# ---------------------------------------------------------------------------+++def test_undeclared_key_difference_passes_when_nothing_was_declared(packs):+ """Default is report-only on key sets: the 2.5 pack legitimately differs+ from 2.3 and a bare run should say so without failing."""+ report = diff_packs(*packs)+ assert report["ok"] is True+ assert report["enforced"] is False+ assert report["mismatches"] == 0+++def test_strict_keys_fails_on_the_real_25_delta(packs):+ report = diff_packs(*packs, strict_keys=True)+ assert report["ok"] is False+ assert report["undeclared_keys"] > 0+++def test_declaring_the_real_25_delta_passes(packs):+ """The exact contract recorded in the module docstring."""+ report = diff_packs(+ *packs,+ allow_only_new=["transformer.keyframes_abs_pos_embedding"],+ allow_only_ref=[+ "transformer.transformer_blocks.N.ff.proj_in.bias",+ "transformer.transformer_blocks.N.ff.proj_out.bias",+ ],+ )+ assert report["ok"] is True+ assert report["enforced"] is True+++def test_a_partial_declaration_still_fails_and_names_what_is_left(packs):+ report = diff_packs(+ *packs,+ allow_only_new=["transformer.keyframes_abs_pos_embedding"],+ allow_only_ref=["transformer.transformer_blocks.N.ff.proj_in.bias"],+ )+ assert report["ok"] is False+ entry = next(f for f in report["files"] if f["new"] == "transformer-dev.safetensors")+ assert [pat for pat, _ in entry["uncovered_ref"]] == ["transformer.transformer_blocks.N.ff.proj_out.bias"]+++def test_an_allowlist_cannot_wave_through_a_shape_mismatch(tmp_path):+ """Shape is not a key-set question. This is the load-bearing assertion:+ an allowlist says which keys may be absent, never that a present key may+ mean something different."""+ write_safetensors(tmp_path / "ref" / "t.safetensors", {"transformer.a.weight": ("BF16", [4, 8])})+ write_safetensors(tmp_path / "new" / "t.safetensors", {"transformer.a.weight": ("BF16", [8, 4])})+ report = diff_packs(+ tmp_path / "ref",+ tmp_path / "new",+ allow_only_new=["anything"],+ allow_only_ref=["anything"],+ )+ assert report["ok"] is False+ assert report["mismatches"] == 1+++def test_verbatim_components_diff_to_zero_across_generations(packs):+ """The vae/vocoder/upscaler are copied byte-for-byte between generations;+ if one of them ever moves, this is where it surfaces."""+ report = diff_packs(*packs)+ vae = next(f for f in report["files"] if f["new"] == "vae_encoder.safetensors")+ assert (vae["only_new"], vae["only_ref"], vae["shape_mm"], vae["dtype_mm"]) == ([], [], [], [])+++# ---------------------------------------------------------------------------+# CLI+# ---------------------------------------------------------------------------+++def test_cli_returns_1_on_a_mismatch_and_0_when_clean(tmp_path, capsys):+ write_safetensors(tmp_path / "ref" / "t.safetensors", {"transformer.a.weight": ("BF16", [4, 8])})+ write_safetensors(tmp_path / "new" / "t.safetensors", {"transformer.a.weight": ("BF16", [8, 4])})+ assert main([str(tmp_path / "ref"), str(tmp_path / "new")]) == 1+ assert "FAIL" in capsys.readouterr().out++ write_safetensors(tmp_path / "new" / "t.safetensors", {"transformer.a.weight": ("BF16", [4, 8])})+ assert main([str(tmp_path / "ref"), str(tmp_path / "new")]) == 0+ assert "PASS" in capsys.readouterr().out+++def test_cli_refuses_to_pass_when_it_compared_nothing(tmp_path, capsys):+ """0 mismatches over an empty comparison is the failure mode this whole+ script exists to stop being possible."""+ (tmp_path / "ref").mkdir()+ (tmp_path / "new").mkdir()+ assert main([str(tmp_path / "ref"), str(tmp_path / "new")]) == 2+ assert "no comparable" in capsys.readouterr().err+++def test_cli_rejects_a_directory_that_does_not_exist(tmp_path, capsys):+ (tmp_path / "ref").mkdir()+ assert main([str(tmp_path / "ref"), str(tmp_path / "nope")]) == 2+ assert "not a directory" in capsys.readouterr().err+++def test_cli_json_is_machine_readable(packs, capsys):+ ref, new = packs+ main([str(ref), str(new), "--json"])+ report = json.loads(capsys.readouterr().out)+ assert report["ok"] is True+ assert report["compared"] == 2+++def test_cli_strict_files_flags_a_file_only_one_pack_has(packs, capsys):+ ref, new = packs+ write_safetensors(new / "duration_head.safetensors", {"duration_head.a": ("BF16", [2])})+ assert main([str(ref), str(new)]) == 0 # shared subset is still clean+ assert main([str(ref), str(new), "--strict-files"]) == 1+ assert "duration_head.safetensors" in capsys.readouterr().out+++if __name__ == "__main__":+ raise SystemExit(pytest.main([__file__, "-q"]))diff --git a/scripts/test_pack_release.py b/scripts/test_pack_release.pynew file mode 100644index 0000000..48cfe42--- /dev/null+++ b/scripts/test_pack_release.py@@ -0,0 +1,319 @@+#!/usr/bin/env python3+"""Tests for the GitHub-release weight mirror — publish_pack_release.py and+fetch_pack_release.py, exercised together.++Stdlib only: no gh, no network, no weights. `upload_asset` is redirected into a+local directory and that directory is served over loopback HTTP, so the pair is+tested through the *same* code paths a real publish and a real fresh install+take — sharding, asset naming, manifest emission, ranged resume, per-shard and+per-file verification, atomic rename.++The cases that matter are the ones that would actually hurt:++ * a **corrupted shard must never reach the pack**. This whole lane exists+ because we ship 11 GB files through a CDN; a mirror that can hand a user a+ silently-truncated transformer is worse than no mirror, because the failure+ surfaces as bad renders, not as an error.+ * an **interrupted download must resume, not restart**. 28 GB restarting from+ zero is how a user gives up on the install.+ * a **complete pack must be left alone**. install.js re-runs this on every+ Resume Install; if that re-downloaded, Resume Install would be a trap.+ * **an incomplete pack must not be publishable.** Cutting a release from a+ pack that is missing a file required_files.json declares mandatory produces+ a fresh install that fetches successfully and is then reported incomplete+ by the panel — the June-2026 mechanism, with a longer download in front.++Run: python3 -m pytest scripts/test_pack_release.py -q+"""++from __future__ import annotations++import hashlib+import json+import os+import shutil+import sys+import threading+from functools import partial+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer+from pathlib import Path++import pytest++sys.path.insert(0, str(Path(__file__).resolve().parent))++import fetch_pack_release as fetcher # noqa: E402+import publish_pack_release as publisher # noqa: E402++SHARD = 1000 # tiny, so a "big" file is a few kB+PACK_KEY = "testpack"+++# --------------------------------------------------------------------------- #+# Fixtures+# --------------------------------------------------------------------------- #+def _write_pack(root: Path) -> Path:+ """A synthetic pack + the required_files.json entry that declares it."""+ pack = root / "mlx_models" / "test-pack"+ pack.mkdir(parents=True)+ # Deliberately not a multiple of SHARD, so the last shard is a short one --+ # off-by-one on the final shard is the classic way to corrupt a reassembly.+ (pack / "big.safetensors").write_bytes(bytes(range(256)) * 17 + b"tail")+ (pack / "small.safetensors").write_bytes(b"\x01\x02\x03" * 40)+ (pack / "config.json").write_text('{"hello": "world"}')+ (pack / "phosphene_quant_manifest.json").write_text(json.dumps({+ "bits": 4, "recipe": "ltx-dit", "group_size": 64,+ "tool": "phosphene/quantize_ltx.py", "tool_version": "1.0.0",+ "files": {"small.safetensors": {"bytes": 120, "sha256": "0" * 64}},+ }))+ (root / "required_files.json").write_text(json.dumps({"repos": [{+ "key": PACK_KEY,+ "kind": "base",+ "name": "Test pack",+ "repo_id": "nobody/test-pack",+ "local_dir": "mlx_models/test-pack",+ "size_gb": 1,+ "mirror": {+ "kind": "github-release",+ "release_repo": "mrbizarro/Phosphene",+ "tag": "test-tag",+ "manifest_asset": f"{PACK_KEY}__phosphene_release_manifest.json",+ },+ "files": ["big.safetensors", "small.safetensors"],+ }]}))+ return pack+++def _publish(root: Path, release_dir: Path, monkeypatch) -> dict:+ """Run the real publisher with uploads redirected to a local directory."""+ release_dir.mkdir(parents=True, exist_ok=True)+ monkeypatch.setattr(publisher, "SHARD_BYTES", SHARD)+ monkeypatch.setattr(publisher, "ensure_release", lambda *a, **k: None)+ monkeypatch.setattr(publisher, "release_assets", lambda *a, **k: {})+ monkeypatch.setattr(publisher, "upload_asset",+ lambda repo, tag, path, **k: shutil.copy2(path, release_dir / path.name))+ return publisher.publish(PACK_KEY, root, tag=None, release_repo=None,+ target="deadbeef", upload=True,+ staging_root=root / "staging",+ license_path=None, notice_path=None,+ notes_file=None, title=None)+++def served(tmp_path, monkeypatch):+ """(root, pack, release_dir, dest, hits) with the release dir on loopback."""+ root = tmp_path / "app"+ root.mkdir()+ pack = _write_pack(root)+ release_dir = tmp_path / "release"+ manifest = _publish(root, release_dir, monkeypatch)++ hits: list[str] = []++ class Handler(SimpleHTTPRequestHandler):+ def log_message(self, *a): # keep pytest output readable+ pass++ def do_GET(self):+ hits.append(self.path)+ super().do_GET()++ srv = ThreadingHTTPServer(("127.0.0.1", 0), partial(Handler, directory=str(release_dir)))+ threading.Thread(target=srv.serve_forever, daemon=True).start()+ base = f"http://127.0.0.1:{srv.server_address[1]}"+ monkeypatch.setattr(fetcher, "asset_url", lambda mirror, asset: f"{base}/{asset}")++ yield root, pack, release_dir, tmp_path / "dest", hits, manifest+ srv.shutdown()+++def _fetch(root: Path, dest: Path, attempts: int = 2) -> int:+ """Through `main()`, i.e. the exact entry point install.js invokes."""+ return fetcher.main(["--repo-key", PACK_KEY, "--root", str(root),+ "--dest", str(dest), "--attempts", str(attempts),+ "--timeout", "10"])+++# --------------------------------------------------------------------------- #+# Publishing+# --------------------------------------------------------------------------- #+def test_a_file_over_the_cap_is_sharded_and_one_under_it_is_not(served):+ _, pack, _, _, _, manifest = served+ big = manifest["files"]["big.safetensors"]+ small = manifest["files"]["small.safetensors"]+ assert big["bytes"] == 4356 == (pack / "big.safetensors").stat().st_size+ assert [s["bytes"] for s in big["shards"]] == [1000, 1000, 1000, 1000, 356]+ assert sum(s["bytes"] for s in big["shards"]) == big["bytes"]+ assert len(small["shards"]) == 1+ assert small["shards"][0]["asset"] == f"{PACK_KEY}__small.safetensors"+++def test_shard_names_are_ordered_zero_padded_and_url_safe(served):+ _, _, _, _, _, manifest = served+ names = [s["asset"] for s in manifest["files"]["big.safetensors"]["shards"]]+ assert names == sorted(names), "lexical order must equal reassembly order"+ assert names[0].endswith(".part000") and names[-1].endswith(".part004")+ allowed = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-")+ assert all(set(n) <= allowed for n in names), "GitHub rewrites anything else"+++def test_every_declared_hash_matches_the_bytes_on_disk(served):+ _, pack, _, _, _, manifest = served+ for name, spec in manifest["files"].items():+ raw = (pack / name).read_bytes()+ assert spec["bytes"] == len(raw)+ assert spec["sha256"] == hashlib.sha256(raw).hexdigest()+++def test_stale_in_pack_manifest_is_reported_not_republished(served):+ """The quantiser's manifest can be stale for sidecars rewritten after it+ ran. The published hash must be the FILE's, and the disagreement named."""+ _, _, _, _, _, manifest = served+ assert manifest["quant_manifest_drift"] == ["small.safetensors"]+ assert manifest["files"]["small.safetensors"]["sha256"] != "0" * 64+++def test_publishing_an_incomplete_pack_is_refused(tmp_path, monkeypatch):+ root = tmp_path / "app"+ root.mkdir()+ pack = _write_pack(root)+ (pack / "big.safetensors").unlink() # required_files.json wants it+ with pytest.raises(SystemExit, match="incomplete"):+ _publish(root, tmp_path / "release", monkeypatch)+++def test_staging_is_left_empty_so_publishing_costs_one_shard(served):+ root, _, _, _, _, _ = served+ staging = root / "staging" / "test-tag"+ leftovers = [p.name for p in staging.iterdir() if p.suffix != ".json" and p.name != "_notes.md"]+ assert leftovers == [], f"shards were not deleted after upload: {leftovers}"+++# --------------------------------------------------------------------------- #+# Fetching+# --------------------------------------------------------------------------- #+def test_round_trip_reassembles_every_file_byte_for_byte(served):+ root, pack, _, dest, _, manifest = served+ assert _fetch(root, dest) == 0+ for name in manifest["files"]:+ assert (dest / name).read_bytes() == (pack / name).read_bytes(), name+ assert not (dest / fetcher.PARTS_DIRNAME).exists(), "parts dir must be cleaned up"+ assert not list(dest.glob("*.partial")), "no partials may survive a success"+++def test_a_corrupted_shard_never_reaches_the_pack(served):+ root, _, release_dir, dest, _, manifest = served+ victim = release_dir / manifest["files"]["big.safetensors"]["shards"][2]["asset"]+ raw = bytearray(victim.read_bytes())+ raw[0] ^= 0xFF # same length, one bad byte+ victim.write_bytes(bytes(raw))++ assert _fetch(root, dest, attempts=1) == 1, "a bad shard must fail the fetch"+ assert not (dest / "big.safetensors").exists(), \+ "a file must only appear under its real name once its hash matches"+ # The good files in the same pack still landed — one poisoned asset is not+ # a reason to throw away 20 GB that verified.+ assert (dest / "small.safetensors").exists()+++def test_a_truncated_shard_resumes_instead_of_restarting(served):+ root, pack, _, dest, hits, manifest = served+ spec = manifest["files"]["big.safetensors"]+ dest.mkdir(parents=True, exist_ok=True)+ parts = dest / fetcher.PARTS_DIRNAME+ parts.mkdir()+ # Simulate a kill mid-shard: half of shard 0 on disk.+ first = spec["shards"][0]+ whole = (pack / "big.safetensors").read_bytes()[:first["bytes"]]+ (parts / first["asset"]).write_bytes(whole[: first["bytes"] // 2])++ hits.clear()+ assert _fetch(root, dest) == 0+ assert (dest / "big.safetensors").read_bytes() == (pack / "big.safetensors").read_bytes()+++def test_a_complete_pack_is_not_downloaded_again(served):+ root, _, _, dest, hits, _ = served+ assert _fetch(root, dest) == 0+ hits.clear()+ assert _fetch(root, dest) == 0+ asset_hits = [h for h in hits if "manifest" not in h]+ assert asset_hits == [], f"re-fetched {asset_hits} on an intact pack"+++def test_a_file_that_is_present_but_wrong_is_refetched(served):+ root, pack, _, dest, _, _ = served+ assert _fetch(root, dest) == 0+ (dest / "big.safetensors").write_bytes(b"junk" * 100)+ assert _fetch(root, dest) == 0+ assert (dest / "big.safetensors").read_bytes() == (pack / "big.safetensors").read_bytes()+++def test_check_only_reports_without_downloading(served):+ root, _, _, dest, hits, _ = served+ rc = fetcher.fetch_pack(PACK_KEY, root, dest, attempts=1, timeout=10, check_only=True)+ assert rc == 1, "an empty destination is not complete"+ assert [h for h in hits if "manifest" not in h] == []+ assert _fetch(root, dest) == 0+ assert fetcher.fetch_pack(PACK_KEY, root, dest, attempts=1, timeout=10,+ check_only=True) == 0+++def test_a_manifest_missing_a_mandatory_file_is_refused_before_downloading(served, monkeypatch):+ root, _, release_dir, dest, hits, manifest = served+ man_path = release_dir / f"{PACK_KEY}__phosphene_release_manifest.json"+ trimmed = json.loads(man_path.read_text())+ trimmed["files"].pop("small.safetensors")+ man_path.write_text(json.dumps(trimmed))+ hits.clear()+ with pytest.raises(SystemExit, match="mandatory"):+ _fetch(root, dest)+ assert [h for h in hits if "manifest" not in h] == [], "refused too late"+++def test_a_pack_with_no_mirror_block_is_refused_not_silently_skipped(tmp_path):+ root = tmp_path / "app"+ root.mkdir()+ _write_pack(root)+ reg = json.loads((root / "required_files.json").read_text())+ reg["repos"][0].pop("mirror")+ (root / "required_files.json").write_text(json.dumps(reg))+ with pytest.raises(SystemExit, match="hf download"):+ fetcher.fetch_pack(PACK_KEY, root, None, attempts=1, timeout=5, check_only=True)+++def test_a_progress_sidecar_that_disagrees_with_the_file_is_ignored(tmp_path):+ """A sidecar is only trusted when the partial's length backs it up —+ otherwise shards splice at the wrong offset and the hash check is the only+ thing standing between the user and a corrupt 11 GB transformer."""+ partial = tmp_path / "x.partial"+ partial.write_bytes(b"0123456789")+ fetcher._write_progress(partial, 3)+ assert fetcher._read_progress(partial) == 3+ partial.write_bytes(b"012") # truncated behind our back+ assert fetcher._read_progress(partial) == 0+++# --------------------------------------------------------------------------- #+# Registry wiring — the real required_files.json, not a fixture+# --------------------------------------------------------------------------- #+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.+ for repo in mirrored:+ m = repo["mirror"]+ assert m["kind"] == "github-release"+ assert m["release_repo"] == "mrbizarro/Phosphene"+ assert m["manifest_asset"] == f"{repo['key']}__phosphene_release_manifest.json"+ assert m["tag"]+ # Every mandatory file has to be fetchable through this lane.+ assert repo.get("files"), f"{repo['key']} declares no required files"+++if __name__ == "__main__":+ sys.exit(pytest.main([__file__, "-q"]))diff --git a/scripts/test_quantize_ltx.py b/scripts/test_quantize_ltx.pynew file mode 100644index 0000000..043c040--- /dev/null+++ b/scripts/test_quantize_ltx.py@@ -0,0 +1,407 @@+#!/usr/bin/env python3+"""Tests for scripts/quantize_ltx.py — the bf16 -> q4/q8 weight pipeline.++No downloads, no GPU, no 40 GB weights. Everything here builds a tiny+*synthetic* LTX DiT with the REAL vendored ``LTXModel``, dumps it as a bf16+source in the real MLX pack layout, quantizes it with the real script, and+then loads it back through the REAL vendored loader functions.++Run: ltx-2-mlx/env/bin/python scripts/test_quantize_ltx.py+ or: ltx-2-mlx/env/bin/python -m unittest scripts.test_quantize_ltx+"""++from __future__ import annotations++import json+import struct+import sys+import tempfile+import unittest+from pathlib import Path++import mlx.core as mx++sys.path.insert(0, str(Path(__file__).resolve().parent))++import quantize_ltx as qz # noqa: E402++qz.add_vendored_to_path()++from ltx_core_mlx.model.transformer.model import LTXModel, LTXModelConfig # noqa: E402++# A DiT small enough to build in a second, big enough to exercise every rule:+# 2 blocks, dims that are multiples of the 64-wide quant group, and the same+# module tree the 22B model has (34 quantizable linears per block).+TINY = LTXModelConfig(+ num_layers=2,+ video_dim=256,+ audio_dim=128,+ video_num_heads=2,+ audio_num_heads=2,+ video_head_dim=128,+ audio_head_dim=64,+ av_cross_num_heads=2,+ av_cross_head_dim=64,+ video_patch_channels=128,+ audio_patch_channels=128,+ ff_mult=2.0,+)+++def flatten(params, prefix=""):+ """dict/list tree of mx.arrays -> flat {dotted.key: array}."""+ out = {}+ if isinstance(params, dict):+ items = params.items()+ elif isinstance(params, (list, tuple)):+ items = ((str(i), v) for i, v in enumerate(params))+ else:+ return {prefix: params}+ for k, v in items:+ out.update(flatten(v, f"{prefix}.{k}" if prefix else k))+ return out+++def write_synthetic_bf16_dit(path: Path) -> dict[str, mx.array]:+ """Build a tiny LTXModel and save its params as a bf16 ``transformer.``-prefixed pack."""+ mx.random.seed(20260811)+ model = LTXModel(TINY)+ flat = flatten(model.parameters())+ tensors = {}+ for k, v in flat.items():+ # Randomize so the dequant probe sees a real distribution, not zeros+ # (a table of zeros would pass any error check).+ arr = mx.random.normal(v.shape) * 0.02 if v.ndim >= 1 else v+ # Mirror the dtypes of the SHIPPED pack: everything bf16 except the+ # scale/shift tables, which are F32 there.+ dtype = mx.float32 if "scale_shift_table" in k else mx.bfloat16+ tensors[f"transformer.{k}"] = arr.astype(dtype)+ mx.eval(list(tensors.values()))+ path.parent.mkdir(parents=True, exist_ok=True)+ mx.save_safetensors(str(path), tensors)+ return tensors+++class RecipeExtraction(unittest.TestCase):+ """The recipe must match what the shipped 2.3 packs actually contain."""++ def test_ltx_recipe_matches_shipped_pack_shape(self):+ r = qz.RECIPES["ltx-dit"]+ self.assertEqual(r.group_size, 64)+ self.assertEqual(r.scales_dtype, "BF16")+ self.assertEqual(r.include_prefixes, ("transformer.transformer_blocks.",))+ self.assertEqual(r.loader_prefix, "transformer.")+ self.assertTrue(r.quant_config_extra["only_transformer_blocks"])++ def test_quantize_config_json_shape(self):+ with tempfile.TemporaryDirectory() as d:+ qz.write_quantize_config(Path(d), qz.RECIPES["ltx-dit"], 4)+ blob = json.loads((Path(d) / "quantize_config.json").read_text())+ # Byte-for-byte the same keys as mlx_models/ltx-2.3-mlx-q4/quantize_config.json+ self.assertEqual(blob, {"quantization": {"bits": 4, "group_size": 64, "only_transformer_blocks": True}})+++class Planner(unittest.TestCase):+ def setUp(self):+ self.tmp = tempfile.TemporaryDirectory()+ self.src = Path(self.tmp.name) / "transformer-distilled.safetensors"+ write_synthetic_bf16_dit(self.src)++ def tearDown(self):+ self.tmp.cleanup()++ def test_only_block_linears_are_quantized(self):+ plan = qz.build_plan(self.src, qz.RECIPES["ltx-dit"], 4)+ # 34 quantizable linears per block x 2 blocks (same count/block as the+ # shipped 48-block pack: 1632 / 48 == 34).+ self.assertEqual(len(plan.quantized_modules), 68)+ for m in plan.quantized_modules:+ self.assertTrue(m.startswith("transformer.transformer_blocks."))+ # Nothing outside the blocks was touched+ outside = [t for t in plan.outputs if ".transformer_blocks." not in t.key]+ self.assertTrue(outside)+ self.assertTrue(all(t.kind == "copy" for t in outside))+ # AdaLN + patch/out projections specifically stay bf16+ by_key = {t.key: t for t in plan.outputs}+ for k in (+ "transformer.patchify_proj.weight",+ "transformer.proj_out.weight",+ "transformer.adaln_single.linear.weight",+ "transformer.prompt_adaln_single.linear.weight",+ ):+ self.assertEqual(by_key[k].kind, "copy", k)+ self.assertEqual(by_key[k].dtype, "BF16", k)++ def test_closed_form_shapes(self):+ for bits in (4, 8):+ plan = qz.build_plan(self.src, qz.RECIPES["ltx-dit"], bits)+ src_index, _, _ = qz.read_header(self.src)+ by_key = {t.key: t for t in plan.outputs}+ for base in plan.quantized_modules:+ out_f, in_f = src_index[base + ".weight"]["shape"]+ self.assertEqual(by_key[base + ".weight"].shape, [out_f, in_f * bits // 32])+ self.assertEqual(by_key[base + ".weight"].dtype, "U32")+ self.assertEqual(by_key[base + ".scales"].shape, [out_f, in_f // 64])+ self.assertEqual(by_key[base + ".scales"].dtype, "BF16")+ self.assertEqual(by_key[base + ".biases"].shape, [out_f, in_f // 64])++ def test_bias_survives_next_to_biases(self):+ plan = qz.build_plan(self.src, qz.RECIPES["ltx-dit"], 4)+ keys = {t.key for t in plan.outputs}+ b = "transformer.transformer_blocks.0.attn1.to_q"+ self.assertIn(f"{b}.bias", keys) # the Linear's real bias, bf16+ self.assertIn(f"{b}.biases", keys) # the quantization zero-points+ by_key = {t.key: t for t in plan.outputs}+ self.assertEqual(by_key[f"{b}.bias"].kind, "copy")+ self.assertEqual(by_key[f"{b}.biases"].kind, "q_biases")+++class RoundTrip(unittest.TestCase):+ """(c) — write a synthetic pack, then point the VENDORED loader at it."""++ def _build(self, bits: int, out: Path) -> Path:+ src = out / "src" / "transformer-distilled.safetensors"+ write_synthetic_bf16_dit(src)+ pack = out / f"pack-q{bits}"+ qz.main(+ [+ "--src", str(src),+ "--out-dir", str(pack),+ "--recipe", "ltx-dit",+ "--bits", str(bits),+ "--probes", "6",+ ]+ )+ return pack++ def test_vendored_loader_accepts_our_pack(self):+ for bits in (4, 8):+ with self.subTest(bits=bits), tempfile.TemporaryDirectory() as d:+ pack = self._build(bits, Path(d))+ f = pack / "transformer-distilled.safetensors"+ self.assertTrue(f.exists())+ self.assertFalse(list(pack.glob("*.partial*")), "partial left behind")++ info = qz.verify_load_ltx_dit(f, config=TINY)+ self.assertTrue(info["loaded"])+ # The loader auto-detects bit width from tensor shapes alone —+ # if our closed-form packing were wrong it would guess wrong.+ self.assertEqual(info["loader_detected_bits"], bits)++ def test_quantized_layers_actually_compute(self):+ """A pack that loads but produces garbage is worse than one that fails."""+ with tempfile.TemporaryDirectory() as d:+ pack = self._build(4, Path(d))+ qz.add_vendored_to_path()+ from ltx_core_mlx.utils.weights import apply_quantization, load_split_safetensors++ f = pack / "transformer-distilled.safetensors"+ weights = load_split_safetensors(f, prefix="transformer.")+ dit = LTXModel(TINY)+ apply_quantization(dit, weights)+ dit.load_weights(list(weights.items()))+ mx.eval(dit.parameters())++ layer = dit.transformer_blocks[0].attn1.to_q+ self.assertEqual(type(layer).__name__, "QuantizedLinear")+ src = Path(d) / "src" / "transformer-distilled.safetensors"+ ref_w = mx.load(str(src))["transformer.transformer_blocks.0.attn1.to_q.weight"].astype(mx.float32)+ ref_b = mx.load(str(src))["transformer.transformer_blocks.0.attn1.to_q.bias"].astype(mx.float32)+ x = mx.random.normal((3, ref_w.shape[1])).astype(mx.bfloat16)+ got = layer(x).astype(mx.float32)+ want = x.astype(mx.float32) @ ref_w.T + ref_b+ rel = float(mx.mean(mx.abs(got - want))) / float(mx.mean(mx.abs(want)))+ self.assertLess(rel, 0.15, f"q4 forward diverged from bf16 reference: rel={rel}")++ def test_manifest_and_configs(self):+ with tempfile.TemporaryDirectory() as d:+ pack = self._build(8, Path(d))+ man = json.loads((pack / qz.MANIFEST_NAME).read_text())+ entry = man["files"]["transformer-distilled.safetensors"]+ self.assertEqual(len(entry["sha256"]), 64)+ self.assertEqual(+ entry["sha256"], qz.sha256_file(pack / "transformer-distilled.safetensors"), "manifest sha is wrong"+ )+ self.assertEqual(entry["bits"], 8)+ self.assertEqual(entry["modules_quantized"], 68)+ cfg = json.loads((pack / "quantize_config.json").read_text())+ self.assertEqual(cfg["quantization"]["bits"], 8)+++class FromPack(unittest.TestCase):+ """The whole-pack driver — the exact command shape used when 2.5 bf16 lands."""++ def _bf16_pack(self, root: Path) -> Path:+ """A miniature bf16 MLX-layout LTX pack: two transformer variants + the+ components the shipped packs never quantize."""+ src = root / "bf16"+ src.mkdir(parents=True)+ for variant in ("distilled", "dev"):+ write_synthetic_bf16_dit(src / f"transformer-{variant}.safetensors")+ mx.save_safetensors(+ str(src / "connector.safetensors"), {"connector.x.weight": mx.zeros((8, 128)).astype(mx.bfloat16)}+ )+ mx.save_safetensors(+ str(src / "vae_decoder.safetensors"), {"vae_decoder.y.weight": mx.zeros((8, 128)).astype(mx.bfloat16)}+ )+ (src / "config.json").write_text(json.dumps({"model_version": "2.5.0"}))+ (src / "split_model.json").write_text(+ json.dumps({"format": "split", "model_version": "2.5.0", "components": ["connector", "vae_decoder"]})+ )+ return src++ def test_builds_a_full_pack(self):+ with tempfile.TemporaryDirectory() as d:+ root = Path(d)+ src = self._bf16_pack(root)+ out = root / "q4"+ qz.main(+ [+ "--from-pack", str(src),+ "--out-dir", str(out),+ "--recipe", "ltx-dit",+ "--bits", "4",+ "--variants", "distilled",+ ]+ )+ names = {p.name for p in out.iterdir()}+ # only the requested variant was quantized...+ self.assertIn("transformer-distilled.safetensors", names)+ self.assertNotIn("transformer-dev.safetensors", names)+ # ...never-quantized components came across verbatim...+ for n in ("connector.safetensors", "vae_decoder.safetensors", "config.json"):+ self.assertIn(n, names)+ self.assertEqual(+ qz.sha256_file(out / "connector.safetensors"),+ qz.sha256_file(src / "connector.safetensors"),+ "a never-quantized component was modified",+ )+ # ...and the pack-level JSONs match the shipped 2.3 shape.+ self.assertEqual(+ json.loads((out / "quantize_config.json").read_text()),+ {"quantization": {"bits": 4, "group_size": 64, "only_transformer_blocks": True}},+ )+ split = json.loads((out / "split_model.json").read_text())+ self.assertTrue(split["quantized"])+ self.assertEqual(split["quantization_bits"], 4)++ man = json.loads((out / qz.MANIFEST_NAME).read_text())+ for n in ("transformer-distilled.safetensors", "connector.safetensors", "quantize_config.json"):+ self.assertIn(n, man["files"], n)+ self.assertEqual(man["files"][n]["sha256"], qz.sha256_file(out / n), n)++ # the quantized transformer still loads through the vendored loader+ info = qz.verify_load_ltx_dit(out / "transformer-distilled.safetensors", config=TINY)+ self.assertEqual(info["loader_detected_bits"], 4)+++class Determinism(unittest.TestCase):+ """(b) — the same input must produce byte-identical output, every run."""++ def test_two_runs_are_byte_identical(self):+ with tempfile.TemporaryDirectory() as d:+ root = Path(d)+ src = root / "transformer-distilled.safetensors"+ write_synthetic_bf16_dit(src)+ shas = []+ for run in ("a", "b"):+ out = root / run+ qz.main(["--src", str(src), "--out-dir", str(out), "--recipe", "ltx-dit", "--bits", "4"])+ shas.append(qz.sha256_file(out / "transformer-distilled.safetensors"))+ self.assertEqual(shas[0], shas[1], "quantization is not reproducible")+++class Robustness(unittest.TestCase):+ def test_truncated_output_is_never_published(self):+ """A plan/write mismatch must leave no final file."""+ with tempfile.TemporaryDirectory() as d:+ root = Path(d)+ src = root / "transformer-distilled.safetensors"+ write_synthetic_bf16_dit(src)+ plan = qz.build_plan(src, qz.RECIPES["ltx-dit"], 4)+ plan.outputs[-1].nbytes += 4096 # lie about the size+ out = root / "bad.safetensors"+ with self.assertRaises(SystemExit):+ qz.write_quantized(plan, out, qz.RECIPES["ltx-dit"], 4, stamp_metadata=False, verbose=False)+ self.assertFalse(out.exists())+ self.assertFalse(qz._partial_path(out).exists())++ def test_disk_preflight_refuses(self):+ with tempfile.TemporaryDirectory() as d:+ with self.assertRaises(SystemExit):+ qz.preflight_disk(Path(d), 10**18)++ def test_unaligned_weight_is_reported_not_dropped(self):+ with tempfile.TemporaryDirectory() as d:+ src = Path(d) / "t.safetensors"+ mx.save_safetensors(+ str(src),+ {+ "transformer.transformer_blocks.0.odd.weight": mx.zeros((8, 100)).astype(mx.bfloat16),+ "transformer.transformer_blocks.0.ok.weight": mx.zeros((8, 128)).astype(mx.bfloat16),+ },+ )+ plan = qz.build_plan(src, qz.RECIPES["ltx-dit"], 4)+ self.assertEqual(len(plan.skipped_unaligned), 1)+ self.assertEqual(len(plan.quantized_modules), 1)+ keys = {t.key: t for t in plan.outputs}+ # unaligned one is still present, at bf16 — never silently dropped+ self.assertEqual(keys["transformer.transformer_blocks.0.odd.weight"].dtype, "BF16")++ def test_header_is_deterministic_and_metadata_preserved(self):+ with tempfile.TemporaryDirectory() as d:+ src = Path(d) / "t.safetensors"+ mx.save_safetensors(+ str(src),+ {"transformer.transformer_blocks.0.ok.weight": mx.zeros((8, 128)).astype(mx.bfloat16)},+ metadata={"config": '{"model_version":"2.5.0"}'},+ )+ plan = qz.build_plan(src, qz.RECIPES["ltx-dit"], 8)+ out = Path(d) / "o.safetensors"+ qz.write_quantized(plan, out, qz.RECIPES["ltx-dit"], 8, stamp_metadata=True, verbose=False)+ _, meta, _ = qz.read_header(out)+ # the 2.5 metadata-driven config path depends on this surviving+ self.assertEqual(json.loads(meta["config"])["model_version"], "2.5.0")+ stamp = json.loads(meta["phosphene_quant"])+ self.assertEqual(stamp["bits"], 8)+ self.assertEqual(stamp["group_size"], 64)+ # no wall-clock anywhere in the safetensors metadata (would break determinism)+ self.assertNotIn("utc", json.dumps(meta).lower())++ def test_writes_are_atomic(self):+ """The in-flight name keeps a loadable extension and is never the final name."""+ p = qz._partial_path(Path("/x/transformer-distilled.safetensors"))+ self.assertEqual(p.name, "transformer-distilled.partial.safetensors")+ self.assertEqual(p.suffix, ".safetensors")+++class SafetensorsFormat(unittest.TestCase):+ def test_our_writer_matches_mlx_reader(self):+ with tempfile.TemporaryDirectory() as d:+ src = Path(d) / "t.safetensors"+ ref = {+ "transformer.transformer_blocks.0.ok.weight": mx.random.normal((8, 128)).astype(mx.bfloat16),+ "transformer.scale_shift_table": mx.random.normal((2, 8)).astype(mx.float32),+ }+ mx.eval(list(ref.values()))+ mx.save_safetensors(str(src), ref)+ plan = qz.build_plan(src, qz.RECIPES["ltx-dit"], 8)+ out = Path(d) / "o.safetensors"+ qz.write_quantized(plan, out, qz.RECIPES["ltx-dit"], 8, stamp_metadata=False, verbose=False)+ got = mx.load(str(out))+ # F32 tables pass through untouched, bit for bit+ self.assertTrue(bool(mx.all(got["transformer.scale_shift_table"] == ref["transformer.scale_shift_table"])))+ self.assertEqual(got["transformer.scale_shift_table"].dtype, mx.float32)+ # offsets are contiguous and cover the file exactly+ index, _, start = qz.read_header(out)+ spans = sorted(v["data_offsets"] for v in index.values())+ self.assertEqual(spans[0][0], 0)+ for a, b in zip(spans, spans[1:]):+ self.assertEqual(a[1], b[0], "non-contiguous offsets")+ self.assertEqual(start + spans[-1][1], out.stat().st_size)+ with open(out, "rb") as f:+ self.assertEqual(struct.unpack("<Q", f.read(8))[0], start - 8)+++if __name__ == "__main__":+ unittest.main(verbosity=2)diff --git a/storyboard.py b/storyboard.pyindex c786aac..97b6441 100644--- a/storyboard.py+++ b/storyboard.py@@ -41,6 +41,13 @@ Consequences, which are the whole architecture:PLANNER MODEL: Qwen3.5, NOT Gemma (decided 2026-07-24)--------------------------------------------------------+WHAT ACTUALLY SHIPS IS GEMMA. Read this section as the decision record it is, not as a+description of the running system: `storyboard_planner.py` plans on+`mlx_models/gemma-3-12b-it-4bit` — the weights the panel already downloads for+`/prompt/enhance` — so the Storyboard tab costs a user zero new bytes. Qwen3.5 remains the+target and is a one-line switch (`LTX_STORYBOARD_PLANNER`); the reasoning below is why.+See the MODEL section at the top of `storyboard_planner.py` for the shipped arrangement.+Gemma 3 stays for `/prompt/enhance` — different task, already tuned, already loaded. Butplanning is 100% structured output, and this project already documented that "Gemma 3 has nonative tool_calls". Gemma 4 has no clean official mlx-community 4-bit build (third-party /@@ -101,12 +108,151 @@ _PIPELINE_BUCKET = {"a2v": "a2v",}+# Storyboard mode -> the mode string the PANEL'S job form actually speaks.+#+# This is load-bearing and it is not cosmetic. `mlx_ltx_panel.py` has exactly one backend+# video mode for both of v1's shot types: t2v. "Character" is a UI INTENT there, not a mode —+# the panel's own setMode('character') sets the hidden #mode field to 't2v' and lets+# `character_id` drive the LoRA stack ("Mode hidden field still 't2v' — backend doesn't know+# 'character' and doesn't need to"). Posting mode="character" or mode="text" to /queue/add+# reaches run_job_inner with a mode nothing dispatches on.+_PANEL_MODE = {+ "text": "t2v",+ "character": "t2v",+ "remix": "t2v", # remix rides t2v + an IC-LoRA ref; not enqueued in v1 (no refs)+ "keyframe": "keyframe",+ "extend": "extend",+ "a2v": "a2v",+}++# Engines a shot may name. Anything else falls back to the built-in one.+VALID_ENGINES = ("ltx", "h3")+DEFAULT_ENGINE = "ltx"++# The FILM-level engine choice, which the user makes once in the brief.+# "auto" — the plan decides per shot: a cast shot goes to LTX (that is where+# character LoRAs load), everything else to H3.+# "h3" — every shot on Hailuo H3. The planner writes the whole film in H3's+# three-field dialect. A trained character cannot come along: H3+# stacks no LoRAs, so a cast shot would render a stranger.+# "ltx" — every shot on LTX-2.3. The planner drops the H3 dialect entirely.+# It is a PLANNING input, not a post-hoc filter: the two engines want prompts+# written differently (`_assemble_h3_prompt` vs `_assemble_ltx_prompt`), so+# changing it on an existing film means re-planning, not re-labelling.+ENGINE_MODES = ("auto", "h3", "ltx")+DEFAULT_ENGINE_MODE = "auto"++# A film is shot TWICE: a cheap draft pass you watch, then a delivery pass of+# only the shots you kept. Which pass a shot has already been through is a+# property of that PASS, and the board records it as the pass's own output key —+# never as the shot's single `status`, which only ever describes the most recent+# thing that happened to it.+#+# That distinction is load-bearing and it was once got wrong: the scheduler+# filtered on `status not in ("done", "skipped")` while the reconciler set+# `status = "done"` the moment the DRAFT landed, so by the time the delivery+# pass asked for work every shot looked finished. `/storyboard/render pass=final`+# answered 202 and enqueued nothing, for every film, forever.+PASS_NAMES = ("draft", "final")+_PASS_OUTPUT_KEY = {"draft": "draft_output", "final": "final_output"}+_PASS_JOB_KEY = {"draft": "draft_job_id", "final": "final_job_id"}+++def pass_output_key(pass_name: str = "draft") -> str:+ """The board field holding this pass's rendered clip."""+ return _PASS_OUTPUT_KEY.get((pass_name or "draft").strip().lower(), "draft_output")+++def pass_job_key(pass_name: str = "draft") -> str:+ """The board field holding this pass's job id."""+ return _PASS_JOB_KEY.get((pass_name or "draft").strip().lower(), "draft_job_id")+++def shot_pass_done(shot: dict, pass_name: str = "draft") -> bool:+ """Has THIS shot already been through THIS pass? The only correct test."""+ return bool(shot.get(pass_output_key(pass_name)))+++def shots_pending(shots: Iterable[dict], pass_name: str = "draft") -> list[dict]:+ """Shots this pass still has to render, in board order.++ A cut shot is out of every pass. Everything else is in until it has that+ pass's own output — a finished draft does NOT excuse a shot from delivery.+ """+ return [s for s in (shots or [])+ if isinstance(s, dict)+ and s.get("status") != "skipped"+ and not shot_pass_done(s, pass_name)]+++def resolve_engine(shot: dict, *, engine_mode: str = DEFAULT_ENGINE_MODE,+ h3_available: bool = True) -> str:+ """The engine this shot will ACTUALLY render on. One function, every caller.++ Precedence, strongest first:+ 1. no H3 pack on this machine -> LTX, always;+ 2. the shot is cast -> LTX, always (H3 stacks no LoRAs, so a cast shot on+ H3 renders a stranger — the exact failure `ensure_trigger` exists for);+ 3. the film's engine mode, when it is not "auto";+ 4. what the plan wrote on the shot.+ """+ if not h3_available:+ return "ltx"+ if shot.get("character_id"):+ return "ltx"+ mode = (engine_mode or DEFAULT_ENGINE_MODE).strip().lower()+ if mode in ("h3", "ltx"):+ return mode+ return shot_engine(shot)++# LTX renders at 24 fps and the sampler requires frames % 8 == 1.+LTX_FPS = 24++# H3's duration axis. The panel owns the canonical table (H3_TIERS, built from a quality axis+# and a length axis); these are the LENGTH keys and the frame count each one delivers, on the+# 17n+5 grid the runner snaps to. Duplicated here — as data, not as a second cost model — so+# `shot_to_job()` emits a self-consistent job dict without importing the panel (this module is+# deliberately pure-stdlib so it unit-tests with no GPU and no weights). make_job re-stamps+# width/height/frames from the real cell, so the panel is still the authority; a drift here+# can only make the pre-flight job dict look wrong, never make a render come out wrong.+H3_LENGTHS = ("3s", "5s", "10s", "15s")+_H3_LENGTH_SECONDS = {"3s": 3.0, "5s": 5.0, "10s": 10.0, "15s": 15.0}+_H3_LENGTH_FRAMES = {"3s": 73, "5s": 124, "10s": 243, "15s": 362}+# How many chained 5 s windows each length renders as. Anything past 5 s is+# 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}++# 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+# clip with Turbo and ~45 without, which is not a cost any pass-level choice should be able+# to opt someone into silently.+_H3_QUALITY_FOR_PASS = {+ "quick": "draft",+ "balanced": "standard",+ "standard": "high",+ "high": "high",+}+# Rough per-second-of-video render cost, by quality, in seconds of wall clock. Deliberately# pessimistic — the estimate exists to stop someone starting a 6-hour job unaware, not to be# a benchmark. Tuned against observed two-stage 1536x896 ~11 min for a 5 s clip._SECS_PER_VIDEO_SEC = {"quick": 24.0, "balanced": 60.0, "standard": 96.0, "high": 132.0}_PIPELINE_LOAD_SECS = 90.0+# H3 FALLBACK cost, per second of video, by canvas. The panel passes `h3_cost=` into+# estimate() and that hook wins every time — it reads H3_TIERS[cell]["eta_min"], which is+# MEASURED wall clock per cell and is the only number allowed on screen. This table exists so+# storyboard.py keeps working (and keeps unit-testing) standalone, and it is derived from the+# same measurements rather than invented:+# draft 3s 3.0 min / 3 s = 60 s per video-second+# standard 5s 9.1 min / 5 s = 109+# high 5s 18.8 min / 5 s = 226 (no Turbo)+# native 5s 44.9 min / 5 s = 538 (no Turbo, never selected by a pass)+# An H3 clip is a fresh subprocess that loads its own weights, so this per-clip number is+# END TO END — which is why an H3 bucket adds no separate pipeline-load charge below.+_H3_SECS_PER_VIDEO_SEC = {"draft": 60.0, "standard": 109.0, "high": 226.0, "native": 538.0}+class StoryboardError(Exception):"""Raised for malformed storyboards. Message is user-facing."""@@ -190,91 +336,129 @@ def list_storyboards(state_dir: Path) -> list[dict]:# Phase 2 — VALIDATE (no models, sub-second, runs BEFORE anything renders)# ----------------------------------------------------------------------------def validate_storyboard(+def validate_storyboard_detail(board: dict,*,known_character_ids: Iterable[str] = (),ref_root: Path | None = None,max_dim: int | None = None,-) -> list[str]:- """Return a list of human-readable problems. Empty list == good to shoot.+) -> list[dict]:+ """Every check `validate_storyboard()` makes, STRUCTURED. Empty list == good to shoot.++ Each entry is::- The whole point: a two-hour render must never begin on a plan that cannot succeed.+ {"code": "missing_trigger", # stable machine name, never translated+ "n": 3 | None, # which shot, when it is about one+ "field": "prompt" | None, # which control to focus / flag+ "message": "<the exact string validate_storyboard() has always returned>",+ "data": {...}} # whatever a fix button needs++ This exists so the UI can render its own human copy per `code` and still put a Fix button+ beside the right control, WITHOUT regexing English out of `message`. `validate_storyboard()`+ below is now a formatter over this, so the strings stay byte-identical by construction and+ the panel's copy can never drift from the check that produced it.++ The whole point of both: a two-hour render must never begin on a plan that cannot succeed.Everything here is cheap string/path/int checking, so it costs ~nothing and can run onevery save. Errors read as a fix-list, not a stack trace."""- errs: list[str] = []+ errs: list[dict] = []chars = set(known_character_ids or ())+ def add(code: str, message: str, *, n: int | None = None,+ field: str | None = None, **data: Any) -> None:+ errs.append({"code": code, "n": n, "field": field,+ "message": message, "data": data})+if board.get("schema") != SCHEMA_VERSION:- errs.append(- f"schema version {board.get('schema')!r} — this build understands {SCHEMA_VERSION}"- )+ add("schema_version",+ f"schema version {board.get('schema')!r} — this build understands {SCHEMA_VERSION}",+ got=board.get("schema"), expected=SCHEMA_VERSION)if not str(board.get("id") or "").strip():- errs.append("storyboard.id is empty")+ add("board_id_empty", "storyboard.id is empty")shots = board.get("shots")if not isinstance(shots, list) or not shots:- errs.append("storyboard has no shots")+ add("no_shots", "storyboard has no shots")return errspolicy = board.get("policy") or {}seen_n: set[int] = set()for idx, s in enumerate(shots):- where = f"shot {s.get('n', idx + 1)}"+ # `where` used to be computed from s.get() BEFORE the isinstance check, so a shot that+ # was a string (exactly the case the next line reports) raised AttributeError instead+ # of returning the error. Fall back to the positional number for a non-dict.if not isinstance(s, dict):- errs.append(f"{where}: not an object")+ add("shot_not_object", f"shot {idx + 1}: not an object", n=idx + 1)continue+ num = s.get("n", idx + 1)+ where = f"shot {num}"+ n_for_ui = num if isinstance(num, int) else idx + 1n = s.get("n")if not isinstance(n, int) or n < 1:- errs.append(f"{where}: 'n' must be a positive integer")+ add("shot_number", f"{where}: 'n' must be a positive integer",+ n=n_for_ui, field="n", got=n)elif n in seen_n:- errs.append(f"{where}: duplicate shot number {n}")+ add("shot_duplicate", f"{where}: duplicate shot number {n}",+ n=n_for_ui, field="n", duplicate=n)else:seen_n.add(n)mode = s.get("mode")if mode not in VALID_MODES:- errs.append(f"{where}: mode {mode!r} is not one of {', '.join(VALID_MODES)}")+ add("bad_mode",+ f"{where}: mode {mode!r} is not one of {', '.join(VALID_MODES)}",+ n=n_for_ui, field="mode", mode=mode, valid=list(VALID_MODES))prompt = (s.get("prompt") or "").strip()if not prompt:- errs.append(f"{where}: empty prompt")+ add("empty_prompt", f"{where}: empty prompt", n=n_for_ui, field="prompt")cid = s.get("character_id")if cid:if chars and cid not in chars:- errs.append(+ add("unknown_character",f"{where}: character {cid!r} is not installed "- f"(have: {', '.join(sorted(chars)) or 'none'})"- )+ f"(have: {', '.join(sorted(chars)) or 'none'})",+ n=n_for_ui, field="character_id",+ character_id=cid, have=sorted(chars))# The trigger is injected mechanically, never trusted to the LLM — but if a plan# arrives with a character and the trigger is missing from the prompt, the LoRA# will not fire and the shot silently renders a stranger. Catch it here.trig = (s.get("trigger") or cid or "").strip()if trig and not re.search(rf"\b{re.escape(trig)}\b", prompt):- errs.append(f"{where}: prompt is missing the character trigger {trig!r}")+ add("missing_trigger",+ f"{where}: prompt is missing the character trigger {trig!r}",+ n=n_for_ui, field="prompt", trigger=trig)elif mode == "character":- errs.append(f"{where}: mode 'character' requires a character_id")+ add("character_without_id",+ f"{where}: mode 'character' requires a character_id",+ n=n_for_ui, field="character_id")dur = s.get("duration_s")if not isinstance(dur, (int, float)) or not (0 < float(dur) <= 60):- errs.append(f"{where}: duration_s must be between 0 and 60 (got {dur!r})")+ add("bad_duration",+ f"{where}: duration_s must be between 0 and 60 (got {dur!r})",+ n=n_for_ui, field="duration_s", duration_s=dur)refs = s.get("refs") or []if not isinstance(refs, list):- errs.append(f"{where}: refs must be a list")+ add("refs_not_list", f"{where}: refs must be a list",+ n=n_for_ui, field="refs")else:for r in refs:rp = Path(r)if ref_root is not None and not rp.is_absolute():rp = Path(ref_root) / rpif not rp.is_file():- errs.append(f"{where}: reference image not found: {r}")+ add("ref_missing", f"{where}: reference image not found: {r}",+ n=n_for_ui, field="refs", ref=str(r), name=Path(str(r)).name)if mode == "remix" and not refs:- errs.append(f"{where}: mode 'remix' needs at least one reference image")+ add("remix_needs_ref",+ f"{where}: mode 'remix' needs at least one reference image",+ n=n_for_ui, field="refs")# Resolution legality for the active tier. Q4 machines clamp; a plan that assumes 1536# on a 16 GB Mac would either clamp silently or swap, so surface it now.@@ -283,18 +467,57 @@ def validate_storyboard(p = policy.get(key) or {}w, h = p.get("width"), p.get("height")if isinstance(w, int) and isinstance(h, int) and max(w, h) > max_dim:- errs.append(+ add("over_cap",f"policy.{key}: {w}x{h} exceeds this machine's {max_dim}px cap — "- f"lower it or the render will clamp"- )+ f"lower it or the render will clamp",+ field=f"policy.{key}", pass_name=key, width=w, height=h, max_dim=max_dim)return errs+def validate_storyboard(+ board: dict,+ *,+ known_character_ids: Iterable[str] = (),+ ref_root: Path | None = None,+ max_dim: int | None = None,+) -> list[str]:+ """Return a list of human-readable problems. Empty list == good to shoot.++ A formatter over validate_storyboard_detail(): same checks, same order, byte-identical+ strings. Kept because it is the documented public surface and it reads better at a REPL.+ """+ return [e["message"] for e in validate_storyboard_detail(+ board,+ known_character_ids=known_character_ids,+ ref_root=ref_root,+ max_dim=max_dim,+ )]++# ---------------------------------------------------------------------------# Phase 3 — SHOOT: scheduling# ----------------------------------------------------------------------------def shooting_order(shots: list[dict]) -> list[dict]:+def shot_engine(shot: dict) -> str:+ """The engine a shot renders on, normalised. Unknown / missing -> the built-in one."""+ e = str(shot.get("engine") or "").strip().lower()+ return e if e in VALID_ENGINES else DEFAULT_ENGINE+++def bucket_key(shot: dict) -> tuple[str, str]:+ """The scheduling bucket: (engine, pipeline kind).++ ENGINE IS PART OF THE KEY, and that is the whole fix. Keying on `mode` alone put an H3+ `text` shot in the same bucket as an LTX one, so a mixed film interleaved the two — and an+ H3 job *tears the LTX warm helper down* before it runs (run_h3_job_inner kills it; 40 GiB+ + the helper's weights does not fit on a 64 GB Mac) and the helper cold-starts again on the+ next LTX job. Interleaved, that teardown is paid per switch, which INVERTS the exact cost+ this grouping exists to avoid.+ """+ return (shot_engine(shot), _PIPELINE_BUCKET.get(shot.get("mode"), "t2v"))+++def shooting_order(shots: list[dict], pass_name: str = "draft") -> list[dict]:"""Group shots by pipeline bucket so the warm helper reloads once per KIND, not per shot.This is the single biggest wall-clock win on Apple Silicon and it exists purely because@@ -305,56 +528,193 @@ def shooting_order(shots: list[dict]) -> list[dict]:Order within a bucket, and the order of buckets, is by first appearance in the story, sooutput stays deterministic and a resumed run reproduces the same sequence. Clips arere-sorted by `n` at assembly, so viewing order is unaffected.++ `pass_name` decides what "still to shoot" MEANS — see shots_pending(). Calling this+ without it schedules the draft pass, which is what every pre-existing caller wanted."""- pending = [s for s in shots if s.get("status") not in ("done", "skipped")]- bucket_first: dict[str, int] = {}+ pending = shots_pending(shots, pass_name)+ bucket_first: dict[tuple[str, str], int] = {}for s in pending:- b = _PIPELINE_BUCKET.get(s.get("mode"), "t2v")+ b = bucket_key(s)n = s.get("n") or 0if b not in bucket_first or n < bucket_first[b]:bucket_first[b] = nreturn sorted(pending,- key=lambda s: (- bucket_first.get(_PIPELINE_BUCKET.get(s.get("mode"), "t2v"), 1 << 30),- s.get("n") or 0,- ),+ key=lambda s: (bucket_first.get(bucket_key(s), 1 << 30), s.get("n") or 0),)-def estimate(board: dict, *, pass_name: str = "final") -> dict:+def h3_length_for(duration_s: float) -> str:+ """Snap a duration onto H3's length axis. Ties go to the shorter window."""+ d = float(duration_s or 0) or 5.0+ return min(H3_LENGTHS, key=lambda k: (abs(_H3_LENGTH_SECONDS[k] - d), _H3_LENGTH_SECONDS[k]))+++def h3_quality_for(quality: str) -> str:+ """A pass's quality -> H3's canvas axis."""+ return _H3_QUALITY_FOR_PASS.get((quality or "").strip().lower(), "standard")+++def ltx_frames_for(duration_s: float) -> int:+ """Seconds -> an LTX frame count on the sampler's `frames % 8 == 1` grid, at 24 fps.++ 3 s -> 73 · 5 s -> 121 · 7 s -> 169 · 10 s -> 241, which is exactly the table docs/API.md+ publishes, so a storyboard shot and a hand-typed generation of the same length produce the+ same number of frames.+ """+ d = float(duration_s or 0)+ if d <= 0:+ return 0+ n = max(1, round(d * LTX_FPS))+ return max(9, 8 * round((n - 1) / 8) + 1)+++def h3_chain_prompts_for(shot: dict) -> list[str]:+ """Per-window prompts for a chained H3 shot. `[]` when it isn't chained.++ A 10 s clip renders as two 5-second windows and a 15 s as three, and by+ default EVERY window is asked for the same prompt — so a one-off action+ ("he raises his arm", a line of dialogue) happens once per window and the+ clip reads as a repeat. That is the artifact `H3_CHAIN_PROMPT_HELP` in the+ panel describes, and it is the single most-reported thing about long H3+ clips.++ The planner writes ONE description per shot, so there is no second beat to+ hand window 2 — but there IS a `settle`: the state the shot is required to+ end in (law L3, and the field exists because the model skipped the law when+ it was only written as a rule). So the first window plays the shot, and+ every later window is told to hold that settled state and start nothing new.+ That is the honest reading of a 10 s shot whose action was written for one+ window, and it is strictly better than saying it twice.++ Window 1 is `""` — the panel's own contract for "use the main prompt" — so+ the shot's real prompt is never duplicated into the array.+ """+ if shot_engine(shot) != "h3":+ return []+ windows = _H3_LENGTH_WINDOWS.get(h3_length_for(shot.get("duration_s") or 0), 1)+ if windows <= 1:+ return []+ settle = (shot.get("settle") or "").strip().rstrip(".")+ if not settle:+ # Nothing honest to say about how it should continue — leave the array+ # empty, which is exactly today's behaviour, rather than inventing one.+ return []+ sound = (shot.get("soundscape") or "").strip()+ tail = ("integrated_multimodal_description: The shot continues without a cut, "+ "exactly where it left off. The camera holds completely still, the "+ "frame never moves - no pan, no push-in, no reframing. Nothing new "+ f"begins and no action restarts: {settle}, and that settled state is "+ "simply held for the whole window. Every face holds the exact angle "+ "to the lens it has at the start. No text appears at any point.")+ if sound:+ tail += "\n\noverall_soundscape: " + sound+ tail += "\n\nnon_diegetic_music: N/A"+ return [""] + [tail] * (windows - 1)+++def shot_render_secs(shot: dict, policy_pass: dict, *, h3_cost=None) -> float:+ """Wall clock for ONE shot, on the engine it actually renders on.++ `h3_cost(quality_key, length_key) -> seconds | None` is the panel's measured per-cell hook+ (H3_TIERS[cell]["eta_min"] * 60). When it is absent or returns nothing we fall back to+ `_H3_SECS_PER_VIDEO_SEC`, which is derived from the same measurements. LTX keeps the+ per-second table it has always used.+ """+ dur = float(shot.get("duration_s") or 0)+ quality = policy_pass.get("quality", "balanced")+ if shot_engine(shot) == "h3":+ lk = h3_length_for(dur)+ qk = h3_quality_for(quality)+ if h3_cost is not None:+ try:+ got = h3_cost(qk, lk)+ except Exception:+ got = None+ if got:+ return float(got)+ return _H3_SECS_PER_VIDEO_SEC.get(qk, 109.0) * _H3_LENGTH_SECONDS[lk]+ return dur * _SECS_PER_VIDEO_SEC.get(quality, 60.0)+++def estimate(board: dict, *, pass_name: str = "final", h3_cost=None) -> dict:"""Wall-clock estimate for a pass, accounting for pipeline reloads.Deliberately pessimistic. Its job is to let someone see '2 h 40 m' BEFORE committing,and to show what grouped scheduling saves versus naive story order.++ ENGINE-AWARE since 2026-08-11. It used to price every shot off the LTX per-second table,+ which under-reports an H3 shot by roughly 2x (an H3 5 s High clip is ~8.5 min measured+ against this table's ~5 min, and a Native 5 s is ~20). A number the summary bar prints+ before someone spends an afternoon has to be honest for the film they actually planned.++ Only LTX buckets are charged a pipeline load: an H3 job is a fresh subprocess that loads+ its own weights every time, so that cost is already inside its measured per-clip eta."""- shots = [s for s in (board.get("shots") or []) if s.get("status") not in ("done", "skipped")]+ shots = shots_pending(board.get("shots") or [], pass_name)policy = (board.get("policy") or {}).get(pass_name) or {}- quality = policy.get("quality", "balanced")- per_sec = _SECS_PER_VIDEO_SEC.get(quality, 60.0)- render = sum(float(s.get("duration_s") or 0) * per_sec for s in shots)+ render = sum(shot_render_secs(s, policy, h3_cost=h3_cost) for s in shots)++ grouped = {bucket_key(s) for s in shots}+ grouped_loads = len(grouped)+ grouped_ltx = sum(1 for b in grouped if b[0] != "h3")- grouped_loads = len({_PIPELINE_BUCKET.get(s.get("mode"), "t2v") for s in shots})naive_loads = 0+ naive_ltx = 0prev = Nonefor s in sorted(shots, key=lambda x: x.get("n") or 0):- b = _PIPELINE_BUCKET.get(s.get("mode"), "t2v")+ b = bucket_key(s)if b != prev:naive_loads += 1+ if b[0] != "h3":+ naive_ltx += 1prev = b+ engine_mix: dict[str, int] = {}+ for s in shots:+ e = shot_engine(s)+ engine_mix[e] = engine_mix.get(e, 0) + 1+return {"pass": pass_name,"shots": len(shots),"render_secs": round(render),"pipeline_loads": grouped_loads,- "total_secs": round(render + grouped_loads * _PIPELINE_LOAD_SECS),- "naive_total_secs": round(render + naive_loads * _PIPELINE_LOAD_SECS),- "saved_secs": round((naive_loads - grouped_loads) * _PIPELINE_LOAD_SECS),+ "total_secs": round(render + grouped_ltx * _PIPELINE_LOAD_SECS),+ "naive_total_secs": round(render + naive_ltx * _PIPELINE_LOAD_SECS),+ "saved_secs": round((naive_ltx - grouped_ltx) * _PIPELINE_LOAD_SECS),+ # Additive, for the UI: the run strip draws one segment per bucket, and the summary+ # bar says "Hailuo H3 isn't installed" only when it has to.+ "engine_mix": engine_mix,+ "runtime_secs": round(sum(float(s.get("duration_s") or 0) for s in shots)),+ "buckets": [+ {"engine": e, "kind": k,+ "shots": sorted(s.get("n") or 0 for s in shots if bucket_key(s) == (e, k))}+ for (e, k) in sorted(+ grouped,+ key=lambda b: min((s.get("n") or 0) for s in shots if bucket_key(s) == b),+ )+ ],}+def per_shot_estimate(board: dict, *, pass_name: str = "final", h3_cost=None) -> dict:+ """`{n: seconds}` for every shot in the board, on the same cost model estimate() uses.++ The shot card prints `~2 m` from this. Server-computed on purpose: the per-second constants+ and the measured H3 cells then live in exactly one place instead of being re-typed in JS.+ """+ policy = (board.get("policy") or {}).get(pass_name) or {}+ out: dict = {}+ for s in (board.get("shots") or []):+ if not isinstance(s, dict):+ continue+ out[str(s.get("n") or 0)] = round(shot_render_secs(s, policy, h3_cost=h3_cost))+ return out++def ensure_trigger(prompt: str, trigger: str) -> str:"""Guarantee the character trigger is present, mechanically.@@ -375,33 +735,97 @@ def ensure_trigger(prompt: str, trigger: str) -> str:return f"{t} {p}" if p else t-def shot_to_job(shot: dict, policy_pass: dict) -> dict:+def shot_to_job(shot: dict, policy_pass: dict, *,+ board_id: str = "", board_title: str = "",+ h3_available: bool = True,+ engine_mode: str = DEFAULT_ENGINE_MODE,+ h3_chain_prompts: bool = False) -> dict:"""Translate one storyboard shot into the panel's ORDINARY job form fields.Deliberately produces the same shape a human clicking Generate would produce, so shotsflow through `/queue/add` -> `make_job` -> the normal worker, land in `mlx_outputs/`, andshow up in the usual gallery with a usual sidecar. No private execution path.+ Every key below is in `make_job`'s allowlist. That is not a style note: a form field+ make_job does not name is silently dropped on /queue/add — the known trap in this codebase —+ so a control can look perfectly wired and do nothing at all.+NOTE `enhance: "off"` is not optional — see ensure_trigger() above."""trigger = (shot.get("trigger") or shot.get("character_id") or "").strip()prompt = shot.get("prompt") or ""if trigger:prompt = ensure_trigger(prompt, trigger)++ # The engine. Without this the job dict has no `engine` key, make_job falls back to+ # ENGINE_DEFAULT ("ltx"), and every H3 shot the planner wrote renders silently on a+ # different model — different aspect, no audio, none of it flagged anywhere.+ # resolve_engine() is the single place that decides, so the chip on the card, the estimate,+ # the scheduling bucket and this job dict can never disagree about what will run.+ engine = resolve_engine(shot, engine_mode=engine_mode, h3_available=h3_available)+job = {- "mode": shot.get("mode") or "text",+ # The panel has ONE backend mode for text and character alike; see _PANEL_MODE.+ "mode": _PANEL_MODE.get(shot.get("mode"), "t2v"),+ "engine": engine,"prompt": prompt,"quality": policy_pass.get("quality", "balanced"),"width": policy_pass.get("width"),"height": policy_pass.get("height"),"frames": policy_pass.get("frames"),- "enhance": "off", # never let Gemma touch a planned prompt- "auto_open": "off", # batches must not steal the viewer+ "enhance": "off", # never let Gemma touch a planned prompt+ # `auto_open` was never in make_job's allowlist, so it silently did nothing. The field+ # that actually exists is `open_when_done`, and it must be off: a 12-shot overnight run+ # must not pop a QuickTime window per shot.+ "open_when_done": "off",}++ # Duration. Without this every shot rendered at the pass's frame count, so the per-shot+ # length control was decoration. Each engine gets its OWN grid — LTX snaps to frames%8==1+ # at 24 fps, H3 renders whole cells off the 17n+5 grid and picks them by length key.+ duration_s = float(shot.get("duration_s") or 0)+ if engine == "h3":+ length = h3_length_for(duration_s) if duration_s > 0 else "5s"+ job["h3_length"] = length+ job["h3_quality"] = h3_quality_for(policy_pass.get("quality", "balanced"))+ # Per-window prompts, when the installed runner supports the flag. The+ # caller passes that capability in rather than this module probing for+ # it — storyboard.py stays model-free and panel-free.+ if h3_chain_prompts:+ chain = h3_chain_prompts_for(shot)+ if chain:+ job["h3_chain_prompts"] = json.dumps(chain)+ # make_job re-stamps geometry from the resolved cell; carrying the cell's own frame+ # count means the job dict is already self-consistent (and honest in a log or a test)+ # before it gets there.+ job["frames"] = _H3_LENGTH_FRAMES[length]+ elif duration_s > 0:+ job["frames"] = ltx_frames_for(duration_s)+if shot.get("character_id"):job["character_id"] = shot["character_id"]if shot.get("seed") is not None:job["seed"] = shot["seed"]++ # Queue linkage. `preset_label` is what the queue card, the Now card, the job pill and the+ # Recent row already print (`j.params.label || snippet(prompt)`), so a storyboard job+ # identifies itself in the bottom pane with no bottom-pane code at all. `session_tag`+ # carries the provenance the badge and the gallery group on. Both keys are already in+ # make_job's allowlist — no allowlist edit, which is the point.+ n = shot.get("n")+ if board_id and isinstance(n, int):+ job["session_tag"] = f"sb:{board_id}#{n}"+ if isinstance(n, int):+ title = (board_title or "").strip()+ job["preset_label"] = f"S{n:02d} · {title}" if title else f"S{n:02d}"++ # `shot["refs"]` is DELIBERATELY not mapped. The four ref-based modes (remix / keyframe /+ # extend / a2v) each want a different field — image, start_image + end_image,+ # video_path, ingredient_images_json — and mapping them half-way would enqueue a job that+ # renders silent t2v from a prompt while looking like it used the reference, which reads+ # as a model bug rather than a missing feature. v1 plans `text` + `character` only and the+ # planner is constrained to the same two, so a board that carries refs is hand-written or+ # from a future version; the validator still checks them and the schema still keeps them.return {k: v for k, v in job.items() if v is not None}diff --git a/storyboard_planner.py b/storyboard_planner.pynew file mode 100644index 0000000..f3f36c6--- /dev/null+++ b/storyboard_planner.py@@ -0,0 +1,1988 @@+#!/usr/bin/env python3+"""Storyboard planner — concept in, valid film spec out.++Companion to `storyboard.py`. That module owns the SCHEMA, the VALIDATOR, the durable+state and the scheduler. This module owns the one thing it deliberately left out: turning+a sentence a human typed into a `shots` list that `validate_storyboard()` accepts on the+first try.++ storyboard.py schema + validate + shooting order + job translation (no models)+ storyboard_planner.py concept -> spec, using a small local LLM (this file)+ mlx_ltx_panel.py UI + queue + rendering (someone else)++Nothing here imports mlx in the panel's process. See MEMORY POLICY below.+++MODEL: gemma-3-12b-it-4bit, the weights the panel ALREADY has+-------------------------------------------------------------+`storyboard.py`'s docstring says the planner is Qwen3.5-4B-4bit (decision 4492775, 2026-07-24).+That decision is sound on the merits and stays the target — but it is not shippable on this+machine today and the module must not pretend otherwise:++ * Qwen3.5-4B-4bit is NOT on disk. Nothing named qwen*-instruct/-4bit exists in+ `mlx_models/` or in the HF hub cache; `qwen-edit-2511-q6` is an mflux IMAGE model.+ * The volume has ~6.5 GiB free. A 3.06 GB download is technically survivable and+ strategically stupid, and the owner's standing rule for this task is explicit:+ do not download new models.+ * The 19 GB ollama `heretic-32b` is out of the question for a step that must run+ BEFORE a render on a unified-memory Mac.++So the planner runs on `mlx_models/gemma-3-12b-it-4bit` — the exact weights+`/prompt/enhance` already loads (`mlx_warm_helper.get_gemma_lm()`), through the exact+runtime (`mlx_lm.load` + `mlx_lm.generate` + `make_sampler`, mlx-lm 0.31.1 in+`ltx-2-mlx/env`). Zero new bytes on disk, and the failure mode "planner model missing" is+impossible for anyone who can already enhance a prompt.++The Qwen3.5 story is not lost, it is a one-line switch: point `LTX_STORYBOARD_PLANNER` (or+the `model_path=` argument) at any mlx-lm-loadable directory and everything else here is+unchanged. `storyboard.py`'s three-layer validity argument (strip preamble, coerce, then+validate with one repair retry) is implemented here verbatim and is model-agnostic; it is+what makes a 4-bit 12B good enough for the job.+++MEMORY POLICY — why a SUBPROCESS and not the warm helper+---------------------------------------------------------+The hard rule from the owner: planning must not clog RAM, must be fully released before+a single frame renders, and must never be resident concurrently with a pipeline.++Three candidate paths were considered. The chosen one is the least-RAM path:++1. REJECTED — call the running warm helper's `enhance_prompt` action.+ It is the only text-LLM route the daemon exposes, and it is hard-wired for a different+ job: `max_new_tokens` is the library default 512 (a 6-shot plan is 1200-2500 tokens, so+ every plan would be truncated mid-JSON), the panel handler force-prepends the Lightricks+ T2V system prompt plus the Phosphene enhance addendum to whatever system prompt you+ supply, and it post-edits the OUTPUT by splicing character triggers back in. Making it+ carry a plan means editing `mlx_warm_helper.py` and `mlx_ltx_panel.py` — both owned by+ other agents on this task. Worse for RAM anyway: the helper holds Gemma warm+ indefinitely after the call (only `release_pipelines()` on the next render frees it), so+ ~7.9 GB sits resident through the user's review of the plan.++2. REJECTED — `mlx_lm.load()` inside the panel process.+ The panel is a long-lived server (it is running on Python 3.9 today). MLX allocates from+ a Metal buffer cache that is not fully returned to the OS when the Python objects are+ dropped, so "unloaded" would still show up as a permanently fatter panel. There is no+ honest `release()` you can write for that.++3. CHOSEN — a short-lived subprocess that loads, generates, and dies.+ `release()` reaps the child; process exit is the only 100%-deterministic reclaim MLX+ offers. Peak RSS is measured, not assumed — the child reports its own+ `ru_maxrss` and `mx.get_peak_memory()`, and the parent independently reads+ `RUSAGE_CHILDREN.ru_maxrss`, so the number in the report needs no cooperation to trust.+ `plan_film()` releases in a `finally:`; there is no code path that returns a plan with a+ model still loaded. Measured: ~7.9 GB peak, gone the instant the call returns.++The child is kept alive ACROSS the repair round-trip inside one `plan_film()` call, because+paying the load twice for one plan is waste, not discipline. It never survives the call.+++OUTPUT DIALECT+--------------+Per-shot prompts are emitted in the dialect of the engine that will render them:++ * `engine: "h3"` (default) — MiniMax H3's official three-field form:+ integrated_multimodal_description: [Shot 1] ...+ overall_soundscape: ...+ non_diegetic_music: ...+ with the laws that were paid for in render hours: the camera is always pinned,+ every action completes and then holds, faces never turn, dialogue is wrapped in+ `<d>[English] ...</d>` with the mouth explicitly told to stop, and+ `non_diegetic_music` carries instrumentation/tempo/dynamics rather than mood words.+ Sources: ~/AI/projects/hailuo-mlx/notes/H3_PROMPTING_GUIDE.md and the graded AURELIUS+ round-2 shot table.++ * `engine: "ltx"` — LTX 2.3's single-paragraph prose with a trailing `Audio:` line and a+ verbatim master-style suffix. Chosen automatically for any shot cast with a trained+ Phosphene character, because character LoRAs ARE LTX LoRAs: identity is the one mode+ H3 does not have. That is also what makes trigger injection safe — `ensure_trigger()`+ prepends, which is legal in LTX prose and would be illegal in H3 (a T2VA prompt must+ begin with `integrated_multimodal_description:`).+++WHAT THE MODEL IS AND IS NOT ALLOWED TO DECIDE+-----------------------------------------------+Everything the validator checks mechanically is produced mechanically. The model returns a+small flat JSON object carrying only the creative payload: a film title, and per shot a+title, an optional character, a duration, a camera CHOICE from a closed set, a prose+description, a settled end state, a soundscape and a music line. Python owns `schema`,+`id`, `created_at`, shot numbering, `mode`, `engine`, `tier`, `seed`, `refs`, `policy`,+trigger injection and every clamp. A small model cannot fail a check it was never asked+to pass.++Two of the prompting laws are enforced the same way, for the same reason. Stated as rules,+they were ignored: over the first measured sweep (5 concepts, 26 shots) the model reused ONE+camera sentence for every shot of every film, and wrote an end-state clause on 2 shots out+of 26. They are now a one-word choice plus a short phrase, and PYTHON writes the sentence —+after which camera variety and end-state coverage were 100%. If a law can be reduced to a+choice, reduce it; only leave prose to the model where prose is the point.++Pure stdlib. Python 3.9-compatible (the panel runs on 3.9 today) — the 3.11 venv is used+only for the child process, which is the only thing that imports mlx.+"""++from __future__ import annotations++import copy+import hashlib+import json+import os+import re+import subprocess+import sys+import time+from pathlib import Path+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple++ROOT = Path(__file__).resolve().parent++# --------------------------------------------------------------------------------------+# Model + runtime location+# --------------------------------------------------------------------------------------+# Mirrors mlx_ltx_panel.py:74-75 so a user who moved LTX_MODELS_DIR does not have to move+# anything twice. LTX_STORYBOARD_PLANNER is the escape hatch for pointing at Qwen3.5 (or+# anything else mlx-lm can load) without touching this file.+MODELS_DIR = Path(os.environ.get("LTX_MODELS_DIR", str(ROOT / "mlx_models")))+DEFAULT_MODEL_PATH = Path(+ os.environ.get("LTX_STORYBOARD_PLANNER")+ or os.environ.get("LTX_GEMMA_PATH")+ or (MODELS_DIR / "gemma-3-12b-it-4bit")+)++# The child needs mlx + mlx_lm; the panel's own interpreter may not have them (it is 3.9).+# Same resolution order as the panel's _resolve_helper_python().+_VENV_PY = ROOT / "ltx-2-mlx" / "env" / "bin" / "python3.11"+++def _resolve_worker_python() -> Path:+ cand = os.environ.get("LTX_HELPER_PYTHON")+ if cand and Path(cand).is_file():+ return Path(cand)+ if _VENV_PY.is_file():+ return _VENV_PY+ alt = ROOT / "ltx-2-mlx" / "env" / "bin" / "python"+ if alt.is_file():+ return alt+ return Path(sys.executable)+++WORKER_PYTHON = _resolve_worker_python()++# Every worker reply is one line prefixed with this, so stray stdout from mlx-lm (progress+# bars, warnings) can never be mistaken for the protocol.+_SENTINEL = "@@PLANNER@@ "++# Modes this planner is allowed to emit. `remix`/`keyframe`/`extend`/`a2v` all require+# inputs the planner does not have (reference images, a prior clip, an audio file), and+# validate_storyboard() rejects them without those — so they are simply not on the menu.+_PLANNABLE_MODES = ("text", "character")++# H3 renders in ~5 s windows (124 frames @ 24 fps); longer clips are chained windows.+# The panel's tier grid offers exactly these lengths, so durations snap to them.+_H3_LENGTHS = (3.0, 5.0, 10.0, 15.0)++_MIN_DURATION = 1.0+_MAX_DURATION = 60.0 # validate_storyboard(): 0 < duration_s <= 60++DEFAULT_TEMPERATURE = 0.15 # low, deliberately: this is structured output, not vibes+DEFAULT_MAX_TOKENS = 3600+DEFAULT_TIMEOUT_S = 900+++class PlannerError(Exception):+ """Raised only for programmer errors (bad arguments). Model failures never raise —+ they come back as a structured error dict the UI can render."""+++# --------------------------------------------------------------------------------------+# The validator we must satisfy — imported, never reimplemented+# --------------------------------------------------------------------------------------++def _load_validator():+ """Return (validate_fn, storyboard_module).++ The whole design principle of this module is that the schema is whatever+ `storyboard.py` says it is, so we call the real thing rather than modelling it.+ Tolerant about the name because the panel-side agent may expose it as `validate`.+ """+ sys_path_added = False+ if str(ROOT) not in sys.path:+ sys.path.insert(0, str(ROOT))+ sys_path_added = True+ try:+ import storyboard # type: ignore+ except Exception as exc: # pragma: no cover - only if storyboard.py is broken+ if sys_path_added:+ try:+ sys.path.remove(str(ROOT))+ except ValueError:+ pass+ raise PlannerError("cannot import storyboard.py: %s" % exc)+ fn = getattr(storyboard, "validate", None) or getattr(storyboard, "validate_storyboard", None)+ if fn is None:+ raise PlannerError("storyboard.py exposes neither validate() nor validate_storyboard()")+ return fn, storyboard+++# --------------------------------------------------------------------------------------+# THE PROMPT+# --------------------------------------------------------------------------------------+# Everything below is few-shot first and rules second, on purpose. The exemplars are real+# graded work: two are trimmed from the AURELIUS round-2 table (owner-graded KEEP/MAYBE+# shots, ~/AI/projects/aurelius/video/clips/_work/shots_r2.py) and one is C1 from+# H3_PROMPTING_GUIDE.md §6.1. The abstract rules exist only to name what the exemplars+# already demonstrate, so a 12B model can pattern-match instead of reason.++_LAWS = """\+THE LAWS (each one was paid for with a wasted render; the examples above obey all of them)++L1 PIN THE CAMERA. Silence is not a tripod - an unnamed camera drifts. Every description+ names exactly ONE camera behaviour, as prose, with amplitude and speed. Locked shot:+ "The camera holds a static shot, the frame never moves - no pan, no push-in, no+ reframing." Moving shot: "The camera pushes in with small amplitude at slow speed."+L2 FACES NEVER TURN. Turning breaks identity. Heads stay square to the lens, shoulders do+ not pivot, nobody rotates toward or away from camera.+L3 THE ACTION COMPLETES, THEN HOLDS. If the arc is still running at the end of the clip+ the model invents - extra limbs, extra motion. Finish early and name the settled end+ state: "The movement is completely finished before the shot ends, and for the last two+ seconds <state>, with no new movement of any kind."+L4 ONE CONTINUOUS ACTION per 5 seconds for a human subject. Two beats maximum in 5 s, and+ only if the second is a reaction. Abstract/product/graphic subjects may have 3-4.+L5 NO UNANCHORED NEGATIONS. There is no negative prompt. Never write "not blurry", "high+ quality", "no distortion". The only refusals allowed are against things the model adds+ by itself: camera drift (L1) and unwanted lettering ("No text appears at any point.").+L6 DIALOGUE lives inside <d>[English] ...</d> and nowhere else. The speaker, their voice+ and their delivery are described OUTSIDE the tag. Immediately after the tag, stop the+ mouth: "his jaw ceases speaking motion and his mouth settles closed". One or two short+ sentences per 5 s. If a shot has no dialogue, it has no <d> at all.+L7 MUSIC IS INSTRUMENTATION, not mood. "Sparse piano at a slow tempo, joined by low+ strings that swell and cut out" - never "epic", "emotional", "uplifting". "N/A" is the+ correct value when there is no score, and is the right answer most of the time.+L8 SOUNDSCAPE IS AMBIENCE + PHYSICAL SOUND ONLY. Never repeat the dialogue there. 1-3+ sentences.+L9 ON-SCREEN TEXT: only if the brief asks for it, and then type the exact words in double+ quotes, 3-5 words, one row. Otherwise end the description with "No text appears at any+ point."+L10 CONVERT MOOD INTO BEHAVIOUR. Not "she is devastated" but "her eyes shine wet and she+ blinks once and keeps very still".+L11 THE FACE IS THE WHOLE POINT. A shot is judged on whether the face reads. If a person is+ on screen their face is IN the frame, whole, lit and turned to the lens - every time.+ NEVER write, and never imply, any of these unless the brief asked for it in so many+ words: "his face obscured", "seen from behind", "her back to the camera", "head out of+ frame", "cropped at the chin", "silhouetted against the light", "in silhouette", "his+ face hidden by his hands", "we never see her face". The temptation is strongest on the+ last shot of a film, where a silhouette feels like an ending - it is not, it is a shot+ with no face in it. End on the face instead.+ A face may be dark, wet, bruised, half in shadow or lit from one side. It may not be+ turned away, blocked, cut off by the frame edge, or reduced to an outline.+"""++_H3_EXAMPLES = """\+EXAMPLE SHOTS - H3 register. Copy this voice. Note that no "description" below contains a+camera sentence or an ending clause: those are the "camera" and "settle" keys.++{+ "n": 1,+ "title": "Clippers",+ "character_id": null,+ "duration_s": 5,+ "camera": "handheld",+ "face": "close",+ "description": "Live-action, cinematic, a close two-shot in a bright kitchen: a woman with a freshly buzzed head sits still while her teenage daughter stands behind her running hair clippers over her scalp, warm window light across both faces. Photoreal, heavy 35mm film grain. Played quietly and underplayed throughout: the daughter draws one more slow clipper pass and a small tuft of hair falls away, the mother's eyes shine wet and she blinks once and keeps very still, and she reaches up and closes her hand over her daughter's hand on her shoulder, and the smallest smile arrives at the corner of her mouth.",+ "settle": "that small smile is simply held, both of them still, hands joined on the shoulder",+ "soundscape": "The steady buzz of hair clippers, one soft unsteady breath, a dripping kitchen tap, and the hum of a fridge. Nobody speaks and no voice is heard at any point.",+ "music": "N/A"+}++{+ "n": 2,+ "title": "The box",+ "character_id": null,+ "duration_s": 5,+ "camera": "static",+ "face": "medium",+ "description": "Live-action, cinematic, a medium-wide shot at dusk of a man in an open-collared shirt beside a battered steel dumpster in an empty back street, a cardboard office box in his arms with a small potted plant balanced on top. Photoreal, heavy 35mm film grain. Blue dusk light. Everything happens at natural real-time speed, never in slow motion. He heaves the box up and away from his chest in one fast decisive movement and it drops hard into the dumpster with the plant tumbling in after it and a puff of dust rising, then his shoulders drop as the weight leaves him and he lets out one long exhale, his face staying square to the lens the whole time.",+ "settle": "he is standing empty-handed with his shoulders down and his face still to the lens",+ "soundscape": "Quiet back-street evening ambience with distant traffic, the hollow bang of cardboard hitting steel, a clatter of a plant pot, and one long relieved exhale.",+ "music": "N/A"+}++{+ "n": 3,+ "title": "Impossible",+ "character_id": null,+ "duration_s": 5,+ "camera": "push_in",+ "face": "close",+ "description": "Live-action, cinematic, a medium close-up of a man in a dark curly fur hat and heavy fur coat on an open dune ridge. He faces the camera squarely and holds eye contact for the entire duration as the wind lifts the fur at his collar. Hard low sun rakes from camera left at the end of the day, carving one bright warm edge down his cheekbone while the other side of his face falls into open shadow; the dune line behind him is a clean dark silhouette against a pale sky. The man, with a warm, measured, slightly gravelled voice (S1), says: <d>[English] They said this was impossible.</d> Exactly as his voice stops, his jaw ceases speaking motion and his mouth settles into a closed steady half-smile.",+ "settle": "his eyes stay on the lens and nothing but the fur at his collar moves",+ "soundscape": "A steady desert wind moves across open sand for the full duration, with the dry rustle of fur at his collar and one soft gust that rises and falls.",+ "music": "N/A"+}++{+ "n": 4,+ "title": "Crema",+ "character_id": null,+ "duration_s": 5,+ "camera": "push_in",+ "face": "none",+ "description": "Live-action, cinematic, an extreme macro of a warm glass cup under a polished steel spout, filling with espresso. A hard raking key light from camera left picks out the rim of the glass against a matte black background. Two dark streams meet and braid as they fall, the liquid climbing the glass while a dense hazelnut crema builds on the surface and settles into a smooth unbroken layer, one bead of condensation sliding down the outside of the glass.",+ "settle": "the crema lies flat and unbroken and the surface is completely still",+ "soundscape": "The low hiss of a pump, the fine trickle of liquid into glass, and a quiet kitchen room tone underneath.",+ "music": "One low sustained synth tone at a slow tempo that rises slightly as the glass fills and drops away at the end."+}+"""++_LTX_EXAMPLE = """\+EXAMPLE SHOT - LTX register. Use this voice ONLY for a shot whose "character_id" is not+null. It is one continuous prose paragraph, 70-120 words: no [Shot 1] marker, no <d> tags,+dialogue in single quotes with a voice descriptor in front of it, and no field labels. Do+NOT write the character's trigger word yourself - leave the person unnamed and described,+the trigger is attached afterwards.++{+ "n": 4,+ "title": "The confession",+ "character_id": "bizarrotrn",+ "duration_s": 10,+ "camera": "handheld",+ "face": "close",+ "description": "A weary man in a soft grey jacket sits in a sterile interview room, medium close-up, fluorescent overhead light, shallow depth of field. He breathes in, looks down at his hands, then up at the lens and holds there. He says quietly and clearly: 'I stopped leaving the chair.'",+ "settle": "he is still, jaw set, both eyes back on the lens",+ "soundscape": "Room tone, a fluorescent hum, one unsteady breath, clear dialogue.",+ "music": "N/A"+}++Words that wreck an LTX shot because they trigger letterbox bars: cinematic, filmic,+anamorphic, widescreen, epic, 2.39:1. Never use them in the LTX register. LTX also cannot+render crowds, rows of people, circles of seated people, or three or more faces the camera+must read - pick ONE principal and imply the rest in the soundscape. Do not describe+fingers gripping objects, and never ask for on-screen text.+"""+++def _build_system_prompt(engine_hint: str, has_characters: bool,+ allow_hidden: bool = False) -> str:+ dialect = """\+THE TARGET DIALECT++Your "description", "soundscape" and "music" for an H3 shot are assembled by the program+into MiniMax H3's official three-field prompt, exactly like this - you never type the field+labels or the shot marker yourself:++ integrated_multimodal_description: [Shot 1] <your description>++ overall_soundscape: <your soundscape>++ non_diegetic_music: <your music>++So "description" must START with the style token ("Live-action, cinematic," / "3D CG," /+"2D-animated," / "claymation," / "vintage film,") followed immediately by the shot size,+and must read as one continuous paragraph of 70-140 words.+"""+ contract = """\+OUTPUT CONTRACT - read this twice++Reply with ONE JSON object and NOTHING else. No preamble, no explanation, no markdown+outside the JSON. The object has exactly two keys:++{+ "title": "<short title for the whole film, 2-6 words>",+ "shots": [ <one object per shot, in story order> ]+}++Each shot object has exactly these nine keys and no others:++ "n" integer, 1-based, in order+ "title" 2-5 words naming the beat+ "character_id" a cast id from CAST below, or null+ "duration_s" 3, 5 or 10+ "camera" ONE of: static, push_in, pull_back, handheld, orbit, pan, tilt_up, tracking+ "face" ONE of: close, medium, none. This is about WHO IS PRESENT, not about how+ important the face is to you.+ close - a face is the subject of the shot and fills much of the frame+ medium - a person is on screen anywhere at all - near, far, small, in the+ background, in a wide shot, only their hands. Their face must+ stay readable. When in doubt this is the answer.+ none - there is NO PERSON of any kind in this shot: an object, a+ landscape, a machine, a graphic. Nobody. Not one.+ There is no fourth option. See L11.+ "description" the visual + action + dialogue paragraph, 70-140 words. It does NOT contain+ a camera sentence and does NOT describe how the shot ends - those are the+ "camera" and "settle" keys, and the program writes their sentences for you.+ "settle" a short phrase naming the settled state the shot ENDS in, written to follow+ "for the last two seconds ..." - e.g. "he is standing empty-handed with his+ shoulders down". Every shot needs one.+ "soundscape" 1-3 sentences of ambience and physical sound+ "music" 1-2 sentences of instrumentation/tempo/dynamics, or "N/A"++The program - not you - assigns schema version, ids, seeds, modes, engines, resolutions and+character trigger words, and turns "camera" and "settle" into their sentences. Do not invent+other keys. Do not wrap the object in an array.+"""+ parts = [+ "You are the Phosphene storyboard planner.\n\n"+ "You turn one sentence of concept into a shot-by-shot film plan that a local video\n"+ "model will render unattended. You are the DIRECTOR, not a transcriber: the concept is\n"+ "INTENT, and your job is to express it as shots this model actually renders well.\n"+ "Every shot must be a single continuous take that can stand on its own - there is no\n"+ "editing, no cutting inside a shot, and no camera move that reframes.\n",+ contract,+ ]+ if engine_hint == "ltx":+ # Every shot will render on LTX, so the H3 dialect would only confuse the model.+ parts.append(_LTX_EXAMPLE)+ parts.append("EVERY shot in this film uses the LTX register shown above, whether or\n"+ "not it has a character_id. Never write [Shot 1], <d> tags or field labels.\n")+ else:+ parts.append(dialect)+ parts.append(_H3_EXAMPLES)+ if has_characters and engine_hint != "h3":+ parts.append(_LTX_EXAMPLE)+ parts.append(_LAWS)+ parts.append("""\+COMPOSITION LIMITS - rewrite around these instead of asking for them++ crowd / audience / rally -> ONE face from it, the rest implied in the soundscape+ circle of seated people, group ring -> a close shot on whoever is speaking+ rows of desks, classroom, newsroom -> the principal in front, everything behind soft+ three or more faces the camera reads-> pick one principal; the others are off-frame+ fast hands, fingers gripping props -> frame past the hands+ "the camera pulls back to reveal" -> state the FINAL framing only, no reveal++ACID TEST before you write a shot: can a reader point at exactly one subject the camera+will hold? If not, rewrite it.++DURATION: 3 s for a beat or a cutaway, 5 s for one action or one short spoken line, 10 s+only when a line genuinely needs it. Speech runs about 2.5 words per second; add one second+of breath before the line and about one and a half seconds of silence after it, then round+up. Never trim a line the brief gave you in order to fit a duration - lengthen the shot.++VARIETY IS A HARD REQUIREMENT, not a preference. Before you answer, look down the list of+"camera" values you have written: no two consecutive shots may share one, and a six-shot+film must use at least three different ones. Do the same for shot size - vary across extreme+close-up, close-up, medium, wide. Let at most half the shots contain dialogue.++EVERY SHOT MUST CONTAIN A PHYSICAL ACTION that starts and finishes inside the clip. A shot+that only describes what a place looks like is a photograph, and this model fills the empty+time by inventing motion. If you cannot name something that moves, the shot does not exist.++WRITE WHAT A LENS COULD SEE. "A testament to human ingenuity", "a symbol of hope", "a space+that feels lived-in", "his face etched with solitude" are unrenderable - they instruct+nothing. Replace each with the visible fact underneath it.+""")+ if allow_hidden:+ parts.append(+ "FACES: this brief explicitly asked for hidden or obscured faces, so L11 is "+ "relaxed for the shots where the brief wants it - you may use \"hidden\" as a\n"+ "\"face\" value on those shots. Every other shot still keeps its face readable.\n")+ return "\n".join(parts)+++def _build_user_prompt(+ concept: str,+ n_shots: int,+ style: str,+ cast: Sequence[Dict[str, str]],+ must_include: Sequence[str],+) -> str:+ lines = ["BRIEF", "", "CONCEPT: %s" % concept.strip(), "", "SHOT COUNT: exactly %d shots." % n_shots]+ if style and style.strip():+ lines += ["", "STYLE (applies to every shot; keep it identical across all of them): %s"+ % style.strip()]+ if cast:+ lines += ["", "CAST - these are trained characters. A shot that features one sets"+ " \"character_id\" to that id and is written in the LTX register:"]+ for c in cast:+ desc = (c.get("description") or "").strip()+ lines.append(" - %s%s%s" % (+ c["id"],+ (" (%s)" % c["name"]) if c.get("name") and c["name"] != c["id"] else "",+ (": " + desc) if desc else "",+ ))+ lines.append(" Any shot without a listed character sets \"character_id\": null.")+ else:+ lines += ["", "CAST: none. Every shot sets \"character_id\": null."]+ if must_include:+ lines += ["", "MUST APPEAR somewhere in the film:"]+ for m in must_include:+ lines.append(" - %s" % str(m).strip())+ lines += ["", "Return the JSON object now. %d shots. Nothing before it, nothing after it."+ % n_shots]+ return "\n".join(lines)+++def _build_repair_prompt(bad_json: str, problems: Sequence[str], n_shots: int) -> str:+ return "\n".join([+ "Your previous reply did not pass validation.",+ "",+ "PROBLEMS FOUND:",+ "\n".join(" - %s" % p for p in problems),+ "",+ "YOUR PREVIOUS OUTPUT:",+ bad_json[:6000],+ "",+ "Fix ONLY those problems. Keep everything that was already good, word for word.",+ "Return the corrected JSON object - exactly %d shots, the same six keys per shot," % n_shots,+ "nothing before the object and nothing after it.",+ ])+++def _build_film_feedback_prompt(previous: Dict[str, Any], note: str, n_shots: int) -> str:+ return "\n".join([+ "You already planned this film. The director has notes.",+ "",+ "DIRECTOR'S NOTES: %s" % note.strip(),+ "",+ "THE CURRENT PLAN:",+ json.dumps(_spec_to_model_view(previous), indent=1, ensure_ascii=False)[:9000],+ "",+ "Re-plan the film so the notes are satisfied. Change only what the notes require;",+ "leave everything else word for word as it was. Return the full corrected JSON",+ "object with exactly %d shots and nothing else." % n_shots,+ ])+++def _build_shot_feedback_prompt(previous: Dict[str, Any], shot_n: int, note: str) -> str:+ shots = previous.get("shots") or []+ target = None+ for s in shots:+ if s.get("n") == shot_n:+ target = s+ break+ if target is None:+ raise PlannerError("shot %r is not in the plan (it has %d shots)" % (shot_n, len(shots)))+ neighbours = [s for s in shots if s.get("n") in (shot_n - 1, shot_n + 1)]+ return "\n".join([+ "You are re-rolling ONE shot of a film that is otherwise finished.",+ "",+ "THE FILM: %s" % (previous.get("title") or ""),+ "",+ "THE SHOTS AROUND IT, for continuity - do NOT return these:",+ json.dumps([_shot_to_model_view(s) for s in neighbours], indent=1, ensure_ascii=False)[:4000],+ "",+ "THE SHOT TO REPLACE (n=%d):" % shot_n,+ json.dumps(_shot_to_model_view(target), indent=1, ensure_ascii=False),+ "",+ "DIRECTOR'S NOTES ON THIS SHOT: %s" % note.strip(),+ "",+ "Return ONE JSON object: {\"title\": \"<the film title, unchanged>\", \"shots\": [ <the",+ "single replacement shot object, with n=%d> ]}. One shot only. Nothing else." % shot_n,+ ])+++def _shot_to_model_view(shot: Dict[str, Any]) -> Dict[str, Any]:+ """The eight creative keys, as the model sees them (drops seeds/modes/engines/etc)."""+ return {+ "n": shot.get("n"),+ "title": shot.get("title", ""),+ "character_id": shot.get("character_id"),+ "duration_s": shot.get("duration_s"),+ "camera": shot.get("camera", "static"),+ "face": shot.get("face", "medium"),+ "description": shot.get("description", ""),+ "settle": shot.get("settle", ""),+ "soundscape": shot.get("soundscape", ""),+ "music": shot.get("music", "N/A"),+ }+++def _spec_to_model_view(spec: Dict[str, Any]) -> Dict[str, Any]:+ return {+ "title": spec.get("title", ""),+ "shots": [_shot_to_model_view(s) for s in (spec.get("shots") or [])],+ }+++# --------------------------------------------------------------------------------------+# JSON extraction from small-model output+# --------------------------------------------------------------------------------------++_FENCE_RE = re.compile(r"```(?:json|JSON)?\s*(.*?)```", re.DOTALL)+_THINK_RE = re.compile(r"<think>.*?</think>|<thinking>.*?</thinking>", re.DOTALL | re.IGNORECASE)+_TRAILING_COMMA_RE = re.compile(r",(\s*[}\]])")+_LINE_COMMENT_RE = re.compile(r"(^|\s)//[^\n]*")+_SMART = {"\u201c": '"', "\u201d": '"', "\u2018": "'", "\u2019": "'", "\u2013": "-", "\u2014": "-"}+++def _balanced_objects(text: str) -> List[str]:+ """Every top-level {...} run in `text`, string- and escape-aware.++ A small model happily writes 'Here is your plan:' before the object and 'Let me know if+ you want changes!' after it, and sometimes emits two objects. Regex cannot match nested+ braces; a two-state scanner can, and it is 20 lines.+ """+ out: List[str] = []+ depth = 0+ start = -1+ in_str = False+ esc = False+ for i, ch in enumerate(text):+ if in_str:+ if esc:+ esc = False+ elif ch == "\\":+ esc = True+ elif ch == '"':+ in_str = False+ continue+ if ch == '"':+ in_str = True+ elif ch == "{":+ if depth == 0:+ start = i+ depth += 1+ elif ch == "}":+ if depth > 0:+ depth -= 1+ if depth == 0 and start >= 0:+ out.append(text[start:i + 1])+ start = -1+ if depth > 0 and start >= 0:+ # Truncated output (hit max_tokens mid-object). Hand back what we have; the+ # bracket-closing repair below often rescues it.+ out.append(text[start:])+ return out+++def _soften(raw: str) -> str:+ s = raw+ for bad, good in _SMART.items():+ s = s.replace(bad, good)+ s = _LINE_COMMENT_RE.sub(r"\1", s)+ s = _TRAILING_COMMA_RE.sub(r"\1", s)+ return s+++def _close_brackets(raw: str) -> str:+ """Best-effort close of an object truncated by the token limit.++ Closers are emitted from an actual stack, innermost first — appending all the `]`+ before all the `}` produces `..."]}}` for a truncated shot object, which is not JSON.+ """+ stack: List[str] = []+ in_str = False+ esc = False+ for ch in raw:+ if in_str:+ if esc:+ esc = False+ elif ch == "\\":+ esc = True+ elif ch == '"':+ in_str = False+ continue+ if ch == '"':+ in_str = True+ elif ch == "{":+ stack.append("}")+ elif ch == "[":+ stack.append("]")+ elif ch in "}]":+ if stack and stack[-1] == ch:+ stack.pop()+ s = raw+ if in_str:+ s += '"'+ s = _TRAILING_COMMA_RE.sub(r"\1", s.rstrip().rstrip(","))+ return s + "".join(reversed(stack))+++def extract_json_object(text: str) -> Optional[Dict[str, Any]]:+ """Pull the plan object out of whatever the model actually said.++ Handles: clean JSON, ```json fences, bare ``` fences, prose before/after, `<think>`+ leakage, trailing commas, smart quotes, // comments, an object wrapped in a list, and+ output truncated mid-object by the token limit. Returns None only when there is no+ recoverable object at all.+ """+ if not text:+ return None+ body = _THINK_RE.sub(" ", text)++ candidates: List[str] = []+ for m in _FENCE_RE.finditer(body):+ candidates.append(m.group(1))+ # An unterminated fence is common when generation is truncated.+ if not candidates and "```" in body:+ candidates.append(body.split("```", 1)[1].lstrip("jsonJSON \n"))+ candidates.append(body)++ scanned: List[str] = []+ for c in candidates:+ scanned.extend(_balanced_objects(c))+ scanned.append(c.strip())++ # Longest first: a plan object is bigger than any stray fragment before it.+ for chunk in sorted({c for c in scanned if c.strip()}, key=len, reverse=True):+ for attempt in (chunk, _soften(chunk), _close_brackets(_soften(chunk))):+ try:+ obj = json.loads(attempt)+ except (ValueError, TypeError):+ continue+ if isinstance(obj, list):+ obj = next((o for o in obj if isinstance(o, dict)), None)+ if obj is None:+ continue+ if isinstance(obj, dict):+ if "shots" in obj or "title" in obj:+ return obj+ # Model returned a bare list of shots under some other key.+ for v in obj.values():+ if isinstance(v, list) and v and isinstance(v[0], dict) and "description" in v[0]:+ return {"title": "", "shots": v}+ return None+++# --------------------------------------------------------------------------------------+# Coercion — everything the validator checks, produced mechanically+# --------------------------------------------------------------------------------------++_DESC_KEYS = ("description", "integrated_multimodal_description", "visual", "prompt", "body", "text")+_SOUND_KEYS = ("soundscape", "overall_soundscape", "audio", "sound", "ambience")+_MUSIC_KEYS = ("music", "non_diegetic_music", "score", "soundtrack")++_SHOT_MARKER_RE = re.compile(r"^\s*\[Shot\s*\d+\][,\s]*", re.IGNORECASE)+_D_TAG_RE = re.compile(r"<d>\s*(?:\[[^\]]*\]\s*)?(.*?)</d>", re.DOTALL)++# --- the two laws the model demonstrably will not apply on its own ----------------------+# Measured over 5 concepts x 26 shots: with the laws stated as rules, the model reused ONE+# camera sentence for every shot in every film, and wrote the settle clause on 2 of 26+# shots. Both are now a small closed choice the model makes and a canonical sentence PYTHON+# writes — which is the same trick that makes the rest of the schema reliable.++_CAMERA_SENTENCES = {+ "static": "The camera holds a static shot, the frame never moves - no pan, no push-in, "+ "no reframing.",+ "push_in": "The camera pushes in with small amplitude at slow speed.",+ "pull_back": "The camera pulls back with small amplitude at slow speed.",+ "handheld": "The camera shakes slightly with small amplitude at slow speed, a handheld "+ "micro-sway that never reframes.",+ "orbit": "The camera arcs around the subject with small amplitude at slow speed.",+ "pan": "The camera pans with small amplitude at slow speed.",+ "tilt_up": "The camera tilts up with small amplitude at slow speed.",+ "tracking": "The camera tracks alongside the subject with medium amplitude at slow speed.",+}+CAMERA_KEYS = tuple(_CAMERA_SENTENCES)++# --- the face law ----------------------------------------------------------------------+# Faces are the quality metric for this project: a plan is judged on whether the face reads.+# Two failures were measured, so both are structural rather than advisory.+#+# 1. The model volunteers face-hiding framing, most often on the LAST shot of a film where+# it reaches for something poetic — "silhouetted against the setting sun", "her+# silhouette framed against the city lights", "his face obscured by the angle" (the last+# one rendered a head half out of frame). Base rate before this law: 5 of 56 shots.+# 2. Turning breaks identity (H3 guide 7.2 / AURELIUS law 2).+#+# So `face` is a closed choice — close / medium / none / hidden — and Python writes the+# sentence, exactly as with `camera` and `settle`. `hidden` is refused unless the brief asked+# for it in so many words. Unambiguous blocking phrases are additionally scrubbed out of the+# prose, because the model writes them regardless of what it chose.++_FACE_LAW_CLOSE = (+ "The face fills much of the frame, and every face holds the exact angle to the lens it "+ "has at the start: heads stay square, shoulders do not pivot, and nobody rotates towards "+ "or away from the camera at any point. The face stays completely inside the frame for "+ "the entire duration with both eyes open and clearly readable, and is never cropped by "+ "the frame edge, never thrown into silhouette, and never covered by a hand, a prop or "+ "another person.")+_FACE_LAW_MEDIUM = (+ "Every face holds the exact angle to the lens it has at the start: heads stay square, "+ "shoulders do not pivot, and nobody rotates towards or away from the camera at any "+ "point. Each face stays completely inside the frame for the entire duration and is "+ "never cropped by the frame edge, never thrown into silhouette, and never covered by a "+ "hand, a prop or another person.")+_FACE_LAWS = {"close": _FACE_LAW_CLOSE, "medium": _FACE_LAW_MEDIUM, "none": "", "hidden": ""}+FACE_KEYS = ("close", "medium", "none", "hidden")++_PERSON_RE = re.compile(+ r"\b(man|woman|men|women|boy|girl|child|children|person|people|face|faces|keeper|"+ r"worker|he|she|his|her|him|hers|they|their|figure|hands?|crowd|speaker|"+ r"[a-z]+er's|[a-z]+man)\b", re.IGNORECASE)++# Unambiguous. These never describe anything but a face the viewer cannot read.+_FACE_BLOCK_RE = re.compile(+ r"\bobscur\w*"+ r"|\bfrom behind\b"+ r"|\bback to (?:the )?(?:camera|lens)\b"+ r"|\b(?:facing|turned|turning|looking) away from (?:the )?(?:camera|lens)\b"+ r"|\bout of (?:the )?frame\b"+ r"|\bcropped (?:out|off|at)\b"+ r"|\b(?:face|features|eyes) (?:is|are|were|stays?) (?:hidden|concealed|covered)\b"+ r"|\bhidden (?:by|behind|in) \w+"+ r"|\bconceal(?:s|ed|ing)\b"+ r"|\bwe (?:do not|don't|never) see\b", re.IGNORECASE)++# Ambiguous on its own — "the dune line behind him is a clean dark silhouette" and "the+# lighthouse stands silhouetted against the night sky" are good cinematography about things+# that have no face. Only the forms that bind the silhouette to a PERSON are blocking.+#+# The window is `[\w'\s]{0,20}?` — word characters, apostrophes and spaces only, so it+# reaches across "he's" and "she stands" but is stopped by any comma or full stop. An+# earlier `\W{0,8}` version was simply wrong: it required NON-word characters, so it matched+# neither "she stands silhouetted" nor "He's silhouetted", and both shipped.+_SIL_SUBJECT = (r"(?:he|she|they|man|woman|boy|girl|child|boxer|keeper|violinist|figure|"+ r"person|player|worker|dancer|singer|fighter)")+_PERSON_SILHOUETTE_RE = re.compile(+ r"^\s*silhouett" # participial, inherits the subject+ r"|\b(?:his|her|their)\s+silhouette\b"+ r"|\b" + _SIL_SUBJECT + r"\b[\w'\s]{0,20}?\bsilhouett", re.IGNORECASE)++# The brief has to ask for a hidden face out loud before the planner will allow one.+_WANTS_HIDDEN_RE = re.compile(+ r"\bsilhouette|\bfrom behind\b|\bback to (?:the )?camera\b|\bfaceless\b|\bno faces?\b|"+ r"\bhidden face|\bface(?:s)? (?:hidden|obscured)|\banonymous\b|\bunidentified\b|"+ r"\bwithout showing (?:the |their |his |her )?face", re.IGNORECASE)+++def _face_level(raw: Any, desc: str) -> Tuple[str, bool]:+ """Normalise the model's `face` choice. Returns (level, was_overridden).++ `none` is the one value the model can use to switch the whole face law off, so it is the+ one value that is checked against the prose. Observed: a wide shot whose description read+ "showing the woman standing beside the neon sign, silhouetted against the vibrant lights"+ was labelled `face: "none"`, which disabled the scrub and shipped the silhouette. If+ there is a person in the description there is a face to protect, whatever the label says.+ """+ k = str(raw or "").strip().lower().replace(" ", "_").replace("-", "_")+ aliases = {"closeup": "close", "close_up": "close", "tight": "close", "face": "close",+ "visible": "medium", "mid": "medium", "wide": "medium", "full": "medium",+ "no_face": "none", "nobody": "none", "n/a": "none", "": "",+ "obscured": "hidden", "silhouette": "hidden", "back": "hidden"}+ k = aliases.get(k, k)+ if k not in _FACE_LAWS:+ return ("medium" if _has_person(desc) else "none"), False+ if k == "none" and _has_person(desc):+ return "medium", True+ return k, False+++def _scrub_face_blocking(text: str) -> Tuple[str, List[str]]:+ """Remove clauses that hide the face. Returns (text, removed clauses).++ Clause-level, like _clean_settle: sentences are split on `.` and clauses on `,`/`;`, and+ only the offending clause is dropped, so the rest of the direction survives. If every+ clause of a sentence is blocking, the sentence goes.+ """+ removed: List[str] = []+ out_sentences: List[str] = []+ for sentence in re.split(r"(?<=[.!?])\s+", text or ""):+ if not sentence.strip():+ continue+ clauses = re.split(r"(?<=[,;])\s+", sentence)+ keep = []+ for c in clauses:+ if _FACE_BLOCK_RE.search(c) or _PERSON_SILHOUETTE_RE.search(c):+ removed.append(c.strip().rstrip(",;"))+ continue+ keep.append(c)+ if keep:+ joined = " ".join(keep).strip()+ joined = re.sub(r"[,;]\s*([.!?])", r"\1", joined).strip().rstrip(",;")+ if joined and joined[-1] not in ".!?":+ joined += "."+ out_sentences.append(joined)+ return " ".join(out_sentences).strip(), removed++_NO_TEXT = "No text appears at any point."++# H3 volunteers lettering unless refused — but refusing it on a shot that IS about lettering+# is worse than not refusing at all. Observed: a title-sequence plan that spelled a word in+# mercury and then told the model that no text may appear.+#+# The only reliable signal for "typography is intended" is a SHORT QUOTED RUN. Keyword+# matching was tried and rejected: "neon sign" tripped on a documentary about repairing neon+# (where the refusal is exactly right), and single-quoted LTX dialogue tripped on every+# talking shot. Keywords now only raise a warning; they never suppress the refusal.+_DQ_RE = re.compile(r'"([^"\n]{1,32})"')+_SQ_RE = re.compile(r"(?<![A-Za-z])'([^'\n]{1,32})'") # lookbehind skips don't / it's+_TEXT_KEYWORD_RE = re.compile(+ r"\b(?:the word|the letter|the letters|spells?|spelling|typography|lettering|"+ r"title card|subtitle|caption)\b", re.IGNORECASE)+++def _typography_strings(text: str) -> List[str]:+ """Quoted runs that read as ON-SCREEN TEXT rather than dialogue or an apostrophe.++ A title is a token or a shout ("PHOSPHENE", 'P'); dialogue is a sentence with spaces and+ mixed case. The spec for on-screen text is 3-5 words and <=32 characters, which is what+ the length bound encodes.+ """+ out = [m.group(1) for m in _DQ_RE.finditer(text or "")]+ for m in _SQ_RE.finditer(text or ""):+ s = m.group(1)+ if re.search(r"[A-Za-z0-9]", s) and (" " not in s or s == s.upper()):+ out.append(s)+ return out+++def _camera_key(raw: Any) -> Tuple[str, bool]:+ """Canonical camera key + whether the input had to be forced.++ The stored `camera` field must be the key that was actually rendered, not whatever the+ model typed — a shot card reading `cam=medium` (observed: the model confused the `face`+ enum with this one) while the prompt says "holds a static shot" is a lie to the user.+ """+ k = str(raw or "").strip().lower().replace(" ", "_").replace("-", "_")+ aliases = {"locked": "static", "locked_off": "static", "tripod": "static", "none": "static",+ "push": "push_in", "zoom_in": "push_in", "dolly_in": "push_in",+ "pull": "pull_back", "pull_out": "pull_back", "zoom_out": "pull_back",+ "dolly_out": "pull_back", "handheld_sway": "handheld", "sway": "handheld",+ "shake": "handheld", "arc": "orbit", "slow_orbit": "orbit", "orbit_slow": "orbit",+ "slow_pan": "pan", "tilt": "tilt_up", "track": "tracking", "truck": "tracking"}+ k = aliases.get(k, k)+ if k in _CAMERA_SENTENCES:+ return k, False+ return "static", True+++def _camera_sentence(key: Any) -> str:+ return _CAMERA_SENTENCES[_camera_key(key)[0]]+++def _clean_settle(state: str) -> str:+ """A settled state describes the SUBJECT, never the camera.++ The model reliably writes "the camera stops orbiting" / "the camera holds on the scene"+ here, which is a camera instruction pasted into a clause that ends "with no new movement+ of any kind" — it contradicts itself and duplicates the camera direction. Clauses that+ talk about the camera are dropped; if that empties the phrase, there is no settle.+ """+ s = (state or "").strip().rstrip(".")+ if not s:+ return ""+ keep = [p for p in re.split(r",\s*", s) if "camera" not in p.lower()]+ return ", ".join(p for p in keep if p.strip()).strip()+++def _settle_sentence(state: str) -> str:+ s = _clean_settle(state)+ if not s:+ return ""+ return ("The movement is completely finished before the shot ends, and for the last two "+ "seconds %s, with no new movement of any kind." % s)+++def _has_person(text: str) -> bool:+ return bool(_PERSON_RE.search(text or ""))+++def _plain_punctuation(text: str) -> str:+ """Curly quotes, en/em dashes and ellipses out.++ H3 guide 7.6: punctuation and separators the model has not seen in training can be+ rendered as literal on-screen text. The model emits U+2019 constantly ("you've"), so it+ is normalised on the way into the prompt rather than left to chance."""+ out = text+ for bad, good in list(_SMART.items()) + [("…", "..."), (" ", " ")]:+ out = out.replace(bad, good)+ return out+++def _first(d: Dict[str, Any], keys: Sequence[str], default: str = "") -> str:+ for k in keys:+ v = d.get(k)+ if isinstance(v, str) and v.strip():+ return v.strip()+ if isinstance(v, (int, float)):+ return str(v)+ return default+++def _split_three_fields(desc: str) -> Tuple[str, str, str]:+ """If the model pasted the whole assembled prompt into one field, take it apart.++ Plain string slicing rather than a regex: the fields are literal labels in a fixed+ order, and a lazy DOTALL regex silently swallows the later labels into the first group.+ """+ low = desc.lower()+ if "integrated_multimodal_description" not in low:+ return desc, "", ""++ def cut(text: str, label: str) -> Tuple[str, str]:+ """-> (text before label, text after 'label:')"""+ i = text.lower().find(label)+ if i < 0:+ return text, ""+ rest = text[i + len(label):].lstrip()+ if rest.startswith(":"):+ rest = rest[1:]+ return text[:i], rest.strip()++ _, body = cut(desc, "integrated_multimodal_description")+ body, music = cut(body, "non_diegetic_music")+ body, sound = cut(body, "overall_soundscape")+ # non_diegetic_music can legally appear before overall_soundscape in sloppy output;+ # the second cut above already removed it from `body`, so nothing leaks either way.+ if music and "overall_soundscape" in music.lower():+ music, sound2 = cut(music, "overall_soundscape")+ sound = sound or sound2+ return body.strip(), sound.strip(), music.strip()+++def _strip_h3_markup(text: str) -> str:+ """H3 markup -> LTX prose. `<d>[English] Hi.</d>` becomes `'Hi.'`, markers go away."""+ out = _D_TAG_RE.sub(lambda m: "'%s'" % m.group(1).strip(), text)+ out = re.sub(r"\[Shot\s*\d+\](?:\s*At\s*\d\d:\d\d\.\d+,)?", "", out, flags=re.IGNORECASE)+ out = re.sub(r"\(S\d(?:,S\d)*\)", "", out)+ out = re.sub(r"</?d>", "", out)+ return re.sub(r"\s{2,}", " ", out).strip()+++def _fix_unbalanced_d(text: str) -> str:+ """A stray `<d>` with no `</d>` would be spoken as literal characters. Close it."""+ opens = len(re.findall(r"<d>", text))+ closes = len(re.findall(r"</d>", text))+ if opens == closes:+ return text+ if opens > closes:+ return text + ("</d>" * (opens - closes))+ return re.sub(r"</d>", "", text, count=(closes - opens))+++def _snap_duration(value: Any, engine: str, default: float) -> float:+ try:+ d = float(value)+ except (TypeError, ValueError):+ d = default+ if not (d > 0):+ d = default+ d = max(_MIN_DURATION, min(_MAX_DURATION, d))+ if engine == "h3":+ d = min(_H3_LENGTHS, key=lambda cand: (abs(cand - d), cand))+ return float(d)+++def _normalise_cast(characters: Optional[Iterable[Any]]) -> List[Dict[str, str]]:+ """Accept list_characters() records, plain ids, or {'id':..,'trigger':..} dicts."""+ out: List[Dict[str, str]] = []+ for c in characters or ():+ if isinstance(c, str):+ cid = c.strip()+ if cid:+ out.append({"id": cid, "trigger": cid, "name": cid, "description": ""})+ continue+ if not isinstance(c, dict):+ continue+ cid = str(c.get("id") or c.get("trigger") or c.get("character_id") or "").strip()+ if not cid:+ continue+ out.append({+ "id": cid,+ "trigger": str(c.get("trigger") or cid).strip(),+ "name": str(c.get("name") or cid).strip(),+ "description": str(c.get("description") or c.get("bio") or "").strip(),+ })+ return out+++def _match_character(raw: Any, cast: Sequence[Dict[str, str]]) -> Optional[Dict[str, str]]:+ if raw is None or not cast:+ return None+ key = str(raw).strip()+ if not key or key.lower() in ("null", "none", "n/a", ""):+ return None+ low = key.lower()+ for c in cast:+ if c["id"].lower() == low or c["trigger"].lower() == low or c["name"].lower() == low:+ return c+ # The model wrote a description ("the fighter"); accept a containment match rather than+ # silently dropping the casting the director asked for.+ for c in cast:+ if c["id"].lower() in low or (c["name"] and c["name"].lower() in low):+ return c+ return None+++def _seed_for(seed_base: int, n: int) -> int:+ return int((seed_base + n * 7919) % 2147483647)+++def _stable_seed(concept: str) -> int:+ h = hashlib.sha256(concept.encode("utf-8")).hexdigest()[:8]+ return int(h, 16) % 2147483647+++def _compose_body(desc: str, camera: Any, settle: str, face: str = "") -> str:+ """description + the camera law + the face law + the settle law, in exemplar order.++ If the model already wrote a camera sentence or an end-state clause of its own, that is+ honoured rather than duplicated — a prompt with two camera instructions is worse than a+ prompt with the wrong one.+ """+ body = _plain_punctuation(_SHOT_MARKER_RE.sub("", (desc or "").strip())).rstrip()+ if body and body[-1] not in ".!?":+ body += "."+ if "the camera" not in body.lower():+ body += " " + _camera_sentence(camera)+ law = _FACE_LAWS.get(face or "", "")+ if law and "holds the exact angle" not in body:+ body += " " + law+ if "completely finished before the shot ends" not in body.lower():+ s = _settle_sentence(_plain_punctuation(settle or ""))+ if s:+ body += " " + s+ if _NO_TEXT.lower() not in body.lower() and not _typography_strings(body):+ body += " " + _NO_TEXT+ return body+++def _assemble_h3_prompt(desc: str, sound: str, music: str,+ camera: Any = "static", settle: str = "", face: str = "") -> str:+ """The official three-field form. `[Shot 1]` carries no timestamp — every storyboard+ shot is one continuous take, so there is never a `[Shot 2]` inside a single prompt."""+ body = _fix_unbalanced_d(_compose_body(desc, camera, settle, face))+ sound = _plain_punctuation((sound or "").strip()) or "N/A"+ music = _plain_punctuation((music or "").strip()) or "N/A"+ return (+ "integrated_multimodal_description: [Shot 1] %s\n\n"+ "overall_soundscape: %s\n\n"+ "non_diegetic_music: %s" % (body, sound, music)+ )+++def _assemble_ltx_prompt(desc: str, sound: str, style: str,+ camera: Any = "static", settle: str = "", face: str = "") -> str:+ """LTX 2.3 prose: one paragraph, master style suffix verbatim, one trailing `Audio:`+ line (the shape mlx_warm_helper's enhance addendum says LTX was trained on)."""+ body = _strip_h3_markup(_compose_body(desc, camera, settle, face)).rstrip()+ if body and body[-1] not in ".!?":+ body += "."+ st = _plain_punctuation((style or "").strip().rstrip("."))+ if st and st.lower() not in body.lower():+ body += " %s." % st+ snd = _plain_punctuation((sound or "").strip().rstrip("."))+ if snd and snd.upper() != "N/A":+ body += " Audio: %s." % snd+ return body.strip()+++def default_policy(max_dim: Optional[int] = None) -> Dict[str, Any]:+ """Same shape `storyboard.new_storyboard()` produces, clamped to the machine's cap.++ validate_storyboard() rejects a policy whose longest edge exceeds `max_dim`, so the+ clamp happens here rather than being discovered at validation time.+ """+ policy = {+ "draft": {"quality": "quick", "width": 640, "height": 480, "frames": 49},+ "final": {"quality": "balanced", "width": 1024, "height": 576, "frames": 121},+ }+ if max_dim:+ for key in ("draft", "final"):+ p = policy[key]+ longest = max(p["width"], p["height"])+ if longest > max_dim:+ scale = float(max_dim) / float(longest)+ p["width"] = max(64, int(p["width"] * scale) // 8 * 8)+ p["height"] = max(64, int(p["height"] * scale) // 8 * 8)+ return policy+++def coerce_spec(+ raw: Any,+ *,+ concept: str,+ n_shots: int,+ style: str = "",+ cast: Optional[Sequence[Dict[str, str]]] = None,+ board_id: Optional[str] = None,+ engine: str = "auto",+ tier: str = "draft",+ duration_s: float = 5.0,+ seed_base: Optional[int] = None,+ max_dim: Optional[int] = None,+ created_at: Optional[int] = None,+ allow_hidden_faces: bool = False,+ storyboard_mod: Any = None,+) -> Tuple[Dict[str, Any], List[str]]:+ """Turn whatever the model returned into a schema-correct storyboard.++ Returns (spec, warnings). Never raises on bad model output — anything unusable is+ replaced by something legal and named in `warnings`, so the caller can decide whether+ the repair round is worth 40 seconds.+ """+ warnings: List[str] = []+ cast = list(cast or ())+ if seed_base is None:+ seed_base = _stable_seed(concept)++ if not isinstance(raw, dict):+ raw = {}+ warnings.append("model returned no JSON object")++ shots_raw = raw.get("shots")+ if not isinstance(shots_raw, list):+ for v in raw.values():+ if isinstance(v, list) and v and isinstance(v[0], dict):+ shots_raw = v+ warnings.append("shots were under a differently-named key")+ break+ if not isinstance(shots_raw, list):+ shots_raw = []+ warnings.append("model returned no shots array")++ shots: List[Dict[str, Any]] = []+ for idx, s in enumerate(shots_raw):+ if not isinstance(s, dict):+ warnings.append("shot %d was not an object" % (idx + 1))+ continue++ desc = _first(s, _DESC_KEYS)+ sound = _first(s, _SOUND_KEYS)+ music = _first(s, _MUSIC_KEYS, "N/A")+ if "integrated_multimodal_description" in desc.lower():+ desc, split_sound, split_music = _split_three_fields(desc)+ sound = split_sound or sound+ music = split_music or music+ warnings.append("shot %d pasted the assembled prompt into one field" % (idx + 1))+ desc = _SHOT_MARKER_RE.sub("", desc.strip())+ if not desc:+ warnings.append("shot %d had an empty description and was dropped" % (idx + 1))+ continue++ char = _match_character(s.get("character_id") or s.get("character"), cast)+ if s.get("character_id") and char is None and cast:+ warnings.append("shot %d named an unknown character %r — recast as uncast"+ % (idx + 1, s.get("character_id")))++ if engine in ("h3", "ltx"):+ eng = engine+ else:+ # auto: a trained Phosphene character is an LTX LoRA, and identity is the one+ # thing H3 cannot do. Everything else goes to H3.+ eng = "ltx" if char else "h3"++ n = len(shots) + 1+ dur = _snap_duration(s.get("duration_s") or s.get("duration") or s.get("seconds"),+ eng, duration_s)+ camera, cam_forced = _camera_key(s.get("camera") or s.get("camera_move"))+ if cam_forced and str(s.get("camera") or "").strip():+ warnings.append("shot %d asked for camera %r, which is not one of %s — locked off"+ % (idx + 1, str(s.get("camera")).strip(), ", ".join(CAMERA_KEYS)))+ settle_raw = str(s.get("settle") or s.get("end_state") or s.get("ending") or "").strip()+ settle = _clean_settle(settle_raw)+ if settle_raw and not settle:+ warnings.append("shot %d described the camera instead of an end state" % (idx + 1))++ # --- the face law ---------------------------------------------------------------+ face, face_forced = _face_level(+ s.get("face") or s.get("face_visible") or s.get("framing"), desc)+ if face_forced:+ warnings.append("shot %d said no face, but a person is on screen — the face law "+ "was applied anyway" % (idx + 1))+ if face == "hidden" and not allow_hidden_faces:+ face = "medium"+ warnings.append("shot %d asked to hide the face; the brief did not ask for that, "+ "so the face is kept visible" % (idx + 1))+ if face in ("close", "medium"):+ desc, cut_d = _scrub_face_blocking(desc)+ settle, cut_s = _scrub_face_blocking(settle)+ settle = settle.rstrip(".")+ for c in (cut_d + cut_s):+ warnings.append("shot %d: removed face-hiding framing %r" % (idx + 1, c[:70]))+ if not desc.strip():+ warnings.append("shot %d was entirely face-hiding and was dropped" % (idx + 1))+ continue+ if _TEXT_KEYWORD_RE.search(desc) and not _DQ_RE.search(desc):+ warnings.append("shot %d names on-screen text but does not put it in double "+ "quotes — H3 renders described strings as letter-shaped noise"+ % (idx + 1))++ if eng == "h3":+ prompt = _assemble_h3_prompt(desc, sound, music, camera, settle, face)+ else:+ prompt = _assemble_ltx_prompt(desc, sound, style, camera, settle, face)++ shot: Dict[str, Any] = {+ "n": n,+ "title": str(s.get("title") or s.get("label") or "Shot %d" % n).strip()[:80],+ "mode": "character" if char else "text",+ "engine": eng,+ "tier": tier,+ "prompt": prompt,+ "duration_s": dur,+ "seed": _seed_for(seed_base, n),+ "refs": [],+ "status": "pending",+ # The creative payload is kept alongside the assembled prompt so a re-roll can+ # edit one field without parsing it back out of the finished string.+ "description": desc,+ "camera": camera,+ "face": face,+ "settle": settle,+ "soundscape": sound,+ "music": music,+ }+ if char:+ shot["character_id"] = char["id"]+ shot["trigger"] = char["trigger"]+ if storyboard_mod is not None and hasattr(storyboard_mod, "ensure_trigger"):+ shot["prompt"] = storyboard_mod.ensure_trigger(shot["prompt"], char["trigger"])+ elif not re.search(r"\b%s\b" % re.escape(char["trigger"]), shot["prompt"]):+ shot["prompt"] = "%s %s" % (char["trigger"], shot["prompt"])+ if eng == "h3":+ # An H3 T2VA prompt must begin with the field label, so a prepended trigger+ # would be illegal (grammar rule 5). Put it inside the description instead.+ shot["prompt"] = _assemble_h3_prompt(+ "%s The on-screen subject is %s." % (desc, char["trigger"]),+ sound, music, camera, settle, face)+ shots.append(shot)++ if len(shots) != n_shots:+ warnings.append("asked for %d shots, model returned %d" % (n_shots, len(shots)))+ cams = {_camera_sentence(s.get("camera")) for s in shots}+ if len(shots) > 2 and len(cams) == 1:+ # Not corrected — overriding a director's camera is worse than telling them. But it+ # is the single most common small-model tell, so the UI gets to say so.+ warnings.append("every shot uses the same camera behaviour (%s) — consider varying it"+ % (shots[0].get("camera") or "static"))+ if len(shots) > 2 and not any((s.get("settle") or "").strip() for s in shots):+ warnings.append("no shot named an end state — H3 invents motion in the tail")++ title = str(raw.get("title") or raw.get("film_title") or "").strip()+ if not title:+ title = concept.strip()[:60] or "Untitled storyboard"+ warnings.append("model returned no title")++ created = int(created_at if created_at is not None else time.time())+ bid = board_id or "sb-%d-%s" % (created, hashlib.sha1(+ ("%s|%d" % (concept, seed_base)).encode("utf-8")).hexdigest()[:6])++ spec = {+ "schema": getattr(storyboard_mod, "SCHEMA_VERSION", 1) if storyboard_mod else 1,+ "id": bid,+ "title": title,+ "created_at": created,+ "cast": [{"id": c["id"], "trigger": c["trigger"], "name": c["name"]}+ for c in cast if any(s.get("character_id") == c["id"] for s in shots)],+ "policy": default_policy(max_dim),+ "shots": shots,+ }+ return spec, warnings+++# --------------------------------------------------------------------------------------+# The model process+# --------------------------------------------------------------------------------------++class PlannerSession(object):+ """A short-lived child process holding the planner model.++ Use it as a context manager when you want several generations to share one load+ (`plan_film()` does this internally for the repair round). It is NEVER left running:+ `plan_film()` releases in a finally, and `__exit__` releases too.++ with PlannerSession() as s:+ out = s.generate(system="...", user="...")+ # model is gone here, guaranteed by process exit+ """++ def __init__(self,+ model_path: Optional[Any] = None,+ python_exe: Optional[Any] = None,+ timeout_s: float = DEFAULT_TIMEOUT_S):+ self.model_path = Path(model_path or DEFAULT_MODEL_PATH)+ self.python_exe = Path(python_exe or WORKER_PYTHON)+ self.timeout_s = float(timeout_s)+ self.proc = None # type: Optional[subprocess.Popen]+ self.stats = {+ "model_path": str(self.model_path),+ "python": str(self.python_exe),+ "load_s": None,+ "calls": 0,+ "gen_s_total": 0.0,+ "prompt_tokens": 0,+ "output_tokens": 0,+ "peak_rss_bytes": 0,+ "mx_peak_bytes": 0,+ "released": False,+ }++ # -- lifecycle ----------------------------------------------------------------+ def _spawn(self) -> None:+ if self.proc is not None and self.proc.poll() is None:+ return+ if not self.model_path.exists():+ raise PlannerError(+ "planner model not found at %s — set LTX_STORYBOARD_PLANNER to an "+ "mlx-lm-loadable directory" % self.model_path)+ env = dict(os.environ)+ env.setdefault("PYTHONUNBUFFERED", "1")+ env.setdefault("TOKENIZERS_PARALLELISM", "false")+ self.proc = subprocess.Popen(+ [str(self.python_exe), str(Path(__file__).resolve()), "--serve"],+ stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,+ env=env, cwd=str(ROOT), text=True, bufsize=1,+ )+ self.stats["released"] = False++ def release(self) -> Dict[str, Any]:+ """Kill the child and reclaim every byte. Idempotent; safe to call twice."""+ proc = self.proc+ self.proc = None+ if proc is None:+ self.stats["released"] = True+ return self.stats+ try:+ if proc.poll() is None and proc.stdin is not None:+ try:+ proc.stdin.write(json.dumps({"action": "exit"}) + "\n")+ proc.stdin.flush()+ except (OSError, ValueError):+ pass+ try:+ proc.wait(timeout=10)+ except subprocess.TimeoutExpired:+ proc.kill()+ proc.wait(timeout=10)+ except Exception:+ try:+ proc.kill()+ except Exception:+ pass+ finally:+ for stream in (proc.stdin, proc.stdout, proc.stderr):+ try:+ if stream is not None:+ stream.close()+ except Exception:+ pass+ # Independent of anything the child said about itself.+ try:+ import resource+ rss = resource.getrusage(resource.RUSAGE_CHILDREN).ru_maxrss+ self.stats["children_maxrss_bytes"] = int(rss if sys.platform == "darwin" else rss * 1024)+ except Exception:+ pass+ self.stats["released"] = True+ return self.stats++ # Context manager so "load -> plan -> release" cannot be forgotten.+ def __enter__(self):+ return self++ def __exit__(self, *exc):+ self.release()+ return False++ unload = release # alias: the panel's vocabulary is "unload"++ # -- generation ---------------------------------------------------------------+ def generate(self, system: str, user: str,+ max_tokens: int = DEFAULT_MAX_TOKENS,+ temperature: float = DEFAULT_TEMPERATURE,+ seed: int = 10) -> Dict[str, Any]:+ self._spawn()+ req = {+ "action": "generate",+ "model_path": str(self.model_path),+ "system": system,+ "user": user,+ "max_tokens": int(max_tokens),+ "temperature": float(temperature),+ "seed": int(seed),+ }+ assert self.proc is not None and self.proc.stdin is not None+ try:+ self.proc.stdin.write(json.dumps(req) + "\n")+ self.proc.stdin.flush()+ except (OSError, ValueError) as exc:+ raise PlannerError("planner subprocess died before it could be asked: %s" % exc)++ deadline = time.time() + self.timeout_s+ assert self.proc.stdout is not None+ while True:+ if self.proc.poll() is not None:+ err = ""+ try:+ if self.proc.stderr is not None:+ err = self.proc.stderr.read()[-2000:]+ except Exception:+ pass+ raise PlannerError("planner subprocess exited (%s)%s"+ % (self.proc.returncode, (": " + err) if err else ""))+ line = self.proc.stdout.readline()+ if not line:+ raise PlannerError("planner subprocess closed its output")+ if line.startswith(_SENTINEL):+ resp = json.loads(line[len(_SENTINEL):])+ break+ if time.time() > deadline:+ raise PlannerError("planner timed out after %.0fs" % self.timeout_s)++ if resp.get("error"):+ raise PlannerError("planner model error: %s" % resp["error"])++ st = self.stats+ if st["load_s"] is None and resp.get("load_s") is not None:+ st["load_s"] = resp["load_s"]+ st["calls"] += 1+ st["gen_s_total"] = round(st["gen_s_total"] + float(resp.get("gen_s") or 0.0), 2)+ st["prompt_tokens"] += int(resp.get("prompt_tokens") or 0)+ st["output_tokens"] += int(resp.get("output_tokens") or 0)+ st["peak_rss_bytes"] = max(st["peak_rss_bytes"], int(resp.get("peak_rss_bytes") or 0))+ st["mx_peak_bytes"] = max(st["mx_peak_bytes"], int(resp.get("mx_peak_bytes") or 0))+ return resp+++# --------------------------------------------------------------------------------------+# plan_film+# --------------------------------------------------------------------------------------++def is_plan_error(result: Any) -> bool:+ """True when plan_film() returned a structured error rather than a film spec."""+ return isinstance(result, dict) and result.get("ok") is False+++def _error(kind: str, message: str, *, hint: str = "", problems: Optional[Sequence[str]] = None,+ raw: str = "", meta: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:+ """A failure the UI can render as a sentence and a fix-list. Never a traceback."""+ return {+ "ok": False,+ "error": {+ "kind": kind,+ "message": message,+ "hint": hint,+ "problems": list(problems or ()),+ "raw_excerpt": (raw or "")[:1200],+ },+ "_planner": dict(meta or {}),+ }+++def _parse_feedback(feedback: Any) -> Tuple[str, Optional[int], str]:+ """-> (mode, shot_n, note). mode is 'none' | 'film' | 'shot'."""+ if feedback is None:+ return "none", None, ""+ if isinstance(feedback, dict):+ note = str(feedback.get("note") or feedback.get("text") or feedback.get("feedback") or "").strip()+ shot = feedback.get("shot", feedback.get("shot_n", feedback.get("n")))+ if shot is not None:+ try:+ return "shot", int(shot), note+ except (TypeError, ValueError):+ pass+ return ("film", None, note) if note else ("none", None, "")+ text = str(feedback).strip()+ if not text:+ return "none", None, ""+ m = re.match(r"^\s*shots?\s*#?\s*(\d+)\s*[:\-\u2014]\s*(.+)$", text, re.IGNORECASE | re.DOTALL)+ if m:+ return "shot", int(m.group(1)), m.group(2).strip()+ return "film", None, text+++def plan_film(+ concept: str,+ n_shots: int = 6,+ style: str = "",+ characters: Optional[Iterable[Any]] = None,+ must_include: Optional[Iterable[Any]] = None,+ feedback: Any = None,+ *,+ previous: Optional[Dict[str, Any]] = None,+ engine: str = "auto",+ tier: str = "draft",+ duration_s: float = 5.0,+ allow_hidden_faces: Optional[bool] = None,+ board_id: Optional[str] = None,+ known_character_ids: Optional[Iterable[str]] = None,+ ref_root: Optional[Any] = None,+ max_dim: Optional[int] = None,+ temperature: float = DEFAULT_TEMPERATURE,+ seed: Optional[int] = None,+ max_tokens: Optional[int] = None,+ model_path: Optional[Any] = None,+ python_exe: Optional[Any] = None,+ session: Optional[PlannerSession] = None,+ timeout_s: float = DEFAULT_TIMEOUT_S,+) -> Dict[str, Any]:+ """Concept -> film spec that `storyboard.validate_storyboard()` accepts.++ Returns EITHER a storyboard dict (schema/id/title/created_at/cast/policy/shots, plus a+ `_planner` block of metadata the validator ignores) OR a structured error dict — test+ with `is_plan_error(result)`. It never raises for model behaviour and never surfaces a+ traceback to a user.++ Args:+ concept one or two sentences of intent. The only required argument.+ n_shots how many shots to plan.+ style master style, reused verbatim on every shot.+ characters trained characters available for casting. Accepts `list_characters()`+ records, bare id strings, or {'id','trigger','name','description'}.+ A shot cast with one renders on LTX (that is where character LoRAs+ live); everything else renders on H3.+ must_include things that must appear somewhere in the film.+ feedback None for a fresh plan. For a re-plan pass `previous=` plus either:+ film-level : "make it colder, drop the voiceover"+ per-shot : "shot 4: he should not turn his head"+ or {"shot": 4, "note": "..."}+ Per-shot re-rolls replace ONLY that shot; every other shot object is+ carried across by reference, so the rest of the plan is byte-stable.+ engine "auto" (default) | "h3" | "ltx". Auto = H3 unless the shot is cast.+ tier per-shot tier, default "draft" — plans are for reviewing, not shipping.+ allow_hidden_faces+ None (default) auto-detects from the brief: a face may only be hidden+ if the concept, style or must_include asked for it in so many words+ ("silhouette", "from behind", "faceless", ...). Otherwise every shot+ with a person carries the face law and face-hiding framing is scrubbed+ out of the prose. Pass True/False to override the detection.+ max_dim this machine's resolution cap; the policy is clamped to it so the+ validator's tier check cannot fire.+ session an already-open PlannerSession to borrow. If given it is NOT released+ (the owner keeps it); otherwise a private one is opened and always+ released before returning.++ Pass one when the caller needs a handle on the running model — a+ Cancel button is the case that matters: `plan_film()` blocks for+ 20-40 s, and the only way to stop it is `sess.release()` from another+ thread, which kills the child and makes this call raise into its own+ `finally`. A caller that supplies a session MUST release it.+ """+ t_start = time.time()+ if not str(concept or "").strip():+ raise PlannerError("concept is empty")+ n_shots = max(1, int(n_shots))+ cast = _normalise_cast(characters)+ must = [str(m).strip() for m in (must_include or ()) if str(m).strip()]+ fb_mode, fb_shot, fb_note = _parse_feedback(feedback)+ if fb_mode != "none" and previous is None:+ previous = feedback.get("previous") if isinstance(feedback, dict) else None+ if fb_mode != "none" and not isinstance(previous, dict):+ raise PlannerError("feedback needs the plan it refers to — pass previous=<spec>")++ # A hidden face is opt-in, and the brief is the only thing that may opt in. Detection+ # reads the concept, the style and the must-includes — not the model's output, which is+ # exactly the thing being guarded against.+ if allow_hidden_faces is None:+ brief_text = " ".join([concept or "", style or ""] + must)+ allow_hidden = bool(_WANTS_HIDDEN_RE.search(brief_text))+ else:+ allow_hidden = bool(allow_hidden_faces)++ validate, sb = _load_validator()+ seed_base = int(seed) if seed is not None else _stable_seed(concept)+ known_ids = list(known_character_ids) if known_character_ids is not None \+ else [c["id"] for c in cast]+ budget = int(max_tokens) if max_tokens else min(+ 8192, max(1200, 380 * (1 if fb_mode == "shot" else n_shots) + 500))++ system = _build_system_prompt(engine, bool(cast), allow_hidden)+ if fb_mode == "shot":+ user = _build_shot_feedback_prompt(previous, fb_shot, fb_note)+ elif fb_mode == "film":+ user = _build_film_feedback_prompt(previous, fb_note, n_shots)+ else:+ user = _build_user_prompt(concept, n_shots, style, cast, must)++ owned = session is None+ sess = session or PlannerSession(model_path=model_path, python_exe=python_exe,+ timeout_s=timeout_s)+ result: Dict[str, Any] = {}+ try:+ result = _plan_with_session(+ sess, system=system, user=user, fb_mode=fb_mode, fb_shot=fb_shot,+ previous=previous, validate=validate, sb=sb, concept=concept, n_shots=n_shots,+ style=style, cast=cast, board_id=board_id, engine=engine, tier=tier,+ duration_s=duration_s, seed_base=seed_base, max_dim=max_dim,+ known_ids=known_ids, ref_root=ref_root, temperature=temperature,+ budget=budget, model_path=model_path, t_start=t_start,+ allow_hidden_faces=allow_hidden)+ finally:+ # The model is gone before this function returns, on every path including an+ # exception. Peak RSS is only final once the child has been reaped, so the+ # measurement is patched in AFTER release.+ stats = sess.release() if owned else sess.stats+ blk = result.get("_planner") if isinstance(result, dict) else None+ if isinstance(blk, dict):+ blk.update(_session_meta_from(stats))+ return result+++def _plan_with_session(sess, *, system, user, fb_mode, fb_shot, previous, validate, sb,+ concept, n_shots, style, cast, board_id, engine, tier, duration_s,+ seed_base, max_dim, known_ids, ref_root, temperature, budget,+ model_path, t_start, allow_hidden_faces) -> Dict[str, Any]:+ """The generate -> extract -> coerce -> validate -> ONE repair loop.++ Split out of plan_film() so the `finally:` that releases the model is three lines with+ nothing else in it — an unload that shares a code path with the happy path is an unload+ that eventually gets skipped.+ """+ meta = {"model": Path(model_path or sess.model_path).name, "attempts": 0}++ def coerce(obj):+ return _coerce_for_mode(+ obj, fb_mode, fb_shot, previous, concept=concept, n_shots=n_shots, style=style,+ cast=cast, board_id=board_id, engine=engine, tier=tier, duration_s=duration_s,+ seed_base=seed_base, max_dim=max_dim, sb=sb,+ allow_hidden_faces=allow_hidden_faces)++ def check(spec):+ return list(validate(spec, known_character_ids=known_ids,+ ref_root=Path(ref_root) if ref_root else None, max_dim=max_dim))++ # ---- attempt 1 ------------------------------------------------------------------+ try:+ resp = sess.generate(system, user, max_tokens=budget,+ temperature=temperature, seed=seed_base % 100000)+ except PlannerError as exc:+ return _error("model_unavailable", str(exc),+ hint="Check that the planner model exists and that ltx-2-mlx/env "+ "has mlx-lm installed.",+ meta=dict(meta, elapsed_s=round(time.time() - t_start, 2)))+ meta["attempts"] = 1+ raw_text = resp.get("text") or ""+ obj = extract_json_object(raw_text)+ spec, warnings = coerce(obj)+ errs = check(spec)+ first_try = list(errs)+ count_off = (fb_mode != "shot") and (len(spec.get("shots") or []) != n_shots)+ first_try_clean = not first_try and not count_off and obj is not None++ # ---- ONE repair round-trip, carrying the REAL validator's words ------------------+ # Not a retry loop: a second failure means the concept is the problem, and burning+ # another 40 s of a user's evening to hear the same complaint helps nobody.+ if errs or count_off or obj is None:+ problems = list(errs)+ if count_off:+ problems.append("the plan has %d shots but exactly %d were requested"+ % (len(spec.get("shots") or []), n_shots))+ if obj is None:+ problems.append("your reply did not contain a JSON object at all")+ try:+ resp2 = sess.generate(system, _build_repair_prompt(raw_text, problems, n_shots),+ max_tokens=budget,+ temperature=max(0.0, temperature * 0.5),+ seed=(seed_base + 1) % 100000)+ meta["attempts"] = 2+ raw2 = resp2.get("text") or ""+ obj2 = extract_json_object(raw2)+ if obj2 is not None:+ spec2, warn2 = coerce(obj2)+ errs2 = check(spec2)+ off2 = (fb_mode != "shot") and (len(spec2.get("shots") or []) != n_shots)+ # Keep the repair only if it is genuinely better, so a worse second draft+ # cannot destroy a first draft that merely had the wrong shot count.+ if (len(errs2), off2) < (len(errs), count_off):+ spec, warnings, errs, count_off, raw_text = spec2, warn2, errs2, off2, raw2+ warnings.append("repaired on the second pass")+ except PlannerError as exc:+ warnings.append("repair round failed: %s" % exc)++ if errs:+ return _error(+ "invalid_plan",+ "The planner could not turn this concept into a valid storyboard.",+ hint="Try a shorter, more concrete concept, or fewer shots.",+ problems=errs, raw=raw_text,+ meta=dict(meta, warnings=warnings, elapsed_s=round(time.time() - t_start, 2),+ **_session_meta(sess)))++ spec["_planner"] = dict(+ meta,+ ok=True,+ warnings=warnings,+ first_try_errors=first_try,+ first_try_clean=first_try_clean,+ shot_count_ok=not count_off,+ engine_mix=_engine_mix(spec),+ concept=concept.strip(),+ feedback_mode=fb_mode,+ elapsed_s=round(time.time() - t_start, 2),+ **_session_meta(sess)+ )+ return spec+++def _session_meta(sess: PlannerSession) -> Dict[str, Any]:+ return _session_meta_from(sess.stats)+++def _session_meta_from(stats: Dict[str, Any]) -> Dict[str, Any]:+ return {+ "model_path": stats.get("model_path"),+ "load_s": stats.get("load_s"),+ "gen_s": stats.get("gen_s_total"),+ "prompt_tokens": stats.get("prompt_tokens"),+ "output_tokens": stats.get("output_tokens"),+ "peak_rss_bytes": stats.get("peak_rss_bytes"),+ "peak_rss_gb": round((stats.get("peak_rss_bytes") or 0) / float(2 ** 30), 2),+ "mx_peak_gb": round((stats.get("mx_peak_bytes") or 0) / float(2 ** 30), 2),+ "model_released": bool(stats.get("released")),+ }+++def _engine_mix(spec: Dict[str, Any]) -> Dict[str, int]:+ mix: Dict[str, int] = {}+ for s in spec.get("shots") or ():+ k = s.get("engine") or "h3"+ mix[k] = mix.get(k, 0) + 1+ return mix+++def _coerce_for_mode(obj, fb_mode, fb_shot, previous, *, concept, n_shots, style, cast,+ board_id, engine, tier, duration_s, seed_base, max_dim, sb,+ allow_hidden_faces=False):+ """Coerce a fresh plan, or splice one re-rolled shot into an existing plan."""+ if fb_mode != "shot":+ return coerce_spec(obj, concept=concept, n_shots=n_shots, style=style, cast=cast,+ board_id=board_id, engine=engine, tier=tier,+ duration_s=duration_s, seed_base=seed_base, max_dim=max_dim,+ allow_hidden_faces=allow_hidden_faces, storyboard_mod=sb)++ # Per-shot re-roll: coerce the single returned shot, then splice. Every other shot+ # object is carried across by reference, so the untouched part of the plan is+ # byte-identical when re-serialised.+ one, warnings = coerce_spec(obj, concept=concept, n_shots=1, style=style, cast=cast,+ board_id=previous.get("id"), engine=engine, tier=tier,+ duration_s=duration_s, seed_base=seed_base, max_dim=max_dim,+ allow_hidden_faces=allow_hidden_faces, storyboard_mod=sb)+ new_shots = one.get("shots") or []+ spec = copy.copy(previous)+ spec["shots"] = list(previous.get("shots") or [])+ if not new_shots:+ warnings.append("re-roll returned no usable shot; the original was kept")+ return spec, warnings+ replacement = new_shots[0]+ for i, s in enumerate(spec["shots"]):+ if s.get("n") == fb_shot:+ replacement["n"] = fb_shot+ # A re-roll should look different: nudge the seed rather than re-render the+ # same latent with new words.+ replacement["seed"] = _seed_for(seed_base + int(time.time()) % 9973, fb_shot)+ for carry in ("status",):+ if carry in s:+ replacement[carry] = s[carry]+ spec["shots"][i] = replacement+ break+ else:+ warnings.append("shot %r was not in the plan; nothing replaced" % fb_shot)+ return spec, warnings+++# --------------------------------------------------------------------------------------+# The worker process (runs under ltx-2-mlx/env python3.11 — the only place mlx is imported)+# --------------------------------------------------------------------------------------++def _worker_serve() -> int:+ import resource++ def emit(obj):+ sys.stdout.write(_SENTINEL + json.dumps(obj) + "\n")+ sys.stdout.flush()++ def peak_rss_bytes():+ r = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss+ return int(r if sys.platform == "darwin" else r * 1024)++ model = tokenizer = None+ loaded_path = None+ load_s = None++ for line in sys.stdin:+ line = line.strip()+ if not line:+ continue+ try:+ req = json.loads(line)+ except ValueError as exc:+ emit({"error": "bad request: %s" % exc})+ continue+ action = req.get("action")+ if action == "exit":+ break+ if action == "ping":+ emit({"pong": True, "peak_rss_bytes": peak_rss_bytes()})+ continue+ if action != "generate":+ emit({"error": "unknown action %r" % action})+ continue+ try:+ import mlx.core as mx+ from mlx_lm import load as mlx_lm_load, generate as mlx_generate+ from mlx_lm.sample_utils import make_sampler++ path = req["model_path"]+ if model is None or loaded_path != path:+ t0 = time.time()+ model, tokenizer = mlx_lm_load(path)+ loaded_path = path+ load_s = round(time.time() - t0, 2)++ messages = [+ {"role": "system", "content": req.get("system") or ""},+ {"role": "user", "content": req.get("user") or ""},+ ]+ try:+ chat = tokenizer.apply_chat_template(+ messages, tokenize=False, add_generation_prompt=True)+ except Exception:+ # Some chat templates refuse a system role — fold it into the user turn.+ chat = tokenizer.apply_chat_template(+ [{"role": "user", "content": (req.get("system") or "") + "\n\n"+ + (req.get("user") or "")}],+ tokenize=False, add_generation_prompt=True)++ mx.random.seed(int(req.get("seed") or 10))+ t0 = time.time()+ text = mlx_generate(+ model=model, tokenizer=tokenizer, prompt=chat,+ max_tokens=int(req.get("max_tokens") or DEFAULT_MAX_TOKENS),+ sampler=make_sampler(temp=float(req.get("temperature") or 0.0)),+ verbose=False,+ )+ gen_s = round(time.time() - t0, 2)+ try:+ mx_peak = int(mx.get_peak_memory())+ except Exception:+ mx_peak = 0+ emit({+ "text": text,+ "load_s": load_s,+ "gen_s": gen_s,+ "prompt_tokens": len(tokenizer.encode(chat)),+ "output_tokens": len(tokenizer.encode(text)),+ "peak_rss_bytes": peak_rss_bytes(),+ "mx_peak_bytes": mx_peak,+ })+ except Exception as exc: # never let a traceback reach the parent as protocol+ import traceback+ emit({"error": "%s: %s" % (type(exc).__name__, exc),+ "trace": traceback.format_exc()[-1500:]})+ return 0+++# --------------------------------------------------------------------------------------+# CLI — `--serve` is the worker; no args plans a film and prints it+# --------------------------------------------------------------------------------------++def _main(argv: Sequence[str]) -> int:+ if "--serve" in argv:+ return _worker_serve()+ import argparse+ ap = argparse.ArgumentParser(description="Plan a Phosphene storyboard from a concept.")+ ap.add_argument("concept", nargs="?", help="one or two sentences of intent")+ ap.add_argument("-n", "--shots", type=int, default=6)+ ap.add_argument("--style", default="")+ ap.add_argument("--character", action="append", default=[],+ help="trigger of a trained character available for casting")+ ap.add_argument("--must", action="append", default=[])+ ap.add_argument("--engine", default="auto", choices=("auto", "h3", "ltx"))+ ap.add_argument("--tier", default="draft")+ ap.add_argument("--temperature", type=float, default=DEFAULT_TEMPERATURE)+ ap.add_argument("--model", default=None)+ args = ap.parse_args([a for a in argv if a != "--serve"])+ if not args.concept:+ ap.error("a concept is required")+ out = plan_film(args.concept, n_shots=args.shots, style=args.style,+ characters=args.character, must_include=args.must,+ engine=args.engine, tier=args.tier, temperature=args.temperature,+ model_path=args.model)+ print(json.dumps(out, indent=2, ensure_ascii=False))+ return 1 if is_plan_error(out) else 0+++if __name__ == "__main__":+ sys.exit(_main(sys.argv[1:]))diff --git a/test_storyboard.py b/test_storyboard.pynew file mode 100644index 0000000..dc29707--- /dev/null+++ b/test_storyboard.py@@ -0,0 +1,445 @@+#!/usr/bin/env python3+"""Tests for storyboard.py — the storyboard spine.++No GPU, no weights, no panel import. Everything here is the real module.++Run: python3 -m unittest test_storyboard+"""++import json+import tempfile+import unittest+from pathlib import Path++import storyboard as sb+++def _shot(n, **kw):+ s = {"n": n, "mode": "text", "engine": "h3", "prompt": f"shot {n} happens",+ "duration_s": 5.0, "seed": 1000 + n, "refs": [], "status": "pending"}+ s.update(kw)+ return s+++def _board(shots, **kw):+ b = sb.new_storyboard("sb_test", "The Long Walk", shots=shots)+ b.update(kw)+ return b+++class FrameGrid(unittest.TestCase):+ def test_ltx_grid_matches_docs_api(self):+ # docs/API.md publishes exactly this table.+ self.assertEqual(sb.ltx_frames_for(3), 73)+ self.assertEqual(sb.ltx_frames_for(5), 121)+ self.assertEqual(sb.ltx_frames_for(7), 169)+ self.assertEqual(sb.ltx_frames_for(10), 241)++ def test_ltx_grid_is_always_on_the_sampler_grid(self):+ for tenths in range(10, 601):+ f = sb.ltx_frames_for(tenths / 10.0)+ self.assertEqual(f % 8, 1, f"{tenths/10.0}s -> {f}")+ self.assertGreaterEqual(f, 9)++ def test_h3_length_snap(self):+ self.assertEqual(sb.h3_length_for(3), "3s")+ self.assertEqual(sb.h3_length_for(4), "3s") # tie -> shorter+ self.assertEqual(sb.h3_length_for(5), "5s")+ self.assertEqual(sb.h3_length_for(7), "5s")+ self.assertEqual(sb.h3_length_for(10), "10s")+ self.assertEqual(sb.h3_length_for(14), "15s")+++class ShotToJob(unittest.TestCase):+ POLICY = {"quality": "quick", "width": 640, "height": 480, "frames": 49}++ def test_engine_rides_through(self):+ j = sb.shot_to_job(_shot(1, engine="h3"), self.POLICY)+ self.assertEqual(j["engine"], "h3")+ j = sb.shot_to_job(_shot(1, engine="ltx"), self.POLICY)+ self.assertEqual(j["engine"], "ltx")++ def test_unknown_engine_falls_back_to_builtin(self):+ j = sb.shot_to_job(_shot(1, engine="sora"), self.POLICY)+ self.assertEqual(j["engine"], "ltx")++ def test_character_shot_is_forced_to_ltx(self):+ j = sb.shot_to_job(+ _shot(1, engine="h3", mode="character", character_id="bizarrotrn",+ trigger="bizarrotrn"), self.POLICY)+ self.assertEqual(j["engine"], "ltx")+ self.assertEqual(j["character_id"], "bizarrotrn")++ def test_h3_unavailable_forces_ltx(self):+ j = sb.shot_to_job(_shot(1, engine="h3"), self.POLICY, h3_available=False)+ self.assertEqual(j["engine"], "ltx")++ def test_mode_is_translated_to_the_panels_vocabulary(self):+ # The panel has no backend mode called "text" or "character" — both are t2v.+ self.assertEqual(sb.shot_to_job(_shot(1, mode="text"), self.POLICY)["mode"], "t2v")+ self.assertEqual(+ sb.shot_to_job(_shot(1, mode="character", character_id="x", trigger="x"),+ self.POLICY)["mode"], "t2v")++ def test_duration_drives_frames_on_the_ltx_grid(self):+ for d, f in ((3, 73), (5, 121), (7, 169), (10, 241)):+ j = sb.shot_to_job(_shot(1, engine="ltx", duration_s=d), self.POLICY)+ self.assertEqual(j["frames"], f, f"{d}s")++ def test_duration_drives_the_h3_cell(self):+ j = sb.shot_to_job(_shot(1, engine="h3", duration_s=10), self.POLICY)+ self.assertEqual(j["h3_length"], "10s")+ self.assertEqual(j["frames"], 243)+ self.assertEqual(j["h3_quality"], "draft") # policy quality "quick"++ def test_h3_quality_tracks_the_pass(self):+ final = {"quality": "standard", "width": 1024, "height": 576, "frames": 121}+ j = sb.shot_to_job(_shot(1, engine="h3"), final)+ self.assertEqual(j["h3_quality"], "high")++ def test_queue_linkage(self):+ j = sb.shot_to_job(_shot(3), self.POLICY,+ board_id="sb_20260811_a1b2", board_title="The Long Walk")+ self.assertEqual(j["session_tag"], "sb:sb_20260811_a1b2#3")+ self.assertEqual(j["preset_label"], "S03 · The Long Walk")++ def test_enhance_stays_off_and_the_viewer_is_not_stolen(self):+ j = sb.shot_to_job(_shot(1), self.POLICY)+ self.assertEqual(j["enhance"], "off")+ self.assertEqual(j["open_when_done"], "off")+ self.assertNotIn("auto_open", j) # was never in make_job's allowlist++ def test_trigger_is_injected_mechanically(self):+ j = sb.shot_to_job(+ _shot(1, mode="character", character_id="bizarrotrn", trigger="bizarrotrn",+ prompt="a man walks"), self.POLICY)+ self.assertTrue(j["prompt"].startswith("bizarrotrn "))++ def test_seed_rides_through(self):+ self.assertEqual(sb.shot_to_job(_shot(4), self.POLICY)["seed"], 1004)+++class FilmLevelEngine(unittest.TestCase):+ """The film's own engine choice — the owner asked for it by name."""++ POLICY = {"quality": "quick", "width": 640, "height": 480, "frames": 49}++ def test_auto_keeps_what_the_plan_wrote(self):+ self.assertEqual(sb.resolve_engine(_shot(1, engine="h3"), engine_mode="auto"), "h3")+ self.assertEqual(sb.resolve_engine(_shot(1, engine="ltx"), engine_mode="auto"), "ltx")++ def test_forcing_h3_moves_an_ltx_shot(self):+ self.assertEqual(sb.resolve_engine(_shot(1, engine="ltx"), engine_mode="h3"), "h3")++ def test_forcing_ltx_moves_an_h3_shot(self):+ self.assertEqual(sb.resolve_engine(_shot(1, engine="h3"), engine_mode="ltx"), "ltx")++ def test_a_cast_shot_beats_the_film_setting(self):+ # H3 stacks no LoRAs; forcing a cast shot onto it renders a stranger.+ cast = _shot(1, engine="h3", mode="character", character_id="c", trigger="c")+ self.assertEqual(sb.resolve_engine(cast, engine_mode="h3"), "ltx")++ def test_a_missing_pack_beats_everything(self):+ self.assertEqual(+ sb.resolve_engine(_shot(1, engine="h3"), engine_mode="h3", h3_available=False),+ "ltx")++ def test_shot_to_job_honours_the_film_setting(self):+ j = sb.shot_to_job(_shot(1, engine="ltx"), self.POLICY, engine_mode="h3")+ self.assertEqual(j["engine"], "h3")+ self.assertIn("h3_length", j)+ j = sb.shot_to_job(_shot(1, engine="h3"), self.POLICY, engine_mode="ltx")+ self.assertEqual(j["engine"], "ltx")+ self.assertNotIn("h3_length", j)++ def test_unknown_mode_falls_back_to_auto(self):+ self.assertEqual(sb.resolve_engine(_shot(1, engine="h3"), engine_mode="nonsense"), "h3")+++class H3ChainPrompts(unittest.TestCase):+ """A 10 s H3 clip is two 5 s windows; both were being asked for the same+ prompt, so the one-off action happened twice."""++ POLICY = {"quality": "quick", "width": 640, "height": 480, "frames": 49}++ def _shot10(self, **kw):+ s = _shot(1, engine="h3", duration_s=10,+ settle="he stands empty-handed with his shoulders down",+ soundscape="Wind across open sand, and one long exhale.")+ s.update(kw)+ return s++ def test_single_window_shapes_get_nothing(self):+ for d in (3, 5):+ self.assertEqual(sb.h3_chain_prompts_for(self._shot10(duration_s=d)), [])++ def test_ltx_gets_nothing(self):+ self.assertEqual(sb.h3_chain_prompts_for(self._shot10(engine="ltx")), [])++ def test_ten_seconds_gets_two_entries_first_blank(self):+ got = sb.h3_chain_prompts_for(self._shot10())+ self.assertEqual(len(got), 2)+ self.assertEqual(got[0], "") # "" == use the main prompt+ self.assertTrue(got[1].startswith("integrated_multimodal_description:"))++ def test_fifteen_seconds_gets_three(self):+ self.assertEqual(len(sb.h3_chain_prompts_for(self._shot10(duration_s=15))), 3)++ def test_the_continuation_holds_the_settled_state(self):+ tail = sb.h3_chain_prompts_for(self._shot10())[1]+ self.assertIn("he stands empty-handed with his shoulders down", tail)+ self.assertIn("without a cut", tail)+ self.assertIn("overall_soundscape:", tail)+ self.assertIn("non_diegetic_music:", tail)++ def test_no_settle_means_no_invention(self):+ # Nothing honest to say about how it continues -> today's behaviour.+ self.assertEqual(sb.h3_chain_prompts_for(self._shot10(settle="")), [])++ def test_shot_to_job_only_sends_it_when_the_runner_supports_it(self):+ s = self._shot10()+ self.assertNotIn("h3_chain_prompts", sb.shot_to_job(s, self.POLICY))+ j = sb.shot_to_job(s, self.POLICY, h3_chain_prompts=True)+ self.assertEqual(len(json.loads(j["h3_chain_prompts"])), 2)+++class Bucketing(unittest.TestCase):+ def test_engine_is_part_of_the_bucket(self):+ self.assertNotEqual(sb.bucket_key(_shot(1, engine="h3")),+ sb.bucket_key(_shot(2, engine="ltx")))++ def test_mixed_film_groups_by_engine_not_story_order(self):+ shots = [_shot(1, engine="h3"), _shot(2, engine="ltx", mode="character",+ character_id="c", trigger="c"),+ _shot(3, engine="h3"), _shot(4, engine="ltx", mode="character",+ character_id="c", trigger="c")]+ order = [s["n"] for s in sb.shooting_order(shots)]+ self.assertEqual(order, [1, 3, 2, 4])++ def test_twelve_shots_one_engine_means_one_bucket(self):+ shots = [_shot(i, engine="h3") for i in range(1, 13)]+ est = sb.estimate(_board(shots), pass_name="draft")+ self.assertEqual(est["pipeline_loads"], 1)+ self.assertEqual([s["n"] for s in sb.shooting_order(shots)], list(range(1, 13)))++ def test_rendered_and_cut_are_excluded(self):+ # "Rendered" means THIS PASS produced a clip — not that `status` happens+ # to read "done". A shot whose status says done but which has no output+ # for this pass still has to be shot.+ shots = [_shot(1, status="done", draft_output="/tmp/s1.mp4"),+ _shot(2, status="skipped"),+ _shot(3),+ _shot(4, status="done")] # done, but nothing to show for it+ self.assertEqual([s["n"] for s in sb.shooting_order(shots)], [3, 4])+++class TwoPasses(unittest.TestCase):+ """Draft then delivery. The release-blocker lived here: the scheduler asked+ the shot's single `status` field whether it was finished, and the reconciler+ set that field to "done" the moment the DRAFT landed — so the delivery pass+ saw an empty film and enqueued nothing, for every board, forever."""++ def _drafted(self):+ """A film whose draft pass has completed, exactly as reconcile leaves it."""+ return [_shot(n, status="done", draft_output=f"/tmp/s{n}.mp4",+ draft_job_id=f"j-{n}") for n in (1, 2, 3)]++ def test_the_draft_pass_is_finished(self):+ self.assertEqual(sb.shooting_order(self._drafted(), "draft"), [])++ def test_the_delivery_pass_still_has_every_shot(self):+ got = sb.shooting_order(self._drafted(), "final")+ self.assertEqual([s["n"] for s in got], [1, 2, 3])++ def test_delivery_drops_a_shot_once_it_has_delivered(self):+ shots = self._drafted()+ shots[1]["final_output"] = "/tmp/s2_final.mp4"+ self.assertEqual([s["n"] for s in sb.shooting_order(shots, "final")], [1, 3])++ def test_cut_shots_are_out_of_both_passes(self):+ shots = self._drafted()+ shots[0]["status"] = "skipped"+ self.assertEqual([s["n"] for s in sb.shooting_order(shots, "final")], [2, 3])+ self.assertEqual(sb.shooting_order(shots, "draft"), [])++ def test_the_delivery_estimate_is_not_zero(self):+ board = _board(self._drafted())+ self.assertEqual(sb.estimate(board, pass_name="draft")["shots"], 0)+ self.assertEqual(sb.estimate(board, pass_name="final")["shots"], 3)+ self.assertGreater(sb.estimate(board, pass_name="final")["total_secs"], 0)++ def test_delivery_jobs_carry_the_delivery_policy(self):+ board = _board(self._drafted())+ policy = board["policy"]["final"]+ j = sb.shot_to_job(sb.shooting_order(board["shots"], "final")[0], policy)+ self.assertEqual(j["quality"], "balanced")+ self.assertEqual((j["width"], j["height"]), (1024, 576))++ def test_pass_helpers(self):+ s = {"draft_output": "/tmp/a.mp4"}+ self.assertTrue(sb.shot_pass_done(s, "draft"))+ self.assertFalse(sb.shot_pass_done(s, "final"))+ self.assertEqual(sb.pass_output_key("final"), "final_output")+ self.assertEqual(sb.pass_job_key("final"), "final_job_id")+ # An unknown pass name must not silently mean "final".+ self.assertEqual(sb.pass_output_key("nonsense"), "draft_output")++ def test_default_pass_is_draft_for_every_old_caller(self):+ self.assertEqual([s["n"] for s in sb.shooting_order(self._drafted())], [])+++class Estimate(unittest.TestCase):+ def test_h3_is_not_priced_as_ltx(self):+ h3 = _board([_shot(1, engine="h3", duration_s=5)])+ ltx = _board([_shot(1, engine="ltx", duration_s=5)])+ h3["policy"]["final"]["quality"] = "standard"+ ltx["policy"]["final"]["quality"] = "standard"+ e_h3 = sb.estimate(h3)["render_secs"]+ e_ltx = sb.estimate(ltx)["render_secs"]+ self.assertGreater(e_h3, e_ltx * 1.8, "H3 was under-reported by ~2x before this")++ def test_the_panels_measured_hook_wins(self):+ board = _board([_shot(1, engine="h3", duration_s=5)])+ seen = []++ def cost(q, ln):+ seen.append((q, ln))+ return 510.0 # 8.5 min, the measured high_5s turbo cell++ est = sb.estimate(board, h3_cost=cost)+ self.assertEqual(est["render_secs"], 510)+ self.assertEqual(seen, [("standard", "5s")]) # final pass default is "balanced"++ def test_h3_bucket_is_not_charged_a_pipeline_load(self):+ # An H3 job spawns its own process and loads its own weights every time; that cost is+ # already inside the measured per-clip eta.+ board = _board([_shot(1, engine="h3")])+ est = sb.estimate(board, h3_cost=lambda q, ln: 100.0)+ self.assertEqual(est["total_secs"], 100)++ def test_ltx_bucket_is_charged_once(self):+ board = _board([_shot(1, engine="ltx", duration_s=5), _shot(2, engine="ltx", duration_s=5)])+ board["policy"]["final"]["quality"] = "quick" # 24 s per video-second+ est = sb.estimate(board)+ self.assertEqual(est["render_secs"], 240)+ self.assertEqual(est["total_secs"], 240 + 90)++ def test_engine_mix_and_buckets_are_reported(self):+ board = _board([_shot(1, engine="h3"), _shot(2, engine="ltx")])+ est = sb.estimate(board)+ self.assertEqual(est["engine_mix"], {"h3": 1, "ltx": 1})+ self.assertEqual([b["engine"] for b in est["buckets"]], ["h3", "ltx"])+ self.assertEqual(est["buckets"][0]["shots"], [1])++ def test_per_shot_estimate_covers_every_shot(self):+ board = _board([_shot(1), _shot(2), _shot(3)])+ per = sb.per_shot_estimate(board, pass_name="draft")+ self.assertEqual(sorted(per.keys()), ["1", "2", "3"])+ self.assertTrue(all(v > 0 for v in per.values()))+++class ValidatorSplit(unittest.TestCase):+ """The messages must stay byte-identical — the whole point of the split."""++ def _cases(self):+ good = _board([_shot(1, mode="character", character_id="bizarrotrn",+ trigger="bizarrotrn", prompt="bizarrotrn walks")])+ yield "clean", good, {}+ yield "schema", _board([_shot(1)], schema=2), {}+ yield "no_id", _board([_shot(1)], id=""), {}+ yield "no_shots", _board([]), {}+ yield "not_object", _board(["nope"]), {}+ bad_n = _shot(1); bad_n["n"] = "x"+ yield "bad_n", _board([bad_n]), {}+ yield "dupe_n", _board([_shot(1), _shot(1)]), {}+ yield "bad_mode", _board([_shot(1, mode="montage")]), {}+ yield "empty_prompt", _board([_shot(1, prompt=" ")]), {}+ yield ("unknown_char",+ _board([_shot(1, character_id="ariatrn", trigger="ariatrn",+ prompt="ariatrn walks")]),+ {"known_character_ids": ["bizarrotrn"]})+ yield ("missing_trigger",+ _board([_shot(1, character_id="bizarrotrn", trigger="bizarrotrn")]),+ {"known_character_ids": ["bizarrotrn"]})+ yield "char_no_id", _board([_shot(1, mode="character")]), {}+ yield "bad_dur", _board([_shot(1, duration_s=90)]), {}+ yield "refs_not_list", _board([_shot(1, refs="x.png")]), {}+ yield "ref_missing", _board([_shot(1, refs=["/nope/desert.png"])]), {}+ yield "remix_no_ref", _board([_shot(1, mode="remix")]), {}+ yield "over_cap", _board([_shot(1)]), {"max_dim": 512}++ def test_detail_and_flat_agree_byte_for_byte(self):+ for name, board, kw in self._cases():+ flat = sb.validate_storyboard(board, **kw)+ detail = sb.validate_storyboard_detail(board, **kw)+ self.assertEqual(flat, [e["message"] for e in detail], name)++ def test_every_case_produces_the_expected_code(self):+ want = {+ "clean": [], "schema": ["schema_version"], "no_id": ["board_id_empty"],+ "no_shots": ["no_shots"], "not_object": ["shot_not_object"],+ "bad_n": ["shot_number"], "dupe_n": ["shot_duplicate"],+ "bad_mode": ["bad_mode"], "empty_prompt": ["empty_prompt"],+ "unknown_char": ["unknown_character"], "missing_trigger": ["missing_trigger"],+ "char_no_id": ["character_without_id"], "bad_dur": ["bad_duration"],+ "refs_not_list": ["refs_not_list"], "ref_missing": ["ref_missing"],+ "remix_no_ref": ["remix_needs_ref"],+ "over_cap": ["over_cap", "over_cap"],+ }+ for name, board, kw in self._cases():+ codes = [e["code"] for e in sb.validate_storyboard_detail(board, **kw)]+ self.assertEqual(codes, want[name], f"{name}: {codes}")++ def test_all_sixteen_codes_are_reachable(self):+ seen = set()+ for _, board, kw in self._cases():+ seen |= {e["code"] for e in sb.validate_storyboard_detail(board, **kw)}+ self.assertEqual(len(seen), 16, sorted(seen))++ def test_a_non_dict_shot_does_not_raise(self):+ # It used to: `where` was computed from s.get() before the isinstance check.+ errs = sb.validate_storyboard_detail(_board([{"n": 1}, "nope"]))+ self.assertIn("shot 2: not an object", [e["message"] for e in errs])++ def test_detail_entries_carry_the_shot_number(self):+ errs = sb.validate_storyboard_detail(_board([_shot(1), _shot(2, prompt="")]))+ empty = [e for e in errs if e["code"] == "empty_prompt"]+ self.assertEqual(len(empty), 1)+ self.assertEqual(empty[0]["n"], 2)+ self.assertEqual(empty[0]["field"], "prompt")++ def test_unknown_character_carries_the_installed_list(self):+ errs = sb.validate_storyboard_detail(+ _board([_shot(1, character_id="ariatrn", trigger="ariatrn",+ prompt="ariatrn walks")]),+ known_character_ids=["bizarrotrn"])+ self.assertEqual(errs[0]["data"]["have"], ["bizarrotrn"])+++class Persistence(unittest.TestCase):+ def test_round_trip(self):+ with tempfile.TemporaryDirectory() as d:+ board = _board([_shot(1)])+ sb.save_storyboard(Path(d), board)+ got = sb.load_storyboard(Path(d), "sb_test")+ self.assertEqual(got["shots"][0]["n"], 1)+ rows = sb.list_storyboards(Path(d))+ self.assertEqual(rows[0]["id"], "sb_test")+ self.assertEqual(rows[0]["shots"], 1)++ def test_additive_fields_survive_and_do_not_invalidate(self):+ board = _board([_shot(1, grade="keep", note="more light", draft_job_id="j-1")],+ concept="a film", style="16mm", must=["the beam"], shots_target=6,+ planner={"state": "done", "stage": "unload"})+ self.assertEqual(sb.validate_storyboard(board), [])+ with tempfile.TemporaryDirectory() as d:+ sb.save_storyboard(Path(d), board)+ got = json.loads((Path(d) / "storyboards" / "sb_test" / "storyboard.json")+ .read_text())+ self.assertEqual(got["concept"], "a film")+ self.assertEqual(got["shots"][0]["grade"], "keep")+ self.assertEqual(got["schema"], 1) # never bumped for additive fields+++if __name__ == "__main__":+ unittest.main()diff --git a/test_storyboard_planner.py b/test_storyboard_planner.pynew file mode 100644index 0000000..f076067--- /dev/null+++ b/test_storyboard_planner.py@@ -0,0 +1,809 @@+#!/usr/bin/env python3+"""Tests for storyboard_planner.py.++Two layers, deliberately separated:++ * The STUB layer (default, no GPU, no weights, runs anywhere in <1 s) drives the whole+ extraction / coercion / repair / validation pipeline through a fake PlannerSession that+ replays canned model output. Every ugly thing a 4-bit 12B has actually been observed to+ do — fenced JSON, prose around the object, a whole three-field prompt pasted into one+ key, a bad character name, an out-of-range duration, truncation mid-object — is a test+ case here rather than a surprise in front of a user.++ * The LIVE layer (opt-in) loads the real planner model, plans a fixed 6-shot concept,+ asserts it validates, and prints the measured plan-phase RSS. It is skipped unless+ PLANNER_LIVE=1 so `python3 -m unittest test_storyboard_planner` stays instant on a+ machine with no weights.++ PLANNER_LIVE=1 python3.11 -m unittest test_storyboard_planner -v+"""++from __future__ import annotations++import copy+import re+import json+import os+import sys+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parent+if str(ROOT) not in sys.path:+ sys.path.insert(0, str(ROOT))++import storyboard # noqa: E402+import storyboard_planner as P # noqa: E402+++# --------------------------------------------------------------------------------------+# Stub model+# --------------------------------------------------------------------------------------++class StubSession(object):+ """Stands in for PlannerSession. Replays canned replies, records what it was asked."""++ def __init__(self, replies):+ self.replies = list(replies)+ self.calls = []+ self.model_path = Path("stub-model")+ self.stats = {"model_path": "stub-model", "load_s": 0.0, "calls": 0,+ "gen_s_total": 0.0, "prompt_tokens": 0, "output_tokens": 0,+ "peak_rss_bytes": 0, "mx_peak_bytes": 0, "released": False}+ self.released = False++ def generate(self, system, user, **kw):+ self.calls.append({"system": system, "user": user, "kw": kw})+ self.stats["calls"] += 1+ if not self.replies:+ raise AssertionError("stub ran out of replies after %d calls" % len(self.calls))+ nxt = self.replies.pop(0)+ if isinstance(nxt, Exception):+ raise nxt+ return {"text": nxt, "load_s": 0.0, "gen_s": 0.0,+ "prompt_tokens": 10, "output_tokens": 10,+ "peak_rss_bytes": 0, "mx_peak_bytes": 0}++ def release(self):+ self.released = True+ self.stats["released"] = True+ return self.stats++ unload = release+++def _shot(n, desc=None, **kw):+ """One shot in the shape the model is asked for: description WITHOUT the camera+ sentence and WITHOUT the ending — those are the `camera` and `settle` keys."""+ d = {+ "n": n,+ "title": "Beat %d" % n,+ "character_id": None,+ "duration_s": 5,+ "camera": "static",+ "description": desc or (+ "Live-action, cinematic, a close-up of a brass key lying on a wet stone step. "+ "Rain beads on the metal and one drop runs off the bow of the key."),+ "settle": "the key lies still and wet",+ "soundscape": "Steady rain on stone, a distant gutter running, no voices.",+ "music": "N/A",+ }+ d.update(kw)+ return d+++def _plan_json(n=6, **kw):+ return json.dumps({"title": "The Key", "shots": [_shot(i + 1, **kw) for i in range(n)]})+++class _StubFactory(object):+ """Replaces PlannerSession so plan_film() OWNS the stub — which means the release+ path under test is the same one production takes."""++ def __init__(self, stub):+ self.stub = stub++ def __call__(self, **kw):+ return self.stub+++def _plan(replies, **kw):+ """plan_film() against a stub, with the arguments the panel would pass.++ The stub is installed as the PlannerSession class rather than handed in as+ `session=`, so plan_film() owns it and its `finally:` release is exercised.+ """+ stub = StubSession(replies)+ kw.setdefault("concept", "a lost brass key finds its door")+ kw.setdefault("n_shots", 6)+ concept = kw.pop("concept")+ real = P.PlannerSession+ P.PlannerSession = _StubFactory(stub)+ try:+ out = P.plan_film(concept, **kw)+ finally:+ P.PlannerSession = real+ return out, stub+++# --------------------------------------------------------------------------------------++class TestJSONExtraction(unittest.TestCase):+ def test_clean_object(self):+ self.assertEqual(P.extract_json_object('{"title":"x","shots":[]}')["title"], "x")++ def test_fenced(self):+ raw = "Sure!\n```json\n{\"title\":\"x\",\"shots\":[]}\n```\nLet me know."+ self.assertEqual(P.extract_json_object(raw)["title"], "x")++ def test_bare_fence_and_trailing_prose(self):+ raw = "```\n{\"title\":\"y\",\"shots\":[]}\n```\n\nHope that helps!"+ self.assertEqual(P.extract_json_object(raw)["title"], "y")++ def test_prose_before_and_after_unfenced(self):+ raw = 'Here is the plan:\n{"title":"z","shots":[{"n":1}]}\nWant changes?'+ self.assertEqual(P.extract_json_object(raw)["title"], "z")++ def test_think_block_is_ignored(self):+ raw = '<think>{"title":"WRONG","shots":[]}</think>{"title":"right","shots":[]}'+ self.assertEqual(P.extract_json_object(raw)["title"], "right")++ def test_trailing_commas_and_smart_quotes(self):+ raw = '{“title”: “q”, “shots”: [1,2,],}'+ self.assertEqual(P.extract_json_object(raw)["title"], "q")++ def test_object_wrapped_in_list(self):+ self.assertEqual(P.extract_json_object('[{"title":"L","shots":[]}]')["title"], "L")++ def test_truncated_output_is_rescued(self):+ raw = '{"title":"T","shots":[{"n":1,"description":"a key on a step'+ got = P.extract_json_object(raw)+ self.assertIsNotNone(got)+ self.assertEqual(got["title"], "T")++ def test_braces_inside_strings_do_not_confuse_the_scanner(self):+ raw = '{"title":"a { brace } inside","shots":[]}'+ self.assertEqual(P.extract_json_object(raw)["title"], "a { brace } inside")++ def test_no_json_at_all(self):+ self.assertIsNone(P.extract_json_object("I'm sorry, I can't help with that."))+++class TestThreeFieldSplit(unittest.TestCase):+ def test_pasted_assembled_prompt_is_taken_apart(self):+ blob = ("integrated_multimodal_description: [Shot 1] Live-action, cinematic, a key.\n\n"+ "overall_soundscape: Rain on stone.\n\n"+ "non_diegetic_music: N/A")+ d, s, m = P._split_three_fields(blob)+ self.assertTrue(d.startswith("[Shot 1] Live-action"))+ self.assertEqual(s, "Rain on stone.")+ self.assertEqual(m, "N/A")+ self.assertNotIn("overall_soundscape", d)+ self.assertNotIn("non_diegetic_music", d)++ def test_plain_description_passes_through(self):+ d, s, m = P._split_three_fields("Live-action, cinematic, a key.")+ self.assertEqual(d, "Live-action, cinematic, a key.")+ self.assertEqual((s, m), ("", ""))+++class TestCoercion(unittest.TestCase):+ def setUp(self):+ self.kw = dict(concept="a lost brass key", n_shots=3, storyboard_mod=storyboard)++ def test_assembles_the_h3_three_field_dialect(self):+ spec, _ = P.coerce_spec(json.loads(_plan_json(3)), **self.kw)+ p = spec["shots"][0]["prompt"]+ self.assertTrue(p.startswith("integrated_multimodal_description: [Shot 1] "))+ self.assertIn("\n\noverall_soundscape: ", p)+ self.assertIn("\n\nnon_diegetic_music: ", p)+ self.assertEqual(spec["shots"][0]["engine"], "h3")+ self.assertEqual(spec["shots"][0]["tier"], "draft")++ def test_shot_marker_is_never_doubled(self):+ raw = json.loads(_plan_json(1))+ raw["shots"][0]["description"] = "[Shot 1] Live-action, cinematic, a key."+ spec, _ = P.coerce_spec(raw, **dict(self.kw, n_shots=1))+ self.assertEqual(spec["shots"][0]["prompt"].count("[Shot 1]"), 1)++ def test_renumbers_and_deduplicates_shot_numbers(self):+ raw = {"title": "t", "shots": [_shot(4), _shot(4), _shot(9)]}+ spec, _ = P.coerce_spec(raw, **self.kw)+ self.assertEqual([s["n"] for s in spec["shots"]], [1, 2, 3])++ def test_durations_are_clamped_and_snapped(self):+ raw = {"title": "t", "shots": [_shot(1, duration_s=999), _shot(2, duration_s=-4),+ _shot(3, duration_s="8")]}+ spec, _ = P.coerce_spec(raw, **self.kw)+ got = [s["duration_s"] for s in spec["shots"]]+ self.assertEqual(got, [15.0, 5.0, 10.0])+ for d in got:+ self.assertTrue(0 < d <= 60)++ def test_seeds_are_assigned_and_deterministic(self):+ a, _ = P.coerce_spec(json.loads(_plan_json(3)), **self.kw)+ b, _ = P.coerce_spec(json.loads(_plan_json(3)), **self.kw)+ self.assertEqual([s["seed"] for s in a["shots"]], [s["seed"] for s in b["shots"]])+ self.assertEqual(len({s["seed"] for s in a["shots"]}), 3)++ def test_character_shot_gets_ltx_engine_mode_and_trigger(self):+ raw = {"title": "t", "shots": [_shot(1, character_id="bizarrotrn")]}+ spec, _ = P.coerce_spec(raw, cast=P._normalise_cast(["bizarrotrn"]),+ **dict(self.kw, n_shots=1))+ s = spec["shots"][0]+ self.assertEqual(s["engine"], "ltx")+ self.assertEqual(s["mode"], "character")+ self.assertEqual(s["character_id"], "bizarrotrn")+ self.assertIn("bizarrotrn", s["prompt"])+ self.assertNotIn("integrated_multimodal_description", s["prompt"])+ self.assertEqual(spec["cast"][0]["id"], "bizarrotrn")++ def test_unknown_character_is_dropped_not_passed_to_the_validator(self):+ raw = {"title": "t", "shots": [_shot(1, character_id="someone_who_does_not_exist")]}+ spec, warns = P.coerce_spec(raw, cast=P._normalise_cast(["bizarrotrn"]),+ **dict(self.kw, n_shots=1))+ self.assertIsNone(spec["shots"][0].get("character_id"))+ self.assertEqual(spec["shots"][0]["mode"], "text")+ self.assertTrue(any("unknown character" in w for w in warns))++ def test_ltx_register_strips_h3_markup(self):+ raw = {"title": "t", "shots": [_shot(+ 1, character_id="bizarrotrn",+ description="[Shot 1] A man on a step. He (S1) says: <d>[English] Found it.</d>")]}+ spec, _ = P.coerce_spec(raw, cast=P._normalise_cast(["bizarrotrn"]),+ style="documentary realism, no letterbox",+ **dict(self.kw, n_shots=1))+ p = spec["shots"][0]["prompt"]+ for junk in ("<d>", "</d>", "[Shot 1]", "(S1)"):+ self.assertNotIn(junk, p)+ self.assertIn("'Found it.'", p)+ self.assertIn("documentary realism, no letterbox", p)+ self.assertIn("Audio:", p)++ def test_camera_choice_becomes_a_canonical_camera_sentence(self):+ raw = {"title": "t", "shots": [_shot(1, camera="push_in", description="A key."),+ _shot(2, camera="nonsense", description="A door."),+ _shot(3, camera="dolly_in", description="A step.")]}+ spec, _ = P.coerce_spec(raw, **self.kw)+ self.assertIn("pushes in with small amplitude at slow speed", spec["shots"][0]["prompt"])+ self.assertIn("holds a static shot", spec["shots"][1]["prompt"]) # unknown -> static+ self.assertIn("pushes in with small amplitude", spec["shots"][2]["prompt"]) # alias++ def test_stored_camera_is_the_key_that_actually_rendered(self):+ # Observed: the model answered the `face` enum in the `camera` slot, and the shot+ # card then read `cam=medium` while the prompt said "holds a static shot".+ raw = {"title": "t", "shots": [_shot(1, camera="medium"), _shot(2, camera="dolly_in")]}+ spec, warns = P.coerce_spec(raw, **dict(self.kw, n_shots=2))+ self.assertEqual([s["camera"] for s in spec["shots"]], ["static", "push_in"])+ self.assertIn("holds a static shot", spec["shots"][0]["prompt"])+ self.assertTrue(any("not one of" in w for w in warns), warns)+ for s in spec["shots"]:+ self.assertIn(s["camera"], P.CAMERA_KEYS)++ def test_a_camera_sentence_the_model_wrote_is_not_duplicated(self):+ raw = {"title": "t", "shots": [_shot(+ 1, camera="push_in",+ description="A key. The camera holds a static shot and never moves.")]}+ spec, _ = P.coerce_spec(raw, **dict(self.kw, n_shots=1))+ self.assertEqual(spec["shots"][0]["prompt"].lower().count("the camera"), 1)++ def test_settle_phrase_becomes_the_end_state_law(self):+ raw = {"title": "t", "shots": [_shot(1, description="A key.",+ settle="the key lies still and wet")]}+ spec, _ = P.coerce_spec(raw, **dict(self.kw, n_shots=1))+ p = spec["shots"][0]["prompt"]+ self.assertIn("completely finished before the shot ends", p)+ self.assertIn("for the last two seconds the key lies still and wet", p)++ def test_face_law_is_added_only_when_a_person_is_in_the_shot(self):+ raw = {"title": "t", "shots": [+ _shot(1, description="Live-action, cinematic, a woman on a step."),+ _shot(2, description="Live-action, cinematic, an empty steel dumpster.")]}+ spec, _ = P.coerce_spec(raw, **dict(self.kw, n_shots=2))+ self.assertIn("holds the exact angle to the lens", spec["shots"][0]["prompt"])+ self.assertNotIn("holds the exact angle to the lens", spec["shots"][1]["prompt"])++ # --- the face law -------------------------------------------------------------+ # Faces are the quality metric. A live plan wrote "his face obscured by the angle" and+ # the render put the head half out of frame; a sweep of 56 shots found 5 face-hiding+ # phrases, mostly "silhouetted against the ..." on the final shot.++ def test_face_level_renders_the_right_law(self):+ raw = {"title": "t", "shots": [+ _shot(1, face="close", description="A close-up of a boxer's face."),+ _shot(2, face="medium", description="A woman at a workbench."),+ _shot(3, face="none", description="An empty steel dumpster.")]}+ spec, _ = P.coerce_spec(raw, **dict(self.kw, n_shots=3))+ self.assertIn("The face fills much of the frame", spec["shots"][0]["prompt"])+ self.assertIn("holds the exact angle to the lens", spec["shots"][1]["prompt"])+ self.assertNotIn("fills much of the frame", spec["shots"][1]["prompt"])+ self.assertNotIn("holds the exact angle", spec["shots"][2]["prompt"])+ self.assertEqual([s["face"] for s in spec["shots"]], ["close", "medium", "none"])++ def test_face_level_defaults_from_whether_a_person_is_on_screen(self):+ raw = {"title": "t", "shots": [+ _shot(1, face=None, description="Live-action, cinematic, a woman on a step."),+ _shot(2, face=None, description="Live-action, cinematic, an empty dumpster.")]}+ spec, _ = P.coerce_spec(raw, **dict(self.kw, n_shots=2))+ self.assertEqual([s["face"] for s in spec["shots"]], ["medium", "none"])++ def test_face_none_cannot_switch_off_the_law_when_a_person_is_present(self):+ """The escape that shipped a silhouette: the model labelled a wide shot containing a+ woman `face: "none"`, which disabled the scrub."""+ raw = {"title": "t", "shots": [+ _shot(1, face="none",+ description=("Live-action, cinematic, a wide shot from the rooftop showing "+ "the woman standing beside the neon sign, silhouetted against "+ "the vibrant lights of the market below."),+ settle="the market glows below and she stands silhouetted against the lights"),+ _shot(2, face="none", description="Live-action, cinematic, an empty rooftop.")]}+ spec, warns = P.coerce_spec(raw, **dict(self.kw, n_shots=2))+ self.assertEqual(spec["shots"][0]["face"], "medium")+ self.assertEqual(spec["shots"][1]["face"], "none") # genuinely no person: honoured+ body = spec["shots"][0]["prompt"].replace(P._FACE_LAW_MEDIUM, " ")+ self.assertNotIn("silhouetted", body)+ self.assertTrue(any("said no face" in w for w in warns), warns)++ def test_person_silhouette_regex_catches_the_forms_that_shipped(self):+ for blocking in ("silhouetted against the vibrant lights of the market below",+ "and she stands silhouetted against the lights",+ "He's silhouetted against the bright light of the lens",+ "her silhouette framed against the backdrop of the city lights",+ "they stood silhouetted in the doorway"):+ self.assertTrue(P._PERSON_SILHOUETTE_RE.search(blocking), blocking)+ for fine in ("the dune line behind him is a clean dark silhouette against a pale sky",+ "the lighthouse stands silhouetted against the night sky",+ "the crane is a hard silhouette on the skyline"):+ self.assertFalse(P._PERSON_SILHOUETTE_RE.search(fine), fine)++ def test_hidden_faces_are_refused_unless_the_brief_asked(self):+ raw = {"title": "t", "shots": [_shot(1, face="hidden",+ description="A woman on a rooftop.")]}+ spec, warns = P.coerce_spec(raw, **dict(self.kw, n_shots=1))+ self.assertEqual(spec["shots"][0]["face"], "medium")+ self.assertIn("holds the exact angle", spec["shots"][0]["prompt"])+ self.assertTrue(any("kept visible" in w for w in warns), warns)++ def test_hidden_faces_are_allowed_when_the_brief_asked(self):+ raw = {"title": "t", "shots": [_shot(1, face="hidden",+ description="A woman on a rooftop.")]}+ spec, warns = P.coerce_spec(raw, allow_hidden_faces=True, **dict(self.kw, n_shots=1))+ self.assertEqual(spec["shots"][0]["face"], "hidden")+ self.assertNotIn("holds the exact angle", spec["shots"][0]["prompt"])+ self.assertEqual([w for w in warns if "kept visible" in w], [])++ def test_face_blocking_prose_is_scrubbed_out(self):+ # Every one of these is verbatim from a real plan, or the reported defect.+ raw = {"title": "t", "shots": [+ _shot(1, description=("Live-action, cinematic, a close-up of a boxer on a stool, "+ "his face obscured by the angle, sweat on his shoulders. "+ "He breathes out slowly.")),+ _shot(2, description=("Live-action, cinematic, a wide shot of the keeper at the "+ "window. He stands very still."),+ settle=("he is standing at the window, silhouetted against the setting "+ "sun, watching the light sweep out")),+ _shot(3, description=("Live-action, cinematic, a medium shot of a woman on a "+ "rooftop, her silhouette framed against the city lights. "+ "She sets down her tools.")),+ _shot(4, description=("Live-action, cinematic, a violinist seen from behind, "+ "her bow arm rising. She draws one long note."))]}+ spec, warns = P.coerce_spec(raw, **dict(self.kw, n_shots=4))+ joined = " ".join(s["prompt"] for s in spec["shots"])+ for banned in ("obscured", "silhouetted against", "her silhouette", "seen from behind"):+ self.assertNotIn(banned, joined, "%r survived the scrub" % banned)+ # The rest of each direction survives — this is a clause scrub, not a shot delete.+ self.assertEqual(len(spec["shots"]), 4)+ self.assertIn("sweat on his shoulders", spec["shots"][0]["prompt"])+ self.assertIn("watching the light sweep out", spec["shots"][1]["prompt"])+ self.assertIn("She sets down her tools", spec["shots"][2]["prompt"])+ self.assertIn("her bow arm rising", spec["shots"][3]["prompt"])+ self.assertEqual(len([w for w in warns if "face-hiding framing" in w]), 4, warns)++ def test_scrub_leaves_legitimate_non_person_silhouettes_alone(self):+ # From the C1 exemplar: a landscape silhouette is good cinematography, not a+ # hidden face. Same for a face half in shadow.+ desc = ("Live-action, cinematic, a medium close-up of a man on a dune ridge. Hard "+ "low sun rakes from camera left, carving one bright edge down his cheekbone "+ "while the other side of his face falls into open shadow; the dune line "+ "behind him is a clean dark silhouette against a pale sky.")+ out, removed = P._scrub_face_blocking(desc)+ self.assertEqual(removed, [])+ self.assertIn("clean dark silhouette against a pale sky", out)+ self.assertIn("falls into open shadow", out)++ def test_scrub_does_not_fire_on_ordinary_behind(self):+ desc = "A daughter stands behind her mother, the crowd close behind him."+ out, removed = P._scrub_face_blocking(desc)+ self.assertEqual(removed, [])+ self.assertEqual(out, desc)++ def test_brief_detection_for_hidden_faces(self):+ for yes in ("a film told entirely in silhouette",+ "we only ever see her from behind",+ "a faceless narrator",+ "shot without showing his face"):+ self.assertTrue(P._WANTS_HIDDEN_RE.search(yes), yes)+ for no in ("a boxer between rounds, close on the face",+ "a lighthouse keeper on his last night",+ "the dune line behind him is a dark shape"):+ self.assertFalse(P._WANTS_HIDDEN_RE.search(no), no)++ def test_curly_punctuation_is_normalised_out_of_the_prompt(self):+ raw = {"title": "t", "shots": [_shot(+ 1, description="A key — he says “you’ve got it”…",+ soundscape="Rain — steady.")]}+ spec, _ = P.coerce_spec(raw, **dict(self.kw, n_shots=1))+ p = spec["shots"][0]["prompt"]+ for ch in ("’", "“", "”", "—", "…"):+ self.assertNotIn(ch, p)++ def test_no_text_clause_is_omitted_when_typography_was_requested(self):+ raw = {"title": "t", "shots": [+ _shot(1, description='A wall where the word "PHOSPHENE" burns in.'),+ _shot(2, description="A plain wall."),+ # Observed failure: the model used single quotes and the refusal landed on a+ # title sequence whose whole point was the lettering.+ _shot(3, description="Mercury coalescing into the letter 'P' on black glass."),+ _shot(4, description="The mercury's surface stays perfectly smooth.")]}+ spec, warns = P.coerce_spec(raw, **dict(self.kw, n_shots=4))+ self.assertNotIn("No text appears", spec["shots"][0]["prompt"])+ self.assertIn("No text appears", spec["shots"][1]["prompt"])+ self.assertNotIn("No text appears", spec["shots"][2]["prompt"])+ # An apostrophe is not a quoted string.+ self.assertIn("No text appears", spec["shots"][3]["prompt"])+ self.assertTrue(any("double quotes" in w for w in warns), warns)++ def test_typography_detector_does_not_fire_on_dialogue_or_props(self):+ # Both were real false positives: single-quoted LTX dialogue, and "neon sign" —+ # where the refusal is exactly what the shot needs.+ dialogue = ("A man at a workbench. He says, 'Everything has a story, you know. "+ "And a purpose. Even if it's broken.'")+ neon = "A woman repairing a large crimson neon sign on a rooftop."+ self.assertEqual(P._typography_strings(dialogue), [])+ self.assertEqual(P._typography_strings(neon), [])+ self.assertEqual(P._typography_strings("the word \"PHOSPHENE\" burns in"),+ ["PHOSPHENE"])+ self.assertEqual(P._typography_strings("the letter 'P' forms"), ["P"])+ spec, warns = P.coerce_spec(+ {"title": "t", "shots": [_shot(1, description=dialogue), _shot(2, description=neon)]},+ **dict(self.kw, n_shots=2))+ for s in spec["shots"]:+ self.assertIn("No text appears", s["prompt"])+ self.assertEqual([w for w in warns if "double quotes" in w], [])++ def test_camera_talk_is_stripped_out_of_the_settle_clause(self):+ raw = {"title": "t", "shots": [+ _shot(1, settle="the camera stops orbiting, the lens keeps turning silently"),+ _shot(2, settle="the camera holds on the scene")]}+ spec, warns = P.coerce_spec(raw, **dict(self.kw, n_shots=2))+ p1, p2 = spec["shots"][0]["prompt"], spec["shots"][1]["prompt"]+ self.assertIn("for the last two seconds the lens keeps turning silently", p1)+ self.assertNotIn("the camera stops orbiting", p1)+ # Nothing but camera talk -> no settle clause at all, rather than a contradiction.+ self.assertNotIn("completely finished before the shot ends", p2)+ self.assertTrue(any("instead of an end state" in w for w in warns), warns)++ def test_camera_monoculture_is_reported_as_a_warning(self):+ raw = {"title": "t", "shots": [_shot(i + 1, camera="static", settle="it is still")+ for i in range(4)]}+ _, warns = P.coerce_spec(raw, **dict(self.kw, n_shots=4))+ self.assertTrue(any("same camera behaviour" in w for w in warns), warns)++ def test_missing_end_states_are_reported_as_a_warning(self):+ raw = {"title": "t", "shots": [_shot(i + 1, settle="") for i in range(4)]}+ _, warns = P.coerce_spec(raw, **dict(self.kw, n_shots=4))+ self.assertTrue(any("no shot named an end state" in w for w in warns), warns)++ def test_unbalanced_dialogue_tag_is_closed(self):+ raw = {"title": "t", "shots": [_shot(1, description="A key. <d>[English] Hello.")]}+ spec, _ = P.coerce_spec(raw, **dict(self.kw, n_shots=1))+ p = spec["shots"][0]["prompt"]+ self.assertEqual(p.count("<d>"), p.count("</d>"))++ def test_empty_description_shot_is_dropped(self):+ raw = {"title": "t", "shots": [_shot(1), _shot(2, description=""), _shot(3)]}+ spec, warns = P.coerce_spec(raw, **self.kw)+ self.assertEqual(len(spec["shots"]), 2)+ self.assertTrue(any("empty description" in w for w in warns))++ def test_policy_is_clamped_to_the_machine_cap(self):+ spec, _ = P.coerce_spec(json.loads(_plan_json(3)), max_dim=768, **self.kw)+ for key in ("draft", "final"):+ p = spec["policy"][key]+ self.assertLessEqual(max(p["width"], p["height"]), 768)++ def test_garbage_input_still_produces_a_legal_envelope(self):+ spec, warns = P.coerce_spec(None, **self.kw)+ self.assertEqual(spec["schema"], storyboard.SCHEMA_VERSION)+ self.assertTrue(spec["id"])+ self.assertEqual(spec["shots"], [])+ self.assertTrue(warns)+++class TestValidatorContract(unittest.TestCase):+ """The point of the module: what comes out passes the REAL validator."""++ def test_stub_plan_validates_clean(self):+ out, stub = _plan([_plan_json(6)])+ self.assertFalse(P.is_plan_error(out), out.get("error"))+ self.assertEqual(storyboard.validate_storyboard(out), [])+ self.assertEqual(len(out["shots"]), 6)+ self.assertTrue(out["_planner"]["first_try_clean"])+ self.assertEqual(out["_planner"]["attempts"], 1)+ self.assertTrue(stub.released)++ def test_plan_survives_a_roundtrip_through_save_and_load(self):+ out, _ = _plan([_plan_json(6)])+ import tempfile+ with tempfile.TemporaryDirectory() as td:+ storyboard.save_storyboard(Path(td), out)+ back = storyboard.load_storyboard(Path(td), out["id"])+ self.assertEqual(storyboard.validate_storyboard(back), [])+ self.assertEqual(back["shots"][0]["prompt"], out["shots"][0]["prompt"])++ def test_plan_translates_to_panel_jobs(self):+ out, _ = _plan([_plan_json(6)])+ shot = out["shots"][0]+ job = storyboard.shot_to_job(shot, out["policy"]["draft"],+ board_id=out["id"], board_title=out["title"])+ self.assertEqual(job["enhance"], "off")+ self.assertTrue(job["prompt"])+ # The PANEL's mode vocabulary, not the storyboard schema's: mlx_ltx_panel has one+ # backend video mode for both of v1's shot types, and "text"/"character" are not it.+ self.assertIn(job["mode"], ("t2v", "i2v", "keyframe", "extend", "a2v"))+ # The engine the planner assigned must survive the translation — this is the seam+ # that used to send every H3 shot to LTX.+ self.assertEqual(job["engine"], shot["engine"])+ self.assertEqual(job["session_tag"], "sb:%s#%d" % (out["id"], shot["n"]))++ def test_character_plan_validates_with_known_ids(self):+ raw = json.dumps({"title": "t", "shots": [+ _shot(1, character_id="bizarrotrn"), _shot(2), _shot(3)]})+ out, _ = _plan([raw], n_shots=3, characters=["bizarrotrn"])+ self.assertFalse(P.is_plan_error(out), out.get("error"))+ self.assertEqual(storyboard.validate_storyboard(+ out, known_character_ids=["bizarrotrn"]), [])+ self.assertEqual(out["_planner"]["engine_mix"], {"ltx": 1, "h3": 2})+++class TestRepairRoundTrip(unittest.TestCase):+ def test_wrong_shot_count_triggers_exactly_one_repair(self):+ out, stub = _plan([_plan_json(4), _plan_json(6)])+ self.assertFalse(P.is_plan_error(out))+ self.assertEqual(len(out["shots"]), 6)+ self.assertEqual(len(stub.calls), 2)+ self.assertEqual(out["_planner"]["attempts"], 2)+ self.assertIn("exactly 6 were requested", stub.calls[1]["user"])++ def test_unparseable_first_reply_is_repaired(self):+ out, stub = _plan(["I cannot do that.", _plan_json(6)])+ self.assertFalse(P.is_plan_error(out))+ self.assertEqual(len(out["shots"]), 6)+ self.assertIn("did not contain a JSON object", stub.calls[1]["user"])++ def test_two_bad_replies_return_a_structured_error_not_a_traceback(self):+ out, stub = _plan(["nope", "still nope"])+ self.assertTrue(P.is_plan_error(out))+ err = out["error"]+ self.assertEqual(err["kind"], "invalid_plan")+ self.assertTrue(err["message"])+ self.assertTrue(err["problems"])+ self.assertNotIn("Traceback", json.dumps(out))+ self.assertEqual(len(stub.calls), 2) # never more than one repair+ self.assertTrue(stub.released)++ def test_a_worse_repair_does_not_replace_a_better_first_draft(self):+ # First draft: 5 shots (count wrong, otherwise valid). Repair: unusable.+ out, _ = _plan([_plan_json(5), "{}"])+ self.assertFalse(P.is_plan_error(out))+ self.assertEqual(len(out["shots"]), 5)+ self.assertFalse(out["_planner"]["shot_count_ok"])++ def test_model_unavailable_is_a_structured_error(self):+ out, _ = _plan([P.PlannerError("planner model not found at /nowhere")])+ self.assertTrue(P.is_plan_error(out))+ self.assertEqual(out["error"]["kind"], "model_unavailable")+ self.assertIn("mlx-lm", out["error"]["hint"])+++class TestFeedback(unittest.TestCase):+ def setUp(self):+ self.base, _ = _plan([_plan_json(6)])++ def test_feedback_string_is_parsed_into_a_shot_reroll(self):+ self.assertEqual(P._parse_feedback("shot 4: he should not turn his head"),+ ("shot", 4, "he should not turn his head"))+ self.assertEqual(P._parse_feedback({"shot": 2, "note": "colder"}),+ ("shot", 2, "colder"))+ self.assertEqual(P._parse_feedback("make it colder")[0], "film")+ self.assertEqual(P._parse_feedback(None)[0], "none")++ def test_shot_reroll_changes_only_that_shot_and_leaves_the_rest_byte_stable(self):+ before = copy.deepcopy(self.base)+ reply = json.dumps({"title": "The Key", "shots": [_shot(+ 4, description=(+ "Live-action, cinematic, a wide shot of a green door in a brick wall. "+ "The camera holds a static shot, the frame never moves. Rain runs down the "+ "paint and the letterbox flap swings once and stops. The movement is "+ "completely finished before the shot ends, and for the last two seconds the "+ "door is simply shut and streaming, with no new movement of any kind."))]})+ out, _ = _plan([reply], feedback="shot 4: make it a door, not a key",+ previous=before, n_shots=6)+ self.assertFalse(P.is_plan_error(out), out.get("error"))+ self.assertEqual(storyboard.validate_storyboard(out), [])+ self.assertEqual(len(out["shots"]), 6)+ self.assertIn("green door", out["shots"][3]["prompt"])+ self.assertEqual(out["shots"][3]["n"], 4)+ for i in (0, 1, 2, 4, 5):+ self.assertEqual(json.dumps(out["shots"][i], sort_keys=True),+ json.dumps(before["shots"][i], sort_keys=True),+ "shot %d drifted during a per-shot re-roll" % (i + 1))++ def test_shot_reroll_prompt_carries_the_neighbours_but_asks_for_one_shot(self):+ _, stub = _plan([json.dumps({"title": "T", "shots": [_shot(4)]})],+ feedback={"shot": 4, "note": "colder"},+ previous=copy.deepcopy(self.base), n_shots=6)+ user = stub.calls[0]["user"]+ self.assertIn("re-rolling ONE shot", user)+ self.assertIn("n=4", user)+ self.assertIn("One shot only", user)++ def test_film_feedback_replans_everything(self):+ _, stub = _plan([_plan_json(6)], feedback="make it colder and drop the voiceover",+ previous=copy.deepcopy(self.base), n_shots=6)+ user = stub.calls[0]["user"]+ self.assertIn("DIRECTOR'S NOTES", user)+ self.assertIn("make it colder", user)++ def test_feedback_without_previous_is_a_programmer_error(self):+ with self.assertRaises(P.PlannerError):+ _plan([_plan_json(6)], feedback="shot 2: colder")+++class TestPromptContent(unittest.TestCase):+ """The prompt IS the product. If a law silently falls out, a test should notice."""++ def test_system_prompt_carries_the_laws_and_the_dialect(self):+ sys_p = P._build_system_prompt("auto", False)+ for needle in ("integrated_multimodal_description", "overall_soundscape",+ "non_diegetic_music", "<d>[English]", "holds a static shot",+ "completely finished before the shot ends", "no negative prompt",+ "Heads stay square to the lens", "VARIETY IS A HARD REQUIREMENT"):+ self.assertIn(needle, sys_p, "missing from the system prompt: %r" % needle)++ def test_contract_lists_every_camera_key_the_coercer_accepts(self):+ sys_p = P._build_system_prompt("auto", False)+ for key in P.CAMERA_KEYS:+ self.assertIn(key, sys_p, "camera %r is legal but never offered to the model" % key)++ def test_face_law_is_in_the_prompt_and_hidden_is_not_offered_by_default(self):+ sys_p = P._build_system_prompt("auto", False)+ self.assertIn("L11 THE FACE IS THE WHOLE POINT", sys_p)+ self.assertIn('"face" ONE of: close, medium, none.', sys_p)+ self.assertIn("There is no fourth option", sys_p)+ self.assertNotIn('you may use "hidden"', sys_p)+ relaxed = P._build_system_prompt("auto", False, allow_hidden=True)+ self.assertIn('you may use "hidden"', relaxed)++ def test_no_exemplar_teaches_the_model_to_hide_a_face(self):+ """The audit that caught it: the box exemplar used to say 'he tips his face up to+ the sky' and hold it there in the settle — a face aimed away from the lens, taught+ by example. The LTX exemplar sent the eyes off-camera on a talking head."""+ sys_p = P._build_system_prompt("auto", True)+ # Strip L11 itself, which necessarily quotes the phrases it forbids.+ body = sys_p.split("L11 THE FACE IS THE WHOLE POINT")[0]+ for phrase in ("tips his face up", "tipped up", "off-camera", "obscur",+ "from behind", "seen from behind", "back to the camera"):+ self.assertNotIn(phrase, body, "exemplars still teach %r" % phrase)+ self.assertEqual(P._FACE_BLOCK_RE.findall(body), [])+ # Every exemplar declares a face level.+ self.assertEqual(re.findall(r'"face": "(\w+)"', sys_p),+ ["close", "medium", "close", "none", "close"])++ def test_ltx_example_appears_only_when_there_is_a_cast(self):+ self.assertNotIn("letterbox", P._build_system_prompt("auto", False))+ self.assertIn("letterbox", P._build_system_prompt("auto", True))++ def test_forcing_ltx_drops_the_h3_dialect(self):+ sys_p = P._build_system_prompt("ltx", True)+ self.assertNotIn("integrated_multimodal_description:", sys_p.split("EVERY shot")[-1])+ self.assertIn("LTX register", sys_p)++ def test_user_prompt_lists_cast_and_must_include(self):+ u = P._build_user_prompt("a key", 6, "documentary", P._normalise_cast(["bizarrotrn"]),+ ["a green door"])+ self.assertIn("bizarrotrn", u)+ self.assertIn("a green door", u)+ self.assertIn("exactly 6 shots", u)+++class TestMemoryDiscipline(unittest.TestCase):+ def test_release_is_idempotent_and_safe_before_spawn(self):+ s = P.PlannerSession(model_path="/definitely/not/here")+ self.assertTrue(s.release()["released"])+ self.assertTrue(s.release()["released"])++ def test_missing_model_raises_a_planner_error_not_an_oserror(self):+ s = P.PlannerSession(model_path="/definitely/not/here")+ with self.assertRaises(P.PlannerError):+ s.generate("sys", "user")+ s.release()++ def test_context_manager_releases(self):+ s = P.PlannerSession(model_path="/definitely/not/here")+ with s:+ pass+ self.assertTrue(s.stats["released"])++ def test_a_borrowed_session_is_the_callers_to_release(self):+ stub = StubSession([_plan_json(3)])+ out = P.plan_film("a key", n_shots=3, session=stub)+ self.assertFalse(P.is_plan_error(out))+ self.assertFalse(stub.released, "plan_film released a session it does not own")+ stub.release()++ def test_an_owned_session_is_released_even_when_the_model_explodes(self):+ stub = StubSession([RuntimeError("boom")])+ real = P.PlannerSession+ P.PlannerSession = _StubFactory(stub)+ try:+ with self.assertRaises(RuntimeError):+ P.plan_film("a key", n_shots=3)+ finally:+ P.PlannerSession = real+ self.assertTrue(stub.released, "the model survived an exception inside plan_film")++ def test_missing_model_reports_release_in_the_metadata(self):+ out = P.plan_film("a key", n_shots=3, model_path="/definitely/not/here")+ self.assertTrue(P.is_plan_error(out))+ self.assertEqual(out["error"]["kind"], "model_unavailable")+ self.assertTrue(out["_planner"]["model_released"])+++# --------------------------------------------------------------------------------------+# LIVE — real weights. Opt-in.+# --------------------------------------------------------------------------------------++LIVE_CONCEPT = ("A lighthouse keeper on his last night before the light is automated. "+ "He says goodbye to the machine that kept him company for thirty years.")++[email protected](os.environ.get("PLANNER_LIVE") == "1",+ "set PLANNER_LIVE=1 to run against the real planner model")+class TestLivePlanner(unittest.TestCase):+ def test_six_shot_plan_validates_and_the_model_is_released(self):+ if not P.DEFAULT_MODEL_PATH.exists():+ self.skipTest("planner model not on disk: %s" % P.DEFAULT_MODEL_PATH)+ out = P.plan_film(LIVE_CONCEPT, n_shots=6,+ style="Live-action, cinematic, photoreal, heavy 35mm film grain")+ self.assertFalse(P.is_plan_error(out),+ "planner failed: %s" % json.dumps(out.get("error"), indent=2))+ errs = storyboard.validate_storyboard(out)+ self.assertEqual(errs, [], "validator complained: %s" % errs)+ self.assertEqual(len(out["shots"]), 6)++ meta = out["_planner"]+ for s in out["shots"]:+ self.assertTrue(s["prompt"].startswith("integrated_multimodal_description: [Shot 1] "))+ self.assertIn("\n\noverall_soundscape: ", s["prompt"])+ self.assertIn("\n\nnon_diegetic_music: ", s["prompt"])+ self.assertEqual(s["prompt"].count("<d>"), s["prompt"].count("</d>"))+ self.assertEqual(s["tier"], "draft")+ self.assertEqual(s["engine"], "h3")++ # The whole point of the subprocess design.+ self.assertTrue(meta["model_released"])+ self.assertGreater(meta["peak_rss_gb"], 0.5)+ self.assertLess(meta["peak_rss_gb"], 16.0,+ "plan-phase RSS blew past the budget: %s GB" % meta["peak_rss_gb"])++ sys.stderr.write(+ "\n LIVE: model=%s attempts=%d load=%.1fs gen=%.1fs total=%.1fs\n"+ " peak RSS=%.2f GB mlx peak=%.2f GB first-try-clean=%s\n"+ % (meta["model"], meta["attempts"], meta["load_s"] or 0.0, meta["gen_s"] or 0.0,+ meta["elapsed_s"], meta["peak_rss_gb"], meta["mx_peak_gb"],+ meta["first_try_clean"]))+++if __name__ == "__main__":+ unittest.main(verbosity=2)diff --git a/update.js b/update.jsindex e3d9563..643454c 100644--- a/update.js+++ b/update.js@@ -52,24 +52,41 @@ module.exports = {].join("\n")}},- // ltx-2-mlx is PINNED to v0.14.8 (2026-06-01 catch-up from v0.14.0;+ // 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.8 source into site-packages (non-editable),- // so an existing user's runtime actually moves to 0.14.8 — a bare+ // 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 checkout v0.14.8",+ "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",+ "git checkout 871694ddaa09c1598d663a49005a2f91ae6b4ed2","git rev-parse --short HEAD"]}@@ -100,11 +117,38 @@ module.exports = {// trainer subprocess fails at `import yaml` without pyyaml, which// is a transitive dep of ltx-trainer-mlx — installing the local// package brings it cleanly.+ //+ // `--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: "./env/bin/pip install --force-reinstall --no-deps ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer"+ 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"}},// 3.0: pyyaml + pydantic + tqdm + rich are ltx-trainer-mlx's