"""Template use-cases: create, draft autosave, soft lock, publish, versions (TZ 2.1.4 А/Б, 2.8.6)."""

from __future__ import annotations

import copy
import re
import time
from datetime import timedelta
from typing import Any

from django.conf import settings
from django.db import IntegrityError, transaction
from django.db.models import F, Max, Q
from django.utils import timezone

from snapfile.assets.fonts import font_library
from snapfile.auth_sso.sessions import EditorPrincipal
from snapfile.core import ids
from snapfile.core.audit import Actor, audit
from snapfile.core.crypto import canonical_json, sha256_hex
from snapfile.core.errors import ApiError
from snapfile.core.locks import db_lock, incr_counter
from snapfile.core.storage import store
from snapfile.jobs.webhooks import enqueue_event
from snapfile.projects.models import Project
from snapfile.projects.variables import build_json_schema, example_data, get_tree, known_paths, merge_override
from snapfile.render.adapters import ProjectAssetResolver
from snapfile_render import ENGINE_VERSION
from snapfile_render.errors import RenderError

from .models import DEFAULT_OUTPUT, Template, TemplateVersion
from .scene import ensure_valid_draft, ensure_valid_scene, unknown_variables

KEY_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
MAX_DRAFT_BYTES = 10 * 1024 * 1024
SHEET_SIZES = {
    "A4": (595.28, 841.89),
    "A3": (841.89, 1190.55),
    "A5": (419.53, 595.28),
    "Letter": (612.0, 792.0),
    "Legal": (612.0, 1008.0),
}


def blank_document(fmt: str = "A4", orientation: str = "portrait", name: str = "Page 1") -> dict[str, Any]:
    w, h = SHEET_SIZES.get(fmt, SHEET_SIZES["A4"])
    if orientation == "landscape":
        w, h = h, w
    return {
        "formatVersion": 1,
        "meta": {},
        "defaults": {"fontFamily": "Inter", "fontSize": 10, "color": "#1A1A1A", "lineHeight": 1.3},
        "styles": {},
        "sheets": [
            {
                "id": "s1",
                "name": name,
                "format": fmt if fmt in SHEET_SIZES else "A4",
                "orientation": orientation,
                "size": {"w": w, "h": h},
                "background": {"type": "solid", "color": "#FFFFFF"},
                "children": [],
            }
        ],
    }


def doc_hash(document: dict[str, Any]) -> str:
    return sha256_hex(canonical_json(document))


def _uuid(prefix: str, value: str) -> Any:
    try:
        return ids.decode(prefix, value)
    except ids.InvalidId as exc:
        raise ApiError(404, "NOT_FOUND", "Not found") from exc


def get_template(project: Project, template_id: str, principal: EditorPrincipal | None = None) -> Template:
    t = (
        Template.objects.select_related("current_version")
        .filter(project=project, pk=_uuid("tpl", template_id), deleted_at__isnull=True)
        .first()
    )
    if t is None:
        raise ApiError(404, "TEMPLATE_NOT_FOUND", "Template not found")
    if principal is not None and principal.templates and t.key not in principal.templates:
        raise ApiError(403, "FORBIDDEN", "Template is outside of the session scope")
    if principal is not None and not user_allowed(t, principal.user_id, principal.role):
        raise ApiError(403, "ACCESS_DENIED", "You do not have access to this template")
    return t


def user_allowed(t: Template, user_id: str, role: str) -> bool:
    """``allowed_users`` limits non-admins; an empty list means everyone in the project."""
    allowed = t.allowed_users or []
    return role == "admin" or not allowed or any(str(u.get("id")) == str(user_id) for u in allowed)


def resolve_variant(t: Template, lang: Any) -> Template:
    """Language variant of a template: exact code, then base code (``en-US`` -> ``en``); otherwise ``t`` itself."""
    if not isinstance(lang, str) or not lang.strip():
        return t
    code = lang.strip().lower().replace("_", "-")
    codes = [code, code.split("-")[0]]
    if t.language and t.language.lower() in codes:
        return t
    base_id = t.variant_of_id or t.id
    family = (
        Template.objects.select_related("current_version")
        .filter(project_id=t.project_id, deleted_at__isnull=True, archived_at__isnull=True)
        .filter(current_version__isnull=False)
        .filter(Q(variant_of_id=base_id) | Q(pk=base_id))
    )
    by_lang = {(v.language or "").lower(): v for v in family}
    for c in codes:
        if c in by_lang:
            return by_lang[c]
    return t


