spriteforge 0.1.1__py3-none-any.whl

spriteforge/game/team_reports.py

@@ -0,0 +1,394 @@
+"""Each agent's report, in simple words and point by point.
+
+Entry (at G2): the Game Designer writes the team's task list. Every agent that will work on
+the build gets a plan: what must be ready before it starts (its entry gate), the steps it will
+take for this game, and how we know it is done (its exit gate). The human approves the plans
+with the design.
+
+Exit (after each build, before G3/G4): every agent that worked says what it did, and code
+checks its exit gate from the build report (the model never marks its own work as done).
+
+Muse Spark writes the task list; code keeps it to the agents that really work on this build,
+in their working order, fills what is missing from a plan made from the design, and keeps each
+point short.
+"""
+
+from collections import Counter
+
+from pydantic import Field
+
+from spriteforge.agents.models import Contract
+
+from .design import GameDesign
+from .plan import PlanRecord
+
+POINT = 140  # the longest point, in characters
+MAX_TASKS = 8
+
+# What each agent really does in a build: the task list may only promise these.
+JOBS = {
+    "Level/Tile Designer": "lays out each level as tiles from the plan, checks that every jump "
+    "can be made, draws a preview of each level",
+    "Art Director": "plans the art of every thing in the design (look, size, animation rows), "
+    "keeps one palette and style, makes the art sheet",
+    "Pixel Artist": "takes art from the library first, asks Muse Image for the rest, cleans "
+    "each image to the palette and size, draws the animation frames",
+    "Menu Designer": "writes every menu screen (title, pause, game over ...), the theme colours "
+    "and the title art, takes a screenshot of each screen",
+    "Sound Director": "picks a sound for every moment of the game (jump, hit, pick up, win ...)",
+    "Programmer": "writes the game's code (Phaser) from the design and the art, then fixes it "
+    "until the design's checks pass",
+    "QA Playtester": "lets a bot play the game, checks every design check, writes its own code "
+    "tests, records a video of the autoplay",
+    "Art Reviewer": "looks at the art inside the running game and fixes art that is hard to "
+    "read before you see it",
+}
+
+
+class AgentPlan(Contract):
+    agent: str = Field(description="the agent's name, exactly as listed")
+    starts_when: list[str] = Field(description="1-3 points: what must be ready before it starts")
+    tasks: list[str] = Field(description="3-8 steps it will do for THIS game, in order")
+    done_when: list[str] = Field(description="1-3 points: how we know it is finished")
+
+
+class TaskList(Contract):
+    agents: list[AgentPlan]
+
+
+class AgentReport(Contract):
+    agent: str
+    did: list[str]
+    checks: list[tuple[str, bool]]  # an exit gate point and whether the build meets it
+
+
+def clip(text: str) -> str:
+    text = " ".join(str(text).split())
+    return text if len(text) <= POINT else text[: POINT - 1].rstrip() + "…"
+
+
+def names(items, n: int = 4) -> str:
+    items = [str(i) for i in items if str(i).strip()]
+    more = len(items) - n
+    return ", ".join(items[:n]) + (f" and {more} more" if more > 0 else "")
+
+
+def build_agents(design: GameDesign, plan: PlanRecord | None, levels: bool, menus: bool,
+                 sounds: bool, review: bool) -> list[str]:  # fmt: skip
+    """The agents that work on a build, in their working order."""
+    on = {"Level/Tile Designer": levels, "Menu Designer": menus, "Sound Director": sounds,
+          "Art Reviewer": review}  # fmt: skip
+    return [a for a in JOBS if on.get(a, True)]
+
+
+# --- entry: the task list -----------------------------------------------------------------------
+
+
+def default_tasks(design: GameDesign, plan: PlanRecord | None, agents: list[str]) -> TaskList:
+    """A plain plan made from the design (offline runs, and whatever the model left out)."""
+    things = names(e.id.replace("_", " ") for e in design.entities)
+    player = next((e for e in design.entities if e.role == "player"), None)
+    moving = [e for e in design.entities if e.animations]
+    levels = plan.plan.levels if plan else []
+    k = plan.kinematics if plan else None
+    approved = "You approve the game design and this plan (G2)"
+    plans = {
+        "Level/Tile Designer": AgentPlan(
+            agent="Level/Tile Designer",
+            starts_when=[approved, "The game plan lists the levels and the jump numbers"],
+            tasks=[
+                f"Lay out {len(levels)} levels: {names(lv.name for lv in levels)}",
+                *(f"Level {lv.n} teaches: {lv.teaching_goal}" for lv in levels[:3]),
+                (f"Keep every gap under {k.max_gap} tiles and every ledge under {k.max_rise} "
+                 "tiles so each jump can be made") if k else "Check that every jump can be made",
+                "Draw a preview picture of each level",
+            ],
+            done_when=["Every level can be finished", "The bot clears every level"],
+        ),
+        "Art Director": AgentPlan(
+            agent="Art Director",
+            starts_when=[approved],
+            tasks=[
+                f"Plan the art for {len(design.entities)} things: {things}",
+                f"Keep one look for all of it: {design.look}",
+                f"Plan the animations of {len(moving)} moving things" if moving
+                else "Keep every thing still (no animations in the design)",
+                "Make one sheet that shows all the art together",
+            ],
+            done_when=["Every thing in the design has an art plan", "The art sheet is ready"],
+        ),
+        "Pixel Artist": AgentPlan(
+            agent="Pixel Artist",
+            starts_when=["The Art Director's art plan is ready"],
+            tasks=[
+                "Take art from the art library first",
+                "Ask Muse Image to draw the things the library does not have",
+                *(f"Draw the {e.id.replace('_', ' ')}: {e.look}" for e in design.entities[:4]),
+                "Clean every image to the game's palette and size",
+            ],
+            done_when=["Every thing has its art", "No art is missing from the game"],
+        ),
+        "Menu Designer": AgentPlan(
+            agent="Menu Designer",
+            starts_when=[approved, "The art is drawn (the menus use its colours)"],
+            tasks=[
+                "Write the title, pause and game over screens",
+                f"Make the title picture for '{design.title}' with Muse Image",
+                "Take theme colours from the game's art",
+                "Take a screenshot of every screen for you to check",
+            ],
+            done_when=["Every menu screen opens", "The title art is ready"],
+        ),
+        "Sound Director": AgentPlan(
+            agent="Sound Director",
+            starts_when=[approved],
+            tasks=[
+                "List every moment that needs a sound",
+                *[f"When the player sees '{f.event}', play: {f.hear}"
+                  for f in (plan.plan.feel if plan else []) if f.hear.strip()][:4],
+                "Pick a sound for each moment",
+            ],
+            done_when=["Every moment has a sound", "The bot hears each sound in play"],
+        ),
+        "Programmer": AgentPlan(
+            agent="Programmer",
+            starts_when=[approved, "The art is ready"],
+            tasks=[
+                f"Write the game '{design.title}' in Phaser",
+                f"Controls: {design.controls}",
+                *(f"Rule: {r}" for r in design.rules[:3]),
+                f"Show on screen: {names(design.hud, 3)}" if design.hud else "Keep the screen clean",
+                f"How you win: {design.win}",
+                "Fix the code until every check passes",
+            ],
+            done_when=["The game starts with no errors",
+                       f"All {len(design.checks)} checks of the design pass"],
+        ),
+        "QA Playtester": AgentPlan(
+            agent="QA Playtester",
+            starts_when=["The Programmer's game runs"],
+            tasks=[
+                "Let a bot play the game",
+                *(f"Check: {c.description}" for c in design.checks[:3]),
+                "Write my own tests and play them with real key presses",
+                "Record a video of the autoplay for you",
+            ],
+            done_when=["Every check is marked pass or fail", "A video or picture of play is ready"],
+        ),
+        "Art Reviewer": AgentPlan(
+            agent="Art Reviewer",
+            starts_when=["The game runs with its art"],
+            tasks=[
+                "Look at the art inside the running game",
+                f"Check that the {player.id.replace('_', ' ') if player else 'player'} is easy to see",
+                "Fix art that is hard to read before you see it",
+                "List smaller ideas for you as suggestions",
+            ],
+            done_when=["No big art problem is left"],
+        ),
+    }
+    return TaskList(agents=[plans[a] for a in agents])
+
+
+def tasks_prompt(design: GameDesign, plan: PlanRecord | None, agents: list[str]) -> str:
+    jobs = "\n".join(f"- {a}: {JOBS[a]}" for a in agents)
+    return (
+        "Write the team's task list for building this game. One entry per agent below, in this "
+        "order. Write in simple, short words that someone who is not a programmer understands; "
+        "each point is one short sentence (under 20 words).\n"
+        "For each agent: starts_when (1-3 points: what must be ready before it starts), tasks "
+        "(3-8 steps it will do for THIS game, in order, naming the real things of the design: "
+        "its characters, levels, rules and checks), done_when (1-3 points: how we know it is "
+        "finished). Only promise what the agent's job below covers.\n"
+        f"Agents and their jobs:\n{jobs}\n"
+        f"The design:\n{design.model_dump_json()}\n"
+        + (f"The game plan:\n{plan.plan.model_dump_json()}\n" if plan else "")
+    )
+
+
+def fit_tasks(answer: TaskList, fallback: TaskList) -> TaskList:
+    """Only the agents of this build, in working order; what the model left empty comes from
+    the plain plan; every point short."""
+    said = {p.agent.strip().lower(): p for p in answer.agents}
+
+    def pick(got: AgentPlan | None, base: AgentPlan, field: str, most: int) -> list[str]:
+        points = [clip(p) for p in getattr(got, field) if str(p).strip()] if got else []
+        return (points or [clip(p) for p in getattr(base, field)])[:most]
+
+    out = []
+    for base in fallback.agents:
+        got = said.get(base.agent.lower())
+        out.append(AgentPlan(agent=base.agent, starts_when=pick(got, base, "starts_when", 3),
+                             tasks=pick(got, base, "tasks", MAX_TASKS),
+                             done_when=pick(got, base, "done_when", 3)))
+    return TaskList(agents=out)
+
+
+def entry_sections(p: AgentPlan, tools: list[str] = ()) -> list[dict]:
+    """`tools`: the MCP tools and skills the agent can use to look things up."""
+    return [
+        {"title": "Starts when (entry gate)", "points": p.starts_when},
+        {"title": "What I will do", "points": p.tasks, "numbered": True},
+        {"title": "Done when (exit gate)", "points": p.done_when},
+        *([{"title": "Tools and skills I can use", "points": list(tools)}] if tools else []),
+    ]
+
+
+def tasks_markdown(tasks: TaskList, version: int, title: str) -> str:
+    out = [f"# Team plan for design v{version}: {title}",
+           "Each agent's plan. Approve the design (G2) to let them start."]  # fmt: skip
+    for p in tasks.agents:
+        out.append(f"\n## {p.agent}")
+        out += sections_markdown(entry_sections(p))
+    return "\n".join(out) + "\n"
+
+
+def sections_markdown(sections: list[dict]) -> list[str]:
+    out = []
+    for s in sections:
+        out.append(f"\n**{s['title']}**")
+        out += [f"{i + 1}. {p}" if s.get("numbered") else f"- {p}"
+                for i, p in enumerate(s["points"])]  # fmt: skip
+    return out
+
+
+def designer_report(design: GameDesign, plan: PlanRecord | None, research: bool,
+                    tasks: TaskList, version: int) -> AgentReport:  # fmt: skip
+    """The Game Designer's own exit report at G2: what it wrote."""
+    did = []
+    if research:
+        did.append("Studied similar games on the web")
+    if plan:
+        did.append(f"Wrote the game plan with {len(plan.plan.requirements)} of your wishes "
+                   f"and {len(plan.plan.levels)} levels")  # fmt: skip
+    did += [
+        f"Wrote design v{version}: '{design.title}'",
+        f"Listed {len(design.entities)} things: {names(e.id.replace('_', ' ') for e in design.entities)}",
+        f"Wrote {len(design.rules)} rules and {len(design.checks)} checks the game must pass",
+        f"Made a plan for {len(tasks.agents)} agents: {names([p.agent for p in tasks.agents], 8)}",
+    ]
+    checks = [("Every part of the design is filled in", bool(design.entities and design.checks))]
+    if plan:
+        checks.append(("The plan has no problem code could not fix", not plan.problems))
+    return AgentReport(agent="Game Designer", did=[clip(d) for d in did], checks=checks)
+
+
+# --- exit: what each agent did --------------------------------------------------------------------
+
+
+def art_counts(art: list[dict]) -> str:
+    def kind(source: str) -> str:
+        s = source.lower()
+        if "review" in s:
+            return "redrawn by the Art Reviewer"
+        if "reuse" in s or "kept" in s or "locked" in s:
+            return "kept from the last build"
+        if "librar" in s or "tileset" in s:
+            return "from the library"
+        if "placeholder" in s or "greybox" in s:
+            return "greybox (Muse unavailable)"
+        if "muse" in s:
+            return "drawn by Muse Image"
+        return "drawn by code"
+
+    counts = Counter(kind(a.get("source", "")) for a in art)
+    return ", ".join(f"{n} {k}" for k, n in counts.most_common())
+
+
+def exit_reports(report: dict, design: GameDesign) -> list[AgentReport]:
+    """What each agent of the build did, and its exit gate checked by code from report.json."""
+    art = report.get("art", [])
+    checks = report.get("checks", [])
+    ok = sum(1 for c in checks if c.get("ok"))
+    out = []
+    if levels := report.get("levels"):
+        cleared = sum(1 for lv in levels if lv.get("cleared"))
+        out.append(AgentReport(agent="Level/Tile Designer", did=[
+            f"Laid out {len(levels)} levels: {names(lv['name'] for lv in levels)}",
+            (f"Code checked the jumps: {sum(1 for lv in levels if lv.get('solved'))} of "
+             f"{len(levels)} levels can be finished"),
+            "Drew a preview of each level",
+        ], checks=[("Every level can be finished", all(lv.get("solved") for lv in levels)),
+                   (f"The bot clears every level ({cleared}/{len(levels)})", cleared == len(levels))]))  # fmt: skip
+    motion = report.get("motion") or {}
+    out.append(AgentReport(agent="Art Director", did=[
+        f"Planned the art for {len(art)} things",
+        *([f"Planned {len(motion['rows'])} animation rows"] if motion.get("rows") else []),
+        "Made the art sheet that shows all the art together",
+    ], checks=[("Every thing in the design has art",
+                {a["entity"] for a in art} >= {e.id for e in design.entities})]))  # fmt: skip
+    warnings = report.get("warnings", [])
+    out.append(AgentReport(agent="Pixel Artist", did=[
+        f"Made art for {len(art)} things: {art_counts(art)}" if art else "No art was needed",
+        "Cleaned every image to the game's palette and size",
+        *([f"{len(warnings)} warning(s) about the art (see the report)"] if warnings else []),
+    ], checks=[("No art is missing", bool(art)), ("No art warnings", not warnings)]))
+    if menus := report.get("menus"):
+        title = menus.get("title_art") or {}
+        out.append(AgentReport(agent="Menu Designer", did=[
+            f"Made {len(menus.get('screens', []))} menu screens",
+            f"Made the title art ({title.get('source', 'none')})",
+            f"Took the theme colours from the art ({(menus.get('theme') or {}).get('style', 'plain')} style)",
+        ], checks=[("Every menu screen opens", not menus.get("errors")),
+                   ("No menu problem left", not menus.get("problems"))]))  # fmt: skip
+    if sounds := report.get("sounds"):
+        cues, missed = sounds.get("cues", []), sounds.get("never_heard", [])
+        out.append(AgentReport(agent="Sound Director", did=[
+            f"Picked {len(cues)} sounds: {names(c['name'] for c in cues)}",
+            f"The bot heard {len(cues) - len(missed)} of them while playing",
+        ], checks=[("Every moment has a sound", bool(cues)),
+                   ("The bot heard every sound", not missed)]))  # fmt: skip
+    attempts = report.get("attempts", [])
+    out.append(AgentReport(agent="Programmer", did=[
+        f"Wrote the game '{report.get('title', design.title)}'",
+        f"Ran it {len(attempts)} time(s) and fixed it after each failed try" if len(attempts) > 1
+        else "It ran on the first try",
+        f"{ok} of {len(checks)} checks of the design pass",
+        *([f"Still open: {clip(p)}" for p in report.get("problems", [])[:2]]),
+    ], checks=[("The game starts with no errors", bool(report.get("play"))),
+               (f"All checks of the design pass ({ok}/{len(checks)})", bool(report.get("passed")))]))  # fmt: skip
+    qa = report.get("qa") or {}
+    out.append(AgentReport(agent="QA Playtester", did=[
+        "Let a bot play the game",
+        f"Checked {len(checks)} checks: {ok} pass, {len(checks) - ok} fail",
+        *([f"Ran {qa['passed'] + qa['failed']} of my own tests: {qa['passed']} pass"] if qa else []),
+        "Recorded the autoplay for you",
+    ], checks=[("Every check is marked pass or fail", bool(checks)),
+               *([("All my tests pass", not qa.get("failed"))] if qa else [])]))  # fmt: skip
+    if review := report.get("art_review"):
+        issues = review.get("issues", [])
+        fixed = sum(1 for i in issues if i.get("status") == "fixed")
+        blocking = sum(1 for i in issues if i.get("severity") == "blocking" and i.get("status") != "fixed")
+        out.append(AgentReport(agent="Art Reviewer", did=[
+            "Looked at the art inside the running game",
+            f"Found {len(issues)} issue(s) and fixed {fixed}",
+            *([f"{len(issues) - fixed} smaller idea(s) are suggestions for you"] if len(issues) > fixed else []),
+        ], checks=[(f"No big art problem left ({blocking} left)", not blocking)]))  # fmt: skip
+    return [r.model_copy(update={"did": [clip(d) for d in r.did]}) for r in out]
+
+
+def looked_up(tools: list[str]) -> str:
+    counts = Counter(tools)
+    return clip(f"Looked things up {len(tools)} time(s) with my tools: "
+                + ", ".join(f"{t} ×{n}" if n > 1 else t for t, n in counts.most_common()))
+
+
+def exit_sections(r: AgentReport) -> list[dict]:
+    return [
+        {"title": "What I did", "points": r.did},
+        {"title": "Exit gate (checked by code)",
+         "points": [("✅ " if met else "⚠️ ") + text for text, met in r.checks]},
+    ]
+
+
+def team_markdown(reports: list[AgentReport], version: int, title: str) -> str:
+    out = [f"# Team report for build v{version}: {title}", "What each agent did, point by point."]
+    for r in reports:
+        out.append(f"\n## {r.agent}")
+        out += sections_markdown(exit_sections(r))
+    return "\n".join(out) + "\n"
+
+
+def payload(stage: str, title: str, sections: list[dict], key: str) -> dict:
+    """The `agent.report` event an agent's chat shows as a report card."""
+    return {"stage": stage, "title": title, "sections": sections, "key": key}

