ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/catalog.py

@@ -0,0 +1,316 @@
+"""The Info Hub: a unified, read-only view over the kit's baked FF9 reference catalogs.
+
+Where the two authoring pillars are *spatial* (Blender -> ``scene.toml``) and *logic* (the editor ->
+``field.toml``), this is the *library* pillar -- the shared game-object data that lives outside any one
+field: which **models**, **animations**, **items**, **battle scenes**, and **fields** the engine knows
+about. It is pure-Python identifier data baked from Memoria's open-source tables (no game bytes, no
+install needed); see ``docs/PROVENANCE.md``.
+
+The headline feature is the **model -> animations** join. FF9 has no standalone "NPC" object: an NPC
+is a model id + animation ids placed inline in a field. A model name ``GEO_<group>_<form>_<token>`` and
+an animation name ``ANH_<group>_<form>_<token>_<action>`` share a (group, token); so a model's gestures
+are the anims with the same (group, token). Verified end-to-end: model id 8 = ``GEO_MAIN_F0_VIV``, and
+``animations_for_model(8)`` yields idle=148 / walk=571 / run=419 / turn_l=917 / turn_r=918 -- exactly
+the kit's built-in ``vivi`` preset.
+
+Usage::
+
+    from ff9mapkit import catalog
+    catalog.models("npc", group="NPC")          # browse townsfolk models
+    m = catalog.model(8)                          # Model(id=8, name='GEO_MAIN_F0_VIV', token='VIV', ...)
+    catalog.animations_for_model("GEO_NPC_F0_BAR")   # {action: anim_id} a model can play
+    catalog.battle_scenes("alex")                 # encounter ids by region
+    catalog.search("vivi")                        # cross-kind discovery
+"""
+
+from __future__ import annotations
+
+import difflib
+from typing import NamedTuple, Optional
+
+from ._animdb_all import ANIMATIONS
+from ._fieldtable import FBG_TO_EVT, FIELD_BY_ID
+from ._itemdb import ITEMS
+from ._modeldb import MODELS
+from ._scenedb import SCENES
+from .animations import TOKENS as _CHAR_ALIAS     # friendly playable name -> token (vivi -> VIV)
+
+# GEO/ANH group code -> human label (the model's role).
+GROUP_KIND = {
+    "MAIN": "playable",
+    "NPC": "npc",
+    "MON": "monster",
+    "ACC": "object",
+    "SUB": "sub-character",
+    "WEP": "weapon",
+}
+# form-code first letter -> the pose family the model belongs to.
+FORM_KIND = {"F": "field", "B": "battle", "W": "world"}
+
+
+class Model(NamedTuple):
+    """One actor/field model. ``id`` is what ``SetModel()`` takes; ``token`` ties it to its anims."""
+    id: int
+    name: str           # GEO_<group>_<form>_<token>
+    group: str          # MAIN / NPC / MON / ACC / SUB / WEP
+    form: str           # F0 / B3 / W0 ...
+    token: str          # VIV / BAR / EGG / 000 ...
+    kind: str           # playable / npc / monster / object / sub-character / weapon
+    field: bool         # True for field-form (F*) models -- the ones you place as a field NPC
+
+
+def _parse_geo(name: str):
+    p = name.split("_")                         # GEO ACC F0 EGG
+    grp = p[1] if len(p) > 1 else ""
+    form = p[2] if len(p) > 2 else ""
+    token = p[3] if len(p) > 3 else ""
+    return grp, form, token
+
+
+def _model_info(mid: int, name: str) -> Model:
+    grp, form, token = _parse_geo(name)
+    return Model(mid, name, grp, form, token,
+                 GROUP_KIND.get(grp, "other"), form[:1] == "F")
+
+
+# ---------------------------------------------------------------- models -----
+def all_models() -> list:
+    """Every model as a :class:`Model`, sorted by name (so groups cluster)."""
+    return [_model_info(mid, MODELS[mid]) for mid in sorted(MODELS, key=lambda i: (MODELS[i], i))]
+
+
+def model(name_or_id) -> Optional[Model]:
+    """Look up one model by id (int / digit-string) or exact GEO name (case-insensitive). None if
+    unknown. (For a name with a typo, use :func:`resolve_model`, which suggests near-misses.)"""
+    if isinstance(name_or_id, bool):
+        return None
+    if isinstance(name_or_id, int) or (isinstance(name_or_id, str) and name_or_id.strip().isdigit()):
+        mid = int(name_or_id)
+        return _model_info(mid, MODELS[mid]) if mid in MODELS else None
+    key = str(name_or_id).strip().upper()
+    for mid, nm in MODELS.items():
+        if nm.upper() == key:
+            return _model_info(mid, nm)
+    return None
+
+
+def models(query=None, *, group=None, field_only=False) -> list:
+    """Filtered model list. ``query`` = substring of the GEO name or token, OR a friendly playable name
+    ('vivi'/'dagger' -> its token); ``group`` = a group code ('NPC') or kind label ('npc');
+    ``field_only`` keeps field-form models (the ones you place as a field NPC)."""
+    grp = (group or "").upper()
+    grp_kind = (group or "").lower()
+    q = (query or "").lower()
+    alias = _CHAR_ALIAS.get(q)                   # 'vivi' -> 'VIV' so a friendly name finds the model
+    out = []
+    for m in all_models():
+        if field_only and not m.field:
+            continue
+        if group and m.group != grp and m.kind != grp_kind:
+            continue
+        if q and q not in m.name.lower() and q not in m.token.lower() and not (alias and m.token == alias):
+            continue
+        out.append(m)
+    return out
+
+
+def resolve_model(name_or_id) -> int:
+    """Resolve a model NAME or id to its numeric id (what ``SetModel`` wants). Raises ValueError with
+    near-miss suggestions on an unknown name / out-of-table id."""
+    if isinstance(name_or_id, bool):
+        raise ValueError("model cannot be a boolean")
+    m = model(name_or_id)
+    if m:
+        return m.id
+    if isinstance(name_or_id, int) or str(name_or_id).strip().isdigit():
+        raise ValueError(f"model id {int(name_or_id)} not in the GEO table")
+    names = {nm.upper(): nm for nm in MODELS.values()}
+    hints = difflib.get_close_matches(str(name_or_id).strip().upper(), list(names), n=6, cutoff=0.4)
+    extra = f" Did you mean: {', '.join(names[h] for h in hints)}?" if hints else \
+        " Run `ff9mapkit models` to browse them."
+    raise ValueError(f"unknown model {name_or_id!r}.{extra}")
+
+
+# ------------------------------------------------------------ animations -----
+def animation_name(anim_id) -> Optional[str]:
+    """The full anim name for an id (7302 -> 'ANH_MAIN_F0_VIV_TALK_3_1'), or None for an unknown
+    or non-numeric id (honors the 'or None' contract instead of raising on e.g. a bad string)."""
+    try:
+        return ANIMATIONS.get(int(anim_id))
+    except (TypeError, ValueError):
+        return None
+
+
+def _split_anh(name: str):
+    """(group, form, token, action_lower) for an ``ANH_..`` name, or None."""
+    p = name.split("_")                         # ANH MAIN F0 VIV TALK 3 1
+    if len(p) < 5 or p[0] != "ANH":
+        return None
+    return p[1], p[2], p[3], "_".join(p[4:]).lower()
+
+
+def _form_rank(form: str):
+    """Sort key preferring field forms (F*, by number) over battle/world -- the field gesture wins."""
+    if form[:1] == "F" and form[1:].isdigit():
+        return (0, int(form[1:]))
+    return (1, 0)
+
+
+def animations_for_model(name_or_id) -> dict:
+    """``{action_label: anim_id}`` -- the gestures a model can play, by the (group, token) join.
+
+    Field forms are preferred when an action exists in more than one form (the field clip is what an
+    on-field NPC uses); ties break to the smaller id. Returns ``{}`` for a model with no matching anims
+    (e.g. a numbered battle-only token). Standard movement actions appear as idle/walk/run/turn_l/turn_r.
+    """
+    m = model(name_or_id)
+    if not m or not m.token:
+        return {}
+    best = {}                                   # action -> (form_rank, id)
+    for aid, nm in ANIMATIONS.items():
+        s = _split_anh(nm)
+        if not s or s[0] != m.group or s[2] != m.token:
+            continue
+        rank = (_form_rank(s[1]), aid)
+        if s[3] not in best or rank < best[s[3]]:
+            best[s[3]] = rank
+    return {action: rank_id[1] for action, rank_id in best.items()}
+
+
+def animation_actions(name_or_id) -> list:
+    """Sorted ``[(action_label, anim_id), ...]`` for a model (for display / the CLI)."""
+    return sorted(animations_for_model(name_or_id).items())
+
+
+# the five field-NPC animation slots the injector drives (``content.npc.ANIM_ORDER``) and the join
+# action each is resolved from. The engine plays a clip by NAME, so any id naming the right clip works.
+NPC_SLOT_ACTION = {"stand": "idle", "walk": "walk", "run": "run", "left": "turn_l", "right": "turn_r"}
+
+
+def npc_anims(name_or_id, *, use_catalog: bool = True) -> dict:
+    """``{stand, walk, run, left, right}`` animation ids to place a model as a field NPC -- the Info
+    Hub's payoff: ANY model becomes ready to drop in.
+
+    Each movement slot the field engine drives is resolved from the model's OWN gestures
+    (:func:`animations_for_model`) with graceful fallbacks (missing run -> walk, missing turn -> idle),
+    so a slot never holds a foreign clip. For ``GEO_MAIN_F0_VIV`` this reproduces the built-in ``vivi``
+    preset (by clip name). Returns ``{}`` for a model with no field gestures (a battle-only / effect
+    model) -- give explicit ``anims`` for those.
+
+    For a model in the baked per-model catalog (:data:`ff9mapkit._npcparams.NPC_PARAMS` -- 156 GEO_NPC/MON
+    rigs), the REAL clips that rig uses as an NPC are returned verbatim (the most faithful set -- e.g. the
+    moogle's exact 2904/2927/2907/2923/2911, not the by-name join's near-miss). Off-catalog models (incl.
+    party GEO_MAIN, so the vivi preset stays) keep the gesture-name resolution below. ``use_catalog=False``
+    forces the by-NAME gesture resolution (used by the archetype-gallery completeness guard, which asks
+    "does this model auto-resolve by GESTURE NAME" -- a stricter bar than "has real clips in the catalog")."""
+    if use_catalog:
+        from ._npcparams import NPC_PARAMS
+        try:
+            mid = resolve_model(name_or_id)
+        except (ValueError, TypeError):              # not a known model -> fall through to by-name (-> {})
+            mid = None
+        if mid is not None and mid in NPC_PARAMS:
+            return dict(NPC_PARAMS[mid]["anims"])
+    a = animations_for_model(name_or_id)
+    if not a:
+        return {}
+
+    def pick(*actions):
+        for act in actions:
+            if act in a:
+                return a[act]
+        return None
+
+    stand = pick("idle", "walk", "run")
+    if stand is None:                            # nothing standable -> not a usable field-NPC model
+        return {}
+    return {
+        "stand": stand,
+        "walk": pick("walk", "run", "idle") or stand,
+        "run": pick("run", "walk", "idle") or stand,
+        "left": pick("turn_l", "turn_r", "idle") or stand,
+        "right": pick("turn_r", "turn_l", "idle") or stand,
+    }
+
+
+# ----------------------------------------------------------- battle scenes ---
+def _is_model_bucket(name) -> bool:
+    """A ``BSC_B3_*`` name is the MODEL bucket (176 entries) -- a model holder, NOT a fightable encounter.
+    Picking one as a field's random-battle scene crashes in-game (``InitBattleScene`` null-ref; see the
+    ``scene_name`` note + ``eb/opcodes.py``). The two scene namespaces are disjoint (this published BSC_ table
+    vs the install's region-coded loadable set), so there's no install cross-ref -- this name rule IS the guard."""
+    return bool(name) and str(name).upper().startswith("BSC_B3_")
+
+
+def battle_scenes(query=None, *, include_model_bucket=False) -> list:
+    """``[(name, id), ...]`` sorted by name; ``query`` filters by name substring (case-insensitive). The
+    ``BSC_B3_*`` MODEL bucket (176 non-fightable model holders that crash as an encounter) is EXCLUDED by
+    default -- it's not a pickable encounter; pass ``include_model_bucket=True`` for the raw table."""
+    q = (query or "").lower()
+    return sorted((nm, sid) for nm, sid in SCENES.items()
+                  if (include_model_bucket or not _is_model_bucket(nm)) and (not q or q in nm.lower()))
+
+
+def is_model_bucket_scene(scene_id) -> bool:
+    """True if an encounter id resolves to a ``BSC_B3_*`` model-bucket name (not fightable) -- the build/Check
+    lint uses this to flag a hand-authored or mis-picked ``[encounter] scene``."""
+    return _is_model_bucket(scene_name(scene_id))
+
+
+_SCENE_BY_ID = None
+
+
+def scene_name(scene_id) -> "str | None":
+    """The published BSC_ name for an encounter id, or None if the id isn't in the table (the table is the
+    full published name<->id map, NOT a guarantee the scene's DATA loads -- e.g. the BSC_B3_* model bucket)."""
+    global _SCENE_BY_ID
+    if _SCENE_BY_ID is None:
+        _SCENE_BY_ID = {}
+        for nm, sid in SCENES.items():
+            _SCENE_BY_ID.setdefault(sid, nm)        # first name wins if an id has aliases
+    return _SCENE_BY_ID.get(int(scene_id))
+
+
+def resolve_scene(name_or_id) -> int:
+    """Resolve a battle-scene NAME (BSC_..) or id to its numeric encounter id. A raw id passes through
+    unchanged (the table isn't exhaustive of every valid id). Raises ValueError on an unknown name."""
+    if isinstance(name_or_id, bool):
+        raise ValueError("scene cannot be a boolean")
+    if isinstance(name_or_id, int) or str(name_or_id).strip().isdigit():
+        return int(name_or_id)
+    key = str(name_or_id).strip().upper()
+    by_name = {nm.upper(): sid for nm, sid in SCENES.items()}
+    if key in by_name:
+        return by_name[key]
+    hints = 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 scenes` to browse them."
+    raise ValueError(f"unknown battle scene {name_or_id!r}.{extra}")
+
+
+# -------------------------------------------------- items / fields (thin) ----
+def items(query=None) -> list:
+    """``[(id, name), ...]`` (excludes the NoItem sentinel); ``query`` filters by name substring."""
+    q = (query or "").lower()
+    return sorted((i, n) for i, n in ITEMS.items() if n != "NoItem" and (not q or q in n.lower()))
+
+
+def fields(query=None) -> list:
+    """``[(fbg_folder, field_id, evt_name), ...]`` for EVERY field (id-keyed, so the ~142 fields that SHARE a
+    background folder with another -- the same room at a different story beat -- BOTH appear, each with its own
+    event); ``query`` filters by fbg/evt substring."""
+    q = (query or "").lower()
+    out = [(fbg, fid, evt) for fid, (fbg, evt) in FIELD_BY_ID.items()
+           if not q or q in fbg.lower() or q in evt.lower()]
+    return sorted(out, key=lambda r: (r[0], r[1]))
+
+
+# ----------------------------------------------------------- cross-kind ------
+def search(query: str) -> dict:
+    """Discovery across every catalog: ``{'models': [...], 'items': [...], 'scenes': [...],
+    'fields': [...]}`` matching ``query`` (substring). The Info Hub's "grab anything by name"."""
+    return {
+        "models": models(query),
+        "items": items(query),
+        "scenes": battle_scenes(query),
+        "fields": fields(query),
+    }

ff9mapkit/chain.py

@@ -0,0 +1,358 @@
+"""import-chain (P1, read-only): walk FF9's walkable-door graph out from a seed field, across zones.
+
+Single-field ``import`` extracts one field's gateway edges but leaves each ``to`` pointing back into the
+live game. ``import-chain`` follows those edges: from a seed it walks the connected region of real fields,
+classifies every connection (walk-in gateway / scripted teleport / overworld exit -- see
+:func:`ff9mapkit.eventscan.scan_all_warps`), bounds the walk (zones, hops, a hard field cap), and renders
+the graph for scoping. Emitting ``campaign.toml`` + the per-field forks (with edges retargeted among the
+chain's own new ids) is P2; this module is P1: discovery + ``--dry-run``.
+
+The walk is PURE: it takes ``scan_fn(id)`` and ``zone_fn(id)`` callbacks, so it unit-tests on a synthetic
+graph with no game install. The CLI wires the real :class:`ff9mapkit.extract.EventBundle`-backed scan.
+
+Grounded in a live byte-survey (2026-06-09): ~41% of real connectivity is scripted (not walk-in), every
+warp target is a literal (FF9 never computes a warp id), WorldMap operands are overworld LOCATION ids
+(9000-9012) not fields, and only ~2.9% of region exits are story-conditional (stacked same-zone doors)."""
+
+from __future__ import annotations
+
+from collections import OrderedDict, deque
+from dataclasses import dataclass
+
+WALK_IN = "walk_in"
+SCRIPTED = "scripted"
+OVERWORLD = "overworld_exit"
+
+DEFAULT_DENYLIST = frozenset({100})     # field 100 (Alexandria) crashes in this setup -- CLAUDE.md §5
+DEFAULT_MAX_FIELDS = 25
+# Generous: within a --zones scope, zones + max_fields are the real bound; a tight hop cap would sever a
+# long linear dungeon (Ice Cavern is 13 screens deep). Lower it for an unscoped --cross-zones sweep.
+DEFAULT_MAX_HOPS = 20
+
+
+def zone_label(folder) -> str:
+    """Zone token of an FBG folder: ``'fbg_n05_iccv_map085_ic_ent_0'`` -> ``'iccv'``. None/odd -> ``'?'``."""
+    if not folder:
+        return "?"
+    parts = str(folder).split("_")
+    return parts[2] if len(parts) >= 3 else str(folder)
+
+
+# --------------------------------------------------------------------------- field-id clustering / ranges
+# FF9 stores "same place, different story state" as SEPARATE field ids that share the background art -- a
+# revisited zone's ids cluster by visit, separated by big id gaps (Alexandria town: 100-117 opening, 1850-1865
+# return, 2450-2457 ruined, 3000 ending). These helpers split a zone by those gaps (so a region fork can scope
+# to ONE visit instead of the whole 48-screen zone) and parse/format the compact id-range string the catalog
+# stores in `members` and import-chain reads from `--ids`.
+DEFAULT_CLUSTER_GAP = 120   # sits in the dead band (98, 135) measured from ID_TO_FBG: the largest WITHIN-visit
+#                             gap is 98 (evft 152->250, an orphaned cutscene screen) and the smallest BETWEEN-
+#                             visit gap is 135 (alxc 1866->2001) -- so 120 keeps each visit whole AND splits all
+#                             distinct visits (margins ~22/15 ids; widen/narrow via --gap if fields are added)
+
+
+def id_clusters(ids, gap: int = DEFAULT_CLUSTER_GAP) -> list:
+    """Split a sorted-unique list of field ids into clusters wherever consecutive ids jump by more than
+    ``gap`` -- each cluster is one story-state visit of a revisited zone. ``[]`` for no ids. PURE."""
+    seq = sorted({int(x) for x in ids})
+    if not seq:
+        return []
+    out, cur = [], [seq[0]]
+    for a, b in zip(seq, seq[1:]):
+        if b - a > gap:
+            out.append(cur)
+            cur = [b]
+        else:
+            cur.append(b)
+    out.append(cur)
+    return out
+
+
+def format_id_ranges(ids) -> str:
+    """Render a set of ids as a compact, sorted range string: ``[100..117, 150, 200..202]`` ->
+    ``'100-117,150,200-202'``. ``''`` for empty. The inverse of :func:`parse_id_ranges`."""
+    seq = sorted({int(x) for x in ids})
+    if not seq:
+        return ""
+    spans, start, prev = [], seq[0], seq[0]
+    for n in seq[1:]:
+        if n == prev + 1:
+            prev = n
+            continue
+        spans.append((start, prev))
+        start = prev = n
+    spans.append((start, prev))
+    return ",".join(f"{a}-{b}" if a != b else f"{a}" for a, b in spans)
+
+
+def parse_id_ranges(spec) -> list:
+    """Parse a compact id-range string (``'100-117,150,200-202'``) -> a sorted-unique ``list[int]``. Accepts
+    spaces, an already-list/tuple of ints, or an empty value (-> ``[]``). Raises ``ValueError`` on a malformed
+    token or a reversed range. The inverse of :func:`format_id_ranges`."""
+    if spec is None or spec == "":
+        return []
+    if isinstance(spec, (list, tuple, set)):
+        return sorted({int(x) for x in spec})
+    out: set = set()
+    for tok in str(spec).replace(" ", "").split(","):
+        if not tok:
+            continue
+        if "-" in tok.lstrip("-"):                 # a range 'A-B' (lstrip guards a leading '-' that isn't a sep)
+            a, _, b = tok.partition("-")
+            lo, hi = int(a), int(b)
+            if hi < lo:
+                raise ValueError(f"reversed id range {tok!r} (low-high)")
+            out.update(range(lo, hi + 1))
+        else:
+            out.add(int(tok))
+    return sorted(out)
+
+
+@dataclass
+class GraphResult:
+    """Outcome of a walk. ``nodes`` is an insertion-ordered (BFS discovery order) id -> info map; that
+    order is also the id-assignment order P2 will use (``campaign_id_base + i``)."""
+
+    nodes: "OrderedDict"     # id -> {zone, found, edges, overworld_exits, encounter, music, hop}
+    portals: list            # edges NOT followed (zone boundary / stop-at / denylist / max-hops)
+    seams: list              # scripted teleport edges not followed (author by hand)
+    unforkable: list         # edges to targets with no FBG/background (shop/menu, variant, cutscene-only)
+    seeds: list
+    allowed_zones: object    # set | None (None = any zone)
+    truncated: bool          # hit max_fields with more queued
+    remaining: int           # fields still queued when truncated
+    bounds: dict
+
+
+def walk(seed_ids, scan_fn, zone_fn, *, forkable_fn=None, max_hops=DEFAULT_MAX_HOPS, zones=None,
+         stop_at=None, max_fields=DEFAULT_MAX_FIELDS, follow_scripted=False, denylist=DEFAULT_DENYLIST,
+         stop_at_zone_boundary=True, restrict_ids=None) -> GraphResult:
+    """Bounded BFS over the door graph.
+
+    ``scan_fn(field_id)`` -> ``{found: bool, edges: [{to, kind, entrance?, zone?, story_conditional?,
+    trigger?}], overworld_exits: [...], encounter, music}`` (``found=False`` for an id with no scannable
+    ``.eb`` -- world/special field -- terminating that branch). ``zone_fn(field_id)`` -> zone label.
+    ``forkable_fn(field_id)`` -> True if the target is a real WALKABLE field (has a background in the
+    FBG table); False for a shop/menu / variant / cutscene-only id that has no room to fork. A non-forkable
+    target is recorded in ``unforkable`` and not followed -- BEFORE the zone test, so a shop door reads as
+    'menu/no-bg', not a bogus zone-boundary portal. Defaults to always-forkable (pure-graph unit tests).
+
+    Scope: if ``zones`` is given, only targets in those zones are followed; otherwise, with
+    ``stop_at_zone_boundary`` (default) the walk stays within the seed's own zone(s). ``restrict_ids`` (an
+    EXPLICIT id set, e.g. import-chain ``--ids``) bounds the walk to exactly those fields regardless of zone --
+    an edge to a field OUTSIDE the set is recorded as a portal, never followed (so one story-state cluster
+    doesn't leak its same-zone sibling visits). Either way an edge rejected SOLELY for being out of scope is
+    recorded as a PORTAL (so you see where the region connects). Scripted edges are recorded as SEAMS and not
+    followed unless ``follow_scripted``. ``max_fields`` is a hard cap with a loud ``truncated`` flag rather
+    than silently forking the whole game."""
+    forkable_fn = forkable_fn or (lambda fid: True)
+    seeds = [int(s) for s in (seed_ids if isinstance(seed_ids, (list, tuple, set)) else [seed_ids])]
+    stop_at = {int(x) for x in (stop_at or ())}
+    deny = {int(x) for x in (denylist or ())}
+    restrict = {int(x) for x in restrict_ids} if restrict_ids is not None else None
+    if zones is not None:
+        allowed = set(zones)
+    elif stop_at_zone_boundary:
+        allowed = {zone_fn(s) for s in seeds}
+    else:
+        allowed = None
+
+    nodes: "OrderedDict" = OrderedDict()
+    portals: list = []
+    seams: list = []
+    unforkable: list = []
+    visited: set = set()
+    q: deque = deque()
+    for s in seeds:
+        if s not in visited:
+            visited.add(s)
+            q.append((s, 0))
+
+    truncated = False
+    while q:
+        fid, hop = q.popleft()
+        if len(nodes) >= max_fields:
+            truncated = True
+            break
+        node = scan_fn(fid)
+        info = {
+            "zone": zone_fn(fid), "found": bool(node.get("found")),
+            "edges": node.get("edges", []), "overworld_exits": node.get("overworld_exits", []),
+            "encounter": node.get("encounter"), "music": node.get("music"), "hop": hop,
+        }
+        nodes[fid] = info
+        if not info["found"]:
+            continue
+        walkin_targets = {int(e["to"]) for e in info["edges"] if e["kind"] == WALK_IN}
+        for e in info["edges"]:
+            to = int(e["to"])
+            kind = e["kind"]
+            if kind == OVERWORLD:
+                continue                                   # never a graph edge (it's an overworld loc id)
+            tzone = zone_fn(to)
+            if kind == SCRIPTED and not follow_scripted:
+                if to not in walkin_targets:               # don't double-report a connection that's
+                    seams.append({"from": fid, "to": to, "entrance": e.get("entrance"),  # also a real door
+                                  "trigger": e.get("trigger"), "to_zone": tzone})
+                continue
+            if to in visited:
+                continue
+            if not forkable_fn(to):                        # shop/menu / variant / no-background id:
+                unforkable.append({"from": fid, "to": to})  # can't fork a room -- classify before zone test
+                continue
+            reason = None
+            if restrict is not None and to not in restrict:
+                reason = "not-in-set"                       # --ids: outside the explicit cluster -> a portal
+            elif to in stop_at:
+                reason = "stop-at"
+            elif allowed is not None and tzone not in allowed:
+                reason = f"zone:{tzone}"
+            elif to in deny:
+                reason = "denylist"
+            elif hop + 1 > max_hops:
+                reason = "max-hops"
+            if reason:
+                portals.append({"from": fid, "to": to, "kind": kind, "to_zone": tzone, "reason": reason})
+                continue
+            visited.add(to)
+            q.append((to, hop + 1))
+
+    # when truncated we broke right after popping an unprocessed field, so it counts as unexplored too
+    return GraphResult(
+        nodes=nodes, portals=portals, seams=seams, unforkable=unforkable, seeds=seeds,
+        allowed_zones=allowed, truncated=truncated, remaining=(len(q) + 1 if truncated else 0),
+        bounds={"max_hops": max_hops, "max_fields": max_fields, "zones": list(zones) if zones else None,
+                "follow_scripted": follow_scripted, "stop_at_zone_boundary": stop_at_zone_boundary,
+                "restrict_ids": sorted(restrict) if restrict is not None else None},
+    )
+
+
+def zone_coverage(result: GraphResult, zone_members_fn) -> dict:
+    """How much of each touched zone the walk actually forked: ``{zone: (reached, total, [unreached_ids])}``.
+    ``zone_members_fn(zone)`` -> the set of ALL forkable field ids in that zone (the static FBG table). A low
+    ratio flags an ISOLATED seed -- e.g. Evil Forest seeded at 152 forks 1 of 13 (the rest aren't door-reachable
+    from that screen). PURE: the membership comes from a callback so :mod:`chain` stays game-free. Only zones the
+    walk forked at least one field in are reported (the seed's own zone(s) + any followed neighbour)."""
+    forked_by_zone: dict = {}
+    for fid, info in result.nodes.items():
+        if info.get("found"):
+            forked_by_zone.setdefault(info["zone"], set()).add(int(fid))
+    out: dict = {}
+    for zone, forked in forked_by_zone.items():
+        total = {int(x) for x in (zone_members_fn(zone) or ())}
+        unreached = sorted(total - forked)
+        out[zone] = (len(forked & total) if total else len(forked), len(total), unreached)
+    return out
+
+
+def render_coverage(coverage: dict) -> list:
+    """Lines flagging under-forked zones (reached < total) -- the 'isolated seed' hint. ``[]`` if every touched
+    zone is fully covered (e.g. a --whole-zone fork)."""
+    lines: list = []
+    for zone, (reached, total, unreached) in sorted(coverage.items()):
+        if total and reached < total:
+            shown = ", ".join(map(str, unreached[:12])) + (" ..." if len(unreached) > 12 else "")
+            lines.append(f"  zone {zone}: forked {reached} of {total} forkable fields -- {len(unreached)} "
+                         f"NOT door-reachable from the seed ({shown}). Try --whole-zone (or a connected seed).")
+    return lines
+
+
+def _walkin_summary(info):
+    """('->' destinations with x{n} stacking, story_conditional?) for a node's walk-in edges."""
+    counts: "OrderedDict" = OrderedDict()
+    cond = False
+    for e in info["edges"]:
+        if e["kind"] != WALK_IN:
+            continue
+        counts[e["to"]] = counts.get(e["to"], 0) + 1
+        cond = cond or bool(e.get("story_conditional"))
+    parts = [f"{to}(x{n})" if n > 1 else str(to) for to, n in counts.items()]
+    return parts, cond
+
+
+def _dedup(rows, keys):
+    seen, out = set(), []
+    for r in rows:
+        k = tuple(r.get(x) for x in keys)
+        if k not in seen:
+            seen.add(k)
+            out.append(r)
+    return out
+
+
+def render(result: GraphResult, label_fn=None, coverage=None) -> str:
+    """A human-readable scoping report for ``--dry-run``: per-zone node lists, inter-zone portals,
+    scripted seams, overworld exits, and a blast-radius line. ``label_fn(id)`` -> a display name. ``coverage``
+    (from :func:`zone_coverage`) adds an 'isolated seed' hint when a touched zone is under-forked."""
+    label_fn = label_fn or (lambda i: "")
+    b = result.bounds
+    zstr = ",".join(b["zones"]) if b["zones"] else ("seed-zone" if b["stop_at_zone_boundary"] else "any")
+    out = [f"import-chain from {', '.join(map(str, result.seeds))}   zones={zstr}  "
+           f"max-hops={b['max_hops']}  max-fields={b['max_fields']}  follow-scripted={b['follow_scripted']}",
+           ""]
+
+    by_zone: "OrderedDict" = OrderedDict()
+    for fid, info in result.nodes.items():
+        by_zone.setdefault(info["zone"], []).append((fid, info))
+    for z, items in by_zone.items():
+        out.append(f"ZONE {z} - {len(items)} field(s)")
+        for fid, info in items:
+            lbl = label_fn(fid) or ""
+            if not info["found"]:
+                out.append(f"  {fid:<5} {lbl}  [no script / world field]")
+                continue
+            parts, cond = _walkin_summary(info)
+            arrow = ("-> " + ", ".join(parts)) if parts else "(no walk-in exits)"
+            tags = []
+            if info.get("encounter"):
+                tags.append(f"enc:{info['encounter']['scenes'][0]}")
+            if info.get("music") is not None:
+                tags.append(f"music:{info['music']}")
+            if info.get("overworld_exits"):
+                tags.append(f"wm:{len(info['overworld_exits'])}")
+            if cond:
+                tags.append("STORY-COND")
+            out.append(f"  {fid:<5} {lbl:<30} {arrow}" + (("   " + " ".join(tags)) if tags else ""))
+        out.append("")
+
+    portals = _dedup(result.portals, ("from", "to", "reason"))
+    if portals:
+        out.append("PORTALS (edges out of scope -- where this region connects onward):")
+        for p in portals:
+            out.append(f"  {p['from']} -> {p['to']:<5} [{p.get('to_zone','?')}]  ({p['kind']}; {p['reason']})")
+        out.append("")
+
+    seams = _dedup(result.seams, ("from", "to"))
+    if seams:
+        out.append("SCRIPTED SEAMS (teleports -- not followed; author by hand):")
+        for s in seams:
+            ent = s.get("entrance")
+            ent_str = str(ent) if isinstance(ent, int) and 0 <= ent <= 999 else "?"  # best-effort in cutscenes
+            out.append(f"  {s['from']} -> {s['to']:<5} [{s.get('to_zone','?')}]  "
+                       f"trigger:{s['trigger']} entrance:{ent_str}")
+        out.append("")
+
+    unfork = _dedup(result.unforkable, ("to",))
+    if unfork:
+        out.append("MENU / NON-FIELD TARGETS (no background in the FBG table -- shops/menus, variants, "
+                   "cutscene-only; not forkable as rooms):")
+        for u in unfork:
+            out.append(f"  {u['from']} -> {u['to']:<5} {label_fn(u['to']) or ''}")
+        out.append("")
+
+    wm = [fid for fid, info in result.nodes.items() if info.get("overworld_exits")]
+    if wm:
+        out.append("OVERWORLD EXITS (screens that leave to the world map): " + ", ".join(map(str, wm)))
+        out.append("")
+
+    cov_lines = render_coverage(coverage) if coverage else []
+    if cov_lines:
+        out.append("UNDER-FORKED ZONES (fields in the zone the seed can't door-reach -- the bytes are there):")
+        out.extend(cov_lines)
+        out.append("")
+
+    nwalk = sum(1 for info in result.nodes.values() for e in info["edges"] if e["kind"] == WALK_IN)
+    status = (f"TRUNCATED at max-fields={b['max_fields']} ({result.remaining}+ more queued -- "
+              f"raise --max-fields or narrow --zones)") if result.truncated else "complete"
+    out.append(f"BLAST RADIUS: {len(result.nodes)} fields, {len(by_zone)} zone(s), {nwalk} walk-in edges, "
+               f"{len(seams)} scripted seams, {len(unfork)} menu/non-field, {len(portals)} portals.  [{status}]")
+    return "\n".join(out)