def lang_codes(lang: Any) -> list[str]:
    """``es-MX`` -> ``["es-mx", "es"]``; empty -> ``[]``."""
    if not isinstance(lang, str) or not lang.strip():
        return []
    code = lang.strip().lower().replace("_", "-")
    return list(dict.fromkeys([code, code.split("-")[0]]))


def is_active(t: Template) -> bool:
    """Usable by the API: published and not archived."""
    return t.archived_at is None and t.current_version_id is not None


def resolve_api_template(project: Project, key: str, lang: Any) -> Template:
    """Template for a public API call.

    ``key`` is a group key when some template of the project has it as ``group_key``: then the active default
    template of the requested language is used (exact code, then base code), else the active default template
    without a language; nothing found is an error. Otherwise ``key`` is a template key (or ``tpl_`` id) and that
    template is used as is (language variants linked by ``variant_of`` still apply).
    """
    group = list(
        Template.objects.select_related("current_version").filter(
            project=project, deleted_at__isnull=True, group_key=key
        )
    )
    if not group:
        return resolve_variant(get_template_by_key(project, key), lang)
    defaults = {(t.language or "").lower(): t for t in group if t.is_default and is_active(t)}
    for code in lang_codes(lang):
        if code in defaults:
            return defaults[code]
    if "" in defaults:
        return defaults[""]
    asked = lang_codes(lang)
    msg = (
        f"Group {key!r} has no active default template for language {asked[0]!r} and no default without a language"
        if asked
        else f"Group {key!r} has no active default template without a language; pass lang"
    )
    raise ApiError(
        404,
        "DEFAULT_TEMPLATE_NOT_FOUND",
        msg,
        [{"group": key, "lang": asked[0] if asked else None, "defaults": sorted(k or "-" for k in defaults)}],
    )


def _settle_default(t: Template) -> None:
    """One default per (group, language): ``t`` stays the default, others of its slot lose the flag."""
    if not (t.is_default and t.group_key):
        return
    lang = (t.language or "").lower()
    rivals = Template.objects.filter(
        project_id=t.project_id, deleted_at__isnull=True, group_key=t.group_key, is_default=True
    ).exclude(pk=t.pk)
    ids_ = [r.pk for r in rivals.only("id", "language") if (r.language or "").lower() == lang]
    if ids_:
        Template.objects.filter(pk__in=ids_).update(is_default=False)


def clean_allowed_users(raw: Any) -> list[dict[str, str]]:
    if not isinstance(raw, list):
        raise ApiError(422, "VALIDATION_FAILED", "allowed_users must be a list", [{"pointer": "/allowed_users"}])
    out: dict[str, dict[str, str]] = {}
    for i, u in enumerate(raw):
        uid = u.get("id") if isinstance(u, dict) else None
        if uid is None or not str(uid).strip():
            raise ApiError(422, "VALIDATION_FAILED", "Each user needs an id", [{"pointer": f"/allowed_users/{i}/id"}])
        out[str(uid)] = {"id": str(uid), "name": str(u.get("name") or "")[:255]}
    return list(out.values())


def get_template_by_key(project: Project, key: str, *, allow_archived: bool = False) -> Template:
    q = Template.objects.select_related("current_version").filter(project=project, deleted_at__isnull=True)
    t = q.filter(key=key).first()
    if t is None and key.startswith("tpl_"):
        try:
            t = q.filter(pk=ids.decode("tpl", key)).first()
        except ids.InvalidId:
            t = None
    if t is None:
        raise ApiError(404, "TEMPLATE_NOT_FOUND", f"Template {key!r} not found")
    if t.archived_at is not None and not allow_archived:
        raise ApiError(
            409, "TEMPLATE_ARCHIVED", f"Template {key!r} is archived; unarchive it in the dashboard to use it"
        )
    return t


def _lock_info(t: Template) -> dict[str, Any] | None:
    if t.locked_by and t.locked_until and t.locked_until > timezone.now():
        return {"holder": t.locked_by, "expiresAt": t.locked_until.isoformat()}
    return None