spriteforge/game/tilesets.py

@@ -0,0 +1,70 @@
+"""Tile sets: named tiles cut from installed tileset sheets, with seasonal variants and parallax.
+
+One JSON per tile set in `library/tilesets/` (see its README): which pack and sheet, the camera
+it is drawn for, its tile size, and named tiles (`floor`, `wall`, `ground_top`, ...) at grid
+cells. A tile set is offered only when its pack is installed. Tiles are referred to as
+`<tileset>/<tile>` (e.g. `pixel-crawler-dungeon/floor`).
+"""
+
+import json
+from pathlib import Path
+
+from PIL import Image
+
+from spriteforge.library.store import library_root, search
+
+TILESETS_DIR = Path(__file__).parents[1] / "library" / "tilesets"
+
+
+def load_tilesets(camera: str = "") -> list[dict]:
+    """Installed tile sets, optionally only those drawn for `camera` (top-down/side-view)."""
+    out = []
+    for path in sorted(TILESETS_DIR.glob("*.json")):
+        ts = json.loads(path.read_text(encoding="utf-8"))
+        if (library_root() / ts["pack"]).exists() and (not camera or ts["camera"] == camera):
+            out.append(ts)
+    return out
+
+
+def tile_ids(tilesets: list[dict]) -> dict[str, tuple[dict, str]]:
+    return {f"{ts['id']}/{name}": (ts, name) for ts in tilesets for name in ts["tiles"]}
+
+
+def pick_variant(ts: dict, text_words: set[str]) -> str:
+    return next(
+        (v for v, spec in ts["variants"].items() if text_words & set(spec["words"])), "normal"
+    )
+
+
+def _asset_file(asset_id: str) -> Path:
+    return library_root() / next(a["file"] for a in search() if a["id"] == asset_id)
+
+
+def tile_image(ts: dict, name: str, variant: str = "normal") -> Image.Image:
+    """One tile at the tile set's native size."""
+    spec = ts["tiles"][name]
+    size = ts["tile_size"]
+    sheet = Image.open(_asset_file(spec["asset"])).convert("RGBA")
+    cx, cy = spec["cell"]
+    if spec.get("seasonal"):
+        cy += ts["variants"].get(variant, ts["variants"]["normal"])["row_offset"]
+    tile = sheet.crop((cx * size, cy * size, cx * size + size, cy * size + size))
+    if spec.get("flip_y"):
+        tile = tile.transpose(Image.Transpose.FLIP_TOP_BOTTOM)
+    return tile
+
+
+def backdrop_layers(ts: dict, variant: str = "normal") -> list[tuple[str, Image.Image, float]]:
+    """Parallax layers back to front as (name, image, scroll factor); [] without a backdrop."""
+    spec = ts.get("backdrop")
+    if not spec:
+        return []
+    files = {a["id"]: a["file"] for a in search()}
+    tag = ts["variants"].get(variant, {}).get("backdrop", "normal-bg")
+    layers = []
+    for i, (layer, factor) in enumerate(zip(spec["layers"], spec["factors"], strict=True)):
+        asset = spec["asset_pattern"].format(variant=tag, layer=layer)
+        if asset in files:
+            image = Image.open(library_root() / files[asset]).convert("RGBA")
+            layers.append((f"backdrop_{i}", image, factor))
+    return layers

