From 08c767f3991dc6d8c7fd89496af21293c5d8bbfd Mon Sep 17 00:00:00 2001
From: hypercross <helios.tnak@gmail.com>
Date: Sat, 8 Aug 2026 12:19:47 +0800
Subject: [PATCH] docs: update architecture and plan for tree inspector UI

Record the viewer-registry decision and refresh the extract/web
descriptions and repo layout.
---
 docs/architecture.md        |  4 ++--
 docs/decisions.md           | 19 ++++++++++++++++++-
 docs/implementation-plan.md | 16 +++++++++++++---
 3 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index b36df46..9adf36c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -47,8 +47,8 @@ apps/web ──► apps/proxy ──► packages/tts ──► packages/shared
 
 - **`apps/web` → `apps/proxy`** — calls `/search`, `/items/:id`, and
   `/items/:id/file` over HTTP.
-- **`apps/web` → `packages/extract`** — uses `flattenObjects` / `collectRefs`
-  to analyze a loaded `TTSMod` in the browser.
+- **`apps/web` → `packages/extract`** — uses `buildTree` / `collectRefs`
+  to analyze a loaded `TTSMod` in the browser (tree sidebar + asset refs).
 - **`apps/proxy` → `packages/tts`** — calls `fetchMod` / `getFileName` to serve
   item requests.
 - **`apps/proxy` → `packages/shared`** — uses shared types and zod schemas for
diff --git a/docs/decisions.md b/docs/decisions.md
index 256253b..6bff799 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -111,4 +111,21 @@ small amount of client state (search + mod).
 
 **Alternatives considered:** Next.js (heavier than needed for a client-only
 tool); Redux Toolkit (more boilerplate than warranted); CSS Modules (no
-utility styling).
\ No newline at end of file
+utility styling).
+
+## D10 — Object inspection via a viewer registry
+
+**Decision:** The mod page shows a containment-tree sidebar (mirroring how TTS
+nests objects) and an inspector pane. The inspector resolves a per-class viewer
+from a registry (`registerViewer` / `resolveViewer`), falling back to a
+`DefaultViewer` that renders an object's raw fields.
+
+**Context:** The user wants to visualize objects in a save. A flat list of all
+objects and assets is hard to navigate, so the UI was reworked around a tree
+and a selected-object inspector. Custom viewers per object class (`Card`,
+`Bag`, ...) are expected later; a registry keeps that extension point explicit
+without coupling the page to any one viewer.
+
+**Alternatives considered:** A single monolithic inspector component. Rejected —
+would grow unboundedly as per-class viewers are added; the registry keeps each
+viewer isolated and swappable.
\ No newline at end of file
diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md
index 43dd890..b7cee2d 100644
--- a/docs/implementation-plan.md
+++ b/docs/implementation-plan.md
@@ -78,7 +78,9 @@ tts-workshop/
 │           │   ├── SearchPage.tsx
 │           │   └── ModPage.tsx
 │           ├── components/
-│           │   └── SearchResults.tsx
+│           │   ├── SearchResults.tsx
+│           │   ├── ObjectTree.tsx     # containment-tree sidebar
+│           │   └── viewers.tsx        # viewer registry + default viewer
 │           └── stores/
 │               ├── searchStore.ts  # zustand
 │               └── modStore.ts     # zustand
@@ -145,6 +147,9 @@ Isomorphic analysis of a parsed `TTSMod`. No Node-specific APIs.
   - `flattenObjects(mod)` — all objects in the tree.
   - `filterObjects(mod, predicate)` — filter by name, GUID, type, etc.
   - `findObject(mod, guid)` — lookup by GUID.
+  - `buildTree(mod)` — containment tree (`{ object, label, children }`),
+    mirroring how TTS nests objects; `label` is `Nickname` when present,
+    else the class `Name`.
   - `traverseMod` / `markParent` (moved from `tts`).
   - Returns lightweight graph shapes: `{ guid, name, type, parentGuid,
     childrenGuids, refs }`.
@@ -195,9 +200,14 @@ proxy API and `packages/extract` directly for analysis.
   `modFileUrl` helper for the raw-file download.
 - `pages/SearchPage.tsx` — search form, drives `searchStore`.
 - `pages/ModPage.tsx` — loads the mod via `modStore`, uses `@tts/extract`
-  (`flattenObjects`, `collectRefs`) to render objects and asset refs, and links
-  to the raw save file.
+  (`buildTree`, `collectRefs`) to render a containment-tree sidebar and an
+  inspector pane for the selected object, and links to the raw save file.
 - `components/SearchResults.tsx` — result grid + pagination.
+- `components/ObjectTree.tsx` — recursive tree sidebar; each entry shows a
+  class tag + display label, indented by depth. Clicking selects an object.
+- `components/viewers.tsx` — viewer registry (`registerViewer` /
+  `resolveViewer`) plus a `DefaultViewer` that renders an object's fields;
+  custom per-class viewers can be registered later.
 - `stores/searchStore.ts` / `stores/modStore.ts` — Zustand stores for search
   and mod state.
 - `vite.config.ts` — dev proxy for `/search`, `/items`, `/health` →