def template_status(t: Template) -> str:
    """``archived`` (switched off) / ``draft`` (never published) / ``published`` / ``modified`` (draft differs)."""
    if t.archived_at is not None:
        return "archived"
    v = t.current_version
    if v is None:
        return "draft"
    return "published" if v.document_hash == t.draft_hash else "modified"


def thumbnail_url(t: Template) -> str:
    """Internal URL of the first-sheet PNG; the hash makes it cacheable and changes with the draft."""
    return f"/internal/v1/templates/{ids.encode('tpl', t.id)}/thumbnail?h={(t.draft_hash or '')[:12]}"


def template_dict(t: Template, *, draft: bool = False) -> dict[str, Any]:
    v = t.current_version
    tid = ids.encode("tpl", t.id)
    out: dict[str, Any] = {
        "id": tid,
        "key": t.key,
        "name": t.name,
        "status": template_status(t),
        "thumbnail_url": thumbnail_url(t),
        "description": t.description,
        "language": t.language,
        "archived_at": t.archived_at.isoformat() if t.archived_at else None,
        "group_key": t.group_key,
        "is_default": t.is_default,
        "variant_of": ids.encode("tpl", t.variant_of_id) if t.variant_of_id else None,
        "allowed_users": t.allowed_users or [],
        "tags": t.tags or [],
        "draft_revision": t.draft_revision,
        "draft_hash": t.draft_hash,
        "current_version": {
            "number": v.number,
            "id": ids.encode("ver", v.id),
            "published_at": v.published_at.isoformat(),
            "published_by": v.published_by,
        }
        if v
        else None,
        "output_defaults": {**DEFAULT_OUTPUT, **(t.output_defaults or {})},
        "sheets": [
            {
                "id": s.get("id"),
                "name": s.get("name"),
                "format": s.get("format"),
                "orientation": s.get("orientation"),
                "size": s.get("size"),
            }
            for s in (t.draft_document or {}).get("sheets", [])
        ],
        "lock": _lock_info(t),
        "created_by": t.created_by,
        "updated_by": t.updated_by,
        "created_at": t.created_at.isoformat(),
        "updated_at": t.updated_at.isoformat(),
    }
    if draft:
        out["draft_document"] = t.draft_document
        out["sample_data"] = t.sample_data
        out["test_data_sets"] = test_data_sets(t)
        out["variables_override"] = t.variables_override
    return out


def test_data_sets(t: Template) -> list[dict[str, Any]]:
    """All test data sets; the first one (id ``sample``) mirrors ``sample_data``."""
    extra = [x for x in (t.test_data_sets or []) if isinstance(x, dict) and x.get("id") != "sample"]
    sample = {"id": "sample", "name": "Sample data", "data": t.sample_data if isinstance(t.sample_data, dict) else {}}
    return [sample, *extra]


def _clean_sets(value: Any) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
    """Validate ``test_data_sets`` from PATCH; returns (extra sets, data of the ``sample`` set if present)."""
    if not isinstance(value, list) or len(value) > 50:
        raise ApiError(
            422, "VALIDATION_FAILED", "test_data_sets must be a list (max 50)", [{"pointer": "/test_data_sets"}]
        )
    seen: set[str] = set()
    extra: list[dict[str, Any]] = []
    sample: dict[str, Any] | None = None
    for i, item in enumerate(value):
        sid = item.get("id") if isinstance(item, dict) else None
        if not isinstance(sid, str) or not sid or len(sid) > 64 or sid in seen:
            raise ApiError(
                422, "VALIDATION_FAILED", "Each set needs a unique id", [{"pointer": f"/test_data_sets/{i}/id"}]
            )
        seen.add(sid)
        data = item.get("data")
        if not isinstance(data, dict):
            raise ApiError(
                422, "VALIDATION_FAILED", "Set data must be an object", [{"pointer": f"/test_data_sets/{i}/data"}]
            )
        if sid == "sample":
            sample = data
        else:
            extra.append({"id": sid, "name": str(item.get("name") or sid)[:120], "data": data})
    if len(canonical_json(extra).encode()) > MAX_DRAFT_BYTES:
        raise ApiError(413, "PAYLOAD_TOO_LARGE", "Test data sets exceed 10 MB")
    return extra, sample


