#!/usr/bin/env python3"""Build Higgsfield-style covers from one full-bleed SCENE image (no text on it).
The image model renders ONLY the scene. ALL typography is drawn here as ONEstructured lockup block, matching the official covers:
        Higgsfield                 <- wordmark (small)        DREAMCUT                   <- title (huge caps)        ( Available now at … )     <- CTA pill(NO tagline by default — the reference lockup has none; --tagline existsonly for an explicit user request.)
Break-out: pass --cutout (subject with alpha from remove_background, samesize as the scene) and on the framed OG variants the subject pops OUT of thestadium capsule onto the frame color instead of being clipped by the window.Text is ALWAYS the last (topmost) layer — the subject never covers a letter.
The stadium capsule, frame and corner dots are code too. Outputs:  --out-cover   full-bleed scene + lockup (marketplace cover)  --out-og      frame + capsule + dots + lockup, same ratio as the art (3:2)  --out-og-wide the 1.91:1 social-card variant
ONE typeface: Inter (the title face on the reference cover) rendersEVERYTHING — wordmark, title, CTA. No other font ships in the bundle.
All type is FLAT white. No shadows, no outlines, no gradients — ever.On framed outputs the whole lockup is clamped INSIDE the stadium capsule(rounded ends included) — text never touches the frame.
Only Pillow required.
ASSETS: the font + logo glyph are NOT bundled — they are fetched once from thehosted asset base and cached locally (~/.cache/higgsfield-cover, override with$COVER_ASSET_CACHE). Point at a different host with $COVER_ASSET_BASE."""import argparseimport colorsysimport osimport sysimport urllib.request
from PIL import Image, ImageDraw, ImageFilter, ImageFont
ALLOWED_FRAMES = {    "sky-blue": "#A9CFF4",    "peach": "#F7DDB9",    "olive": "#7A7D3C",    "warm-gray": "#D6D3CE",    "dusty-rose": "#E7B7B0",    "deep-navy": "#243A5E",    "signal-red": "#D23B2E",    "cream": "#F1EEE6",}DEFAULT_FRAME = ALLOWED_FRAMES["sky-blue"]CTA_DEFAULT = "Available now at higgsfield.ai"# ONE font. Inter Bold — the title face on the reference cover.BRAND_FONT = "Inter-Variable.ttf"
# Hosted asset base (font + logo). Override with $COVER_ASSET_BASE. The two# assets live at <base>/fonts/Inter-Variable.ttf and <base>/logo/hf-glyph.png.ASSET_BASE = os.environ.get(    "COVER_ASSET_BASE",    "https://static.higgsfield.ai/website-builder/app-cover-generator",).rstrip("/")

def cache_dir():    d = os.environ.get(        "COVER_ASSET_CACHE",        os.path.join(os.path.expanduser("~"), ".cache", "higgsfield-cover"),    )    os.makedirs(d, exist_ok=True)    return d

def ensure_asset(rel_path):    """Return a local path to a hosted asset, downloading + caching on first use.    rel_path is relative to ASSET_BASE, e.g. 'fonts/Inter-Variable.ttf'."""    local = os.path.join(cache_dir(), os.path.basename(rel_path))    if os.path.exists(local) and os.path.getsize(local) > 0:        return local    url = f"{ASSET_BASE}/{rel_path}"    try:        # A browser-ish User-Agent — some CDNs/WAFs 403 the default urllib UA.        req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})        with urllib.request.urlopen(req, timeout=30) as r:  # noqa: S310 (trusted host)            data = r.read()        with open(local, "wb") as f:            f.write(data)        return local    except Exception as e:  # pragma: no cover - network/host failure        print(f"WARNING: could not fetch asset {url}: {e}", file=sys.stderr)        return None

def hex_rgb(s):    c = s.lstrip("#")    if len(c) != 6:        sys.exit(f"bad hex color: {s}")    return tuple(int(c[i:i + 2], 16) for i in (0, 2, 4))

def check_frame_color(rgb, force):    h, s, v = colorsys.rgb_to_hsv(*(c / 255 for c in rgb))    if 40 / 360 <= h <= 160 / 360 and s > 0.55 and v > 0.55:        msg = ("frame color %02X%02X%02X is in the BANNED acid lime/yellow band. "               "Allowed: %s" %               (*rgb, ", ".join(f"{k} {v}" for k, v in ALLOWED_FRAMES.items())))        if force:            print("WARNING:", msg)        else:            sys.exit("ERROR: " + msg)

def luminance(rgb):    r, g, b = (c / 255 for c in rgb)    return 0.2126 * r + 0.7152 * g + 0.0722 * b

def brand_font(px, weight):    """Inter at the given weight (opsz pinned for display). The ONLY typeface."""    path = ensure_asset(f"fonts/{BRAND_FONT}")    if path is None:        return ImageFont.load_default(px)    try:        f = ImageFont.truetype(path, px)        try:            f.set_variation_by_axes([32, weight])        except Exception:            pass        return f    except Exception:        return ImageFont.load_default(px)

def measure(d, text, font):    x0, y0, x1, y1 = d.textbbox((0, 0), text, font=font)    return x1 - x0, y1 - y0, x0, y0

class Lockup:    """One structured type block: wordmark / title lines / tagline / CTA pill."""
    def __init__(self, a, W, H):        self.a = a        probe = ImageDraw.Draw(Image.new("RGB", (8, 8)))        lines = [ln.strip() for part in a.title.split("\\n")                 for ln in part.split("\n") if ln.strip()]        if a.title_caps == "upper":            lines = [ln.upper() for ln in lines]        self.title_lines = lines
        # Size the title so its longest line fills the width budget…        budget = W * a.title_width        px = round(H * 0.5)        f = brand_font(px, 700)        w = max(measure(probe, ln, f)[0] for ln in self.title_lines)        px = max(24, round(px * budget / max(1, w)))        # …capped by line height and by total available width at the anchor.        px = min(px, round(H * a.title_max_h))        avail = W * (0.94 - a.block_x) if a.anchor == "left" else W * 0.88        f = brand_font(px, 700)        w = max(measure(probe, ln, f)[0] for ln in self.title_lines)        if w > avail:            px = round(px * avail / w)        self.title_px = px        self.f_title = brand_font(px, 700)
        glyph_path = ensure_asset("logo/hf-glyph.png")        self.glyph = (Image.open(glyph_path).convert("RGBA")                      if glyph_path and os.path.exists(glyph_path) else None)        self.f_word = brand_font(max(16, round(px * 0.26)), 650)        self.f_tag = brand_font(max(14, round(px * 0.20)), 500)        self.f_cta = brand_font(max(13, round(px * 0.17)), 500)        self.cta_pad_y = round(px * 0.14)        self.cta_pad_x = round(px * 0.30)
        def rows_for(names):            rows = []            if "word" in names and a.wordmark:                rows.append(("word", a.wordmark, self.f_word, 0))            if "title" in names:                for i, ln in enumerate(self.title_lines):                    gap = round(px * (0.30 if (i == 0 and a.wordmark) else 0.10 if i else 0))                    rows.append(("title", ln, self.f_title, gap))            if "tag" in names and a.tagline:                rows.append(("tag", a.tagline, self.f_tag, round(px * 0.26)))            if "cta" in names and a.cta:                rows.append(("cta", a.cta, self.f_cta, round(px * 0.30)))            out = []            for kind, text, font, gap in rows:                tw, th, ox, oy = measure(probe, text, font)                if kind == "cta":                    tw += 2 * self.cta_pad_x                    th += 2 * self.cta_pad_y                if kind == "word" and self.glyph is not None:                    gh = round(th * 1.3)                    tw += round(gh * self.glyph.width / self.glyph.height) \                        + round(th * 0.45)                    th = max(th, gh)                out.append([kind, text, font, gap, tw, th, ox, oy])            return out
        self.rows = rows_for(("word", "title", "tag", "cta"))        self.width = max(r[4] for r in self.rows)        self.height = sum(r[3] + r[5] for r in self.rows)
    def origin(self, W, H, window=None):        a = self.a        bx = round(W * a.block_x)        by = round(H * a.block_y)        if a.anchor == "center":            bx -= self.width // 2        bx = max(round(W * 0.05), min(bx, W - self.width - round(W * 0.05)))        by = max(round(H * 0.07), min(by, H - self.height - round(H * 0.075)))        if window:            # Framed variant: the WHOLE block must sit inside the stadium            # capsule, including its rounded ends — never on/over the frame.            wx0, wy0, wx1, wy1 = window            r = (wy1 - wy0) / 2            cy = (wy0 + wy1) / 2            pad = round(W * 0.015)            by = max(wy0 + pad, min(by, wy1 - self.height - pad))            for _ in range(3):                dy = max(abs(by - cy), abs(by + self.height - cy))                dx = r - (max(r * r - dy * dy, 0.0)) ** 0.5                lo = round(wx0 + dx) + pad                hi = round(wx1 - dx) - pad - self.width                bx = max(lo, min(bx, max(lo, hi)))                by = max(wy0 + pad, min(by, wy1 - self.height - pad))        return bx, by
    def render(self, im, cutout=None, window=None):        """Layer order: scene -> scrim -> subject cutout -> ALL text LAST.
        The cutout's only job is the capsule break-out on the framed OG        variants (the subject pops over the frame like the official covers).        Text is always the topmost layer and never hidden by the subject."""        a = self.a        W, H = im.size        bx, by = self.origin(W, H, window)        base = im.convert("RGBA")
        if a.scrim > 0:            scr = Image.new("L", (W, H), 0)            pad = round(self.title_px * 0.8)            ImageDraw.Draw(scr).rounded_rectangle(                (bx - pad, by - pad, bx + self.width + pad, by + self.height + pad),                radius=pad, fill=a.scrim)            scr = scr.filter(ImageFilter.GaussianBlur(pad))            base.alpha_composite(                Image.composite(Image.new("RGBA", (W, H), (8, 8, 12, 255)),                                Image.new("RGBA", (W, H), (0, 0, 0, 0)), scr))
        white = (255, 255, 255, 255)
        def draw_rows(target, kinds):            layer = Image.new("RGBA", (W, H), (0, 0, 0, 0))            d = ImageDraw.Draw(layer)            y = by            for kind, text, font, gap, tw, th, ox, oy in self.rows:                y += gap                if kind not in kinds:                    y += th                    continue                x = bx if a.anchor == "left" else bx + (self.width - tw) // 2                if kind == "cta":                    ss = 4                    tile = Image.new("RGBA", (tw * ss, th * ss), (0, 0, 0, 0))                    td = ImageDraw.Draw(tile)                    td.rounded_rectangle((0, 0, tw * ss - 1, th * ss - 1),                                         radius=th * ss // 2, fill=(15, 15, 18, 135),                                         outline=(255, 255, 255, 115), width=ss)                    layer.alpha_composite(tile.resize((tw, th), Image.LANCZOS), (x, y))                    d.text((x + self.cta_pad_x - ox, y + self.cta_pad_y - oy),                           text, font=font, fill=white)                elif kind == "word" and self.glyph is not None:                    twt, tht, oxt, oyt = measure(d, text, font)                    gh = round(tht * 1.3)                    gw = round(gh * self.glyph.width / self.glyph.height)                    tile = Image.new("RGBA", (tw, th), (0, 0, 0, 0))                    tile.alpha_composite(                        self.glyph.resize((gw, gh), Image.LANCZOS), (0, (th - gh) // 2))                    ImageDraw.Draw(tile).text(                        (gw + round(tht * 0.45) - oxt, (th - tht) // 2 - oyt),                        text, font=font, fill=white)                    layer.alpha_composite(tile, (x, y))                else:                    d.text((x - ox, y - oy), text, font=font, fill=white)                y += th            target.alpha_composite(layer)
        if cutout is not None:            base.alpha_composite(cutout.convert("RGBA"))        draw_rows(base, {"title", "word", "tag", "cta"})        return base.convert("RGB")

