ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/editor/battle_forms.py

@@ -0,0 +1,240 @@
+"""Form specs for the Battle document (ENCOUNTER-FIRST), reusing the field editor's tk-free spec machinery
+(:mod:`ff9mapkit.editor.forms` -- the :class:`~ff9mapkit.editor.forms.Field` dataclass, the field kinds, and
+``build_entity`` / ``entity_to_values``).
+
+A ``battle.toml`` is authored as an ENCOUNTER, not a loose enemy (the engine itself enforces this: a scene IS
+a formation, and per-slot edits only apply once ``[scene] monster_count`` composes the formation). The three
+specs here mirror that:
+
+* :data:`BATTLEMAP_SPEC` -- ``[battlemap]``: the map's identity (the BBG slot it ships as, its geometry, and
+  the mint/repoint scene wiring).
+* :data:`SCENE_SPEC` -- ``[scene]``: the FORMATION (how many enemies, the opening camera, the AP reward).
+* :data:`ENEMY_SPEC` -- ``[[scene.enemy]]``: one formation SLOT's enemy -- identity & stats, element/status
+  affinities, rewards, placement, and a model re-skin.
+
+The scalar stats are int fields; the element/status/drop/flags lists are :data:`~forms.STRLIST` (the same
+comma-separated name list ``[party]`` uses); placement is a :data:`~forms.COORD`. The player-side CSV tuning
+tables (``[[battle_action]]`` / ``[[status]]`` / ``[[character]]`` / ...) are a SEPARATE, scene-independent
+spec set (now wired -- see :data:`PLAYER_TABLES`); they don't belong on a per-enemy slot. The high-level AI
+branch (:data:`AI_PHASE_SPEC`) and the SAME-LENGTH constant patches (:data:`AI_PATCH_SPEC` /
+:data:`SEQ_PATCH_SPEC`, the "cite an offset" tier) have flat specs here; the length-CHANGING authoring
+(``ai_function`` / ``ai_insert`` / ``seq_replace`` / ``seq_insert``) stays CLI-only (the disassemble/splice tier).
+"""
+from __future__ import annotations
+
+from .forms import COORD, FLOAT, INT, OPTINT, STR, STRLIST, Field
+
+# [[scene.ai_phase]] -- a high-level "enrage below X% stat" AI branch (aiauthor.apply_ai_phases GENERATES the
+# HP-threshold branch + splices it before the function's Attack). Flat: the attack-index variable is inferred,
+# so the author only gives the entry/function + the threshold + the two attack indices.
+AI_PHASE_SPEC = [
+    Field("entry", "Enemy AI entry", INT,
+          "the .eb AI entry for the enemy type (often 1 + the slot's type; `battle-ai <donor>` lists them)"),
+    Field("tag", "AI function", INT, "which AI function has the single Attack — the readout's 'Enrage-able' line "
+          "shows it (usually 5, the per-turn attack executor; 1=Main, 6=Counter, 7=ATB, 9=Dying)"),
+    Field("stat", "Threshold stat", STR, "hp / mp / at (default hp)"),
+    Field("below", "Enrage below", FLOAT, "a unit fraction 1/N: 0.5 = half, 0.25 = quarter, 0.2 = a fifth (default 0.5)"),
+    Field("then", "Attack when below", INT, "enemy_attack[] index used WHILE below the threshold (the enrage move)"),
+    Field("else", "Attack when above", INT, "enemy_attack[] index used while ABOVE the threshold (the normal move)"),
+]
+
+# [[scene.ai_patch]] -- a SAME-LENGTH enemy-AI constant patch (aipatch.apply_ai_patches): rewrite ONE numeric
+# literal in the AI bytecode in place -- an HP threshold a phase compares, the attack index a turn selects, a
+# `Wait` count -- with no byte movement. Addressed by BYTE OFFSET (from `battle-ai --sites`, or the form's
+# "Browse sites…" picker) + an OLD-value guard so a stale offset fails LOUD instead of corrupting a byte. The
+# bytecode is language-identical, so one patch hits every language's eb.
+AI_PATCH_SPEC = [
+    Field("at", "Offset", INT, "the byte offset of the AI constant — use 'Browse sites…' (or `battle-ai --sites`)"),
+    Field("old", "Current value", INT, "the value the eb has there NOW — the guard (Browse sites… fills it)"),
+    Field("new", "New value", INT, "the value to write (must fit the SAME byte width — a literal patch can't widen)"),
+]
+
+# [[scene.seq_patch]] -- a SAME-LENGTH raw17 attack-CHOREOGRAPHY operand patch (seqpatch.apply_seq_patches):
+# retime a `Wait` / `MoveTo*` frame count, swap an `Anim` code or a `SetCamera` id, in place. Byte OFFSET (from
+# `battle-seq --sites`, or "Browse sites…") + an OLD guard; `seq` is the optional owning attack/sub index (a
+# cross-check the picker pre-fills, NOT required). raw17 is language-independent, so the patch applies once.
+SEQ_PATCH_SPEC = [
+    Field("at", "Offset", INT, "the byte offset of the sequence operand — use 'Browse sites…' (or `battle-seq --sites`)"),
+    Field("old", "Current value", INT, "the value the raw17 has there NOW — the guard (Browse sites… fills it)"),
+    Field("new", "New value", INT, "the value to write (must fit the SAME field width + signedness)"),
+    Field("seq", "Owning attack", OPTINT, "optional cross-check: the attack/sub index that owns this operand"),
+]
+
+# [battlemap] -- the map identity (validate_battle: bbg is required + must look like BBG_B013; scene_id needs
+# scene_name; scene_id (mint) and repoint_scene are mutually exclusive; char_tint/shadow are cosmetic).
+BATTLEMAP_SPEC = [
+    Field("bbg", "Background slot", STR,
+          "the BBG_* slot this map ships as, e.g. BBG_B013 (= the forked slot to OVERRIDE that real map)"),
+    Field("fbx", "Geometry (.fbx)", STR, "the FBX geometry file in this folder (default <bbg>.fbx)"),
+    Field("repoint_scene", "Repoint scene id", OPTINT,
+          "point an EXISTING battle scene's background at this map (mutually exclusive with a mint)"),
+    Field("scene_id", "Mint scene id", OPTINT, "advanced: a NEW battle-scene id to mint (needs a scene name)"),
+    Field("scene_name", "Mint scene name", STR, "advanced: the new scene's name (pair with the mint id)"),
+    Field("char_tint", "Char tint (r, g, b)", STRLIST,
+          "RGB the engine lights party/enemies with on this map (0-255 each; default 128, 128, 128)"),
+    Field("shadow", "Shadow", OPTINT, "shadow intensity 0-255 (default 32)"),
+]
+
+# [scene] -- the FORMATION. monster_count is the keystone: it recomposes every pattern and unlocks per-slot
+# editing, so it reads first in the form. `flags` are the encounter RULES (header scene_flags); the camera_*
+# floats nudge the OPENING-camera pose (raw17, in place). The AI / sequence edits live in their own sibling
+# tables ([[scene.ai_phase]] / [[scene.ai_patch]] / [[scene.seq_patch]]), not on this form; full camera
+# keyframes + the length-changing ai_*/seq_* authoring stay CLI-only.
+SCENE_SPEC = [
+    Field("monster_count", "Monster count", OPTINT,
+          "how many enemies spawn (1-4) -- SET THIS to compose the formation + unlock per-slot edits"),
+    Field("camera", "Camera", OPTINT, "opening camera: 0-2 = a fixed PSX pose, >=3 = random"),
+    Field("ap", "AP reward", OPTINT, "the gameplay AP this fight awards"),
+    Field("pattern", "Pattern", OPTINT, "which formation pattern to tune (default 0)"),
+    Field("flags", "Encounter rules", STRLIST,
+          "scene RULES (any of): back_attack, preemptive, no_escape, no_exp -- absent keeps the donor's"),
+    Field("camera_yaw", "Camera yaw °", FLOAT, "rotate the opening camera by this many degrees (+/-, default 0)"),
+    Field("camera_pitch", "Camera pitch °", FLOAT, "tilt the opening camera by this many degrees (+/-, default 0)"),
+    Field("camera_zoom", "Camera zoom ×", FLOAT, "magnify the opening camera (>1 zooms IN, <1 zooms OUT; 1.0 = unchanged)"),
+]
+
+# [[scene.enemy]] -- one formation slot's enemy. Stats are per-TYPE: two slots sharing a type share ALL stats.
+ENEMY_SPEC = [
+    Field("slot", "Slot", INT, "the formation slot 0-3 (required)"),
+    Field("type", "Type", OPTINT, "the enemy TYPE to place here (must already exist in the scene)"),
+    # identity & stats (all per-type, 0-255 unless noted)
+    Field("hp", "HP", OPTINT, "max HP (0-65535)"),
+    Field("mp", "MP", OPTINT, "max MP (0-65535)"),
+    Field("speed", "Speed", OPTINT, "0-255"),
+    Field("strength", "Strength", OPTINT, "0-255"),
+    Field("magic", "Magic", OPTINT, "0-255"),
+    Field("spirit", "Spirit", OPTINT, "0-255"),
+    Field("level", "Level", OPTINT, "0-255 (drives variance, steal, Level-N spells)"),
+    Field("category", "Category", OPTINT, "race/killer/flight/undead category bits (0-255)"),
+    Field("hit_rate", "Hit rate", OPTINT, "physical accuracy (0-255)"),
+    Field("phys_def", "Phys. defence", OPTINT, "0-255"),
+    Field("phys_evade", "Phys. evade", OPTINT, "0-255"),
+    Field("mag_def", "Mag. defence", OPTINT, "0-255"),
+    Field("mag_evade", "Mag. evade", OPTINT, "0-255"),
+    Field("blue_magic", "Blue magic id", OPTINT, "the Quina Eat / Blue-magic learn id"),
+    # affinities (element / status NAME lists)
+    Field("null", "Null elements", STRLIST, "elements this enemy is IMMUNE to, e.g. Fire, Ice"),
+    Field("absorb", "Absorb elements", STRLIST, "elements this enemy ABSORBS (heals from)"),
+    Field("half", "Halve elements", STRLIST, "elements this enemy takes HALF from"),
+    Field("weak", "Weak elements", STRLIST, "elements this enemy is WEAK to"),
+    Field("resist_status", "Resist status", STRLIST, "statuses this enemy resists, e.g. Poison, Sleep"),
+    Field("auto_status", "Auto status", STRLIST, "statuses always active on this enemy"),
+    Field("initial_status", "Initial status", STRLIST, "statuses on this enemy at battle start"),
+    # rewards
+    Field("gil", "Gil", OPTINT, "gil awarded (0-65535)"),
+    Field("exp", "EXP", OPTINT, "EXP awarded (0-65535)"),
+    Field("drop", "Drops (4 items)", STRLIST, 'win items: 4 entries (name/id; "none" for an empty slot)'),
+    Field("steal", "Steals (4 items)", STRLIST, 'stealable items: 4 entries (name/id; "none" for empty)'),
+    Field("win_card", "Win card", OPTINT, "the Tetra Master card id awarded"),
+    Field("flags", "Flags", STRLIST, "behaviour flags: die_atk, die_dmg, non_dying_boss"),
+    # placement
+    Field("pos", "Position (x, z)", COORD, "where this enemy stands in the formation"),
+    Field("y", "Height (y)", OPTINT, "vertical placement offset"),
+    Field("rot", "Rotation", OPTINT, "facing rotation"),
+    # re-skin (visual transplant)
+    Field("model", "Re-skin model id", OPTINT, "advanced: borrow another enemy TYPE's model + animations"),
+    Field("model_scene", "Re-skin donor scene", STR, "advanced: a donor battle scene to borrow a model from"),
+    Field("model_type", "Re-skin donor type", OPTINT, "advanced: which type in the donor scene to borrow"),
+    Field("ai_entry", "AI entry", OPTINT, "advanced: explicit AI entry for this slot (needs monster_count)"),
+]
+
+
+# ===== PLAYER / ABILITY tuning ==========================================================================
+# Mod-GLOBAL CSV deltas a battle.toml may ALSO carry (the same blocks a field.toml can -- see
+# ``ff9mapkit.battle.build.player_csv_problems`` / ``_emit_player_data``), so a battle fork tunes the PARTY
+# that fights it in the SAME deployable doc. Each spec is FLAT over the existing field kinds; the FIRST field
+# is the row "selector" (the tree label). The values name->id + base-CSV merge happens at build (which has the
+# install); these specs only shape the override. Nested / multiline / list tables -- ``[[learn]]`` (sub-tables),
+# ``[[ability_feature]]`` (a code body), ``[[status_set]]`` / ``[[magic_sword_set]]`` (offline list bundles) --
+# stay build-supported + hand-authorable; they're out of the v1 forms (a later sub-increment).
+
+# [[character]] -> BaseStats.csv (per-character base stats). The canonical CHARACTER_FIELDS keys.
+CHARACTER_SPEC = [
+    Field("character", "Character", STR, "name (Zidane..Beatrix) or a 0-11 id"),
+    Field("strength", "Strength", OPTINT, "base Strength 0-255"),
+    Field("magic", "Magic", OPTINT, "base Magic 0-255"),
+    Field("dexterity", "Dexterity", OPTINT, "base Dexterity 0-255"),
+    Field("will", "Will (Spirit)", OPTINT, "base Will / Spirit 0-255"),
+    Field("gems", "Magic stones", OPTINT, "starting Gems / magic-stone count"),
+]
+
+# [[battle_action]] -> Actions.csv (rebalance a shared player ability). The common scalar levers; the
+# targeting BOOLEANS + vfx ids stay hand-authorable (a delta omits an unchecked bool, which can't express
+# "turn this OFF", so the form would silently fail to override it -- see build_entity's BOOL rule).
+BATTLE_ACTION_SPEC = [
+    Field("action", "Ability", STR, "name (e.g. Fire) or a 0-191 id"),
+    Field("power", "Power", OPTINT, "base damage/heal power"),
+    Field("element", "Elements", STRLIST, "element names, e.g. Fire, Ice (sets the element bitmask)"),
+    Field("rate", "Rate / accuracy", OPTINT, "the action's hit/status rate"),
+    Field("mp", "MP cost", OPTINT, "MP the ability costs"),
+    Field("category", "Category", OPTINT, "ability category bits (0-255)"),
+    Field("type", "Type", OPTINT, "ability type (0-255)"),
+    Field("status_index", "Status set", OPTINT, "the StatusSets.csv row this action inflicts/cures"),
+]
+
+# [[status]] -> StatusData.csv (retune an ailment).
+STATUS_SPEC = [
+    Field("status", "Status", STR, "name (e.g. Poison) or a 0-32 id"),
+    Field("tick", "Per-tick effect", OPTINT, "OprCount: the per-tick magnitude 0-255"),
+    Field("duration", "Duration", OPTINT, "ContiCount: 0 = until cured (0-65535)"),
+    Field("clear_on_apply", "Clears on apply", STRLIST, "statuses applying this one CLEARS, e.g. Sleep"),
+    Field("immunity_provided", "Grants immunity to", STRLIST, "statuses this one blocks while active"),
+]
+
+# [[ability_gem]] -> AbilityGems.csv (the support-ability gem COST).
+ABILITY_GEM_SPEC = [
+    Field("ability", "Support ability", STR, "name (e.g. Auto-Haste / AutoHaste) or a 0-63 id"),
+    Field("gems", "Gem cost", OPTINT, "magic stones to equip it"),
+]
+
+# [[character_param]] -> CharacterParameters.csv (per-character menu/row/preset wiring).
+CHARACTER_PARAM_SPEC = [
+    Field("character", "Character", STR, "name (Zidane..Beatrix) or a 0-11 id"),
+    Field("row", "Front/back row", OPTINT, "0 = front, 1 = back (0-255)"),
+    Field("win_pose", "Win pose", OPTINT, "victory-pose id (0-255)"),
+    Field("category", "Category", OPTINT, "category bits (0-255)"),
+    Field("menu_type", "Menu preset", STR, "a CharacterPresetId name (e.g. Steiner) or a 0-19 id"),
+    Field("equipment_set", "Equipment set", OPTINT, "which equipment set governs this character (0-255)"),
+    Field("serial_formula", "Serial formula", STR, "advanced: the serial-stat formula string"),
+    Field("name_keyword", "Name keyword", STR, "advanced: the name-resolution keyword string"),
+]
+
+# [[command_set]] -> CommandSets.csv (re-point a character's battle-menu command SLOTS to BattleCommandIds).
+COMMAND_SET_SPEC = [
+    Field("preset", "Character preset", STR, "a CharacterPresetId name (e.g. Zidane) or a 0-19 id"),
+    Field("attack", "Attack", OPTINT, "BattleCommandId 0-47"),
+    Field("defend", "Defend", OPTINT, "BattleCommandId 0-47"),
+    Field("ability1", "Ability 1", OPTINT, "BattleCommandId 0-47"),
+    Field("ability2", "Ability 2", OPTINT, "BattleCommandId 0-47"),
+    Field("item", "Item", OPTINT, "BattleCommandId 0-47"),
+    Field("change", "Change", OPTINT, "BattleCommandId 0-47"),
+    Field("attack_trance", "Attack (Trance)", OPTINT, "BattleCommandId 0-47"),
+    Field("defend_trance", "Defend (Trance)", OPTINT, "BattleCommandId 0-47"),
+    Field("ability1_trance", "Ability 1 (Trance)", OPTINT, "BattleCommandId 0-47"),
+    Field("ability2_trance", "Ability 2 (Trance)", OPTINT, "BattleCommandId 0-47"),
+    Field("item_trance", "Item (Trance)", OPTINT, "BattleCommandId 0-47"),
+    Field("change_trance", "Change (Trance)", OPTINT, "BattleCommandId 0-47"),
+]
+
+# [[leveling]] -> Leveling.csv (the per-level growth curve; WHOLE-FILE re-emit, patched by level).
+LEVELING_SPEC = [
+    Field("level", "Level", INT, "1-99 (the level this row tunes)"),
+    Field("exp", "EXP to next", OPTINT, "experience to the NEXT level (UInt32)"),
+    Field("bonus_hp", "Bonus HP", OPTINT, "HP grows BonusHP*Strength/50 (UInt16)"),
+    Field("bonus_mp", "Bonus MP", OPTINT, "MP grows BonusMP*Magic/100 (UInt16)"),
+]
+
+# the v1 "Party & abilities" tree branch: ordered (key, label, spec, selector_key, default_entry).
+PLAYER_TABLES = [
+    ("character", "Character stats", CHARACTER_SPEC, "character", {"character": "Zidane"}),
+    ("battle_action", "Ability rebalance", BATTLE_ACTION_SPEC, "action", {"action": "Fire"}),
+    ("status", "Status ailment", STATUS_SPEC, "status", {"status": "Poison"}),
+    ("ability_gem", "Ability gem cost", ABILITY_GEM_SPEC, "ability", {"ability": "Auto-Haste"}),
+    ("character_param", "Character params", CHARACTER_PARAM_SPEC, "character", {"character": "Zidane"}),
+    ("command_set", "Battle command set", COMMAND_SET_SPEC, "preset", {"preset": "Zidane"}),
+    ("leveling", "Leveling curve", LEVELING_SPEC, "level", {"level": 1}),
+]
+PLAYER_SPECS = {k: spec for (k, _l, spec, _s, _d) in PLAYER_TABLES}
+PLAYER_LABEL = {k: lbl for (k, lbl, _sp, _s, _d) in PLAYER_TABLES}
+PLAYER_SELECTOR = {k: sel for (k, _l, _sp, sel, _d) in PLAYER_TABLES}
+PLAYER_DEFAULT = {k: dict(d) for (k, _l, _sp, _s, d) in PLAYER_TABLES}

