unsloth/tests/studio/test_model_picker_contracts.py

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Source-contract guards for the model-picker per-model-config feature.

These are cheap, CPU-only, no-browser checks that read the frontend source and
assert the specific fixes that got the predecessor PR reverted stay in place. If
a future edit reverts one of them (e.g. rounds the context ceiling up again, or
puts the HF token back in the URL), the matching assertion reddens. They pair
with the runtime Playwright checks (which prove the behavior end to end) and the
backend pytest checks (which prove the backend logic).
"""

from __future__ import annotations

import re
from pathlib import Path

WORKDIR = Path(__file__).resolve().parents[2]
FRONTEND = WORKDIR / "studio" / "frontend" / "src"


def _read(rel: str) -> str:
    path = FRONTEND / rel
    assert path.exists(), f"missing source file: {path}"
    return path.read_text(encoding = "utf-8")


def test_models_api_sends_token_via_header_not_query():
    """getModelConfig / checkVisionModel / checkEmbeddingModel must pass the HF
    token through hubTokenHeader, never as a ?hf_token= query param (which leaks
    the credential into server/proxy access logs)."""
    src = _read("features/training/api/models-api.ts")
    assert src.count("hubTokenHeader(") >= 3
    assert "hf_token=" not in src
    assert '"hf_token"' not in src and "'hf_token'" not in src


def test_model_metadata_probe_never_puts_token_in_query():
    src = _read("features/model-picker/api/model-metadata.ts")
    assert "hf_token=" not in src
    assert '"hf_token"' not in src and "'hf_token'" not in src


def test_model_config_page_floors_the_context_ceiling():
    """The model's native max-context must be FLOORED to the step grid, never
    rounded up (rounding up can offer/persist a length above the model's real
    ceiling and break loading)."""
    src = _read("features/model-picker/components/model-config-page.tsx")
    assert "floorMaxSeqLength(modelMaxPosition.maxPositionEmbeddings)" in src
    assert "normalizeMaxSeqLength(modelMaxPosition.maxPositionEmbeddings)" not in src


def test_compare_load_clears_stale_native_lease():
    """A compare-pane load never comes from the desktop file picker, so it must
    clear any prior picked file's lease token + expiry, otherwise a reload can
    send a stale lease for the now-active model."""
    src = _read("features/chat/shared-composer.tsx")
    assert "activeNativePathToken: null" in src
    assert "activeNativePathExpiresAtMs: null" in src


def test_autoload_records_backend_loaded_model_identity():
    """An inactive-cache inventory row loads by local path, so startup autoload
    must key both the active checkpoint and its summary by the backend's loaded
    model identity instead of the catalog repo id."""
    src = _read("features/chat/api/chat-adapter.ts")
    autoload = src.split("async function loadAutoLoadCandidate", 1)[1]
    autoload = autoload.split("\n  try {", 1)[0]
    assert "const loadedModelId = loadResp.model || modelPath" in autoload
    assert "setCheckpoint(loadedModelId," in autoload
    assert "id: loadedModelId" in autoload
    assert "m.id === loadedModelId" in autoload


def test_rollback_restores_native_lease_expiry_with_token():
    """A failed model switch that rolls back to a previously loaded picked GGUF
    must restore the lease expiry paired with the token, never the token alone
    (which would look non-expiring and skip the expiry guard)."""
    src = _read("features/chat/hooks/use-chat-model-runtime.ts")
    assert "previousActiveNativePathExpiresAtMs" in src
    assert re.search(
        r"activeNativePathExpiresAtMs:\s*previousActiveNativePathToken", src
    ), "rollback must restore the expiry alongside the token"


def test_default_caches_keyed_on_inventory_version():
    """The chat-template and max-position caches must key on the inventory
    version so a model update in the same session invalidates the cached value
    instead of showing the stale revision."""
    src = _read("features/model-picker/hooks/use-model-defaults.ts")
    # Both cache keys (template + max-position) end with the inventory version.
    assert src.count("${inventoryVersion}") >= 2


def test_hidden_infra_model_needles_present():
    """The frontend static needle list must keep hiding the RAG embedder and the
    llama.cpp validation probe."""
    src = _read("features/hub/lib/hidden-models.ts")
    assert '"bge-small-en-v1.5"' in src
    assert '"ggml-org/models"' in src
    assert '"stories260k.gguf"' in src


def test_hidden_models_dynamic_exact_ids_wired():
    """The configured embedder arrives from /api/hub/hidden-models as exact
    repo ids; a substring needle would let a generic basename like "model"
    hide unrelated chat models."""
    src = _read("features/hub/lib/hidden-models.ts")
    assert "toLowerStrings(data.exact_ids)" in src
    assert "dynamicExactIds.includes(lower)" in src


def test_hidden_model_matchers_refresh_with_inventory_version():
    src = _read("features/hub/lib/hidden-models.ts")
    assert "const version = getInventoryVersion()" in src
    assert "matchersFetchVersion === version" in src
    assert "getInventoryVersion() !== version" in src


def test_diffusion_capability_labeled_image_generation():
    """The diffusion capability detects image GENERATORS (FLUX, SDXL,
    text-to-image tags); labeling it "Image to text" showed generators when
    users asked for captioning models."""
    for rel in (
        "features/hub/lib/model-capabilities.ts",
        "features/hub/lib/model-type-filter.ts",
        "features/hub/lib/view-models.ts",
    ):
        src = _read(rel)
        assert "Image to text" not in src, rel
        assert "Image generation" in src, rel


def test_active_model_config_round_trips_gpu_fields():
    """The active model's config must carry the GPU Memory knobs (GGUF only) so
    a sidebar/hub-gear reload cannot silently reset manual GPU settings, and
    "Remember settings" cannot persist a GPU-less config over a saved one."""
    src = _read("features/model-picker/hooks/use-active-model-config.ts")
    for field in ("gpuMemoryMode", "gpuLayers", "nCpuMoe", "selectedGpuIds"):
        assert field in src, field
    assert "if (!isGguf)" in src and "return base" in src
    for rel in (
        "features/chat/chat-page.tsx",
        "features/hub/catalog/sampling-settings-dialog.tsx",
    ):
        assert "useActiveModelConfig(" in _read(rel), rel
    signature = _read("features/model-picker/components/sidebar-model-config.tsx")
    assert "gpuFieldsSignature(config)" in signature
    shared = _read("features/model-picker/model-config/apply-per-model-config.ts")
    assert "export function gpuFieldsSignature" in shared


def test_gpu_picker_round_trips_requested_pool_not_fitted_subset():
    """A GGUF fit may narrow [0, 1] to [0], but load/status hydration must keep
    [0, 1] as the editable pool so a later reload can grow back onto GPU 1."""
    types = _read("features/chat/types/api.ts")
    assert types.count("requested_gpu_ids?: number[] | null") >= 2

    store = _read("features/chat/stores/chat-runtime-store.ts")
    assert "resp.requested_gpu_ids ?? resp.gpu_ids ?? null" in store

    status = _read("features/chat/lib/apply-inference-status-to-store.ts")
    assert "status.requested_gpu_ids ?? status.gpu_ids ?? null" in status


def test_compare_load_uses_each_models_gpu_config():
    src = _read("features/chat/shared-composer.tsx")
    assert "ownConfig.gpuMemoryMode ?? compareLoadKnobs.gpuMemoryMode" in src
    assert "ownConfig.gpuLayers ?? compareLoadKnobs.gpuLayers" in src
    assert "ownConfig.nCpuMoe ?? compareLoadKnobs.nCpuMoe" in src
    assert "if (ownConfig.selectedGpuIds != null)" in src
    assert "reconcilePersistedGpuIds(ownConfig.selectedGpuIds)" in src
    for field in (
        "gpu_memory_mode: effectiveGpuMemoryMode",
        "gpu_layers: effectiveGpuLayers",
        "n_cpu_moe: effectiveNCpuMoe",
        "gpu_ids: effectiveSelectedGpuIds ?? undefined",
    ):
        assert field in src


def test_active_native_gguf_metadata_uses_path_token():
    src = _read("features/model-picker/components/model-config-page.tsx")
    assert "(isActiveModel ? activeNativePathToken : null)" in src
    assert "target.meta.nativePathToken ??" in src
    assert "nativePathToken," in src
    assert '${nativePathToken ?? ""}' in src


def test_model_default_hooks_do_not_reset_state_in_effect():
    src = _read("features/model-picker/hooks/use-model-defaults.ts")
    assert "setFetched(null)" not in src


def test_variant_expander_refreshes_after_delete():
    """Deleting a downloaded quant from an expanded repo that still has other
    cached quants must bump the expander refresh key, or the deleted quant stays
    shown as downloaded and clickable and tries to reload the removed file."""
    src = _read("features/model-picker/components/model-selector/pickers.tsx")
    del_confirm = re.search(
        r"await onDeleteVariant\(v\.quant\);.*?setRefreshKey\(\(key\) => key \+ 1\)",
        src,
        re.S,
    )
    assert del_confirm, "delete onConfirm must bump refreshKey after a successful delete"


def test_local_picker_rows_require_chat_capability():
    """Local inventory rows can be classified non-chat (canChat false, e.g. a
    folder with only config.json). The picker must filter those out, or selecting
    one loads a weightless path; toLocalModelInfo drops capabilities so the memo
    is the only place the guard can live."""
    src = _read("features/model-picker/inventory/use-chat-picker-inventory.ts")
    memo = re.search(r"const localModels = useMemo\(.*?\[inventory\.localRows\]", src, re.S)
    assert memo, "localModels memo not found"
    assert "row.capabilities.canChat" in memo.group(0)


def test_model_picker_toolbar_reflows_before_crossing_picker_edge():
    """The content-sized section tabs and fixed-width dropdowns must reflow,
    while an oversized tab group must shrink labels but preserve its icons."""
    picker = _read("features/model-picker/components/model-selector/pickers.tsx")
    assert '"flex flex-wrap items-center gap-2"' in picker
    assert 'hasConnected ? "-mr-4" : "-mr-2"' in picker
    assert '"flex max-w-full min-w-0 flex-wrap items-center gap-2"' in picker

    tabs = _read("features/model-picker/components/model-selector/pill-tabs.tsx")
    assert 'fit ? "min-w-0 shrink" : "min-w-0 flex-1"' in tabs
    assert '<span className="min-w-0 truncate">{tab.label}</span>' in tabs

    selector = _read("features/model-picker/components/model-selector.tsx")
    assert 'icon={StarIcon} className="size-3.5 shrink-0"' in selector
    assert 'icon={Download01Icon} className="size-3.5 shrink-0"' in selector
    assert 'icon={CloudIcon} className="size-3.5 shrink-0"' in selector


def test_native_picked_gguf_template_read_through_lease():
    """A native (picked / drag-drop) GGUF's path lives only in its signed lease,
    and the picker chat-template GET has no lease plumbing, so the default
    template must be read through the lease-aware validate probe: mint a
    validate-model lease and post include_chat_template. The native token also
    has to reach the fetch (threaded through the hook) and be part of the cache
    key so two picks of the same basename don't share a template."""
    api = _read("features/model-picker/api/templates.ts")
    assert 'consumeNativePathToken(nativePathToken, "validate-model")' in api
    assert "include_chat_template: true" in api
    assert "/api/inference/validate" in api
    hook = _read("features/model-picker/hooks/use-model-defaults.ts")
    assert "nativePathToken," in hook
    assert '${nativePathToken ?? ""}' in hook