def create_template(
    project: Project,
    actor: Actor,
    *,
    key: str,
    name: str,
    description: str | None = None,
    tags: list[str] | None = None,
    document: dict[str, Any] | None = None,
    fmt: str = "A4",
    orientation: str = "portrait",
    sample_data: dict[str, Any] | None = None,
    request: Any = None,
) -> Template:
    if not KEY_RE.match(key or ""):
        raise ApiError(422, "VALIDATION_FAILED", "key must match [a-z0-9][a-z0-9_-]*", [{"pointer": "/key"}])
    doc = document or blank_document(fmt, orientation)
    ensure_valid_scene(doc)
    snap = actor.snapshot()
    try:
        with transaction.atomic():
            t = Template.objects.create(
                project=project,
                key=key,
                name=name[:255],
                description=description,
                tags=tags,
                draft_document=doc,
                draft_revision=1,
                draft_hash=doc_hash(doc),
                output_defaults=dict(DEFAULT_OUTPUT),
                sample_data=sample_data,
                created_by=snap,
                updated_by=snap,
            )
            audit(
                "template.create",
                actor,
                project_id=project.id,
                subject_type="template",
                subject_id=t.id,
                request=request,
            )
    except IntegrityError as exc:
        raise ApiError(409, "KEY_EXISTS", f"Template key {key!r} already exists") from exc
    return t


def update_meta(t: Template, actor: Actor, fields: dict[str, Any], request: Any = None) -> Template:
    changes: dict[str, Any] = {}
    if fields.get("test_data_sets") is not None:
        extra, sample = _clean_sets(fields["test_data_sets"])
        t.test_data_sets = extra or None
        changes["test_data_sets"] = [None, [x["id"] for x in extra]]
        if sample is not None and fields.get("sample_data") is None:
            fields = {**fields, "sample_data": sample}
    if fields.get("default_format") is not None:
        fmt = fields["default_format"]
        if fmt not in ("pdf", "png", "jpg"):
            raise ApiError(422, "VALIDATION_FAILED", "Unknown format", [{"pointer": "/default_format"}])
        merged = {**(t.output_defaults or {}), **(fields.get("output_defaults") or {}), "format": fmt}
        fields = {**fields, "output_defaults": merged}
    if fields.get("allowed_users") is not None:
        fields = {**fields, "allowed_users": clean_allowed_users(fields["allowed_users"])}
    for name in (
        "name",
        "key",
        "description",
        "language",
        "allowed_users",
        "tags",
        "output_defaults",
        "sample_data",
        "variables_override",
    ):
        if name in fields and fields[name] is not None:
            if name == "key" and not KEY_RE.match(fields[name]):
                raise ApiError(422, "VALIDATION_FAILED", "Invalid key", [{"pointer": "/key"}])
            changes[name] = [getattr(t, name) if name not in ("sample_data",) else None, fields[name]]
            setattr(t, name, fields[name] or None if name == "language" else fields[name])
    if "group_key" in fields and fields["group_key"] is not None:
        group = str(fields["group_key"]).strip().lower() or None
        if group is not None:
            if not KEY_RE.match(group):
                raise ApiError(422, "VALIDATION_FAILED", "Invalid group key", [{"pointer": "/group_key"}])
            # a group must not hide a template (outside the group) that callers reach by the same key
            clash = (
                Template.objects.filter(project_id=t.project_id, deleted_at__isnull=True, key=group)
                .exclude(pk=t.pk)
                .exclude(group_key=group)
                .first()
            )
            if clash is not None:
                raise ApiError(
                    409,
                    "GROUP_KEY_TAKEN",
                    f"Key {group!r} belongs to template {clash.name!r} outside this group; add it to the group "
                    "or choose another group key",
                    [{"pointer": "/group_key"}],
                )
        changes["group_key"] = [t.group_key, group]
        t.group_key = group
        if group is None:
            t.is_default = False
    if fields.get("is_default") is not None:
        if fields["is_default"] and not t.group_key:
            raise ApiError(422, "GROUP_REQUIRED", "Set a group key before making the template a default")
        changes["is_default"] = [t.is_default, bool(fields["is_default"])]
        t.is_default = bool(fields["is_default"])
    archive_event = None
    if fields.get("archived") is not None and bool(fields["archived"]) != (t.archived_at is not None):
        t.archived_at = timezone.now() if fields["archived"] else None
        archive_event = "template.archive" if fields["archived"] else "template.unarchive"
    t.updated_by = actor.snapshot()
    try:
        with transaction.atomic():
            t.save()
            _settle_default(t)
            if archive_event:
                audit(
                    archive_event, actor, project_id=t.project_id, subject_type="template", subject_id=t.id,
                    request=request,
                )
            audit(
                "template.update",
                actor,
                project_id=t.project_id,
                subject_type="template",
                subject_id=t.id,
                changes={k: v for k, v in changes.items() if k != "sample_data"},
                request=request,
            )
    except IntegrityError as exc:
        raise ApiError(409, "KEY_EXISTS", "Template key already exists") from exc
    return t