ff9mapkit/editor/breadcrumb.py

@@ -0,0 +1,89 @@
+"""A clickable breadcrumb -- the GUI's "you are here" across the game-data hierarchy.
+
+The kit's data forms a containment hierarchy -- a JOURNEY (a playable arc) contains CAMPAIGNS, a
+campaign contains FIELDS, a field contains OBJECTS (NPCs/gateways/events/the player & party). Today
+that depth is split across windows; this widget renders the full resolved path as one line of
+clickable segments (``◆ Dali Arc  ▸  ▣ Dali chain  ▸  ● DALI_INN  ▸  ▸ NPC: Innkeeper``) so a user
+always reads, in plain words, where they are -- and clicking any ancestor segment navigates up to it.
+
+Same discipline as :mod:`.theme` / :mod:`.feedback`: the data layer (``Crumb`` + :func:`trail`) is
+tk-FREE and unit-testable; the only Tk lives in :class:`Breadcrumb`, which imports tkinter lazily.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# the four containment-spine levels, outermost -> innermost, with a leading glyph (matches the navigator
+# badges). BATTLE / SAVE are the two OFF-spine doc families -- a battle.toml is a referenced SIBLING of a
+# field, a save doc is ORTHOGONAL game state -- so the breadcrumb can name them on their own tabs too.
+JOURNEY, CAMPAIGN, FIELD, OBJECT = "journey", "campaign", "field", "object"
+HUB = "hub"                                   # the journeys.toml root (the CONTAINER of journeys, above a journey)
+BATTLE, SAVE = "battle", "save"
+GLYPH = {HUB: "⌂", JOURNEY: "◆", CAMPAIGN: "▣", FIELD: "●", OBJECT: "▸", BATTLE: "⚔", SAVE: "◈"}
+
+
+@dataclass(frozen=True)
+class Crumb:
+    """One breadcrumb segment: its hierarchy ``level``, the ``label`` shown, and a ``key`` the click
+    handler uses to navigate (a member name for a field, a tree iid for an object, a sentinel for the
+    journey/campaign roots)."""
+
+    level: str
+    label: str
+    key: str = ""
+
+
+def trail(journey=None, campaign=None, field=None, obj_label=None, obj_key="") -> list:
+    """Build the ordered :class:`Crumb` list from whatever levels are currently resolved (each is
+    optional; an unopened level is simply omitted, so the trail grows as the user drills in)."""
+    out = []
+    if journey:
+        out.append(Crumb(JOURNEY, journey, "@journey"))
+    if campaign:
+        out.append(Crumb(CAMPAIGN, campaign, "@campaign"))
+    if field:
+        out.append(Crumb(FIELD, field, field))           # key = the campaign member name
+    if obj_label:
+        out.append(Crumb(OBJECT, obj_label, obj_key))     # key = the editor tree iid (e.g. "npc:2")
+    return out
+
+
+class Breadcrumb:
+    """A one-line clickable path bar themed from a palette dict. ``on_navigate(crumb)`` fires when an
+    ANCESTOR segment is clicked (the leaf -- where you already are -- is inert)."""
+
+    def __init__(self, parent, palette, *, on_navigate=None):
+        import tkinter as tk
+
+        self.pal = palette
+        self.on_navigate = on_navigate
+        self.frame = tk.Frame(parent, background=palette["surface"],
+                              highlightthickness=1, highlightbackground=palette["border"])
+        self._empty = "No campaign open -- Open a campaign.toml to navigate it."
+        self.set([])
+
+    def set(self, crumbs):
+        """Render ``crumbs`` (a :func:`trail` list); an empty list shows a muted placeholder."""
+        import tkinter as tk
+
+        for w in self.frame.winfo_children():
+            w.destroy()
+        if not crumbs:
+            tk.Label(self.frame, text=self._empty, background=self.pal["surface"],
+                     foreground=self.pal["muted"], font=("Segoe UI", 10)).pack(side="left", padx=10, pady=5)
+            return
+        last = len(crumbs) - 1
+        for i, c in enumerate(crumbs):
+            if i:
+                tk.Label(self.frame, text="▸", background=self.pal["surface"],
+                         foreground=self.pal["muted"], font=("Segoe UI", 10)).pack(side="left", padx=1)
+            leaf = (i == last)
+            lbl = tk.Label(self.frame, text=f"{GLYPH.get(c.level, '')} {c.label}",
+                           background=self.pal["surface"],
+                           foreground=self.pal["text"] if leaf else self.pal["accent"],
+                           font=("Segoe UI", 10, "bold") if leaf else ("Segoe UI", 10),
+                           cursor="arrow" if leaf else "hand2", padx=5, pady=4)
+            lbl.pack(side="left", pady=1)
+            if not leaf and self.on_navigate is not None:
+                lbl.bind("<Button-1>", lambda _e, cc=c: self.on_navigate(cc))

ff9mapkit/editor/dialogs.py

@@ -0,0 +1,116 @@
+"""Small THEMED modal input dialogs -- a drop-in for :mod:`tkinter.simpledialog`.
+
+tkinter's ``simpledialog`` builds its Toplevel from CLASSIC tk widgets with OS-default colours, so it
+ignores the app's ttk theme and renders light against the dark editor. These replacements use ttk
+widgets on a Toplevel whose background matches the themed app, so an input prompt looks native to the
+editor. :func:`ask_string` returns the entered text (or ``None`` if cancelled); :func:`ask_integer`
+parses + range-checks an int, re-prompting inline on a bad value. The dialog is a small class
+(mirroring :mod:`.picker`) so it's headless-testable -- ``ask_*`` just wrap it with ``wait_window``.
+"""
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk
+
+
+class _InputDialog:
+    def __init__(self, parent, title, prompt, *, initial="", integer=False, minvalue=None, maxvalue=None):
+        self.integer = integer
+        self.minvalue, self.maxvalue = minvalue, maxvalue
+        self.result = None
+
+        win = self.win = tk.Toplevel(parent)
+        win.title(title)
+        win.transient(parent)
+        win.resizable(False, False)
+        try:                                              # match the themed app (a bare Toplevel is OS-gray)
+            win.configure(background=parent.winfo_toplevel()["background"])
+        except tk.TclError:
+            pass
+
+        ttk.Label(win, text=prompt, wraplength=380, justify="left").pack(anchor="w", padx=14, pady=(14, 6))
+        self.var = tk.StringVar(value="" if initial is None else str(initial))
+        ent = self.ent = ttk.Entry(win, textvariable=self.var, width=46)
+        ent.pack(fill="x", padx=14)
+        self.err = ttk.Label(win, text="", foreground="#ff6b6b", wraplength=380, justify="left")
+        self.err.pack(anchor="w", padx=14, pady=(2, 0))
+
+        bar = ttk.Frame(win, padding=12)
+        bar.pack(fill="x")
+        ttk.Button(bar, text="OK", style="Accent.TButton", command=self._ok).pack(side="right")
+        ttk.Button(bar, text="Cancel", command=self._cancel).pack(side="right", padx=6)
+        ent.bind("<Return>", lambda e: self._ok())
+        ent.bind("<Escape>", lambda e: self._cancel())
+        ent.focus_set()
+        ent.select_range(0, "end")
+        win.grab_set()
+
+    def _ok(self):
+        v = self.var.get().strip()
+        if self.integer:
+            try:
+                n = int(v)
+            except ValueError:
+                self.err.config(text="Enter a whole number.")
+                return
+            if self.minvalue is not None and n < self.minvalue:
+                self.err.config(text=f"Must be at least {self.minvalue}.")
+                return
+            if self.maxvalue is not None and n > self.maxvalue:
+                self.err.config(text=f"Must be at most {self.maxvalue}.")
+                return
+            self.result = n
+        else:
+            self.result = v                               # the caller treats "" as cancel (if not name: ...)
+        self.win.destroy()
+
+    def _cancel(self):
+        self.result = None
+        self.win.destroy()
+
+
+def ask_string(parent, title, prompt, *, initial=""):
+    """Modal themed text prompt. Returns the entered string, or None if cancelled."""
+    dlg = _InputDialog(parent, title, prompt, initial=initial)
+    parent.wait_window(dlg.win)
+    return dlg.result
+
+
+def ask_integer(parent, title, prompt, *, initial=None, minvalue=None, maxvalue=None):
+    """Modal themed integer prompt (re-prompts inline on a non-int / out-of-range). Returns int or None."""
+    dlg = _InputDialog(parent, title, prompt, initial=initial, integer=True,
+                       minvalue=minvalue, maxvalue=maxvalue)
+    parent.wait_window(dlg.win)
+    return dlg.result
+
+
+def _smoke():
+    """Headless self-test: build the dialog, drive _ok/_cancel, and check string + int parsing/ranging."""
+    from .theme import apply_theme
+    root = tk.Tk()
+    root.withdraw()
+    apply_theme(root)
+
+    d = _InputDialog(root, "t", "name?", initial="seed")
+    assert d.var.get() == "seed"
+    d.var.set("boss_dead"); d._ok()
+    assert d.result == "boss_dead", d.result
+
+    bad = _InputDialog(root, "t", "n?", integer=True, minvalue=4000, maxvalue=32767)
+    bad.var.set("nope"); bad._ok()
+    assert bad.result is None and bad.err["text"], "a non-int stays open with an error"
+    bad.var.set("10"); bad._ok()
+    assert bad.result is None, "below minvalue stays open"
+    bad.var.set("5000"); bad._ok()
+    assert bad.result == 5000, bad.result
+
+    cx = _InputDialog(root, "t", "x?"); cx._cancel()
+    assert cx.result is None
+    print("dialogs smoke ok: string + integer (parse/range) + cancel")
+    root.destroy()
+
+
+if __name__ == "__main__":
+    import sys
+    if "--smoke" in sys.argv:
+        _smoke()

ff9mapkit/editor/feedback.py

@@ -0,0 +1,208 @@
+"""A shared *result* surface for the GUI apps: a verdict banner + a structured problems list.
+
+The kit's apps used to dump raw subprocess/traceback text into a scrolling log, leaving the user to
+read tea leaves for "did it work, and what do I do next?". This module replaces that with two pieces:
+
+  * a :class:`Verdict` -- a one-line outcome (ok / passed-with-warnings / failed / running) plus an
+    optional next-action line ("Relaunch once, then F6 -> Warp -> 2640"), rendered as a coloured banner;
+  * a flat list of :class:`Problem` rows (errors + warnings), rendered as a compact, colour-coded,
+    selectable list -- the structured replacement for ``ERROR ...`` / ``warn ...`` log spam.
+
+Following the same discipline as :mod:`.theme` / :mod:`.forms` / :mod:`.model`, the data layer
+(``Verdict``/``Problem`` + the ``classify``/``from_returncode``/``problems`` builders) is **tk-FREE**
+and unit-testable on a headless machine; the only Tk lives in :class:`FeedbackPanel`, which imports
+tkinter lazily in ``__init__`` so importing this module never needs a display. The panel takes a
+palette dict from :func:`.theme.apply_theme`, so it matches whatever app hosts it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# --- the four outcome levels (also the problem severities, minus "ok"/"running") -----------------
+OK = "ok"
+WARN = "warn"
+ERROR = "error"
+RUNNING = "running"
+
+# glyphs read fine in Segoe UI (the themed default font); kept ASCII-safe-ish for any console echo.
+_GLYPH = {OK: "✓", WARN: "⚠", ERROR: "✕", RUNNING: "…"}  # ✓ ⚠ ✕ …
+
+
+@dataclass(frozen=True)
+class Problem:
+    """One row in the problems list: an error or a warning, with an optional location label."""
+
+    severity: str          # ERROR | WARN
+    message: str
+    where: str = ""        # optional: a field/member/line the problem belongs to (for a future jump-to)
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """A one-line outcome to show in the banner."""
+
+    level: str             # OK | WARN | ERROR | RUNNING
+    headline: str
+    next_action: str = ""  # the single most useful next step (e.g. an in-game warp), shown under the banner
+
+
+def _n(count: int, word: str) -> str:
+    """``2, 'error' -> '2 errors'`` / ``1, 'warning' -> '1 warning'`` (naive English pluralisation)."""
+    return f"{count} {word}" + ("" if count == 1 else "s")
+
+
+def classify(errors, warnings, *, subject="", clean_headline=None, next_action="") -> Verdict:
+    """Turn two message lists into a :class:`Verdict`.
+
+    ``subject`` prefixes the headline ("Build", "Check", "Campaign lint"). Errors win over warnings:
+    any error -> a failed verdict; warnings only -> passed-with-warnings; neither -> ``clean_headline``
+    (default "<subject> -- all clear")."""
+    ne, nw = len(errors), len(warnings)
+    subj = subject.strip()
+    if ne:
+        tail = _n(ne, "problem") + (f", {_n(nw, 'warning')}" if nw else "") + " to fix"
+        head = f"{subj} -- {tail}" if subj else tail
+        return Verdict(ERROR, head, next_action)
+    if nw:
+        head = f"{subj} -- passed with {_n(nw, 'warning')}" if subj else f"passed with {_n(nw, 'warning')}"
+        return Verdict(WARN, head, next_action)
+    head = clean_headline or (f"{subj} -- all clear" if subj else "all clear")
+    return Verdict(OK, head, next_action)
+
+
+def from_returncode(code, *, subject="", ok_headline=None, ok_next="", fail_hint="") -> Verdict:
+    """A :class:`Verdict` for a subprocess result (the import/deploy shell-outs that have no structured
+    error list -- only an exit code + a streamed log). ``code == 0`` -> ok; anything else -> failed,
+    pointing the user at the streamed details."""
+    subj = subject.strip()
+    if code == 0:
+        return Verdict(OK, ok_headline or (f"{subj} -- done" if subj else "done"), ok_next)
+    head = f"{subj} -- failed (exit {code})" if subj else f"failed (exit {code})"
+    return Verdict(ERROR, head, fail_hint or "See the details below.")
+
+
+def problems(errors=(), warnings=()) -> list:
+    """Flatten ``(errors, warnings)`` string lists into a severity-tagged :class:`Problem` list
+    (errors first, then warnings -- the natural read order)."""
+    rows = [Problem(ERROR, str(m)) for m in errors]
+    rows += [Problem(WARN, str(m)) for m in warnings]
+    return rows
+
+
+# --- the Tk widget (lazy import keeps the data layer above headless-importable) ------------------
+class FeedbackPanel:
+    """A coloured verdict banner + a structured problems list, themed from a palette dict.
+
+    Construct it on a ttk parent and ``.frame.pack(...)`` it where the old log used to dominate. Drive
+    it from the UI thread: ``running(headline)`` when a job starts, then ``show(verdict, problems)``
+    when it finishes. ``on_select(problem)`` (optional) fires when a problem row is clicked -- the seam
+    a future unified shell will use to jump to the offending node.
+    """
+
+    def __init__(self, parent, palette, *, on_select=None):
+        import tkinter as tk
+        from tkinter import ttk
+
+        self.pal = palette
+        self.on_select = on_select
+        self._rows: list = []
+
+        self.frame = ttk.Frame(parent)
+
+        # the banner: a coloured status stripe + a glyph + the headline, and a next-action line beneath.
+        self._banner = tk.Frame(self.frame, background=palette["surface"],
+                                highlightthickness=1, highlightbackground=palette["border"])
+        self._stripe = tk.Frame(self._banner, width=4, background=palette["muted"])
+        self._stripe.pack(side="left", fill="y")
+        inner = tk.Frame(self._banner, background=palette["surface"])
+        inner.pack(side="left", fill="both", expand=True, padx=10, pady=7)
+        self._glyph = tk.Label(inner, text="", background=palette["surface"], foreground=palette["muted"],
+                               font=("Segoe UI", 13, "bold"))
+        self._glyph.pack(side="left", padx=(0, 8))
+        headwrap = tk.Frame(inner, background=palette["surface"])
+        headwrap.pack(side="left", fill="x", expand=True)
+        self._headline = tk.Label(headwrap, text="", background=palette["surface"],
+                                  foreground=palette["text"], font=("Segoe UI", 11, "bold"),
+                                  anchor="w", justify="left")
+        self._headline.pack(fill="x", anchor="w")
+        self._next = tk.Label(headwrap, text="", background=palette["surface"],
+                              foreground=palette["accent"], font=("Segoe UI", 10), anchor="w",
+                              justify="left", wraplength=560)
+        # _next is packed only when there's a next-action string.
+
+        # the problems list: a compact tree (severity glyph + message), colour-coded, selectable.
+        self._plist_wrap = ttk.Frame(self.frame)
+        self._plist = ttk.Treeview(self._plist_wrap, show="tree", selectmode="browse", height=5)
+        self._plist.column("#0", width=560, stretch=True)
+        self._plist.pack(side="left", fill="both", expand=True)
+        psb = ttk.Scrollbar(self._plist_wrap, orient="vertical", command=self._plist.yview)
+        psb.pack(side="right", fill="y")
+        self._plist.configure(yscrollcommand=psb.set)
+        self._plist.tag_configure(ERROR, foreground=palette["error"])
+        self._plist.tag_configure(WARN, foreground=palette["warn"])
+        self._plist.bind("<<TreeviewSelect>>", self._on_row_select)
+
+        # both pieces start hidden; show() / running() reveal them.
+
+    # -- public API (call on the UI thread) --
+    def running(self, headline="Working…"):
+        """Show a neutral 'in progress' banner and clear any prior problems."""
+        self._set_banner(Verdict(RUNNING, headline))
+        self._set_problems([])
+
+    def show(self, verdict, problem_rows=()):
+        """Render a finished :class:`Verdict` + its (possibly empty) :class:`Problem` rows."""
+        self._set_banner(verdict)
+        self._set_problems(list(problem_rows))
+
+    def clear(self):
+        """Hide the banner + problems entirely (back to the resting state)."""
+        self._banner.pack_forget()
+        self._plist_wrap.pack_forget()
+
+    # -- internals --
+    def _color(self, level):
+        return {OK: self.pal["success"], WARN: self.pal["warn"], ERROR: self.pal["error"],
+                RUNNING: self.pal["muted"]}.get(level, self.pal["muted"])
+
+    def _set_banner(self, verdict):
+        col = self._color(verdict.level)
+        self._stripe.configure(background=col)
+        self._glyph.configure(text=_GLYPH.get(verdict.level, ""), foreground=col)
+        self._headline.configure(text=verdict.headline)
+        if verdict.next_action:
+            self._next.configure(text=verdict.next_action)
+            self._next.pack(fill="x", anchor="w", pady=(2, 0))
+        else:
+            self._next.pack_forget()
+        if not self._banner.winfo_ismapped():
+            kw = {"fill": "x", "padx": 10, "pady": (8, 4)}
+            if self._plist_wrap.winfo_ismapped():    # keep the banner above an already-shown problems list
+                kw["before"] = self._plist_wrap
+            self._banner.pack(**kw)
+
+    def _set_problems(self, rows):
+        self._rows = rows
+        self._plist.delete(*self._plist.get_children())
+        if not rows:
+            self._plist_wrap.pack_forget()
+            return
+        for i, p in enumerate(rows):
+            label = f"{_GLYPH.get(p.severity, '')}  {p.message}"
+            if p.where:
+                label += f"   ({p.where})"
+            self._plist.insert("", "end", iid=str(i), text=label, tags=(p.severity,))
+        # size the list to its contents (capped), so a single problem isn't a tall empty box.
+        self._plist.configure(height=max(2, min(len(rows), 8)))
+        if not self._plist_wrap.winfo_ismapped():
+            self._plist_wrap.pack(fill="both", expand=True, padx=10, pady=(0, 6))
+
+    def _on_row_select(self, _evt=None):
+        if not self.on_select:
+            return
+        sel = self._plist.selection()
+        if sel and sel[0].isdigit():
+            idx = int(sel[0])
+            if 0 <= idx < len(self._rows):
+                self.on_select(self._rows[idx])