def test_model_load_guard_is_cross_instance():
    """The in-flight load guard must consult the shared store pick (not only the
    per-hook ref) and ejectModel must refuse while any instance is loading:
    three live useChatModelRuntime instances exist (chat page, hub page, hub
    gear dialog)."""
    src = _read("features/chat/hooks/use-chat-model-runtime.ts")
    assert "useChatRuntimeStore.getState().loadingModelPick" in src
    assert "clearLoadingModelPick" in src
    eject_body = src.split("const ejectModel", 1)[1]
    assert "loadingModelPick" in eject_body.split("ejectModel,", 1)[0]


def test_partial_safetensors_download_keeps_delete_menu():
    """A stopped partial safetensors download must keep its options menu (the
    Delete affordance) like the GGUF card does, or partial downloads can only
    be cleaned up by finishing or leaving them. During an ACTIVE download the
    menu stays hidden (every item would be disabled: no Copy path while not
    downloaded, no Delete while downloading, pin suppressed in the run bar)."""
    src = _read("features/hub/catalog/safetensors-download-card.tsx")
    assert "(isDownloaded || (isPartial && !downloading))" in src


def test_pinned_validation_uses_cached_local_variant_listing():
    """Pinned-quant validation must use the TTL-cached hub client with
    preferLocalCache (downloaded-ness is local state) instead of one uncached
    round-trip per pinned repo on every picker open. Picker deletes must go
    through the hub inventory client, whose delete invalidates both the
    variants TTL cache and the server-side HF cache scan (the legacy
    /api/models/delete-cached route invalidates neither, so a post-delete
    inventory refresh would resurrect the deleted row until the scan TTL)."""
    src = _read("features/model-picker/components/model-selector/pickers.tsx")
    assert "listGgufVariantsCached(" in src
    assert "preferLocalCache: true" in src
    assert re.search(r'import \{[^}]*\bdeleteCachedModel\b[^}]*\} from "@/features/hub"', src)
    hub_api = _read("features/hub/inventory/api.ts")
    delete_fn = hub_api.split("export async function deleteCachedModel", 1)[1]
    delete_fn = delete_fn.split("export ", 1)[0]
    assert "invalidateGgufVariantsCache(" in delete_fn
    assert "bumpInventoryVersion(" in delete_fn


