Skip to content

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.

release(v4.5.0): one health chip, and two fixes that came from outside

mrbizarroee278e03accc
diff --git a/VERSION b/VERSION
index fdc6698..a84947d 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-4.4.0
+4.5.0
diff --git a/docs/STATE.md b/docs/STATE.md
index 97b9a04..57ea665 100644
--- a/docs/STATE.md
+++ b/docs/STATE.md
@@ -1,5 +1,13 @@
# Phosphene — project state, history, open work
+> **🎛️ 2026-08-16 — v4.5.0: the health cluster becomes one chip, and two fixes that came from outside.**
+>
+> - **One health chip.** Six pills truncated on a 14" window and could not take a seventh. The chip states the summary — worst state wins the colour, memory stays on the face — and a portaled popover holds Tier / Memory / Helper / Models / ComfyUI / Queue / Render. The pills are unchanged: same ids, same updaters, relocated once at boot and read back, so the summary can never disagree with them.
+> - **safetensors data now lands 16-byte aligned** — the lead came from tgo-app-dev/vpipe, who measured 39.1 GB of silent copy-instead-of-mmap on a checkpoint whose data began at 8 (mod 16). Metal buffer offsets must be 16-byte aligned and a misaligned section does not error. The obvious fix is backwards: the file is `[8-byte length][blob][data]`, so padding the blob to a multiple of 16 lands data at 8 mod 16 — misaligned EVERY time. Measured across 200 header lengths: old rule 103/200 bad, naive %16 200/200 bad, correct rule 0/200. `test_safetensors_alignment.py` reads the padding expression out of the panel source so it cannot drift.
+> - **The 48 GB generation clamp now respects `LTX_TIER_OVERRIDE`.** Reported on Reddit with the diagnosis already done: `_select_generation_profile()` accepts `tier_key` and never reads it, so a requested 1088x1472 was reshaped to 768x1024 while memory sat at 9.4/48 GB, and forcing the tier moved the modal and nothing else. Their measurement — 12.79 s/it unclamped vs 13.4 s/it clamped, 284 s, no swap, no OOM — is real data from hardware we do not own. An explicit high/pro override now lifts the cap, and `LTX_GENERATION_PROFILE=full` lifts it outright. The 64 GB default STAYS: it was put there by a real swap thrash and one clean result does not retire it.
+>
+> **Gates:** `check_ltx_pin` PASS · `check_pinokio_scripts` PASS · `check_output_codec` PASS · 15 panel suites green · `node -c` install/update.
+
> **🔁 2026-08-15 — v4.4.0: every update since v4.0.5 has silently kept running the old code.** The most important release of the day, and it exists because the owner said "I updated and I still don't see any of the changes."
>
> - **The "Restart to finish update" pill has never fired. Not once.** v4.0.5 compared disk HEAD against `_VERSION_STATE["local_sha"]`, described in its own docstring as *the boot snapshot*. It is not one: `_check_remote_once()` calls `_detect_local_install_state()` at the top of **every poll** — deliberately, so a tree that was dirty at boot and is clean now stops being suppressed without a restart — and that same call refreshes `local_sha`. Within one 30-minute interval `local_sha` equals disk again, so `disk_sha != boot_sha` is false forever. The detector could never report the one condition it exists to report.
@@ -66,7 +74,7 @@
> **🔧 2026-08-14 night — v4.0.5 ASSEMBLED on dev/beta (`65880b3` + version `66f0dbd`), HELD for the owner's word.** The two recovered audits' punch-list, closed in one campaign. (1) **H3 Turbo install is LIVE again**: the v1.0 runner-layout repack is a published release asset on `weights-ltx25-v1` (sha256 `d51d626f…`, verified byte-identical against the local repack the selection was graded on); `/h3/turbo/install` streams it partial→verify→atomic-rename, `install_h3.js` fetches the same asset best-effort via `scripts/fetch_h3_turbo.py` (resumable, digest-checked, short Pinokio-safe lines), and the retired **ckpt500-EMA is accepted again as the LAST fallback** — dropping it in 4.0.4 un-Turboed installs that rendered fine on it. Raw v0.1 stays refused by name. Turbo gate 5→11 tests incl. script↔panel pin parity. (2) **The dead HQ Speed control is gone** (skip-step fields were dropped at the engine boundary; both pills ran identical settings under a "~12% faster" claim), and the collapsed summary stops printing "exact speed" from the retired accel input. (3) **The real speed control**: the engine's 2.5-only `fast` schedule preset (F6S2, 5+2 forwards, owner-graded, **a different take**) wired end to end — Speed pills → `schedule_preset` → make_job (lane-gated: dropped with a sentence on 2.3/HQ/H3) → helper → `generate_two_stage`; tier cells carry `fast_eta` (cost-model 5+2/8+2 ratio, so fixed costs aren't discounted), chips re-price while Fast is armed, and Load Params round-trips it from day one (`test_schedule_preset.py`, 8). (4) **Geometry truth**: make_job floors LTX canvases to the two-stage engine's /64 grid and frames to 8k+1 (floored, never raised) and pushes a sentence when it does; dims inputs step by 64; warnings state what WILL render; H3 tier-cell geometry untouched (`test_geometry_grid.py`, 6). (5) **Load Params restores the cast** (owner-reported): the fire-and-forget IIFE is replaced by an awaited restore through `applyCharacterSelection()` — the new non-toggling hydrator — with visible failure when the character left the library; quality chip by the sidecar's own token, explicit `no_voice` with touched provenance, Extend's four fields, STG (absence = Off), and the Length chip repaints after programmatic frame assignment. A hidden checked No-voice can no longer rewrite a plain render (submit gated on a cast; every hide path clears the box). (6) **One health cluster**: the six machine-state pills live in a single bordered container that is the header's only shrinkable region — narrow windows degrade it to colored state dots, then collapse it; the creator avatar is never clipped again. (7) **Stale-process pill**: `/version` compares HEAD-on-disk to HEAD-at-boot each poll; a promote landing under a running panel renders "Restart to finish update" — **validated live**: the dev panel booted at `90b8a6e` reported `stale_process: true` the moment `65880b3` landed. (8) Keyframe sidecars stamp the resolved q8 pack, not the 2.3-defaulting `MODEL_ID_HQ`. **Gates all green at the tree** (pinokio scripts 377/500 worst · ltx pin unmoved at `v0.14.19+ltx25.4` · post_update · registry 169 · schedules 45 · character round-trip 35 · lora_compat · stage_live_preview · spicy · turbo 11 · schedule_preset 8 · geometry 6 · storyboard suites · py_compile · page parse). **Known-remaining / descoped**: the owner's "stray −1 bar" did not reproduce in either live panel's idle state (needs a screenshot the moment it appears); HDR Load-Params restore is moot while the HDR pill ships commented out (roadmap-parked); render validation of the fast preset + Turbo v1.0 timing run deferred until the GPU frees (the eltrumpo retrain holds both locks overnight). **Audit sources**: `~/AI/projects/phosphene/notes/customize_audit_2026-08-14.md` + `journey_audit_2026-08-14.md` (recovered from the sandboxed sessions' stdout; the FIELD REGISTRY campaign spec in the journey audit is the post-4.0.5 systemic fix).
-**Public release: `v4.4.0`** (2026-08-14 — the live preview leaves the postage stamp and plays full-size on the main stage; the Spicy option follows the Settings switch on both engines; H3's Turbo adapter selection moves to LightX2V v1.0 768p and its automatic install is paused until the repack is published. Carries v4.0.3's picker-LoRA crash fix and the v4.0.2 content: the 720p High tier, i2v that animates the image you gave it, characters on the engine's native runtime-LoRA route, and the vendored pin at `v0.14.19+ltx25.4`; see the entries below. The narrative in this paragraph stops at v3.1.1 and is kept as history). **The 2.3/2.5 divergence that ran through the v3.8.x line was closed by v4.0.0** — LTX-2.5 is the registered default and the vendored port is pinned at the tag `v0.14.19+ltx25.4`. v3.8.x registered 2.3 only and pinned `871694d`, because the 2.5 packs were not publicly downloadable at cut time; they are now. See `CLAUDE.md`'s pin table. The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)** → **v3.0.11 (latent helper-handshake hang fixed: `_read_until` mixed `select()` on the raw fd with a buffered `readline()`, so any event the helper emitted *right before* `ready` — a version-skew line, the new runtime fingerprint — got stranded in the TextIOWrapper buffer and the panel hung 120 s → "helper failed to start: None". This is the true root cause behind the mislabeled "⚠️-emoji" handshake break. Now reads the raw fd via `os.read()` into a carry buffer and drains every complete line before re-`select()`-ing. PLUS: every render log self-documents its runtime — mlx/mlx-metal version + Apple chip + macOS — surfaced in `/status`, the `helper ready ·` line, and a standalone `runtime |` line, the exact data needed to triangulate the remaining MLX-numerical "mosaic")** → **v3.0.12 (the REAL mosaic fix + 3 more. The mosaic is NOT a code bug or the missing-upscaler theory (both disproved by local repro — the bare 6-file Q4 set renders byte-identical-clean on M4 Max); it's stale/corrupt weight *content* — right size, wrong bytes — that v3.0.10's header+size check can't see (confirmed: ronyeoh/#18 + claude3d/#5 fixed it only by a fresh full re-download). Added **deep checksum verify vs upstream**: Settings → Model files → "Verify model files (checksum)" / `/models/verify-deep` hashes every weight + compares to HuggingFace's published SHA-256 (proven to match local), mismatches feed the existing one-click Repair re-download. Validated: flipped 16 bytes mid-file → header+size passed, deep-verify caught it. ALSO in v3.0.12: character-LoRA-shows-as-"style-only" fix (#5 — `list_user_loras` recovers trigger+kind from the `_v2` filename when the sidecar is missing); `cgi`→`email` multipart migration (Python-3.13-ready, removes the boot DeprecationWarning, adopted from @ssfeather's PR #22); dynamic 3–8 multi-keyframe UI (adopted from @youngbee12's PR #20, ported clean with the integrity feature preserved + a JS ReferenceError fixed). Folds in v3.0.11's handshake fix + runtime fingerprint.)** → **v3.0.13 (character LoRA fixes, #5 @claude3d: a multi-word/spaced character filename no longer mislabels as style-only — the id regex gated out spaces before the sidecar was read; and the Character tab no longer silently falls back to plain T2V — a UI desync left the avatar's selection ring lit after `character_id` was cleared. Plus an `enhancePrompt` element-id fix. Cherry-picked to prod `ce03139`, release `814dc2d`.)** → **v3.1.0 (Ideogram 4 — open-weight 9.3B text-rendering image model + a visual text-placement canvas that places exact text via normalized-bbox captions. mflux 0.18 `mflux-generate-ideogram4`; gated `ideogram-ai/ideogram-4-fp8` ~26 GB, needs a HF Read token + license. Fixed the gated-download 401 that would have hit EVERY user — the panel now exports its configured token to subprocess env via `_sync_hf_token_to_env` so a stale `hf auth login` cache can't shadow it; proven clean-room. Validated end-to-end: 8-text-element field-guide poster rendered clean, every label placed per its bbox.)** → **v3.1.1 (Ideogram output-card buttons hotfix, reported by Mr Bizarro: an Ideogram image's prompt is a caption JSON, which broke every output surface that fed it into a plain box / inline onclick — the Recent-list Animate button was worked-but-dead because apostrophes/&/< in the caption terminated the single-quoted onclick. Display-layer fix: `_displayPromptFor` derives `high_level_description`, `escapeHtml` the onclick args, friendly `_imgEngineLabel`, and `loadParams` restores an Ideogram image into the visual canvas instead of dumping JSON. `params.prompt` stays the caption JSON; renders unaffected. Validated live.)** All validated end-to-end on the dev panel (deep-verify corrupt-detect + repair, /loras, byte-identical upload, multi-keyframe render, FFLF regression). See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.
+**Public release: `v4.5.0`** (2026-08-14 — the live preview leaves the postage stamp and plays full-size on the main stage; the Spicy option follows the Settings switch on both engines; H3's Turbo adapter selection moves to LightX2V v1.0 768p and its automatic install is paused until the repack is published. Carries v4.0.3's picker-LoRA crash fix and the v4.0.2 content: the 720p High tier, i2v that animates the image you gave it, characters on the engine's native runtime-LoRA route, and the vendored pin at `v0.14.19+ltx25.4`; see the entries below. The narrative in this paragraph stops at v3.1.1 and is kept as history). **The 2.3/2.5 divergence that ran through the v3.8.x line was closed by v4.0.0** — LTX-2.5 is the registered default and the vendored port is pinned at the tag `v0.14.19+ltx25.4`. v3.8.x registered 2.3 only and pinned `871694d`, because the 2.5 packs were not publicly downloadable at cut time; they are now. See `CLAUDE.md`'s pin table. The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)** → **v3.0.11 (latent helper-handshake hang fixed: `_read_until` mixed `select()` on the raw fd with a buffered `readline()`, so any event the helper emitted *right before* `ready` — a version-skew line, the new runtime fingerprint — got stranded in the TextIOWrapper buffer and the panel hung 120 s → "helper failed to start: None". This is the true root cause behind the mislabeled "⚠️-emoji" handshake break. Now reads the raw fd via `os.read()` into a carry buffer and drains every complete line before re-`select()`-ing. PLUS: every render log self-documents its runtime — mlx/mlx-metal version + Apple chip + macOS — surfaced in `/status`, the `helper ready ·` line, and a standalone `runtime |` line, the exact data needed to triangulate the remaining MLX-numerical "mosaic")** → **v3.0.12 (the REAL mosaic fix + 3 more. The mosaic is NOT a code bug or the missing-upscaler theory (both disproved by local repro — the bare 6-file Q4 set renders byte-identical-clean on M4 Max); it's stale/corrupt weight *content* — right size, wrong bytes — that v3.0.10's header+size check can't see (confirmed: ronyeoh/#18 + claude3d/#5 fixed it only by a fresh full re-download). Added **deep checksum verify vs upstream**: Settings → Model files → "Verify model files (checksum)" / `/models/verify-deep` hashes every weight + compares to HuggingFace's published SHA-256 (proven to match local), mismatches feed the existing one-click Repair re-download. Validated: flipped 16 bytes mid-file → header+size passed, deep-verify caught it. ALSO in v3.0.12: character-LoRA-shows-as-"style-only" fix (#5 — `list_user_loras` recovers trigger+kind from the `_v2` filename when the sidecar is missing); `cgi`→`email` multipart migration (Python-3.13-ready, removes the boot DeprecationWarning, adopted from @ssfeather's PR #22); dynamic 3–8 multi-keyframe UI (adopted from @youngbee12's PR #20, ported clean with the integrity feature preserved + a JS ReferenceError fixed). Folds in v3.0.11's handshake fix + runtime fingerprint.)** → **v3.0.13 (character LoRA fixes, #5 @claude3d: a multi-word/spaced character filename no longer mislabels as style-only — the id regex gated out spaces before the sidecar was read; and the Character tab no longer silently falls back to plain T2V — a UI desync left the avatar's selection ring lit after `character_id` was cleared. Plus an `enhancePrompt` element-id fix. Cherry-picked to prod `ce03139`, release `814dc2d`.)** → **v3.1.0 (Ideogram 4 — open-weight 9.3B text-rendering image model + a visual text-placement canvas that places exact text via normalized-bbox captions. mflux 0.18 `mflux-generate-ideogram4`; gated `ideogram-ai/ideogram-4-fp8` ~26 GB, needs a HF Read token + license. Fixed the gated-download 401 that would have hit EVERY user — the panel now exports its configured token to subprocess env via `_sync_hf_token_to_env` so a stale `hf auth login` cache can't shadow it; proven clean-room. Validated end-to-end: 8-text-element field-guide poster rendered clean, every label placed per its bbox.)** → **v3.1.1 (Ideogram output-card buttons hotfix, reported by Mr Bizarro: an Ideogram image's prompt is a caption JSON, which broke every output surface that fed it into a plain box / inline onclick — the Recent-list Animate button was worked-but-dead because apostrophes/&/< in the caption terminated the single-quoted onclick. Display-layer fix: `_displayPromptFor` derives `high_level_description`, `escapeHtml` the onclick args, friendly `_imgEngineLabel`, and `loadParams` restores an Ideogram image into the visual canvas instead of dumping JSON. `params.prompt` stays the caption JSON; renders unaffected. Validated live.)** All validated end-to-end on the dev panel (deep-verify corrupt-detect + repair, /loras, byte-identical upload, multi-keyframe render, FFLF regression). See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.
> **🎬 2026-08-14 — v4.0.4: the forming take plays on the MAIN STAGE.** The live preview existed since v3.7 and lived in a postage stamp next to the queue, which is not where anyone looks while they wait. It now takes the big player.
>
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 0e7dff6..3481630 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -6432,7 +6432,39 @@ def _select_generation_profile(total_ram_gb: float, tier_key: str) -> dict:
T2V/I2V jobs are shaped so they do not start in the pathological state the
current live render hit.
"""
- if 0 < float(total_ram_gb or 0) < 64:
+ # Two escape hatches, because a hardcoded 64 GB threshold was making this
+ # decision alone and was demonstrably too conservative on real hardware.
+ #
+ # Reported 2026-08-16 (Mac Studio M4 Max, 48 GB, v4.0.6): a requested
+ # 1088x1472 was silently clamped to 768x1024 while memory sat at 9.4/48 GB.
+ # The reporter patched the threshold out and ran the same i2v job at the
+ # full size: 12.79 s/it versus 13.4 s/it clamped, 284 s, no swap, no OOM.
+ # They also found the real inconsistency — LTX_TIER_OVERRIDE moved the tier
+ # modal to "Studio" while this function kept reading physical RAM, so the
+ # two disagreed about what the machine could do.
+ #
+ # 1. An EXPLICIT tier override now flows through. If you told us to treat
+ # this machine as high/pro, the shaping obeys that instead of the RAM
+ # reading it contradicts.
+ # 2. LTX_GENERATION_PROFILE=full lifts the cap on its own, for anyone who
+ # wants the cap gone without also restating their tier.
+ #
+ # The threshold stays the DEFAULT because it was put here by a real swap
+ # thrash, and one clean 48 GB result does not retire it — but it is no
+ # longer the only voice.
+ _forced = os.environ.get("LTX_GENERATION_PROFILE", "").strip().lower()
+ if _forced in ("full", "off", "uncapped"):
+ return {
+ "key": "full_generation",
+ "label": "Full generation (cap lifted by LTX_GENERATION_PROFILE)",
+ "ram_gb": round(float(total_ram_gb or 0), 1),
+ "tier": tier_key,
+ "compact": False, "max_dim": 0,
+ "auto_temporal_after_frames": 0, "warn_loras": 0,
+ }
+ _override = os.environ.get("LTX_TIER_OVERRIDE", "").strip().lower()
+ _override_lifts = _override in ("high", "pro")
+ if 0 < float(total_ram_gb or 0) < 64 and not _override_lifts:
return {
"key": "m5pro48_generation",
"label": "48 GB fast generation",
@@ -9015,10 +9047,17 @@ def _h3_lora_strip_prefix(path: Path, prefix: str) -> int:
new_header: dict = {"__metadata__": new_meta}
new_header.update(renamed)
blob = json.dumps(new_header, separators=(",", ":")).encode("utf-8")
- # The tensor buffer must start 8-byte aligned; the spec pads the JSON with
- # spaces to get there, which is why trailing whitespace inside the header
- # is legal and ignored by every reader.
- blob += b" " * ((-len(blob)) % 8)
+ # The tensor buffer must start 8-byte aligned per the spec; we align to 16
+ # because Metal buffer offsets must be 16-byte aligned, and a misaligned
+ # data section makes every tensor fall back to a COPY instead of a
+ # zero-copy mmap view — silently, with no error, on the whole checkpoint.
+ #
+ # The arithmetic is the part to get right: the file is
+ # [8-byte header length][header blob][tensor data], so the data starts at
+ # 8 + len(blob). Padding the blob to a multiple of 16 therefore lands the
+ # data at 8 mod 16 — misaligned EVERY time, which is worse than the 8-byte
+ # padding it would replace. What we need is len(blob) == 8 (mod 16).
+ blob += b" " * ((-(len(blob) + 8)) % 16)
tmp = path.with_name(path.name + ".converting")
try:
with path.open("rb") as src, tmp.open("wb") as dst:
@@ -25525,6 +25564,51 @@ HTML = r"""<!doctype html>
.ub-sep { opacity: .4; }
.star-link { color: var(--ink-500, #98a0b3); }
.star-link:hover { color: #f0b940; }
+ /* ---- Health: one chip, detail in a portaled popover ----------------- */
+ #healthChip {
+ display: inline-flex; align-items: center; gap: 7px; width: auto;
+ padding: 4px 9px 4px 8px; cursor: pointer; white-space: nowrap;
+ background: rgba(255,255,255,.04);
+ border: 1px solid var(--line, #262a33); border-radius: 99px;
+ color: var(--ink, #e8eaf0); font-size: 11.5px; font-weight: 500;
+ font-variant-numeric: tabular-nums;
+ }
+ #healthChip:hover { background: rgba(255,255,255,.07); }
+ .hc-dot {
+ width: 7px; height: 7px; border-radius: 50%; flex: 0 0 auto;
+ background: #5fbf8f; box-shadow: 0 0 0 3px rgba(95,191,143,.15);
+ }
+ #healthChip.is-warn { border-color: rgba(240,185,64,.42); color: #f7d489; }
+ #healthChip.is-warn .hc-dot { background: #f0b940; box-shadow: 0 0 0 3px rgba(240,185,64,.15); }
+ #healthChip.is-danger { border-color: rgba(255,92,92,.46); color: #ffa3a3; }
+ #healthChip.is-danger .hc-dot { background: #ff5c5c; box-shadow: 0 0 0 3px rgba(255,92,92,.17); }
+ .hc-caret { width: 10px; height: 10px; opacity: .5; }
+ #healthPop {
+ position: fixed; z-index: 9000; min-width: 250px;
+ background: var(--panel, #14161c);
+ border: 1px solid var(--line, #262a33);
+ border-radius: 12px; padding: 5px;
+ box-shadow: 0 18px 44px rgba(0,0,0,.55);
+ }
+ #healthPop[hidden] { display: none; }
+ .hc-row {
+ display: flex; align-items: center; gap: 12px;
+ padding: 6px 9px; border-radius: 8px; font-size: 12px;
+ }
+ .hc-row:hover { background: rgba(255,255,255,.04); }
+ .hc-label { color: var(--ink-500, #98a0b3); flex: 0 0 auto; }
+ /* The relocated pill drops its chrome in here: a bordered pill inside a
+ bordered popover row is one box too many. Its dot and colour classes
+ stay, which is the whole point of reusing the element. */
+ .hc-row .pill {
+ margin: 0 0 0 auto; padding: 0; border: 0; background: none;
+ font-size: 12px; font-variant-numeric: tabular-nums;
+ }
+ /* "Helper · helper idle" reads badly, so a self-naming pill takes the row. */
+ .hc-row.is-selfnamed .hc-label { display: none; }
+ .hc-row.is-selfnamed .pill { margin-left: 0; }
+ .hc-row.is-empty { display: none; }
+
.pill-update {
color: var(--warning, #f0b940);
border-color: rgba(240,185,64,0.55);
@@ -32151,6 +32235,51 @@ HTML = r"""<!doctype html>
.eng-opt.inert { opacity: .58; }
.eng-opt.needs-install .eng-badge.offer { color: var(--eng-accent, currentColor); }
+ /* ---- Health: one chip, detail in a portaled popover ------------------ */
+ #healthChip {
+ display: inline-flex; align-items: center; gap: 7px; width: auto;
+ padding: 4px 9px 4px 8px; cursor: pointer; white-space: nowrap;
+ background: rgba(255,255,255,.04);
+ border: 1px solid var(--line, #262a33); border-radius: 99px;
+ color: var(--ink, #e8eaf0); font-size: 11.5px; font-weight: 500;
+ font-variant-numeric: tabular-nums;
+ transition: background .14s ease, border-color .14s ease;
+ }
+ #healthChip:hover { background: rgba(255,255,255,.075); border-color: #333a46; }
+ #healthChip[aria-expanded="true"] { background: rgba(255,255,255,.085); }
+ .hc-dot {
+ width: 7px; height: 7px; border-radius: 50%; flex: 0 0 auto;
+ background: #5fbf8f; box-shadow: 0 0 0 3px rgba(95,191,143,.16);
+ transition: background .2s ease, box-shadow .2s ease;
+ }
+ #healthChip.is-warn .hc-dot { background: #f0b940; box-shadow: 0 0 0 3px rgba(240,185,64,.16); }
+ #healthChip.is-warn { border-color: rgba(240,185,64,.42); color: #f7d489; }
+ #healthChip.is-danger .hc-dot { background: #ff5c5c; box-shadow: 0 0 0 3px rgba(255,92,92,.18); }
+ #healthChip.is-danger { border-color: rgba(255,92,92,.46); color: #ffa3a3; }
+ .hc-caret { width: 10px; height: 10px; opacity: .5; }
+ #healthPop {
+ position: fixed; z-index: 9000; min-width: 264px;
+ background: #171a21; border: 1px solid #2a2f3a;
+ border-radius: 13px; padding: 6px;
+ box-shadow: 0 20px 48px rgba(0,0,0,.58), inset 0 1px 0 rgba(255,255,255,.04);
+ }
+ #healthPop[hidden] { display: none; }
+ .hc-row {
+ display: flex; align-items: center; gap: 10px;
+ padding: 6px 8px; border-radius: 8px; font-size: 12px;
+ }
+ /* display:flex above beats the UA's [hidden]{display:none} — without this a
+ hidden row still paints its label with nothing after it. */
+ .hc-row[hidden] { display: none; }
+ .hc-row:hover { background: rgba(255,255,255,.04); }
+ .hc-label { color: var(--ink-500, #98a0b3); flex: 0 0 74px; }
+ /* The relocated pill keeps its own id, classes and colour logic; the row
+ only gives it a place to stand and a word in front of it. */
+ .hc-row .pill {
+ margin: 0 0 0 auto !important; font-size: 11.5px;
+ font-variant-numeric: tabular-nums;
+ }
+
body > header .engine-switch {
flex-shrink: 0;
}
@@ -33190,7 +33319,53 @@ HTML = r"""<!doctype html>
window compresses the cluster instead of shoving the creator chip
into the header's overflow:hidden (the "avatar clipped" report).
Individual pill ids and their JS updaters are untouched. -->
- <div id="healthCluster" role="group" aria-label="System health">
+ <!-- ONE CHIP (v4.5.0). Six pills across the header truncated on a 14" window
+ and could not have taken a seventh. The pills are UNCHANGED — same ids,
+ same updaters, same colour classes — they simply live inside the popover
+ now, relocated at boot, so nothing downstream had to learn a new shape.
+ The chip SUMMARISES them: worst state wins the colour, and memory stays
+ on the face because it is the one number worth a glance.
+ PORTALED to <body>: <header> is overflow:hidden and would slice it —
+ the same clipping that once cut off the avatar. -->
+ <!-- ONE CHIP (v4.5.0). Six pills across the header truncated on a 14" and
+ could not have taken a seventh. The pills are UNCHANGED — same ids, same
+ updaters, same colour classes — they are simply relocated into the rows
+ below at boot, and #healthChip summarises them: worst state wins the
+ colour, memory stays on the face because it is the one number worth a
+ glance. Both the chip's popover and this cluster escape <header>, which
+ is overflow:hidden and would slice them. -->
+ <button type="button" id="healthChip" aria-haspopup="dialog" aria-expanded="false"
+ aria-controls="healthPop" title="System health — click for detail">
+ <span class="hc-dot"></span>
+ <span class="hc-face">checking…</span>
+ <svg class="ph hc-caret" aria-hidden="true"><use href="#ph-caret-down-bold"/></svg>
+ </button>
+ <div id="healthPop" hidden role="dialog" aria-label="System health detail">
+ <div class="hc-row" data-pill="tierPill"><span class="hc-label">Tier</span></div>
+ <div class="hc-row" data-pill="memPill"><span class="hc-label">Memory</span></div>
+ <div class="hc-row" data-pill="helperPill"><span class="hc-label">Helper</span></div>
+ <div class="hc-row" data-pill="modelsPill"><span class="hc-label">Models</span></div>
+ <div class="hc-row" data-pill="comfyPill"><span class="hc-label">ComfyUI</span></div>
+ <div class="hc-row" data-pill="queuePill"><span class="hc-label">Queue</span></div>
+ <div class="hc-row" data-pill="jobPill"><span class="hc-label">Render</span></div>
+ </div>
+ <div id="healthCluster" role="group" aria-label="System health" hidden>
+ <button type="button" id="healthChip" aria-haspopup="dialog"
+ aria-expanded="false" aria-controls="healthPop"
+ title="System health — click for detail">
+ <span class="hc-dot" id="hcDot"></span>
+ <span class="hc-face" id="hcFace">checking…</span>
+ <svg class="ph hc-caret" aria-hidden="true"><use href="#ph-caret-down-bold"/></svg>
+ </button>
+ <div id="healthPop" hidden role="dialog" aria-label="System health detail">
+ <div class="hc-row" data-pill="tierPill"><span class="hc-label">Tier</span></div>
+ <div class="hc-row" data-pill="memPill"><span class="hc-label">Memory</span></div>
+ <div class="hc-row" data-pill="helperPill"><span class="hc-label">Helper</span></div>
+ <div class="hc-row" data-pill="modelsPill"><span class="hc-label">Models</span></div>
+ <div class="hc-row" data-pill="comfyPill"><span class="hc-label">ComfyUI</span></div>
+ <div class="hc-row" data-pill="queuePill"><span class="hc-label">Queue</span></div>
+ <div class="hc-row" data-pill="jobPill"><span class="hc-label">Render</span></div>
+ </div>
<span id="tierPill" class="pill" style="cursor:pointer" onclick="openTierModal()" title="Click to see what this Mac can do">click for system info</span>
<span id="memPill" class="pill">memory…</span>
<span id="comfyPill" class="pill" style="display:none">comfy…</span>
@@ -45177,6 +45352,9 @@ async function poll() {
const m = s.memory;
const memPill = document.getElementById('memPill');
memPill.innerHTML = `<span class="dot"></span>${fmtMem(m)}`;
+ try { _healthSync(); } catch (e) {}
+ memPill.title = fmtMemTitle(m);
+ if (typeof updateHealthChip === 'function') updateHealthChip();
memPill.title = fmtMemTitle(m);
// 2026-05-20: color the badge by real pressure, not by sticky swap.
// Same reason fmtMem dropped swap from the visible label — swap is
@@ -52083,6 +52261,103 @@ function renderVersionPill() {
pill.title = 'Checking for updates…';
}
+// ---- Health: one chip, one popover ---------------------------------------
+//
+// The pills are NOT rewritten. Every existing updater still writes to
+// #memPill / #helperPill / #modelsPill / #tierPill / #comfyPill / #queuePill /
+// #jobPill exactly as before; they are relocated once and read back here to
+// summarise. A summary that re-derived state from /status would be a second
+// source of truth, and the two would drift the first time a pill's rule moved.
+window._healthPopOpen = false;
+
+function _healthPortal() {
+ const pop = document.getElementById('healthPop');
+ if (!pop || pop.dataset.portaled === '1') return pop;
+ pop.querySelectorAll('.hc-row[data-pill]').forEach(row => {
+ const pill = document.getElementById(row.dataset.pill);
+ if (pill) row.appendChild(pill);
+ else row.remove(); // a pill this build does not have
+ });
+ const cluster = document.getElementById('healthCluster');
+ if (cluster) cluster.remove(); // the now-empty holder
+ document.body.appendChild(pop); // escape header overflow:hidden
+ pop.dataset.portaled = '1';
+ return pop;
+}
+
+function closeHealthPop() {
+ window._healthPopOpen = false;
+ const pop = document.getElementById('healthPop');
+ if (pop) pop.hidden = true;
+ const chip = document.getElementById('healthChip');
+ if (chip) chip.setAttribute('aria-expanded', 'false');
+}
+
+function toggleHealthPop() {
+ const pop = _healthPortal();
+ const chip = document.getElementById('healthChip');
+ if (!pop || !chip) return;
+ if (window._healthPopOpen) { closeHealthPop(); return; }
+ const r = chip.getBoundingClientRect();
+ pop.hidden = false; // measure before placing
+ const w = pop.getBoundingClientRect().width;
+ pop.style.top = (r.bottom + 7) + 'px';
+ pop.style.left = Math.max(8, Math.min(r.left, window.innerWidth - w - 10)) + 'px';
+ window._healthPopOpen = true;
+ chip.setAttribute('aria-expanded', 'true');
+}
+
+// Worst state wins: a green chip must never hide a red pill.
+function _healthSync() {
+ const chip = document.getElementById('healthChip');
+ if (!chip) return;
+ const ids = ['tierPill', 'memPill', 'comfyPill', 'helperPill', 'modelsPill'];
+ const pills = ids.map(id => document.getElementById(id))
+ .filter(el => el && el.style.display !== 'none');
+ let worst = 'good';
+ pills.forEach(el => {
+ if (el.classList.contains('pill-danger') || el.classList.contains('pill-bad')) worst = 'bad';
+ else if (el.classList.contains('pill-warn') && worst !== 'bad') worst = 'warn';
+ });
+ chip.classList.toggle('is-warn', worst === 'warn');
+ chip.classList.toggle('is-danger', worst === 'bad');
+
+ // Comfy hides ITSELF when not running; its row has to follow or the popover
+ // shows a label with nothing after it.
+ const pop = document.getElementById('healthPop');
+ if (pop) pop.querySelectorAll('.hc-row[data-pill]').forEach(row => {
+ const pill = document.getElementById(row.dataset.pill);
+ row.hidden = !!(pill && pill.style.display === 'none');
+ });
+
+ // Memory keeps its place on the face: it is the number that moves while you
+ // watch, and the one that decides whether the next render fits.
+ const mem = document.getElementById('memPill');
+ const memText = mem ? mem.textContent.trim() : '';
+ const label = worst === 'bad' ? 'Needs attention'
+ : worst === 'warn' ? 'Under pressure' : 'All good';
+ const face = chip.querySelector('.hc-face');
+ if (face) face.textContent = memText ? `${label} · ${memText}` : label;
+ chip.title = pills.map(el => el.textContent.trim()).filter(Boolean).join(' · ')
+ || 'System health';
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+ _healthPortal();
+ const chip = document.getElementById('healthChip');
+ if (chip) chip.onclick = (ev) => { ev.stopPropagation(); toggleHealthPop(); };
+ _healthSync();
+});
+document.addEventListener('click', (ev) => {
+ if (!window._healthPopOpen) return;
+ if (ev.target.closest('#healthPop') || ev.target.closest('#healthChip')) return;
+ closeHealthPop();
+}, true);
+document.addEventListener('keydown', (ev) => {
+ if (ev.key === 'Escape' && window._healthPopOpen) closeHealthPop();
+});
+window.addEventListener('resize', closeHealthPop);
+
// ---- Update banner -------------------------------------------------------
//
// The pill has always known we were behind; it just said so quietly, in the
@@ -52215,6 +52490,100 @@ document.addEventListener('DOMContentLoaded', () => {
.catch(() => {});
});
+// ---- Health chip -----------------------------------------------------------
+// The pills still exist and are still written by the same updaters; at boot
+// each is MOVED into its row. The chip is DERIVED from them, so whatever turns
+// memPill red turns the chip red by construction, rather than by a second
+// opinion that could disagree with the first.
+window._hcOpen = false;
+
+function _hcSeverity(el) {
+ if (!el) return 0;
+ if (el.classList.contains('pill-danger')) return 2;
+ if (el.classList.contains('pill-warn')) return 1;
+ return 0;
+}
+
+function _hcRelocate() {
+ const pop = document.getElementById('healthPop');
+ if (!pop) return;
+ pop.querySelectorAll('.hc-row').forEach(row => {
+ const pill = row.dataset.pill && document.getElementById(row.dataset.pill);
+ if (pill && pill.parentElement !== row) row.appendChild(pill);
+ });
+ if (pop.parentElement !== document.body) document.body.appendChild(pop);
+}
+
+function closeHealthPop() {
+ const pop = document.getElementById('healthPop');
+ if (pop) pop.hidden = true;
+ const chip = document.getElementById('healthChip');
+ if (chip) chip.setAttribute('aria-expanded', 'false');
+ window._hcOpen = false;
+}
+
+function toggleHealthPop() {
+ const pop = document.getElementById('healthPop');
+ const chip = document.getElementById('healthChip');
+ if (!pop || !chip) return;
+ if (window._hcOpen) { closeHealthPop(); return; }
+ updateHealthChip();
+ const r = chip.getBoundingClientRect();
+ pop.hidden = false; // measure before placing
+ const w = pop.getBoundingClientRect().width;
+ pop.style.top = (r.bottom + 6) + 'px';
+ pop.style.left = Math.max(8, Math.min(r.right - w, window.innerWidth - w - 8)) + 'px';
+ chip.setAttribute('aria-expanded', 'true');
+ window._hcOpen = true;
+}
+
+function updateHealthChip() {
+ const chip = document.getElementById('healthChip');
+ const face = document.getElementById('hcFace');
+ if (!chip || !face) return;
+ const mem = document.getElementById('memPill');
+ const models = document.getElementById('modelsPill');
+ const helper = document.getElementById('helperPill');
+ const worst = [mem, models, helper].reduce((a, el) => Math.max(a, _hcSeverity(el)), 0);
+ chip.classList.toggle('is-warn', worst === 1);
+ chip.classList.toggle('is-danger', worst === 2);
+ const clean = el => (el ? el.textContent : '').replace(/\s+/g, ' ').trim();
+ if (worst > 0) {
+ // Name the thing that is wrong. "Attention" tells the user to go looking.
+ const bad = [models, helper, mem].find(el => _hcSeverity(el) === worst);
+ face.textContent = clean(bad) || 'needs attention';
+ } else {
+ face.textContent = clean(mem) || 'all good';
+ }
+ document.querySelectorAll('#healthPop .hc-row').forEach(row => {
+ const pill = row.querySelector('.pill');
+ const gone = !pill || pill.style.display === 'none';
+ row.classList.toggle('is-empty', gone);
+ if (gone) return;
+ const label = row.querySelector('.hc-label');
+ if (!label) return;
+ if (!label.dataset.word) label.dataset.word = label.textContent.trim();
+ const first = (pill.textContent || '').trim().toLowerCase().split(/[\s·]+/)[0] || '';
+ row.classList.toggle('is-selfnamed', first === label.dataset.word.toLowerCase());
+ });
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+ _hcRelocate();
+ const chip = document.getElementById('healthChip');
+ if (chip) chip.onclick = (ev) => { ev.stopPropagation(); toggleHealthPop(); };
+ updateHealthChip();
+});
+document.addEventListener('click', (ev) => {
+ if (!window._hcOpen) return;
+ if (ev.target.closest('#healthPop') || ev.target.closest('#healthChip')) return;
+ closeHealthPop();
+}, true);
+document.addEventListener('keydown', (ev) => {
+ if (ev.key === 'Escape' && window._hcOpen) closeHealthPop();
+});
+window.addEventListener('resize', closeHealthPop);
+
// One click — does the right thing for the current state. Magic button.
async function versionPillClick() {
if (_versionRestartPending) {
diff --git a/test_generation_profile_override.py b/test_generation_profile_override.py
new file mode 100644
index 0000000..63e2617
--- /dev/null
+++ b/test_generation_profile_override.py
@@ -0,0 +1,67 @@
+"""The 48 GB generation clamp, and the two ways to lift it.
+
+Reported 2026-08-16 on r/... (Mac Studio M4 Max, 48 GB, v4.0.6): a requested
+1088x1472 was silently reshaped to 768x1024 while memory sat at 9.4/48 GB. The
+reporter also found the real inconsistency — LTX_TIER_OVERRIDE moved the tier
+modal to "Studio" while _select_generation_profile kept reading physical RAM,
+so the two disagreed about the same machine. They patched the threshold out and
+ran the identical i2v job at full size: 12.79 s/it vs 13.4 s/it clamped, 284 s,
+no swap, no OOM.
+
+The default threshold stays — it was put there by a real swap thrash and one
+clean 48 GB result does not retire it. What changed is that it is no longer the
+only voice: an explicit tier override is believed, and LTX_GENERATION_PROFILE
+can lift the cap outright.
+"""
+
+import os
+import unittest
+from unittest import mock
+
+import mlx_ltx_panel as panel
+
+
+class GenerationProfileClamp(unittest.TestCase):
+ def _profile(self, ram, tier="standard", **env):
+ with mock.patch.dict(os.environ, env, clear=False):
+ for k in ("LTX_TIER_OVERRIDE", "LTX_GENERATION_PROFILE"):
+ if k not in env:
+ os.environ.pop(k, None)
+ return panel._select_generation_profile(ram, tier)
+
+ def test_48gb_still_clamps_by_default(self):
+ """The default must not change silently — it exists for a reason."""
+ p = self._profile(48.0)
+ self.assertTrue(p["compact"])
+ self.assertEqual(p["max_dim"], 1024)
+
+ def test_64gb_and_up_never_clamped(self):
+ self.assertFalse(self._profile(64.0)["compact"])
+ self.assertFalse(self._profile(128.0)["compact"])
+
+ def test_tier_override_lifts_the_clamp(self):
+ """THE reported bug: the override moved the modal and nothing else."""
+ for tier in ("high", "pro"):
+ p = self._profile(48.0, LTX_TIER_OVERRIDE=tier)
+ self.assertFalse(p["compact"], tier)
+ self.assertEqual(p["max_dim"], 0, tier)
+
+ def test_a_lower_override_does_not_lift_it(self):
+ """Forcing 'base' must not accidentally hand you the uncapped profile."""
+ p = self._profile(48.0, LTX_TIER_OVERRIDE="base")
+ self.assertTrue(p["compact"])
+
+ def test_explicit_flag_lifts_the_clamp_on_its_own(self):
+ for val in ("full", "off", "uncapped"):
+ p = self._profile(48.0, LTX_GENERATION_PROFILE=val)
+ self.assertFalse(p["compact"], val)
+ self.assertEqual(p["max_dim"], 0, val)
+
+ def test_unknown_flag_value_is_ignored(self):
+ """Junk must fall through to the safe default, not to uncapped."""
+ p = self._profile(48.0, LTX_GENERATION_PROFILE="yes-please")
+ self.assertTrue(p["compact"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test_safetensors_alignment.py b/test_safetensors_alignment.py
new file mode 100644
index 0000000..ba357ef
--- /dev/null
+++ b/test_safetensors_alignment.py
@@ -0,0 +1,59 @@
+"""Where the tensor data starts in a safetensors file we WRITE.
+
+The spec only demands 8-byte alignment. Metal demands 16 for a buffer offset,
+and a misaligned data section does not error — every tensor silently falls back
+to a copy instead of a zero-copy mmap view. vpipe (tgo-app-dev) measured 39.1 GB
+of that on a single checkpoint whose data began at 8 (mod 16).
+
+The arithmetic is the trap. The layout is:
+
+ [8-byte little-endian header length][header blob][tensor data]
+
+so data starts at 8 + len(blob). Padding the BLOB to a multiple of 16 puts the
+data at 8 (mod 16) — misaligned every single time, i.e. strictly worse than the
+8-byte padding it replaces. The correct condition is len(blob) == 8 (mod 16).
+"""
+
+import re
+import unittest
+from pathlib import Path
+
+PANEL = Path(__file__).with_name("mlx_ltx_panel.py")
+
+
+def _pad(blob_len: int) -> int:
+ """The padding rule as it exists in the panel source, not a copy of it."""
+ src = PANEL.read_text()
+ m = re.search(r'blob \+= b" " \* \(\(([^\n]+?)\) % (\d+)\)', src)
+ assert m, "padding expression not found — did the writer change shape?"
+ expr, mod = m.group(1), int(m.group(2))
+ return eval(expr.replace("len(blob)", str(blob_len))) % mod # noqa: S307
+
+
+class DataSectionAlignment(unittest.TestCase):
+ def test_data_starts_16_byte_aligned_for_every_header_length(self):
+ for blob_len in range(1, 1024):
+ data_start = 8 + blob_len + _pad(blob_len)
+ self.assertEqual(data_start % 16, 0,
+ f"header {blob_len} -> data at {data_start} "
+ f"({data_start % 16} mod 16)")
+
+ def test_still_satisfies_the_spec_minimum(self):
+ """16-alignment implies the spec's 8 — assert it rather than assume."""
+ for blob_len in range(1, 256):
+ self.assertEqual((8 + blob_len + _pad(blob_len)) % 8, 0)
+
+ def test_padding_is_minimal(self):
+ """Never add a whole extra 16 bytes when zero would do."""
+ for blob_len in range(1, 256):
+ self.assertLess(_pad(blob_len), 16)
+
+ def test_a_naive_16_pad_would_be_wrong(self):
+ """Documents the trap: this is the fix that looks right and is not."""
+ for blob_len in (200, 201, 240):
+ naive = (-blob_len) % 16
+ self.assertNotEqual((8 + blob_len + naive) % 16, 0)
+
+
+if __name__ == "__main__":
+ unittest.main()