def _check_lock(t: Template, principal: EditorPrincipal) -> None:
    info = _lock_info(t)
    if info and (t.locked_by or {}).get("sid") != principal.session_id:
        raise ApiError(409, "TEMPLATE_LOCKED", f"Template is being edited by {info['holder'].get('name')}", [info])


def save_draft(
    t: Template, principal: EditorPrincipal, document: dict[str, Any], base_revision: int, request: Any = None
) -> dict[str, Any]:
    size = len(canonical_json(document).encode())
    if size > MAX_DRAFT_BYTES:
        raise ApiError(413, "PAYLOAD_TOO_LARGE", "Draft exceeds 10 MB")
    if incr_counter(f"autosave:{principal.session_id}:{timezone.now():%Y%m%d%H%M}", 120) > 60:
        raise ApiError(429, "RATE_LIMITED", "Too many autosaves", headers={"Retry-After": "5"})
    warnings = ensure_valid_draft(document)
    _check_lock(t, principal)
    now = timezone.now()
    snap = principal.snapshot()
    h = doc_hash(document)
    updated = Template.objects.filter(pk=t.pk, draft_revision=base_revision).update(
        draft_document=document, draft_revision=F("draft_revision") + 1, draft_hash=h, updated_by=snap, updated_at=now
    )
    if not updated:
        cur = Template.objects.filter(pk=t.pk).values("draft_revision", "updated_by", "updated_at").first() or {}
        raise ApiError(
            409,
            "REVISION_CONFLICT",
            "Draft was changed elsewhere",
            [
                {
                    "current_revision": cur.get("draft_revision"),
                    "updated_by": cur.get("updated_by"),
                    "updated_at": cur.get("updated_at").isoformat() if cur.get("updated_at") else None,
                }
            ],
        )
    # Audit is aggregated: at most one record per 5 minutes per editor session.
    if incr_counter(f"auditdraft:{principal.session_id}:{int(time.time() // 300)}", 600) == 1:
        audit(
            "template.draft.save",
            principal.actor,
            project_id=t.project_id,
            subject_type="template",
            subject_id=t.id,
            changes={"revision": base_revision + 1},
            request=request,
        )
    return {"revision": base_revision + 1, "hash": h, "saved_at": now.isoformat(), "warnings": warnings}


def take_lock(t: Template, principal: EditorPrincipal, takeover: bool = False) -> dict[str, Any]:
    now = timezone.now()
    with transaction.atomic():
        locked = Template.objects.select_for_update().get(pk=t.pk)
        info = _lock_info(locked)
        foreign = info and (locked.locked_by or {}).get("sid") != principal.session_id
        if foreign and not (takeover and principal.role == "admin"):
            raise ApiError(409, "TEMPLATE_LOCKED", f"Template is being edited by {info['holder'].get('name')}", [info])
        if not info or (locked.locked_by or {}).get("sid") != principal.session_id:
            since = now.isoformat()
        else:
            since = (locked.locked_by or {}).get("since", now.isoformat())
        locked.locked_by = {
            "id": principal.user_id,
            "name": principal.name,
            "sid": principal.session_id,
            "role": principal.role,
            "since": since,
        }
        locked.locked_until = now + timedelta(seconds=settings.TEMPLATE_LOCK_TTL)
        Template.objects.filter(pk=t.pk).update(locked_by=locked.locked_by, locked_until=locked.locked_until)
    return {
        "lockToken": principal.session_id,
        "holder": locked.locked_by,
        "expiresAt": locked.locked_until.isoformat(),
        "ttl": settings.TEMPLATE_LOCK_TTL,
    }


