@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/threejs/skills/_shared/scripts/placeholder_lib.py

@@ -0,0 +1,993 @@
+"""Local placeholder image generation — placehold.co replacement with shape support."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from PIL import Image, ImageDraw, ImageFont
+
+ShapeName = Literal[
+    "fill",
+    "rounded",
+    "circle",
+    "ellipse",
+    "diamond",
+    "ring",
+    "triangle-up",
+    "triangle-down",
+    "auto",
+]
+
+CSS_COLORS: dict[str, str] = {
+    "transparent": "00000000",
+    "black": "000000",
+    "white": "ffffff",
+    "red": "ff0000",
+    "green": "00ff00",
+    "blue": "0000ff",
+    "orange": "ffa500",
+    "yellow": "ffff00",
+    "gray": "808080",
+    "grey": "808080",
+}
+
+
+def parse_color(value: str, *, alpha_default: int = 255) -> tuple[int, int, int, int]:
+    raw = (value or "").strip().lower()
+    if not raw:
+        raise ValueError("color value is required")
+    if raw in CSS_COLORS:
+        raw = CSS_COLORS[raw]
+    raw = raw.lstrip("#")
+    if raw == "transparent":
+        return 0, 0, 0, 0
+    if len(raw) == 3:
+        raw = "".join(ch * 2 for ch in raw)
+    if len(raw) == 8:
+        r, g, b, a = (int(raw[i : i + 2], 16) for i in (0, 2, 4, 6))
+        return r, g, b, a
+    if len(raw) != 6:
+        raise ValueError(f"invalid color: {value}")
+    r, g, b = (int(raw[i : i + 2], 16) for i in (0, 2, 4))
+    return r, g, b, alpha_default
+
+
+GradientDirection = Literal["vertical", "horizontal", "diag-tl-br", "diag-tr-bl"]
+
+
+@dataclass(frozen=True)
+class ColorStop:
+    color: tuple[int, int, int, int]
+    position: float
+
+
+@dataclass(frozen=True)
+class SolidFill:
+    color: tuple[int, int, int, int]
+
+
+@dataclass(frozen=True)
+class LinearGradientFill:
+    stops: tuple[ColorStop, ...]
+    direction: GradientDirection = "vertical"
+
+
+@dataclass(frozen=True)
+class RadialGradientFill:
+    stops: tuple[ColorStop, ...]
+    center: tuple[float, float] = (0.5, 0.5)
+
+
+FillSpec = SolidFill | LinearGradientFill | RadialGradientFill
+
+_LINEAR_DIRECTIONS: dict[str, GradientDirection] = {
+    "vertical": "vertical",
+    "v": "vertical",
+    "horizontal": "horizontal",
+    "h": "horizontal",
+    "diag-tl-br": "diag-tl-br",
+    "diag-tr-bl": "diag-tr-bl",
+    "diagonal": "diag-tl-br",
+}
+
+
+def is_gradient_fill(value: str) -> bool:
+    raw = (value or "").strip().lower()
+    return raw.startswith("linear:") or raw.startswith("radial:")
+
+
+def _split_gradient_stops(raw: str) -> list[str]:
+    normalized = raw.replace("->", "→")
+    return [part.strip() for part in normalized.split("→") if part.strip()]
+
+
+def _parse_stop_position(token: str, *, radial: bool) -> float:
+    value = token.strip().lower()
+    if value in {"center", "c"}:
+        return 0.0
+    if value in {"edge", "e", "outer"}:
+        return 1.0
+    if value.endswith("%"):
+        return max(0.0, min(1.0, float(value[:-1]) / 100.0))
+    pos = float(value)
+    if pos > 1.0:
+        pos /= 100.0
+    return max(0.0, min(1.0, pos))
+
+
+def _parse_color_stop_part(part: str, *, radial: bool) -> ColorStop:
+    if "@" in part:
+        color_raw, pos_raw = part.rsplit("@", 1)
+        position = _parse_stop_position(pos_raw, radial=radial)
+    else:
+        color_raw = part
+        position = -1.0
+    return ColorStop(color=parse_color(color_raw.strip()), position=position)
+
+
+def _normalize_stops(parts: list[str], *, radial: bool) -> tuple[ColorStop, ...]:
+    if len(parts) < 2:
+        raise ValueError("gradient requires at least two color stops")
+    parsed = [_parse_color_stop_part(part, radial=radial) for part in parts]
+    unset = [stop for stop in parsed if stop.position < 0]
+    if unset and len(unset) != len(parsed):
+        raise ValueError("gradient stops must all specify @position or none")
+    if unset:
+        if len(parsed) == 2:
+            parsed = [
+                ColorStop(parsed[0].color, 0.0),
+                ColorStop(parsed[1].color, 1.0),
+            ]
+        else:
+            step = 1.0 / (len(parsed) - 1)
+            parsed = [
+                ColorStop(stop.color, i * step) for i, stop in enumerate(parsed)
+            ]
+    parsed = sorted(parsed, key=lambda stop: stop.position)
+    if parsed[0].position > 0.0:
+        parsed = [ColorStop(parsed[0].color, 0.0), *parsed]
+    if parsed[-1].position < 1.0:
+        parsed = [*parsed, ColorStop(parsed[-1].color, 1.0)]
+    return tuple(parsed)
+
+
+def parse_fill(value: str) -> FillSpec:
+    raw = (value or "").strip()
+    if not raw:
+        raise ValueError("fill value is required")
+    lower = raw.lower()
+    if lower.startswith("linear:"):
+        body = raw.split(":", 1)[1]
+        direction: GradientDirection = "vertical"
+        if ":" in body:
+            stops_raw, dir_raw = body.rsplit(":", 1)
+            if dir_raw.strip().lower() in _LINEAR_DIRECTIONS:
+                body = stops_raw
+                direction = _LINEAR_DIRECTIONS[dir_raw.strip().lower()]
+        stops = _normalize_stops(_split_gradient_stops(body), radial=False)
+        return LinearGradientFill(stops=stops, direction=direction)
+    if lower.startswith("radial:"):
+        body = raw.split(":", 1)[1]
+        stops = _normalize_stops(_split_gradient_stops(body), radial=True)
+        return RadialGradientFill(stops=stops)
+    return SolidFill(color=parse_color(raw))
+
+
+def rgba_to_hex(color: tuple[int, int, int, int], *, with_alpha: bool = False) -> str:
+    r, g, b, a = color
+    if with_alpha and a != 255:
+        return f"{r:02x}{g:02x}{b:02x}{a:02x}"
+    return f"{r:02x}{g:02x}{b:02x}"
+
+
+def describe_fill_short(value: str) -> str:
+    if not is_gradient_fill(value):
+        return normalize_hex_color(value)
+    spec = parse_fill(value)
+    if isinstance(spec, LinearGradientFill):
+        a = rgba_to_hex(spec.stops[0].color)
+        b = rgba_to_hex(spec.stops[-1].color)
+        return f"lin #{a}→#{b}"
+    if isinstance(spec, RadialGradientFill):
+        a = rgba_to_hex(spec.stops[0].color, with_alpha=True)
+        b = rgba_to_hex(spec.stops[-1].color, with_alpha=True)
+        return f"rad #{a}→#{b}"
+    return normalize_hex_color(value)
+
+
+def fill_to_sidecar_value(value: str) -> str | dict:
+    if not is_gradient_fill(value):
+        return f"#{normalize_hex_color(value)}"
+    spec = parse_fill(value)
+    if isinstance(spec, LinearGradientFill):
+        return {
+            "kind": "linear",
+            "direction": spec.direction,
+            "stops": [
+                {"color": f"#{rgba_to_hex(stop.color, with_alpha=True)}", "at": stop.position}
+                for stop in spec.stops
+            ],
+        }
+    if isinstance(spec, RadialGradientFill):
+        return {
+            "kind": "radial",
+            "center": {"x": spec.center[0], "y": spec.center[1]},
+            "stops": [
+                {"color": f"#{rgba_to_hex(stop.color, with_alpha=True)}", "at": stop.position}
+                for stop in spec.stops
+            ],
+        }
+    return f"#{normalize_hex_color(value)}"
+
+
+def _lerp_channel(a: int, b: int, t: float) -> int:
+    return int(round(a + (b - a) * t))
+
+
+def _sample_gradient(stops: tuple[ColorStop, ...], t: float) -> tuple[int, int, int, int]:
+    t = max(0.0, min(1.0, t))
+    for index in range(len(stops) - 1):
+        left = stops[index]
+        right = stops[index + 1]
+        if t <= right.position or index == len(stops) - 2:
+            span = max(right.position - left.position, 1e-9)
+            local = 0.0 if span == 0 else (t - left.position) / span
+            local = max(0.0, min(1.0, local))
+            return (
+                _lerp_channel(left.color[0], right.color[0], local),
+                _lerp_channel(left.color[1], right.color[1], local),
+                _lerp_channel(left.color[2], right.color[2], local),
+                _lerp_channel(left.color[3], right.color[3], local),
+            )
+    last = stops[-1].color
+    return last
+
+
+def _linear_gradient_image(width: int, height: int, spec: LinearGradientFill) -> Image.Image:
+    image = Image.new("RGBA", (width, height))
+    pixels = image.load()
+    max_x = max(width - 1, 1)
+    max_y = max(height - 1, 1)
+    for y in range(height):
+        for x in range(width):
+            if spec.direction == "vertical":
+                t = y / max_y
+            elif spec.direction == "horizontal":
+                t = x / max_x
+            elif spec.direction == "diag-tl-br":
+                t = (x + y) / (max_x + max_y)
+            else:
+                t = (x + (max_y - y)) / (max_x + max_y)
+            pixels[x, y] = _sample_gradient(spec.stops, t)
+    return image
+
+
+def _radial_gradient_image(width: int, height: int, spec: RadialGradientFill) -> Image.Image:
+    image = Image.new("RGBA", (width, height))
+    pixels = image.load()
+    cx = spec.center[0] * max(width - 1, 1)
+    cy = spec.center[1] * max(height - 1, 1)
+    max_dist = max(((cx) ** 2 + (cy) ** 2) ** 0.5, ((width - 1 - cx) ** 2 + (cy) ** 2) ** 0.5,
+                   ((cx) ** 2 + (height - 1 - cy) ** 2) ** 0.5, ((width - 1 - cx) ** 2 + (height - 1 - cy) ** 2) ** 0.5, 1.0)
+    for y in range(height):
+        for x in range(width):
+            dist = ((x - cx) ** 2 + (y - cy) ** 2) ** 0.5
+            t = dist / max_dist
+            pixels[x, y] = _sample_gradient(spec.stops, t)
+    return image
+
+
+def render_fill_layer(width: int, height: int, spec: FillSpec) -> Image.Image:
+    if isinstance(spec, SolidFill):
+        return Image.new("RGBA", (width, height), spec.color)
+    if isinstance(spec, LinearGradientFill):
+        return _linear_gradient_image(width, height, spec)
+    return _radial_gradient_image(width, height, spec)
+
+
+def parse_size(value: str) -> tuple[int, int]:
+    raw = (value or "").strip().lower().replace(" ", "")
+    if not raw:
+        raise ValueError("size is required")
+    if "x" in raw:
+        w_s, h_s = raw.split("x", 1)
+        w, h = int(w_s), int(h_s)
+    else:
+        w = h = int(raw)
+    if w < 1 or h < 1 or w > 4096 or h > 4096:
+        raise ValueError(f"size out of range: {value}")
+    return w, h
+
+
+def infer_shape(label: str, width: int, height: int) -> ShapeName:
+    name = (label or "").strip().lower()
+    if not name:
+        return "fill"
+    if name.startswith(("bg_", "background_", "scene_")):
+        return "fill"
+    if name.startswith(("btn_", "button_", "cta_", "tab_")):
+        return "rounded"
+    if name.startswith(("ring_", "halo_", "aura_")):
+        return "ring"
+    if name.startswith(("diamond_", "gem_", "crystal_")):
+        return "diamond"
+    if name.startswith(("arrow_up", "arrow-up", "caret_up")):
+        return "triangle-up"
+    if name.startswith(("arrow_down", "arrow-down", "caret_down")):
+        return "triangle-down"
+    if name.startswith(("tile_", "icon_", "token_", "piece_", "coin_")):
+        ratio = width / max(height, 1)
+        if 0.85 <= ratio <= 1.15:
+            return "circle"
+        return "rounded"
+    if name.startswith(("badge_", "chip_", "pill_")):
+        return "rounded"
+    if width == height and min(width, height) <= 192:
+        return "circle"
+    return "fill"
+
+
+def normalize_hex_color(value: str) -> str:
+    raw = (value or "").strip().lower().lstrip("#")
+    if raw in CSS_COLORS:
+        raw = CSS_COLORS[raw]
+    if len(raw) == 3:
+        raw = "".join(ch * 2 for ch in raw)
+    if len(raw) != 6:
+        return raw or "??????"
+    return raw
+
+
+def infer_role(label: str) -> str:
+    name = (label or "").strip().lower()
+    if not name:
+        return "asset · 资产"
+    rules: list[tuple[tuple[str, ...], str]] = [
+        (("bg_", "background_", "scene_"), "background · 背景"),
+        (("btn_", "button_", "cta_", "tab_"), "button · 按钮"),
+        (("tile_", "piece_", "token_", "coin_"), "tile · 方块"),
+        (("icon_",), "icon · 图标"),
+        (("ring_", "halo_", "aura_"), "halo/VFX · 光环"),
+        (("gem_", "diamond_", "crystal_"), "gem · 宝石"),
+        (("vfx_", "fx_", "particle_"), "VFX · 特效"),
+        (("ui_", "hud_", "panel_"), "UI · 界面"),
+        (("txt_", "digit_", "num_"), "digit · 数字"),
+        (("logo_", "brand_"), "logo · 标识"),
+        (("avatar_", "char_", "hero_"), "character · 角色"),
+    ]
+    for prefixes, role in rules:
+        if name.startswith(prefixes):
+            return role
+    if "bg" in name:
+        return "background · 背景"
+    if "btn" in name or "cta" in name:
+        return "button · 按钮"
+    return "asset · 资产"
+
+
+def role_short(role: str) -> str:
+    if " · " in role:
+        return role.split(" · ", 1)[0].strip()
+    return role
+
+
+def build_metadata_lines(
+    *,
+    width: int,
+    height: int,
+    bg: str,
+    fg: str,
+    label: str,
+    role: str | None = None,
+    minimal: bool = False,
+) -> list[tuple[str, float]]:
+    """Return (text, weight) lines; weight 1.0 = title scale."""
+    bg_label = describe_fill_short(bg)
+    fg_hex = normalize_hex_color(fg)
+    resolved_role = (role or infer_role(label)).strip()
+    min_side = min(width, height)
+    use_minimal = minimal or min_side < 200 or height < 140
+
+    if use_minimal:
+        # Two lines only — largest readable fonts on small contract sizes.
+        return [
+            (label, 1.0),
+            (f"{width}x{height}  {bg_label}  {role_short(resolved_role)}", 0.62),
+        ]
+
+    return [
+        (label, 1.0),
+        (f"{width} x {height} px", 0.68),
+        (f"bg {bg_label}  fg #{fg_hex}", 0.56),
+        (resolved_role, 0.6),
+    ]
+
+
+# Text-only overlay supersample — shapes stay 1×; text rasterized sharp then pasted.
+TEXT_SUPERSAMPLE = 4
+
+
+def _needs_cjk_font(text: str) -> bool:
+    return any(ord(ch) > 127 for ch in text)
+
+
+def load_font(size: int, *, text: str | None = None) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    use_cjk = _needs_cjk_font(text or "")
+    if use_cjk:
+        candidates = [
+            "/System/Library/Fonts/PingFang.ttc",
+            "/System/Library/Fonts/STHeiti Medium.ttc",
+            "/System/Library/Fonts/STHeiti Light.ttc",
+            "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc",
+        ]
+    else:
+        candidates = [
+            "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+            "/Library/Fonts/Arial Bold.ttf",
+            "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+            "/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf",
+            "/System/Library/Fonts/Helvetica.ttc",
+        ]
+    for path in candidates:
+        try:
+            return ImageFont.truetype(path, size, layout_engine=ImageFont.Layout.BASIC)
+        except (OSError, ValueError):
+            try:
+                return ImageFont.truetype(path, size)
+            except OSError:
+                continue
+    return ImageFont.load_default()
+
+
+def _text_size(draw: ImageDraw.ImageDraw, text: str, font: ImageFont.ImageFont) -> tuple[int, int]:
+    bbox = draw.textbbox((0, 0), text, font=font)
+    return bbox[2] - bbox[0], bbox[3] - bbox[1]
+
+
+def _fit_minimal_subtitle(
+    draw: ImageDraw.ImageDraw,
+    inner_w: int,
+    *,
+    width: int,
+    height: int,
+    bg_hex: str,
+    role: str,
+    font_size: int,
+) -> str:
+    short = role_short(role)
+    for text in (
+        f"{width}x{height}  {bg_hex}  {short}",
+        f"{width}x{height}  {bg_hex}",
+        f"{width}x{height}",
+    ):
+        font = load_font(font_size, text=text)
+        tw, _ = _text_size(draw, text, font)
+        if tw <= inner_w:
+            return text
+    return f"{width}x{height}"
+
+
+def _stroke_for_fill(fill: tuple[int, int, int] | tuple[int, int, int, int]) -> tuple[int, int, int]:
+    r, g, b = fill[0], fill[1], fill[2]
+    luminance = 0.299 * r + 0.587 * g + 0.114 * b
+    return (0, 0, 0) if luminance > 140 else (255, 255, 255)
+
+
+def _draw_metadata_direct(
+    draw: ImageDraw.ImageDraw,
+    box: tuple[int, int, int, int],
+    lines: list[tuple[str, float]],
+    fill: tuple[int, int, int] | tuple[int, int, int, int],
+    *,
+    meta: dict | None = None,
+) -> None:
+    x0, y0, x1, y1 = box
+    inner_w = max(1, x1 - x0)
+    inner_h = max(1, y1 - y0)
+    min_side = min(inner_w, inner_h)
+    line_count = max(1, len(lines))
+    two_line = line_count == 2
+
+    if two_line:
+        title = lines[0][0]
+        title_size = max(14, min(int(inner_h * 0.44), int(inner_w / max(len(title), 3))))
+        sub_size = max(10, min(int(inner_h * 0.24), title_size - 3))
+        gap = max(2, title_size // 7)
+        if meta:
+            subtitle = _fit_minimal_subtitle(
+                draw,
+                inner_w,
+                width=int(meta["width"]),
+                height=int(meta["height"]),
+                bg_hex=str(meta["bg_hex"]),
+                role=str(meta["role"]),
+                font_size=sub_size,
+            )
+        else:
+            subtitle = lines[1][0]
+        title_font = load_font(title_size, text=title)
+        sub_font = load_font(sub_size, text=subtitle)
+        th0 = _text_size(draw, title, title_font)[1]
+        th1 = _text_size(draw, subtitle, sub_font)[1]
+        total_h = th0 + gap + th1
+        y = int(y0 + (inner_h - total_h) / 2)
+        cx = int(x0 + inner_w / 2)
+        draw.text((cx, int(y + th0 / 2)), title, fill=fill, font=title_font, anchor="mm")
+        draw.text((cx, int(y + th0 + gap + th1 / 2)), subtitle, fill=fill, font=sub_font, anchor="mm")
+        return
+
+    base_size = max(14, min(56, min(inner_h // (line_count + 1), min_side // 3)))
+    for start in range(base_size, 12, -1):
+        sized: list[tuple[str, ImageFont.ImageFont, int, int]] = []
+        total_h = 0
+        gap = max(3, start // 5)
+        ok = True
+        for text, weight in lines:
+            size = max(12, int(start * weight))
+            font = load_font(size, text=text)
+            tw, th = _text_size(draw, text, font)
+            if tw > inner_w:
+                ok = False
+                break
+            sized.append((text, font, tw, th, size))
+            total_h += th + gap
+        if not ok:
+            continue
+        if sized:
+            total_h -= gap
+        if total_h <= inner_h:
+            y = int(y0 + (inner_h - total_h) / 2)
+            for text, font, tw, th, size in sized:
+                cx = int(x0 + inner_w / 2)
+                cy = int(y + th / 2)
+                kwargs: dict = {"fill": fill, "font": font, "anchor": "mm"}
+                if size >= 14:
+                    kwargs["stroke_width"] = 1
+                    kwargs["stroke_fill"] = _stroke_for_fill(fill)
+                draw.text((cx, cy), text, **kwargs)
+                y += th + gap
+            return
+
+    font = load_font(max(12, min_side // 5), text=lines[0][0])
+    cx = int(x0 + inner_w / 2)
+    cy = int(y0 + inner_h / 2)
+    draw.text(
+        (cx, cy),
+        lines[0][0],
+        fill=fill,
+        font=font,
+        anchor="mm",
+    )
+
+
+def draw_metadata_stack(
+    image: Image.Image,
+    box: tuple[int, int, int, int],
+    lines: list[tuple[str, float]],
+    fill: tuple[int, int, int] | tuple[int, int, int, int],
+    *,
+    supersample: int = TEXT_SUPERSAMPLE,
+    meta: dict | None = None,
+) -> None:
+    x0, y0, x1, y1 = box
+    bw = max(1, x1 - x0)
+    bh = max(1, y1 - y0)
+    scale = max(1, int(supersample))
+
+    if scale == 1:
+        draw = ImageDraw.Draw(image)
+        _draw_metadata_direct(draw, box, lines, fill, meta=meta)
+        return
+
+    overlay = Image.new("RGBA", (bw * scale, bh * scale), (0, 0, 0, 0))
+    o_draw = ImageDraw.Draw(overlay)
+    scaled_meta = None
+    if meta:
+        scaled_meta = {**meta, "width": int(meta["width"]), "height": int(meta["height"])}
+    _draw_metadata_direct(o_draw, (0, 0, bw * scale, bh * scale), lines, fill, meta=scaled_meta)
+    overlay = overlay.resize((bw, bh), Image.Resampling.BOX)
+    image.paste(overlay, (x0, y0), overlay)
+
+
+def fit_font(
+    draw: ImageDraw.ImageDraw,
+    text: str,
+    max_w: int,
+    max_h: int,
+    *,
+    start_size: int = 48,
+    min_size: int = 12,
+) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    for size in range(start_size, min_size - 1, -2):
+        font = load_font(size)
+        bbox = draw.textbbox((0, 0), text, font=font)
+        tw = bbox[2] - bbox[0]
+        th = bbox[3] - bbox[1]
+        if tw <= max_w and th <= max_h:
+            return font
+    return load_font(min_size)
+
+
+def draw_centered_text(
+    draw: ImageDraw.ImageDraw,
+    box: tuple[int, int, int, int],
+    text: str,
+    fill: tuple[int, int, int] | tuple[int, int, int, int],
+    *,
+    font: ImageFont.FreeTypeFont | ImageFont.ImageFont | None = None,
+) -> None:
+    x0, y0, x1, y1 = box
+    inner_w = x1 - x0
+    inner_h = y1 - y0
+    font = font or fit_font(draw, text, inner_w, inner_h)
+    bbox = draw.textbbox((0, 0), text, font=font)
+    tw = bbox[2] - bbox[0]
+    th = bbox[3] - bbox[1]
+    x = x0 + (inner_w - tw) / 2 - bbox[0]
+    y = y0 + (inner_h - th) / 2 - bbox[1]
+    draw.text((x, y), text, fill=fill, font=font)
+
+
+def _content_box(width: int, height: int, *, pad_ratio: float = 0.08) -> tuple[int, int, int, int]:
+    pad = max(4, int(min(width, height) * pad_ratio))
+    return pad, pad, width - pad, height - pad
+
+
+def _build_shape_mask(
+    width: int,
+    height: int,
+    shape: ShapeName,
+    box: tuple[int, int, int, int],
+) -> Image.Image:
+    mask = Image.new("L", (width, height), 0)
+    draw = ImageDraw.Draw(mask)
+    x0, y0, x1, y1 = box
+    w = x1 - x0
+    h = y1 - y0
+    cx = (x0 + x1) // 2
+    cy = (y0 + y1) // 2
+
+    if shape == "fill":
+        draw.rectangle(box, fill=255)
+        return mask
+
+    if shape == "rounded":
+        radius = max(8, min(w, h) // 6)
+        draw.rounded_rectangle(box, radius=radius, fill=255)
+        return mask
+
+    if shape == "circle":
+        side = min(w, h)
+        left = cx - side // 2
+        top = cy - side // 2
+        draw.ellipse((left, top, left + side, top + side), fill=255)
+        return mask
+
+    if shape == "ellipse":
+        draw.ellipse(box, fill=255)
+        return mask
+
+    if shape == "diamond":
+        points = [(cx, y0), (x1, cy), (cx, y1), (x0, cy)]
+        draw.polygon(points, fill=255)
+        return mask
+
+    if shape == "ring":
+        side = min(w, h)
+        left = cx - side // 2
+        top = cy - side // 2
+        outer = (left, top, left + side, top + side)
+        thickness = max(3, side // 8)
+        draw.ellipse(outer, outline=255, width=thickness)
+        return mask
+
+    if shape == "triangle-up":
+        points = [(cx, y0), (x1, y1), (x0, y1)]
+        draw.polygon(points, fill=255)
+        return mask
+
+    if shape == "triangle-down":
+        points = [(x0, y0), (x1, y0), (cx, y1)]
+        draw.polygon(points, fill=255)
+        return mask
+
+    draw.rectangle(box, fill=255)
+    return mask
+
+
+def _composite_shape_fill(
+    image: Image.Image,
+    *,
+    shape: ShapeName,
+    box: tuple[int, int, int, int],
+    fill_spec: FillSpec,
+) -> tuple[int, int, int, int]:
+    x0, y0, x1, y1 = box
+    bw = max(1, x1 - x0)
+    bh = max(1, y1 - y0)
+    local_box = (0, 0, bw, bh)
+    fill_layer = render_fill_layer(bw, bh, fill_spec)
+    mask = _build_shape_mask(bw, bh, shape, local_box)
+    shaped = Image.new("RGBA", (bw, bh), (0, 0, 0, 0))
+    shaped.paste(fill_layer, (0, 0), mask)
+    image.paste(shaped, (x0, y0), shaped)
+    return box
+
+
+def _draw_shape(
+    draw: ImageDraw.ImageDraw,
+    shape: ShapeName,
+    box: tuple[int, int, int, int],
+    fill: tuple[int, int, int, int],
+) -> tuple[int, int, int, int]:
+    x0, y0, x1, y1 = box
+    w = x1 - x0
+    h = y1 - y0
+    cx = (x0 + x1) // 2
+    cy = (y0 + y1) // 2
+
+    if shape == "fill":
+        draw.rectangle(box, fill=fill)
+        return box
+
+    if shape == "rounded":
+        radius = max(8, min(w, h) // 6)
+        draw.rounded_rectangle(box, radius=radius, fill=fill)
+        return box
+
+    if shape == "circle":
+        side = min(w, h)
+        left = cx - side // 2
+        top = cy - side // 2
+        circle_box = (left, top, left + side, top + side)
+        draw.ellipse(circle_box, fill=fill)
+        return circle_box
+
+    if shape == "ellipse":
+        draw.ellipse(box, fill=fill)
+        return box
+
+    if shape == "diamond":
+        points = [(cx, y0), (x1, cy), (cx, y1), (x0, cy)]
+        draw.polygon(points, fill=fill)
+        return box
+
+    if shape == "ring":
+        side = min(w, h)
+        left = cx - side // 2
+        top = cy - side // 2
+        outer = (left, top, left + side, top + side)
+        thickness = max(3, side // 8)
+        draw.ellipse(outer, outline=fill, width=thickness)
+        return outer
+
+    if shape == "triangle-up":
+        points = [(cx, y0), (x1, y1), (x0, y1)]
+        draw.polygon(points, fill=fill)
+        return box
+
+    if shape == "triangle-down":
+        points = [(x0, y0), (x1, y0), (cx, y1)]
+        draw.polygon(points, fill=fill)
+        return box
+
+    draw.rectangle(box, fill=fill)
+    return box
+
+
+def shape_uses_transparent_canvas(shape: ShapeName) -> bool:
+    """Non-fill shapes leave pixels outside the silhouette transparent."""
+    return shape != "fill"
+
+
+def resolve_transparent_bg(shape: ShapeName, transparent_bg: bool | None) -> bool:
+    if transparent_bg is None:
+        return shape_uses_transparent_canvas(shape)
+    return transparent_bg
+
+
+def _render_placeholder_raster(
+    *,
+    width: int,
+    height: int,
+    bg: str,
+    fg: str,
+    label: str,
+    role: str | None,
+    resolved_shape: ShapeName,
+    transparent_bg: bool,
+    display_width: int | None = None,
+    display_height: int | None = None,
+    minimal: bool = False,
+) -> Image.Image:
+    fill_spec = parse_fill(bg)
+    bg_label = describe_fill_short(bg)
+
+    if transparent_bg:
+        image = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+    elif resolved_shape == "fill" and isinstance(fill_spec, SolidFill):
+        image = Image.new("RGBA", (width, height), fill_spec.color)
+    else:
+        image = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+
+    if resolved_shape == "fill":
+        text_box = (0, 0, width, height)
+        if is_gradient_fill(bg) or transparent_bg:
+            _composite_shape_fill(image, shape="fill", box=text_box, fill_spec=fill_spec)
+    else:
+        box = _content_box(width, height)
+        text_box = _composite_shape_fill(image, shape=resolved_shape, box=box, fill_spec=fill_spec)
+
+    fg_rgba = parse_color(fg)
+    text_fill: tuple[int, int, int] | tuple[int, int, int, int] = (
+        fg_rgba[:3] if fg_rgba[3] == 255 else fg_rgba
+    )
+    metadata_lines = build_metadata_lines(
+        width=display_width or width,
+        height=display_height or height,
+        bg=bg,
+        fg=fg,
+        label=label,
+        role=role,
+        minimal=minimal,
+    )
+    logical_w = display_width or width
+    logical_h = display_height or height
+    text_meta = {
+        "width": logical_w,
+        "height": logical_h,
+        "bg_hex": bg_label,
+        "role": (role or infer_role(label)),
+    }
+    draw_metadata_stack(image, text_box, metadata_lines, text_fill, meta=text_meta)
+    return image
+
+
+def render_placeholder(
+    *,
+    width: int,
+    height: int,
+    bg: str,
+    fg: str,
+    text: str | None = None,
+    role: str | None = None,
+    shape: ShapeName = "fill",
+    transparent_bg: bool | None = None,
+    minimal: bool = False,
+) -> Image.Image:
+    label = (text or f"{width}x{height}").strip()
+    resolved_shape = infer_shape(label, width, height) if shape == "auto" else shape
+    return _render_placeholder_raster(
+        width=width,
+        height=height,
+        bg=bg,
+        fg=fg,
+        label=label,
+        role=role,
+        resolved_shape=resolved_shape,
+        transparent_bg=resolve_transparent_bg(resolved_shape, transparent_bg),
+        minimal=minimal,
+    )
+
+
+DEFAULT_IMAGE_FORMAT = "webp"
+SIDECAR_VERSION = 1
+
+
+def normalize_output_path(path: str | Path) -> Path:
+    """Default to .webp when the output path has no extension."""
+    out = Path(path)
+    if not out.suffix:
+        return out.with_suffix(f".{DEFAULT_IMAGE_FORMAT}")
+    return out
+
+
+def sidecar_path_for(image_path: str | Path) -> Path:
+    return Path(image_path).with_suffix(".json")
+
+
+def build_sidecar_payload(
+    *,
+    image_path: str | Path,
+    label: str,
+    width: int,
+    height: int,
+    bg: str,
+    fg: str,
+    shape: str,
+    role: str | None,
+    transparent: bool,
+    retina: int = 1,
+    logical_width: int | None = None,
+    logical_height: int | None = None,
+) -> dict:
+    image_path = Path(image_path)
+    resolved_role = (role or infer_role(label)).strip()
+    lw = logical_width or width
+    lh = logical_height or height
+    return {
+        "kind": "playcraft.placeholder",
+        "version": SIDECAR_VERSION,
+        "label": label,
+        "role": resolved_role,
+        "purpose": role_short(resolved_role),
+        "size": {"width": lw, "height": lh},
+        "outputSize": {"width": width, "height": height},
+        "retina": retina,
+        "colors": {
+            "bg": fill_to_sidecar_value(bg),
+            "fg": f"#{normalize_hex_color(fg)}",
+        },
+        "shape": shape,
+        "transparent": transparent,
+        "format": output_format_from_path(image_path),
+        "image": image_path.name,
+        "note": "Develop-stage placeholder. TA replaces image at the same contract path; code unchanged.",
+    }
+
+
+def write_placeholder_sidecar(image_path: str | Path, payload: dict) -> Path:
+    sidecar = sidecar_path_for(image_path)
+    sidecar.parent.mkdir(parents=True, exist_ok=True)
+    sidecar.write_text(f"{json.dumps(payload, ensure_ascii=False, indent=2)}\n", encoding="utf-8")
+    return sidecar
+
+
+def output_format_from_path(path: str | Path) -> str:
+    suffix = Path(path).suffix.lower().lstrip(".")
+    if suffix in {"jpg", "jpeg", "png", "webp", "gif"}:
+        return suffix
+    return DEFAULT_IMAGE_FORMAT
+
+
+def save_placeholder(image: Image.Image, path: str | Path, *, quality: int = 95) -> None:
+    out = Path(path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    fmt = output_format_from_path(out)
+
+    if fmt in {"jpg", "jpeg"}:
+        save_image = image
+        if save_image.mode == "RGBA":
+            background = Image.new("RGB", save_image.size, parse_color("ffffff")[:3])
+            background.paste(save_image, mask=save_image.split()[3])
+            save_image = background
+        save_image.save(out, format="JPEG", quality=quality)
+        return
+
+    if fmt == "webp":
+        image.save(out, format="WEBP", quality=quality, method=6)
+        return
+
+    if fmt == "gif":
+        if image.mode == "RGBA":
+            image.save(out, format="GIF", transparency=0)
+        else:
+            image.save(out, format="GIF")
+        return
+
+    image.save(out, format="PNG")
+
+
+def normalize_batch_entry(entry: dict) -> dict:
+    label = entry.get("label") or entry.get("text") or Path(str(entry.get("path", ""))).stem
+    size = entry.get("size") or f"{entry.get('width', 128)}x{entry.get('height', 128)}"
+    return {
+        "path": str(normalize_output_path(str(entry["path"]))),
+        "size": str(size),
+        "bg": str(entry.get("bg", "1a1a2e")),
+        "fg": str(entry.get("fg", "cccccc")),
+        "label": str(label),
+        "role": (str(entry["role"]).strip() or None) if entry.get("role") is not None else None,
+        "shape": str(entry.get("shape", "auto")),
+        "retina": int(entry.get("retina", 1)),
+        "minimal": bool(entry.get("minimal", False)),
+        "transparent": entry.get("transparent"),
+    }
+
+
+def slug_label(label: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9_+-]+", "_", label).strip("_") or "asset"