def test_chat_autoload_scopes_variant_lookup_to_cached_repo_path():
    """Autoload must probe the exact cache row it will load, including rows
    retained from a previously selected Hugging Face cache."""
    src = _read("features/chat/api/chat-adapter.ts")
    auto_load = src.split("async function autoLoadSmallestModel", 1)[1]
    assert auto_load.count("preferLocalCache: true") >= 2
    assert auto_load.count("localPath: repo.cache_path") >= 2

    chat_api = _read("features/chat/api/chat-api.ts")
    variants_fn = chat_api.split("export async function listGgufVariants", 1)[1]
    variants_fn = variants_fn.split("export interface KvCacheEstimate", 1)[0]
    assert 'params.set("prefer_local_cache", "true")' in variants_fn
    assert 'params.set("local_path", localPath)' in variants_fn


def test_cache_location_update_invalidates_frontend_inventory():
    """A successful cache switch must refresh both inventory rows and cached
    GGUF variant results before any stale active-cache identity can be reused."""
    src = _read("features/settings/api/hugging-face-cache.ts")
    update_fn = src.split("export async function updateHuggingFaceCacheSettings", 1)[1]
    assert "bumpInventoryVersion();" in update_fn
    assert "invalidateGgufVariantsCache();" in update_fn


def test_downloaded_list_offsets_virtual_rows():
    """The On Device virtualized list sits below the Pinned block in the same
    scroll element, so it must pass its measured offset as scrollMargin or rows
    past the overscan render blank."""
    src = _read("features/hub/catalog/models-catalog-lists.tsx")
    assert "scrollMargin={scrollMargin}" in src


def test_local_gguf_diagnostics_gate_on_broad_is_gguf():
    """The MTP fallback note and the context/VRAM warning must gate on the broad
    isGguf (variant, loaded gguf context, or .gguf suffix), not the variant-only
    isLoadedGguf, so direct-file and custom-folder GGUF loads keep those
    diagnostics."""
    src = _read("features/chat/chat-settings-sheet.tsx")
    spec = re.search(r"const showSpecFallback =.*?;", src, re.S)
    vram = re.search(r"const showContextVramWarning =.*?;", src, re.S)
    assert spec and "isGguf &&" in spec.group(0) and "isLoadedGguf" not in spec.group(0)
    assert vram and "isGguf &&" in vram.group(0) and "isLoadedGguf" not in vram.group(0)


def test_fixed_layer_gguf_pins_displayed_context():
    """An already-loaded auto-fit GGUF saved with Manual fixed GPU layers must
    pin the shown context, so a later fresh load keeps the fitted placement
    instead of sending native/0 and recreating the OOM."""
    src = _read("features/model-picker/components/model-config-page.tsx")
    assert "const pinFixedLayerContext =" in src
    assert 'config.gpuMemoryMode === "manual"' in src
    assert "customContextLength: activeLoadedContext" in src


