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.4.2): H3 selectable steps + community fix wave
mrbizarro295dbdf89ac5
diff --git a/.gitignore b/.gitignoreindex 00a128b..fb86640 100644--- a/.gitignore+++ b/.gitignore@@ -20,6 +20,13 @@ panel_settings.json# to docs/stats-data.jsonl — rolled back in 70b4489. Never again.)**/stats-data.jsonlstats-data.jsonl+# Same defense-in-depth for the anonymous-usage mirror + the cached fleet+# rollup. These carry no prompts/paths/media by construction, but they are+# still this machine's own telemetry and have no business in a public repo.+**/usage-log.jsonl+usage-log.jsonl+**/usage-fleet.json+usage-fleet.json*.log*.tmp# Manual `.original_<date>` asset backups (e.g. before re-exporting a logo).diff --git a/docs/ANALYTICS.md b/docs/ANALYTICS.mdnew file mode 100644index 0000000..0ae5d73--- /dev/null+++ b/docs/ANALYTICS.md@@ -0,0 +1,295 @@+# Anonymous usage analytics++Phosphene sends a small number of anonymous counts so that bugs in the field+get noticed. This page is the complete specification: every event, every+field, every value. If the panel ever sends something that isn't listed here,+that's a bug — please open an issue.++**In one line:** counts and hardware classes, never content. No prompts, no+filenames, no paths, no images, no video, no audio, no seeds, no LoRA or+character names.++---++## The short version++| | |+|---|---|+| **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 |+| **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 |+| **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.++---++## How to turn it off++**Settings → Anonymous usage analytics → Turn off.** One click; no confirm+step. Turning it off stops the network calls *and* stops writing the local+log.++Before the panel has ever written a settings file — or if you'd rather set it+in your environment — use:++```sh+PHOSPHENE_ANALYTICS_DISABLED=1+```++That env var wins over the setting, always.++---++## What identifies you++A single random **UUID4**, generated the first time an event is captured and+stored as `analytics_install_id` in `state/panel_settings.json`.++It is **not derived from anything**: not your hardware serial, not the MAC+address, not the username, not the hostname, not the install path. Delete the+key (or the file) and this install becomes a brand-new anonymous install with+no way to correlate it to the old one. The panel shows you the exact value in+Settings.++**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).++---++## Events++Five event types. That's the whole list.++### `app_boot`++Once per panel start.++| Field | Type | Example | Notes |+|---|---|---|---|+| `version` | string | `"3.4.1"` | Contents of the repo `VERSION` file |+| `os_version` | string | `"26.4"` | macOS major.minor. Patch level deliberately dropped |+| `chip_family` | string | `"M4 Max"` | Parsed from the CPU brand string. A hardware *class*, identical across every machine of that model. `"unknown"` or `"non-apple-silicon"` when unparseable |+| `ram_gb` | int | `64` | Unified memory, rounded to whole GB |+| `cap_tier` | string | `"q8"` | `q4` or `q8` — which capability surface the UI is showing |+| `packs` | object | `{"h3":true,"sharp":false,"q8":true,"qwen":false}` | Booleans only: is each optional pack installed |+| `h3_chain_supported` | bool | `false` | Whether the installed H3 runner supports window chaining (10 s / 15 s tiers) |++### `render_completed`++Once per job that finishes successfully — every engine and every mode,+including image and training jobs.++| Field | Type | Example | Notes |+|---|---|---|---|+| `engine` | string | `"ltx"` | `ltx` or `h3` |+| `mode` | string | `"i2v"` | `t2v`, `i2v`, `extend`, `keyframe`, `a2v`, `restore`, `ingredients`, `control`, `image`, `train` |+| `tier` | string | `"standard"` | LTX quality (`quick`/`balanced`/`standard`/`high`) or H3 tier (`3s`/`5s`/`10s`/`15s`) |+| `duration_bucket` | string | `"5-15m"` | One of `<2m`, `2-5m`, `5-15m`, `15-40m`, `>40m`, `unknown`. Bucketed, not raw — a precise duration plus a resolution plus a timestamp starts to look like a fingerprint |+| `resolution` | string | `"1216x704"` | Output dimensions, or `"unknown"` |+| `frames` | int | `121` | Frame count |++### `render_failed`++Same as `render_completed`, plus one field:++| Field | Type | Example | Notes |+|---|---|---|---|+| `error_signature` | string | `"RuntimeError: helper exited before first frame"` | **The only free-text field the panel sends.** See the scrubbing rules below |++Cancelled jobs are **not** reported — a user cancelling is not a signal about+the software.++#### How `error_signature` is scrubbed++In this order:++1. **First line only.** Tracebacks and multi-line detail are discarded.+2. **Exact content redaction.** This job's prompt, negative prompt, image+ path, audio path, output path, character name and training-job id are+ removed by exact substring match → `<redacted>`. This is the defense that+ matters: the realistic leak is an exception that quotes your prompt back.+3. **Path stripping.** Anything shaped like an absolute path — `/Users/…`,+ `~/…`, `/private/var/…`, `/Volumes/…`, or any run of two or more path+ segments — becomes `<path>`.+4. **Truncation to 120 characters.**++Strings shorter than 6 characters are not redacted, so a terse prompt can't+blank out ordinary words in an error message.++### `pack_state_change`++Fired at boot when an optional pack's installed state differs from the+previous boot. At most four per boot; usually zero.++| Field | Type | Example |+|---|---|---|+| `pack` | string | `"h3"` — one of `h3`, `sharp`, `q8`, `qwen` |+| `from` | bool | `true` |+| `to` | bool | `false` |++A `true → false` transition means a pack that *was* installed is no longer+detectable — a broken install, not a user choice. This is the whole reason+this event exists: nothing else in the panel notices that today.++### `engine_selected` — not implemented, on purpose++The obvious way to count engine-picker usage is a ping per click. That adds a+network request to an interaction that currently has none, and it would be by+far the chattiest event in the system. The same question is answered for free+by the `engine` field on every render event plus the `packs.h3` field on+`app_boot`, so the picker is measured by what people actually render rather+than what they click. If clicks-without-renders ever become the question,+that's the point to add it.++---++## What is never sent++Not "we try not to send" — these are dropped by name before any payload is+built, and there's a test asserting it:++> `prompt`, `negative_prompt`, `override_prompt`, `caption`, `image`,+> `image_path`, `images`, `audio`, `audio_path`, `video`, `output`,+> `output_path`, `raw_output`, `native_output`, `path`, `paths`, `file`,+> `filename`, `files`, `dir`, `directory`, `root`, `first_frame`,+> `last_frame`, `refs`, `reference`, `seed_image`, `lora`, `loras`,+> `lora_path`, `lora_paths`, `character`, `trigger`, `trigger_words`,+> `hostname`, `username`, `user`, `email`, `home`, `command`, `cmd`, `argv`,+> `env`, `token`, `key`, `api_key`++No media file ever leaves the machine under any circumstance — there is no+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:++```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"}+```++Two reasons it exists: it's the "this machine" data source for the Usage+section 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.++The file is capped at **5 MB**; at the cap the oldest half is dropped. It's+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`).++### 1. Turn the pings on — PostHog **Project API key**++PostHog → *Project settings* → *Project API key* (starts `phc_…`). This key is+write-only and safe to hold on disk.++Paste it into **PostHog project key (capture)**. Until this is set,+`ANALYTICS_KEY_DEFAULT` is `""` and the panel opens **no socket at all**.++Env override: `PHOSPHENE_ANALYTICS_KEY`.++### 2. Turn the fleet dashboard on — PostHog **Personal API key**++PostHog → *Personal settings* → *Personal API keys* → create one with **read**+scope on the project (starts `phx_…`).++Paste it into **PostHog personal API key (fleet view)**. This unlocks the+fleet numbers in the Usage section at <http://127.0.0.1:8199/stats>. It is+never used for sending, only for querying.++Env override: `PHOSPHENE_ANALYTICS_QUERY_KEY`.++### Self-hosting++| Variable | Default | Purpose |+|---|---|---|+| `PHOSPHENE_ANALYTICS_HOST` | `https://us.i.posthog.com` | Ingestion endpoint. Must accept a PostHog-shaped single-event `POST /i/v0/e/` |+| `PHOSPHENE_ANALYTICS_API_HOST` | `https://us.posthog.com` | Query API host for the fleet view |+| `PHOSPHENE_ANALYTICS_PROJECT` | `@current` | PostHog project id used in the query URL |+| `PHOSPHENE_ANALYTICS_DISABLED` | *(unset)* | `1` disables everything, overriding the setting |++---++## The dashboard — `/stats` → Usage++The maintainer dashboard at <http://127.0.0.1:8199/stats> (127.0.0.1-only,+like every other panel endpoint) has a **Usage** section fed by+`GET /stats/usage`. Two tiers, one renderer:++- **`this mac`** — aggregated from `state/usage-log.jsonl`. Always available,+ needs no keys, works offline. Labelled *"this machine only — add a PostHog+ query key in Settings for fleet data"*.+- **`fleet`** — aggregated by PostHog across every install that has pinged.+ Requires the personal API key. Cached to `state/usage-fleet.json` for **6+ hours**; the section's *refresh* button bypasses the cache.++It shows: weekly active installs, renders this week, H3 share, error rate, the+top 5 error signatures of the last 7 days, version / chip / memory+distributions, and a **pack-regression alert** that turns red when any pack+went `true → false` in the last week.++The fleet view runs ten read-only aggregate HogQL `SELECT`s against `events`.+Each is independent — one failing leaves that panel empty rather than+collapsing the view. If every query fails, the section falls back to local+data with a visible warning.++---++## Design notes++**Why default ON.** An opt-in version of this shipped on 2026-05-21 and was+reverted the next day (`da1d6f5`). It was off by default, which meant it would+have 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.++**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+`except: pass` around the entire path. Nothing is retried and nothing is+queued — a dropped event is strictly preferable to state that outlives the+render it describes. There are no background timers and no heartbeats.++**Where it's wired.** Two call sites, both in `mlx_ltx_panel.py`:+`_analytics_boot()` in `__main__` (never at import time, so `import+mlx_ltx_panel` from a script sends nothing), and `_analytics_render_event()`+in `worker_loop`'s `finally` — the single point every job from every engine+passes through, so a future engine is counted for free.++---++## Verifying it yourself++```sh+# The dry-run suite: no network, no panel, isolated temp state dir.+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.++To watch it live, tail the local log while you render:++```sh+tail -f state/usage-log.jsonl+```diff --git a/docs/STATE.md b/docs/STATE.mdindex 1a5ffa4..f4e86cf 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -4,7 +4,7 @@> **📯 2026-08-03 — v3.4.0 SHIPPED PUBLIC: the Hailuo H3 engine.** Public `origin/main` `0ef1a98`, tag `v3.4.0`, tree==beta. Engine picker (LTX-2.3 | Hailuo H3) in the Video tab; H3 in Text+Image (Image = first-frame conditioning); 4 measured tiers (Draft 3s ~3min / HQ 3s ~5min / HQ 5s ~8min / Long 10s ~36min); optional install_h3.js (~75GB, 64GB-RAM gated, clones mrbizarro/minimax-h3-mlx@codex/h3-engine); warm-helper teardown before H3 jobs; subprocess isolation — LTX untouched. Validated end-to-end by an independent agent (real t2v + first-frame i2v renders with audio, stop test, LTX regression, 5/5 SHIP). Release post LIVE: <https://beta.pinokio.co/posts/01kz48kve8g17ymk8dtms5j2g7> (robot-chef validation clip as hero). Residual known risk (accepted, owner-driven release): install_h3.js has never run on a truly clean machine — weights sources verified fetchable+ungated and the branch verified byte-identical to the validated runner; if a fresh-install report comes in, treat as hotfix priority. H3 experiment records: ~/AI/projects/hailuo-mlx/.-> **🧪 2026-08-05 — v3.4.1 on `dev`/`beta` (NOT public): chained H3 tiers, the H3 export pass, crash-reap, and BT.709 on every delivered clip.** Four changes, all validated on the dev box before the push.+> **🧪 2026-08-05 — v3.4.1: chained H3 tiers, the H3 export pass, crash-reap, and BT.709 on every delivered clip.** (**SHIPPED PUBLIC same day** — `f66e59c`, tag `v3.4.1`; release post <https://beta.pinokio.co/posts/01kz986wqj2nemwm7f3vr1bm8c>.) Four changes, all validated on the dev box before the push.>> - **Chained 10 s / 15 s H3 tiers** (`e831fb3`). Anything past 5 s now renders as N chained 5 s windows — window N's last decoded frame re-enters as window N+1's first-frame keyframe. 10 s went 36:12 (one dense 243f pass) → **17:05**; 15 s is newly reachable at **26:34**; memory is FLAT (13,580 rows/window, 40.2 GiB peak) so duration is linear in wall clock. The dense 10 s path stays behind `LTX_H3_DENSE_10S=1` for A/B. Honest artefact reported as data: one prompt is asked of every window, so a scripted line lands once per window — the tier carries a `note` the panel renders under the strip. Chaining needs `--chain-windows` on the INSTALLED runner, so it is probed (`/status.h3.chain`), the chained tiers are withheld when absent, and `make_job` falls back to the longest single-pass tier instead of failing a queued job.> - **H3 gets the export pass LTX already had** (`e831fb3`). H3's native 768×448 (12:7) no longer lands in a gallery of 1280×720 clips: same ffmpeg recipe (lanczos fit inside the canvas, pad the remainder, user's codec settings, `+faststart`, audio copied through). Default `fit_720p`, `fit_1080p` option, `off` for native. `h3_upscale` is in the make_job allowlist; native stays on disk but hidden, exactly like the LTX path; `UPSCALE_TAGS` is module-level so `/output/delete` and Load Params can't drift from `compute_upscale_plan`.@@ -41,6 +41,7 @@> - `pinokio.js` probes the interpreter with **`fs.existsSync`** (follows symlinks → a dangling chain is definitively false) instead of `info.exists`, so menu and panel agree by construction. Adds **"Repair Hailuo H3 (weights kept — no re-download)"** and keeps it reachable from **every** menu state, including post-Reset.> - `install_h3.js`'s venv step no longer trusts a path guard — a dangling chain can read as *present* depending on whether the check stats the link or the target, which would silently skip the repair. It now asks whether the interpreter **runs** and rebuilds only when it doesn't (~50 ms on a healthy install, ~2 min self-heal when broken, zero bytes re-downloaded).> - `reset.js` documents that `minimax-h3-mlx/` and `mlx_models/hailuo-h3/` are user content and must never be added to it.+> - **Follow-up, same session (`87b28f4`): the LTX venv carried the IDENTICAL guard.** `install.js` gated its venv rebuild on `when: !exists('ltx-2-mlx/env/bin/python3.11')`, and the LTX chain into Pinokio's shared uv Python is the same one (verified above — it's what the H3 comparison was made against). Replaced with the install_h3.js run-probe shape: `env/bin/python3.11 -c 'import sys'` in-shell → reuse (~50 ms) or rebuild (~5 min, zero re-downloads); the macOS-14 preflight + v2.0.3 diagnostics kept inside the rebuild branch; python3.11 (not python) so a legacy conda-3.10 venv still rebuilds; the if/else ships as one joined multi-line message (the mflux-step idiom) so it runs as a single compound. Lower urgency than H3 was — `reset.js` DOES delete `ltx-2-mlx/`, so Reset+Install already recovered a broken LTX venv — but Reset is no longer the only cure. Gates run: `node --check` + the exact message string extracted from the module and executed in bash+zsh across healthy / dangling-terminal-target / absent / fake-macOS-13 sims (healthy reused untouched; dangling healed via real `uv venv` back to the exact production chain and converged to "healthy" on re-run; Ventura sim exited 1 before uv). The standing rule holds product-wide now: **no venv-backed pack probes `bin/python*` by path anywhere** — remaining `exists()` uses are `.git` clone guards and the pyvenv.cfg/`fs.existsSync` probes. Remaining ideal gate before any public promote: one real fresh Pinokio install.>> **Validation.** Sandbox at the DEFAULT paths (no env overrides) driving the **real** `h3_paths()` (spliced from the panel) and the **real** `pinokio.js` menu block, across healthy → stomp → Reset → repair. Before: panel "not installed", menu after Reset `[Install, Models]`. After: panel `reason=missing_venv repairable=true venv_broken=true weights_ok=true`, menu `Repair Hailuo H3` present in the healthy *and* post-Reset states, back to clean once the venv is rebuilt — **5/5 weight components untouched throughout**. `py_compile` + `node --check` on all nine root scripts. The live panel was **not** restarted (a Codex GPU experiment held the box), so this is code-level + simulation validation; a real Pinokio click-through of Repair is the remaining gate.>@@ -48,6 +49,32 @@>> **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.+>+> **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").+> - **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.+> - **Two keys, two jobs.** Capture = PostHog **Project** key (`phc_…`, write-only, turns the pings on). Fleet = PostHog **Personal** API key (`phx_…`, read-only, turns the dashboard numbers on). Both in Settings → *Maintainer / self-hosting keys*; env overrides `PHOSPHENE_ANALYTICS_KEY` / `_QUERY_KEY`; self-host via `PHOSPHENE_ANALYTICS_HOST` / `_API_HOST`.+>+> **Validation (code-level — a Codex GPU experiment held the box, so the live panel was NOT restarted).** `python3 scripts/test_analytics_dryrun.py` — **35/35 pass**, no network, isolated temp state dir: zero sockets with no key; nothing written at all when disabled; exact field set asserted per event against the doc; non-leakage proven including a prompt quoted inside an exception message (exact-secret redaction runs *before* path stripping) and paths the job never mentioned (HF cache, venv); forbidden-key dropping; bucketing; log rotation; local aggregates. The **real** `Handler` was then served on a spare port (8478, isolated state dir, no worker/GPU/helper): `GET /stats/usage` → 200 with correct local aggregates and zero leakage in the response body; `GET /settings` exposes `analytics_enabled` + `has_analytics_*` booleans + the install id, and never the raw keys. The dashboard section was driven through fleet / local-fallback / empty / endpoint-404 payloads in a browser against a throwaway static server — all four render correctly, and a 404 (older panel) leaves the section hidden. **Remaining gate: a live-panel pass — boot disclosure line, the Settings toggle round-trip, and a real render writing a `render_completed` row.**++> **🎛 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 — 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.+> - `a4e033a`+`b3f46a5` **#44 M1 Metal watchdog kill in Gemma prompt-encode** — NOT the Enhance feature (mandatory text encoder; every LTX render). Panel now sniffs the watchdog signature and retries the job ONCE with `LTX2_GEMMA_MAX_LENGTH=256`, sticky per boot, never pre-emptive — healthy Macs byte-identical. Also documented why user env `export`s never reach the panel (Pinokio `shell.run` replaces env wholesale; only `start.js` `env` entries arrive). OPEN pending reporter's 256-token datapoint (if THAT still times out → driver issue, upstream).+> - `a420eec` **#48 Extend progressive distortion** — Extend consumed the visible `_720p` EXPORT (2 resamples + 2 H.264 generations before the VAE) → now resolves the hidden native via sidecar (`_native_render_for()`); `_ensure_downscaled` squashed aspect 3.85% (independent /32 floors) → aspect-preserving scale+crop, dims unchanged. **NOT fixed (upstream, vendored):** per-round re-encode of the accumulated clip + audio resampled to 16 kHz per round before the audio VAE (the audible bulk; >8 kHz destroyed per extend) — candidate for a dgrauet upstream PR, same lane as AdaLN. Stated plainly on the issue. OPEN.+> - `a21e188` **#36 placement-aware integrity** — deep-verify + `/status` now catch *shadow* (undeclared same-name file differing from the declared copy) and *displaced* (declared file missing but same-name candidate elsewhere; size-matched candidates hashed only then). 9/9 unit cases incl. false-positive traps; 0 findings on this machine's real install. CLOSED.+> - `59ed751` **#35 train preflight poisoned its own well** — the one-click download pulled the Q4 repo's ~11 GB QUANTIZED transformer-dev (trainer refuses it via `FULL_DEV_MIN_BYTES` → dead LoRA) and showed green at a 1 KB presence gate. Now downloads `dgrauet/ltx-2.3-mlx-q8` (~21 GB full-precision, matching the trainer's q8-sibling resolution) and `ready` requires ≥15 GB. 6/6 sparse-file unit cases. #35 OPEN pending reporter (voice-LoRA regression is separate).+> - Response-only: **#30** (48 GB truth: cap_tier hides nothing at 48 GB — the separate `<64 GB` boundary shapes jobs; real numbers given, no promises), **#24** (enhancer is positive-only; a ~90-term default negative already rides CFG paths — auto-negative isn't a uniform win), **#21** (alt-base training blocked by inference-path match, honest requirements listed), **#46** (audio_start_time supported by pipelines+helper but never wired into the panel — plumbing task filed; A2V collapses past ~257 frames ≈ 10.7 s @24fps, workaround ≤10 s given), **#47** (prompting guide answer, CLOSED; publicly owned the Avoid-field gap: silently ignored in Control/Colorize/Ingredients and under H3).+> - Also from the sweep: JS training-preset fallback drifted (3000/5000/7000 vs real 8000/12000/20000); `docs/API.md` documents an `enhance` param with no consumers; `_train_install_dev_transformer` was item 3 of #36 and is now `59ed751`. Deferred live gates (panel restart still blocked by the GPU campaign): #44 fallback on a real M1, #48 end-to-end extend chain, #45 visual once the panel restarts.+Current `dev` head: see `git log -1` for the live SHA. `dev` tracks `beta/main` (private repo — see §1).> ## 🆕 IN PROGRESS on `dev` 2026-08-03 — **Hailuo H3 as a SECOND video engine** (not pushed, VERSION untouched)@@ -93,7 +120,7 @@ Current `dev` head: see `git log -1` for the live SHA. `dev` tracks `beta/main`> **Session 2026-07-20 — Pinokio notifications + GitHub triage + #35/#36 training fix + identity scrub (beta `3164512`, still v3.2.13, NOT public):**> - **Pinokio inbox → zero.** Answered all 3 substantive @bizarro posts: **@hottboytank** (auto-titled "python3.11 NOT FOUND", but the real blocker is **macOS 13 Ventura** — `mlx 0.31.1` has no `macosx_13_0` wheel, so `ltx_core_mlx` never installs; also 8 GB M1, under floor → told him to upgrade to macOS 14+); **@fardad_resin** (#showcase resin-pendant Reel prompt → 3 tips: Q8 for macro detail, video can't render legible calligraphy, image→video for the hero shot); **@shaurya11** (transformers-5.13.0 crash, self-resolved → warm close). Marked all read.> - **GitHub: PR queue emptied, every open issue answered.** **PR #29** (@anton-vsh A2V distilled) adopted onto beta (was already in `d335c7c`) + **closed** as adopted. Issues: **#43** (samuellzengkang) = the harmless stats-403 → replied + FIXED (below); **#36** (@saved-j) → replied owning the 6-day silence + real diagnosis + immediate workaround; **#34** circle-back (auto-close in a few days if silent); #35 kept open (tracks the training fix); #30/#24/#21 unchanged.-> - **🔧 #35/#36 training fix on beta (`6da73bf`), NOT public — needs a clean-install train-run validation first.** `_patch_loader_prefer_dev_transformer` only checked the dev file *existed*, not its precision → a **4-bit quantized dev (~11 GB)** in the Q4 dir got loaded → near-zero LoRA (exactly @saved-j's #36). Now **size-aware**: full dev ~19 GB vs quantized ~11 GB; prefers the largest dev ≥15 GB across the Q4 dir + Q8 sibling, warns loudly on a shadowing quantized one. Error msg corrected 11→19 GB. **@saved-j's voice-LoRA regression is SEPARATE** (voice never touches the dev transformer) — asked him for the first ~40 train-log lines. **TODO: reproduce from a clean install with saved-j's attached Archive.zip, then promote.**+> - **🔧 #35/#36 training fix — SHIPPED PUBLIC in v3.4.1** (verified present on `main` 2026-08-05; the "needs clean-install validation" gate below was overtaken by the release train). Companion fix `59ed751` (2026-08-05): the Train preflight itself was still DOWNLOADING the quantized Q4 dev and green-lighting it at a 1 KB presence gate — now pulls the ~21 GB full-precision Q8 copy and requires ≥15 GB to show ready. `_patch_loader_prefer_dev_transformer` only checked the dev file *existed*, not its precision → a **4-bit quantized dev (~11 GB)** in the Q4 dir got loaded → near-zero LoRA (exactly @saved-j's #36). Now **size-aware**: full dev ~19 GB vs quantized ~11 GB; prefers the largest dev ≥15 GB across the Q4 dir + Q8 sibling, warns loudly on a shadowing quantized one. Error msg corrected 11→19 GB. **@saved-j's voice-LoRA regression is SEPARATE** (voice never touches the dev transformer) — asked him for the first ~40 train-log lines. **TODO: reproduce from a clean install with saved-j's attached Archive.zip, then promote.**> - **🔒 Identity scrub (`b04fc8b`)**: `elontrn`/`Eltrumpo` (politically-loaded) appeared in **8 internal comments across ROADMAP.md + train_character.py + mlx_ltx_panel.py — and were ALREADY in PUBLIC v3.2.6.** Renamed to neutral `chartest`; comment-only, no logic change. Reaches public with the next promote.> - **🔧 #43 stats-noise fix (`3164512`)**: the stats-dashboard fetch 403 (token scope / rate limit) was pushed as "stats: fetch failed" every cycle → users filed it as a bug. Now warns **once**, phrased as a harmless maintainer-only refresh skip, re-arms on the next success.> - **PUBLIC-PROMOTE PUNCH-LIST (all gated on Mr Bizarro's OK + from-zero validation):** (1) **character-on-Q4 face decision** — PR #29 relaxed the Q8-forced-character gate so 16 GB users get character on Q4 at a softer-identity cost; the Q8 reference face is rendered (`mlx_outputs/cinematic_waist_up_medium_close_up.mp4`), the Q4 side is still un-rendered → DECISION NEEDED before promote. (2) validate the #35/#36 train fix on a clean install (saved-j's data). (3) **macOS-14 installer preflight** still TODO (promised @hottboytank) — fail early with a clear "needs macOS 14+" instead of the cryptic mlx-wheel error.diff --git a/install.js b/install.jsindex 27b9fbc..33509c8 100644--- a/install.js+++ b/install.js@@ -5,7 +5,8 @@// pinokio.js). Every step below is safe to repeat://// - clone: skipped if ltx-2-mlx/.git exists-// - venv: skipped if env/bin/python3.11 exists (force 3.11)+// - venv: reused when its interpreter actually runs; rebuilt when+// it doesn't (self-healing — see that step's note)// - uv pip: idempotent (already-installed packages are no-ops)// - patch: patch_ltx_codec.py is idempotent + fails loud on drift// - hf download: resumes partial files, skips intact ones@@ -125,15 +126,43 @@ module.exports = {// to download 35 GB of weights into a broken venv. So we explicitly// create the venv with `uv venv --python 3.11` before any pip step.//- // Idempotency: if env/bin/python3.11 already exists we skip. If env- // exists but is 3.10 (our exact failure mode), nuke and rebuild — those- // dirs only hold a wrong-Python venv, no user data.+ // SELF-HEALING, and deliberately NOT gated on `when: !exists(...)` —+ // the same latent bug fixed for Hailuo H3 in v3.4.0's "installed other+ // packs and H3 vanished" regression (install_h3.js, 3c9bdf6). `uv venv`+ // creates the interpreter as a symlink chain into Pinokio's SHARED+ // managed Python (verified — this venv has the identical chain):+ // env/bin/python3.11 -> python+ // env/bin/python -> <pinokio>/cache/XDG_DATA_HOME/uv/python/+ // cpython-3.11-macos-aarch64-none/bin/python3.11+ // That target is Pinokio's, not ours. Any other pack install — or any+ // other Pinokio app — that makes uv re-resolve, bump or prune the+ // managed interpreter leaves the chain DANGLING while env/ still+ // exists. A path-existence guard cannot handle that state: depending on+ // whether the check stats the link or its target, a dangling chain+ // reads as either present (rebuild silently skipped → a broken venv+ // that re-running Install can never fix) or absent. So we ask the only+ // question that matters — does the interpreter RUN? — inside the+ // shell, and rebuild only when it doesn't. python3.11 specifically+ // (not python): a legacy conda-3.10 venv (the failure mode above) has+ // a working `python` but no `python3.11`, so probing python3.11 keeps+ // that rebuild path too — and it is the exact interpreter every later+ // step invokes. Healthy installs pay ~50 ms; broken ones rebuild in+ // ~5 min with zero re-downloads. (Unlike H3, Reset+Install could+ // already recover this venv — reset.js deletes ltx-2-mlx/ wholesale —+ // but a user should never need Reset for it; env/ holds no user data.)+ //+ // One joined multi-line message (the mflux-step idiom below), so the+ // whole if/else runs as a single shell compound.{- when: "{{!exists('ltx-2-mlx/env/bin/python3.11')}}",method: "shell.run",params: {path: "ltx-2-mlx",message: [+ "echo '=== LTX venv check ==='",+ "if env/bin/python3.11 -c 'import sys' >/dev/null 2>&1; then",+ "echo 'venv healthy - reusing it'",+ "else",+ "echo 'venv missing or broken (wrong Python or dangling interpreter) - rebuilding, no models are re-downloaded'",// v2.0.3: log the toolchain BEFORE creating the venv so the// install log self-documents which Python uv landed on. A user// (KTDS) hit a silent "ModuleNotFoundError: ltx_pipelines_mlx"@@ -163,8 +192,9 @@ module.exports = {"uv venv --python 3.11 --seed env","echo '=== venv created ==='","ls -la env/bin/python* 2>&1 || echo 'venv create FAILED'",- "env/bin/python --version || echo 'venv python NOT executable'"- ]+ "env/bin/python --version || echo 'venv python NOT executable'",+ "fi"+ ].join("\n")}},diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex 24724c8..869714a 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -353,13 +353,35 @@ def _settings_defaults() -> dict:# Memory/speed policy. Defaults to Auto so 5 s clips keep the fast# full-decode path while long/high-pressure renders stay protected."memory_policy": DEFAULT_MEMORY_POLICY,- # NOTE: opt-in anonymous telemetry was experimented with in- # 2026-05 and removed on 2026-05-22 (see commit history) — Mr- # Bizarro chose to stay on GitHub-data-only signal (see- # docs/stats.html + scripts/fetch_repo_stats.py) rather than- # ship anything that touches the user's render path. Existing- # panel_settings.json files may still have analytics_* keys;- # they're now silently ignored.+ # ---- 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.+ #+ # Default ON. This is a change of posture from the 2026-05 opt-in+ # experiment that was reverted (da1d6f5) — that one was OFF by+ # default and therefore told us nothing. A settings file left over+ # from that 24-hour window may already carry+ # `analytics_enabled: false`; _load_settings() backfills with+ # setdefault, so that user's explicit opt-out is preserved rather+ # than silently flipped back on. That is the intended behaviour.+ "analytics_enabled": True,+ # 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.+ "analytics_key": "",+ # PostHog PERSONAL API key (read-only, maintainer-only). Powers the+ # fleet view on /stats/usage. Never used for capture.+ "analytics_query_key": "",+ # Last boot's optional-pack snapshot, diffed on the next boot to+ # emit pack_state_change. Panel-written, not user-editable.+ "analytics_last_packs": {},+ # Whether the one-line boot disclosure has already been printed.+ "analytics_disclosed": False,}@@ -573,9 +595,31 @@ def _validate_settings_patch(patch: dict) -> tuple[dict, str | None]:return {}, f"unknown memory_policy: {policy}"out["memory_policy"] = policy- # analytics_enabled / analytics_install_id used to be validated here;- # both removed 2026-05-22 when opt-in analytics was rolled back. Any- # legacy keys in panel_settings.json are now silently ignored.+ # ---- Anonymous usage analytics -------------------------------------+ # Additive only: three user-settable fields. `analytics_install_id`,+ # `analytics_last_packs` and `analytics_disclosed` are deliberately NOT+ # accepted here — they're panel bookkeeping written via+ # _settings_set_internal(), and a form must not be able to set the+ # install id (that would let a page correlate installs).+ if "analytics_enabled" in patch:+ # Same urlencoded-bool coercion as spicy_mode / models_card_dismissed.+ v = patch["analytics_enabled"]+ if isinstance(v, bool):+ out["analytics_enabled"] = v+ else:+ out["analytics_enabled"] = str(v).strip().lower() in ("1", "true", "yes", "on")++ for _akey, _alabel in (("analytics_key", "PostHog project key"),+ ("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.+ 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] = valreturn out, None@@ -635,6 +679,19 @@ def get_settings_public() -> dict:"models_card_dismissed": bool(s.get("models_card_dismissed", False)),"spicy_mode": bool(s.get("spicy_mode", False)),"memory_policy": s.get("memory_policy", DEFAULT_MEMORY_POLICY),+ # Analytics. Same has_X-boolean treatment as the other secrets —+ # the keys themselves never come back over the wire. The install id+ # DOES come back: it's a random UUID with no meaning off this+ # machine, and showing users the exact identifier the panel sends+ # is the entire point of the Settings row.+ "analytics_enabled": bool(s.get("analytics_enabled", True)),+ "analytics_install_id": str(s.get("analytics_install_id", "") or ""),+ "has_analytics_key": bool(str(s.get("analytics_key", "") or "").strip()+ or ANALYTICS_KEY_DEFAULT+ or os.environ.get("PHOSPHENE_ANALYTICS_KEY", "").strip()),+ "has_analytics_query_key": bool(+ str(s.get("analytics_query_key", "") or "").strip()+ or os.environ.get("PHOSPHENE_ANALYTICS_QUERY_KEY", "").strip()),}@@ -1582,23 +1639,27 @@ def _train_required_models() -> list[dict]:is present locally. Surfaces missing models to the UI so the user canone-click download them via the existing hf flow.- Train Character requires `transformer-dev.safetensors` from the LTX-2.3- Q4 repo (the dev base — distilled is structurally wrong for training:- different sigma schedule than the trainer's flow-matching objective).- The default install ships distilled but NOT dev to save ~11 GB on disk- for users who only run inference.+ Train Character requires the FULL-PRECISION `transformer-dev.safetensors`+ from the LTX-2.3 Q8 repo (~21 GB). The dev base is required because+ distilled is structurally wrong for training (different sigma schedule+ than the trainer's flow-matching objective) — and it must be the Q8+ repo's full-precision copy because the Q4 repo's transformer-dev is+ QUANTIZED (~11 GB): the trainer refuses it (train.py's+ FULL_DEV_MIN_BYTES) since it silently trains a near-zero LoRA (#35).+ The default install ships neither, to save disk for inference-only+ users.Gemma + the rest of the Q4 stack (vae, audio, etc.) are already requiredfor inference so they should already be present, but we check anyway."""q4_local_dir = ROOT / "mlx_models" / "ltx-2.3-mlx-q4"q8_local_dir = ROOT / "mlx_models" / "ltx-2.3-mlx-q8"- q4_repo_id = "dgrauet/ltx-2.3-mlx-q4"gemma_local_dir = ROOT / "mlx_models" / "gemma-3-12b-it-4bit"gemma_repo_id = "mlx-community/gemma-3-12b-it-4bit"def _file_present(local_dir: Path, repo_id: str, filename: str,- *, extra_dirs: list[Path] | None = None) -> bool:+ *, extra_dirs: list[Path] | None = None,+ min_bytes: int = _MIN_FILE_BYTES) -> bool:"""Check known locations for a model file in this order:1. The primary local_dir (where the helper expects it by default).@@ -1636,26 +1697,37 @@ def _train_required_models() -> list[dict]:passfor c in candidates:try:- if c.exists() and c.stat().st_size >= _MIN_FILE_BYTES:+ if c.exists() and c.stat().st_size >= min_bytes:return Trueexcept OSError:continuereturn False+ # Mirror of lora_lab/train.py FULL_DEV_MIN_BYTES: anything smaller is a+ # quantized transformer-dev, which the trainer refuses. The preflight+ # must not show green on a file the trainer will reject (#35).+ _FULL_DEV_MIN_BYTES = 15 * 1000**3+items = [{"key": "ltx_dev_transformer",- "label": "LTX-2.3 dev transformer (training-only)",+ "label": "LTX-2.3 dev transformer (training-only, full precision)","blurb": "Required for training. Standard inference uses the distilled ""transformer instead; the dev transformer has the right "- "flow-matching schedule for LoRA-from-images training.",- "repo_id": q4_repo_id,+ "flow-matching schedule for LoRA-from-images training. "+ "Must be the full-precision (~21 GB) copy — a quantized "+ "dev transformer trains a LoRA that never applies.",+ "repo_id": "dgrauet/ltx-2.3-mlx-q8","filename": "transformer-dev.safetensors",- "local_dir": str(q4_local_dir),- "size_gb": 11.0,- "ready": _file_present(q4_local_dir, q4_repo_id,+ "local_dir": str(q8_local_dir),+ "size_gb": 20.6,+ # Size-gated: an 11 GB quantized dev (the old preflight's Q4+ # download, still on many disks) must show NOT-ready, because+ # the trainer refuses it and the LoRA comes out dead (#35).+ "ready": _file_present(q8_local_dir, "dgrauet/ltx-2.3-mlx-q8","transformer-dev.safetensors",- extra_dirs=[q8_local_dir]),+ extra_dirs=[q4_local_dir],+ min_bytes=_FULL_DEV_MIN_BYTES),},{"key": "gemma_text_encoder",@@ -1674,7 +1746,10 @@ def _train_required_models() -> list[dict]:def _train_install_dev_transformer(push_log) -> dict:"""Trigger an hf download for just `transformer-dev.safetensors` from- the LTX-2.3 Q4 repo. Reuses the same `hf download` binary the existing+ the LTX-2.3 Q8 repo — the FULL-PRECISION copy the trainer requires.+ (Until v3.4.1 this pulled the Q4 repo's transformer-dev, which is+ quantized: the trainer refuses it and the LoRA trains dead — #35.)+ Reuses the same `hf download` binary the existingHF download flow uses; runs synchronously in a worker thread so thecaller can stream progress (the panel currently invokes this from a/train/install endpoint that returns quickly + then polls /status).@@ -1689,8 +1764,8 @@ def _train_install_dev_transformer(push_log) -> dict:"error": f"another download is already active "f"({DOWNLOAD.get('repo_id', '?')})."}- repo_id = "dgrauet/ltx-2.3-mlx-q4"- local_dir = ROOT / "mlx_models" / "ltx-2.3-mlx-q4"+ repo_id = "dgrauet/ltx-2.3-mlx-q8"+ local_dir = ROOT / "mlx_models" / "ltx-2.3-mlx-q8"local_dir.mkdir(parents=True, exist_ok=True)hf_bin = HF_BIN if HF_BIN is not None else _resolve_hf()@@ -1717,7 +1792,8 @@ def _train_install_dev_transformer(push_log) -> dict:def _runner():try:push_log(f"[hf] dev transformer download started "- f"({repo_id} / transformer-dev.safetensors, ~11 GB).")+ f"({repo_id} / transformer-dev.safetensors, ~21 GB — "+ f"the full-precision copy training requires).")proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,text=True, bufsize=1, env=env, start_new_session=True)@@ -3162,6 +3238,220 @@ def _verify_safetensors(path: Path) -> tuple[bool, str]:return True, "ok"+# ---- Model file PLACEMENT verification ---------------------------------------+# A checksum answers "is this file's content correct?". It cannot answer "is the+# file in the right PLACE?" — and a byte-perfect weight at the wrong path fails+# just as hard as a corrupt one, while every existing check reports green:+#+# * a 4-bit `transformer-dev.safetensors` left in the Q4 dir SHADOWS the+# full-precision one in the Q8 dir. The trainer resolves the Q4 dir first, so+# it silently optimizes against quantized weights and emits a near-zero LoRA+# (GitHub #35 / #36, reported by @saved-j — every checksum passed).+# * a declared weight that got moved reads as plain "missing", so the panel+# offers a fresh ~19 GB download while the bytes sit one directory over.+#+# required_files.json already declares each file's expected RELATIVE PATH inside+# its repo dir, so placement is verifiable from the manifest we already load —+# no new metadata, no new network calls.+#+# Cost discipline: this is stat-only. One non-recursive listdir per declared+# model dir, no hashing. The deep pass may hand in a hasher, and even then a+# candidate is hashed ONLY when (a) the declared copy is MISSING — a file+# deep-verify therefore never hashed anyway — and (b) the candidate's size+# already matches the expected size. So placement verification adds zero+# full-file reads to a healthy install.+#+# False-positive discipline (these all occur on real installs):+# * weight files only. Sidecar configs (`config.json`, `tokenizer.json`)+# legitimately repeat across model dirs and are not placement-sensitive.+# * a same-NAME, same-SIZE sibling copy is benign, not a shadow: the Q4 and Q8+# repos both legitimately ship `ltx-2.3-22b-distilled-lora-384.safetensors`.+# Only a copy that DIFFERS from the declared one can mis-resolve.+# * nothing is flagged unless the declared copy actually exists to be shadowed.+# On a Q4-only install the ~11 GB dev transformer in the Q4 dir is what our+# own Train → Preflight puts there; it shadows nothing, so it stays quiet.+# * repos that aren't installed at all are skipped (an absent optional Q8 is+# not "misplaced"), and HF-cache-backed installs are skipped entirely: that+# layer is a content-addressed blob farm with symlinked snapshots, where+# placement is huggingface_hub's business, not ours.+_PLACEMENT_EXT = ".safetensors"+++def _fmt_gb(n: int) -> str:+ return f"{n / 1e9:.1f} GB"+++def _short_path(p: Path) -> str:+ """ROOT-relative when possible — matches how the manifest and UI name files."""+ try:+ return str(Path(p).relative_to(ROOT))+ except ValueError:+ return str(p)+++def _placed_size(p: Path) -> int:+ """Size in bytes, or 0 if absent/too small to be a real weight. Uses the same+ `_MIN_FILE_BYTES` floor as `_repo_missing`, so 'present' means the same thing+ here as everywhere else in the panel."""+ try:+ size = p.stat().st_size+ except OSError:+ return 0+ return size if size >= _MIN_FILE_BYTES else 0+++def _placement_dirs() -> list[tuple[dict, Path]]:+ """(repo_def, resolved_dir) for every manifest repo whose declared directory+ exists on disk. Honors the LTX_Q8_LOCAL override the rest of the panel uses."""+ out = []+ for r in _repos():+ base = Q8_LOCAL_PATH if r.get("key") == "q8" else (ROOT / r["local_dir"])+ try:+ if base.is_dir():+ out.append((r, base))+ except OSError:+ continue+ return out+++def _placement_errors(expected: dict | None = None, hasher=None) -> list[dict]:+ """Audit installed weights against the placement the manifest declares.++ Returns entries in the exact shape the header and checksum checks emit —+ ``{"repo", "file", "reason"}`` — so /status, the red banner, the boot warning+ and one-click Repair all consume them unchanged. (Repair is also the correct+ cure for a shadow copy: it deletes that repo's copy of the file and re-runs+ the download, whose `download_include` allowlist never puts it back.) Two+ extra keys — ``placement``/``found_at``/``expected_at`` — ride along for+ consumers that want the two paths without parsing prose.++ expected: optional {(repo_key, relpath): {"size": int, "sha256": str}} of+ known-good metadata (upstream HF info, supplied by the deep pass).+ The manifest's own `file_sizes` block is always used as a fallback.+ hasher: optional callable(Path) -> sha256 hex, supplied by the deep pass so+ a relocated file can be confirmed by CONTENT rather than by name.+ """+ dirs = _placement_dirs()+ meta = dict(expected or {})++ declared: list[tuple[dict, Path, str]] = [] # (repo, dir, relpath)+ pairs: set[tuple[str, str]] = set() # (dir, relpath) the manifest declares+ homes: dict[str, list[tuple[dict, Path, str]]] = {} # basename -> declared homes+ for r, base in dirs:+ for rel in r.get("files", []):+ if not rel.endswith(_PLACEMENT_EXT):+ continue+ declared.append((r, base, rel))+ pairs.add((str(base), rel))+ homes.setdefault(Path(rel).name, []).append((r, base, rel))+ man_size = int((r.get("file_sizes") or {}).get(rel, 0) or 0)+ if man_size and not meta.get((r["key"], rel), {}).get("size"):+ meta.setdefault((r["key"], rel), {})["size"] = man_size++ out: list[dict] = []+ seen: set[tuple[str, str]] = set()++ def _flag(repo_key: str, fname: str, reason: str, found: str, want: str) -> None:+ if (repo_key, fname) in seen:+ return+ seen.add((repo_key, fname))+ out.append({"repo": repo_key, "file": fname, "reason": reason,+ "placement": True, "found_at": found, "expected_at": want})++ # Pass 1 — SHADOW copies. A weight sitting in a declared model dir under a+ # name the manifest places somewhere ELSE, whose content differs from the+ # declared copy. Reported against the repo that OWNS THE DIRECTORY holding+ # the stray, so Repair deletes the stray and never the good copy.+ for r, base in dirs:+ try:+ names = sorted(os.listdir(base))+ except OSError:+ continue+ for name in names:+ if not name.endswith(_PLACEMENT_EXT) or (str(base), name) in pairs:+ continue+ candidates = homes.get(name) or []+ if not candidates:+ continue # a name we never place anywhere — the user's own file+ stray = base / name+ stray_size = _placed_size(stray)+ if not stray_size:+ continue+ for _hr, hbase, hrel in candidates:+ if hbase == base:+ continue # same dir, different relpath — not a misplacement+ home = hbase / hrel+ home_size = _placed_size(home)+ if not home_size or home_size == stray_size:+ continue # nothing to shadow (Pass 2's job), or a benign twin+ _flag(r["key"], name,+ f"misplaced: {_short_path(stray)} ({_fmt_gb(stray_size)}) is not a "+ f"file this model declares, and it shadows the real {name} at "+ f"{_short_path(home)} ({_fmt_gb(home_size)}) - anything that "+ f"resolves this directory first loads the wrong weights",+ _short_path(stray), _short_path(home))+ break++ # Pass 2 — DISPLACED files. A declared weight is missing from where it+ # belongs while a same-named file sits in another declared model dir. This is+ # the case the plain "missing" report turns into a needless multi-GB+ # re-download. Only runs for repos that are actually installed, so an absent+ # optional repo is never described as misplaced.+ for r, base, rel in declared:+ if not any(_placed_size(base / f) for f in r.get("files", [])):+ continue # repo not installed here at all — not our business+ home = base / rel+ if _placed_size(home):+ continue # exactly where it should be+ name = Path(rel).name+ want = meta.get((r["key"], rel), {})+ want_size = int(want.get("size") or 0)+ want_sha = want.get("sha256") or ""+ for _r2, base2 in dirs:+ if base2 == base:+ continue+ cand = base2 / name+ if (str(base2), name) in pairs and _placed_size(cand):+ continue # that dir declares this name too — it's their copy+ cand_size = _placed_size(cand)+ if not cand_size:+ continue+ detail = (f"same name, {_fmt_gb(cand_size)} - verify it is the same "+ f"file before moving it")+ if want_size and cand_size != want_size:+ detail = (f"that copy is {_fmt_gb(cand_size)}, not the expected "+ f"{_fmt_gb(want_size)} - a different build of {name}, "+ f"so it will not stand in for the missing file")+ elif want_size and want_sha and hasher is not None:+ # The only hash placement ever asks for: the declared copy is+ # missing (so the checksum pass skipped it) and the candidate's+ # size already matches. Net-zero extra hashing on a healthy install.+ got = ""+ try:+ got = hasher(cand)+ except OSError as e: # unreadable candidate is not fatal+ detail = f"could not read that copy to confirm it ({e})"+ if got == want_sha:+ detail = (f"same content (sha256 matches) - move it back instead of "+ f"re-downloading {_fmt_gb(cand_size)}")+ elif got:+ detail = ("same size but different content (sha256 mismatch) - "+ "not the missing file")+ elif want_size and cand_size == want_size:+ detail = (f"same name and exactly the expected {_fmt_gb(want_size)} - "+ f"almost certainly the missing file in the wrong folder")+ else:+ detail = (f"same name, {_fmt_gb(cand_size)} - run Verify (deep) to "+ f"confirm it is the same file before moving it")+ _flag(r["key"], rel,+ f"wrong location: expected at {_short_path(home)}, found at "+ f"{_short_path(cand)} - {detail}",+ _short_path(cand), _short_path(home))+ break++ return out++_INTEGRITY_LOCK = threading.Lock()_INTEGRITY_CACHE: dict = {"ts": 0.0, "data": None}@@ -3198,6 +3488,20 @@ def _model_integrity(force: bool = False) -> dict:if not ok:result["ok"] = Falseresult["bad"].append({"repo": r["key"], "file": fname, "reason": reason})+ # Placement audit — right content, wrong path. Folded into the same bad[] the+ # banner, boot warning and Repair already consume. It is stat-only, so it is+ # safe in the /status path, and unlike the header scan above it deliberately+ # runs for INCOMPLETE repos too: "a declared file is missing here and the+ # bytes are one directory over" is exactly what it exists to catch.+ try:+ already = {(b["repo"], b["file"]) for b in result["bad"]}+ placement = [p for p in _placement_errors()+ if (p["repo"], p["file"]) not in already]+ except Exception: # noqa: BLE001 — integrity must never break /status+ placement = []+ if placement:+ result["ok"] = False+ result["bad"].extend(placement)with _INTEGRITY_LOCK:_INTEGRITY_CACHE["ts"] = now_INTEGRITY_CACHE["data"] = result@@ -3225,11 +3529,15 @@ _DEEP_VERIFY_LOCK = threading.Lock()_DEEP_VERIFY: dict = {"active": False, "result": None, "progress": "", "started_ts": 0.0}-def _upstream_shas(repo_id: str) -> dict:- """filename -> published SHA-256 from HuggingFace LFS metadata, cached for+def _upstream_meta(repo_id: str) -> dict:+ """filename -> {"sha256", "size"} from HuggingFace LFS metadata, cached forthe session (upstream rarely changes mid-session). Returns {} on anynetwork/lib failure — the caller treats 'unknown' as unverifiable, never as- corrupt, so a flaky lookup can never trigger a spurious re-download."""+ corrupt, so a flaky lookup can never trigger a spurious re-download.++ The published SIZE comes back in the same `files_metadata=True` response as+ the checksum (no extra request), and the placement audit uses it to decide+ whether a relocated file is even worth hashing."""with _UPSTREAM_SHA_LOCK:if repo_id in _UPSTREAM_SHA_CACHE:return _UPSTREAM_SHA_CACHE[repo_id]@@ -3240,9 +3548,14 @@ def _upstream_shas(repo_id: str) -> dict:token=_active_hf_token() or None)for s in info.siblings:lfs = getattr(s, "lfs", None)- sha = lfs.get("sha256") if isinstance(lfs, dict) else getattr(lfs, "sha256", None)- if sha:- out[s.rfilename] = sha+ if isinstance(lfs, dict):+ sha, lfs_size = lfs.get("sha256"), lfs.get("size")+ else:+ sha = getattr(lfs, "sha256", None)+ lfs_size = getattr(lfs, "size", None)+ size = int(lfs_size or getattr(s, "size", 0) or 0)+ if sha or size:+ out[s.rfilename] = {"sha256": sha or "", "size": size}except Exception as e: # noqa: BLE001 — network/lib failure → unverifiablepush(f"[deep-verify] upstream checksum lookup failed for {repo_id}: {e}")return {}@@ -3251,6 +3564,13 @@ def _upstream_shas(repo_id: str) -> dict:return out+def _upstream_shas(repo_id: str) -> dict:+ """filename -> published SHA-256. Thin view over `_upstream_meta` (same+ single cached lookup); files upstream publishes without a checksum are+ omitted, so callers still read a missing key as 'unverifiable'."""+ return {k: v["sha256"] for k, v in _upstream_meta(repo_id).items() if v.get("sha256")}++def _sha256_file(path: Path) -> str:h = hashlib.sha256()with open(path, "rb") as fh:@@ -3274,7 +3594,7 @@ 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 = _upstream_shas(repo_id)+ up = {k: v["sha256"] for k, v in _upstream_meta(repo_id).items() if v.get("sha256")}for fname in repo_def.get("files", []):if not fname.endswith(".safetensors"):continue@@ -3304,6 +3624,25 @@ def _deep_verify_thread() -> None:"repo": r["key"], "file": fname,"reason": f"checksum mismatch (stale/corrupt: upstream {exp[:10]}…, local {local[:10]}…)",})+ # Placement audit — right content, WRONG PATH. A checksum pass is blind+ # to it by construction: every byte can be correct and the loader still+ # resolves the wrong file (#35/#36). Hand it the published sizes and+ # checksums (already cached from the lookups above) so a relocated weight+ # can be confirmed by CONTENT, then fold findings into the same bad[].+ 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", [])):+ continue # not installed here — don't ask upstream+ for fname, m in _upstream_meta(repo_id).items():+ exp_meta[(r["key"], fname)] = m+ already = {(b["repo"], b["file"]) for b in result["bad"]}+ for p in _placement_errors(expected=exp_meta, hasher=_sha256_file):+ if (p["repo"], p["file"]) in already:+ continue+ result["ok"] = False+ result["bad"].append(p)except Exception as e: # noqa: BLE001 — must never crash the thread silentlyresult["error"] = str(e)finally:@@ -3314,9 +3653,16 @@ def _deep_verify_thread() -> None:if result.get("error"):push(f"[deep-verify] error: {result['error']}")elif not result.get("ok"):- push("[deep-verify] DONE — checksum mismatch on: "- + ", ".join(f"{b['repo']}/{b['file']}" for b in result["bad"])- + ". Use Repair to re-download.")+ _misplaced = [b for b in result["bad"] if b.get("placement")]+ _corrupt = [b for b in result["bad"] if not b.get("placement")]+ _msg = "[deep-verify] DONE — "+ if _corrupt:+ _msg += ("checksum mismatch on: "+ + ", ".join(f"{b['repo']}/{b['file']}" for b in _corrupt)+ + ". Use Repair to re-download. ")+ if _misplaced:+ _msg += "misplaced file(s): " + "; ".join(b["reason"] for b in _misplaced)+ push(_msg.strip())else:uv = len(result.get("unverified") or [])push(f"[deep-verify] DONE — all {result['checked']} weight file(s) match upstream"@@ -4730,6 +5076,883 @@ def h3_status() -> dict:}+# ---- Anonymous usage analytics ----------------------------------------------+#+# History first, because this file has some: an OPT-IN telemetry module+# shipped 2026-05-21 and was reverted wholesale the next day (da1d6f5) —+# "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 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+# keys and _analytics_scrub_text() strips absolute paths out of the one+# free-text field that exists (error_signature) before truncating it.+# * IT CANNOT SLOW OR BREAK A RENDER. Every capture returns immediately;+# delivery happens on a daemon thread with a 2 s timeout and a bare+# `except Exception: pass` around the whole path. That property is the+# one this module must never lose — if analytics ever raises into a+# render, the bug is here, not in the caller.+# * IT IS VISIBLE AND REVERSIBLE. One line in the boot log the first time+# it runs, a Settings toggle (default ON), and a plain-text local mirror+# at state/usage-log.jsonl showing exactly what this panel would send.+#+# Event volume is deliberately tiny: one app_boot per panel start, zero or+# more pack_state_change at the same moment, and one event per finished job.+# There are NO heartbeats and NO background timers in this module.++# Empty string = analytics disabled at the source. This constant stays ""+# in the public tree; the maintainer supplies the real key at runtime via+# Settings or PHOSPHENE_ANALYTICS_KEY so it is never committed.+ANALYTICS_KEY_DEFAULT = ""+# PostHog ingestion host (capture). Override for a self-hosted receiver.+ANALYTICS_HOST_DEFAULT = "https://us.i.posthog.com"+# PostHog app host (HogQL query API — different host from ingestion).+# Only used by the maintainer-only fleet view on /stats/usage.+ANALYTICS_API_HOST_DEFAULT = "https://us.posthog.com"+ANALYTICS_TIMEOUT_SEC = 2.0+ANALYTICS_STR_MAX = 120++# 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+# state/ (gitignored, fs.link-preserved across Pinokio Reset) and is capped+# so a heavy user's log can't grow without bound.+USAGE_LOG_FILE = STATE_DIR / "usage-log.jsonl"+USAGE_LOG_MAX_BYTES = 5 * 1024 * 1024+USAGE_FLEET_CACHE = STATE_DIR / "usage-fleet.json"+USAGE_FLEET_TTL_SEC = 6 * 60 * 60+_USAGE_LOG_LOCK = threading.Lock()++# Keys that must never appear in an event payload. This is defense in depth,+# not the primary control — no call site passes any of these — but a future+# edit that spreads `**params` into a props dict would otherwise leak the+# user's prompt to a server. _analytics_clean_props() drops them by name.+_ANALYTICS_FORBIDDEN_KEYS = frozenset({+ "prompt", "negative_prompt", "override_prompt", "caption",+ "image", "image_path", "images", "audio", "audio_path", "video",+ "output", "output_path", "raw_output", "native_output", "path", "paths",+ "file", "filename", "files", "dir", "directory", "root",+ "first_frame", "last_frame", "refs", "reference", "seed_image",+ "lora", "loras", "lora_path", "lora_paths", "character", "trigger",+ "trigger_words", "hostname", "username", "user", "email", "home",+ "command", "cmd", "argv", "env", "token", "key", "api_key",+})++# Absolute-path shapes to redact from error signatures. Applied in order:+# the anchored pass catches the macOS roots a Phosphene error is likely to+# quote, the generic pass catches anything else with 2+ path segments.+_ANALYTICS_PATH_RES = (+ re.compile(r"(?:~|/(?:Users|home|private|var|tmp|opt|Volumes|Applications"+ r"|Library|System))(?:/[^\s'\"<>,;)\]]*)*"),+ re.compile(r"(?:/[\w.+\-]+){2,}/?"),+)+_ANALYTICS_UUID_RE = re.compile(+ r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")+++def _settings_set_internal(**kv) -> None:+ """Persist panel-internal settings keys that never come from a form.++ `update_settings()` runs the user-input whitelist, which by design+ rejects anything not in it. Analytics bookkeeping (`install_id`, the+ last-known pack snapshot, the one-time disclosure flag) is written by+ the panel itself, so it goes straight to the store. Fail-silent: losing+ a bookkeeping write costs at most one duplicate boot event."""+ try:+ with _SETTINGS_LOCK:+ _SETTINGS.update(kv)+ _save_settings(_SETTINGS)+ except Exception:+ pass+++def _analytics_enabled() -> bool:+ """Master switch. Settings toggle (default ON), with an env kill-switch+ 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."""+ if _optional_bool_env("PHOSPHENE_ANALYTICS_DISABLED") is True:+ return False+ return bool(get_settings().get("analytics_enabled", True))+++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"."""+ env = (os.environ.get("PHOSPHENE_ANALYTICS_KEY") or "").strip()+ if env:+ return env+ saved = str(get_settings().get("analytics_key") or "").strip()+ return saved or ANALYTICS_KEY_DEFAULT+++def _analytics_query_key() -> str:+ """PostHog PERSONAL API key — read-only, maintainer-only, used solely by+ the fleet view on /stats/usage. Separate from the capture key on+ purpose: the capture key is write-only and safe to ship in a binary,+ the personal key can read the whole project and must not be."""+ env = (os.environ.get("PHOSPHENE_ANALYTICS_QUERY_KEY") or "").strip()+ if env:+ return env+ return str(get_settings().get("analytics_query_key") or "").strip()+++def _analytics_host() -> str:+ return (os.environ.get("PHOSPHENE_ANALYTICS_HOST")+ or ANALYTICS_HOST_DEFAULT).strip().rstrip("/")+++def _analytics_api_host() -> str:+ return (os.environ.get("PHOSPHENE_ANALYTICS_API_HOST")+ or ANALYTICS_API_HOST_DEFAULT).strip().rstrip("/")+++def _analytics_install_id() -> str:+ """Random UUID4 generated once and persisted to panel_settings.json.++ This is the ONLY identifier that leaves the machine. It is not derived+ from anything — not the hardware serial, not the MAC address, not the+ username, not the install path. Deleting panel_settings.json (or the+ key) makes this install a brand-new anonymous install with no way to+ correlate it to the old one.++ A value that isn't a well-formed UUID4 (e.g. the 32-char hex id the+ reverted 2026-05 module wrote) is discarded and regenerated."""+ cur = str(get_settings().get("analytics_install_id") or "").strip().lower()+ if _ANALYTICS_UUID_RE.match(cur):+ return cur+ import uuid as _uuid+ new = str(_uuid.uuid4())+ _settings_set_internal(analytics_install_id=new)+ return new+++def _analytics_scrub_text(text, secrets=()) -> str:+ """Reduce free text to a safe one-line signature.++ Order matters. Exact user strings (this job's prompt, its image path)+ are redacted FIRST — an exception message that quotes the prompt is the+ realistic leak, and exact-substring removal is the only defense that+ provably catches it. Then absolute paths, then whitespace collapse,+ then a hard truncation. Returns "" for anything unusable."""+ try:+ s = str(text or "").strip()+ if not s:+ return ""+ s = s.splitlines()[0]+ for secret in secrets or ():+ sec = str(secret or "").strip()+ # 6 chars is short enough to catch a terse prompt and long+ # enough not to blank out ordinary words in an error string.+ if len(sec) >= 6 and sec in s:+ s = s.replace(sec, "<redacted>")+ for rx in _ANALYTICS_PATH_RES:+ s = rx.sub("<path>", s)+ s = " ".join(s.split())+ return s[:ANALYTICS_STR_MAX]+ except Exception:+ return ""+++def _analytics_clean_props(props: dict) -> dict:+ """Whitelist-by-shape pass over an outgoing property dict.++ Drops forbidden keys outright, keeps only JSON primitives (plus a+ single level of flat dict, which `packs` needs), and truncates every+ string. Anything unexpected is dropped rather than coerced — a prop we+ can't reason about is a prop we don't send."""+ out: dict = {}+ for key, val in (props or {}).items():+ k = str(key)+ if k.lower() in _ANALYTICS_FORBIDDEN_KEYS:+ continue+ if isinstance(val, bool) or isinstance(val, int) or isinstance(val, float):+ out[k] = val+ elif isinstance(val, str):+ out[k] = val[:ANALYTICS_STR_MAX]+ elif val is None:+ out[k] = None+ elif isinstance(val, dict):+ flat = {}+ for sk, sv in val.items():+ if str(sk).lower() in _ANALYTICS_FORBIDDEN_KEYS:+ continue+ if isinstance(sv, (bool, int, float)) or sv is None:+ flat[str(sk)] = sv+ elif isinstance(sv, str):+ flat[str(sk)] = sv[:ANALYTICS_STR_MAX]+ out[k] = flat+ return out+++def _analytics_duration_bucket(seconds) -> str:+ """Bucket an elapsed time. Buckets, not raw seconds, because a raw+ duration plus a resolution plus a timestamp starts to look like a+ fingerprint; the buckets answer the only question we actually have+ ("is this tier usable on real hardware?") without that risk."""+ try:+ s = float(seconds or 0)+ except (TypeError, ValueError):+ return "unknown"+ if s <= 0:+ return "unknown"+ if s < 120:+ return "<2m"+ if s < 300:+ return "2-5m"+ if s < 900:+ return "5-15m"+ if s < 2400:+ return "15-40m"+ return ">40m"+++def _analytics_os_version() -> str:+ """macOS version as major.minor ("26.4"). Patch level is dropped — it+ adds no signal and narrows the anonymity set."""+ try:+ import platform as _platform+ ver = (_platform.mac_ver()[0] or "").strip()+ if not ver:+ return "unknown"+ return ".".join(ver.split(".")[:2])+ except Exception:+ return "unknown"+++_CHIP_FAMILY_CACHE: str | None = None+_CHIP_FAMILY_RE = re.compile(r"\bM(\d+)\s*(Pro|Max|Ultra)?\b", re.IGNORECASE)+++def _analytics_chip_family() -> str:+ """Chip class from the CPU brand string: 'Apple M4 Max' -> 'M4 Max'.++ This is a hardware CLASS, not a hardware ID — every M4 Max on earth+ reports the same string. It is the field that answers "does this+ feature work on the machines people actually own?", which is the+ question that made the H3 tier table honest."""+ global _CHIP_FAMILY_CACHE+ if _CHIP_FAMILY_CACHE is not None:+ return _CHIP_FAMILY_CACHE+ family = "unknown"+ try:+ brand = subprocess.run(+ ["sysctl", "-n", "machdep.cpu.brand_string"],+ capture_output=True, text=True, timeout=2,+ ).stdout.strip()+ m = _CHIP_FAMILY_RE.search(brand)+ if m:+ family = f"M{m.group(1)}" + (f" {m.group(2).title()}" if m.group(2) else "")+ elif brand:+ family = "non-apple-silicon"+ except Exception:+ pass+ _CHIP_FAMILY_CACHE = family+ return family+++def _qwen_pack_available() -> bool:+ """Whether the optional Qwen image pack's mflux binary is installed.+ Same probe the /agent/image/config endpoint uses for its family pills."""+ try:+ probe = agent_image_engine.ImageEngineConfig(+ kind="mflux", mflux_family="qwen_edit")+ return bool(agent_image_engine._resolve_mflux_bin(probe))+ except Exception:+ return False+++def _analytics_pack_state() -> dict:+ """Current install state of the four optional packs. Booleans only.++ Diffed against the previous boot's snapshot to emit pack_state_change.+ A true->false transition is the 'my H3 vanished' bug class: the pack+ was installed, then a panel Update / Pinokio Reset / venv breakage made+ it undetectable. Nothing in the panel notices that today; this does."""+ return {+ "h3": bool(h3_available()),+ "sharp": bool(PIPERSR_UPSCALE_ENABLED),+ "q8": bool(q8_available_anywhere()),+ "qwen": bool(_qwen_pack_available()),+ }+++def _usage_log_rotate() -> None:+ """Halve the local mirror when it hits the cap. Keeps the NEWEST half —+ the dashboard's windows are all 7/14-day, so old lines have no readers.+ Rewrites in place via the same temp+replace shape the rest of the panel+ uses so a kill mid-rotate can't truncate the log to nothing."""+ try:+ lines = USAGE_LOG_FILE.read_text(encoding="utf-8", errors="replace").splitlines()+ except OSError:+ return+ keep = lines[len(lines) // 2:]+ tmp = USAGE_LOG_FILE.with_name(f".{USAGE_LOG_FILE.name}.{os.getpid()}.tmp")+ try:+ tmp.write_text("\n".join(keep) + ("\n" if keep else ""), encoding="utf-8")+ os.replace(tmp, USAGE_LOG_FILE)+ except OSError:+ try: tmp.unlink()+ except OSError: pass+++def _usage_log_append(record: dict) -> None:+ """Append one JSON line to the local mirror. Never raises."""+ try:+ _ensure_state_dir()+ line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"+ with _USAGE_LOG_LOCK:+ try:+ if USAGE_LOG_FILE.stat().st_size + len(line) > USAGE_LOG_MAX_BYTES:+ _usage_log_rotate()+ except OSError:+ pass # missing file is the normal first-write case+ with USAGE_LOG_FILE.open("a", encoding="utf-8") as fh:+ fh.write(line)+ except Exception:+ pass+++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)."""+ key = _analytics_key()+ if not key:+ return # no key => inert, and this is the only guard that matters+ body = json.dumps({+ "api_key": key,+ "event": payload["event"],+ "distinct_id": payload["install_id"],+ "timestamp": payload["utc"],+ "properties": {+ **payload["props"],+ "$process_person_profile": False,+ },+ }).encode("utf-8")+ req = urllib.request.Request(+ f"{_analytics_host()}/i/v0/e/",+ data=body,+ headers={"Content-Type": "application/json",+ "User-Agent": "phosphene-panel-analytics"},+ method="POST",+ )+ with urllib.request.urlopen(req, timeout=ANALYTICS_TIMEOUT_SEC) as resp:+ resp.read(256) # drain so the socket closes cleanly; body unused+++def _analytics_deliver(payload: dict) -> None:+ """Thread body: mirror locally, then try the network. Fail-silent.++ The local write happens FIRST and unconditionally, so a dead endpoint+ or an absent key still leaves the maintainer a complete record on this+ machine. Nothing here is retried — a dropped event is strictly+ preferable to a queue that outlives the render it describes."""+ try:+ _usage_log_append(payload)+ except Exception:+ pass+ try:+ _analytics_post(payload)+ except Exception:+ pass # network down, endpoint 500, bad key, offline Mac — all fine+++def _analytics_capture(event: str, props: dict | None = None) -> None:+ """Record one event. Returns immediately; never raises; never blocks.++ This is the only entry point call sites should use. Everything after+ the thread start is best-effort by design — see the module note above+ for why that contract is non-negotiable."""+ try:+ if not _analytics_enabled():+ return+ payload = {+ "event": str(event)[:64],+ "props": _analytics_clean_props(props or {}),+ "install_id": _analytics_install_id(),+ "ts": time.time(),+ "at": iso_now(),+ "utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),+ }+ except Exception:+ return+ try:+ threading.Thread(target=_analytics_deliver, args=(payload,),+ name="analytics-capture", daemon=True).start()+ except Exception:+ pass+++def _analytics_disclose_once() -> None:+ """One line, once per install, in the boot log. Users find out that the+ panel does this from the panel itself — not from a docs page they'd+ have to go looking for. ASCII only (emoji in panel stdout can break the+ Pinokio/helper handshake — see 2026-06-02)."""+ if get_settings().get("analytics_disclosed"):+ return+ print(+ "Phosphene sends anonymous usage counts (version, hardware class, "+ "render stats, error signatures - never your prompts or media). "+ "Disable in Settings.",+ flush=True,+ )+ _settings_set_internal(analytics_disclosed=True)+++def _analytics_boot() -> None:+ """Emit app_boot plus any pack transitions since the previous boot.++ Called once from __main__ — never at import time, so `import+ mlx_ltx_panel` from a test or a script sends nothing."""+ try:+ if not _analytics_enabled():+ return+ _analytics_disclose_once()+ packs = _analytics_pack_state()+ _analytics_capture("app_boot", {+ "version": _read_local_version() or "unknown",+ "os_version": _analytics_os_version(),+ "chip_family": _analytics_chip_family(),+ "ram_gb": int(round(SYSTEM_RAM_GB)),+ "cap_tier": _resolve_cap_tier(),+ "packs": packs,+ "h3_chain_supported": bool(packs["h3"] and h3_supports_chain()),+ })+ prev = get_settings().get("analytics_last_packs")+ if isinstance(prev, dict):+ for name in sorted(packs):+ was = prev.get(name)+ if isinstance(was, bool) and was != packs[name]:+ _analytics_capture("pack_state_change", {+ "pack": name, "from": was, "to": packs[name],+ })+ _settings_set_internal(analytics_last_packs=packs)+ except Exception:+ pass+++def _analytics_job_secrets(job: dict) -> list:+ """Exact strings from this job that must never survive into an error+ signature. Collected from the job itself so the redaction is exact+ rather than heuristic — see _analytics_scrub_text()."""+ p = (job or {}).get("params") or {}+ out = []+ for k in ("prompt", "negative_prompt", "image", "audio", "output",+ "first_frame", "last_frame", "character", "train_job_id"):+ v = p.get(k)+ if isinstance(v, str) and v.strip():+ out.append(v.strip())+ for k in ("output", "error_path"):+ v = (job or {}).get(k)+ if isinstance(v, str) and v.strip():+ out.append(v.strip())+ return out+++def _analytics_render_tier(params: dict, engine: str) -> str:+ """The user-facing quality/tier selector for this job, per engine.+ LTX calls it `quality` (quick/balanced/standard/high); H3 calls it+ `h3_tier` (3s/5s/10s/15s). One field in the event, either way."""+ if engine == "h3":+ return str(params.get("h3_tier") or "unknown")+ return str(params.get("quality") or params.get("mode") or "unknown")+++def _analytics_render_event(job: dict) -> None:+ """Emit render_completed / render_failed for a finished queue job.++ Wired at the single point in worker_loop's `finally` where every job+ from every engine lands, so LTX, H3, image and training jobs are all+ covered by one call and a future engine gets counted for free.+ Cancelled jobs are deliberately not reported (a user cancelling is not+ a signal about the software)."""+ try:+ status = (job or {}).get("status")+ if status not in ("done", "failed"):+ return+ p = (job or {}).get("params") or {}+ engine = str(p.get("engine") or "ltx").strip().lower()+ try:+ width, height = int(p.get("width") or 0), int(p.get("height") or 0)+ except (TypeError, ValueError):+ width = height = 0+ try:+ frames = int(p.get("frames") or 0)+ except (TypeError, ValueError):+ frames = 0+ props = {+ "engine": engine,+ "mode": str(p.get("mode") or "unknown"),+ "tier": _analytics_render_tier(p, engine),+ "duration_bucket": _analytics_duration_bucket(job.get("elapsed_sec")),+ "resolution": f"{width}x{height}" if width and height else "unknown",+ "frames": frames,+ }+ if status == "failed":+ props["error_signature"] = _analytics_scrub_text(+ job.get("error"), _analytics_job_secrets(job))+ _analytics_capture(+ "render_completed" if status == "done" else "render_failed", props)+ except Exception:+ pass+++# ---- Usage report: local aggregates + optional fleet view -------------------+#+# Feeds the "Usage" section of the maintainer dashboard at /stats, the same+# way the GitHub sections are fed by scripts/fetch_repo_stats.py. Two tiers,+# and the dashboard renders whichever it gets:+#+# LOCAL — aggregated from state/usage-log.jsonl, i.e. this Mac only.+# Always available, needs no keys, works offline. This is also+# the debugging view for the fleet pings: whatever the panel+# would have sent is sitting in that file in plain text.+# FLEET — aggregated by PostHog over every install that has pinged,+# via the HogQL query API. Requires a PostHog PERSONAL API key+# (Settings -> analytics_query_key), which is read-only and+# maintainer-only. Cached to state/usage-fleet.json for 6 h so+# an open dashboard tab can't hammer the query API.+#+# Both endpoints are 127.0.0.1-only via the early _is_local_request guard,+# like everything else on this server.++_USAGE_FLEET_LOCK = threading.Lock()+++def _usage_log_read(max_age_days: float | None = None) -> list[dict]:+ """Parse the local mirror. Bad lines are skipped, not fatal — this file+ is append-only from several threads and a torn last line is possible."""+ out: list[dict] = []+ try:+ raw = USAGE_LOG_FILE.read_text(encoding="utf-8", errors="replace")+ except OSError:+ return out+ cutoff = (time.time() - max_age_days * 86400) if max_age_days else None+ for line in raw.splitlines():+ line = line.strip()+ if not line:+ continue+ try:+ rec = json.loads(line)+ except (json.JSONDecodeError, ValueError):+ continue+ if not isinstance(rec, dict) or "event" not in rec:+ continue+ if cutoff is not None:+ try:+ if float(rec.get("ts") or 0) < cutoff:+ continue+ except (TypeError, ValueError):+ continue+ out.append(rec)+ return out+++def _usage_rank(counter: dict, key_name: str, limit: int = 12) -> list[dict]:+ """{value: count} -> sorted [{<key_name>: value, "count": n}] rows."""+ rows = sorted(counter.items(), key=lambda kv: (-kv[1], str(kv[0])))+ return [{key_name: k, "count": v} for k, v in rows[:limit]]+++def _usage_local_report() -> dict:+ """Aggregate the local mirror into the dashboard's payload shape.++ Deliberately the SAME shape the fleet path produces, so stats.html has+ exactly one renderer and the only difference the user sees is the+ `source` label and the note above the tiles."""+ recs = _usage_log_read()+ now = time.time()+ d7, d14 = now - 7 * 86400, now - 14 * 86400++ boots_by_day: dict[str, int] = {}+ engines: dict[str, int] = {}+ errors: dict[str, int] = {}+ versions: dict[str, int] = {}+ chips: dict[str, int] = {}+ rams: dict[str, int] = {}+ flips: dict[tuple, int] = {}+ renders_7d = ok_14d = fail_14d = 0+ h3_14d = tot_14d = 0+ active_7d = False++ for rec in recs:+ try:+ ts = float(rec.get("ts") or 0)+ except (TypeError, ValueError):+ continue+ ev = str(rec.get("event") or "")+ props = rec.get("props") if isinstance(rec.get("props"), dict) else {}+ if ts >= d7:+ active_7d = True+ if ev == "app_boot":+ if ts >= d14:+ day = time.strftime("%Y-%m-%d", time.localtime(ts))+ boots_by_day[day] = boots_by_day.get(day, 0) + 1+ versions[str(props.get("version") or "unknown")] = \+ versions.get(str(props.get("version") or "unknown"), 0) + 1+ chips[str(props.get("chip_family") or "unknown")] = \+ chips.get(str(props.get("chip_family") or "unknown"), 0) + 1+ ram_key = str(props.get("ram_gb") or "unknown")+ rams[ram_key] = rams.get(ram_key, 0) + 1+ elif ev in ("render_completed", "render_failed"):+ if ts >= d7:+ renders_7d += 1+ if ts >= d14:+ tot_14d += 1+ eng = str(props.get("engine") or "unknown")+ engines[eng] = engines.get(eng, 0) + 1+ if eng == "h3":+ h3_14d += 1+ if ev == "render_completed":+ ok_14d += 1+ else:+ fail_14d += 1+ if ev == "render_failed" and ts >= d7:+ sig = str(props.get("error_signature") or "unknown error")+ errors[sig] = errors.get(sig, 0) + 1+ elif ev == "pack_state_change" and ts >= d7:+ k = (str(props.get("pack") or "?"),+ bool(props.get("from")), bool(props.get("to")))+ flips[k] = flips.get(k, 0) + 1++ flip_rows = [{"pack": p, "from": f, "to": t, "count": c}+ for (p, f, t), c in sorted(flips.items(), key=lambda kv: -kv[1])]+ h3_lost = sum(r["count"] for r in flip_rows+ if r["pack"] == "h3" and r["from"] and not r["to"])++ return {+ "ok": True,+ "source": "local",+ "generated_at": iso_now(),+ "cached": False,+ "note": ("this machine only - add a PostHog query key in Settings "+ "for fleet data"),+ "tiles": {+ "weekly_active_installs": 1 if active_7d else 0,+ "renders_7d": renders_7d,+ "h3_share_pct": round(100.0 * h3_14d / tot_14d, 1) if tot_14d else None,+ "error_rate_pct": (round(100.0 * fail_14d / (ok_14d + fail_14d), 1)+ if (ok_14d + fail_14d) else None),+ },+ "boots_by_day": [{"date": d, "count": boots_by_day[d]}+ for d in sorted(boots_by_day)],+ "engines": _usage_rank(engines, "engine", 8),+ "top_errors": [{"signature": k, "count": v} for k, v in+ sorted(errors.items(), key=lambda kv: (-kv[1], kv[0]))[:5]],+ "versions": _usage_rank(versions, "version"),+ "chips": _usage_rank(chips, "chip"),+ "ram": _usage_rank(rams, "ram_gb"),+ "pack_flips": {"h3_lost": h3_lost, "rows": flip_rows},+ "events_logged": len(recs),+ }+++# HogQL fragments for the fleet view. Kept as a table (not inline strings)+# so the whole surface the personal API key touches is auditable in one+# place: eight read-only aggregate SELECTs over `events`, nothing else.+# `properties['x']` bracket form throughout — `properties.from` would+# collide with the SQL keyword in the pack_state_change query.+_USAGE_FLEET_QUERIES = {+ "wau": "SELECT count(DISTINCT distinct_id) FROM events "+ "WHERE event = 'app_boot' AND timestamp > now() - INTERVAL 7 DAY",+ "dau": "SELECT count(DISTINCT distinct_id) FROM events "+ "WHERE event = 'app_boot' AND timestamp > now() - INTERVAL 1 DAY",+ "boots_by_day":+ "SELECT toDate(timestamp) AS d, count() AS c FROM events "+ "WHERE event = 'app_boot' AND timestamp > now() - INTERVAL 14 DAY "+ "GROUP BY d ORDER BY d",+ "engines":+ "SELECT properties['engine'] AS e, count() AS c FROM events "+ "WHERE event IN ('render_completed', 'render_failed') "+ "AND timestamp > now() - INTERVAL 14 DAY GROUP BY e ORDER BY c DESC",+ "outcomes":+ "SELECT event, count() AS c FROM events "+ "WHERE event IN ('render_completed', 'render_failed') "+ "AND timestamp > now() - INTERVAL 14 DAY GROUP BY event",+ "top_errors":+ "SELECT properties['error_signature'] AS sig, count() AS c FROM events "+ "WHERE event = 'render_failed' AND timestamp > now() - INTERVAL 7 DAY "+ "GROUP BY sig ORDER BY c DESC LIMIT 5",+ "versions":+ "SELECT properties['version'] AS v, count(DISTINCT distinct_id) AS c "+ "FROM events WHERE event = 'app_boot' "+ "AND timestamp > now() - INTERVAL 14 DAY GROUP BY v ORDER BY c DESC LIMIT 12",+ "chips":+ "SELECT properties['chip_family'] AS chip, count(DISTINCT distinct_id) AS c "+ "FROM events WHERE event = 'app_boot' "+ "AND timestamp > now() - INTERVAL 14 DAY GROUP BY chip ORDER BY c DESC LIMIT 12",+ "ram":+ "SELECT properties['ram_gb'] AS ram, count(DISTINCT distinct_id) AS c "+ "FROM events WHERE event = 'app_boot' "+ "AND timestamp > now() - INTERVAL 14 DAY GROUP BY ram ORDER BY c DESC LIMIT 12",+ "pack_flips":+ "SELECT properties['pack'] AS pack, properties['from'] AS was, "+ "properties['to'] AS now_, count() AS c FROM events "+ "WHERE event = 'pack_state_change' AND timestamp > now() - INTERVAL 7 DAY "+ "GROUP BY pack, was, now_ ORDER BY c DESC",+}+++def _usage_fleet_query_one(hogql: str, key: str) -> list:+ """Run one HogQL query. Returns the `results` rows, or [] on any error.++ 10 s timeout (not the 2 s capture timeout — this is a human waiting on a+ dashboard, not a render path). Raises nothing; the caller treats an+ empty result as "this panel of the dashboard has no data"."""+ body = json.dumps({"query": {"kind": "HogQLQuery", "query": hogql}}).encode("utf-8")+ project = (os.environ.get("PHOSPHENE_ANALYTICS_PROJECT") or "@current").strip()+ req = urllib.request.Request(+ f"{_analytics_api_host()}/api/projects/{quote(project)}/query/",+ data=body,+ headers={"Content-Type": "application/json",+ "Authorization": f"Bearer {key}",+ "User-Agent": "phosphene-panel-stats"},+ method="POST",+ )+ with urllib.request.urlopen(req, timeout=10) as resp:+ data = json.loads(resp.read().decode("utf-8", "replace"))+ rows = data.get("results")+ return rows if isinstance(rows, list) else []+++def _usage_fleet_report() -> dict | None:+ """Build the fleet payload, or None when no query key is configured.++ Every sub-query is independent: one failing (rate limit, schema drift,+ a property that no install has sent yet) leaves that panel empty rather+ than collapsing the whole view back to local. If EVERY query fails we+ return None so the caller falls back to local with a warning."""+ key = _analytics_query_key()+ if not key:+ return None+ res: dict[str, list] = {}+ failures = 0+ for name, hogql in _USAGE_FLEET_QUERIES.items():+ try:+ res[name] = _usage_fleet_query_one(hogql, key)+ except Exception:+ res[name] = []+ failures += 1+ if failures == len(_USAGE_FLEET_QUERIES):+ return None++ def _scalar(name):+ rows = res.get(name) or []+ try:+ return rows[0][0]+ except (IndexError, TypeError):+ return None++ outcomes = {str(r[0]): int(r[1]) for r in (res.get("outcomes") or [])+ if isinstance(r, (list, tuple)) and len(r) >= 2}+ ok_n = outcomes.get("render_completed", 0)+ fail_n = outcomes.get("render_failed", 0)+ engines = [{"engine": str(r[0] or "unknown"), "count": int(r[1])}+ for r in (res.get("engines") or [])+ if isinstance(r, (list, tuple)) and len(r) >= 2]+ tot = sum(e["count"] for e in engines)+ h3 = sum(e["count"] for e in engines if e["engine"] == "h3")++ flip_rows = []+ for r in (res.get("pack_flips") or []):+ if not (isinstance(r, (list, tuple)) and len(r) >= 4):+ continue+ flip_rows.append({+ "pack": str(r[0] or "?"),+ "from": str(r[1]).lower() in ("true", "1"),+ "to": str(r[2]).lower() in ("true", "1"),+ "count": int(r[3]),+ })+ h3_lost = sum(r["count"] for r in flip_rows+ if r["pack"] == "h3" and r["from"] and not r["to"])++ return {+ "ok": True,+ "source": "fleet",+ "generated_at": iso_now(),+ "cached": False,+ "note": "",+ "partial": failures > 0,+ "tiles": {+ "weekly_active_installs": _scalar("wau"),+ "daily_active_installs": _scalar("dau"),+ "renders_7d": ok_n + fail_n,+ "h3_share_pct": round(100.0 * h3 / tot, 1) if tot else None,+ "error_rate_pct": (round(100.0 * fail_n / (ok_n + fail_n), 1)+ if (ok_n + fail_n) else None),+ },+ "boots_by_day": [{"date": str(r[0]), "count": int(r[1])}+ for r in (res.get("boots_by_day") or [])+ if isinstance(r, (list, tuple)) and len(r) >= 2],+ "engines": engines,+ "top_errors": [{"signature": str(r[0] or "unknown error"), "count": int(r[1])}+ for r in (res.get("top_errors") or [])+ if isinstance(r, (list, tuple)) and len(r) >= 2],+ "versions": [{"version": str(r[0] or "unknown"), "count": int(r[1])}+ for r in (res.get("versions") or [])+ if isinstance(r, (list, tuple)) and len(r) >= 2],+ "chips": [{"chip": str(r[0] or "unknown"), "count": int(r[1])}+ for r in (res.get("chips") or [])+ if isinstance(r, (list, tuple)) and len(r) >= 2],+ "ram": [{"ram_gb": str(r[0] or "unknown"), "count": int(r[1])}+ for r in (res.get("ram") or [])+ if isinstance(r, (list, tuple)) and len(r) >= 2],+ "pack_flips": {"h3_lost": h3_lost, "rows": flip_rows},+ }+++def _usage_report(force: bool = False) -> dict:+ """What GET /stats/usage returns. Fleet when a query key is configured+ and the 6 h cache is stale; otherwise the cache; otherwise local."""+ with _USAGE_FLEET_LOCK:+ if _analytics_query_key():+ if not force:+ try:+ cached = json.loads(USAGE_FLEET_CACHE.read_text(encoding="utf-8"))+ if (time.time() - float(cached.get("_fetched_at") or 0)+ < USAGE_FLEET_TTL_SEC):+ cached["cached"] = True+ return cached+ except (OSError, ValueError, json.JSONDecodeError):+ pass+ fleet = None+ try:+ fleet = _usage_fleet_report()+ except Exception:+ fleet = None+ if fleet:+ fleet["_fetched_at"] = time.time()+ try:+ _ensure_state_dir()+ atomic_write_text(USAGE_FLEET_CACHE,+ json.dumps(fleet, indent=2))+ except Exception:+ pass+ return fleet+ local = _usage_local_report()+ local["warning"] = ("PostHog query failed - showing this machine "+ "only. Check the personal API key in Settings.")+ return local+ return _usage_local_report()++def _scale_dims_to_max(width: int, height: int, max_dim: int,*, align: int = 32) -> tuple[int, int]:"""Scale dimensions down to max_dim while preserving aspect and alignment."""@@ -4974,6 +6197,62 @@ def _probe_video_dims(path: str) -> tuple[int, int]:return 0, 0+def _native_render_for(src: Path) -> Path:+ """The un-exported render behind `src`, when there is one.++ Every export pass (`fit_720p`, `fit_1080p`, `x2`, the H3 export) writes+ `<stem>_<tag>.mp4` NEXT TO the native render, hides the native from the+ gallery via `set_hidden`, and records the pair in the exported file's+ sidecar as `native_output`. The gallery therefore only ever OFFERS the+ export — so every surface that feeds a clip back into a model was+ silently consuming a lanczos-resampled, re-encoded, sometimes+ black-bar-padded copy instead of the pixels the model actually made.++ Concretely, on a 1024×576 render exported to 720p and then extended:+ 1024×576 (native) → 1280×720 (upscale + H.264 re-encode) → 768×416+ (Extend's own downscale + another re-encode). Two full-frame resamples+ and two lossy generations before the VAE ever sees a pixel, and the+ letterbox bars an export can add become content the model is asked to+ continue. Resolving back to the native skips the entire round-trip.++ Returns the native file when the sidecar names one and it is still on+ disk; otherwise `src` unchanged (own-render sidecars point at+ themselves, which this treats as "no native to resolve")."""+ try:+ sidecar = src.with_suffix(src.suffix + ".json")+ if not sidecar.is_file():+ return src+ data = json.loads(sidecar.read_text(encoding="utf-8")) or {}+ except (OSError, ValueError): # ValueError covers JSONDecodeError+ return src+ if not isinstance(data, dict):+ return src+ # Compare RESOLVED paths: a sidecar stores absolute paths while the+ # caller may hold a relative one, and `Path("a/b") != Path("/x/a/b")`+ # even when they are the same file. Without this an own-render sidecar+ # (`raw_output` == itself) would look like a different, better source+ # and we'd log a confusing "using the native render X instead of the+ # export X".+ try:+ src_key = src.resolve()+ except OSError:+ src_key = src+ for key in ("native_output", "raw_output"):+ cand = data.get(key)+ if not cand:+ continue+ try:+ cand_path = Path(str(cand))+ if not (cand_path.is_file() and cand_path.stat().st_size > 1024):+ continue+ if cand_path.resolve() == src_key:+ continue+ return cand_path+ except OSError:+ continue+ return src++def _ensure_downscaled(src: Path, max_dim: int = 768, align: int = 32) -> Path:"""If `src` has its longer side > max_dim, write a downscaled losslesscopy alongside it and return that. Cached on disk by target dimensions@@ -4983,7 +6262,17 @@ def _ensure_downscaled(src: Path, max_dim: int = 768, align: int = 32) -> Path:source's native resolution. On 64 GB Macs, 1280×704 + dev transformer+ CFG-style guided denoising peaks past ~50 GB resident and pushes8-12 GB into swap, making each step take 4 minutes instead of 25- seconds. Pre-downscaling to ≤768 max-side fits cleanly in RAM."""+ seconds. Pre-downscaling to ≤768 max-side fits cleanly in RAM.++ ASPECT (fixed 2026-08): both target dimensions are floored to a+ multiple of `align` INDEPENDENTLY, so the aligned box almost never+ carries the source's aspect ratio — 1280×720 (1.778) lands on 768×416+ (1.846). The filter used to be a bare `scale=W:H`, which forces those+ dimensions and therefore squashed every frame ~3.9% vertically before+ the model saw it. Scale-to-cover + centre-crop keeps the geometry+ exact instead, at the cost of ≤31 px trimmed on one axis. Crop rather+ than pad on purpose: pillar/letterbox bars would become in-frame+ content that the model is then asked to continue."""src_w, src_h = _probe_video_dims(str(src))if not src_w or not src_h or max(src_w, src_h) <= max_dim:return src@@ -5003,7 +6292,9 @@ def _ensure_downscaled(src: Path, max_dim: int = 768, align: int = 32) -> Path:# dies at downscale time. Was silent for a while because Extend wasn't# exercised after the .partial rename was added.cmd = [str(FFMPEG), "-y", "-i", str(src),- "-vf", f"scale={new_w}:{new_h}",+ "-vf", (f"scale={new_w}:{new_h}:force_original_aspect_ratio=increase"+ f":flags=lanczos:force_divisible_by=2,"+ f"crop={new_w}:{new_h}"),"-c:v", "libx264", "-pix_fmt", "yuv444p", "-crf", "0", "-preset", "veryfast","-c:a", "copy", # don't re-encode audio — extend doesn't need it transformed"-f", "mp4",@@ -5481,6 +6772,14 @@ class WarmHelper:# just log it loudly on a mismatch. Makes healthy remote bug reports# carry the version that's actually running.self.ready_info: dict = {}+ # Gemma prompt-encode fallback state (#44). `gemma_max_length` is+ # sticky for the whole panel boot once a Metal GPU-watchdog timeout+ # has been observed — every helper spawned afterwards encodes at the+ # shorter padded length, so the crash happens at most once per boot.+ # The two flags are per-run and reset at the top of _run_once().+ self.gemma_max_length: int | None = None+ self._metal_timeout_seen = False+ self._past_prompt_encode = Falsedef _ensure(self) -> None:with self.lock:@@ -5519,6 +6818,24 @@ class WarmHelper:_civ = _active_civitai_key()if _civ:env["CIVITAI_API_KEY"] = _civ+ # Gemma prompt-encode fallback (#44) — sticky once a Metal GPU+ # watchdog timeout has been seen this boot. Upstream reads+ # LTX2_GEMMA_MAX_LENGTH inside PromptEncoder.encode+ # (ltx_pipelines_mlx/utils/blocks.py) and defaults to 1024, so+ # setting it here is the whole mechanism — no patching needed.+ # A value the user pinned themselves is only overridden when+ # ours is smaller (they asked for a cap; we may need a tighter+ # one, but we never loosen theirs).+ if self.gemma_max_length is not None:+ try:+ _pinned = int(env.get("LTX2_GEMMA_MAX_LENGTH", "") or 0)+ except ValueError:+ _pinned = 0+ if _pinned <= 0 or self.gemma_max_length < _pinned:+ env["LTX2_GEMMA_MAX_LENGTH"] = str(self.gemma_max_length)+ push(f"[gemma-fallback] encoding prompts at "+ f"{self.gemma_max_length} tokens for the rest of this "+ f"session (Metal GPU watchdog seen on this machine)")push(f"Spawning warm helper (low_memory={HELPER_LOW_MEMORY}, idle_timeout={HELPER_IDLE_TIMEOUT}s)")self.proc = subprocess.Popen([str(HELPER_PYTHON), str(HELPER_SCRIPT)],@@ -5638,6 +6955,7 @@ class WarmHelper:ev = json.loads(line)except json.JSONDecodeError:push(line)+ self._sniff_helper_line(line)if log_hook is not None:try: log_hook(line)except Exception: pass@@ -5646,6 +6964,7 @@ class WarmHelper:if ev_type == "log":log_line = ev.get("line", "")push(log_line)+ self._sniff_helper_line(log_line)if log_hook is not None:try: log_hook(log_line)except Exception: pass@@ -5750,7 +7069,97 @@ class WarmHelper:return log_hook, panic_check+ # ---- Gemma prompt-encode watchdog fallback (#44) ---------------------+ #+ # 2026-08 (#44, @BobDixon58, M1 Max 32 GB): every render died in+ # `[Encoding prompt]` with+ # [METAL] Command buffer execution failed: Caused GPU Timeout Error+ # (00000002:kIOGPUCommandBufferCallbackErrorTimeout)+ # MLX raises that from the Metal completion-queue thread as an uncaught+ # C++ exception, so it lands as SIGABRT — the helper process is GONE and+ # no try/except inside it can ever catch this. The panel is the only+ # place left that can react, which is why the recovery lives here.+ #+ # The lever is the padded sequence length Gemma encodes at. Upstream's+ # PromptEncoder.encode reads LTX2_GEMMA_MAX_LENGTH (default 1024); each+ # of the 48 Gemma blocks costs O(T) in its MLP and O(T^2) in attention,+ # so dropping 1024 -> 256 is ~4x less MLP and ~16x less attention inside+ # the single command buffer the watchdog is timing. Prompts are+ # truncated from the LEFT (upstream keeps the last T tokens), so a+ # normal prompt is untouched. This is NOT applied pre-emptively — it+ # costs conditioning headroom on very long prompts, so it only arms+ # itself after this machine has actually proven it needs it.+ _METAL_TIMEOUT_RX = re.compile(+ r"kIOGPUCommandBufferCallbackErrorTimeout|Caused GPU Timeout Error",+ re.IGNORECASE)+ # Anything proving the run got PAST prompt encoding. If the watchdog+ # fires later than that (denoise, decode), a shorter prompt encode is+ # not the fix and an automatic retry would just burn another render.+ _PAST_PROMPT_ENCODE_RX = re.compile(+ r"Denoising|\[Decoding|Loading transformer|step:denoise",+ re.IGNORECASE)+ # Overridable for anyone who needs a different landing spot.+ GEMMA_FALLBACK_MAX_LENGTH = max(+ 64, int(os.environ.get("LTX_GEMMA_FALLBACK_MAX_LENGTH", "256") or 256))++ def _sniff_helper_line(self, line: str) -> None:+ """Watch every helper line for the Metal GPU-watchdog signature.++ Called for BOTH the JSON `log` events and the raw non-JSON lines —+ the crash line is C++ stderr (`libc++abi: terminating due to ...`),+ never a structured event, so sniffing only the log events would+ miss the one line that matters.+ """+ if not line:+ return+ if not self._metal_timeout_seen and self._METAL_TIMEOUT_RX.search(line):+ self._metal_timeout_seen = True+ if not self._past_prompt_encode and self._PAST_PROMPT_ENCODE_RX.search(line):+ self._past_prompt_encode = True++ def _gemma_fallback_applies(self) -> bool:+ """True when the run that just died is a retryable Gemma-encode+ watchdog kill: signature seen, still inside prompt encoding, no+ fallback armed yet this boot, and the helper really is dead (so+ there is nothing half-done to collide with)."""+ # A /stop that lands in the same instant as the crash must win —+ # never resurrect a job the user just cancelled.+ with LOCK:+ cur = STATE.get("current")+ if cur is not None and cur.get("cancel_requested"):+ return False+ return (self._metal_timeout_seen+ and not self._past_prompt_encode+ and self.gemma_max_length is None+ and not self.is_alive())+def run(self, job_spec: dict) -> dict:+ """Run a job, with one automatic retry at a shorter Gemma prompt+ encode if the macOS GPU watchdog killed this machine's encode.++ The retry is deliberately cheap and bounded: the timeout happens+ before ANY sampling or output is written, the helper is already+ dead (so _ensure respawns it with the shorter length), and the+ fallback arms at most once per panel boot — every later job in the+ session spawns pre-mitigated instead of crashing again.+ """+ try:+ return self._run_once(job_spec)+ except RuntimeError:+ if not self._gemma_fallback_applies():+ raise+ self.gemma_max_length = self.GEMMA_FALLBACK_MAX_LENGTH+ push(f"[gemma-fallback] the macOS GPU watchdog killed prompt "+ f"encoding on this chip. Retrying this job once with Gemma "+ f"encoding at {self.gemma_max_length} tokens instead of 1024 "+ f"— nothing was rendered yet, so no work is lost.")+ return self._run_once(job_spec)++ def _run_once(self, job_spec: dict) -> dict:+ # Per-run detector state — reset here so a watchdog kill seen on an+ # earlier job can't arm the fallback for an unrelated failure.+ self._metal_timeout_seen = False+ self._past_prompt_encode = False# Whole-run serialization so concurrent callers don't both park in# _read_until and grab each other's done/error events. See __init__# for why this is distinct from self.lock.@@ -5796,21 +7205,45 @@ class WarmHelper:# prompt encoding — "[METAL] Command buffer execution failed:# Caused GPU Timeout Error". Name it, because the generic# "assertion failed" sends people hunting the wrong thing.- # Note LTX2_GEMMA_EVAL_EVERY is already 1 (the smallest- # command-buffer setting) so there is no knob left to turn —- # this is an engine/driver issue worth reporting upstream.+ # LTX2_GEMMA_EVAL_EVERY is already 1 (the smallest+ # command-buffer setting). CORRECTION (2026-08): the+ # earlier note here said that left no knob to turn —+ # wrong. The *width* of that buffer is still tunable via+ # LTX2_GEMMA_MAX_LENGTH, which upstream reads in+ # PromptEncoder.encode; see the Gemma fallback block+ # below, which arms it automatically on a detected kill."SIGABRT": ("C-level abort. If the log shows '[METAL] Command buffer ""execution failed: Caused GPU Timeout Error', this is the ""macOS GPU watchdog killing an over-long Metal command ""buffer (seen on M1/M2-class GPUs during prompt encoding). "- "Phosphene already runs the smallest command buffers it "- "can (LTX2_GEMMA_EVAL_EVERY=1), so please open an issue "- "with your chip + macOS version and the crashlog at "+ "Phosphene retries prompt encoding once at a shorter "+ "padded length when it sees that line; if it never "+ "reached the panel, please open an issue with your chip "+ "+ macOS version and the crashlog at ""~/Library/Logs/DiagnosticReports/python3.11_*.ips"),"SIGBUS": "memory access fault — could indicate a Metal driver issue or a bad weight file",}.get(sig_name, "external kill")+ # #44: when the watchdog signature is actually in this job's+ # log, stop hedging — name it outright and say what we already+ # tried. The conditional SIGABRT wording above still covers the+ # case where the line never reached us.+ if self._metal_timeout_seen:+ _tried = (+ f" Prompt encoding was already retried at "+ f"{self.gemma_max_length} tokens and still timed out."+ if self.gemma_max_length is not None else ""+ )+ hint = (+ "the macOS GPU watchdog killed a Metal command buffer "+ "(kIOGPUCommandBufferCallbackErrorTimeout) — that line is "+ "in this job's log, so this is a driver-level kill, not a "+ "Phosphene assertion." + _tried + " Please add your chip + "+ "macOS version and the crashlog at "+ "~/Library/Logs/DiagnosticReports/python3.11_*.ips to "+ "https://github.com/mrbizarro/phosphene/issues/44"+ )raise RuntimeError(f"helper exited from {sig_name} ({hint}); returncode={rc}")@@ -6786,6 +8219,17 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,_h3_upscale = "fit_1080p"if _h3_upscale not in H3_UPSCALE_MODES:_h3_upscale = H3_UPSCALE_DEFAULT+ # Sampler depth override for an H3 render ("Steps" pills). 0 = Auto = the+ # tier's tuned count (9 → 8 forwards, the validated speed/quality point).+ # The official reference recipe runs 20; wall time scales ~(steps-1)/8.+ _h3_steps_raw = (f("h3_steps", "") or "").strip().lower()+ if _h3_steps_raw in ("", "auto", "0"):+ _h3_steps = 0+ else:+ try:+ _h3_steps = max(4, min(30, int(_h3_steps_raw)))+ except (TypeError, ValueError):+ _h3_steps = 0if _engine == "h3":if mode_in not in H3_MODES:push(f"engine=h3 requested for mode={mode_in!r} — Hailuo H3 only "@@ -6831,6 +8275,10 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,# fit_1080p). SAME allowlist trap as every key in this dict: a new# form field that isn't listed here silently no-ops on /queue/add."h3_upscale": _h3_upscale,+ # Steps override for H3 (0 = Auto = tier default). Kept alongside+ # the resolved `steps` below so the ⓘ modal can say the default+ # was overridden. Same allowlist trap as above.+ "h3_steps": _h3_steps,"prompt": prompt,"negative_prompt": f("negative_prompt", ""),"width": max(32, int(f("width", str(default_w)) or default_w)),@@ -6966,7 +8414,10 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,# the per-window count, so the queue card and the duration line read the# clip the user actually gets. run_h3_job_inner splits it back out.job["params"]["frames"] = _tier_cfg["frames"]- job["params"]["steps"] = _tier_cfg["steps"]+ # Tier steps unless the user pinned a depth on the Steps pills —+ # run_h3_job_inner reads this resolved value, so the override rides+ # the SAME path the tier default does (nothing downstream branches).+ job["params"]["steps"] = int(_h3_steps or _tier_cfg["steps"])job["params"]["h3_chain_windows"] = int(_tier_cfg.get("chain_windows") or 1)job["params"]["h3_window_frames"] = int(_tier_cfg.get("window_frames") or _tier_cfg["frames"])@@ -8631,6 +10082,28 @@ def run_job_inner(job: dict) -> None:src = p["video_path"]if not src or not Path(src).exists():raise RuntimeError(f"source video for extend not found: {src}")+ # Feed the model the NATIVE render, not the export (issue #48).+ #+ # An upscaled render hides its native file from the gallery, so the+ # Extend picker can only ever offer the export — and Extend was+ # taking it at face value. That put a lanczos upscale + H.264+ # re-encode (and, when the export letterboxes, black bars) in front+ # of every extend, and then Extend's own clamp resampled the whole+ # thing back DOWN again. Chained extends therefore paid a fresh+ # resample + generation on the first hop of every chain, on top of+ # the per-round cost the pipeline already carries.+ #+ # `_native_render_for` is a no-op for clips that were never+ # exported and for extend outputs (their sidecar points at+ # themselves), so this only fires where there is a strictly better+ # file sitting right next to the one the user picked.+ picked_src = Path(src)+ native_src = _native_render_for(picked_src)+ if native_src != picked_src:+ src = str(native_src)+ push(f"Extend: using the native render {native_src.name} instead of "+ f"the export {picked_src.name} — skips an upscale + re-encode "+ f"round-trip before the model sees it.")# Resolution clamp — same fix shape as FFLF. The upstream extend# pipeline runs the dev transformer in CFG-guided mode (line 294# of extend.py — guided_denoise_loop is unconditional; cfg_scale=1.0@@ -8706,6 +10179,15 @@ def run_job_inner(job: dict) -> None:"fps": FPS, "model": str(Q8_LOCAL_PATH), "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+ # the UI, `extend_source` is what actually reached the model after+ # native-resolution + the tier clamp. A chain of these is what a+ # future "carry the pristine prior segment forward" pass needs to+ # walk, and it makes a degraded chain diagnosable from the sidecars+ # alone instead of by reading filenames.+ "extend_picked": str(picked_src),+ "extend_source": src,+ "extend_new_frames": int(p["extend_frames"]) * 8,}write_sidecar(final_out.with_suffix(final_out.suffix + ".json"), sidecar)job["output_path"] = str(final_out)@@ -10039,6 +11521,13 @@ def worker_loop() -> None:job["finished_at"] = iso_now()if job.get("started_ts"):job["elapsed_sec"] = round(time.time() - job["started_ts"], 2)+ # Anonymous usage counts. This is the single point every job+ # from every engine passes through (LTX, H3, image, training),+ # so one call covers them all and a future engine is counted+ # for free. Returns immediately and cannot raise — see the+ # analytics section's contract; it must never be able to turn+ # a finished render into a failed one.+ _analytics_render_event(job)with LOCK:STATE["history"].insert(0, job)STATE["history"] = STATE["history"][:HISTORY_LIMIT]@@ -10766,6 +12255,20 @@ class Handler(BaseHTTPRequestHandler):try: self.wfile.write(body)except (BrokenPipeError, ConnectionResetError): passreturn+ # Usage section of the same dashboard. Local aggregates from+ # state/usage-log.jsonl always; fleet aggregates from PostHog when a+ # personal API key is configured (6 h cached). `?force=1` busts the+ # cache for the dashboard's refresh button. Never raises out — a+ # broken usage view must not 500 the maintainer's stats page.+ if parsed.path == "/stats/usage":+ try:+ qs = parse_qs(parsed.query)+ report = _usage_report(force=qs.get("force", ["0"])[0] == "1")+ except Exception as exc:+ report = {"ok": False, "source": "local",+ "error": str(exc)[:200]}+ self._json(report)+ returnif parsed.path == "/status":qs = parse_qs(parsed.query)include_hidden = qs.get("include_hidden", ["0"])[0] == "1"@@ -10811,6 +12314,11 @@ class Handler(BaseHTTPRequestHandler):payload["mlx_metal_version"] = HELPER.ready_info.get("mlx_metal_version")payload["chip"] = HELPER.ready_info.get("chip")payload["macos"] = HELPER.ready_info.get("macos")+ # #44: null on a healthy machine. Non-null means this boot hit the+ # Metal GPU watchdog during prompt encoding and Gemma is now+ # encoding at the shorter padded length — the single most useful+ # field on a "my prompts feel weaker" follow-up report.+ payload["gemma_max_length"] = HELPER.gemma_max_length# Per-kind avg ETA: image jobs are 30s–2min, video jobs are# 5–30min. Computing queue ETA from one mixed avg makes an# image queued after a few videos show "~30 min" — the@@ -11736,9 +13244,11 @@ class Handler(BaseHTTPRequestHandler):# ====== Train Character — preflight model check.# required_files.json's q4 entry ships transformer-distilled only.- # Training needs transformer-dev (extra ~11 GB), which isn't in the- # default install. Surface what's missing so the UI can offer a- # one-click download via the existing hf flow.+ # Training needs the FULL-PRECISION transformer-dev from the Q8 repo+ # (extra ~21 GB), which isn't in the default install. Surface what's+ # missing so the UI can offer a one-click download via the existing+ # hf flow. (The Q4 repo's transformer-dev is quantized — the trainer+ # refuses it, #35 — so the preflight neither offers nor greenlights it.)if parsed.path == "/train/preflight":req = _train_required_models()self._json({"ok": True, "required": req,@@ -14686,9 +16196,14 @@ class Handler(BaseHTTPRequestHandler):prev.get("memory_policy", DEFAULT_MEMORY_POLICY) !=current.get("memory_policy", DEFAULT_MEMORY_POLICY))- # Analytics opt-in lifecycle removed 2026-05-22 (the entire- # analytics surface was rolled back — we stand on GitHub-data- # signal via docs/stats.html instead).+ # Anonymous usage analytics. No helper restart needed — the+ # analytics path reads get_settings() per event, in-process.+ # Log the flip so there's a visible record in the panel log+ # of a setting that governs what leaves the machine.+ if prev.get("analytics_enabled", True) != current.get("analytics_enabled", True):+ push("settings: anonymous usage analytics "+ + ("ON." if current.get("analytics_enabled", True)+ else "OFF - nothing is sent or logged."))if codec_changed:push(f"settings: output codec → {current['output_pix_fmt']} "@@ -20211,11 +21726,30 @@ HTML = r"""<!doctype html>font-size: 10px; text-transform: uppercase; letter-spacing: 0.04em;color: var(--muted); width: 52px; flex: none;}+ /* Slider needs the same chrome reset as .range-strip — the generic+ `input, textarea, select, button` rule paints every input with a+ border + panel background + 8px/11px padding, which turned this+ track into a boxed control that ate ~24px of row width on top of+ being the greedy flex child. */.lora-row .lora-strength-row input[type="range"] {flex: 1; min-width: 0; accent-color: var(--accent);+ padding: 0; border: none; background: none;}- .lora-row .lora-strength-row input[type="number"] {- width: 54px; padding: 2px 5px; font-size: 11px; text-align: right;+ /* The picker renders inside #genForm on the video form, where+ `#genForm input[type="number"]` wins on ID specificity and+ re-inflated this readout to 13px text with 10px/12px padding.+ In a 54px border-box that left ~28px of content, and the native+ spinner ate half of what was left, so the strength value was+ clipped to an unreadable sliver (issue #45). Repeat the compact+ sizing at matching specificity, pin the box with flex:none so it+ can never shrink, and give it room for the widest value ("-1.05").+ The un-prefixed selector still covers the picker when it's+ portaled to the Image Studio / Characters slots, which render+ outside the form. */+ .lora-row .lora-strength-row input[type="number"],+ #genForm .lora-row .lora-strength-row input[type="number"] {+ flex: none; width: 68px;+ padding: 2px 5px; font-size: 11px; text-align: right;}.lora-row .trigger-chips {display: flex; flex-wrap: wrap; gap: 3px; margin-top: 7px;@@ -22574,6 +24108,29 @@ HTML = r"""<!doctype html></div></div><input type="hidden" name="h3_upscale" id="h3_upscale" value="fit_720p">+ <!-- H3 sampler depth. Tiers bake 9 steps (8 forwards) — the+ validated speed/quality point; the official reference recipe+ runs 20. Four honest pills with the time cost in the tooltip+ beat an unbounded numeric box. `h3_steps` is in the make_job+ allowlist (an unlisted field silently no-ops on /queue/add). -->+ <div class="h3-export-row" id="h3StepsRow" data-h3-only>+ <span class="h3-export-label">Steps</span>+ <div class="pill-group" id="h3StepsGroup" style="display:flex;gap:4px;flex:0 0 auto;">+ <button type="button" class="pill-btn active" data-h3-steps="auto"+ style="padding:4px 10px;font-size:12px;"+ title="The tier's tuned count — the validated speed/quality point.">Auto</button>+ <button type="button" class="pill-btn" data-h3-steps="12"+ style="padding:4px 10px;font-size:12px;"+ title="More refinement — ~1.4× the tier's render time.">12</button>+ <button type="button" class="pill-btn" data-h3-steps="16"+ style="padding:4px 10px;font-size:12px;"+ title="~1.9× the tier's render time.">16</button>+ <button type="button" class="pill-btn" data-h3-steps="20"+ style="padding:4px 10px;font-size:12px;"+ title="The official reference recipe — ~2.4× the tier's render time.">20</button>+ </div>+ </div>+ <input type="hidden" name="h3_steps" id="h3_steps" value="auto"><!-- 2026-05-17 (Codex C+ pass 6): the character-only skip-steptoggle moved out of here into the Customize section as"HQ speed". It's a Q8 sampler control, not a character@@ -24407,6 +25964,89 @@ HTML = r"""<!doctype html><div class="hint" id="spicyHint" style="margin-top:8px; display:none"></div></div>+ <!-- Anonymous usage analytics. Default ON, one click to turn off, and+ the copy below is the whole truth about what leaves the machine —+ if this list and docs/ANALYTICS.md ever disagree, the code is the+ bug. The maintainer key rows live behind a <details> because+ ordinary users have no use for them; a fork that wants its own+ receiver, or the project owner switching the fleet on, pastes+ keys there. Reuses the spicy-row / token-row markup so this+ section inherits the modal's existing styling with no new CSS. -->+ <div class="settings-section">+ <h3>Anonymous usage analytics</h3>+ <div class="hint" style="margin-bottom:10px">+ Sends anonymous counts so bugs in the field get noticed: panel+ version, hardware class (e.g. <em>M4 Max, 64 GB</em>), which+ optional packs are installed, and for each render the engine,+ tier, resolution, frame count and a coarse duration bucket —+ plus the first line of the error when one fails.+ <b>Never your prompts, filenames, paths, images or video.</b>+ You are a random ID, generated on this Mac and tied to nothing.+ Everything the panel would send is also written in plain text to+ <code>state/usage-log.jsonl</code> so you can read it yourself;+ the full schema is in <code>docs/ANALYTICS.md</code>.+ </div>+ <div class="spicy-row">+ <span class="spicy-state" id="analyticsStateBadge">ON</span>+ <button type="button" class="ghost-btn" id="analyticsToggleBtn"+ onclick="toggleAnalytics()" style="margin-left:auto">+ Turn off+ </button>+ </div>+ <div class="hint" id="analyticsHint" style="margin-top:8px"></div>++ <details style="margin-top:12px">+ <summary style="cursor:pointer; font-size:12px; color:var(--muted, #9aa)">+ 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.+ </div>+ <div class="token-row">+ <div class="token-label">+ <span>PostHog project key <span class="hint">(capture)</span></span>+ <span class="token-status" id="analyticsKeyStatus">—</span>+ </div>+ <div class="token-row-input">+ <input type="password" id="analyticsKeyInput" autocomplete="off"+ placeholder="phc_…">+ <button type="button" class="ghost-btn"+ onclick="toggleTokenVisibility('analyticsKeyInput', this)">show</button>+ <button type="button" class="primary-btn token-savetest"+ onclick="saveAnalyticsKey('analytics_key')">save</button>+ <button type="button" class="ghost-btn" id="analyticsKeyClear"+ onclick="clearAnalyticsKey('analytics_key')" style="display:none">clear</button>+ </div>+ <div class="hint">+ Write-only project key. Pasting one turns the pings on.+ </div>+ </div>+ <div class="token-row">+ <div class="token-label">+ <span>PostHog personal API key <span class="hint">(fleet view)</span></span>+ <span class="token-status" id="analyticsQueryKeyStatus">—</span>+ </div>+ <div class="token-row-input">+ <input type="password" id="analyticsQueryKeyInput" autocomplete="off"+ placeholder="phx_…">+ <button type="button" class="ghost-btn"+ onclick="toggleTokenVisibility('analyticsQueryKeyInput', this)">show</button>+ <button type="button" class="primary-btn token-savetest"+ onclick="saveAnalyticsKey('analytics_query_key')">save</button>+ <button type="button" class="ghost-btn" id="analyticsQueryKeyClear"+ onclick="clearAnalyticsKey('analytics_query_key')" style="display:none">clear</button>+ </div>+ <div class="hint">+ Read-only key that unlocks the fleet numbers in the Usage+ section of the stats dashboard. Never used for sending.+ </div>+ </div>+ </details>+ </div>+<div class="settings-section" id="settingsCustomSection" style="display:none"><h3>Custom (advanced)</h3><div class="settings-row" style="margin-bottom:10px">@@ -28293,9 +29933,11 @@ function trainGuidanceDismiss() {// Hits /train/preflight and surfaces a banner inside the Train form when a// required model is missing. Today the only on-demand download is the LTX-2.3-// dev transformer (~11 GB) — Phosphene's default install ships the distilled-// transformer only. Banner offers a one-click Download button that triggers-// /train/install + redirects to /status for progress.+// full-precision dev transformer (~21 GB, Q8 repo) — Phosphene's default+// install ships the distilled transformer only, and the Q4 repo's smaller+// transformer-dev is quantized (trainer refuses it, #35). Banner offers a+// one-click Download button that triggers /train/install + redirects to+// /status for progress.async function trainCheckPreflight() {const box = document.getElementById('trainPreflight');if (!box) return;@@ -29550,6 +31192,8 @@ function updateCustomizeSummary() {const tier = h3TierByKey((document.getElementById('h3_tier') || {}).value);const up = (document.getElementById('h3_upscale') || {}).value || 'off';const parts = [tier ? tier.spec : 'Hailuo H3'];+ const stOv = (document.getElementById('h3_steps') || {}).value || 'auto';+ if (stOv !== 'auto') parts.push(stOv + ' steps');if (up === 'fit_720p') parts.push('720p export');else if (up === 'fit_1080p') parts.push('1080p export');else parts.push('native export');@@ -29691,6 +31335,12 @@ function h3TierByKey(key) {try { savedUp = localStorage.getItem('phos_h3_upscale'); } catch (e) {}const allowed = H3.upscale_modes || ['off', 'fit_720p', 'fit_1080p'];if (savedUp && allowed.indexOf(savedUp) !== -1) up.value = savedUp;+ // And again for the sampler-depth pills, same reason.+ const st = document.getElementById('h3_steps');+ if (!st) return;+ let savedSt = null;+ try { savedSt = localStorage.getItem('phos_h3_steps'); } catch (e) {}+ if (savedSt && ['auto', '12', '16', '20'].indexOf(savedSt) !== -1) st.value = savedSt;})();// Export canvas for an H3 render. Separate from the LTX `upscale` control@@ -29710,6 +31360,29 @@ document.querySelectorAll('#h3UpscaleGroup [data-h3-upscale]').forEach(b => {b.onclick = () => setH3Upscale(b.dataset.h3Upscale);});+// Sampler depth for an H3 render. 'auto' = the tier's tuned count (stamped in+// H3_TIERS); a number overrides it for every window of the job. Server-side+// make_job clamps to 4-30 and re-validates — a stale tab must never win.+function setH3Steps(v) {+ const allowed = ['auto', '12', '16', '20'];+ v = allowed.indexOf(String(v)) !== -1 ? String(v) : 'auto';+ const inp = document.getElementById('h3_steps');+ if (inp) inp.value = v;+ document.querySelectorAll('#h3StepsGroup [data-h3-steps]').forEach(b =>+ b.classList.toggle('active', b.dataset.h3Steps === v));+ // Mirror the resolved count into the shared hidden `steps` so the queue+ // card and the estimate line read the truth (make_job re-stamps anyway).+ const tier = h3TierByKey((document.getElementById('h3_tier') || {}).value);+ const s = document.getElementById('steps');+ if (s && tier) s.value = (v === 'auto') ? tier.steps : parseInt(v, 10);+ try { localStorage.setItem('phos_h3_steps', v); } catch (e) {}+ if (typeof updateDerived === 'function') { try { updateDerived(); } catch (e) {} }+ if (typeof updateCustomizeSummary === 'function') { try { updateCustomizeSummary(); } catch (e) {} }+}+document.querySelectorAll('#h3StepsGroup [data-h3-steps]').forEach(b => {+ b.onclick = () => setH3Steps(b.dataset.h3Steps);+});+function _engineRowVisible() {// Only Macs that could actually run H3 see the picker at all. Showing a// permanently-disabled engine to the ~80% of users under 64 GB is noise.@@ -29755,7 +31428,12 @@ function setH3Tier(key) {if (w) w.value = tier.width;if (h) h.value = tier.height;if (f) f.value = tier.frames;- if (s) s.value = tier.steps;+ if (s) {+ // Respect a pinned Steps override across tier switches; 'auto' follows+ // the tier's own count.+ const ov = (document.getElementById('h3_steps') || {}).value || 'auto';+ s.value = (ov !== 'auto' && /^\d+$/.test(ov)) ? parseInt(ov, 10) : tier.steps;+ }// Chained tiers carry an honest artefact note (one prompt is asked of every// window, so a scripted line lands once per window). Surface it where the// user is choosing, not in a tooltip.@@ -29846,6 +31524,7 @@ function setEngine(engine, opts) {setH3Tier((document.getElementById('h3_tier') || {}).value || H3.default_tier);setH3Upscale((document.getElementById('h3_upscale') || {}).value|| H3.default_upscale || 'fit_720p');+ setH3Steps((document.getElementById('h3_steps') || {}).value || 'auto');// LTX post-processing doesn't run on an H3 render (make_job neutralises// all three server-side). Mirror that in the UI or the derived line lies:// it was reading "768×448 → 1280×720 fit" for a render that ships 768×448.@@ -30714,8 +32393,12 @@ function renderDeepVerifyStatus(deep) {if (!r) return;if (r.error) { st.textContent = 'verify error: ' + r.error; return; }if (!r.ok) {- const n = (r.bad || []).length;- st.innerHTML = '<span style="color:#e06666">✗ ' + n + ' file(s) corrupt/stale — use the red banner up top to re-download.</span>';+ const nMisplaced = (r.bad || []).filter(b => b.placement).length;+ const n = (r.bad || []).length - nMisplaced;+ st.innerHTML = '<span style="color:#e06666">✗ '+ + [n ? n + ' file(s) corrupt/stale' : '',+ nMisplaced ? nMisplaced + ' file(s) in the wrong place' : ''].filter(Boolean).join(', ')+ + ' — see the red banner up top.</span>';} else {const uv = (r.unverified || []).length;st.innerHTML = '<span style="color:#5bbf7b">✓ all ' + r.checked + ' file(s) match upstream'@@ -30739,11 +32422,26 @@ function renderIntegrityBanner(integ) {document.body.appendChild(el);}const repos = [...new Set(bad.map(b => b.repo))];- const files = bad.map(b => b.file).join(', ');+ // Placement errors (right content, wrong path) are a different failure from a+ // corrupt download, and the cure is usually a move rather than a re-fetch — so+ // they get their own headline and their reason printed in full (it names both+ // the found-at and expected-at paths). See _placement_errors() in the backend.+ const misplaced = bad.filter(b => b.placement);+ const corrupt = bad.filter(b => !b.placement);el.innerHTML =- '<span style="font-weight:700">Model files look incomplete / corrupt</span>'- + '<span style="opacity:.92">' + escapeHtml(files) + ' — this produces garbled / "mosaic" '- + 'output (usually an interrupted download).</span>'+ '<span style="font-weight:700">'+ + (corrupt.length ? 'Model files look incomplete / corrupt'+ : 'Model files are in the wrong place') + '</span>'+ + (corrupt.length+ ? '<span style="opacity:.92">' + escapeHtml(corrupt.map(b => b.file).join(', '))+ + ' — this produces garbled / "mosaic" output (usually an interrupted '+ + 'download).</span>'+ : '')+ + (misplaced.length+ ? '<span style="opacity:.92;flex-basis:100%">'+ + misplaced.map(b => escapeHtml(b.reason)).join('<br>')+ + '</span>'+ : '')+ '<span style="margin-left:auto;display:flex;gap:8px">'+ repos.map(k => '<button class="btn btn-primary" onclick="repairModel(\'' + escapeHtml(k)+ '\')">Repair ' + escapeHtml(k.toUpperCase()) + ' (re-download)</button>').join('')@@ -32547,6 +34245,11 @@ function renderOutputInfoBody(path, data) {const h3TierDef = ((H3 && H3.tiers) || []).find(t => t.key === h3TierKey);genRows.push(`<dt>Engine</dt><dd>Hailuo H3</dd>`);genRows.push(`<dt>H3 tier</dt><dd>${escapeHtml(h3TierDef ? h3TierDef.label : (h3TierKey || '—'))}</dd>`);+ // Steps only earns a row when the user pinned a depth — the tier default+ // is already implied by the tier row.+ if (Number(p.h3_steps || 0) > 0) {+ genRows.push(`<dt>Steps</dt><dd>${escapeHtml(String(p.steps || p.h3_steps))} · tier default overridden</dd>`);+ }} else {genRows.push(`<dt>Quality</dt><dd>${escapeHtml((p.quality || 'standard').replace(/^./, c => c.toUpperCase()))}</dd>`);}@@ -33471,6 +35174,113 @@ async function openSettingsModal() {// on the JS side; only ON/OFF gets persisted._spicyArmed = false;renderSpicyState(!!cur.spicy_mode);++ // Anonymous usage analytics — badge, hint (shows the actual install id+ // so "you are a random ID" is verifiable, not a claim), and the two+ // maintainer key rows. Same has_X-boolean treatment as the other+ // secrets: the keys never come back from the server.+ renderAnalyticsState(cur);+}++// ---- Anonymous usage analytics ---------------------------------------------+// Single-click both ways: turning it OFF must be at least as easy as+// leaving it ON, which is the whole justification for defaulting to ON.+// No confirm dance here (unlike Spicy mode) — nothing irreversible happens.+function renderAnalyticsState(cur) {+ const on = cur.analytics_enabled !== false;+ const badge = document.getElementById('analyticsStateBadge');+ const btn = document.getElementById('analyticsToggleBtn');+ const hint = document.getElementById('analyticsHint');+ if (badge) {+ badge.textContent = on ? 'ON' : 'OFF';+ badge.className = 'spicy-state' + (on ? ' on' : '');+ }+ if (btn) btn.textContent = on ? 'Turn off' : 'Turn on';+ if (hint) {+ if (!on) {+ hint.textContent = 'Off — nothing is sent, and nothing is written to '+ + 'the local usage log either.';+ } else if (!cur.has_analytics_key) {+ hint.innerHTML = 'On, but no project key is configured — this panel is '+ + 'sending <b>nothing</b> over the network. Events are only written to '+ + 'the local log.';+ } else {+ hint.textContent = 'Your anonymous ID: ' + (cur.analytics_install_id || '(not yet generated)');+ }+ }+ setTokenStatus('analyticsKey', !!cur.has_analytics_key);+ setTokenStatus('analyticsQueryKey', !!cur.has_analytics_query_key);+ const k1 = document.getElementById('analyticsKeyInput');+ const k2 = document.getElementById('analyticsQueryKeyInput');+ if (k1) { k1.value = ''; k1.placeholder = cur.has_analytics_key ? '•••••••••• saved — paste new to replace' : 'phc_…'; }+ if (k2) { k2.value = ''; k2.placeholder = cur.has_analytics_query_key ? '•••••••••• saved — paste new to replace' : 'phx_…'; }+ const c1 = document.getElementById('analyticsKeyClear');+ const c2 = document.getElementById('analyticsQueryKeyClear');+ if (c1) c1.style.display = cur.has_analytics_key ? '' : 'none';+ if (c2) c2.style.display = cur.has_analytics_query_key ? '' : 'none';+}++async function toggleAnalytics() {+ const cur = (_settingsCache && _settingsCache.settings) || {};+ const target = !(cur.analytics_enabled !== false);+ const status = document.getElementById('settingsStatus');+ try {+ const fd = new URLSearchParams();+ fd.set('analytics_enabled', target ? 'true' : 'false');+ const r = await fetch('/settings', { method: 'POST', body: fd });+ const j = await r.json();+ if (j.error) throw new Error(j.error);+ if (j.settings) _settingsCache.settings = j.settings;+ else if (_settingsCache && _settingsCache.settings) {+ _settingsCache.settings.analytics_enabled = target;+ }+ renderAnalyticsState(_settingsCache.settings || {});+ if (status) {+ status.textContent = target+ ? 'Anonymous usage analytics ON'+ : 'Anonymous usage analytics OFF · nothing will be sent or logged';+ status.className = 'settings-status ok';+ }+ } catch (e) {+ if (status) {+ status.textContent = 'Could not change analytics: ' + (e.message || e);+ status.className = 'settings-status err';+ }+ }+}++async function _persistAnalyticsKey(field, value) {+ const status = document.getElementById('settingsStatus');+ try {+ const fd = new URLSearchParams();+ fd.set(field, value);+ const r = await fetch('/settings', { method: 'POST', body: fd });+ const j = await r.json();+ if (j.error) throw new Error(j.error);+ if (j.settings) _settingsCache.settings = j.settings;+ renderAnalyticsState(_settingsCache.settings || {});+ if (status) {+ status.textContent = value ? 'Key saved.' : 'Key cleared.';+ status.className = 'settings-status ok';+ }+ } catch (e) {+ if (status) {+ status.textContent = 'Could not save key: ' + (e.message || e);+ status.className = 'settings-status err';+ }+ }+}++function saveAnalyticsKey(field) {+ const id = field === 'analytics_query_key' ? 'analyticsQueryKeyInput' : 'analyticsKeyInput';+ const el = document.getElementById(id);+ const val = (el && el.value || '').trim();+ if (!val) return;+ _persistAnalyticsKey(field, val);+}++function clearAnalyticsKey(field) {+ _persistAnalyticsKey(field, '');}function renderMemoryPolicyHint() {@@ -36257,6 +38067,12 @@ if __name__ == "__main__":# state/ (gitignored), never on the public repo. Skipped silently# when no GitHub token is resolvable.threading.Thread(target=stats_fetch_loop, daemon=True).start()+ # 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.+ _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 OSError# ("[Errno 48] Address already in use") was confusing users who'd closed@@ -36281,13 +38097,19 @@ if __name__ == "__main__":try:_integ = _model_integrity(force=True)if not _integ["ok"]:+ _misplaced = [_b for _b in _integ["bad"] if _b.get("placement")]print("-" * 64, flush=True)print(f"WARNING model integrity: {len(_integ['bad'])} weight file(s) look "- f"corrupt/incomplete:", flush=True)+ f"corrupt/incomplete or are in the wrong place:", flush=True)for _b in _integ["bad"]:print(f" [{_b['repo']}] {_b['file']} - {_b['reason']}", flush=True)print(" This produces garbled / 'mosaic' output. Use the Repair banner in", flush=True)print(" the panel (or re-run Install) to re-download the affected files.", flush=True)+ if _misplaced:+ print(" The misplaced file(s) above are a PLACEMENT problem, not a corrupt", flush=True)+ print(" download: the content can be fine while the loader still resolves the", flush=True)+ print(" wrong file. Moving/removing the copy named above fixes it without a", flush=True)+ print(" re-download; Repair also works.", flush=True)print("-" * 64, flush=True)else:print(f"model integrity: OK ({_integ['checked']} weight files verified)", flush=True)diff --git a/panel_assets/stats.html b/panel_assets/stats.htmlindex bde4caf..30df8a8 100644--- a/panel_assets/stats.html+++ b/panel_assets/stats.html@@ -675,6 +675,89 @@}.board-empty .ok { color: var(--success); font-size: 14px; }+ /* ============================================================+ USAGE — anonymous panel telemetry. Two possible sources, one+ renderer: the local mirror (state/usage-log.jsonl, always+ available) or the PostHog fleet rollup when a personal API key+ is configured. Deliberately the same card / KPI / list language+ as the GitHub sections above so the page reads as one dashboard+ rather than two bolted together.+ ============================================================ */+ .usage-note {+ display: flex; align-items: center; gap: 8px; flex-wrap: wrap;+ margin: 0 0 14px;+ padding: 9px 12px;+ background: var(--bg-2);+ border: 1px dashed var(--border);+ border-radius: var(--r-md);+ color: var(--muted); font-size: 11.5px;+ }+ .usage-note .src {+ font-family: var(--ph-font-mono); font-size: 10px; font-weight: 700;+ text-transform: uppercase; letter-spacing: 0.08em;+ padding: 2px 7px; border-radius: var(--r-pill);+ background: var(--accent-dim); color: var(--accent-bright);+ }+ .usage-note.is-local .src { background: rgba(210,153,34,0.16); color: var(--warning); }+ .usage-alert {+ display: flex; align-items: center; gap: 9px;+ margin: 14px 0 0; padding: 11px 13px;+ border-radius: var(--r-md);+ background: rgba(248, 81, 73, 0.08);+ border: 1px solid rgba(248, 81, 73, 0.34);+ color: var(--text); font-size: 12.5px;+ }+ .usage-alert.is-clear {+ background: rgba(63, 185, 80, 0.06);+ border-color: rgba(63, 185, 80, 0.26);+ color: var(--muted);+ }+ .usage-alert .n {+ font-family: var(--ph-font-mono); font-weight: 700; color: var(--danger);+ }+ .usage-alert.is-clear .n { color: var(--success); }+ .dist-grid {+ display: grid; gap: 14px; margin-top: 16px;+ grid-template-columns: repeat(auto-fit, minmax(230px, 1fr));+ }+ .dist-col { min-width: 0; }+ .dist-col > h3 { display: flex; align-items: center; gap: 8px; }+ .dist-list {+ list-style: none; margin: 8px 0 0; padding: 0;+ display: flex; flex-direction: column; gap: 6px;+ }+ .dist-row {+ position: relative; overflow: hidden;+ display: grid; grid-template-columns: 1fr auto; gap: 10px;+ align-items: center;+ padding: 7px 11px;+ background: var(--bg-2);+ border: 1px solid var(--border);+ border-radius: var(--r-sm);+ font-size: 12px;+ }+ /* Proportional fill behind each row — same "bar in a table cell"+ idea the Traffic sources tables use, so the eye reads them alike. */+ .dist-row .fill {+ position: absolute; top: 0; bottom: 0; left: 0;+ background: var(--accent-dim);+ z-index: 0;+ }+ .dist-row .name, .dist-row .n { position: relative; z-index: 1; min-width: 0; }+ .dist-row .name {+ overflow: hidden; text-overflow: ellipsis; white-space: nowrap;+ color: var(--text);+ }+ .dist-row.is-err .name {+ font-family: var(--ph-font-mono); font-size: 11px; color: var(--muted);+ white-space: normal; word-break: break-word;+ }+ .dist-row.is-err .fill { background: rgba(248, 81, 73, 0.14); }+ .dist-row .n {+ font-family: var(--ph-font-mono); font-variant-numeric: tabular-nums;+ font-weight: 700; color: var(--muted); font-size: 11px;+ }+/* ============================================================Skeleton loading state.============================================================ */@@ -860,6 +943,53 @@</div></section>+ <!-- ============================================================+ USAGE — anonymous panel telemetry. Independent of /stats/data:+ it reads /stats/usage, which always answers (local aggregates+ from state/usage-log.jsonl) and upgrades to fleet-wide numbers+ when a PostHog personal API key is configured in Settings.+ Hidden only if the endpoint itself is missing — i.e. on a panel+ older than this feature.+ ============================================================ -->+ <section class="card" id="sec-usage" hidden>+ <div class="section-head">+ <h2>Usage <span class="h2-sub">anonymous panel telemetry · renders, errors, hardware</span></h2>+ <button class="icon-btn" id="usage-refresh" type="button"+ title="Re-query PostHog now (bypasses the 6h cache)">+ <span class="ico">↻</span> refresh+ </button>+ </div>+ <div class="usage-note" id="usage-note">+ <span class="src" id="usage-src">local</span>+ <span id="usage-note-text">loading…</span>+ </div>+ <div class="kpi-grid" id="usage-tiles" aria-label="Usage headline stats"></div>+ <!-- Pack-flip alert. A pack going true→false across boots is the+ "my H3 vanished" bug class; red when it has happened at all. -->+ <div class="usage-alert is-clear" id="usage-packflip">+ <span class="n">0</span>+ <span>optional-pack regressions in the last 7 days.</span>+ </div>+ <div class="dist-grid">+ <div class="dist-col">+ <h3>Top errors <span class="count-pill" id="usage-errors-count">0</span></h3>+ <ul class="dist-list" id="usage-errors"></ul>+ </div>+ <div class="dist-col">+ <h3>Versions</h3>+ <ul class="dist-list" id="usage-versions"></ul>+ </div>+ <div class="dist-col">+ <h3>Chip</h3>+ <ul class="dist-list" id="usage-chips"></ul>+ </div>+ <div class="dist-col">+ <h3>Memory</h3>+ <ul class="dist-list" id="usage-ram"></ul>+ </div>+ </div>+ </section>+<!-- ============================================================FUNNEL — Views → Clones → Stars → Forks.============================================================ -->@@ -1183,6 +1313,9 @@// Refresh endpoint is "coming soon" on the panel side — POST best-effort// and degrade silently when it 404s.const REFRESH_URL = '/stats/refresh';+ // Anonymous usage telemetry. Answers on every panel new enough to have+ // the endpoint; 404s on older ones (the Usage section stays hidden).+ const USAGE_URL = '/stats/usage';// Color tokens for charts (kept here so chart code is theme-agnostic).const C = {@@ -2383,6 +2516,128 @@paint(prs, '#attn-prs-list', '#attn-prs-more', prsTotal, 'PRs');}+ // ===================================================================+ // USAGE — anonymous panel telemetry from /stats/usage.+ //+ // Runs on its own fetch, independent of the GitHub snapshot archive:+ // a fresh install with zero /stats/data rows still has usage numbers+ // from its own boots, and a /stats/data failure must not blank this+ // section out. One renderer serves both payload sources — the server+ // hands back the same shape either way and only `source` differs.+ // ===================================================================++ /** Render one {name,count} distribution list with proportional fills. */+ function paintDist(sel, rows, nameKey, opts) {+ const el = $(sel);+ if (!el) return;+ const list = Array.isArray(rows) ? rows : [];+ if (!list.length) {+ el.innerHTML = `<li class="dist-row"><span class="name" style="color:var(--faint)">no data yet</span><span class="n">—</span></li>`;+ return;+ }+ const max = Math.max(1, ...list.map(r => Number(r.count) || 0));+ const cls = (opts && opts.err) ? ' is-err' : '';+ el.innerHTML = list.map(r => {+ const pct = Math.max(2, Math.round(100 * (Number(r.count) || 0) / max));+ const label = r[nameKey];+ const shown = (label === null || label === undefined || label === '')+ ? 'unknown' : String(label);+ return `<li class="dist-row${cls}">+ <span class="fill" style="width:${pct}%"></span>+ <span class="name" title="${escapeAttr(shown)}">${escapeHtml(shown)}</span>+ <span class="n">${fmt(r.count)}</span>+ </li>`;+ }).join('');+ }++ function renderUsage(u) {+ const sec = $('#sec-usage');+ if (!sec) return;+ sec.hidden = false;++ const isFleet = u.source === 'fleet';+ const note = $('#usage-note');+ const srcEl = $('#usage-src');+ const noteText = $('#usage-note-text');+ if (note) note.classList.toggle('is-local', !isFleet);+ if (srcEl) srcEl.textContent = isFleet ? 'fleet' : 'this mac';+ if (noteText) {+ let msg;+ if (u.warning) {+ msg = u.warning;+ } else if (isFleet) {+ msg = 'every install that has pinged'+ + (u.cached ? ' · cached, refreshes every 6h' : ' · fresh')+ + (u.partial ? ' · some queries returned nothing' : '');+ } else {+ msg = u.note || 'this machine only — add a PostHog query key in Settings for fleet data';+ }+ noteText.textContent = msg;+ }++ // Headline tiles. Null values render as "—" rather than 0 so+ // "we have no data" never masquerades as "the number is zero".+ const t = u.tiles || {};+ const tiles = [+ { label: isFleet ? 'Weekly active installs' : 'Active this week',+ value: fmt(t.weekly_active_installs),+ sub: isFleet ? 'unique installs · 7d' : 'this machine · 7d', hero: true },+ { label: 'Renders this week', value: fmt(t.renders_7d), sub: 'completed + failed · 7d' },+ { label: 'H3 share', value: fmtPct(t.h3_share_pct), sub: 'of renders · 14d' },+ { label: 'Error rate', value: fmtPct(t.error_rate_pct), sub: 'failed renders · 14d' },+ ];+ const grid = $('#usage-tiles');+ if (grid) {+ grid.innerHTML = tiles.map(k => `+ <div class="kpi${k.hero ? ' is-hero' : ''}">+ <div class="label">${escapeHtml(k.label)}</div>+ <div class="value">${k.value}</div>+ <div class="delta">${escapeHtml(k.sub)}</div>+ </div>`).join('');+ }++ // Pack-flip alert — the H3-vanished detector. Any true→false+ // transition on any pack counts; h3 is called out by name because+ // it is the one that has actually bitten a user.+ const flips = u.pack_flips || {};+ const lost = Number(flips.h3_lost) || 0;+ const others = (Array.isArray(flips.rows) ? flips.rows : [])+ .filter(r => r.from && !r.to && r.pack !== 'h3')+ .reduce((a, r) => a + (Number(r.count) || 0), 0);+ const alert = $('#usage-packflip');+ if (alert) {+ const total = lost + others;+ alert.classList.toggle('is-clear', total === 0);+ alert.innerHTML = total === 0+ ? `<span class="n">0</span><span>optional-pack regressions in the last 7 days.</span>`+ : `<span class="n">${fmt(total)}</span><span>optional-pack regression${total === 1 ? '' : 's'} in the last 7 days`+ + (lost ? ` — <strong>H3 went from installed to missing ${fmt(lost)}×</strong>` : '')+ + `. A pack that disappears between boots is a broken install, not a user choice.</span>`;+ }++ const errs = Array.isArray(u.top_errors) ? u.top_errors : [];+ const errCount = $('#usage-errors-count');+ if (errCount) errCount.textContent = fmt(errs.reduce((a, r) => a + (Number(r.count) || 0), 0));+ paintDist('#usage-errors', errs, 'signature', { err: true });+ paintDist('#usage-versions', u.versions, 'version');+ paintDist('#usage-chips', u.chips, 'chip');+ paintDist('#usage-ram', u.ram, 'ram_gb');+ }++ async function loadUsage(force) {+ try {+ const r = await fetch(USAGE_URL + (force ? '?force=1' : ''), { cache: 'no-store' });+ if (!r.ok) throw new Error('HTTP ' + r.status);+ const u = await r.json();+ if (u && u.ok === false && !u.tiles) throw new Error(u.error || 'usage unavailable');+ renderUsage(u || {});+ } catch (e) {+ // A panel older than this endpoint 404s — leave the section hidden+ // rather than showing a broken card. Not an error worth surfacing.+ console.debug('usage unavailable:', e && e.message);+ }+ }+function renderTables(rows) {const last = rows[rows.length - 1] || {};const refs = Array.isArray(last.referrers) ? last.referrers : [];@@ -2546,6 +2801,20 @@// REFRESH — best-effort POST. Endpoint may 404; fall back to a reload.// ===================================================================+ // Usage refresh — busts the server's 6h fleet cache. Separate from the+ // GitHub refresh button because they hit completely different backends+ // (PostHog's query API vs the repo-stats fetcher) with different costs.+ function initUsageRefresh() {+ const btn = $('#usage-refresh');+ if (!btn) return;+ btn.addEventListener('click', async () => {+ btn.classList.add('is-busy');+ btn.disabled = true;+ try { await loadUsage(true); }+ finally { btn.classList.remove('is-busy'); btn.disabled = false; }+ });+ }+function initRefresh() {const btn = $('#refresh-btn');if (!btn) return;@@ -2679,7 +2948,12 @@initChips();initClonesChart();initRefresh();+ initUsageRefresh();main();+ // Own fetch, not awaited by main() — the GitHub archive and the usage+ // telemetry are independent sources and either can be empty or broken+ // without taking the other down with it.+ loadUsage(false);</script></body></html>diff --git a/scripts/test_analytics_dryrun.py b/scripts/test_analytics_dryrun.pynew file mode 100644index 0000000..9679abb--- /dev/null+++ b/scripts/test_analytics_dryrun.py@@ -0,0 +1,569 @@+#!/usr/bin/env python3+"""Dry-run tests for the panel's anonymous usage analytics.++ python3 scripts/test_analytics_dryrun.py++No network, no panel, no renders: the whole suite runs against an isolated+temp state dir with `urllib.request.urlopen` replaced by a spy, so it can be+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".+ 2. NOTHING LEAKS. No prompt, path, filename or media string may appear in+ any 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.+ 4. IT CANNOT BREAK A RENDER. Capture never raises, even on garbage input+ and even when the transport blows up.+"""+from __future__ import annotations++import json+import os+import sys+import tempfile+import threading+import time+import unittest+import urllib.request+from pathlib import Path++REPO = Path(__file__).resolve().parent.parent++# Isolate every file the panel writes BEFORE importing it. mlx_ltx_panel+# loads/creates panel_settings.json at import time; pointing LTX_STATE_DIR at+# a temp dir keeps a live panel's real state (and a concurrent render) safe.+_TMP_STATE = tempfile.mkdtemp(prefix="phosphene-analytics-test-")+os.environ["LTX_STATE_DIR"] = _TMP_STATE+os.environ.pop("PHOSPHENE_ANALYTICS_KEY", None)+os.environ.pop("PHOSPHENE_ANALYTICS_QUERY_KEY", None)+os.environ.pop("PHOSPHENE_ANALYTICS_DISABLED", None)++sys.path.insert(0, str(REPO))+import mlx_ltx_panel as P # noqa: E402+++# --------------------------------------------------------------------------+# Test doubles+# --------------------------------------------------------------------------++class _Resp:+ """Minimal urlopen() return value: a context manager with .read()."""+ def __init__(self, body: bytes = b"{\"status\":1}"):+ self._body = body++ def read(self, n: int = -1) -> bytes:+ return self._body++ def __enter__(self):+ return self++ def __exit__(self, *exc):+ return False+++class Spy:+ """Records every urlopen() call instead of making it."""+ def __init__(self, raise_exc: Exception | None = None):+ self.calls: list[dict] = []+ self.raise_exc = raise_exc+ self._lock = threading.Lock()++ def __call__(self, req, timeout=None, **kw):+ with self._lock:+ self.calls.append({+ "url": getattr(req, "full_url", str(req)),+ "body": getattr(req, "data", None) or b"",+ "headers": dict(getattr(req, "headers", {}) or {}),+ "timeout": timeout,+ })+ if self.raise_exc:+ raise self.raise_exc+ return _Resp()++ @property+ def bodies(self) -> list[dict]:+ return [json.loads(c["body"].decode("utf-8")) for c in self.calls]++ def raw(self) -> str:+ return "\n".join(c["body"].decode("utf-8", "replace") for c in self.calls)+++def drain(timeout: float = 5.0) -> None:+ """Wait for every in-flight analytics delivery thread to finish."""+ deadline = time.time() + timeout+ while time.time() < deadline:+ alive = [t for t in threading.enumerate()+ if t.name.startswith("analytics-capture") and t.is_alive()]+ if not alive:+ return+ time.sleep(0.01)+++class AnalyticsTestCase(unittest.TestCase):+ """Common fixture: clean state dir, spy installed, analytics ON, no key."""++ def setUp(self):+ self.spy = Spy()+ self._real_urlopen = urllib.request.urlopen+ urllib.request.urlopen = self.spy+ try:+ P.USAGE_LOG_FILE.unlink()+ except OSError:+ pass+ self.configure(analytics_enabled=True, analytics_key="",+ analytics_query_key="", analytics_last_packs={},+ analytics_disclosed=True)++ def tearDown(self):+ drain()+ urllib.request.urlopen = self._real_urlopen++ @staticmethod+ def configure(**kv):+ P._settings_set_internal(**kv)++ @staticmethod+ def log_lines() -> list[dict]:+ return P._usage_log_read()+++# --------------------------------------------------------------------------+# 1. Inert without a key+# --------------------------------------------------------------------------++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):+ P._analytics_capture("app_boot", {"version": "3.4.1"})+ drain()+ self.assertEqual(self.spy.calls, [],+ "analytics opened a socket with no key configured")++ 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."""+ P._analytics_capture("app_boot", {"version": "3.4.1"})+ drain()+ rows = self.log_lines()+ self.assertEqual(len(rows), 1)+ self.assertEqual(rows[0]["event"], "app_boot")++ def test_disabled_writes_nothing_anywhere(self):+ self.configure(analytics_enabled=False)+ P._analytics_capture("app_boot", {"version": "3.4.1"})+ P._analytics_render_event({"status": "done", "params": {"mode": "t2v"}})+ P._analytics_boot()+ drain()+ self.assertEqual(self.spy.calls, [])+ self.assertEqual(self.log_lines(), [],+ "toggle OFF must stop the local log too")++ def test_env_kill_switch_beats_the_setting(self):+ os.environ["PHOSPHENE_ANALYTICS_DISABLED"] = "1"+ try:+ self.assertFalse(P._analytics_enabled())+ P._analytics_capture("app_boot", {})+ drain()+ self.assertEqual(self.spy.calls, [])+ self.assertEqual(self.log_lines(), [])+ finally:+ os.environ.pop("PHOSPHENE_ANALYTICS_DISABLED", None)++ def test_query_key_absent_means_local_report(self):+ report = P._usage_report()+ self.assertEqual(report["source"], "local")+ self.assertIn("this machine only", report["note"])+ self.assertEqual(self.spy.calls, [],+ "the usage report must not query PostHog with no key")+++# --------------------------------------------------------------------------+# 2. Transport shape once a key IS configured+# --------------------------------------------------------------------------++class TestCaptureWithKey(AnalyticsTestCase):++ def setUp(self):+ super().setUp()+ self.configure(analytics_key="phc_fake_key_for_tests")++ def test_single_post_with_posthog_payload_shape(self):+ P._analytics_capture("app_boot", {"version": "3.4.1", "ram_gb": 64})+ drain()+ self.assertEqual(len(self.spy.calls), 1, "expected exactly one POST")+ call = self.spy.calls[0]+ self.assertTrue(call["url"].endswith("/i/v0/e/"), call["url"])+ self.assertEqual(call["timeout"], P.ANALYTICS_TIMEOUT_SEC)+ body = self.spy.bodies[0]+ self.assertEqual(body["api_key"], "phc_fake_key_for_tests")+ self.assertEqual(body["event"], "app_boot")+ self.assertEqual(body["properties"]["version"], "3.4.1")+ # Anonymous: no person profile is built for the install id.+ self.assertIs(body["properties"]["$process_person_profile"], False)+ self.assertTrue(body["timestamp"].endswith("Z"))++ def test_distinct_id_is_a_random_uuid4_and_stable(self):+ import re as _re+ P._analytics_capture("app_boot", {})+ drain()+ did = self.spy.bodies[0]["distinct_id"]+ self.assertRegex(did, _re.compile(+ r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"))+ self.assertEqual(did, P._analytics_install_id(), "install id must be stable")+ # Not derived from anything about the machine.+ for leak in (os.uname().nodename, os.environ.get("USER", "x"), str(REPO)):+ self.assertNotIn(leak.lower(), did.lower())++ def test_env_key_overrides_the_setting(self):+ os.environ["PHOSPHENE_ANALYTICS_KEY"] = "phc_from_env"+ try:+ self.assertEqual(P._analytics_key(), "phc_from_env")+ finally:+ os.environ.pop("PHOSPHENE_ANALYTICS_KEY", None)++ def test_host_override_is_honoured(self):+ os.environ["PHOSPHENE_ANALYTICS_HOST"] = "https://selfhosted.example"+ try:+ P._analytics_capture("app_boot", {})+ drain()+ self.assertTrue(self.spy.calls[0]["url"].startswith(+ "https://selfhosted.example/"), self.spy.calls[0]["url"])+ finally:+ os.environ.pop("PHOSPHENE_ANALYTICS_HOST", None)++ def test_transport_failure_is_swallowed_and_log_still_written(self):+ """A dead endpoint must be indistinguishable from success to the+ caller — this is the property that keeps analytics out of renders."""+ urllib.request.urlopen = Spy(raise_exc=OSError("network down"))+ P._analytics_capture("render_completed", {"engine": "ltx"})+ drain()+ self.assertEqual(len(self.log_lines()), 1)++ def test_capture_never_raises_on_garbage(self):+ for bad in (None, object(), b"bytes", 12345):+ P._analytics_capture("weird_event", {"x": bad})+ P._analytics_capture(None, None) # type: ignore[arg-type]+ P._analytics_render_event(None) # type: ignore[arg-type]+ P._analytics_render_event({"status": "done"})+ drain() # reaching here at all is the assertion+++# --------------------------------------------------------------------------+# 3. No content ever leaves the machine+# --------------------------------------------------------------------------++class TestNoLeakage(AnalyticsTestCase):++ PROMPT = ("a weathered lighthouse keeper bizarrotrn turns toward camera, "+ "storm light raking his face")+ NEG = "blurry, extra fingers, watermark"+ IMG = "/Users/salo/Desktop/private-photos/keeper-reference.png"+ OUT = "/Users/salo/pinokio/drive/mlx_outputs/20260805_lighthouse_final.mp4"++ def setUp(self):+ super().setUp()+ self.configure(analytics_key="phc_fake_key_for_tests")++ def failed_job(self, error: str) -> dict:+ return {+ "id": "job-1", "status": "failed", "error": error,+ "elapsed_sec": 412.5, "output": self.OUT,+ "params": {+ "mode": "i2v", "engine": "ltx", "quality": "standard",+ "width": 1216, "height": 704, "frames": 121,+ "prompt": self.PROMPT, "negative_prompt": self.NEG,+ "image": self.IMG, "output": self.OUT, "seed": "12345",+ "character": "bizarrotrn_v2",+ },+ }++ def assert_clean(self):+ """No fragment of the user's content in ANY transmitted byte."""+ blob = self.spy.raw() + json.dumps(self.log_lines())+ for needle in (self.PROMPT, self.NEG, self.IMG, self.OUT,+ "lighthouse", "keeper-reference", "private-photos",+ "bizarrotrn", "/Users/", "Desktop", "mlx_outputs",+ ".mp4", ".png"):+ self.assertNotIn(needle, blob,+ f"leaked {needle!r} into an analytics payload")++ def test_failed_render_with_prompt_in_the_error_message(self):+ """The realistic leak: an exception that quotes the prompt back."""+ P._analytics_render_event(self.failed_job(+ f"RuntimeError: helper died while encoding '{self.PROMPT}'"))+ drain()+ self.assertEqual(len(self.spy.calls), 1)+ self.assert_clean()+ props = self.spy.bodies[0]["properties"]+ self.assertIn("<redacted>", props["error_signature"])++ def test_failed_render_with_paths_in_the_error_message(self):+ """Paths that came from the job get caught by the exact-secret pass+ (which runs first and is stronger); either marker is a pass, the+ assertion that matters is assert_clean()."""+ P._analytics_render_event(self.failed_job(+ f"FileNotFoundError: {self.IMG} is missing; wrote {self.OUT}"))+ drain()+ self.assert_clean()+ sig = self.spy.bodies[0]["properties"]["error_signature"]+ self.assertTrue("<path>" in sig or "<redacted>" in sig, sig)++ def test_paths_the_job_never_mentioned_are_still_stripped(self):+ """The path regex is the net for everything the exact-secret pass+ can't know about: helper temp dirs, HF cache entries, venv paths."""+ P._analytics_render_event(self.failed_job(+ "OSError: cannot load /Users/someone/.cache/huggingface/hub/"+ "models--Lightricks--LTX/snapshots/abc/model.safetensors"))+ drain()+ sig = self.spy.bodies[0]["properties"]["error_signature"]+ self.assertIn("<path>", sig)+ self.assertNotIn("someone", sig)+ self.assertNotIn("huggingface", sig)++ def test_completed_render_carries_no_content_at_all(self):+ job = self.failed_job("unused")+ job["status"] = "done"+ job.pop("error")+ P._analytics_render_event(job)+ drain()+ self.assert_clean()+ props = self.spy.bodies[0]["properties"]+ self.assertNotIn("error_signature", props,+ "successful renders must not carry an error field")++ def test_forbidden_keys_are_dropped_even_if_a_caller_passes_them(self):+ """Defense in depth: a future `**params` spread must not leak."""+ dirty = {+ "prompt": self.PROMPT, "image": self.IMG, "output_path": self.OUT,+ "filename": "secret.mp4", "username": "salo", "lora_paths": [self.IMG],+ "engine": "ltx", "frames": 121,+ }+ clean = P._analytics_clean_props(dirty)+ self.assertEqual(set(clean), {"engine", "frames"})++ def test_nested_dict_props_are_scrubbed_too(self):+ clean = P._analytics_clean_props(+ {"packs": {"h3": True, "prompt": self.PROMPT, "q8": False}})+ self.assertEqual(clean["packs"], {"h3": True, "q8": False})++ def test_scrub_takes_first_line_and_truncates(self):+ sig = P._analytics_scrub_text("boom happened\nsecond line with detail")+ self.assertEqual(sig, "boom happened")+ long = P._analytics_scrub_text("x" * 500)+ self.assertLessEqual(len(long), P.ANALYTICS_STR_MAX)++ def test_scrub_strips_home_and_tilde_paths(self):+ for raw in ("could not open /Users/salo/AI/notes.txt",+ "missing ~/pinokio/api/phosphene.git/models/x.safetensors",+ "bad /private/var/folders/t3/zz/T/render.mp4",+ "nested /a/b/c/d/e.bin"):+ out = P._analytics_scrub_text(raw)+ self.assertIn("<path>", out, raw)+ self.assertNotIn("/Users/", out)+ self.assertNotIn("salo", out)++ def test_short_secrets_do_not_blank_ordinary_words(self):+ """A 3-char 'prompt' must not turn every error into <redacted>."""+ out = P._analytics_scrub_text("out of memory during decode", ["out"])+ self.assertEqual(out, "out of memory during decode")+++# --------------------------------------------------------------------------+# 4. Event schemas — kept in lockstep with docs/ANALYTICS.md+# --------------------------------------------------------------------------++class TestEventSchemas(AnalyticsTestCase):++ def setUp(self):+ super().setUp()+ self.configure(analytics_key="phc_fake_key_for_tests")++ def props_of(self, event: str) -> dict:+ for body in self.spy.bodies:+ if body["event"] == event:+ p = dict(body["properties"])+ p.pop("$process_person_profile", None)+ return p+ self.fail(f"no {event} event was captured")++ def test_app_boot_fields(self):+ P._analytics_boot()+ drain()+ p = self.props_of("app_boot")+ self.assertEqual(set(p), {+ "version", "os_version", "chip_family", "ram_gb", "cap_tier",+ "packs", "h3_chain_supported"})+ self.assertEqual(set(p["packs"]), {"h3", "sharp", "q8", "qwen"})+ for v in p["packs"].values():+ self.assertIsInstance(v, bool)+ self.assertIsInstance(p["ram_gb"], int)+ self.assertIn(p["cap_tier"], ("q4", "q8"))+ # os_version is major.minor only — no patch level.+ self.assertLessEqual(len(p["os_version"].split(".")), 2)++ def test_render_completed_fields(self):+ P._analytics_render_event({+ "status": "done", "elapsed_sec": 340.0,+ "params": {"mode": "t2v", "engine": "ltx", "quality": "standard",+ "width": 1216, "height": 704, "frames": 121},+ })+ drain()+ p = self.props_of("render_completed")+ self.assertEqual(set(p), {+ "engine", "mode", "tier", "duration_bucket", "resolution", "frames"})+ self.assertEqual(p["resolution"], "1216x704")+ self.assertEqual(p["duration_bucket"], "5-15m")+ self.assertEqual(p["tier"], "standard")++ def test_render_failed_adds_only_error_signature(self):+ P._analytics_render_event({+ "status": "failed", "error": "OOM during VAE decode",+ "elapsed_sec": 61.0,+ "params": {"mode": "i2v", "engine": "h3", "h3_tier": "5s",+ "width": 1280, "height": 720, "frames": 90},+ })+ drain()+ p = self.props_of("render_failed")+ 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")+ self.assertEqual(p["duration_bucket"], "<2m")++ def test_cancelled_jobs_are_not_reported(self):+ P._analytics_render_event({"status": "cancelled", "params": {"mode": "t2v"}})+ drain()+ self.assertEqual(self.spy.calls, [])++ def test_pack_state_change_fires_on_a_true_to_false_flip(self):+ """The H3-vanished detector. Seed a previous boot that had H3, then+ boot with the real (H3-absent-or-present) state and require an event+ only when it actually changed."""+ packs_before = dict(P._analytics_pack_state())+ flipped = dict(packs_before, h3=not packs_before["h3"])+ self.configure(analytics_last_packs=flipped)+ P._analytics_boot()+ drain()+ p = self.props_of("pack_state_change")+ self.assertEqual(set(p), {"pack", "from", "to"})+ self.assertEqual(p["pack"], "h3")+ self.assertIs(p["from"], flipped["h3"])+ self.assertIs(p["to"], packs_before["h3"])++ def test_no_pack_event_when_nothing_changed(self):+ self.configure(analytics_last_packs=dict(P._analytics_pack_state()))+ P._analytics_boot()+ drain()+ self.assertEqual([b["event"] for b in self.spy.bodies], ["app_boot"],+ "a steady-state boot must emit exactly one event")++ def test_boot_emits_no_heartbeat_thread(self):+ before = {t.name for t in threading.enumerate()}+ P._analytics_boot()+ drain()+ after = {t.name for t in threading.enumerate()}+ self.assertEqual(after - before, set(),+ "analytics must not leave a background timer running")+++class TestBucketsAndParsing(unittest.TestCase):++ def test_duration_buckets(self):+ cases = [(0, "unknown"), (None, "unknown"), (1, "<2m"), (119, "<2m"),+ (120, "2-5m"), (299, "2-5m"), (300, "5-15m"), (899, "5-15m"),+ (900, "15-40m"), (2399, "15-40m"), (2400, ">40m"), (9999, ">40m")]+ for secs, want in cases:+ self.assertEqual(P._analytics_duration_bucket(secs), want, secs)++ def test_chip_family_parsing(self):+ """'Apple M4 Max' -> 'M4 Max'. Live value on this Mac must parse."""+ got = P._analytics_chip_family()+ self.assertRegex(got, r"^(M\d+( (Pro|Max|Ultra))?|unknown|non-apple-silicon)$")+++# --------------------------------------------------------------------------+# 5. Local aggregation + the /stats/usage payload+# --------------------------------------------------------------------------++class TestUsageReport(AnalyticsTestCase):++ def seed(self, records):+ for rec in records:+ P._usage_log_append(rec)++ def test_local_aggregates(self):+ now = time.time()+ self.seed([+ {"event": "app_boot", "ts": now - 3600, "at": "x",+ "props": {"version": "3.4.1", "chip_family": "M4 Max", "ram_gb": 64}},+ {"event": "render_completed", "ts": now - 1800, "at": "x",+ "props": {"engine": "ltx"}},+ {"event": "render_completed", "ts": now - 1700, "at": "x",+ "props": {"engine": "h3"}},+ {"event": "render_failed", "ts": now - 1600, "at": "x",+ "props": {"engine": "ltx", "error_signature": "OOM during decode"}},+ {"event": "pack_state_change", "ts": now - 1500, "at": "x",+ "props": {"pack": "h3", "from": True, "to": False}},+ ])+ r = P._usage_local_report()+ self.assertEqual(r["source"], "local")+ self.assertEqual(r["tiles"]["renders_7d"], 3)+ self.assertAlmostEqual(r["tiles"]["h3_share_pct"], 33.3, places=1)+ self.assertAlmostEqual(r["tiles"]["error_rate_pct"], 33.3, places=1)+ self.assertEqual(r["top_errors"], [{"signature": "OOM during decode", "count": 1}])+ self.assertEqual(r["pack_flips"]["h3_lost"], 1)+ self.assertEqual(r["versions"], [{"version": "3.4.1", "count": 1}])+ self.assertEqual(r["chips"], [{"chip": "M4 Max", "count": 1}])++ def test_old_rows_fall_out_of_the_windows(self):+ old = time.time() - 40 * 86400+ self.seed([{"event": "render_completed", "ts": old, "at": "x",+ "props": {"engine": "ltx"}}])+ r = P._usage_local_report()+ self.assertEqual(r["tiles"]["renders_7d"], 0)++ def test_empty_log_is_a_valid_report(self):+ r = P._usage_local_report()+ self.assertTrue(r["ok"])+ self.assertEqual(r["tiles"]["renders_7d"], 0)+ self.assertIsNone(r["tiles"]["h3_share_pct"])+ self.assertEqual(r["top_errors"], [])++ def test_corrupt_lines_are_skipped_not_fatal(self):+ with P.USAGE_LOG_FILE.open("a", encoding="utf-8") as fh:+ fh.write("{not json at all\n")+ fh.write('{"event":"app_boot","ts":' + str(time.time()) + ',"props":{}}\n')+ fh.write('{"truncated":\n')+ self.assertEqual(len(P._usage_log_read()), 1)++ def test_log_rotation_caps_the_file(self):+ original = P.USAGE_LOG_MAX_BYTES+ P.USAGE_LOG_MAX_BYTES = 4096+ try:+ for i in range(400):+ P._usage_log_append({"event": "app_boot", "ts": time.time(),+ "at": "x", "props": {"i": i}})+ self.assertLess(P.USAGE_LOG_FILE.stat().st_size, 4096 * 2)+ self.assertGreater(len(P._usage_log_read()), 0)+ finally:+ P.USAGE_LOG_MAX_BYTES = original+++def main() -> int:+ suite = unittest.defaultTestLoader.loadTestsFromModule(sys.modules[__name__])+ result = unittest.TextTestRunner(verbosity=2).run(suite)+ print(f"\nstate dir used (safe to delete): {_TMP_STATE}")+ return 0 if result.wasSuccessful() else 1+++if __name__ == "__main__":+ sys.exit(main())