"""Canonical presentation contract for generated application admin surfaces.

This is a projection contract, not a capability or policy engine. It describes
the shell and the states Codegen may compose; the runtime contract remains the
source of truth for which platform capabilities are available.
"""
from __future__ import annotations

from typing import Any

ADMIN_PRESENTATION_CONTRACT_VERSION = "admin-shell-v1"


def build_admin_presentation_contract(
    runtime_contract: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Return a deterministic, safe-to-embed admin presentation projection."""
    contract = runtime_contract or {}
    capabilities = contract.get("capabilities") or {}
    search = capabilities.get("records.search.external_index") or {}
    project = contract.get("project") or {}
    application_name = str(project.get("name") or "Application").strip() or "Application"
    experience = contract.get("experience") if isinstance(contract.get("experience"), dict) else {}
    design = experience.get("design") if isinstance(experience.get("design"), dict) else {}
    raw_modules = experience.get("admin_modules")
    modules = raw_modules if isinstance(raw_modules, list) else []
    accent = str(design.get("accent") or "#2563eb")
    return {
        "contract_version": ADMIN_PRESENTATION_CONTRACT_VERSION,
        "profile": "professional-admin",
        "branding": {
            "application_name": application_name,
            "source": "core-project-identity",
            "admin_derivation": "operational-contrast",
        },
        "theme": {
            "source": "public-theme-brand-tokens",
            "admin_derivation": "dense-neutral",
            "allowed_overrides": ["accent", "radius", "spacing", "typography", "surface"],
            "defaults": {
                "accent": accent,
                "surface": "#f8fafc",
                "panel": "#ffffff",
                "text": "#0f172a",
                "muted": "#64748b",
                "radius": "12px",
                "density": "comfortable",
            },
        },
        "shell": {
            "navigation": ["sidebar", "header", "breadcrumbs", "page_header"],
            "states": ["loading", "empty", "error", "success", "configuration_required"],
            "responsive": ["desktop", "tablet", "mobile"],
            "accessibility": [
                "semantic_landmarks", "keyboard_navigation", "visible_focus", "reduced_motion"
            ],
        },
        "primitives": [
            "stat_card", "data_table", "filters", "search", "pagination",
            "record_detail", "form", "confirmation", "toast",
        ],
        "modules": [
            item.get("id")
            for item in modules
            if isinstance(item, dict) and isinstance(item.get("id"), str)
        ],
        "admitted_surfaces": {
            "auth": bool((capabilities.get("auth") or {}).get("magic_link")),
            "records": bool((capabilities.get("data") or {}).get("available")),
            "external_search": bool(search.get("available")),
            "email": bool((capabilities.get("email") or {}).get("available")),
        },
        "rules": [
            "compose navigation from admitted capabilities and installed App Blocks",
            "never invent entities, analytics, inventory, orders, or CRM modules",
            "keep branding as data; do not mutate semantic templates or capability policy",
            "preserve customer-owned or customer-modified admin files during reconciliation",
        ],
    }