def test_fixed_layer_pin_recomputed_after_committing_gpu_layers():
    """pinFixedLayerContext is computed from the render-time config, before a
    same-click GPU Layers draft is committed. handleRun must recompute it from the
    committed effectiveConfig; otherwise typing a positive GPU Layers value on an
    auto-fit GGUF and clicking Reload saves customContextLength: null, so a later
    fresh load sends the native context with fixed layers (the OOM the pin avoids)."""
    src = _read("features/model-picker/components/model-config-page.tsx")
    assert "const effectivePinFixedLayerContext =" in src
    assert 'effectiveConfig.gpuMemoryMode === "manual"' in src
    assert "effectiveConfig.gpuLayers != null" in src
    assert "effectiveConfig.customContextLength == null" in src
    assert "{ ...effectiveConfig, customContextLength: activeLoadedContext }" in src


def test_blur_cache_cleared_on_every_settled_render():
    """The lastBlurCommittedRef bridge is valid only across the single synchronous
    same-click gesture that set it. Keying its clear on [value] missed a Reset (or
    external edit) that restores the shown value unchanged after the blur dispatched
    onChange: value nets back to its prior number, the effect never re-ran, and a
    later Load/Save replayed the override Reset removed. Clear it on every settled
    render instead."""
    src = _read("features/model-picker/components/numeric-value-input.tsx")
    # The clearing effect must run on every commit, not be gated on [value] alone.
    assert not re.search(r"lastBlurCommittedRef\.current = null;\s*\}, \[value\]\);", src)
    assert re.search(
        r"useEffect\(\(\) => \{\s*lastBlurCommittedRef\.current = null;\s*\}\);",
        src,
    )


def test_auto_defaults_not_persisted_as_overrides():
    """Auto GPU memory mode and Auto/default speculative type are follow-global
    defaults; normalization must not persist them as per-model overrides, else a
    model stops following later changes to the global preference."""
    src = _read("features/model-picker/model-config/per-model-config.ts")
    assert 'if (partial.gpuMemoryMode === "manual") {' in src
    assert 'partial.gpuMemoryMode === "auto" || partial.gpuMemoryMode === "manual"' not in src
    spec = re.search(r'if \(s === "auto" \|\| s === "default"\) \{\s*return ([^;]+);', src)
    assert spec and spec.group(1).strip() == "null"


def test_compare_pane_context_from_own_config_only():
    """A compare pane's context comes from its own config only (a saved pin, else
    null for Auto/native); it must not inherit the active model's shared snapshot,
    which resolveFitMaxSeqLength would treat as an explicit pin (VRAM/OOM)."""
    src = _read("features/chat/shared-composer.tsx")
    assert "const effectiveCustomContextLength = ownConfig.customContextLength;" in src
    assert "compareLoadKnobs.customContextLength" not in src


def test_reset_max_seq_length_falls_back_to_app_default():
    """After Reset clears maxSeqLength (null), a non-GGUF active model's shown
    max sequence length must fall back to the app default, never the loaded
    runtime snapshot, or a remembered/active override can never be cleared."""
    src = _read("features/model-picker/components/model-config-page.tsx")
    # The null fallback resolves to the app-default constant, not a runtime value.
    assert "clampMaxSeqLength(DEFAULT_MAX_SEQ_LENGTH, nativeMaxSeqLength)" in src
    # The buggy runtime-seeded fallback must not come back.
    assert "clampMaxSeqLength(initialMaxSeqLength" not in src


def test_reset_persists_null_max_length_and_substitutes_only_for_load():
    """The persisted per-model record must keep config.maxSeqLength (null after
    Reset) so isDefaultConfig can clear a remembered override; the concrete
    fallback is substituted only into the load request, not the saved record."""
    src = _read("features/model-picker/components/model-config-page.tsx")
    # Load-only substitution of the resolved value (recomputed from any committed
    # same-click Max Seq Length draft, so it is never dropped).
    assert "maxSeqLength: effectiveMaxSeqLengthValue" in src
    assert "const effectiveLoadConfig" in src
    # The persisted record is saved from effectiveRuntimeConfig; the load request
    # carries effectiveLoadConfig (with any committed context input).
    assert "onRun(effectiveLoadConfig)" in src
    assert "savePerModelConfig(" in src


def test_initial_load_uses_staged_config_payload():
    """Run-settings Load must pass the staged config through to /load even when
    React has not flushed NumericValueInput blur commits into the store yet."""
    runtime = _read("features/chat/hooks/use-chat-model-runtime.ts")
    assert "const pendingLoadConfig =" in runtime
    assert "pendingLoadConfig?.kvCacheDtype" in runtime
    assert "pendingLoadConfig?.customContextLength" in runtime
    page = _read("features/model-picker/components/model-config-page.tsx")
    assert "contextInputRef" in page
    assert "contextInputRef.current?.commit()" in page
    numeric = _read("features/model-picker/components/numeric-value-input.tsx")
    assert "export type NumericValueInputHandle" in numeric
    assert "commit:" in numeric
    # P1: commit returns null unless the user actually edited the field,
    # so Load/Save with untouched Auto does not pin native context.
    assert "dirtyRef.current" in numeric
    assert "return null;" in numeric
    # P2: blur clears dirtyRef after commit so Reset/slider cannot be
    # overwritten by a stale draft on a later Load.
    assert "dirtyRef.current = false;" in numeric
    assert "draftRef.current = String(final);" in numeric
    # Same-click Load after blur still sees the committed draft.
    assert "lastBlurCommittedRef" in numeric
    # Invalid drafts must not turn Auto into an explicit pin.
    assert "const commitDraft = (raw: string): number | null" in numeric
    assert re.search(r"if \(!Number\.isFinite\(parsed\)\) \{\s*return null;", numeric)
    assert re.search(
        r"if \(final == null\) \{\s*"
        r"draftRef\.current = String\(value\);\s*"
        r"lastBlurCommittedRef\.current = null;",
        numeric,
    )
    # handleRun only promotes commit() when non-null.
    assert "committedContext != null" in page
    assert "pendingPatch.customContextLength = committedContext;" in page


