settled-reach/docs/architecture/implant-app-pattern.md

# Implant App Pattern

**Status:** Proposed — introduced in Sprint 36 atlas refactor (#844). `implant_app.gd`, `implant_nav_stack.gd`, `implant_app_manifest.gd`, and `implant_registry.gd` land alongside the atlas split. Economics panel is migrated in the same PR as the second reference implementation.

## Context

The implant is the diegetic frame for every HUD tool the player carries — map atlas, economics monitor, Drifter's Guide reader (GTTR), knowledge journal, and anything we add later. These are not ad-hoc panels. They share z-index rules (D-170), a component library (D-169), an input model (one app active at a time, others occluded or hidden), and a visual identity.

The useful mental model: treat the implant as a **faux mobile OS**.

| Mobile OS concept  | Implant equivalent                               | State                        |
|--------------------|--------------------------------------------------|------------------------------|
| Window manager     | `HudGroups` autoload (D-170)                     | Exists                       |
| UIKit / widget set | D-169 component library (`ImplantPanel`, etc.)   | Exists                       |
| Activity / App     | `ImplantApp` base class                          | **Introduced here**          |
| Manifest / Info.plist | `ImplantAppManifest` resource + `app.tres`    | **Introduced here**          |
| Nav controller     | `ImplantNavStack`                                | **Introduced here**          |
| Intent dispatcher  | (planned — cross-app routing)                    | Seam sketched, not built yet |
| PackageManager     | `ImplantRegistry` autoload                       | **Introduced here** (in-tree scan only) |
| Mod SDK / .ipa     | pck-mounted app bundles, signing                 | Deferred (Phase 6+)          |

This document specifies the four pieces landing now and the seams left open for the deferred pieces.

## Design drivers

1. **Cargo-cult elimination.** Every implant app currently re-implements ~30 LOC of boilerplate: anchoring, `visible = false`, `MOUSE_FILTER_STOP`, `HudGroups.register`, `app_changed` filtering, `set_insert_active`, `toggle_visible`. Drift between apps is already visible — the atlas and economics panel handle `INSERT` mode differently. Absorb all of it into a base class.
2. **Moddability as first-class driver.** A modder or content author writes a self-contained app directory, drops it under `client/ui/implant/apps/`, and the implant discovers and registers it at startup. **No core-code edits required to ship a new app.** This constraint shapes every downstream choice — manifest format, key-binding routing, data-channel seam, inter-app signalling.
3. **Intra-app navigation without ad-hoc enums.** The atlas ships a `Level` enum and manual screen management. Each new app repeating that invention is wrong. One nav primitive, reused.

## The Manifest — file-based discovery

Each app directory contains an `app.tres` (Godot `Resource`) declaring the app's identity and capabilities. At startup, `ImplantRegistry` scans `res://ui/implant/apps/*/app.tres` and builds the installed-app registry. **This scan is the seam that later extends to mod discovery** — once we mount modded pck files under a known path, the same scan finds their manifests.

```gdscript
# client/ui/implant/implant_app_manifest.gd
extends Resource
class_name ImplantAppManifest

@export var schema_version: int = 1        # bump on breaking manifest changes
@export var app_path: String = ""          # unique HudGroups id, e.g. "implant/map"
@export var scene_path: String = ""        # res:// path to the app's root scene (empty = metadata-only)
@export var default_mode: String = "fullscreen"  # "gameplay" | "insert" | "fullscreen"
@export var default_key: int = -1          # e.g. KEY_M = 77; -1 = no default binding
@export var preserves_state: bool = true   # keep nav stack across close/open
```

**`schema_version`** lets the registry differentiate mods built against older or newer manifest shapes. `ImplantRegistry.CURRENT_SCHEMA_VERSION` names the version the current build understands. On scan:
- `schema_version == CURRENT`: silent, proceed normally.
- `schema_version < CURRENT`: `print_verbose("backfilled from v{n}")`, proceed with field defaults.
- `schema_version > CURRENT`: `push_warning("proceeding best-effort")`, proceed.

Reject-on-unknown is deliberately avoided — forward tolerance matters more than strict validation in a modded context. An app that relies on a field the build does not understand may malfunction at runtime; that failure is traceable via the warning.

**`default_mode`** is a string (`"gameplay"` / `"insert"` / `"fullscreen"`) rather than the raw `HudGroups.Mode` int, because editing enum ints in `.tres` is fragile. The registry resolves the string to `HudGroups.Mode` via `ImplantRegistry.get_resolved_mode(app_path)`; invalid strings skip the manifest with a warning.

`display_name` and `icon_path` are intentionally omitted at this stage — they add surface without callers. Add them only when a launcher UI needs them.

Keeping the manifest declarative — a `Resource`, not a script — means the installed-app list is data. Mod authors don't need to touch GDScript to register. The scan output can be cached. Validation happens in one place.

## Generic key routing in `main.gd`

Today (`main.gd`:180ish):

```gdscript
if event.keycode == KEY_M:
    atlas_panel.toggle_visible()
elif event.keycode == KEY_N:
    economics_panel.toggle_visible()
```

Every new app requires a `main.gd` edit. Fatal for moddability. Replace with a registry-driven router:

```gdscript
for manifest in ImplantRegistry.get_manifests():
    if manifest.default_key == event.keycode:
        HudGroups.toggle_app(manifest.app_path, manifest.default_mode)
        return
```

Adding a new app = drop directory, restart, done.

**Key-binding collision policy for this sprint:** first-wins, warn on startup. Future sprint: settings UI to remap.

## `ImplantApp` base class

Absorbs every piece of cargo-culted boilerplate. Each app's shell extends `ImplantApp` and overrides lifecycle hooks instead of reinventing infrastructure.

```gdscript
# client/ui/implant/implant_app.gd
class_name ImplantApp
extends Control

var manifest: ImplantAppManifest = null
var nav: ImplantNavStack = null

var _screens: Dictionary = {}      # screen_id → Control
var _current_screen_id: String = ""

signal app_opened(mode: int)
signal app_closed

func _ready() -> void:
    set_anchors_preset(Control.PRESET_FULL_RECT)
    mouse_filter = Control.MOUSE_FILTER_STOP
    visible = false

    if manifest:
        HudGroups.register(self, manifest.app_path)
    HudGroups.app_changed.connect(_internal_app_changed)

    nav = ImplantNavStack.new()
    nav.screen_changed.connect(_on_screen_changed)
    add_child(nav)

    on_install()

# --- Internal wiring — do not override ---

func _internal_app_changed(app_path: String, mode: int) -> void:
    if manifest == null:
        return
    if app_path != manifest.app_path:
        if visible:
            visible = false
            on_close()
            app_closed.emit()
        return

    match mode:
        HudGroups.Mode.FULLSCREEN, HudGroups.Mode.INSERT:
            if not visible:
                visible = true
                if not manifest.preserves_state:
                    nav.reset_to_default()
                elif nav.is_empty():
                    nav.push_default()
                on_open(mode)
                app_opened.emit(mode)
        HudGroups.Mode.GAMEPLAY:
            if visible:
                visible = false
                on_close()
                app_closed.emit()

# --- Screen management (base-owned) ---

## Register a screen under an id. Base adds it as a child and starts it hidden.
## Call from on_install(). Wire signals BEFORE calling register_screen.
func register_screen(id: String, screen: Control) -> void:
    # Warns + returns on duplicate id; base-parents if unparented; forces visible = false.
    ...

func current_screen_id() -> String:
    return _current_screen_id

## Default screen-swap. Base handles leave/hide/enter/show with has_method tolerance
## and skips leave/hide when replacing the same screen id (payload-only update).
## Subclasses rarely override.
func _on_screen_changed(new_id: String) -> void:
    # See implant_app.gd for the full body.
    ...

# --- Lifecycle hooks — subclasses override ---

func on_install() -> void: pass                      # once, after _ready
func on_open(_mode: int) -> void: pass               # every transition to visible
func on_close() -> void: pass                        # every transition to hidden
func on_insert_deactivated() -> void:                # SnapshotConsumers calls this
    # Default: closes the app if it is active in INSERT mode. FULLSCREEN apps inherit no-op.
    pass
func handle_intent(_action: String, _params: Dictionary) -> void: pass  # future — Intents
```

**What the subclass is responsible for:**
- Loading its own manifest in `_ready()` before calling `super._ready()`.
- In `on_install`: constructing screens, calling `setup`/signal wiring on them, then `register_screen(id, screen)`. Setting `nav.set_default(id)` once.
- Reading state via `current_screen_id()`, emitting app-specific signals, handling app-specific input.

**What the subclass is *not* responsible for:**
- `HudGroups` wiring. Ever.
- `visible` management (app-level or screen-level). Ever.
- Anchor / mouse-filter boilerplate. Ever.
- `add_child` on registered screens. `register_screen` handles parenting.
- `_current_screen_id` bookkeeping. The base owns it.
- Enter/leave dispatch. The default `_on_screen_changed` drives it; screens that need enter/leave implement those methods, the base invokes them via `has_method` tolerance.

### Lifecycle hooks

The four hooks fire in a defined order with a defined nav-stack guarantee at each point. Subclasses can rely on this contract without inspecting `HudGroups` state directly.

| Hook | When it fires | Nav stack state when it fires | Intended use |
|------|--------------|-------------------------------|--------------|
| `on_install()` | Once, from `_ready()`, after nav is created | **Empty.** No screens have been pushed yet. | Construct screens; call `register_screen(id, screen)`; call `nav.set_default("...")`. Wiring only — do not read `nav.current()`. |
| `on_open(mode)` | Every activation (FULLSCREEN or INSERT) | **Non-empty.** Base ensures: `preserves_state=false` → `reset_to_default()` called; `preserves_state=true` and stack was empty → `push_default()` called; `preserves_state=true` and stack non-empty → untouched. | Data refresh; announce current screen; start animations. `nav.current()` is safe here. |
| `on_close()` | Every deactivation (GAMEPLAY or different app takes focus) | Stack preserved — base does not mutate it. | Pause timers; stop high-frequency feeds; save scroll position. Do **not** push or pop — the stack survives for the next `on_open`. |
| `on_insert_deactivated()` | SnapshotConsumers calls this when server drops insert state | Whatever `on_close()` left it (if the app was already closed) or the live state (if the app is still open) | Base default: close if active in INSERT mode, no-op otherwise. FULLSCREEN apps override. Do not call `close_app()` manually — call `super()` or replicate the guard. |

**Why `on_install` sees an empty stack:** `_ready()` fires bottom-up — children before parents. The base's `_ready()` creates `nav` and then calls `on_install()` synchronously. No `HudGroups.app_changed` signal has fired yet (that comes from `open_app()`, which requires the game to be running). Subclasses that call `nav.current()` in `on_install` always see `""` — which is always wrong. The right pattern is to call `nav.set_default("my_first_screen")` in `on_install` and let the base push it on the first `on_open`.

**Why `on_close` must not push/pop:** The nav stack is the in-flight navigation position that survives across close/reopen cycles (when `preserves_state=true`). Mutating it in `on_close` destroys the user's position. If an app needs to reset navigation on close, set `preserves_state=false` in the manifest instead — the base handles the reset at the top of `on_open`, which is the right moment.

## `ImplantNavStack` — intra-app navigation

Apps push and pop screens. The stack is owned by `ImplantApp` (one per app instance — no global nav state).

```gdscript
# client/ui/implant/implant_nav_stack.gd
class_name ImplantNavStack
extends Node

signal screen_changed(current_screen_id: String)

var _stack: Array[String] = []
var _payloads: Array[Dictionary] = []
var _default_screen_id: String = ""

func set_default(screen_id: String) -> void
func push(screen_id: String, payload: Dictionary = {}) -> void
func pop() -> void
func replace(screen_id: String, payload: Dictionary = {}) -> void
func reset_to_default() -> void
func is_empty() -> bool
func push_default() -> void
func current() -> String
func current_payload() -> Dictionary
```

**Mutation is synchronous.** `push()` updates `_stack`, emits `screen_changed` before returning. The shell's handler synchronously calls `enter(payload)` on the new screen and `leave()` on the previous one. No `call_deferred` races; a frame always ends with a coherent nav state.

**Screens are plain `Control` nodes, registered via `ImplantApp.register_screen(id, screen)`.** Subclass `on_install` constructs each screen, wires its signals, and calls `register_screen` — base handles `add_child` and `visible = false`. Screens never touch `HudGroups`, `APP_PATH`, `app_changed`, or their own visibility. They only emit nav signals back to the shell (e.g. `select_system(system_id)`), and the shell translates to `nav.push("system", {...})`.

Screens optionally expose:

```gdscript
func enter(payload: Dictionary) -> void      # called when pushed or re-surfaced
func leave() -> void                          # called when popped or superseded
```

The base's default `_on_screen_changed` invokes these via `has_method` — screens that need neither don't ship stubs. The base also detects same-screen-replace (`nav.replace("system", new_payload)` while already on `"system"`) and re-enters with the fresh payload without calling `leave` first. Atlas exercises this on the reach → system-picker → system-orbital transition.

### Nav-stack edge cases

Behavior defined by the base class — subclasses do not re-implement these.

- **`open_app()` with `preserves_state = false`:** stack cleared, default screen pushed. State-free apps never surprise the user with stale context.
- **`open_app()` with `preserves_state = true`, empty stack:** default screen pushed. Typical first-ever-open case.
- **`open_app()` with `preserves_state = true`, non-empty stack:** no mutation — app re-opens on the screen the user was last viewing. This is the atlas case (reopen on the body you were looking at).
- **`push()` / `pop()` / `replace()`:** synchronous. Stack mutates inside the call; `screen_changed` fires before the call returns; the shell's `_on_screen_changed` handler swaps the visible screen via `enter` / `leave` synchronously. No frame-boundary coherence issues.
- **Stack ownership:** each `ImplantApp` instance owns exactly one `ImplantNavStack`. No shared nav state across apps. Cross-app navigation goes through Intents (below), not through a shared stack.
- **Popping an empty stack:** no-op; log a warning. Preserves the invariant that a visible app always has at least one screen.

## Inter-app navigation — Intents (seam only)

Economics → Atlas linking is the first real case. Today it's handled by a direct signal `economics_link_requested(planet_id)` wired in `main.gd`. Hardcoded routing between named apps is fatal for modded apps — a modded atlas replacement or a modded economics replacement can't receive the signal.

The target pattern:

```gdscript
# emitted by any app's shell:
signal intent_requested(target_app: String, action: String, params: Dictionary)

# economics app emits:
intent_requested.emit("implant/map", "focus_planet", {"planet_id": id})
```

An intents dispatcher (sibling of `ImplantRegistry`) routes the intent to the target app's shell, calling `handle_intent(action, params)` which the registered target app overrides.

**This sprint: keep the existing `economics_link_requested` wiring.** The base class exposes `handle_intent` as a no-op hook so subclasses don't need rewiring once the dispatcher lands. Refactor to Intents is mechanical and can happen in a small follow-up PR.

## Data channels — seam flagged

Modded apps will want to subscribe to simulation data: observer snapshots, entity events, region-filtered feeds, periodic economics rollups. Today, apps reach into `GameState` and `SnapshotConsumers` directly.

**This sprint: no change.** Apps continue to use the direct path.

**Future seam:** a `DataChannels` autoload apps subscribe to by channel name, with manifest-declared requirements:

```gdscript
# in app.tres
@export var subscribed_channels: Array[String] = ["snapshot/observer", "economics/rollup"]
```

The registry wires subscriptions on `on_install`. Modded apps get their data through a documented API rather than poking core globals. **Not implemented this sprint — flagged so the base-class API doesn't accidentally close the door.** Specifically: `on_install` is the right hook for channel subscription; `on_close` is not where channels get unsubscribed (an app stays subscribed while hidden). Binding subscription lifetime to app instance lifetime, not visibility, is the right shape.

## D-169 component library — keep, hands off

`ImplantPanel`, `ImplantHeader`, `ImplantSeparator`, `ImplantDataRow`, `ImplantTextBlock` are already modder-friendly — pure `Control` nodes styled via `default_implant.tres`. Modded apps compose with them exactly like in-tree apps.

**Flagged risk:** if any primitive grows a dependency on a specific in-tree data model (e.g. `ImplantDataRow` taking a `CurrencyAmount`-typed parameter instead of a generic string), moddability regresses. **Rule: keep primitives data-shape agnostic.** Adapters live in each app, not in the shared library.

## Directory layout

```
client/ui/implant/
  default_implant.tres           # D-169 theme
  implant_panel.gd               # D-169 primitives — unchanged
  implant_header.gd
  implant_separator.gd
  implant_data_row.gd
  implant_text_block.gd
  implant_theme.gd
  implant_app.gd                 # NEW — base class
  implant_nav_stack.gd           # NEW — nav helper
  implant_app_manifest.gd        # NEW — manifest resource class
  implant_registry.gd            # NEW — autoload; scans apps/ at startup
  widgets/                       # shared cross-app widgets
    # (future: reach_map_widget.gd once extracted from atlas)
  apps/
    atlas/
      app.tres                   # manifest: app_path=implant/map, default_key=KEY_M
      atlas_app.gd               # extends ImplantApp — owns nav + shared header
      atlas_app.tscn             # root scene
      atlas_marker_overlay.gd    # moved from implant/
      atlas_overlay_bar.gd
      atlas_viewer.gd
      screens/
        reach_screen.gd          # plain Control; enter/leave; emits nav signals
        system_screen.gd
        planet_screen.gd
        regional_screen.gd
    economics/
      app.tres                   # manifest: app_path=implant/economics, default_key=KEY_N
      economics_app.gd           # extends ImplantApp
      economics_app.tscn
      screens/
        overview_screen.gd       # currently the only screen; keep the directory shape
```

Autoload order: `implant_registry` must scan before `main.gd` queries manifests for key routing. Manifest scan is lazy-on-first-read to sidestep the `class_name` autoload parse-order trap documented in `CLAUDE.md`.

## Phasing

### Landed — Sprint 36 #844 and review rounds

- `implant_app.gd`, `implant_nav_stack.gd`, `implant_app_manifest.gd` — new classes
- `implant_registry.gd` — autoload; lazy-scans `apps/*/app.tres` on first `get_manifests()` call, exposes `get_manifests()`, `get_resolved_mode()`, `instantiate_all(parent)`, `get_app_instance(app_path)`
- Manifest `schema_version` field with `ImplantRegistry.CURRENT_SCHEMA_VERSION = 1`; tiered warn/backfill/proceed behavior
- `scene_path` consumed: `ImplantRegistry.instantiate_all($AppsContainer)` called from `hud.gd._ready()`. `hud.tscn` no longer direct-instances apps — holds only the `AppsContainer` placement node. `main.gd` looks up app instances via `ImplantRegistry.get_app_instance(app_path)`.
- `main.gd` key routing replaced with registry-driven loop; `KEY_M` / `KEY_N` literals removed
- `ImplantApp` base owns `_screens` / `_current_screen_id`; `register_screen(id, screen)` + `current_screen_id()` + default `_on_screen_changed` with `has_method` tolerance and same-screen-replace detection
- Atlas: split into `apps/atlas/` with `atlas_app.gd` + per-screen `Control`s. `Level` enum replaced by nav-stack screen ids. `on_install` is construct → setup → wire → `register_screen` per screen.
- Economics: relocated to `apps/economics/economics_app.gd`, refactored to `extends ImplantApp`; `on_install` reduced to three lines (construct overview_screen, register_screen, nav.set_default)
- Both apps ship `schema_version = 1` manifests
- `SnapshotConsumers` calls `on_insert_deactivated()` uniformly; the base's default closes the app when active in INSERT mode
- Legacy `implant/map/starchart` HudGroups path deleted
- `hud.gd`: single `_ready()` call to `ImplantRegistry.instantiate_all($AppsContainer)` seeds all registered apps; Godot's bottom-up `_ready` ordering guarantees `main.gd` finds them when it looks up by `app_path`

### Follow-up (not this sprint, not blockers)

- **Intents dispatcher** — replace `economics_link_requested` with generic `intent_requested` routing. Mechanical refactor.
- **`DataChannels` autoload** — manifest-declared snapshot subscriptions. Seam already reserved via `on_install` lifecycle position.
- **Launcher UI** — once a fourth implant app exists, a chooser becomes necessary. Until then, key bindings suffice.
- **Settings-UI key remapping** — resolves key-binding collisions beyond first-wins.
- **`handle_global_key` lifecycle hook** — new `ImplantApp` override; shells handle intra-app keys (e.g. economics `[`/`]` system navigation). Main.gd routes unhandled keydown to the active app instead of hardcoding per-app bindings.

### Deferred (Phase 6+, not sprint-scoped)

- Shipped-build mod discovery (pck mounting, manifest signing, trust model)
- Scripting API surface — what mods can safely call into core
- Mod registry UI — enable/disable, conflict resolution, version compatibility

## Review checklist — for future PRs adding a new implant app

- [ ] App directory lives under `client/ui/implant/apps/{name}/` with `app.tres`, `{name}_app.gd`, `{name}_app.tscn`
- [ ] Manifest includes `schema_version: int = 1` (or higher if manifest schema has bumped)
- [ ] Manifest `default_mode` is one of `"gameplay"`, `"insert"`, `"fullscreen"`
- [ ] Manifest `app_path` is unique; `default_key` either -1 or non-colliding
- [ ] App script `extends ImplantApp`; its `_ready()` assigns `manifest = load("res://ui/implant/apps/{name}/app.tres")` then calls `super._ready()`
- [ ] `on_install` constructs and `register_screen`s each screen; sets `nav.set_default("...")` once. No direct `add_child` on screens; no `.visible =` on screens; no `_current_screen_id` field.
- [ ] Screens are plain `Control`s. They optionally define `enter(payload)` / `leave()`. They do not touch `HudGroups`, `APP_PATH`, or `app_changed`.
- [ ] Nothing in `hud.tscn` direct-instances the new app. Discovery happens via the registry.
- [ ] No `KEY_*` literals in `main.gd` tied to the new app — rely on `default_key` in the manifest.
- [ ] Cross-app wiring (if any) stays on a named signal today; migrate to `handle_intent` when Intents dispatcher lands.

## Risks / open items

- **Manifest scan load cost.** Cheap in-tree but becomes load-time-variable once modded apps enter the mix. Flag for profiling once registered apps > ~10.
- **Autoload parse-order.** `implant_registry` must defer `class_name ImplantAppManifest` resolution to first `get_manifests()` call rather than `_ready()`. See `CLAUDE.md` "Autoload parse-order rule."
- **Manifest validation.** An invalid `app.tres` (missing fields, bad paths) in a modded app must not crash startup. Warn, skip, continue.
- **Scene-vs-script coupling.** The manifest points at `scene_path`; the shell script is loaded from the scene's root node. If a modder ships a scene with the wrong root script, failures should be diagnosable. Flagged for the eventual mod SDK docs.