def release_lock(t: Template, principal: EditorPrincipal) -> None:
    holder = (t.locked_by or {}).get("sid")
    if holder and holder != principal.session_id and principal.role != "admin":
        raise ApiError(403, "ROLE_INSUFFICIENT", "Only the holder or an admin can release the lock")
    Template.objects.filter(pk=t.pk).update(locked_by=None, locked_until=None)


def effective_variables(t: Template) -> list[dict[str, Any]]:
    return merge_override(get_tree(t.project), t.variables_override)


def _check_dependencies(project: Project, plan: dict[str, Any]) -> tuple[list[dict[str, Any]], dict[str, Any]]:
    errors = []
    resolver = ProjectAssetResolver(project, allow_fetch=False)
    assets = []
    for aid in plan.get("assets", []):
        if resolver.image(aid) is None:
            errors.append({"rule": "SCENE_MISSING_ASSET", "assetId": aid, "message": f"Asset {aid} not found"})
        else:
            assets.append(aid)
    lib = font_library(project)
    fonts = []
    for fid in plan.get("fonts", []):
        if not any(fid in f.ids for f in lib.faces):
            errors.append({"rule": "SCENE_MISSING_FONT", "fontId": fid, "message": f"Font {fid} not found"})
        else:
            fonts.append(fid)
    families = sorted({f[0] for f in plan.get("families", [])})
    for fam in families:
        if not lib.has_family(fam):
            errors.append({"rule": "SCENE_MISSING_FONT", "family": fam, "message": f"Font family {fam!r} not found"})
    return errors, {"assets": assets, "fonts": fonts, "families": families}


def check_render(t: Template, plan: dict[str, Any], data: dict[str, Any]) -> dict[str, Any]:
    from snapfile.render.service import render_for_project

    started = time.perf_counter()
    try:
        result = render_for_project(t.project, plan, data, {"format": "pdf"}, timeout_s=settings.RENDER_TIMEOUT_SYNC)
    except RenderError as exc:
        raise ApiError(
            422,
            "TEMPLATE_CHECK_FAILED",
            f"Test render failed: {exc.message}",
            [{"rule": exc.code, **d} for d in exc.details] or [{"rule": exc.code}],
        ) from exc
    return {
        "pages": result.page_count,
        "total_ms": int((time.perf_counter() - started) * 1000),
        "warnings": result.warnings[:50],
    }


def publish(
    t: Template,
    principal: EditorPrincipal,
    *,
    base_revision: int | None,
    comment: str | None,
    check: bool = True,
    acknowledge: list[str] | None = None,
    request: Any = None,
) -> TemplateVersion:
    if not principal.can("publish"):
        raise ApiError(403, "ROLE_INSUFFICIENT", "Publishing is not allowed for this session")
    acknowledge = acknowledge or []
    if base_revision is not None and t.draft_revision != base_revision:
        raise ApiError(409, "REVISION_CONFLICT", "Draft revision changed", [{"current_revision": t.draft_revision}])
    document = copy.deepcopy(t.draft_document)
    plan, scene_warnings = ensure_valid_scene(document)
    tree = effective_variables(t)
    warnings: list[dict[str, Any]] = list(scene_warnings)
    unknown = unknown_variables(plan, known_paths(tree))
    if unknown:
        item = {"code": "SCENE_UNKNOWN_VARIABLE", "paths": unknown[:50]}
        if "SCENE_UNKNOWN_VARIABLE" not in acknowledge:
            raise ApiError(
                422,
                "SCENE_UNKNOWN_VARIABLE",
                "Template uses variables missing from the schema",
                [{"rule": "SCENE_UNKNOWN_VARIABLE", "path": p} for p in unknown[:100]],
            )
        warnings.append(item)
    dep_errors, deps = _check_dependencies(t.project, plan)
    if dep_errors:
        raise ApiError(422, "SCENE_INVALID", "Template references missing resources", dep_errors)
    check_info = None
    if check:
        sample = t.sample_data if isinstance(t.sample_data, dict) else example_data(tree)
        check_info = check_render(t, plan, sample)
    strict = bool(t.project.setting("strict_payload"))
    snap = principal.snapshot()
    owner = f"publish:{principal.session_id}"
    with db_lock(f"publish:{t.id}", owner, lease_seconds=30, wait_seconds=5) as got:
        if not got:
            raise ApiError(409, "TEMPLATE_LOCKED", "Another publish is in progress")
        with transaction.atomic():
            locked = Template.objects.select_for_update().get(pk=t.pk)
            if locked.draft_revision != t.draft_revision:
                raise ApiError(
                    409,
                    "REVISION_CONFLICT",
                    "Draft changed during publish",
                    [{"current_revision": locked.draft_revision}],
                )
            number = (TemplateVersion.objects.filter(template=locked).aggregate(m=Max("number"))["m"] or 0) + 1
            version = TemplateVersion.objects.create(
                template=locked,
                project_id=locked.project_id,
                number=number,
                status="published",
                document=document,
                document_hash=doc_hash(document),
                schema_snapshot=tree,
                json_schema=build_json_schema(tree, strict=strict, title=locked.name),
                format_version=int(document.get("formatVersion", 1)),
                engine_version=ENGINE_VERSION,
                dependencies=deps,
                comment=comment,
                published_by=snap,
            )
            Template.objects.filter(pk=locked.pk).update(current_version=version, updated_at=timezone.now())
            audit(
                "template.publish",
                principal.actor,
                project_id=locked.project_id,
                subject_type="version",
                subject_id=version.id,
                changes={"number": number, "comment": comment},
                request=request,
            )
            enqueue_event(
                t.project,
                "template.published",
                {
                    "template": {"key": locked.key, "id": ids.encode("tpl", locked.id)},
                    "version": {"number": number, "published_by": snap},
                },
            )
    from snapfile.render.plans import version_plan

    version_plan(version)
    version.check_render = check_info  # type: ignore[attr-defined]
    version.publish_warnings = warnings  # type: ignore[attr-defined]
    return version