spriteforge/game/title_art.py

@@ -0,0 +1,186 @@
+"""The title art (L2.5): a background picture behind the title and main screens and an emblem
+over the game's title, drawn by Muse Image in the style of the game's locked art (two calls),
+cleaned and checked by the pixel tools. Muse never draws text: the SDK draws every word.
+
+Style references are only art Muse drew for this game (library art, whatever its licence,
+is never sent). Accepted title art is locked: a later build reuses it unless the menus'
+descriptions of it change. Offline, when the calls fail or a picture fails its checks, code
+draws it from the game's own art: a panel in the theme's colours with the ground tile along
+the bottom, and the player sprite enlarged as the emblem.
+"""
+
+import io
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+import numpy as np
+from PIL import Image
+
+from spriteforge.pixel.schemas import ProcessingOptions, ProcessingReport
+from spriteforge.pixel.source import key_background, mode_resize
+from spriteforge.providers.base import ImageRequest
+
+from .art import ArtResult, limit_palette, png
+from .design import GameDesign
+from .menus import MenuSpec, mix
+
+BACKGROUND_SIZE, EMBLEM_SIZE = (1792, 1024), (1024, 1024)
+EMBLEM_BOX = 56  # px at scale 1: the emblem's longest side
+
+
+@dataclass
+class TitleArt:
+    title: bytes  # PNG at the screen's size
+    emblem: bytes  # PNG with transparency
+    source: str  # "muse", "muse (locked, from vN)", "code-drawn: <why>"
+    prompts: dict = field(default_factory=dict)  # {"title": ..., "emblem": ...}
+    notes: list[str] = field(default_factory=list)
+    raw: dict = field(default_factory=dict)  # Muse's pictures before cleaning
+    version: int = 0  # the build that made it (0: not built yet)
+
+    def record(self) -> dict:
+        return {"source": self.source, "prompts": self.prompts, "notes": self.notes,
+                "version": self.version}
+
+
+def prompts(spec: MenuSpec, design: GameDesign) -> dict:
+    style = (f"Match the pixel size, outlines, shading and palette of the reference sprites "
+             f"exactly. Art direction: {design.look}.")  # fmt: skip
+    return {
+        "title": (f"Pixel art title-screen background for the 2D {design.camera} game "
+                  f"'{design.title}': {spec.title_art}. Wide landscape scene, chunky readable "
+                  f"pixels, a calm darker area across the upper middle where a title will be "
+                  f"placed. {style} No text, no letters, no numbers, no logo, no UI, no border."),
+        "emblem": (f"A single pixel art emblem for the game '{design.title}': {spec.emblem}. "
+                   f"One centred subject, bold outline, on a plain flat magenta background "
+                   f"(#FF00FF) that touches nothing. {style} No text, no letters, no numbers."),
+    }  # fmt: skip
+
+
+def references(art: ArtResult) -> list[bytes]:
+    """Up to two of the game's own Muse sprites (the player first), enlarged for Muse."""
+    muse = [(eid, f) for eid, f in art.filled.items() if f.source.startswith("muse")]
+    muse.sort(key=lambda kv: kv[1].meta.get("role") != "player")
+    out = []
+    for _, f in muse[:2]:
+        img = Image.open(io.BytesIO(f.png)).convert("RGBA")
+        frame = f.meta.get("frame") if f.kind == "sprite" else None
+        if frame:
+            img = img.crop((0, 0, int(frame[0]), int(frame[1])))
+        k = max(1, 256 // max(img.size))
+        out.append(png(img.resize((img.width * k, img.height * k), Image.NEAREST)))
+    return out
+
+
+def clean_background(raw: bytes, screen: tuple[int, int]) -> tuple[Image.Image, list[str]]:
+    img = Image.open(io.BytesIO(raw)).convert("RGBA")
+    w, h = screen
+    scale = max(w / img.width, h / img.height)
+    size = (max(w, round(img.width * scale)), max(h, round(img.height * scale)))
+    img = mode_resize(img, size)
+    left, top = (img.width - w) // 2, (img.height - h) // 2
+    img = limit_palette(img.crop((left, top, left + w, top + h)), 32)
+    problems = []
+    luma = np.asarray(img.convert("L"), dtype=float) / 255
+    if luma.std() < 0.03:
+        problems.append("the background is one flat colour")
+    return img, problems
+
+
+def clean_emblem(raw: bytes, box: int) -> tuple[Image.Image, list[str]]:
+    img = key_background(Image.open(io.BytesIO(raw)), ProcessingOptions(), ProcessingReport())
+    alpha = np.asarray(img)[..., 3]
+    problems = []
+    if not alpha.any():
+        return img, ["the emblem came back empty after removing its background"]
+    if (alpha > 0).mean() > 0.9:  # nothing was keyed: the subject is on a picture, not a plain ground
+        problems.append("the emblem kept its background (no plain ground to remove)")
+    ys, xs = np.nonzero(alpha)
+    img = img.crop((int(xs.min()), int(ys.min()), int(xs.max()) + 1, int(ys.max()) + 1))
+    k = box / max(img.size)
+    img = mode_resize(img, (max(1, round(img.width * k)), max(1, round(img.height * k))))
+    img = limit_palette(img, 16)
+    filled = float((np.asarray(img)[..., 3] > 0).mean())
+    if filled < 0.08:
+        problems.append("the emblem is mostly empty")
+    return img, problems
+
+
+def code_drawn(spec: MenuSpec, art: ArtResult, why: str) -> TitleArt:
+    """The title art drawn by code from the game's art and the theme's colours."""
+    w, h = art.screen
+    top, bottom = spec.theme.panel, mix(spec.theme.panel, spec.theme.border, 0.35)
+    rows = [np.array([int(mix(top, bottom, y / max(1, h - 1))[i:i + 2], 16) for i in (1, 3, 5)] + [255],
+                     dtype=np.uint8) for y in range(h)]  # fmt: skip
+    canvas = Image.fromarray(np.repeat(np.stack(rows)[:, None, :], w, axis=1))
+    tile = next((f for f in art.filled.values() if f.meta.get("role") == "tile" and f.kind == "image"), None)
+    if tile:
+        t = Image.open(io.BytesIO(tile.png)).convert("RGBA")
+        ground = h - t.height
+        for x in range(0, w, t.width):
+            canvas.alpha_composite(t, (x, ground))
+    player = next((f for f in art.filled.values() if f.meta.get("role") == "player"), None)
+    if player:
+        img = Image.open(io.BytesIO(player.png)).convert("RGBA")
+        frame = player.meta.get("frame") if player.kind == "sprite" else None
+        if frame:
+            img = img.crop((0, 0, int(frame[0]), int(frame[1])))
+        k = max(1, (EMBLEM_BOX * art.scale) // max(img.size))
+        emblem = img.resize((img.width * k, img.height * k), Image.NEAREST)
+    else:
+        emblem = Image.new("RGBA", (8, 8), (0, 0, 0, 0))
+    return TitleArt(png(canvas), png(emblem), f"code-drawn: {why}")
+
+
+Generate = Callable[[ImageRequest, bool], bytes]
+
+
+def make_title_art(spec: MenuSpec, design: GameDesign, art: ArtResult,
+                   generate: Generate | None, cache=None,
+                   previous: TitleArt | None = None) -> TitleArt:  # fmt: skip
+    """Muse's title art for `spec`, or the locked `previous` when its descriptions are the
+    same, or code's when there is no image model (`generate` None) or the pictures fail."""
+    asked = prompts(spec, design)
+    if previous is not None and previous.prompts == asked and previous.source.startswith("muse"):
+        return previous
+    if generate is None:
+        offline = code_drawn(spec, art, "offline (no image model)")
+        offline.prompts = asked  # what an image model would be asked (a later build may draw it)
+        return offline
+    refs = references(art)
+    raw, notes = {}, []
+    for part, size in (("title", BACKGROUND_SIZE), ("emblem", EMBLEM_SIZE)):
+        request = ImageRequest(prompt=asked[part], size=size, references=refs)
+        edit = bool(refs)
+        try:
+            hit = cache.get(request, edit) if cache else None
+            raw[part] = hit if hit is not None else generate(request, edit)
+            if hit is None and cache:
+                cache.put(request, edit, raw[part])
+        except Exception as exc:  # noqa: BLE001 -- the title art falls back to code's
+            notes.append(f"Muse could not draw the {part} art ({type(exc).__name__}: {str(exc)[:160]})")
+    drawn = code_drawn(spec, art, "the Muse pictures failed their checks")
+    title, emblem = None, None
+    if "title" in raw:
+        img, problems = clean_background(raw["title"], art.screen)
+        notes += [f"title background: {p}" for p in problems]
+        title = None if problems else png(img)
+    if "emblem" in raw:
+        img, problems = clean_emblem(raw["emblem"], EMBLEM_BOX * art.scale)
+        notes += [f"emblem: {p}" for p in problems]
+        emblem = None if problems else png(img)
+    if title is None and emblem is None:
+        return TitleArt(drawn.title, drawn.emblem, drawn.source, asked, notes, raw)
+    source = "muse" if title and emblem else "muse (" + ("background" if title else "emblem") + "; the other code-drawn)"
+    return TitleArt(title or drawn.title, emblem or drawn.emblem, source, asked, notes, raw)
+
+
+def manifest_images(t: TitleArt) -> tuple[dict, dict[str, bytes]]:
+    """assets.json image entries (role "menu": the SDK's, not the Programmer's) and files."""
+    out, files = {}, {}
+    for ident, data in (("sf_title_art", t.title), ("sf_emblem", t.emblem)):
+        w, h = Image.open(io.BytesIO(data)).size
+        out[ident] = {"file": f"assets/{ident}.png", "role": "menu", "size": [w, h],
+                      "source": t.source}  # fmt: skip
+        files[f"assets/{ident}.png"] = data
+    return out, files

spriteforge/library/__init__.py

@@ -0,0 +1,15 @@
+"""Third-party pixel-art library: ingested packs with per-pack license tracking."""
+
+from .models import AssetEntry, Pack
+from .store import add_pack, asset_path, library_root, load_packs, search, set_license
+
+__all__ = [
+    "AssetEntry",
+    "Pack",
+    "add_pack",
+    "asset_path",
+    "library_root",
+    "load_packs",
+    "search",
+    "set_license",
+]