def test_same_click_commit_covers_all_numeric_inputs():
    """The same-click blur bridge must flush every NumericValueInput-backed
    setting, not just Context Length. Max Seq Length (non-GGUF), GPU Layers and
    MoE Layers (GGUF) also stage their draft only on blur, so handleRun must
    imperatively commit each and fold the value into the staged load config;
    otherwise a value the user typed right before clicking Load/Reload is lost."""
    page = _read("features/model-picker/components/model-config-page.tsx")
    # Each numeric input owns an imperative handle that handleRun commits, and the
    # handle is forwarded down to the actual NumericValueInput.
    for ref in ("maxSeqLengthInputRef", "gpuLayersInputRef", "moeLayersInputRef"):
        assert f"const {ref} = useRef<NumericValueInputHandle>(null);" in page
        assert f"{ref}.current?.commit()" in page
        assert f"inputRef={{{ref}}}" in page
    # The leaf sub-components accept and forward the handle as a ref.
    assert page.count("inputRef?: Ref<NumericValueInputHandle>;") >= 2
    assert "ref={inputRef}" in page
    # Committed drafts are folded into the staged config, gated on non-null so an
    # untouched field never fabricates an override.
    assert "committedMaxSeqLength != null" in page
    assert "committedGpuLayers != null" in page
    assert "committedMoeLayers != null" in page
    assert "pendingPatch.gpuLayers = committedGpuLayers;" in page
    assert "pendingPatch.nCpuMoe = committedMoeLayers;" in page
    # The non-GGUF load path substitutes the committed Max Seq Length draft.
    assert "const effectiveMaxSeqLengthValue =" in page
    assert "maxSeqLength: effectiveMaxSeqLengthValue" in page


def test_context_commit_rechecks_persistence_only_shortcut():
    """Committed context changes must bypass persistence-only saves."""
    src = _read("features/model-picker/components/model-config-page.tsx")
    assert "const effectiveConfig =" in src
    assert "perModelConfigsEqual(effectiveConfig, baseline)" in src
    assert "const effectivePersistenceOnly =" in src
    assert "if (effectivePersistenceOnly)" in src


def test_reset_enabled_for_explicit_context_pin_at_native():
    """An explicit customContextLength that equals the native ceiling is still a
    user override, so contextAtDefault must require customContextLength == null.
    The buggy form treated `contextValue === native` alone as default, wedging
    the Reset button disabled for a deliberate pin-to-native."""
    src = " ".join(_read("features/model-picker/components/model-config-page.tsx").split())
    assert (
        "const contextAtDefault = !target.isGguf || "
        "(config.customContextLength == null && "
        "(nativeContextLength == null || contextValue === nativeContextLength));" in src
    )
    # The old form that ignored an explicit pin equal to native must not return.
    assert (
        "(nativeContextLength == null ? config.customContextLength == null : "
        "contextValue === nativeContextLength)" not in src
    )
    # The app-default constant is the single source of truth (imported, not local).
    assert "DEFAULT_MAX_SEQ_LENGTH," in src
    assert "const DEFAULT_MAX_SEQ_LENGTH = 4096" not in src


def test_compare_pane_non_gguf_falls_back_to_app_default():
    """A non-GGUF compare pane with no saved maxSeqLength must fall back to the
    shared app default, not the active model's runtime snapshot; otherwise an
    unconfigured pane inherits a saved 128K neighbor's context and can OOM."""
    per_model = _read("features/model-picker/model-config/per-model-config.ts")
    assert "export const DEFAULT_MAX_SEQ_LENGTH = 4096;" in per_model
    barrel = _read("features/model-picker/index.ts")
    assert "DEFAULT_MAX_SEQ_LENGTH," in barrel
    src = " ".join(_read("features/chat/shared-composer.tsx").split())
    assert "DEFAULT_MAX_SEQ_LENGTH," in src
    assert (
        "const effectiveMaxSeqLength = ownConfig.customContextLength ?? "
        "normalizeMaxSeqLength(ownConfig.maxSeqLength) ?? "
        "(isGgufLoad ? 0 : DEFAULT_MAX_SEQ_LENGTH);" in src
    )
    # The buggy fallback to the active model's shared runtime value must not return.
    assert "(isGgufLoad ? 0 : maxSeqLength)" not in src
    assert "const maxSeqLength = store.params.maxSeqLength;" not in src


def test_default_gpu_mode_clears_manual_knobs():
    """Switching GPU Memory back to Default must clear the Manual-only knobs
    (gpuLayers/nCpuMoe/selectedGpuIds); otherwise a remembered config keeps stale
    pins that a later load re-applies when the global preference is Manual."""
    src = _read("features/model-picker/components/model-config-page.tsx")
    assert 'gpuMemoryMode: "auto",' in src
    assert "gpuLayers: undefined," in src
    assert "nCpuMoe: undefined," in src
    assert "selectedGpuIds: undefined," in src