def stadium_mask(size, box):    W, H = size    ss = 4 if max(W, H) <= 1800 else 2    big = Image.new("L", (W * ss, H * ss), 0)    r = (box[3] - box[1]) // 2    ImageDraw.Draw(big).rounded_rectangle([v * ss for v in box],                                          radius=r * ss, fill=255)    return big.resize((W, H), Image.LANCZOS)

def draw_dots(im, dot_rgb):    W, H = im.size    dr = max(3, round(W * 0.008))    ox, oy = round(W * 0.028), round(H * 0.045)    ss = 4    tile = Image.new("RGBA", (dr * 2 * ss, dr * 2 * ss), (0, 0, 0, 0))    ImageDraw.Draw(tile).ellipse((0, 0, dr * 2 * ss - 1, dr * 2 * ss - 1),                                 fill=(*dot_rgb, 255))    tile = tile.resize((dr * 2, dr * 2), Image.LANCZOS)    for cx in (ox, W - ox):        for cy in (oy, H - oy):            im.paste(tile, (cx - dr, cy - dr), tile)

def crop_box_for(size, ratio):    w, h = size    if w / h > ratio:        nw = round(h * ratio)        x = (w - nw) // 2        return (x, 0, x + nw, h)    nh = round(w / ratio)    y = (h - nh) // 2    return (0, y, w, y + nh)