def version_dict(v: TemplateVersion, *, document: bool = False) -> dict[str, Any]:
    out = {
        "id": ids.encode("ver", v.id),
        "number": v.number,
        "status": v.status,
        "comment": v.comment,
        "published_by": v.published_by,
        "published_at": v.published_at.isoformat(),
        "engine_version": v.engine_version,
        "plan_status": v.plan_status,
        "document_hash": v.document_hash,
    }
    if document:
        out["document"] = v.document
        out["json_schema"] = v.json_schema
    return out


def activate_version(t: Template, number: int, principal: EditorPrincipal, request: Any = None) -> TemplateVersion:
    v = TemplateVersion.objects.filter(template=t, number=number).first()
    if v is None:
        raise ApiError(404, "NOT_FOUND", f"Version {number} not found")
    with transaction.atomic():
        Template.objects.filter(pk=t.pk).update(current_version=v, updated_at=timezone.now())
        audit(
            "template.version.activate",
            principal.actor,
            project_id=t.project_id,
            subject_type="version",
            subject_id=v.id,
            changes={"number": number},
            request=request,
        )
        enqueue_event(
            t.project, "template.version.activated", {"template": {"key": t.key}, "version": {"number": number}}
        )
    return v


def restore_version(t: Template, number: int, principal: EditorPrincipal, request: Any = None) -> dict[str, Any]:
    v = TemplateVersion.objects.filter(template=t, number=number).first()
    if v is None:
        raise ApiError(404, "NOT_FOUND", f"Version {number} not found")
    _check_lock(t, principal)
    doc = copy.deepcopy(v.document)
    now = timezone.now()
    Template.objects.filter(pk=t.pk).update(
        draft_document=doc,
        draft_revision=F("draft_revision") + 1,
        draft_hash=doc_hash(doc),
        updated_by=principal.snapshot(),
        updated_at=now,
    )
    audit(
        "template.version.restore",
        principal.actor,
        project_id=t.project_id,
        subject_type="version",
        subject_id=v.id,
        request=request,
    )
    t.refresh_from_db()
    return {"revision": t.draft_revision, "hash": t.draft_hash}