def test_legacy_migration_is_idempotent_and_non_destructive():
    """The v1->v2 localStorage migration (unsloth_load_settings ->
    unsloth_model_configs) is invoked on every store read, so it must be
    idempotent: repeated reads, browser reloads, and Studio restarts must never
    re-migrate, duplicate records, or overwrite a newer per-model config. This
    was the class of regression that reverted the predecessor PR, so pin all
    three idempotency layers at source level; dropping any of them reddens here.
    """
    raw = _read("features/model-picker/model-config/per-model-config.ts")
    src = " ".join(raw.split())
    # Migration runs from readMap (every store read), so it must be safe to repeat.
    assert (
        "function readMap(): StoredMap { migrateLegacyLoadSettingsOnce(); "
        "return readMapRaw(); }" in src
    )
    # Layer 1: in-memory once-per-session guard so repeated readMap() calls
    # migrate at most once.
    assert "let legacyMigrationChecked = false;" in src
    assert "if (legacyMigrationChecked || !canUseStorage()) {" in src
    assert "legacyMigrationChecked = true;" in src
    # Layer 2: persistent cross-session flag so a completed migration is never
    # redone. Set in every terminal branch (malformed data, nothing to migrate,
    # successful write); a failed quota write leaves it unset so the next session
    # retries. Three set-sites encode exactly that.
    assert 'const LEGACY_MIGRATION_FLAG = "unsloth_model_configs_migrated";' in src
    assert "if (localStorage.getItem(LEGACY_MIGRATION_FLAG)) {" in src
    assert src.count('localStorage.setItem(LEGACY_MIGRATION_FLAG, "1");') >= 3
    # Layer 3: non-overwriting merge skips an existing (or default) key, so even a
    # forced re-run cannot duplicate or clobber a user's config.
    assert "if (isDefaultConfig(migrated) || Object.hasOwn(map, key)) {" in src


def test_variant_expander_forwards_the_gguf_filename():
    """A quant pick must carry the exact .gguf filename. The diffusion pages load
    by filename and cannot map a quant label back to one, so without it every hub
    GGUF pick on Images/Video fell through to a silent return and nothing loaded."""
    src = _read("features/model-picker/components/model-selector/pickers.tsx")
    handler = re.search(r"const handleVariantClick = useCallback\(.*?\n  \);", src, re.S)
    assert handler, "handleVariantClick not found"
    assert "ggufFilename: filename," in handler.group(0)
    # The call site has to actually pass it through, in the handler's argument order.
    # Matched structurally: prettier wraps the call across lines once it grows.
    call = re.search(r"handleVariantClick\(([^)]*)\)", src)
    assert call, "handleVariantClick call site not found"
    args = [a.strip() for a in call.group(1).split(",") if a.strip()]
    assert args[:2] == ["v.quant", "v.filename"], args


def test_a_routed_local_single_file_pick_keeps_its_load_kind():
    """A pick routed from the chat picker arrives as ?model=&quant= with no picker metadata,
    so a bare local .gguf / .safetensors has to be recognised from the path. Loading one as a
    pipeline evicts the resident model and then fails on the missing model_index.json, because
    an explicit model_kind wins over the backend's filename sniffing."""
    helper = _read("lib/diffusion-route-pick.ts")
    assert '"gguf"' in helper and '"single_file"' in helper
    assert 'lower.endsWith(".gguf")' in helper
    assert 'lower.endsWith(".safetensors")' in helper
    # A repo id (no recognised extension) still loads as a pipeline, as before.
    assert 'kind: "pipeline"' in helper

    for rel in ("features/images/images-page.tsx", "features/video/video-page.tsx"):
        src = _read(rel)
        assert "diffusionRoutePick(" in src, f"{rel}: route pick not derived"
        # And the derived pick is what gets loaded, not the raw search params.
        assert re.search(r"loadOrStage\(\s*pick\.repoId,\s*pick\.opts", src), rel


def test_a_routed_curated_pick_uses_the_same_load_spec_as_a_direct_one():
    """The chat picker can only forward a GGUF filename (ggufFilename is GGUF-specific), so a
    curated single-file artifact -- an LTX-2.3 checkpoint, an FP8 transformer -- arrives with no
    quant. Classifying it by shape alone made it a pipeline load, which calls from_pretrained on a
    repo that has no model_index.json. The catalog spec the page's own picker consults has to win."""
    helper = _read("lib/diffusion-route-pick.ts")
    assert re.search(r"spec\?:\s*\{\s*kind:", helper), "the helper takes no catalog spec"
    assert (
        "if (spec) return { repoId: model, opts: { kind: spec.kind, filename: spec.filename } };"
        in helper
    )
    for rel, catalog in (
        ("features/images/images-page.tsx", "IMAGE_CATALOG"),
        ("features/video/video-page.tsx", "VIDEO_CATALOG"),
    ):
        src = _read(rel)
        call = re.search(
            r"diffusionRoutePick\(\s*wanted,\s*routeSearch\.quant,\s*(.*?),?\s*\);", src, re.S
        )
        assert call, f"{rel}: the routed pick passes no spec"
        assert f"loadSpecFor(wanted, {catalog})" in call.group(1), rel


def test_a_quantized_load_drops_a_lora_selection_it_cannot_bake():
    """int8/fp8 builds take adapters only at load time. Switching artifact inside one family
    keeps the selection (same family, no clear) while the load did not bake it, so Generate
    would 400 with the picker still showing the adapter as active."""
    src = _read("features/images/images-page.tsx")
    assert "bakedLorasOnLoad.current = bakeLoras.length > 0;" in src
    guard = re.search(
        r"if \(!loraCapable \|\| checkedBuildForBake\.current === residentBuildKey\) return;.*?\n  \}, \[",
        src,
        re.S,
    )
    assert guard, "the bake-only check is missing"
    body = guard.group(0)
    assert '"int8"' in body and '"fp8"' in body
    assert "bakedLorasOnLoad.current" in body, "a baked selection must be kept"
    assert "setLoras([])" in body and "toast.info(" in body, "cleared without telling the user"


