client: allow dataset-repo override for MatVisClient (env var + ctor arg)

[gerchowl]

Motivation

MAT_VIS_HF_BASE env var (client.py:56) already routes the entire base URL — confirmed working end-to-end against gerchowl/mat-vis-tst@v2026.04.99-tst-full-369 (returns the post-#294 neutral-multiplier scalar blocks for ambientcg). So the primary substrate-routing problem is solved by the existing env var.

What this issue actually addresses:

1. Ergonomics — env vars are hidden state and orchestrators (bake/preview/run.py) don't surface them. A --repo flag + constructor arg is the right shape for first-class API support.
2. Hidden gap in the standalone client — mat_vis_client_standalone.py:518 builds the HF tree-listing URL using the raw HF_DATASET constant, not HF_BASE-derived. So MAT_VIS_HF_BASE partially routes the standalone client (resolve URLs route correctly, tree-listing routes to prod) → Frankenstein behavior.
3. Smell in the e2e suite — tests/e2e/test_per_file_roundtrip.py:181-182 monkey-patches _mvc.HF_DATASET directly instead of using the env var, presumably as a workaround for (2).

The original bug-cascade (thumb-bake produced 3 byte-identical PNGs) turned out not to be substrate routing after all — see #385 for the actual culprit (renderer doesn't wait for async texture decode before screenshot). #384 stays valuable for the items above; downgrading priority from priority:high to priority:medium.

Proposed approach (unchanged)

Two layered overrides, both honouring the existing tag semantics:

# explicit
MatVisClient(repo="gerchowl/mat-vis-tst", tag="v2026.04.99-tst-full-369")

# implicit (CI / dispatch parity) — already works for resolve URLs;
# this issue makes it work for ALL HF endpoints the client touches.
os.environ["MAT_VIS_DATASET_REPO"] = "gerchowl/mat-vis-tst"

Precedence: explicit kwarg > MAT_VIS_DATASET_REPO env var > MAT_VIS_HF_BASE (legacy, full-URL form) > HF_DATASET constant default.

What already exists / known sites

• clients/python/src/mat_vis_client/client.py:55-58 — main client constants. Fully overridable today via MAT_VIS_HF_BASE (no tree-URL code path here).
• clients/python/mat_vis_client_standalone.py:46-49 — standalone client constants. Tree-URL gap at line 518.
• clients/python/mat_vis_client_standalone.py:518 — tree_url = f"https://huggingface.co/api/datasets/{HF_DATASET}/tree/{rev}?recursive=true" — bypasses env routing.
• clients/rust/src/main.rs:19,37-38 — Rust client. Already env-overridable.
• clients/mat-vis.sh:20-21 — Bash client. Already env-overridable.
• tests/e2e/test_per_file_roundtrip.py:181-182 — monkey-patches both _mvc.HF_DATASET and _mvc.HF_BASE. Replace with constructor-arg once available.
• scripts/proof_hf_fetch.py:29-30 — hardcoded REPO + BASE, no env honoring. Low-impact (proof script).
• bake/preview/run.py (feat(bake): dedicated "thumb" tier — sphere-rendered material previews #361 orchestrator) — no --repo flag. P1 add.

Scope

P0 (medium-priority, no longer blocking)

• Constructor kwarg repo: str | None = None on MatVisClient
• Env-var fallback MAT_VIS_DATASET_REPO (precedence above)
• All URL builders read the resolved repo, not HF_DATASET directly — including _build_manifest_from_tree in standalone (line 518)
• Unit test: MatVisClient(repo="…") produces tree-URLs against that repo (regression test for the standalone gap)

P1

• CLI flag --repo on python -m mat_vis_client
• bake/preview/run.py (feat(bake): dedicated "thumb" tier — sphere-rendered material previews #361) plumbs --repo through to MatVisClient
• Replace monkey-patches in tests/e2e/test_per_file_roundtrip.py with the new kwarg
• scripts/proof_hf_fetch.py honors env or accepts --repo

Pitfalls

• Cache directory keying: per-repo namespacing required; gerchowl/mat-vis@v1 and gerchowl/mat-vis-tst@v1 must not collide on disk.
• Coexistence with legacy MAT_VIS_HF_BASE (full-URL form): document precedence (explicit args win, then MAT_VIS_DATASET_REPO, then MAT_VIS_HF_BASE).
• HF_DATASET symbol may be re-exported elsewhere in the package; replace at all read sites including the standalone tree-URL builder.

Acceptance criteria

• MatVisClient(repo="gerchowl/mat-vis-tst", tag="v2026.04.99-tst-full-369").index("ambientcg") returns 1949 entries with the post-feat(baker): extract gpuopen MaterialX standard_surface scalars (#290) #294 neutral-multiplier pbr blocks (currently works via env; this asserts the kwarg path).
• MAT_VIS_DATASET_REPO=gerchowl/mat-vis-tst produces the same result without a kwarg.
• Standalone client's _build_manifest_from_tree honours the resolved repo (regression test against the line-518 gap).
• Cache namespacing is keyed on (repo, tag).

References

• feat(bake): dedicated "thumb" tier — sphere-rendered material previews #361 (thumb bake — original trigger; turned out to be bake/preview: check_thumbs.py — duplicate-bytes detector (catches scalar-collapse / orchestrator mid-mixup) #385's bug, not this one)
• bake/preview: check_thumbs.py — duplicate-bytes detector (catches scalar-collapse / orchestrator mid-mixup) #385 (the actual byte-identical-x3 cause: textures not awaited before screenshot)
• feat(client): adapter field passthrough — to_threejs/to_gltf (closes #380) #381 (Layer 3 passthrough fix)
• feat(baker): extract gpuopen MaterialX standard_surface scalars (#290) #294 (textured-multiplier ADR)
• ADR-0007, ADR-0012 (substrate workflow)

[gerchowl]

Scope bump (2026-05-10): add a third "combined" override form MAT_VIS_DATASET=repo@tag that takes the repo coord + revision in one HF-conventional string. Pairs with the existing MatVisClient(repo=…, tag=…) kwargs and MAT_VIS_HF_DATASET (repo-only, added in PR #388).

Final precedence chain (most specific → least):

1. Explicit kwargs: MatVisClient(repo=…, tag=…) win over everything.
2. MAT_VIS_DATASET=repo@tag — both in one env var. If @tag is present, MAT_VIS_TAG is ignored.
3. MAT_VIS_HF_DATASET=repo (just repo) + MAT_VIS_TAG=tag (just tag, if exists; else DEFAULT_TAG).
4. MAT_VIS_HF_BASE=https://…/resolve (legacy full-URL form — kept for back-compat).
5. Defaults: gerchowl/mat-vis@DEFAULT_TAG.

Parsing rule: repo@tag splits on the last @ (HF allows @ in branch names but not repo names; the rightmost @ is always the rev separator).

Re-prioritized to priority:high because it's the unblock for cleaner dispatch parity in the bake/CI/test flows (#361 and beyond).