def duplicate(
    t: Template,
    actor: Actor,
    key: str | None,
    name: str | None,
    request: Any = None,
    language: str | None = None,
    as_variant: bool = False,
) -> Template:
    base_key = key or f"{t.key}-copy"
    candidate = base_key
    n = 2
    while Template.objects.filter(project_id=t.project_id, key=candidate).exists() and key is None:
        candidate = f"{base_key}-{n}"
        n += 1
    dup = create_template(
        t.project,
        actor,
        key=candidate[:64],
        name=name or f"{t.name} (copy)",
        description=t.description,
        tags=t.tags,
        document=copy.deepcopy(t.draft_document),
        sample_data=copy.deepcopy(t.sample_data),
        request=request,
    )
    if t.test_data_sets:
        dup.test_data_sets = copy.deepcopy(t.test_data_sets)
        Template.objects.filter(pk=dup.pk).update(test_data_sets=dup.test_data_sets)
    if language or as_variant:
        dup.language = language or t.language
        dup.variant_of_id = (t.variant_of_id or t.id) if as_variant else None
        Template.objects.filter(pk=dup.pk).update(language=dup.language, variant_of_id=dup.variant_of_id)
    if t.group_key:  # the copy joins the same group as a non-default template
        dup.group_key = t.group_key
        Template.objects.filter(pk=dup.pk).update(group_key=t.group_key)
    return dup


def soft_delete(t: Template, actor: Actor, request: Any = None) -> None:
    now = timezone.now()
    # Free the key for reuse while keeping the row for audit (TZ 2.2.1 p.9).
    Template.objects.filter(pk=t.pk).update(deleted_at=now, key=f"{t.key[:40]}~del{int(now.timestamp())}")
    audit("template.delete", actor, project_id=t.project_id, subject_type="template", subject_id=t.id, request=request)


def purge(t: Template, actor: Actor, request: Any = None) -> None:
    """Delete an archived template for good: versions, generations with their files, thumbnails."""
    from snapfile.jobs.models import RenderJob
    from snapfile.jobs.service import delete_job

    if t.archived_at is None:
        raise ApiError(409, "TEMPLATE_NOT_ARCHIVED", "Only an archived template can be deleted permanently")
    jobs = 0
    for job in RenderJob.objects.filter(template=t).prefetch_related("files").iterator(chunk_size=200):
        delete_job(job)
        jobs += 1
    store().delete_tree(f"thumbs/{t.project_id}/{t.id}")
    meta = {"key": t.key, "name": t.name, "jobs": jobs}
    tid, pid = t.id, t.project_id
    t.delete()
    audit(
        "template.purge", actor, project_id=pid, subject_type="template", subject_id=tid, changes=meta, request=request
    )


def _flat_nodes(doc: dict[str, Any]) -> dict[str, str]:
    """node id -> canonical JSON of the node without its nested children (for the publish summary)."""
    out: dict[str, str] = {}
    nested = ("children", "item", "header", "footer", "emptyState")

    def walk(nodes: Any) -> None:
        for n in nodes or []:
            if not isinstance(n, dict):
                continue
            if n.get("id"):
                out[str(n["id"])] = canonical_json({k: v for k, v in n.items() if k not in nested})
            walk(n.get("children"))
            for part in nested[1:]:
                if isinstance(n.get(part), dict):
                    walk(n[part].get("children"))

    for sheet in (doc or {}).get("sheets") or []:
        if isinstance(sheet, dict):
            walk(sheet.get("children"))
    return out


def draft_changes(t: Template, draft_plan_vars: list[str] | None) -> dict[str, Any] | None:
    """Summary "changes since vN" for the publish dialog (I16 ``changes``)."""
    v = t.current_version
    if v is None:
        return None
    old, new = _flat_nodes(v.document), _flat_nodes(t.draft_document)
    changed = sum(1 for k in new.keys() & old.keys() if new[k] != old[k])
    old_vars: set[str] = set()
    if draft_plan_vars is not None:
        from snapfile.render.plans import version_plan

        try:
            old_vars = set(version_plan(v)[0].get("variables") or [])
        except RenderError:
            old_vars = set()
    return {
        "since_version": v.number,
        "sheets": len(t.draft_document.get("sheets") or []) - len(v.document.get("sheets") or []),
        "nodes_added": len(new.keys() - old.keys()),
        "nodes_removed": len(old.keys() - new.keys()),
        "nodes_changed": changed + len(new.keys() - old.keys()) + len(old.keys() - new.keys()),
        "variables_added": len(set(draft_plan_vars or []) - old_vars),
    }