def test_diffusion_pages_never_drop_a_gguf_pick_silently():
    """The fallback branch splits a local path; a repo pick reaching it has no
    filename. It must say so instead of returning with no request and no toast."""
    for rel in ("features/images/images-page.tsx", "features/video/video-page.tsx"):
        src = _read(rel)
        branch = re.search(
            r'if \(!filename\.toLowerCase\(\)\.endsWith\("\.gguf"\)\) \{.*?\}', src, re.S
        )
        assert branch, f"{rel}: gguf extension guard not found"
        assert "toast.error(" in branch.group(0), f"{rel}: guard returns silently"


def test_diffusion_pages_stage_downloads_through_the_manager():
    """Images/Video must not download inside the load: an undownloaded hub pick goes to
    the Hub download manager first, so it shares the panel, progress, cancel/resume,
    disk preflight and manifest verification with every other model."""
    for rel in ("features/images/images-page.tsx", "features/video/video-page.tsx"):
        src = _read(rel)
        assert "useStagedDownload" in src, f"{rel}: not wired to the download manager"
        # The plan carries the loader's own file scope, so nothing extra is pulled.
        assert "DownloadPlan(" in src, f"{rel}: does not fetch a download plan"
        stage_fn = re.search(r"const loadOrStage = useCallback\(.*?\n  \);", src, re.S)
        assert stage_fn, f"{rel}: loadOrStage not found"
        body = stage_fn.group(0)
        # Already-downloaded (and local) picks must skip staging and load straight away.
        assert "isDownloaded !== false" in body, f"{rel}: cached picks would re-stage"
        # A missing plan must still load rather than dead-end.
        assert "catch" in body, f"{rel}: no fallback when the plan is unavailable"


def test_a_hidden_diffusion_page_does_not_load_when_its_download_lands():
    """Images and Video stay mounted behind the router, and a load evicts whoever holds the
    GPU. A multi-GB staged download finishing while the user is on another page must not take
    the model out from under them; the pick waits for its page to be visible again."""
    for rel in ("features/images/images-page.tsx", "features/video/video-page.tsx"):
        src = _read(rel)
        ready = re.search(r"onReady: \(\) => \{.*?\n    \},", src, re.S)
        assert ready, f"{rel}: staged-download onReady not found"
        assert "if (!active)" in ready.group(0), f"{rel}: a hidden page still takes the GPU"
        # Deferred, not dropped: something has to fire the held pick when the page returns.
        assert "stagedLoadDeferred" in ready.group(0), f"{rel}: the pick is discarded"
        flush = re.search(
            r"if \(!active \|\| !stagedLoadDeferred\.current\) return;.*?\n  \}, \[active\]\);",
            src,
            re.S,
        )
        assert flush, f"{rel}: nothing flushes the deferred load when the page is shown"
        assert "handleLoadRef.current(" in flush.group(0), f"{rel}: deferred load never runs"


def test_staged_downloads_always_scope_their_files():
    """Every staged entry must go out as a scoped job carrying its file list, GGUF
    checkpoints included. A plain snapshot job drops *.gguf via the Hub's ignore list, so
    it would finish instantly having fetched everything except the weights and leave the
    repo on device unloadable."""
    src = _read("features/hub/download-manager/use-staged-download.ts")
    start = re.search(r"downloadManager\.requestStart\(\{.*?\}\);", src, re.S)
    assert start, "requestStart call not found"
    body = start.group(0)
    # Unconditional: no branch may send a null scope or omit the files.
    assert "scopeId," in body and "files: current.files," in body
    assert "? null" not in body and "? undefined" not in body
    assert "const activeVariant = current ? scopedVariant(scopeId) : null;" in src


def test_local_model_sections_respect_the_task_filter():
    """LM Studio / ./models / custom-folder rows must honour the picker's task filter.
    The backend tags every local model with a task for exactly this; without the gate the
    Images picker listed chat GGUFs (which 400 on a diffusion load) and buried the
    diffusion models the page can actually run."""
    src = _read("features/model-picker/components/model-selector/pickers.tsx")
    for memo in ("sortedLmStudio", "sortedLocalDir", "sortedCustomFolderModels"):
        block = re.search(rf"const {memo} = useMemo\(.*?\n  \);", src, re.S)
        assert block, f"{memo} not found"
        assert "passesTaskGate(m.task" in block.group(0), f"{memo} does not apply the task gate"


def test_chat_picker_routes_diffusion_picks_to_their_page():
    """Chat cannot load a diffusion model. Rather than hiding an on-device one or letting
    it 400, the unfiltered picker routes the pick to the Images/Video page, which loads it."""
    src = _read("features/model-picker/components/model-selector/pickers.tsx")
    gate = re.search(r"function passesTaskGate\(.*?\n\}", src, re.S)
    assert gate, "passesTaskGate not found"
    # The chat branch no longer drops the generation tasks outright.
    assert "UNSUPPORTED_DIFFUSION_TASK" in gate.group(0)
    wrapper = re.search(r"const onSelect = useCallback\(.*?\n  \);", src, re.S)
    assert wrapper, "the routing wrapper around onSelect is missing"
    body = wrapper.group(0)
    assert "diffusionPageForTask" in body and "navigateToPage" in body
    # Task-scoped pickers (already on those pages) must select normally.
    assert "if (!task)" in body


def test_staged_download_callbacks_only_answer_their_own_variant():
    """subscribeJobListeners is per repo, not per job, so a staged entry hears every job on
    that repo (the Models tab fetching a chat quant of the same repo, say). Each callback
    carries the variant it fired for: without comparing it, a sibling job's completion advanced
    the staged queue and started a load whose scoped files were still downloading, and its
    failure wiped a queue that was still running."""
    src = _read("features/hub/download-manager/use-staged-download.ts")
    # The comparison lives in the shared isOurs() guard the three callbacks run (which also binds
    # them to the started file set; see the test below).
    assert "(variant ?? null) === activeVariant &&" in src
    for callback in ("onComplete", "onError", "onCancelled"):
        handler = re.search(rf"{callback}: \(variant\) => \{{\n(.*?)\n    \}},", src, re.S)
        assert handler, f"{callback} does not take the variant"
        assert "isOurs(variant)" in handler.group(1), callback


