--- name: fo3-pipboy-program description: "THE FO3 PIP-BOY PROGRAM — the locked design (landscape = true Pip-Boy, portrait = legacy view), the design thesis, the sub-tab mapping, the edit-survives rule, and the reasoning behind extracting the skin abstraction from two real machines rather than pre-building it" metadata: node_type: memory type: project originSessionId: 0b7c5f41-bb34-4ab4-93be-fdb363f5eb40 --- ✅ **THE OWED EXTRACTION PASS WAS RUN AND CLOSED — 2026-07-15.** Dispatch owned it as promised. Write-up: `planning/SKIN_ARCHITECTURE_EXTRACTION.md` (analysis-only, evidence-grepped). **The verdict — the answer to the owner's question — is that the architecture is SOUND:** FO3's entire divergence turned out to be a **pure CSS override layer** living in its own file, with the shared render/state/API pipeline carrying **no game-name branches at all** (per-game behavior flows through the identity lookup), one shared render path, no per-game render forks. **The "dead DOM accumulates per game" fear was DISPROVEN** — so keep chrome as per-game CSS in its own file rather than injecting it at boot. **For the next game:** the reskin half is a clean **file drop**; the re-body half needs ONE scoped unit *only if* that game takes the Pip-Boy body — re-keying the shell selectors from a game-specific hook to a **machine-specific** one (which finally wires the already-declared-but-dead machine/structural-mode identity fields — the one real "anticipated-but-unwired" strain). A flat-view-only game is a pure file drop. See [[data-provenance-program-complete]] for the sibling data work. ⭐ **LOCKED WITH THE OWNER 2026-07-12** in a long brainstorm (no sessions dispatched during it — he asked to think it through first). This supersedes the earlier "FO3 bezel reskin" framing entirely. ## The premise — NOT a reskin Per [[per-game-device-form]]: **NV = a salvaged RobCo desk TERMINAL you operate. FO3 = the Pip-Boy 3000 ITSELF** — a wrist unit; the data is native to the device. Three earlier Fable passes were REJECTED by the owner. His verdicts, verbatim: - *"the bezel definitely isn't a pip boy"* (it solved mobile by deleting the device — chrome that "only spends pixels it earns" meant NO device on the phone, the one surface he uses). - *"more like the NV terminal bezel with extra stuff slapped onto it — with pipboy stuff slapped"*. ⚠ **DISPATCH'S OWN FAULT, RECORDED:** I briefed "keep the same DOM / same nav structure," so Fable reskinned the NV shell. **The two devices shared a SKELETON — a rectangular screen, a frame, and a row of evenly-spaced keys along the bottom.** Change the metal and the colour and it is *still the same shape*. **A different machine needs a different skeleton, not different paint.** ## ⭐ THE DESIGN THESIS (the deepest idea in the thread — keep it) > **NV puts the machinery ON THE GLASS. FO3 puts it IN THE CASING.** NV's screen is full of physical instruments (the fader board, the weigh bridge, the tempo dial, the reputation console). The real Pip-Boy screen is the **exact opposite: austere.** Flat green text, boxed outlines, dash-connected rails, `▲▼` arrows, plain-text actions with a symbol (`Equip ✕`, `Drop ◯`). **No chrome on the glass at all** — because all the tactility moved into the BODY (the knob, gauge, roller, lamps, toggle). *That* is where you touch the machine. ⇒ FO3's controls get **simpler**, not more elaborate. Faster to build AND more faithful. ## THE LOCKED DECISIONS (owner answered each) 1. **LANDSCAPE = the true Pip-Boy, and it is the PRIMARY FO3 view** (*"we will use landscape for fo3 most of the time"*). ⭐ **The insight that unlocked everything: the Pip-Boy screen is LANDSCAPE; a phone is PORTRAIT. You CANNOT faithfully render a landscape CRT in a portrait viewport.** Every earlier compromise came from fighting that. Rotating is not a workaround — it is *diegetic* (you turn your wrist to look at a Pip-Boy). 2. **PORTRAIT = THE LEGACY VIEW.** Not a squashed Pip-Boy — the honest flat layout. This kills the compromise object entirely. ⚠ **It also makes the legacy view LOAD-BEARING** (it was a dusty fallback; it is now how FO3 is used in portrait). It must be genuinely good. That work was scheduled after FO3 — it **moves INTO** the FO3 program. 3. **LIST + DETAIL** — the real Pip-Boy content pattern (list left, detail right, status strip top, sub-tab rail bottom). **But only where the content IS a list.** The real Pip-Boy is full-bleed for the map and for the Status figure. List-and-detail where it's a list; full-bleed where it isn't. That is faithful, not lazy. 4. **NV IS UNCHANGED. DIR IS CUT FROM FO3** (a directory listing is a *desk terminal* concept; a Pip-Boy has none). The a11y "flat fallback one tap away" promise still holds — the Pip-Boy's own structure is 3 buttons → sub-tab, never more than 2 taps deep. 5. **THE VAULT BOY FIGURE** (*"have it recreate the vault boy figure for limbs… if it can"*) — as **inline SVG**, zero-asset, themeable per game, an ORIGINAL figure in that style (not a traced copy). ## ⭐ THE SUB-TAB MAPPING — and why the groupings are MORE authentic, not compromises The app's boards collapse onto the Pip-Boy's five-per-tab structure: **OPERATOR → STATS:** - **STATUS** = vital telemetry + skeletal harness + status effects → HP, radiation, limb condition, active effects, **around a figure**. ⭐ *That IS the real Pip-Boy Status screen.* Three boards don't get crammed together — they BECOME the thing they were imitating. (⚠ This is a **genuinely NEW VIEW**, not a CSS rearrangement — real build work, and the single most Pip-Boy thing in the project.) - **S.P.E.C.I.A.L.** = the SPECIAL tuning board, 1:1. - **SKILLS** = the skill matrix (+ skill books/magazines as its read-tracker). - **PERKS** = perk loadout (+ traits). - **GENERAL** = position/clock + faction standing + karma alignment → FO3's real "General" tab **is** the karma/reputation screen. It already matches. **OPERATIONS → ITEMS:** MANIFEST · CRAFT · BARTER · SQUAD · CURIO. ⭐ The real Pip-Boy's item tabs (Weapons/Apparel/Aid/Misc/Ammo) are **drawers inside the manifest — which is already how the inventory works.** They become the filter row INSIDE the manifest tab. And the **weigh bridge needs no tab at all**: carry weight belongs in the **top strip** (`Wg 118/230`), exactly where the real one puts it. **DATABANK → DATA:** MAP · QUESTS · NOTES · LOG · QUERY. (Directive registry = Quests; cartography table = Map; field notes; campaign chronicle; catalog query. Service tally folds in.) **The other subsystems are CONTROLS ON THE BODY, not keys in a row** — this is what finally broke the twin-silhouette problem: **five *kinds* of control, not six identical keys.** UPLINK = the big ribbed radio knob (tuning it darkens all three lamps — a state the NV machine cannot express) · CHASSIS = the white-face red-needle gauge · SETTINGS = a flick toggle in its own pod · DIR = cut. ## ⚠⚠ THE HARD INVARIANT — EDITING SURVIVES **The real Pip-Boy is READ-ONLY (it displays a character the game owns). This app is the OPPOSITE: the player owns the truth and types it in as they play** ([[player-control-principle]]). A beautiful read-only Pip-Boy would stop being the tool and become a screensaver. > **RULE: if you can change it today, you can change it in the Pip-Boy.** Any board that can't honour that is FLAGGED, never quietly downgraded to read-only. ⚠ **AMENDED 2026-07-13 — the TAP-PARITY clause is REMOVED.** The rule originally read *"…in NO MORE TAPS than it takes now."* The owner struck that clause himself (*"Yes allow it, and remove that rule"*) when it collided with the approved mockup: the manifest's list+detail pattern costs **+1 tap on the first action per item** (select, then act; 1 tap thereafter), and the mockup he approved is built that way. **The mockup and the tap-parity clause simply contradicted each other, and he chose the mockup** — his complaint about the earlier version was always that it *looked* wrong, never that it was slow. Also accepted at the same time: **SKILLS loses drag-to-set** (typing and the ▲▼ steppers both survive, so tap count is unchanged). **WHAT SURVIVES, AND IT IS THE LOAD-BEARING HALF: nothing may become READ-ONLY.** Everything editable today stays editable in the Pip-Boy. That is the entire reason the device doesn't decay into a screensaver ([[player-control-principle]]) and it is NOT what was removed. **And tap-cost changes must still be DISCLOSED in a tap-delta table, never absorbed silently** — the tap count is no longer a hard gate, but it is still a number the owner gets told. ⭐ **And the real Pip-Boy already solves this** — the ITEMS detail pane shows `Equip ✕ / Drop ◯ / Repair △ / Hot Key`. **Actions, on the glass.** So master-detail is the natural HOME for the edit controls, not a threat to them. **Controls MAY be re-skinned per game** (owner: *"we don't have to keep the same steppers, drags, etc… I want each game to have its own skin"*). ⚠ But the FO3 control set must be **a small, coherent screen LANGUAGE** (`▲▼` steppers, boxed number fields, `[X]`/`[ ]` toggles), **NOT a hundred bespoke one-offs** — otherwise per-game control maintenance becomes a tax with no ceiling. NOTE: this does NOT contradict the NV "six ways to set a number is INTENTIONAL" ruling ([[parked-nv-overhaul-design-audit]]) — that ruling protects NV's custom 1-of-1 instruments; FO3 is a different machine with its own language. --- # ⭐⭐ THE REASONING BEHIND THE EXTRACTION — DO NOT LOSE THIS **Owner, verbatim: *"make sure you add/fold the extract part ya know? so I don't have to remind you since I'll probably forget."*** He will not remind you. **Dispatch owns follow-ups like this.** (This particular one was honoured — see the top of the file.) ## Decision taken: DO NOT pre-build the N-game skin framework. Build FO3 concretely FIRST, then EXTRACT the abstraction from two real machines. **Why — the reasoning matters more than the conclusion:** the existing per-game layer was built for **RESKINS, not RE-BODIES** — colours, strings, motion textures, boot flavour. It had never been asked to swap the *device*: different chrome, layout, nav grammar, control language, orientation behaviour. **FO3 was the first thing that actually stressed it.** You cannot build a good abstraction from **one** real example plus a **guess** (the next game being a design-only stub for something not playable yet). Pre-building the framework means generalising from one data point and inventing the second — near-certainly the wrong seams, torn out later. **Two genuinely different machines on the table reveal the real axes of variation.** This is the same call the owner already made in deferring the next game's panels: **don't build UI for data that doesn't exist.** ## ⇒ FOUR DISCIPLINES DURING ANY PER-GAME BUILD (cost nothing now; make the next game cheap later) 1. **NEVER hardcode a game name** — not in CSS, not in JS. Everything routes through the game attribute plus the identity data. 2. **Each game's skin gets its OWN CSS FILE** in the numbered cascade. A third game ADDS a file; it never edits a shared one. 3. **Every flavour string lives in the game's `identity` data** — never a CSS `content:` literal, never a JS string. 4. ⭐ **KEEP A RUNNING LIST — every single place someone is TEMPTED to fork per-game.** That list **IS** the specification for the abstraction, written from evidence rather than imagination. **This is the single most valuable artifact of the build.** ## ⇒ WHAT AN EXTRACTION PASS MUST ANSWER (the template, for the next machine) - Read the temptation list from discipline #4 — that is the input. - **Measure how much of the work was genuinely per-game vs shared.** ⭐ *That number IS the answer to the owner's question.* - Decide the real skin seams: is the chrome DOM per-game-in-the-page-and-CSS-gated, or injected/selected at boot the way the data-file manifest already works? **Prove it against two machines; don't assume.** - Output: whether the next game is a **file drop** or a **refactor** — known, not guessed. - Fold the result into the game definitions/identity layer, the architecture doc, the brain dump, and the queue. *Correction 2026-07-20: measured code metrics (line counts, selector and call-site counts, percentages), a commit hash, file names duplicated from `library/CODE_MAP.md`, protocol numbers and version pins were stripped from this file. Architecture belongs in `library/CODE_MAP.md`; rules in `CLAUDE.md` + `rules/`; roadmap in `QUEUE.md`. The design reasoning is untouched.* **Related:** [[roadmap-parked-placement]], [[design-overhaul-direction]], [[parked-diegetic-audit]] (the CLARITY VETO still applies to every label), [[engineering-metrics-log]], [[per-game-device-form]], [[player-control-principle]].