@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-tools/clis/maggie_template_package.py

@@ -0,0 +1,1141 @@
+#!/usr/bin/env python3
+"""Package-quality checks, design measurement, studio preview, and image review
+for Maggie marketplace templates.
+
+The functions here are read-only unless a caller passes ``write=True``. They
+make no network or model calls; optional local tools (Pillow, tesseract,
+ImageMagick, google-chrome) are used only when installed.
+"""
+
+from __future__ import annotations
+
+import colorsys
+import html as html_lib
+import json
+import re
+import shutil
+import struct
+import subprocess
+import threading
+import zlib
+from datetime import datetime, timezone
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+# sharp's documented default `limitInputPixels` is 268402689 (0x3FFF * 0x3FFF).
+# Package screenshots stay far below it so standard tooling (sharp, Pillow's
+# decompression-bomb guard at ~89 MP, WebP's 16383 px edge) never needs limits
+# disabled. Full-page captures are tiled instead (see the marketplace skill).
+SHARP_DEFAULT_LIMIT_INPUT_PIXELS = 268_402_689
+SCREENSHOT_PIXEL_BUDGET = 40_000_000
+SCREENSHOT_MAX_EDGE = 16_383
+SCREENSHOT_TILE_HEIGHT = 4_096
+IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".webp", ".gif", ".avif", ".svg"}
+CAPTURED_PROVIDER = "captured-source"
+UNRECORDED_PROVIDER = "unrecorded"
+NON_GENERATED_PROVIDERS = {CAPTURED_PROVIDER, UNRECORDED_PROVIDER, "pending", "source-derived-local", "", None}
+STUDIO_VIEWPORTS = (390, 768, 1024, 1440)
+PALETTE_ROLES = ("canvas", "panel", "soft", "text", "accent", "accentText", "onAccent", "dark", "deep")
+HEX_RE = re.compile(r"#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{3})(?![0-9a-fA-F])")
+SERIF_HINTS = ("serif", "garamond", "playfair", "cormorant", "merriweather", "lora", "fraunces", "baskerville", "bodoni", "didot", "caslon", "instrument serif", "dm serif", "libre", "crimson", "prata", "marcellus", "cinzel", "italiana", "gloock")
+GENERIC_NAME_WORDS = {
+    "spa", "spas", "wellness", "beauty", "studio", "salon", "massage", "therapy", "clinic", "medical", "medspa", "landing",
+    "page", "template", "premium", "luxury", "editorial", "the", "and", "of", "for", "in", "a", "an", "your", "with", "by",
+    "health", "care", "body", "skin", "hair", "head", "foot", "float", "booking", "book", "resort", "hotel", "recovery",
+    "inner", "radiance", "discover", "considered", "london", "uk", "thai", "korean", "traditional", "traditionelle",
+    "thai-massage", "wellbeing", "aesthetics", "treatments", "home", "official", "site", "maggie", "restoration", "repair",
+    "service", "card", "cards", "damaged", "fix", "premier", "&", "-", "|",
+}
+HUE_WORDS = (
+    (0, "Rose"), (15, "Coral"), (25, "Terracotta"), (38, "Amber"), (50, "Ochre"), (68, "Olive"), (95, "Moss"),
+    (135, "Sage"), (160, "Jade"), (180, "Teal"), (200, "Ocean"), (222, "Cobalt"), (242, "Indigo"), (262, "Iris"),
+    (280, "Violet"), (305, "Plum"), (325, "Orchid"), (345, "Rose"),
+)
+# Tailwind v3 default neutral scales, so `bg-stone-50`/`text-zinc-900` resolve.
+_TW_STEPS = ("50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950")
+_TW_NEUTRALS = {
+    "slate": "f8fafc f1f5f9 e2e8f0 cbd5e1 94a3b8 64748b 475569 334155 1e293b 0f172a 020617",
+    "gray": "f9fafb f3f4f6 e5e7eb d1d5db 9ca3af 6b7280 4b5563 374151 1f2937 111827 030712",
+    "zinc": "fafafa f4f4f5 e4e4e7 d4d4d8 a1a1aa 71717a 52525b 3f3f46 27272a 18181b 09090b",
+    "neutral": "fafafa f5f5f5 e5e5e5 d4d4d4 a3a3a3 737373 525252 404040 262626 171717 0a0a0a",
+    "stone": "fafaf9 f5f5f4 e7e5e4 d6d3d1 a8a29e 78716c 57534e 44403c 292524 1c1917 0c0a09",
+}
+TAILWIND_NEUTRALS = {f"{name}-{step}": "#" + value.upper() for name, values in _TW_NEUTRALS.items() for step, value in zip(_TW_STEPS, values.split())}
+CONTENT_SCHEMA_VERSION = "maggie-template-content-v1"
+REPORT_SCHEMA_VERSION = "maggie-image-generation-report-v1"
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        raise ValueError(f"invalid JSON in {path.name}: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError(f"{path.name} must contain a JSON object")
+    return value
+
+
+def _write_json(path: Path, value: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Image decoding
+
+
+def _png_info(data: bytes) -> dict:
+    if data[:8] != b"\x89PNG\r\n\x1a\n":
+        return {"format": "png", "decodable": False, "error": "missing PNG signature"}
+    offset, idat, header = 8, bytearray(), None
+    while offset + 12 <= len(data):
+        length, kind = struct.unpack(">I4s", data[offset:offset + 8])
+        end = offset + 12 + length
+        if end > len(data):
+            return {"format": "png", "decodable": False, "error": f"truncated {kind.decode('latin-1')} chunk"}
+        body = data[offset + 8:offset + 8 + length]
+        (crc,) = struct.unpack(">I", data[offset + 8 + length:end])
+        if zlib.crc32(kind + body) & 0xFFFFFFFF != crc:
+            return {"format": "png", "decodable": False, "error": f"{kind.decode('latin-1')} chunk CRC mismatch (corrupt image data)", **(header or {})}
+        if kind == b"IHDR":
+            width, height, depth, colour, _, _, interlace = struct.unpack(">IIBBBBB", body)
+            header = {"width": width, "height": height, "depth": depth, "colourType": colour, "interlace": interlace}
+        elif kind == b"IDAT":
+            idat.extend(body)
+        elif kind == b"IEND":
+            break
+        offset = end
+    if not header:
+        return {"format": "png", "decodable": False, "error": "missing IHDR chunk"}
+    try:
+        raw = zlib.decompress(bytes(idat))
+    except zlib.error as error:
+        return {"format": "png", "decodable": False, "error": f"image data does not inflate: {error}", **header}
+    channels = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}.get(header["colourType"], 0)
+    if channels and header["interlace"] == 0:
+        stride = (header["width"] * channels * header["depth"] + 7) // 8 + 1
+        if len(raw) != stride * header["height"]:
+            return {"format": "png", "decodable": False, "error": "decoded size does not match the PNG header", **header}
+    return {"format": "png", "decodable": True, **header}
+
+
+def _jpeg_info(data: bytes) -> dict:
+    if data[:2] != b"\xff\xd8":
+        return {"format": "jpeg", "decodable": False, "error": "missing JPEG start marker"}
+    offset, size = 2, None
+    while offset + 4 <= len(data):
+        if data[offset] != 0xFF:
+            offset += 1
+            continue
+        marker = data[offset + 1]
+        if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7:
+            offset += 2
+            continue
+        (length,) = struct.unpack(">H", data[offset + 2:offset + 4])
+        if marker in (0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF):
+            height, width = struct.unpack(">HH", data[offset + 5:offset + 9])
+            size = {"width": width, "height": height}
+            break
+        offset += 2 + length
+    if not size:
+        return {"format": "jpeg", "decodable": False, "error": "missing JPEG frame header"}
+    if b"\xff\xd9" not in data[-4096:]:
+        return {"format": "jpeg", "decodable": False, "error": "missing JPEG end marker (truncated)", **size}
+    return {"format": "jpeg", "decodable": True, **size}
+
+
+def _webp_info(data: bytes) -> dict:
+    if data[:4] != b"RIFF" or data[8:12] != b"WEBP":
+        return {"format": "webp", "decodable": False, "error": "missing WebP header"}
+    (riff_size,) = struct.unpack("<I", data[4:8])
+    if riff_size + 8 > len(data):
+        return {"format": "webp", "decodable": False, "error": "truncated WebP container"}
+    chunk = data[12:16]
+    if chunk == b"VP8X":
+        width = 1 + int.from_bytes(data[24:27], "little")
+        height = 1 + int.from_bytes(data[27:30], "little")
+    elif chunk == b"VP8L":
+        bits = int.from_bytes(data[21:25], "little")
+        width, height = (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1
+    elif chunk == b"VP8 ":
+        width, height = (struct.unpack("<H", data[26:28])[0] & 0x3FFF), (struct.unpack("<H", data[28:30])[0] & 0x3FFF)
+    else:
+        return {"format": "webp", "decodable": False, "error": "unknown WebP chunk"}
+    return {"format": "webp", "decodable": True, "width": width, "height": height}
+
+
+def sniff_image_format(data: bytes) -> str | None:
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        return "png"
+    if data[:2] == b"\xff\xd8":
+        return "jpeg"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "webp"
+    if data[:6] in (b"GIF87a", b"GIF89a"):
+        return "gif"
+    if data[4:12] in (b"ftypavif", b"ftypavis"):
+        return "avif"
+    head = data[:512].lstrip().lower()
+    if head.startswith(b"<svg") or (head.startswith(b"<?xml") and b"<svg" in data[:2048].lower()):
+        return "svg"
+    return None
+
+
+def inspect_image(path: Path) -> dict:
+    """Return format, dimensions, and whether the image fully decodes."""
+    data = path.read_bytes()
+    kind = sniff_image_format(data)
+    if kind == "png":
+        info = _png_info(data)
+    elif kind == "jpeg":
+        info = _jpeg_info(data)
+    elif kind == "webp":
+        info = _webp_info(data)
+    elif kind in {"gif", "avif", "svg"}:
+        info = {"format": kind, "decodable": True}
+    else:
+        return {"format": None, "decodable": False, "error": "unrecognised image format"}
+    if info.get("decodable") and kind in {"jpeg", "webp", "gif"}:
+        try:  # Pillow, when installed, catches corrupt entropy-coded data too.
+            from PIL import Image  # type: ignore
+
+            with Image.open(path) as image:
+                image.load()
+        except ImportError:
+            pass
+        except Exception as error:  # noqa: BLE001 - any decoder failure is the finding
+            info.update({"decodable": False, "error": f"decoder failed: {error}"})
+    return info
+
+
+# ---------------------------------------------------------------------------
+# T13a: screenshot integrity and pixel budget
+
+
+def screenshot_report(path: Path) -> dict:
+    files = {}
+    for item in sorted((path / "screenshots").glob("*")) if (path / "screenshots").is_dir() else []:
+        if not item.is_file() or item.suffix.lower() not in IMAGE_SUFFIXES:
+            continue
+        info = inspect_image(item)
+        entry = {key: info[key] for key in ("format", "width", "height", "decodable", "error") if key in info}
+        width, height = info.get("width") or 0, info.get("height") or 0
+        if width * height > SCREENSHOT_PIXEL_BUDGET or max(width, height) > SCREENSHOT_MAX_EDGE:
+            entry["overBudget"] = True
+        files[item.name] = entry
+    failing = [name for name, entry in files.items() if not entry.get("decodable") or entry.get("overBudget")]
+    return {
+        "status": "recapture-required" if failing else "passed",
+        "checkedAt": now(),
+        "pixelBudget": SCREENSHOT_PIXEL_BUDGET,
+        "maxEdge": SCREENSHOT_MAX_EDGE,
+        "files": files,
+    }
+
+
+def audit_screenshots(path: Path) -> list[str]:
+    errors = []
+    report = screenshot_report(path)
+    for name, entry in report["files"].items():
+        if not entry.get("decodable"):
+            errors.append(f"screenshot is not decodable and must be recaptured: screenshots/{name} ({entry.get('error', 'unknown error')})")
+        if entry.get("overBudget"):
+            errors.append(
+                f"screenshot exceeds the {SCREENSHOT_PIXEL_BUDGET // 1_000_000} MP / {SCREENSHOT_MAX_EDGE}px budget: screenshots/{name} "
+                f"({entry.get('width')}x{entry.get('height')}); tile full-page captures into <= {SCREENSHOT_TILE_HEIGHT}px segments or ship a compressed WebP preview"
+            )
+    metadata_path = path / "template.json"
+    if metadata_path.exists():
+        try:
+            review = _read_json(metadata_path).get("screenshotReview")
+        except ValueError:
+            review = None
+        if isinstance(review, dict) and review.get("status") == "recapture-required" and not errors:
+            errors.append("template.json screenshotReview is recapture-required; recapture and rerun audit-package --record")
+    return errors
+
+
+# ---------------------------------------------------------------------------
+# T13c: asset provenance
+
+
+def _asset_files(path: Path) -> list[Path]:
+    root = path / "assets"
+    if not root.is_dir():
+        return []
+    files = []
+    for item in sorted(root.rglob("*")):
+        if not item.is_file():
+            continue
+        relative = item.relative_to(path)
+        if "phosphor" in relative.parts or item.suffix.lower() in {".css", ".woff", ".woff2", ".ttf", ".otf", ".js", ".map"}:
+            continue  # vendored runtime files are covered by the stylesheet/icon gates
+        if item.suffix.lower() in IMAGE_SUFFIXES or not item.suffix:
+            files.append(item)
+    return files
+
+
+def manifest_provider(manifest_path: Path) -> str | None:
+    """Top-level provider applies to entries without one, except the pipeline placeholder."""
+    if not manifest_path.exists():
+        return None
+    provider = _read_json(manifest_path).get("provider")
+    return None if provider in {None, "", "maggie-marketplace-pipeline"} else str(provider)
+
+
+def audit_asset_provenance(path: Path, published: bool = False) -> list[str]:
+    errors = []
+    manifest_path = path / "generated-asset-manifest.json"
+    try:
+        entries = _read_json(manifest_path).get("assets", []) if manifest_path.exists() else []
+    except ValueError as error:
+        return [f"invalid generated asset manifest: {error}"]
+    listed = {str(item.get("path")): item for item in entries if isinstance(item, dict) and item.get("path")}
+    inherited = manifest_provider(manifest_path)
+    for item in _asset_files(path):
+        relative = item.relative_to(path).as_posix()
+        if not item.suffix:
+            errors.append(f"asset has no file extension: {relative}")
+        entry = listed.get(relative)
+        if entry is None:
+            errors.append(f"asset is not listed in generated-asset-manifest.json: {relative}")
+            continue
+        provider = entry.get("provider") or inherited
+        if not provider or not entry.get("role"):
+            errors.append(f"asset manifest entry needs provider and role: {relative}")
+        if provider in {CAPTURED_PROVIDER, UNRECORDED_PROVIDER} and entry.get("reuse") is not False:
+            errors.append(f"{provider} asset must be marked reuse=false: {relative}")
+        if published and provider == CAPTURED_PROVIDER:
+            errors.append(f"captured third-party asset must be replaced before publishing: {relative}")
+        if published and provider == UNRECORDED_PROVIDER:
+            errors.append(f"asset provenance must be confirmed before publishing: {relative}")
+    return errors
+
+
+def repair_asset_provenance(path: Path, write: bool = False) -> dict:
+    """List every unlisted asset honestly and give extensionless files a suffix."""
+    manifest_path = path / "generated-asset-manifest.json"
+    manifest = _read_json(manifest_path) if manifest_path.exists() else {"provider": "maggie-marketplace-pipeline", "assets": []}
+    entries = manifest.setdefault("assets", [])
+    source_items = {}
+    source_manifest = path / "source" / "asset-manifest.json"
+    if source_manifest.exists():
+        for item in _read_json(source_manifest).get("items", []):
+            name = Path(str(item.get("local_path") or item.get("project_path") or "")).name
+            if name:
+                source_items[name] = item
+    alts = {}
+    inventory = path / "image-inventory.json"
+    if inventory.exists():
+        for item in _read_json(inventory).get("occurrences", []):
+            if item.get("path"):
+                alts.setdefault(item["path"], item.get("alt") or "")
+    renames, added = [], []
+    listed = {item.get("path") for item in entries if isinstance(item, dict)}
+    for item in _asset_files(path):
+        relative = item.relative_to(path).as_posix()
+        source = source_items.get(item.name)
+        target = item
+        if not item.suffix:
+            kind = sniff_image_format(item.read_bytes()[:4096])
+            suffix = {"jpeg": ".jpg"}.get(kind or "", f".{kind}" if kind else "")
+            if suffix:
+                target = item.with_name(item.name + suffix)
+                renames.append((relative, target.relative_to(path).as_posix()))
+        new_relative = target.relative_to(path).as_posix()
+        for entry in entries:
+            if entry.get("path") == relative and new_relative != relative:
+                entry["path"] = new_relative
+        if relative in listed:
+            continue
+        if source is not None:
+            host = re.sub(r"^https?://([^/]+).*$", r"\1", str(source.get("url") or ""))
+            entry = {"path": new_relative, "role": "captured source image", "provider": CAPTURED_PROVIDER,
+                     "sourceHost": host or None, "reuse": False, "replacementRequired": True,
+                     "note": "Captured from the source page as clone evidence; replace with a generated or licensed asset before publishing."}
+        else:
+            entry = {"path": new_relative, "role": alts.get(relative) or "content image", "provider": UNRECORDED_PROVIDER,
+                     "reuse": False, "provenanceReview": "required",
+                     "note": "Present in assets/ without a generation record; confirm provenance before reuse."}
+        entries.append(entry)
+        added.append(entry)
+    if write:
+        for old, new in renames:
+            (path / old).rename(path / new)
+        if renames:
+            for name in ("homepage.html", "image-inventory.json", "README.md"):
+                document = path / name
+                if not document.exists():
+                    continue
+                text = document.read_text(encoding="utf-8")
+                for old, new in renames:
+                    text = re.sub(re.escape(old) + r"(?![\w.])", new, text)
+                document.write_text(text, encoding="utf-8")
+        _write_json(manifest_path, manifest)
+    return {"renamed": renames, "added": added}
+
+
+# ---------------------------------------------------------------------------
+# T13b: measured design tokens
+
+
+def norm_hex(value: str) -> str:
+    value = value.strip().lstrip("#")
+    if len(value) == 3:
+        value = "".join(ch * 2 for ch in value)
+    return "#" + value.upper()
+
+
+def _rgb(value: str) -> tuple[int, int, int]:
+    value = norm_hex(value)
+    return int(value[1:3], 16), int(value[3:5], 16), int(value[5:7], 16)
+
+
+def luminance(value: str) -> float:
+    def channel(c: int) -> float:
+        c = c / 255
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+    r, g, b = _rgb(value)
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)
+
+
+def contrast(a: str, b: str) -> float:
+    high, low = sorted((luminance(a), luminance(b)), reverse=True)
+    return (high + 0.05) / (low + 0.05)
+
+
+def saturation(value: str) -> float:
+    r, g, b = (c / 255 for c in _rgb(value))
+    _, light, sat = colorsys.rgb_to_hls(r, g, b)
+    return sat if 0.06 < light < 0.94 else 0.0
+
+
+def chroma(value: str) -> int:
+    channels = _rgb(value)
+    return max(channels) - min(channels)
+
+
+def colour_distance(a: str, b: str) -> float:
+    return sum((x - y) ** 2 for x, y in zip(_rgb(a), _rgb(b))) ** 0.5
+
+
+def _darken_until(colour: str, against: str, target: float = 4.5) -> str:
+    r, g, b = (c / 255 for c in _rgb(colour))
+    hue, light, sat = colorsys.rgb_to_hls(r, g, b)
+    lighter = luminance(against) < 0.18
+    for _ in range(100):
+        candidate = "#%02X%02X%02X" % tuple(round(c * 255) for c in colorsys.hls_to_rgb(hue, light, sat))
+        if contrast(candidate, against) >= target:
+            return candidate
+        light = min(1.0, light + 0.01) if lighter else max(0.0, light - 0.01)
+    return "#FFFFFF" if lighter else "#000000"
+
+
+def _tailwind_config(markup: str) -> str:
+    match = re.search(r"tailwind\.config\s*=\s*(\{.*?\})\s*;?\s*</script>", markup, re.S)
+    return match.group(1) if match else ""
+
+
+def _config_colours(config: str) -> dict[str, str]:
+    block = re.search(r"colors\s*:\s*\{(.*?)\}\s*,?\s*(?:fontFamily|backgroundImage|spacing|extend|animation|keyframes|boxShadow|\}\s*\})", config, re.S)
+    colours = {}
+    text = block.group(1) if block else ""
+    parent = None
+    for match in re.finditer(r"['\"]?([\w-]+)['\"]?\s*:\s*(?:(\{)|['\"](#[0-9a-fA-F]{3,6})['\"])|(\})", text):
+        if match.group(4):
+            parent = None
+            continue
+        key, value = match.group(1), match.group(3)
+        if match.group(2):
+            parent = key
+            continue
+        name = key
+        if parent and key == "DEFAULT":
+            name = parent
+        elif parent:
+            name = f"{parent}-{key}"
+        colours[name] = norm_hex(value)
+    return colours
+
+
+def _config_fonts(config: str) -> dict[str, str]:
+    fonts = {}
+    block = re.search(r"fontFamily\s*:\s*\{(.*?)\}", config, re.S)
+    for match in re.finditer(r"['\"]?([\w-]+)['\"]?\s*:\s*\[\s*['\"]+([^'\"]+)", block.group(1) if block else ""):
+        fonts[match.group(1)] = match.group(2).strip()
+    return fonts
+
+
+def measure_design_tokens(markup: str) -> dict:
+    """Measure palette roles and fonts from a template's homepage CSS."""
+    config = _tailwind_config(markup)
+    config_colours = _config_colours(config)
+    named = {"white": "#FFFFFF", "black": "#000000", **TAILWIND_NEUTRALS, **config_colours}
+    usage: dict[str, dict[str, int]] = {"bg": {}, "text": {}, "border": {}, "any": {}}
+
+    def count(kind: str, colour: str, weight: int = 1) -> None:
+        colour = norm_hex(colour)
+        usage[kind][colour] = usage[kind].get(colour, 0) + weight
+        usage["any"][colour] = usage["any"].get(colour, 0) + weight
+
+    for classes in re.findall(r"\bclass=[\"']([^\"']*)[\"']", markup):
+        for token in classes.split():
+            base = token.split(":")[-1]
+            match = re.fullmatch(r"(bg|text|border|from|via|to|fill|stroke|ring|divide|decoration)-(?:\[(#[0-9a-fA-F]{3,6})\]|([a-z][\w-]*?))(?:/\d+)?", base)
+            if not match:
+                continue
+            colour = match.group(2) or named.get(match.group(3) or "")
+            if not colour:
+                continue
+            kind = {"bg": "bg", "from": "bg", "via": "bg", "to": "bg", "text": "text", "fill": "text", "decoration": "text"}.get(match.group(1), "border")
+            count(kind, colour)
+    styles = " ".join(re.findall(r"<style[^>]*>(.*?)</style>", markup, re.S | re.I)) + " " + " ".join(re.findall(r"\bstyle=[\"']([^\"']*)", markup))
+    for prop, colour in re.findall(r"(background(?:-color)?|color|border(?:-[a-z]+)?(?:-color)?)\s*:\s*[^;{}]*?(#[0-9a-fA-F]{3,6})\b", styles):
+        count("bg" if prop.startswith("background") else "text" if prop == "color" else "border", colour)
+    body_bg = body_text = None
+    for rule in re.findall(r"(?:^|[}\s,])body\s*\{([^}]*)\}", styles):
+        bg = re.search(r"background(?:-color)?\s*:\s*(#[0-9a-fA-F]{3,6})", rule)
+        fg = re.search(r"(?<![-\w])color\s*:\s*(#[0-9a-fA-F]{3,6})", rule)
+        body_bg = norm_hex(bg.group(1)) if bg else body_bg
+        body_text = norm_hex(fg.group(1)) if fg else body_text
+    body = re.search(r"<body\b[^>]*\bclass=[\"']([^\"']*)", markup, re.I)
+    for token in (body.group(1).split() if body else []):
+        match = re.fullmatch(r"(bg|text)-(?:\[(#[0-9a-fA-F]{3,6})\]|([a-z][\w-]*))", token)
+        if match:
+            colour = match.group(2) or named.get(match.group(3) or "")
+            if colour and match.group(1) == "bg":
+                body_bg = norm_hex(colour)
+            elif colour:
+                body_text = norm_hex(colour)
+
+    def ranked(kind: str) -> list[str]:
+        return [colour for colour, _ in sorted(usage[kind].items(), key=lambda item: (-item[1], item[0]))]
+
+    backgrounds = ranked("bg")
+    canvas = body_bg or next((c for c in backgrounds if luminance(c) > 0.6), None) or (backgrounds[0] if backgrounds else "#FFFFFF")
+    texts = ranked("text")
+    text = body_text or next((c for c in texts if contrast(c, canvas) >= 4.5), None) or ("#111111" if luminance(canvas) > 0.4 else "#FFFFFF")
+    # Brand accents are often muted (olive, sage, clay), so rank by chroma
+    # rather than HLS saturation, and prefer colours the template named.
+    tokens = set(config_colours.values())
+    accents = [c for c in ranked("any") if chroma(c) >= 14 and c not in {canvas, text} and 0.02 < luminance(c) < 0.85]
+    accent = next((c for c in accents if c in tokens), None) or (accents[0] if accents else text)
+    light_bgs = [c for c in backgrounds if c != canvas and abs(luminance(c) - luminance(canvas)) < 0.35]
+    panel = light_bgs[0] if light_bgs else canvas
+    soft = next((c for c in light_bgs[1:] if c != panel), panel)
+    darks = [c for c in backgrounds if luminance(c) < 0.2]
+    dark = darks[0] if darks else text
+    every = list(usage["any"]) or [text]
+    deep = min(every + [dark], key=luminance)
+    muted = next((c for c in texts if c not in {text, "#FFFFFF"} and contrast(c, canvas) >= 3), None)
+    border = (ranked("border") or [soft])[0]
+    roles = {
+        "canvas": canvas, "panel": panel, "soft": soft, "text": text, "accent": accent,
+        "accentText": accent if contrast(accent, canvas) >= 4.5 else _darken_until(accent, canvas),
+        "onAccent": max(("#FFFFFF", text), key=lambda c: contrast(c, accent)),
+        "dark": dark, "deep": deep,
+    }
+    fonts = _config_fonts(config)
+    families = []
+    for href in re.findall(r"<link\b(?![^>]*all-fonts-link)[^>]*href=[\"']([^\"']*fonts\.googleapis\.com/css2?[^\"']*)", markup, re.I):
+        for family in re.findall(r"family=([^:&;]+)", html_lib.unescape(href)):
+            families.append(family.replace("+", " "))
+    body_font = None
+    for rule in re.findall(r"(?:^|[}\s,])body\s*\{([^}]*)\}", styles):
+        match = re.search(r"font-family\s*:\s*['\"]?([^,'\";]+)", rule)
+        body_font = match.group(1).strip() if match and "var(" not in match.group(1) else body_font
+    display = fonts.get("serif") or fonts.get("display") or fonts.get("heading") or (families[0] if families else None) or body_font
+    sans = fonts.get("sans") or body_font or (families[-1] if families else None)
+    loaded = set(families)
+    missing_links = sorted({name for name in (display, sans) if name and name not in loaded and name.lower() not in {"serif", "sans-serif", "system-ui"}})
+    return {
+        "roles": roles,
+        "textSecondary": muted,
+        "border": border,
+        "fonts": {"display": display, "body": sans, "loadedFamilies": families, "missingFontLinks": missing_links},
+        "usedColours": sorted(set(usage["any"]) | set(named.values()) | {canvas, text}),
+        "measuredFrom": "homepage.html",
+    }
+
+
+def parse_design_palette(design: str) -> dict[str, str]:
+    section = re.search(r"^#{2,4}[^\n]*palette[^\n]*\n(.*?)(?=\n#{1,4}\s|\Z)", design, re.S | re.I | re.M)
+    # Fall back to the whole document for packages whose palette is a table
+    # under an "approved palette" paragraph rather than a palette heading.
+    body = section.group(1) if section else design
+    palette = {}
+    for label, colour in re.findall(r"^-\s*([^:\n]+):\s*`?(#[0-9a-fA-F]{3,6})`?", body, re.M):
+        palette[label.strip()] = norm_hex(colour)
+    for label, colour in re.findall(r"^\|\s*([^|\n]+?)\s*\|\s*`?(#[0-9a-fA-F]{3,6})`?", body, re.M):
+        palette.setdefault(label.strip(), norm_hex(colour))
+    return palette
+
+
+def audit_design_palette(path: Path, tolerance: float = 18.0) -> list[str]:
+    design_path, homepage = path / "DESIGN.md", path / "homepage.html"
+    if not design_path.exists() or not homepage.exists():
+        return []
+    declared = parse_design_palette(design_path.read_text(encoding="utf-8", errors="replace"))
+    if not declared:
+        return ["DESIGN.md has no reference palette to compare with homepage CSS"]
+    measured = measure_design_tokens(homepage.read_text(encoding="utf-8", errors="replace"))
+    used = measured["usedColours"]
+    errors = []
+    for label, colour in declared.items():
+        if "derived" in label.lower():
+            continue  # contrast-safe recommendations, not observed values
+        if not used or min(colour_distance(colour, other) for other in used) > tolerance:
+            errors.append(f"DESIGN.md palette {label} {colour} is not present in homepage CSS (run measure-design --write)")
+    for label, role in (("Background", "canvas"), ("Text primary", "text")):
+        if label in declared and colour_distance(declared[label], measured["roles"][role]) > tolerance:
+            errors.append(f"DESIGN.md {label} {declared[label]} does not match the measured {role} {measured['roles'][role]}")
+    return errors
+
+
+def palette_markdown(measured: dict, date: str) -> str:
+    roles = measured["roles"]
+    lines = [
+        "### Reference palette", "",
+        f"Measured from `homepage.html` CSS (Tailwind config, arbitrary utilities, inline and",
+        f"stylesheet declarations) by `maggie_marketplace.py measure-design` on {date}. Compare",
+        "with `screenshots/` before overriding; record any decision below.", "",
+        f"- Background: `{roles['canvas']}`",
+        f"- Surface: `{roles['panel']}`",
+        f"- Soft band: `{roles['soft']}`",
+        f"- Text primary: `{roles['text']}`",
+    ]
+    if measured.get("textSecondary"):
+        lines.append(f"- Text secondary: `{measured['textSecondary']}`")
+    lines += [
+        f"- Accent: `{roles['accent']}`",
+        f"- Accent text (derived, 4.5:1 on background): `{roles['accentText']}`",
+        f"- On accent (derived for contrast): `{roles['onAccent']}`",
+        f"- Dark band: `{roles['dark']}`",
+        f"- Deep: `{roles['deep']}`",
+        f"- Border: `{measured['border']}`",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def write_measured_design(path: Path, measured: dict) -> None:
+    design_path = path / "DESIGN.md"
+    design = design_path.read_text(encoding="utf-8")
+    block = palette_markdown(measured, datetime.now(timezone.utc).date().isoformat())
+    pattern = re.compile(r"#{2,4}\s*(?:Reference|Measured)?\s*palette\s*\n.*?(?=\n#{2,4}\s)", re.S | re.I)
+    design = pattern.sub(lambda _: block, design, count=1) if pattern.search(design) else design.rstrip() + "\n\n" + block
+    fonts = measured["fonts"]
+    if fonts.get("display"):
+        design = re.sub(r"^- Display:.*$", f"- Display: `{fonts['display']}` (measured); preserve measured weight, line-height, and tracking.", design, count=1, flags=re.M)
+    if fonts.get("body"):
+        design = re.sub(r"^- Body:.*$", f"- Body: `{fonts['body']}` (measured).", design, count=1, flags=re.M)
+    design_path.write_text(design, encoding="utf-8")
+
+
+def derived_style_tags(measured: dict) -> list[str]:
+    roles = measured["roles"]
+    tags = ["dark-canvas" if luminance(roles["canvas"]) < 0.2 else "light-canvas"]
+    display = (measured["fonts"].get("display") or "").lower()
+    tags.append("serif-display" if any(hint in display for hint in SERIF_HINTS) else "sans-display")
+    r, _, b = _rgb(roles["canvas"])
+    if tags[0] == "light-canvas":
+        tags.append("warm-neutral" if r > b + 4 else "cool-neutral" if b > r + 4 else "neutral")
+    return tags
+
+
+# ---------------------------------------------------------------------------
+# T13d: neutral display identity
+
+
+def _hue_word(colour: str) -> str:
+    r, g, b = (c / 255 for c in _rgb(colour))
+    hue, light, sat = colorsys.rgb_to_hls(r, g, b)
+    if chroma(colour) < 14 or light < 0.08:
+        return "Graphite" if light < 0.5 else "Linen"
+    degrees = hue * 360
+    return min(HUE_WORDS, key=lambda item: min(abs(item[0] - degrees), 360 - abs(item[0] - degrees)))[1]
+
+
+def source_brand_tokens(metadata: dict) -> set[str]:
+    title = str((metadata.get("sourceMetadata") or {}).get("title") or "")
+    head = re.split(r"\s[|—–:-]\s|\s\|\s|\|", title)[0]
+    tokens = {token.lower() for token in re.findall(r"[A-Za-z][A-Za-z'’-]{2,}", head)}
+    return {token for token in tokens if token not in GENERIC_NAME_WORDS}
+
+
+def generate_display_identity(metadata: dict, measured: dict, taken: set[str]) -> dict:
+    roles = measured["roles"]
+    display = (measured["fonts"].get("display") or "").lower()
+    style = "Editorial" if any(hint in display for hint in SERIF_HINTS) else "Modern"
+    tone = "Noir" if luminance(roles["canvas"]) < 0.2 else "Linen" if _rgb(roles["canvas"])[0] > _rgb(roles["canvas"])[2] + 4 else "Mist"
+    industry = [str(item) for item in metadata.get("industry") or []]
+    noun = "Clinic" if "medical-spa" in industry and "spa" not in industry[:1] else "Spa" if "spa" in industry else "Wellness" if "wellness" in industry else "Studio"
+    hue = _hue_word(roles["accent"])
+    brand = source_brand_tokens(metadata)
+    candidates = [f"{hue} {style} {noun}", f"{tone} {hue} {noun}", f"{hue} {tone} {style}", f"{tone} {style} {noun}"]
+    candidates += [f"{lead} {style} {place}" for lead in (hue, tone) for place in ("Atelier", "House", "Rooms", "Retreat", "Haven", "Parlour")]
+    candidates += [f"{lead} {style} {noun} {numeral}" for lead in (hue, tone) for numeral in ("II", "III", "IV", "V", "VI", "VII", "VIII", "IX")]
+    name = next((item for item in candidates if item.lower() not in taken and not (set(item.lower().split()) & brand)), None)
+    if name is None:
+        raise ValueError("could not derive a unique neutral displayName; pass --display-name")
+    font = measured["fonts"].get("display") or "system"
+    canvas_word = "dark" if tone == "Noir" else "light"
+    description = f"A {canvas_word} {noun.lower()} homepage with {font} headings and {hue.lower()} accents."
+    return {"displayName": name, "displayDescription": description}
+
+
+def audit_display_identity(path: Path, catalog: list[dict] | None = None) -> list[str]:
+    metadata_path = path / "template.json"
+    if not metadata_path.exists():
+        return []
+    metadata = _read_json(metadata_path)
+    name = str(metadata.get("displayName") or "").strip()
+    errors = []
+    if not name:
+        errors.append("template.json needs a neutral displayName for customer-facing pickers")
+    if not str(metadata.get("displayDescription") or "").strip():
+        errors.append("template.json needs a short displayDescription")
+    if name:
+        if re.search(r"\b\d{2,}\b", name) or name == metadata.get("name"):
+            errors.append(f"displayName must be a style name, not a generic counter: {name}")
+        leaked = sorted(set(re.findall(r"[a-z][a-z'’-]{2,}", (name + " " + str(metadata.get("displayDescription") or "")).lower())) & source_brand_tokens(metadata))
+        if leaked:
+            errors.append(f"displayName/displayDescription repeats the source brand: {', '.join(leaked)}")
+        for entry in catalog or []:
+            if entry.get("id") != metadata.get("id") and str(entry.get("displayName") or "").strip().lower() == name.lower():
+                errors.append(f"displayName is not unique in the catalog: {name} (also {entry.get('id')})")
+    return errors
+
+
+# ---------------------------------------------------------------------------
+# T14: template content contract and studio preview
+
+
+CONTENT_SECTIONS = ("brand", "contact", "hero", "categories", "about", "gallery", "reviews", "hours", "faqs")
+CONTENT_FIELD_HELP = {
+    "brand.name": "Business name (MaggieDash Settings → Business profile)",
+    "brand.tagline": "Short tagline (Business profile)",
+    "brand.logo": "Logo image (Business profile → Logo)",
+    "contact.phone": "Phone number (Business profile → Contact)",
+    "contact.email": "Public email (Business profile → Contact)",
+    "contact.address": "Street address (Business profile → Location)",
+    "hero.headline": "Homepage headline (Content → Homepage → Hero)",
+    "hero.subheadline": "Supporting line under the headline (Content → Homepage → Hero)",
+    "hero.image": "Hero image (Content → Homepage → Hero)",
+    "hero.cta": "Primary call-to-action label and link (Content → Homepage → Hero)",
+    "categories": "Treatment categories and services (Booking → Catalogue)",
+    "about": "About section (Content → Homepage → About)",
+    "gallery": "Gallery images (Media)",
+    "reviews": "Customer reviews (Content → Reviews; never invent reviews)",
+    "hours": "Opening hours (Booking → Settings → Opening hours)",
+    "faqs": "Frequently asked questions (Content → FAQs)",
+}
+
+
+def _content_path_exists(content: dict, dotted: str) -> bool:
+    node: object = content
+    for part in dotted.split("."):
+        if isinstance(node, list) and part.isdigit() and int(part) < len(node):
+            node = node[int(part)]
+        elif isinstance(node, dict) and part in node:
+            node = node[part]
+        else:
+            return False
+    return True
+
+
+def validate_content(content: dict) -> list[str]:
+    errors = []
+    if content.get("schemaVersion") != CONTENT_SCHEMA_VERSION:
+        errors.append(f"schemaVersion must be {CONTENT_SCHEMA_VERSION}")
+    for section in CONTENT_SECTIONS:
+        if section not in content:
+            errors.append(f"missing section: {section}")
+    brand = content.get("brand") if isinstance(content.get("brand"), dict) else {}
+    if not str(brand.get("name") or "").strip():
+        errors.append("brand.name is required")
+    contact = content.get("contact") if isinstance(content.get("contact"), dict) else {}
+    if contact.get("email") and not re.fullmatch(r"[^@\s]+@[^@\s]+\.[^@\s]+", str(contact["email"])):
+        errors.append("contact.email is invalid")
+    hero = content.get("hero") if isinstance(content.get("hero"), dict) else {}
+    if not str(hero.get("headline") or "").strip():
+        errors.append("hero.headline is required")
+    categories = content.get("categories")
+    if not isinstance(categories, list):
+        errors.append("categories must be an array")
+        categories = []
+    for index, category in enumerate(categories):
+        if not isinstance(category, dict) or not str(category.get("name") or "").strip():
+            errors.append(f"categories.{index}.name is required")
+            continue
+        services = category.get("services")
+        if not isinstance(services, list):
+            errors.append(f"categories.{index}.services must be an array")
+            continue
+        for position, service in enumerate(services):
+            label = f"categories.{index}.services.{position}"
+            if not isinstance(service, dict) or not str(service.get("name") or "").strip():
+                errors.append(f"{label}.name is required")
+                continue
+            price = service.get("price")
+            if price is not None and (not isinstance(price, (int, float)) or price < 0):
+                errors.append(f"{label}.price must be a non-negative number or null")
+            duration = service.get("durationMinutes")
+            if duration is not None and (not isinstance(duration, int) or duration <= 0):
+                errors.append(f"{label}.durationMinutes must be a positive integer or null")
+    for key in ("gallery", "reviews", "faqs"):
+        if key in content and not isinstance(content[key], list):
+            errors.append(f"{key} must be an array")
+    for position, review in enumerate(content.get("reviews") or []):
+        if isinstance(review, dict) and review.get("sample") is not True and not review.get("source"):
+            errors.append(f"reviews.{position} needs a source, or sample=true for demo copy")
+    hours = content.get("hours")
+    if hours is not None and not isinstance(hours, list):
+        errors.append("hours must be an array of {day, opens, closes} or {day, closed}")
+    for position, item in enumerate(hours or []):
+        if not isinstance(item, dict) or item.get("day") not in {"mon", "tue", "wed", "thu", "fri", "sat", "sun"}:
+            errors.append(f"hours.{position}.day must be mon..sun")
+        elif not item.get("closed") and not (re.fullmatch(r"\d{2}:\d{2}", str(item.get("opens") or "")) and re.fullmatch(r"\d{2}:\d{2}", str(item.get("closes") or ""))):
+            errors.append(f"hours.{position} needs opens/closes as HH:MM or closed=true")
+    samples = content.get("samples", [])
+    if not isinstance(samples, list):
+        errors.append("samples must be an array of content paths")
+        samples = []
+    for dotted in samples:
+        if not isinstance(dotted, str) or not _content_path_exists(content, dotted):
+            errors.append(f"samples entry does not resolve to content: {dotted}")
+    palette = content.get("palette")
+    if palette is not None:
+        roles = palette.get("roles") if isinstance(palette, dict) else None
+        if not isinstance(roles, dict) or any(not re.fullmatch(r"#[0-9A-Fa-f]{6}", str(roles.get(role) or "")) for role in PALETTE_ROLES):
+            errors.append("palette.roles must define every maggie-palette-roles-v1 role as #RRGGBB")
+    return errors
+
+
+def palette_css_variables(roles: dict) -> str:
+    def kebab(name: str) -> str:
+        return re.sub(r"([A-Z])", lambda match: "-" + match.group(1).lower(), name)
+
+    return ":root {\n" + "".join(f"  --maggie-{kebab(role)}: {roles[role]};\n" for role in PALETTE_ROLES if role in roles) + "}\n"
+
+
+def load_palettes(path: Path | None, measured: dict, template_id: str) -> dict:
+    if path is not None:
+        palettes = _read_json(path)
+        if palettes.get("schemaVersion") != "maggie-palette-roles-v1":
+            raise ValueError("palette file must use schemaVersion maggie-palette-roles-v1")
+        return palettes
+    return {"schemaVersion": "maggie-palette-roles-v1", "template": template_id,
+            "signature": {"id": "signature", "name": "Signature (measured)", "roles": measured["roles"]}, "variants": []}
+
+
+STUDIO_SCRIPT = r"""
+const DATA = JSON.parse(document.getElementById('maggie-studio-data').textContent);
+const select = document.getElementById('palette');
+const labels = document.getElementById('labels');
+const report = {};
+const palettes = [DATA.palettes.signature, ...(DATA.palettes.variants || [])];
+palettes.forEach((palette, index) => { const option = document.createElement('option'); option.value = index; option.textContent = palette.name || palette.id; select.append(option); });
+select.value = String(Math.max(0, palettes.findIndex((palette) => '#' + palette.id === location.hash)));
+select.addEventListener('change', () => history.replaceState(null, '', '#' + palettes[select.value].id));
+const sourcePromise = fetch(DATA.homepage).then((response) => { if (!response.ok) throw new Error('homepage ' + response.status); return response.text(); });
+function kebab(value) { return value.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase()); }
+function themed(source, palette) {
+  let output = source;
+  const signature = DATA.palettes.signature.roles;
+  for (const [role, colour] of Object.entries(signature)) {
+    const target = palette.roles[role];
+    if (target && colour && target.toLowerCase() !== colour.toLowerCase()) output = output.replace(new RegExp(colour.replace('#', '#?'), 'gi'), target);
+  }
+  const vars = ':root{' + Object.entries(palette.roles).map(([role, colour]) => `--maggie-${kebab(role)}:${colour};`).join('') + '}';
+  const head = `<base href="${DATA.base}"><style id="maggie-studio-palette">${vars}</style><style>[data-maggie-sample-label]{outline:2px dashed #d97706!important;outline-offset:2px;position:relative}.maggie-sample-badge{position:absolute;z-index:2147483647;font:600 11px/1.3 system-ui,sans-serif;background:#d97706;color:#fff;padding:2px 6px;border-radius:4px;text-decoration:none;pointer-events:auto}</style>`;
+  return output.replace(/<head([^>]*)>/i, (match) => match + head);
+}
+function guessSamples(doc) {
+  const found = [...doc.querySelectorAll('[data-maggie-sample]')].map((el) => [el, el.dataset.maggieSample]);
+  if (found.length) return found;
+  const guesses = [];
+  const h1 = doc.querySelector('h1'); if (h1) { guesses.push([h1, 'hero.headline']); const p = h1.parentElement && h1.parentElement.querySelector('p'); if (p) guesses.push([p, 'hero.subheadline']); }
+  doc.querySelectorAll('a[href^="tel:"]').forEach((el) => guesses.push([el, 'contact.phone']));
+  doc.querySelectorAll('a[href^="mailto:"]').forEach((el) => guesses.push([el, 'contact.email']));
+  doc.querySelectorAll('address').forEach((el) => guesses.push([el, 'contact.address']));
+  doc.querySelectorAll('section, footer').forEach((section) => {
+    const text = (section.querySelector('h2,h3') || {}).textContent || '';
+    if (/faq|question/i.test(text)) guesses.push([section, 'faqs']);
+    else if (/review|testimonial|clients say/i.test(text)) guesses.push([section, 'reviews']);
+    else if (/hours|opening/i.test(text)) guesses.push([section, 'hours']);
+    else if (/treatment|service|menu|price/i.test(text)) guesses.push([section, 'categories']);
+    else if (/about|story|philosophy/i.test(text)) guesses.push([section, 'about']);
+    else if (/gallery|space|journal/i.test(text)) guesses.push([section, 'gallery']);
+  });
+  return guesses;
+}
+function label(doc, show) {
+  doc.querySelectorAll('.maggie-sample-badge').forEach((el) => el.remove());
+  doc.querySelectorAll('[data-maggie-sample-label]').forEach((el) => el.removeAttribute('data-maggie-sample-label'));
+  if (!show) return [];
+  const seen = [];
+  for (const [element, field] of guessSamples(doc)) {
+    element.setAttribute('data-maggie-sample-label', field);
+    const badge = doc.createElement('a');
+    badge.className = 'maggie-sample-badge'; badge.textContent = 'Sample · ' + field; badge.target = '_top';
+    badge.href = DATA.fieldsPage + '#' + field.split('.')[0] + (field.includes('.') ? '-' + field.split('.')[1] : '');
+    element.prepend(badge); seen.push(field);
+  }
+  return seen;
+}
+function measure(frame, width) {
+  const doc = frame.contentDocument; if (!doc) return;
+  const root = doc.documentElement; const overflow = Math.max(0, root.scrollWidth - root.clientWidth);
+  const offenders = overflow ? [...doc.body.querySelectorAll('*')].filter((el) => el.getBoundingClientRect().right > root.clientWidth + 1).slice(0, 5).map((el) => el.tagName.toLowerCase() + (el.className && typeof el.className === 'string' ? '.' + el.className.trim().split(/\s+/).slice(0, 3).join('.') : '')) : [];
+  report[width] = { overflowPx: overflow, offenders, samples: label(doc, labels.checked) };
+  document.getElementById('badge-' + width).textContent = overflow ? `overflow ${overflow}px` : 'no overflow';
+  document.getElementById('badge-' + width).className = overflow ? 'badge bad' : 'badge ok';
+  document.getElementById('maggie-studio-report').textContent = JSON.stringify({ palette: palettes[select.value].id, viewports: report });
+}
+async function render() {
+  const palette = palettes[select.value];
+  let source;
+  try { source = await sourcePromise; } catch (error) { document.getElementById('maggie-studio-report').textContent = JSON.stringify({ error: String(error) }); return; }
+  for (const width of DATA.viewports) {
+    const frame = document.getElementById('frame-' + width);
+    frame.onload = () => setTimeout(() => measure(frame, width), DATA.settleMs);
+    frame.srcdoc = themed(source, palette);
+  }
+}
+select.addEventListener('change', render);
+labels.addEventListener('change', () => DATA.viewports.forEach((width) => { const frame = document.getElementById('frame-' + width); if (frame.contentDocument) measure(frame, width); }));
+function fit() { DATA.viewports.forEach((width) => { const cell = document.getElementById('cell-' + width); const scale = Math.min(1, (cell.clientWidth - 2) / width); const frame = document.getElementById('frame-' + width); frame.style.transform = `scale(${scale})`; cell.style.height = (DATA.height * scale + 2) + 'px'; }); }
+window.addEventListener('resize', fit); fit(); render();
+"""
+
+
+def build_studio(path: Path, output: Path, palettes: dict, height: int = 900, settle_ms: int = 1500) -> dict:
+    """Write a static studio page: template × palette × viewport with sample labels."""
+    output.mkdir(parents=True, exist_ok=True)
+    homepage = (path / "homepage.html").resolve()
+    rel_home = Path(_relative(homepage, output.resolve()))
+    base = rel_home.parent.as_posix().rstrip("/") + "/"
+    metadata = _read_json(path / "template.json") if (path / "template.json").exists() else {}
+    title = metadata.get("displayName") or metadata.get("id") or path.name
+    data = {"homepage": rel_home.as_posix(), "base": base, "viewports": list(STUDIO_VIEWPORTS), "height": height,
+            "settleMs": settle_ms, "palettes": palettes, "fieldsPage": "content-fields.html"}
+    cells = "".join(
+        f'<figure><figcaption>{width}px <span class="badge" id="badge-{width}">measuring…</span></figcaption>'
+        f'<div class="cell" id="cell-{width}"><iframe id="frame-{width}" title="{width}px preview" width="{width}" height="{height}" '
+        f'style="width:{width}px;height:{height}px"></iframe></div></figure>'
+        for width in STUDIO_VIEWPORTS
+    )
+    payload = json.dumps(data).replace("</", "<\\/")
+    page = f"""<!doctype html>
+<html lang="en-GB"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>{html_lib.escape(str(title))} studio</title>
+<style>
+body{{margin:0;font:14px/1.5 system-ui,sans-serif;background:#f4f4f2;color:#1c1c1a}}
+header{{display:flex;flex-wrap:wrap;gap:16px;align-items:center;padding:12px 16px;background:#fff;border-bottom:1px solid #ddd;position:sticky;top:0;z-index:1}}
+main{{display:grid;grid-template-columns:repeat(auto-fit,minmax(320px,1fr));gap:16px;padding:16px}}
+figure{{margin:0}} figcaption{{display:flex;justify-content:space-between;margin-bottom:6px;font-weight:600}}
+.cell{{overflow:hidden;border:1px solid #ccc;background:#fff}} iframe{{border:0;transform-origin:0 0;display:block}}
+.badge{{font-weight:500;padding:0 6px;border-radius:4px}} .ok{{background:#dcfce7;color:#166534}} .bad{{background:#fee2e2;color:#991b1b}}
+#maggie-studio-report{{margin:0 16px 16px;white-space:pre-wrap;font-size:12px;color:#555}}
+</style></head><body>
+<header><strong>{html_lib.escape(str(title))}</strong>
+<label>Palette <select id="palette"></select></label>
+<label><input type="checkbox" id="labels" checked> Show sample labels</label>
+<a href="content-fields.html">Where owners replace sample content</a></header>
+<main>{cells}</main>
+<pre id="maggie-studio-report">{{}}</pre>
+<script type="application/json" id="maggie-studio-data">{payload}</script>
+<script>{STUDIO_SCRIPT}</script>
+</body></html>
+"""
+    (output / "index.html").write_text(page, encoding="utf-8")
+    rows = "".join(
+        f'<tr id="{field.replace(".", "-")}"><td><code>{field}</code></td><td>{html_lib.escape(text)}</td></tr>'
+        for field, text in CONTENT_FIELD_HELP.items()
+    )
+    (output / "content-fields.html").write_text(
+        "<!doctype html><html lang=\"en-GB\"><head><meta charset=\"utf-8\"><title>Sample content fields</title>"
+        "<style>body{font:14px/1.5 system-ui,sans-serif;margin:24px;max-width:860px}td{padding:6px 10px;border-bottom:1px solid #ddd;vertical-align:top}tr:target{background:#fef3c7}</style></head><body>"
+        f"<h1>Sample content fields</h1><p>Each labelled sample in the studio maps to a <code>{CONTENT_SCHEMA_VERSION}</code> field. "
+        "Owners replace it in the location listed; the template renders the content contract instead of hand-edited copy.</p>"
+        f"<table>{rows}</table></body></html>\n",
+        encoding="utf-8",
+    )
+    _write_json(output / "palettes.json", palettes)
+    return {"studio": str(output / "index.html"), "viewports": list(STUDIO_VIEWPORTS), "palettes": 1 + len(palettes.get("variants") or [])}
+
+
+def _relative(target: Path, start: Path) -> str:
+    import os
+
+    return os.path.relpath(target, start)
+
+
+def parse_studio_report(dom: str) -> dict:
+    match = re.search(r'<pre id="maggie-studio-report">(.*?)</pre>', dom, re.S)
+    if not match:
+        raise ValueError("studio report was not rendered")
+    return json.loads(html_lib.unescape(match.group(1)) or "{}")
+
+
+def check_studio_overflow(serve_root: Path, studio_index: Path, budget_ms: int = 12000, palette_id: str | None = None) -> dict:
+    """Render the studio in headless Chrome and return the per-viewport overflow report."""
+    chrome = shutil.which("google-chrome") or shutil.which("chromium") or shutil.which("chromium-browser")
+    if not chrome:
+        raise RuntimeError("google-chrome or chromium is required for --check-overflow")
+    handler = partial(_QuietHandler, directory=str(serve_root))
+    server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        url = f"http://127.0.0.1:{server.server_port}/{studio_index.resolve().relative_to(serve_root.resolve()).as_posix()}"
+        if palette_id:
+            url += "#" + palette_id
+        proc = subprocess.run([chrome, "--headless=new", "--no-sandbox", "--disable-gpu", "--hide-scrollbars",
+                               "--window-size=1600,1200", f"--virtual-time-budget={budget_ms}", "--dump-dom", url],
+                              capture_output=True, text=True, timeout=120)
+        if proc.returncode != 0:
+            raise RuntimeError(f"headless chrome failed: {(proc.stderr or '')[-300:]}")
+        return parse_studio_report(proc.stdout)
+    finally:
+        server.shutdown()
+        server.server_close()
+
+
+class _QuietHandler(SimpleHTTPRequestHandler):
+    def log_message(self, *_args) -> None:  # noqa: D401 - silence request logging
+        return
+
+
+# ---------------------------------------------------------------------------
+# T15: image generation cost report and no-text review gate
+
+
+def _generated_assets(path: Path) -> list[dict]:
+    manifest = path / "generated-asset-manifest.json"
+    if not manifest.exists():
+        return []
+    inherited = manifest_provider(manifest)
+    return [item for item in _read_json(manifest).get("assets", [])
+            if isinstance(item, dict) and item.get("path") and (item.get("provider") or inherited) not in NON_GENERATED_PROVIDERS
+            and (path / item["path"]).is_file()]
+
+
+def plan_image_generation(path: Path, unit_cost: float | None, currency: str, provider: str) -> dict:
+    planned = 0
+    inventory = path / "image-inventory.json"
+    if inventory.exists():
+        planned += sum(1 for item in _read_json(inventory).get("occurrences", []) if item.get("status") == "needs-generation")
+    manifest = path / "generated-asset-manifest.json"
+    if manifest.exists():
+        planned += sum(1 for item in _read_json(manifest).get("assets", []) if item.get("provider") in {"pending", "", None})
+        planned += sum(1 for item in _read_json(manifest).get("assets", []) if item.get("provider") == CAPTURED_PROVIDER)
+    report_path = path / "image-generation-report.json"
+    report = _read_json(report_path) if report_path.exists() else {"schemaVersion": REPORT_SCHEMA_VERSION}
+    report["before"] = {
+        "createdAt": now(), "provider": provider, "plannedImages": planned, "unitCost": unit_cost, "currency": currency,
+        "estimatedCost": round(planned * unit_cost, 4) if unit_cost is not None else None,
+        "note": None if unit_cost is not None else "unit cost not supplied; pass --unit-cost from the provider's current price list",
+    }
+    report["generatedBefore"] = sorted(item["path"] for item in _generated_assets(path))
+    _write_json(report_path, report)
+    return report
+
+
+def _ocr_words(image: Path) -> list[str] | None:
+    tesseract = shutil.which("tesseract")
+    if not tesseract or image.suffix.lower() == ".svg":
+        return None
+    proc = subprocess.run([tesseract, str(image), "stdout", "--psm", "11"], capture_output=True, text=True, timeout=120)
+    if proc.returncode != 0:
+        return None
+    return [word for word in re.findall(r"[A-Za-z]{3,}", proc.stdout)]
+
+
+def review_generated_images(path: Path, approve: bool = False, reviewer: str = "", flags: list[str] | None = None, note: str = "") -> dict:
+    report_path = path / "image-generation-report.json"
+    report = _read_json(report_path) if report_path.exists() else {"schemaVersion": REPORT_SCHEMA_VERSION}
+    assets = _generated_assets(path)
+    before = set(report.get("generatedBefore") or [])
+    new_images = [item for item in assets if item["path"] not in before] if "generatedBefore" in report else assets
+    plan = report.get("before") or {}
+    unit_cost = plan.get("unitCost")
+    report["after"] = {
+        "reviewedAt": now(), "generatedImages": len(new_images), "totalGeneratedAssets": len(assets),
+        "unitCost": unit_cost, "currency": plan.get("currency", "USD"),
+        "estimatedCost": round(len(new_images) * unit_cost, 4) if isinstance(unit_cost, (int, float)) else None,
+        "plannedImages": plan.get("plannedImages"),
+    }
+    review_dir = path / "image-review"
+    review_dir.mkdir(parents=True, exist_ok=True)
+    tiles = "".join(
+        f'<figure><img src="../{html_lib.escape(item["path"])}" alt=""><figcaption>{html_lib.escape(item["path"])}<br>{html_lib.escape(str(item.get("role", "")))}</figcaption></figure>'
+        for item in assets
+    )
+    (review_dir / "contact-sheet.html").write_text(
+        "<!doctype html><html lang=\"en-GB\"><head><meta charset=\"utf-8\"><title>Generated image contact sheet</title>"
+        "<style>body{font:13px system-ui,sans-serif;margin:16px}main{display:grid;grid-template-columns:repeat(auto-fill,minmax(260px,1fr));gap:12px}"
+        "img{width:100%;height:260px;object-fit:contain;background:#eee}figure{margin:0}</style></head><body>"
+        "<h1>Check every image for readable text, labels, logos, and watermarks</h1>"
+        f"<main>{tiles}</main></body></html>\n",
+        encoding="utf-8",
+    )
+    flagged = set(flags or [])
+    items, method = [], "ocr" if shutil.which("tesseract") else "human"
+    for item in assets:
+        words = _ocr_words(path / item["path"]) if method == "ocr" else None
+        status = "flagged" if item["path"] in flagged or words else "passed" if (words == [] or approve) else "pending"
+        items.append({"path": item["path"], "role": item.get("role"), "status": status,
+                      **({"ocrWords": words[:12]} if words else {})})
+    if any(item["status"] == "flagged" for item in items):
+        status = "flagged"
+    elif all(item["status"] == "passed" for item in items) and (method == "ocr" or approve):
+        status = "passed"
+    else:
+        status = "pending-human-review"
+    if approve and not reviewer:
+        raise ValueError("--approve requires --reviewer")
+    report["textReview"] = {
+        "status": status, "method": "ocr+human" if method == "ocr" and approve else method,
+        "reviewer": reviewer or None, "note": note or None, "contactSheet": "image-review/contact-sheet.html",
+        "reviewedAt": now(), "items": items,
+    }
+    _write_json(report_path, report)
+    return report
+
+
+def audit_image_review(path: Path) -> list[str]:
+    assets = _generated_assets(path)
+    if not assets:
+        return []
+    report_path = path / "image-generation-report.json"
+    if not report_path.exists():
+        return ["generated images need a no-text review: run image-review (contact sheet/OCR) and record the result"]
+    report = _read_json(report_path)
+    review = report.get("textReview") or {}
+    if not review:
+        return ["generated images need a no-text review: run image-review (contact sheet/OCR) and record the result"]
+    if review.get("status") != "passed":
+        return [f"generated image text review is {review.get('status', 'missing')}; resolve flagged or pending images before completion"]
+    reviewed = {item.get("path") for item in review.get("items", []) if item.get("status") == "passed"}
+    missing = sorted(item["path"] for item in assets if item["path"] not in reviewed)
+    return [f"generated image was not covered by the text review: {name}" for name in missing]
+
+
+def package_audit(path: Path, catalog: list[dict] | None = None) -> dict:
+    metadata = _read_json(path / "template.json") if (path / "template.json").exists() else {}
+    published = metadata.get("status") in {"published", "ready"}
+    groups = {
+        "screenshots": audit_screenshots(path),
+        "designPalette": audit_design_palette(path),
+        "assetProvenance": audit_asset_provenance(path, published=published),
+        "displayIdentity": audit_display_identity(path, catalog),
+        "imageReview": audit_image_review(path),
+    }
+    return {"template": metadata.get("id") or path.name, "passed": not any(groups.values()), "checks": groups}