def test_video_gallery_fetches_clips_as_their_cards_come_into_view():
    """Each gallery record's src is a blob holding the whole MP4 until the page closes, so
    fetching a full page of them up front pinned hundreds of MB (gigabytes across "load more"
    pages) for cards the user may never scroll to. Fetch on visibility instead, and always
    fetch the selected clip, since that is the one the preview player plays."""
    src = _read("features/video/video-page.tsx")
    assert "new IntersectionObserver(" in src
    assert "ref={stripRef}" in src and "data-clip-id={video.id}" in src
    assert 'root.querySelectorAll("[data-clip-id]")' in src
    # rootMargin is added to the root box only, so the strip (the clipping scroller) has to
    # BE the root, or the prefetch margin never reaches a card clipped past its edge.
    assert '{ root, rootMargin: "0px 600px" }' in src
    # The only surviving whole-page fetches are the no-IntersectionObserver fallbacks.
    eager = list(re.finditer(r"page\.videos\.forEach\(\(video\) => void ensureSrc\(video\)\)", src))
    assert eager, "the jsdom/old-webview fallback fetch is missing"
    for match in eager:
        assert (
            'typeof IntersectionObserver === "undefined"'
            in src[max(0, match.start() - 260) : match.start()]
        )
    assert re.search(
        r"if \(!selected\) return;\s*\n\s*void \(async \(\) => \{\s*\n\s*await ensureSrc\(selected\);",
        src,
    )


def test_on_device_rows_carry_the_task_the_pickers_filter_on():
    """The picker's On Device rows come from the /api/hub inventory, not the models API, and the
    task-scoped pickers drop every row whose task is unset. Without the task threaded through the
    hub inventory and its adapter, the Images and Video pickers listed nothing on device and the
    chat picker never routed a diffusion pick, since diffusionTaskById reads the same field."""
    api = _read("features/hub/inventory/api.ts")
    assert api.count("task?: string | null;") >= 3, "the hub row response types carry no task"
    rows = _read("features/hub/inventory/types.ts")
    assert rows.count("task?: string | null;") >= 2, "the inventory row types carry no task"
    vm = _read("features/hub/inventory/view-models.ts")
    assert "task: row.task ?? null," in vm and "task: model.task ?? null," in vm
    conv = _read("features/model-picker/inventory/use-chat-picker-inventory.ts")
    assert conv.count("task: row.task ?? null,") == 3, "a picker converter drops the task"
    # A generation-task row is not a chat row, so the chat-only guard must not hide it from the
    # pickers that can load it.
    assert "row.capabilities.canChat || studioPageForTask(row.task) !== undefined" in conv


def test_local_diffusion_routing_is_keyed_by_the_id_the_row_selects():
    """A local row's click passes m.id (a filesystem load id), while m.model_id is its HF-style
    name. Keying the routing map on one alone let the lookup miss, so the pick fell through to the
    chat loader instead of navigating to Images or Video."""
    src = _read("features/model-picker/components/model-selector/pickers.tsx")
    block = re.search(r"const diffusionTaskById = useMemo\(.*?\n  \}, \[", src, re.S)
    assert block, "diffusionTaskById not found"
    body = block.group(0)
    assert "put(m.id, m.task);" in body and "put(m.model_id, m.task);" in body


def test_a_staged_download_that_never_starts_clears_the_queue():
    """requestStart can answer "error" (network failure, rejected scoped request, worker refused).
    Nothing completes after that, so leaving the head in place stranded the pick: the effect never
    re-ran and onReady never fired."""
    src = _read("features/hub/download-manager/use-staged-download.ts")
    assert 'if (outcome === "error") {' in src
    branch = src[src.index('if (outcome === "error") {') :][:400]
    assert "setQueue(null)" in branch


def test_staged_download_callbacks_are_bound_to_the_started_file_set():
    """Every scoped pick in a repo shares the "@diffusion" variant, so the variant alone cannot
    tell two file sets in that repo apart: restaging while the first job finishes let its
    completion pass for the new pick and load a checkpoint that had not downloaded."""
    src = _read("features/hub/download-manager/use-staged-download.ts")
    assert "const inFlight = useRef<{ key: string; generation: number } | null>(null);" in src
    assert "inFlight.current.key === entryKey(current)" in src
    assert "inFlight.current.generation === generation.current" in src
    # A fresh plan invalidates the previous job's callbacks.
    stage = re.search(r"const stage = useCallback\(.*?\}, \[\]\);", src, re.S)
    assert stage and "generation.current += 1;" in stage.group(0)
    for callback in ("onComplete", "onError", "onCancelled"):
        handler = re.search(rf"{callback}: \(variant\) => \{{\n(.*?)\n    \}},", src, re.S)
        assert handler and "isOurs(variant)" in handler.group(1), callback


def test_a_lost_generate_post_must_prove_it_reached_the_backend():
    """A rejected fetch does not say whether the POST landed. Treating an immediately idle progress
    read as success made a submission that never reached the server look like a finished image."""
    src = _read("features/images/images-page.tsx")
    fn = src[src.index("async function settleLostGeneration") :]
    fn = fn[: fn.index("\n}\n")]
    assert "knownIds" in fn and "sawActive" in fn
    assert "!knownIds.has(image.id)" in fn
    assert "did not reach the server" in fn
    # And the caller snapshots the ids BEFORE the POST.
    assert "new Set(galleryCache.images.map((image) => image.id))" in src