def touches_edges(piece, band_h, band_w):    """True if the subject plate has meaningful alpha in the top or side    bands of the window — i.e. the subject actually reaches the capsule    edge and a breakout is possible."""    alpha = piece.getchannel("A")    w, h = alpha.size    for bbox in (        (0, 0, w, max(1, band_h)),          # top band        (0, 0, max(1, band_w), h),          # left band        (w - max(1, band_w), 0, w, h),      # right band    ):        region = alpha.crop(bbox)        hist = region.histogram()        solid = sum(hist[128:])        if solid > 0.005 * (region.width * region.height):            return True    return False

def build_framed(art, cutout, canvas_ratio, a, frame_rgb, dot_rgb):    W = art.width    H = round(W / canvas_ratio)    mx, my = round(W * a.margin_x), round(H * a.margin_y)    box = (mx, my, W - mx, H - my)    bw, bh = box[2] - box[0], box[3] - box[1]    cb = crop_box_for(art.size, bw / bh)
    scene = Image.new("RGB", (W, H), frame_rgb)    scene.paste(art.crop(cb).resize((bw, bh), Image.LANCZOS), (box[0], box[1]))
    cut = None    mask_box = box    if cutout is not None:        # UNCLIPPED on purpose: the subject breaks out of the capsule onto the        # frame (official look — Cinema Studio 4's boot + ball over the green).        cut = Image.new("RGBA", (W, H), (0, 0, 0, 0))        piece = cutout.crop(cb).resize((bw, bh), Image.LANCZOS)        cut.paste(piece, (box[0], box[1]), piece)        # ADAPTIVE window shrink: only if the subject actually reaches the        # window's top/side edges does the window pull in (top + sides,        # bottom stays flush) so the full-size plate pops over the capsule        # with zero ghosting. Otherwise the window keeps the full scene —        # no wasted frame ring.        ins = round(bh * a.pop_inset)        if ins > 0 and touches_edges(piece, round(bh * 0.06), round(bw * 0.04)):            mask_box = (box[0] + ins, box[1] + ins, box[2] - ins, box[3])
    mask = stadium_mask((W, H), mask_box)    out = Image.composite(scene, Image.new("RGB", (W, H), frame_rgb), mask)    if not a.no_dots:        draw_dots(out, dot_rgb)    return Lockup(a, W, H).render(out, cut, window=mask_box)

def main():    p = argparse.ArgumentParser(description=__doc__,                                formatter_class=argparse.RawDescriptionHelpFormatter)    p.add_argument("--art", required=True, help="full-bleed SCENE image, no text on it")    p.add_argument("--cutout", help="subject-with-alpha PNG aligned to --art "                                    "(remove_background output); pops out of the OG capsule")    p.add_argument("--title", required=True, help=r"product name; '\n' splits lines")    p.add_argument("--title-caps", choices=["upper", "keep"], default="upper")    p.add_argument("--title-width", type=float, default=0.52,                   help="longest title line as fraction of canvas width (0.35-0.62)")    p.add_argument("--title-max-h", type=float, default=0.26)    p.add_argument("--wordmark", default="Higgsfield", help="'' to disable")    p.add_argument("--tagline", default="")    p.add_argument("--cta", default=CTA_DEFAULT, help="'' to disable")    p.add_argument("--anchor", choices=["left", "center"], default="left")    p.add_argument("--block-x", type=float, default=0.07)    p.add_argument("--block-y", type=float, default=0.28)    p.add_argument("--scrim", type=int, default=90,                   help="0-255 soft dark scrim behind the block (0 = off)")    p.add_argument("--out-cover")    p.add_argument("--out-og")    p.add_argument("--out-og-wide")    p.add_argument("--frame-color", default=DEFAULT_FRAME)    p.add_argument("--force-frame-color", action="store_true")    p.add_argument("--dot-color", default="auto")    p.add_argument("--no-dots", action="store_true")    p.add_argument("--margin-x", type=float, default=0.045)    p.add_argument("--margin-y", type=float, default=0.055)    p.add_argument("--pop-inset", type=float, default=0.03,                   help="with --cutout: shrink the capsule window by this "                        "fraction of its height (top/sides) so the subject "                        "plate pops over the edge — applied ONLY when the "                        "subject actually reaches the window edge; 0 disables")    p.add_argument("--min-width", type=int, default=1500)    a = p.parse_args()
    if not (a.out_cover or a.out_og or a.out_og_wide):        sys.exit("nothing to do: pass --out-cover / --out-og / --out-og-wide")
    frame_rgb = hex_rgb(a.frame_color)    check_frame_color(frame_rgb, a.force_frame_color)    dot_rgb = ((26, 26, 26) if luminance(frame_rgb) > 0.55 else (255, 255, 255)) \        if a.dot_color == "auto" else hex_rgb(a.dot_color)
    art = Image.open(a.art).convert("RGB")    if art.width < a.min_width:        sys.exit(f"ERROR: art is {art.width}px wide (< {a.min_width}). Upscale "                 f"first — do not ship a soft cover.")    cutout = None    if a.cutout:        cutout = Image.open(a.cutout).convert("RGBA")        if cutout.size != art.size:            cutout = cutout.resize(art.size, Image.LANCZOS)
    if a.out_cover:        out = Lockup(a, art.width, art.height).render(art, cutout)        out.save(a.out_cover)        print(f"cover    {a.out_cover} {out.size[0]}x{out.size[1]}")
    if a.out_og:        out = build_framed(art, cutout, art.width / art.height, a, frame_rgb, dot_rgb)        out.save(a.out_og)        print(f"og       {a.out_og} {out.size[0]}x{out.size[1]} frame={a.frame_color}")
    if a.out_og_wide:        out = build_framed(art, cutout, 1.91, a, frame_rgb, dot_rgb)        out.save(a.out_og_wide)        print(f"og-wide  {a.out_og_wide} {out.size[0]}x{out.size[1]} frame={a.frame_color}")

if __name__ == "__main__":    main()