ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/infohub.py

@@ -0,0 +1,580 @@
+"""The Info Hub spine -- a UI-agnostic discovery API over the kit's reference catalogs + named archetypes.
+
+This is the reusable CORE every Info Hub frontend sits on -- a standalone viewer today, the Campaign
+Editor suite tomorrow, even a Blender panel -- so the expensive part (the data logic) is written and
+tested once, independent of any UI. It answers three authoring questions:
+
+  * ``browse(query)``  -> WHAT exists by this name? (search every catalog + archetype table at once)
+  * ``detail(entry)``  -> WHAT is this exactly? (model, animations, composite parts, the line to author it)
+  * ``snippet(entry)`` -> HOW do I drop it into a ``field.toml``? (the ``[[npc]]`` / ``[[prop]]`` block)
+
+Pure-offline + provenance-clean: it reads only the baked catalogs (:mod:`catalog`) and the curated
+archetype tables -- no game install. Game-dependent extras stay OUT of the spine and arrive via hooks:
+:func:`detail` takes an optional ``usage_fn`` for "where does this appear in real FF9?", and a frontend
+wires its own in-game *preview* by feeding the selection back to the gallery builders. Everything here is
+a dataclass -- trivially rendered by Tkinter, a web view, or the CLI, and JSON-serializable.
+"""
+from __future__ import annotations
+
+import re
+
+from dataclasses import dataclass, field as _dc_field
+from typing import Callable, Optional
+
+from . import archetypes as _arch
+from . import catalog as _cat
+from . import prop_archetypes as _props
+from .content.npc import PRESETS as _CHAR_PRESETS    # vivi / zidane -- explicit, byte-golden
+
+# the kinds the Info Hub indexes, listed in browse priority order (curated/named first, raw + reference last)
+KINDS = ("archetype", "creature", "composite", "prop", "model", "item", "scene", "storyflag", "sps_template")
+
+
+@dataclass(frozen=True)
+class Entry:
+    """One browsable result -- the unit a frontend lists and acts on. ``name`` is what you type to use it;
+    ``model`` is the GEO model behind it (when any); ``ident`` is the numeric id for a model/item/scene."""
+    kind: str
+    name: str
+    model: Optional[str] = None
+    summary: str = ""
+    ident: Optional[int] = None
+
+
+@dataclass
+class Detail:
+    """The rich record for one entry -- everything an authoring detail pane shows."""
+    name: str
+    kind: str
+    model: Optional[str] = None
+    model_id: Optional[int] = None
+    facts: list = _dc_field(default_factory=list)      # [(label, value)] -- generic key facts
+    movement: Optional[dict] = None                    # {stand,walk,run,left,right} iff NPC-ready
+    anims: list = _dc_field(default_factory=list)      # [(action, anim_id)] -- the full gesture list
+    parts: list = _dc_field(default_factory=list)      # composite parts [(model_name, pose, dx, dz)]
+    aliases: list = _dc_field(default_factory=list)    # other names mapping to the same model
+    locations: Optional[list] = None                   # [(field_id, name)] iff a usage_fn was supplied
+    snippet: str = ""
+    preview_png: Optional[str] = None                  # a rendered preview image path (SPS effects)
+
+
+# ----------------------------------------------------------------- helpers ---
+def _model_of_archetype(name) -> Optional[str]:
+    """The GEO model NAME an archetype/creature maps to (or None). Cheap -- a direct model lookup, NOT
+    ``archetypes.resolve`` (which also scans every animation to build the movement set)."""
+    key = str(name).strip().lower()
+    if key in _CHAR_PRESETS:
+        model = _CHAR_PRESETS[key][0]
+    else:
+        spec = _arch.ARCHETYPES.get(key) or _arch.CREATURES.get(key)
+        model = spec["model"] if spec else None
+    m = _cat.model(model) if model is not None else None
+    return m.name if m else None
+
+
+_DESC_CACHE: Optional[dict] = None
+_DESC_RE = re.compile(r'^\s*"([a-z0-9_]+)"\s*:\s*[\{\[].*?#\s*(.+)$')
+
+
+def _descriptions() -> dict:
+    """``{name: short description}`` parsed from the archetype/prop source comments (built once). The rich
+    "what is it" text already lives in trailing comments (shelf -> 'a Dali ... shelf / box'; cask ->
+    'a "CaSK" / barrel'); this surfaces it for SEARCH + display without migrating it into the data."""
+    global _DESC_CACHE
+    if _DESC_CACHE is None:
+        d: dict = {}
+        for mod in (_arch, _props):
+            try:
+                src = open(mod.__file__, encoding="utf-8").read()
+            except OSError:
+                continue
+            for line in src.splitlines():
+                mm = _DESC_RE.match(line)
+                if mm:
+                    d.setdefault(mm.group(1), mm.group(2).strip())
+        _DESC_CACHE = d
+    return _DESC_CACHE
+
+
+def _build_entries() -> list:
+    """Every indexed :class:`Entry`, in :data:`KINDS` order (built once, then cached). Each summary folds
+    in the comment DESCRIPTION + (for raw models) the friendly archetype names that use it, so search
+    matches what a thing IS ('box' -> shelf, 'zidane' -> the ZDN model), not just its cryptic GEO token."""
+    desc = _descriptions()
+    by_model = _model_names_index()
+    out = []
+    for name in sorted(set(_CHAR_PRESETS) | set(_arch.ARCHETYPES)):     # archetypes (playable + NPC types)
+        mname = _model_of_archetype(name)
+        m = _cat.model(mname) if mname else None
+        role = m.kind if m else "npc"
+        out.append(Entry("archetype", name, mname, f"{role} NPC -- {desc.get(name) or mname or '?'}",
+                         m.id if m else None))
+    for name in sorted(_arch.CREATURES):                               # creatures (GEO_MON field objects)
+        mname = _arch.CREATURES[name]["model"]
+        m = _cat.model(mname)
+        out.append(Entry("creature", name, mname, f"monster -- {desc.get(name) or mname}", m.id if m else None))
+    for name in sorted(_props.PROP_COMPOSITES):                        # composites (multi-part set pieces)
+        d = desc.get(name) or f"{len(_props.PROP_COMPOSITES[name])} parts"
+        out.append(Entry("composite", name, None, f"set piece -- {d}"))
+    for name in sorted(_props.PROP_ARCHETYPES):                        # props (single static set-dressing)
+        spec = _props.PROP_ARCHETYPES[name]
+        m = _cat.model(_cat.resolve_model(spec["model"]))
+        gname = m.name if m else spec["model"]
+        out.append(Entry("prop", name, gname, f"prop -- {desc.get(name) or gname}", m.id if m else None))
+    for m in _cat.all_models():                                        # raw models (anything by GEO name)
+        friendly = by_model.get(m.name, [])
+        extra = ("  -- " + ", ".join(friendly)) if friendly else ""
+        out.append(Entry("model", m.name, m.name, f"{m.kind} model ({m.form}){extra}", m.id))
+    from . import itemstats as _istats                                # live stats from YOUR install (or None)
+    for iid, nm in _cat.items():                                       # items
+        out.append(Entry("item", nm, None, _istats.summary(iid) or f"item #{iid}", iid))
+    for nm, sid in _cat.battle_scenes():                              # battle scenes (encounters)
+        out.append(Entry("scene", nm, None, f"battle scene #{sid}", sid))
+    out += _storyflag_entries()                                       # FF9 story-flag registry (reference)
+    out += _sps_template_entries()                                    # Tier-2 [[sps]] creator presets
+    return out
+
+
+def _sps_template_entries() -> list:
+    """The curated ``[[sps]]`` effect templates (``sps.templates``) as a static, install-free kind -- the
+    names + descriptions list with no install; the detail-pane PREVIEW renders the donor effect lazily
+    (install-gated). The entry's ``model`` stashes the donor ``field:sps`` for that preview."""
+    from .sps import templates as _tpl
+    return [Entry("sps_template", name, f"{field}:{sid}", f"effect template -- {desc}", sid)
+            for name, desc, field, sid in _tpl.list_templates()]
+
+
+_ENTRY_CACHE: Optional[list] = None
+
+
+def _all_entries() -> list:
+    """The indexed entries (lazily built once; the catalogs are static)."""
+    global _ENTRY_CACHE
+    if _ENTRY_CACHE is None:
+        _ENTRY_CACHE = _build_entries()
+    return _ENTRY_CACHE
+
+
+_MODEL_NAMES_CACHE: Optional[dict] = None
+
+
+def _model_names_index() -> dict:
+    """``{model_name: [names...]}`` -- every archetype/creature/prop name grouped by its GEO model, built
+    ONCE so :func:`_aliases_for` is an O(1) lookup instead of re-scanning every archetype per detail."""
+    global _MODEL_NAMES_CACHE
+    if _MODEL_NAMES_CACHE is None:
+        idx: dict = {}
+        for n in set(_CHAR_PRESETS) | set(_arch.ARCHETYPES) | set(_arch.CREATURES):
+            mn = _model_of_archetype(n)
+            if mn:
+                idx.setdefault(mn, []).append(n)
+        for n, spec in _props.PROP_ARCHETYPES.items():
+            m = _cat.model(_cat.resolve_model(spec["model"]))
+            if m:
+                idx.setdefault(m.name, []).append(n)
+        _MODEL_NAMES_CACHE = {k: sorted(v) for k, v in idx.items()}
+    return _MODEL_NAMES_CACHE
+
+
+def _aliases_for(name, model_name) -> list:
+    """Other archetype/creature/prop names on the same GEO model (so a detail pane can show 'also: dagger,
+    garnets_mother') -- an O(1) lookup into the cached :func:`_model_names_index`."""
+    if not model_name:
+        return []
+    return [n for n in _model_names_index().get(model_name, []) if n != name]
+
+
+# ------------------------------------------------------ story-flag registry ---
+# The FF9 story-flag REGISTRY (flags.py) browsable as a reference kind: named engine vars, reserved bit
+# regions, the census story clusters, the scenario-milestone table, and the safe custom band. Always
+# available + install-free (flags.py is pure). Distinct from the campaign 'flag' kind (a campaign's own
+# [[flag]] gates) -- this is FF9's built-in story state, for "what bit / scenario is X?".
+_STORYFLAG_SUBLABEL = {"var": "story var", "RESERVED": "RESERVED region", "region": "bit region",
+                       "story": "story cluster", "scenario": "scenario milestone", "band": "safe custom band"}
+_STORYFLAG_TIER = {"a": "engine-grounded", "b": "empirical (census)", "c": "uncertain",
+                   "a/b": "engine + census"}
+_STORYFLAG_ROWS_CACHE: Optional[dict] = None
+
+
+def _storyflag_rows() -> dict:
+    """``{display_name: (sub, raw_name, location, meaning, tier)}`` from ``flags.registry_rows()`` (built
+    once). Scenario rows display as 'Beat (value)' so they're unique + searchable by beat AND value."""
+    global _STORYFLAG_ROWS_CACHE
+    if _STORYFLAG_ROWS_CACHE is None:
+        from . import flags as _flags
+        rows: dict = {}
+        for sub, name, loc, meaning, tier in _flags.registry_rows():
+            disp = f"{meaning} ({name})" if sub == "scenario" else name
+            rows[disp] = (sub, name, loc, meaning, tier)
+        _STORYFLAG_ROWS_CACHE = rows
+    return _STORYFLAG_ROWS_CACHE
+
+
+def _storyflag_entries() -> list:
+    out = []
+    for disp, (sub, name, loc, meaning, tier) in _storyflag_rows().items():
+        label = _STORYFLAG_SUBLABEL.get(sub, sub)
+        ident = int(name) if sub == "scenario" else None
+        out.append(Entry("storyflag", disp, None, f"{label} · {loc} · {meaning}", ident))
+    return out
+
+
+# ----------------------------------------------------------- campaign layer ---
+def _campaign_entries(plan) -> list:
+    """Field entries (kind='field') for the members of a campaign -- the ADDITIVE layer browse/detail
+    expose when a frontend passes ``campaign_context``. Lets the Info Hub search 'the fields in THIS
+    campaign' alongside the static catalogs. Duck-typed (anything with a ``.members`` list of objects
+    carrying ``name``/``new_id``/``mode``) so the spine never imports campaign.py at module load."""
+    out = []
+    for m in getattr(plan, "members", None) or []:
+        nm = getattr(m, "name", None)
+        if not nm:
+            continue
+        nid = getattr(m, "new_id", None)
+        mode = getattr(m, "mode", "") or ""
+        out.append(Entry("field", nm, None, f"campaign field #{nid} ({mode})", nid))
+    for fdef in getattr(plan, "flags", None) or []:               # shared NAMED story flags (cross-field gates)
+        nm = fdef.get("name") if isinstance(fdef, dict) else None
+        if nm:
+            idx = fdef.get("index")
+            out.append(Entry("flag", str(nm), None, f"campaign story flag (bit {idx})", idx))
+    return out
+
+
+# -------------------------------------------------------------------- SPS layer ---
+# Field particle effects (fire/smoke/magic) browsable as the ADDITIVE 'sps' kind a frontend exposes via
+# ``sps_context`` -- a {label: sps_dir} map of the OPEN project's carried ``sps/`` sidecars (the effects a
+# native fork ships + can ``[[sps_edit]]``). Install-FREE: it reads the project's own staged ``.sps``/
+# ``spt.tcb`` files, never the install (the spine stays game-free). Each entry stashes its ``.sps`` path in
+# ``Entry.model`` so :func:`detail` is self-contained. -> [[project-ff9-sps-authoring]], docs/SPS.md.
+def _sps_dir_map(sps_context) -> dict:
+    """Normalise ``sps_context`` to ``{label: Path}``. Accepts a {label: dir} map, a single dir path, or a
+    list of (label, dir) / dirs. Drops anything that isn't a real directory."""
+    from pathlib import Path
+    out: dict = {}
+    if sps_context is None:
+        return out
+    items = sps_context.items() if isinstance(sps_context, dict) else (
+        [(None, sps_context)] if isinstance(sps_context, (str, Path)) else list(sps_context))
+    for label, d in items:
+        if d is None:
+            label, d = None, label                      # a bare list of dirs
+        p = Path(d)
+        if p.is_dir():
+            out[str(label) if label is not None else p.parent.name] = p
+    return out
+
+
+def _sps_entries(sps_context) -> list:
+    """``Entry(kind='sps')`` for every ``<id>.sps.bytes`` in the open project's carried ``sps/`` sidecars.
+    The entry's ``model`` holds the ``.sps`` file path (so detail/preview need no re-resolution)."""
+    dirs = _sps_dir_map(sps_context)
+    multi = len(dirs) > 1
+    out = []
+    for label, d in dirs.items():
+        for f in sorted(d.glob("*.sps.bytes")):
+            stem = f.name[: -len(".sps.bytes")]
+            try:
+                sid = int(stem)
+            except ValueError:
+                continue
+            name = f"{label}:{sid}" if multi else str(sid)
+            out.append(Entry("sps", name, str(f), f"SPS effect #{sid} (carried by {label})", sid))
+    return out
+
+
+_SPS_PREVIEW_DIR = None
+
+
+def _sps_preview_png(sps, tcb, key: str) -> Optional[str]:
+    """Render a single representative frame to a cached PNG (dark-flattened so it's visible on any pane) and
+    return its path, or ``None`` if rendering isn't possible (no Pillow). Local imports keep the spine light."""
+    global _SPS_PREVIEW_DIR
+    try:
+        import re as _re
+        import tempfile
+        from pathlib import Path
+        from .sps import render as _render
+        if _SPS_PREVIEW_DIR is None:
+            _SPS_PREVIEW_DIR = Path(tempfile.gettempdir()) / "ff9mapkit_sps_preview"
+            _SPS_PREVIEW_DIR.mkdir(parents=True, exist_ok=True)
+        from PIL import Image  # noqa: PLC0415
+        frame = _render.render_frame(sps, tcb, sps.frame_count // 2, scale=4)   # a developed mid frame
+        flat = Image.new("RGBA", frame.size, (34, 34, 34, 255))                 # dark tile -> always visible
+        flat.alpha_composite(frame)
+        dest = _SPS_PREVIEW_DIR / (_re.sub(r"[^0-9A-Za-z_.-]", "_", key) + ".png")
+        flat.convert("RGB").save(dest)
+        return str(dest)
+    except Exception:  # noqa: BLE001 -- preview is best-effort; never break detail
+        return None
+
+
+def _sps_template_detail(entry: Entry) -> Detail:
+    """A ``[[sps]]`` template: facts + a rendered preview of the donor effect it clones (install-gated; the
+    listing stays install-free, only this lazy detail reads the install)."""
+    from .sps import catalog as _spscat, codec as _spscodec
+    d = Detail(name=entry.name, kind="sps_template", model=None, model_id=entry.ident, snippet=snippet(entry))
+    field, _, sid = (entry.model or "").partition(":")
+    d.facts = [("kind", "SPS effect template"), ("use", f'template = "{entry.name}"'), ("clones", f"{field} #{sid}")]
+    try:
+        rows = _spscat.list_field_sps(field)
+        ent = next((r for r in rows if r.sps_id == int(sid)), None)
+        if ent is not None:
+            sps = _spscat.load_sps(ent)
+            d.facts += [(k, v) for k, v in _spscat.effect_facts(sps) if k != "kind"]   # keep the template's kind
+            tcb = _spscat.load_tcb(field)
+            if tcb is not None:
+                d.preview_png = _sps_preview_png(sps, tcb, f"tpl_{entry.name}")
+    except Exception:  # noqa: BLE001 -- install-gated preview; degrade to facts-only offline
+        pass
+    return d
+
+
+def _sps_detail(entry: Entry) -> Detail:
+    """Decode one carried effect (``entry.model`` is its ``.sps`` path) -> facts + a rendered preview + a
+    ``[[sps_edit]]`` snippet. Reads the sibling ``spt.tcb.bytes`` for the texture."""
+    from pathlib import Path
+    from .sps import catalog as _spscat, codec as _spscodec
+    d = Detail(name=entry.name, kind="sps", model=None, model_id=entry.ident, snippet=snippet(entry))
+    path = Path(entry.model) if entry.model else None
+    if path is None or not path.is_file():
+        d.facts = [("kind", "SPS field effect"), ("id", str(entry.ident)), ("note", "bin not found")]
+        return d
+    try:
+        sps = _spscodec.parse(path.read_bytes())
+    except Exception as ex:  # noqa: BLE001
+        d.facts = [("kind", "SPS field effect"), ("id", str(entry.ident)), ("error", str(ex))]
+        return d
+    d.facts = _spscat.effect_facts(sps)
+    tcb_path = path.parent / "spt.tcb.bytes"
+    if tcb_path.is_file():
+        d.preview_png = _sps_preview_png(sps, tcb_path.read_bytes(), f"{path.parent.name}_{entry.ident}")
+    return d
+
+
+# --------------------------------------------------------------- public API ---
+def browse(query: str = "", kinds=None, limit=200, campaign_context=None, sps_context=None) -> list:
+    """Search every catalog + archetype table at once. ``query`` = a case-insensitive substring of an
+    entry's name / model / SUMMARY (the summary folds in the comment description + friendly names, so you
+    can search by what a thing IS); ``kinds`` restricts to a subset of :data:`KINDS`; ``limit`` caps the
+    result (curated/named kinds come first) or ``None`` for no cap. The Info Hub's 'grab anything by name'.
+
+    When ``campaign_context`` (a campaign.CampaignPlan) is given, that campaign's member fields are ALSO
+    searchable as kind='field' entries, listed FIRST; with no context the result is exactly as before.
+    When ``sps_context`` (a {label: sps_dir} map of the open project's carried ``sps/`` sidecars) is given,
+    the project's SPS effects are searchable as kind='sps' entries (install-free)."""
+    q = (query or "").strip().lower()
+    field_entries = _campaign_entries(campaign_context) if campaign_context is not None else []
+    sps_entries = _sps_entries(sps_context) if sps_context is not None else []
+    if kinds:
+        want = set(kinds)
+    else:
+        want = set(KINDS) | ({"field", "flag"} if campaign_context is not None else set()) \
+            | ({"sps"} if sps_entries else set())
+    # no context -> iterate the cached list directly (no copy), preserving today's behavior exactly
+    extra = field_entries + sps_entries
+    entries = (extra + _all_entries()) if extra else _all_entries()
+    out = []
+    for e in entries:
+        if e.kind not in want:
+            continue
+        if q and q not in e.name.lower() and not (e.model and q in e.model.lower()) \
+                and q not in e.summary.lower():
+            continue
+        out.append(e)
+        if limit is not None and len(out) >= limit:
+            break
+    return out
+
+
+def find(name, kind=None) -> Optional[Entry]:
+    """The first :class:`Entry` whose name matches ``name`` exactly (case-insensitive), optionally of a
+    given ``kind`` -- for callers that have a name but no Entry (e.g. resolving a `field.toml` value)."""
+    key = str(name).strip().lower()
+    for e in _all_entries():
+        if e.name.lower() == key and (kind is None or e.kind == kind):
+            return e
+    return None
+
+
+def snippet(entry: Entry) -> str:
+    """The ``field.toml`` block to author this entry (a frontend's 'copy / insert'). Placeables get a
+    ``[[npc]]`` / ``[[prop]]`` block with a ``pos = [0, 0]`` placeholder; item/scene get the line they're
+    used in."""
+    e = entry
+    if e.kind in ("archetype", "creature"):
+        return f'[[npc]]\narchetype = "{e.name}"\npos = [0, 0]'
+    if e.kind in ("prop", "composite"):
+        return f'[[prop]]\nprop = "{e.name}"\npos = [0, 0]'
+    if e.kind == "model":
+        m = _cat.model(e.ident) if e.ident is not None else _cat.model(e.model)
+        if m and m.group == "ACC":
+            return f'[[prop]]\nmodel = "{m.name}"\npos = [0, 0]'
+        return f'[[npc]]\nmodel = "{e.model}"\npos = [0, 0]'
+    if e.kind == "item":
+        return f'give_item = [{e.ident}, 1]  # {e.name} -- e.g. an [[event]] reward'
+    if e.kind == "scene":
+        return f'[encounter]\nscene = {e.ident}  # {e.name}'
+    if e.kind == "sps_template":                       # a creator preset -> a ready [[sps]] block
+        return (f'[[sps]]\nid = 5000\ntemplate = "{e.name}"\n'
+                f'pos = [0, 0]        # [x, z] -- auto-grounded onto the floor')
+    if e.kind == "sps":                                # a carried field effect -> a re-skin starter block
+        return (f'[[sps_edit]]\nsps = {e.ident}        # re-skin this effect over its carried texture\n'
+                f'kind = "tint"\nmul = [0, 0, 512]    # recolour the whole ramp (256 == identity; this -> blue)\n'
+                f'# other kinds: recolor_ramp / scale / reposition -- see docs/SPS.md')
+    if e.kind == "field":                              # a campaign member -- not a paste-able toml block
+        return f"# campaign field: {e.name} (id {e.ident})"
+    if e.kind == "flag":                               # a shared named story flag -> the gate line
+        return f'requires_flag = "{e.name}"'
+    if e.kind == "storyflag":                          # the FF9 registry -> a reference / authoring hint
+        from . import flags as _flags
+        sub = _storyflag_rows().get(e.name, ("",))[0]
+        if sub == "band":
+            return (f'[[flag]]\nname = "my_flag"\nindex = {_flags.FIRST_SAFE_FLAG}   '
+                    f'# a custom story flag in the safe band')
+        if sub == "scenario":
+            return f'ff9mapkit save-edit <SavedData_ww.dat> --scenario {e.ident}   # jump to this story beat'
+        loc = _storyflag_rows().get(e.name, ("", "", "?"))[2]
+        return f"# {e.name}  ({loc})  -- FF9 engine state, reference only (do not allocate here)"
+    return e.name
+
+
+def _field_detail(entry: Entry, plan) -> Detail:
+    """Detail for a campaign member (kind='field'): its place in the chain -- id/source/mode, the live
+    doors it leads to + is entered from, onward seams, and entry/reachability/needs-export flags. Resolved
+    through :func:`campaign.campaign_graph` (lazy import -- the spine stays campaign-free at module load)."""
+    d = Detail(name=entry.name, kind="field", model=None, model_id=entry.ident, snippet=snippet(entry))
+    d.facts = [("kind", "campaign field"), ("id", str(entry.ident))]
+    if plan is None:
+        return d
+    from . import campaign as _camp
+    node = _camp.campaign_graph(plan).by_name.get(entry.name)
+    if node is None:
+        return d
+    d.facts = [("kind", "campaign field"), ("id", str(node.new_id)),
+               ("source", str(node.real_id)), ("mode", node.mode)]
+    if node.is_entry:
+        d.facts.append(("role", "campaign entry"))
+    if node.needs_export:
+        d.facts.append(("needs_export", "yes -- export this field's art in-game"))
+    if not node.reachable:
+        d.facts.append(("reachable", "NO -- no live-door path from the entry"))
+    if node.dead_end:
+        d.facts.append(("dead_end", "no onward connection"))
+    for oe in node.out_edges:
+        d.facts.append(("door", f"-> {oe['to']} (entrance {oe['entrance']})"
+                                + (" [gated]" if oe["gated"] else "")))
+    for ie in node.in_edges:
+        d.facts.append(("entered_from", f"<- {ie['frm']} (entrance {ie['entrance']})"))
+    for s in node.seams:
+        tgt = s["to_member"] or ("WORLDMAP" if s["to_real"] == "WORLDMAP" else s["to_real"])
+        d.facts.append((f"seam:{s['kind']}", f"-> {tgt}"))
+    return d
+
+
+def detail(entry: Entry, usage_fn: Optional[Callable] = None, campaign_context=None, sps_context=None) -> Detail:
+    """Resolve an :class:`Entry` to its full :class:`Detail`. ``usage_fn(model_id) -> [(field_id, name),
+    ...]`` is an optional hook a frontend passes to add 'where it appears in real FF9' (the spine stays
+    install-free -- field-usage needs the game); errors from it degrade to ``locations = None``. When the
+    entry is a campaign member (kind='field') and ``campaign_context`` (a CampaignPlan) is given, the
+    detail is the member's place in the chain (doors/seams/reachability)."""
+    e = entry
+    if e.kind == "sps_template":                       # a creator preset (decode + preview the donor)
+        return _sps_template_detail(e)
+    if e.kind == "sps":                                # a carried field effect (decode + preview)
+        return _sps_detail(e)
+    if e.kind == "field":
+        return _field_detail(e, campaign_context)
+    if e.kind == "flag":                               # a shared named story flag (cross-field gate)
+        d = Detail(name=e.name, kind="flag", model=None, model_id=e.ident, snippet=snippet(e))
+        d.facts = [("kind", "campaign story flag"), ("index", str(e.ident)),
+                   ("gate", f'requires_flag = "{e.name}"'), ("set", f'set_flag = ["{e.name}", 1]')]
+        return d
+    if e.kind == "storyflag":                          # an FF9 story-flag registry entry (reference)
+        sub, name, loc, meaning, tier = _storyflag_rows().get(e.name, ("", e.name, "", e.summary, ""))
+        d = Detail(name=e.name, kind="storyflag", model=None, model_id=None, snippet=snippet(e))
+        d.facts = [("kind", _STORYFLAG_SUBLABEL.get(sub, sub)), ("location", loc),
+                   ("confidence", _STORYFLAG_TIER.get(tier, tier))]
+        if meaning:
+            d.facts.append(("meaning", meaning))
+        if sub == "RESERVED":
+            d.facts.append(("note", "reserved -- a mod must NOT allocate flags here"))
+        elif sub == "band":
+            d.facts.append(("note", "allocate your custom story flags in this band"))
+        return d
+    d = Detail(name=e.name, kind=e.kind, model=e.model, model_id=e.ident, snippet=snippet(e))
+    dsc = _descriptions().get(e.name)
+    if e.kind == "composite":
+        d.parts = [((_cat.model(mid).name if _cat.model(mid) else str(mid)), pose, dx, dz)
+                   for mid, pose, dx, dz in _props.resolve_composite(e.name)]
+        d.facts = [("kind", "composite set piece"), ("parts", str(len(d.parts)))]
+        if dsc:
+            d.facts.append(("desc", dsc))
+        return d
+    if e.kind == "item":
+        from . import itemstats as _istats                            # live stat join from YOUR install
+        d.facts = [("kind", "item"), ("id", str(e.ident))] + _istats.facts(e.ident)
+        return d
+    if e.kind == "scene":
+        d.facts = [("kind", "battle scene"), ("id", str(e.ident))]
+        return d
+    # archetype / creature / prop / model -- everything model-backed
+    m = _cat.model(e.ident) if e.ident is not None else (_cat.model(e.model) if e.model else None)
+    if m:
+        d.model, d.model_id = m.name, m.id
+        d.facts = [("kind", e.kind), ("model", m.name), ("role", m.kind), ("form", m.form)]
+        if e.kind == "prop":
+            d.facts.append(("pose", str(_props.resolve(e.name)[1])))
+        if dsc:
+            d.facts.append(("desc", dsc))
+        d.anims = _cat.animation_actions(m.id)
+        d.movement = _cat.npc_anims(m.id) or None
+        d.aliases = _aliases_for(e.name, m.name)
+        if usage_fn is not None:
+            try:
+                d.locations = list(usage_fn(m.id))
+            except Exception:
+                d.locations = None
+    return d
+
+
+_PLACEABLE = ("archetype", "creature", "composite", "prop", "model")
+
+
+def _place_lines(entry, x, z) -> list:
+    """The ``[[npc]]`` / ``[[prop]]`` block placing one entry at world (x, z) on a preview field."""
+    e, pos = entry, f"pos = [{x}, {z}]"
+    if e.kind in ("archetype", "creature"):
+        return ["", "[[npc]]", f'archetype = "{e.name}"', pos]
+    if e.kind in ("prop", "composite"):
+        return ["", "[[prop]]", f'prop = "{e.name}"', pos]
+    if e.kind == "model":
+        m = _cat.model(e.ident) if e.ident is not None else _cat.model(e.model)
+        if m and m.group == "ACC":
+            return ["", "[[prop]]", f'model = "{m.name}"', pos]
+        return ["", "[[npc]]", f'model = "{e.model}"', pos]
+    return []
+
+
+def preview_field_toml(entries, art_dir, *, screens: int = 3) -> Optional[str]:
+    """Build a deployable arena ``field.toml`` that PLACES the given entries -- a gallery of your selection,
+    so a frontend deploys it + F6-reloads to see them LIVE on the debug checkerboard. Writes the arena art
+    into ``art_dir`` and returns the toml; returns ``None`` if nothing is placeable (items/scenes are not
+    field objects). Game-free -- only the caller's deploy touches the install."""
+    from .scene import arena as _arena
+    placeable = [e for e in (entries or []) if e.kind in _PLACEABLE]
+    if not placeable:
+        return None
+    n = len(placeable)
+    meta = _arena.build_arena(art_dir, screens=max(screens, n))
+    half = meta["quad"][1][0]
+    margin = 700
+    xs = [round(-(half - margin) + 2 * (half - margin) * i / max(1, n - 1)) for i in range(n)]
+    zs = [z for _, z in meta["quad"]]
+    z_lo, z_hi = min(zs), max(zs)
+    row_z, spawn_z = (z_lo + z_hi) // 2, z_hi - 150
+    lines = [f"# Info Hub preview -- {', '.join(e.name for e in placeable)}. F6 -> Reload field to see it."]
+    lines += _arena.arena_scene_lines(meta, spawn_z=spawn_z, name="PREVIEW")
+    for e, x in zip(placeable, xs):
+        lines += _place_lines(e, x, row_z)
+    return "\n".join(lines)

ff9mapkit/items.py

@@ -0,0 +1,63 @@
+"""Author-facing item catalog -- give an item by NAME instead of a numeric id.
+
+``give_item = ["Potion", 1]`` instead of ``[236, 1]``. Backed by :mod:`ff9mapkit._itemdb` (FF9 item
+id <-> name, from Memoria's open-source ``RegularItem`` enum). Names match case / spacing / hyphen
+insensitively, so ``"Potion"``, ``"potion"``, ``"Hi-Potion"``, ``"phoenix down"`` all resolve. A
+numeric id (int or digit string) passes through, validated to 0-255.
+
+Usage::
+
+    from ff9mapkit import items
+    items.resolve("Potion")       # -> 236
+    items.resolve("hi-potion")    # -> 237
+    items.resolve(236)            # -> 236  (raw id passes through)
+    items.name_of(236)            # -> "Potion"
+"""
+
+from __future__ import annotations
+
+import difflib
+
+from ._itemdb import ITEMS
+
+# normalized-name -> id (lowercased, alphanumerics only -> "Hi-Potion"/"hi potion" both match HiPotion)
+_BY_NAME = {}
+
+
+def _norm(s) -> str:
+    return "".join(c for c in str(s).lower() if c.isalnum())
+
+
+for _id, _name in ITEMS.items():
+    _BY_NAME[_norm(_name)] = _id
+
+
+def resolve(name_or_id) -> int:
+    """Resolve an item NAME or id to its numeric id. An int / digit-string passes through (validated
+    0-255); a name is matched case/space/hyphen-insensitively. Raises ValueError (with near-miss
+    suggestions) on an unknown name or out-of-range id."""
+    if isinstance(name_or_id, bool):
+        raise ValueError("item cannot be a boolean")
+    if isinstance(name_or_id, int):
+        if not 0 <= name_or_id <= 255:
+            raise ValueError(f"item id {name_or_id} out of range (0-255)")
+        return name_or_id
+    s = str(name_or_id).strip()
+    if s.isdigit():
+        return resolve(int(s))
+    key = _norm(s)
+    if key in _BY_NAME:
+        return _BY_NAME[key]
+    hints = [ITEMS[_BY_NAME[h]] for h in difflib.get_close_matches(key, list(_BY_NAME), n=6, cutoff=0.4)]
+    extra = f" Did you mean: {', '.join(hints)}?" if hints else " Run `ff9mapkit items` to list them."
+    raise ValueError(f"unknown item {name_or_id!r}.{extra}")
+
+
+def name_of(item_id: int):
+    """Canonical name for an id (236 -> 'Potion'), or None."""
+    return ITEMS.get(int(item_id))
+
+
+def all_items() -> list:
+    """Sorted ``[(id, name), ...]`` (for the CLI / docs)."""
+    return sorted(ITEMS.items())