From f01bb5f99b30744e4f883221e6ffaef55420aaa1 Mon Sep 17 00:00:00 2001
From: hypercross <helios.tnak@gmail.com>
Date: Fri, 14 Aug 2026 11:27:46 +0800
Subject: [PATCH] feat(web): rework mod inspector layout

Fill the viewport with a fixed sidebar of highlightable type-filter
icons over an independently scrolling tree, and let the viewer expand
into a full-height scene.
---
 apps/web/src/App.tsx                          | 12 ++-
 apps/web/src/components/ObjectTree.tsx        | 69 +++++++++-------
 apps/web/src/components/viewers.tsx           | 11 ++-
 .../web/src/components/viewers/CardViewer.tsx |  5 +-
 .../components/viewers/CustomModelViewer.tsx  |  5 +-
 .../web/src/components/viewers/DeckViewer.tsx | 19 ++++-
 apps/web/src/components/viewers/Scene.tsx     | 10 ++-
 .../web/src/components/viewers/TileViewer.tsx |  5 +-
 .../src/components/viewers/TokenViewer.tsx    |  5 +-
 apps/web/src/pages/ModPage.tsx                | 82 +++++++------------
 10 files changed, 123 insertions(+), 100 deletions(-)

diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 0b53aaa..b225c12 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -19,12 +19,17 @@ const SetupsPage = lazy(() => import('./pages/SetupsPage'));
 const SetupPage = lazy(() => import('./pages/SetupPage'));
 
 export default function App() {
-  const { pathname } = useLocation();
+  const pathname = useLocation().pathname;
   const isModRoute = pathname.startsWith('/mod/');
+  // The inspector view is full-bleed/viewport-height; the setup sub-route keeps the standard centered layout.
+  const isModView = /^\/mod\/[^/]+$/.test(pathname);
 
   return (
     <div className="min-h-screen bg-zinc-950 text-zinc-100">
-      <header className="border-b border-zinc-800">
+      {/* For the mod route the layout is full-bleed and fills the viewport so
+          the sidebar can scroll independently and the viewer gets all the space. */}
+      <div className={"flex min-h-screen flex-col " + (isModView ? "h-screen" : "")}>
+        <header className={"border-b border-zinc-800 " + (isModRoute ? "shrink-0" : "")}>
         {isModRoute ? (
           <ModHeader />
         ) : (
@@ -43,7 +48,7 @@ export default function App() {
           </div>
         )}
       </header>
-      <main className="mx-auto max-w-5xl px-4 py-8">
+      <main className={(isModView ? "min-h-0 flex-1" : "mx-auto max-w-5xl px-4 py-8")}>
         <Routes>
           <Route path="/" element={<SearchPage />} />
           <Route path="/mod/:id" element={<ModPage />} />
@@ -65,6 +70,7 @@ export default function App() {
           <Route path="/bgm/:id/setups/:type/:setup" element={<Suspense fallback={null}><SetupPage /></Suspense>} />
         </Routes>
       </main>
+      </div>
     </div>
   );
 }
\ No newline at end of file
diff --git a/apps/web/src/components/ObjectTree.tsx b/apps/web/src/components/ObjectTree.tsx
index 407736e..10d009e 100644
--- a/apps/web/src/components/ObjectTree.tsx
+++ b/apps/web/src/components/ObjectTree.tsx
@@ -32,44 +32,51 @@ export default function ObjectTree({ nodes, selectedPath, onSelect }: Props) {
   const clearAll = () => setHighlighted(new Set());
 
   return (
-    <div className="space-y-2">
+    <div className="flex h-full min-h-0 flex-col">
       {types.length > 0 && (
-        <div className="flex flex-wrap gap-1 border-b border-zinc-800 pb-2">
-          {types.map(({ name, count }) => {
-            const active = highlighted.has(name);
-            return (
-              <button
-                key={name}
-                onClick={() => toggleType(name)}
-                aria-pressed={active}
-                title={`${active ? 'Unhighlight' : 'Highlight'} ${name}`}
-                className={`inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs transition-colors ${
-                  active
-                    ? 'border-zinc-300 bg-zinc-700 text-zinc-100'
-                    : 'border-zinc-800 text-zinc-400 hover:border-zinc-600 hover:text-zinc-200'
-                }`}
-              >
-                <span className="inline-flex items-center gap-0.5">
+        <div className="shrink-0 border-b border-zinc-800 p-3 pb-2">
+          <div className="grid grid-cols-6 gap-1">
+            {types.map(({ name, count }) => {
+              const active = highlighted.has(name);
+              return (
+                <button
+                  key={name}
+                  onClick={() => toggleType(name)}
+                  aria-pressed={active}
+                  title={`${name} (${count}) — ${active ? 'unhighlight' : 'highlight'}`}
+                  className={`relative flex h-8 items-center justify-center rounded-md border transition-colors ${
+                    active
+                      ? 'border-zinc-300 bg-zinc-700 text-zinc-100'
+                      : 'border-zinc-800 text-zinc-400 hover:border-zinc-600 hover:text-zinc-200'
+                  }`}
+                >
                   {iconsForObject(name).map((icon) => (
-                    <Icon key={icon} icon={icon} className="h-3.5 w-3.5" />
+                    <Icon key={icon} icon={icon} className="h-4 w-4" />
                   ))}
-                </span>
-                <span>{name}</span>
-                <span className="text-zinc-500">{count}</span>
-              </button>
-            );
-          })}
+                  <span
+                    className={`absolute -bottom-1 -right-1 rounded bg-zinc-950 px-0.5 font-mono text-[9px] leading-tight ${
+                      active ? 'text-zinc-200' : 'text-zinc-500'
+                    }`}
+                  >
+                    {count}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
           {highlighted.size > 0 && (
-            <button
-              onClick={clearAll}
-              className="ml-auto inline-flex items-center rounded px-1.5 py-0.5 text-xs text-zinc-500 hover:text-zinc-200"
-            >
-              Clear
-            </button>
+            <div className="mt-1.5 flex justify-end">
+              <button
+                onClick={clearAll}
+                className="inline-flex items-center rounded px-1.5 py-0.5 text-xs text-zinc-500 hover:text-zinc-200"
+              >
+                Clear
+              </button>
+            </div>
           )}
         </div>
       )}
-      <ul className="space-y-0.5">
+      <ul className="min-h-0 flex-1 space-y-0.5 overflow-y-auto p-3 pt-2">
         {visibleNodes.map(({ node, path }) => (
           <TreeNode
             key={path}
diff --git a/apps/web/src/components/viewers.tsx b/apps/web/src/components/viewers.tsx
index ccac7ca..27739f3 100644
--- a/apps/web/src/components/viewers.tsx
+++ b/apps/web/src/components/viewers.tsx
@@ -8,7 +8,14 @@ import type { TTSObject } from '@tts/shared';
 export interface ObjectViewer {
   /** The object class this viewer handles, e.g. `Card`, `Bag`. */
   name: string;
-  component: (props: { object: TTSObject }) => ReactNode;
+  component: (props: ViewerProps) => ReactNode;
+}
+
+/** Props passed to every object viewer. */
+export interface ViewerProps {
+  object: TTSObject;
+  /** Expand the 3D scene to fill its container instead of the default frame. */
+  fill?: boolean;
 }
 
 const registry = new Map<string, ObjectViewer['component']>();
@@ -24,7 +31,7 @@ export function resolveViewer(object: TTSObject): ObjectViewer['component'] {
 }
 
 /** The default viewer: a plain inspection of the object's fields. */
-export function DefaultViewer({ object }: { object: TTSObject }) {
+export function DefaultViewer({ object }: ViewerProps) {
   return (
     <dl className="grid grid-cols-1 gap-2 text-sm sm:grid-cols-2">
       {Object.entries(object).map(([key, value]) => {
diff --git a/apps/web/src/components/viewers/CardViewer.tsx b/apps/web/src/components/viewers/CardViewer.tsx
index 98cea35..6fe1529 100644
--- a/apps/web/src/components/viewers/CardViewer.tsx
+++ b/apps/web/src/components/viewers/CardViewer.tsx
@@ -1,6 +1,7 @@
 import type { TTSObject } from '@tts/shared';
 import Scene from './Scene';
 import { CardObjectMesh } from './CardMesh';
+import type { ViewerProps } from '../viewers';
 
 /**
  * A playing card: a thin rounded rect with the face texture on the front and
@@ -24,9 +25,9 @@ import { CardObjectMesh } from './CardMesh';
  * It is flipped left/right so it isn't mirrored when viewed from the back of
  * the card.
  */
-export default function CardViewer({ object }: { object: TTSObject }) {
+export default function CardViewer({ object, fill }: ViewerProps) {
   return (
-    <Scene>
+    <Scene fill={fill}>
       <CardObjectMesh object={object} />
     </Scene>
   );
diff --git a/apps/web/src/components/viewers/CustomModelViewer.tsx b/apps/web/src/components/viewers/CustomModelViewer.tsx
index a3eb613..a52402b 100644
--- a/apps/web/src/components/viewers/CustomModelViewer.tsx
+++ b/apps/web/src/components/viewers/CustomModelViewer.tsx
@@ -1,6 +1,7 @@
 import type { TTSObject } from '@tts/shared';
 import Scene from './Scene';
 import { CustomModelMesh } from './CustomModelMesh';
+import type { ViewerProps } from '../viewers';
 
 /**
  * A custom 3D model loaded from `CustomMesh.MeshURL`. Supports GLTF/GLB, OBJ,
@@ -8,9 +9,9 @@ import { CustomModelMesh } from './CustomModelMesh';
  * (TTS model URLs are often extension-less). `DiffuseURL` is applied to the
  * model's materials when present.
  */
-export default function CustomModelViewer({ object }: { object: TTSObject }) {
+export default function CustomModelViewer({ object, fill }: ViewerProps) {
   return (
-    <Scene>
+    <Scene fill={fill}>
       <CustomModelMesh object={object} />
     </Scene>
   );
diff --git a/apps/web/src/components/viewers/DeckViewer.tsx b/apps/web/src/components/viewers/DeckViewer.tsx
index 2a7331a..01ab62e 100644
--- a/apps/web/src/components/viewers/DeckViewer.tsx
+++ b/apps/web/src/components/viewers/DeckViewer.tsx
@@ -6,6 +6,7 @@ import type { TTSObject } from '@tts/shared';
 import { useBounds } from '@react-three/drei';
 import Scene from './Scene';
 import { CardObjectMesh } from './CardMesh';
+import type { ViewerProps } from '../viewers';
 
 /** How many cards to show to each side of the active card. */
 const HALF_WINDOW = 3;
@@ -29,7 +30,7 @@ const ARC_PADDING = 0.2;
  * hidden), so large decks stay lean. Falls back to a single card (the deck
  * object itself) when there are no contained cards.
  */
-export default function DeckViewer({ object }: { object: TTSObject }) {
+export default function DeckViewer({ object, fill }: ViewerProps) {
   const cards = (object.ContainedObjects ?? []).filter(
     (o) => o.CardID != null || o.CustomImage != null,
   );
@@ -61,6 +62,7 @@ export default function DeckViewer({ object }: { object: TTSObject }) {
     <Scene
       fit={false}
       autoRotate={false}
+      fill={fill}
       overlay={
         hasCards ? (
           <CarouselControls active={active} count={count} onStep={step} />
@@ -116,16 +118,27 @@ function FitActive({
   onMeasure: (width: number) => void;
 }) {
   const bounds = useBounds();
+  // Whether the active card's width has been measured once. The fit waits one
+  // frame after measuring so the arc radius (and thus the active card's slot)
+  // has settled before framing it.
+  const measured = useRef(false);
 
   useFrame(() => {
     const node = targetRef.current;
     if (!node) return;
+    // Stop refreshing once fit: drei's `bounds.refresh()` resets the camera
+    // goal, so calling it every frame would wipe the fit we just set before
+    // the camera tween ever runs.
+    if (didFit.current) return;
     bounds.refresh(node);
     const { size, center, distance } = bounds.getSize();
     // Report the active card's width so the arc radius can widen for wide
-    // cards (see `arcRadius`). Runs every frame until the radius settles.
+    // cards (see `arcRadius`).
     onMeasure(size.x);
-    if (didFit.current) return;
+    if (!measured.current) {
+      measured.current = true;
+      return;
+    }
     didFit.current = true;
     // The card's front face points toward +Z, so put the camera in front of it
     // and look straight at it.
diff --git a/apps/web/src/components/viewers/Scene.tsx b/apps/web/src/components/viewers/Scene.tsx
index 4e9b62e..118857b 100644
--- a/apps/web/src/components/viewers/Scene.tsx
+++ b/apps/web/src/components/viewers/Scene.tsx
@@ -24,6 +24,9 @@ import { EffectComposer, Vignette } from '@react-three/postprocessing';
  * content on mount and resize. A viewer that needs to frame a specific part of
  * its content (e.g. the active card in a deck carousel) can set it to false and
  * call `useBounds()` itself to refit.
+ *
+ * By default the scene renders in an `aspect-[3/4]` frame; set `fill` to expand
+ * to the full height of its container (used by the inspector view).
  */
 export default function Scene({
   children,
@@ -31,6 +34,7 @@ export default function Scene({
   enablePan = false,
   fullscreen = false,
   fit = true,
+  fill = false,
   overlay,
   shadowScale = 22,
   maxPolarAngle = Math.PI,
@@ -41,6 +45,8 @@ export default function Scene({
   fullscreen?: boolean;
   /** Whether the shared scene fits + clips its children with `Bounds` (default true). */
   fit?: boolean;
+  /** Expand to fill the container height instead of the default aspect-[3/4] frame. */
+  fill?: boolean;
   /** HTML rendered inside the scene container (e.g. controls), shown in fullscreen. */
   overlay?: ReactNode;
   /** Contact shadow plane size in world units; defaults to a generous 22. */
@@ -65,7 +71,9 @@ export default function Scene({
   return (
     <div
       ref={containerRef}
-      className="relative aspect-[3/4] w-full overflow-hidden rounded-lg bg-linear-to-b from-zinc-300 to-zinc-400"
+      className={`relative w-full overflow-hidden rounded-lg bg-linear-to-b from-zinc-300 to-zinc-400 ${
+        fill ? 'h-full min-h-0' : 'aspect-[3/4]'
+      }`}
     >
       <LoadingOverlay />
       {fullscreen && (
diff --git a/apps/web/src/components/viewers/TileViewer.tsx b/apps/web/src/components/viewers/TileViewer.tsx
index b72150d..5d921da 100644
--- a/apps/web/src/components/viewers/TileViewer.tsx
+++ b/apps/web/src/components/viewers/TileViewer.tsx
@@ -1,6 +1,7 @@
 import type { TTSObject } from '@tts/shared';
 import Scene from './Scene';
 import { TileObjectMesh } from './TileMesh';
+import type { ViewerProps } from '../viewers';
 
 /**
  * A flat tile with a texture on its top face. Uses `CustomImage.ImageURL`
@@ -10,9 +11,9 @@ import { TileObjectMesh } from './TileMesh';
  * When `CustomTile.Stretch` is false, the tile's aspect ratio follows the
  * source image instead of being forced square.
  */
-export default function TileViewer({ object }: { object: TTSObject }) {
+export default function TileViewer({ object, fill }: ViewerProps) {
   return (
-    <Scene>
+    <Scene fill={fill}>
       <TileObjectMesh object={object} />
     </Scene>
   );
diff --git a/apps/web/src/components/viewers/TokenViewer.tsx b/apps/web/src/components/viewers/TokenViewer.tsx
index 04d77f5..e58de47 100644
--- a/apps/web/src/components/viewers/TokenViewer.tsx
+++ b/apps/web/src/components/viewers/TokenViewer.tsx
@@ -1,6 +1,7 @@
 import type { TTSObject } from '@tts/shared';
 import Scene from './Scene';
 import { TokenObjectMesh } from './TokenMesh';
+import type { ViewerProps } from '../viewers';
 
 /**
  * A token: a short extruded shape with the texture on its top face. Uses
@@ -8,9 +9,9 @@ import { TokenObjectMesh } from './TokenMesh';
  * color when absent. The footprint is traced from the image's alpha channel via
  * the proxy `/trace` endpoint, so the token matches the artwork's silhouette.
  */
-export default function TokenViewer({ object }: { object: TTSObject }) {
+export default function TokenViewer({ object, fill }: ViewerProps) {
   return (
-    <Scene>
+    <Scene fill={fill}>
       <TokenObjectMesh object={object} />
     </Scene>
   );
diff --git a/apps/web/src/pages/ModPage.tsx b/apps/web/src/pages/ModPage.tsx
index e80a442..80ed7ad 100644
--- a/apps/web/src/pages/ModPage.tsx
+++ b/apps/web/src/pages/ModPage.tsx
@@ -39,59 +39,37 @@ export default function ModPage() {
   const Viewer = selected ? resolveViewer(selected.object) : null;
 
   return (
-    <div className="space-y-6">
-      <div className="grid grid-cols-1 gap-6 lg:grid-cols-[280px_1fr]">
-        <aside className="rounded-lg border border-zinc-800 bg-zinc-900 p-2">
-          <ObjectTree
-            nodes={tree}
-            selectedPath={selectedPath}
-            onSelect={setSelectedPath}
-          />
-        </aside>
+    <div className="flex h-full min-h-0">
+      {/* Independently scrolling tree; the filter bar stays pinned above it. */}
+      <aside className="flex h-full min-h-0 w-72 shrink-0 flex-col border-r border-zinc-800 bg-zinc-900">
+        <ObjectTree
+          nodes={tree}
+          selectedPath={selectedPath}
+          onSelect={setSelectedPath}
+        />
+      </aside>
 
-        <section className="rounded-lg border border-zinc-800 bg-zinc-900 p-4">
-          {selected ? (
-            <>
-              <header className="mb-4 flex items-center gap-2">
-                <span
-                  title={selected.object.Name}
-                  className="inline-flex shrink-0 items-center gap-1 text-zinc-400"
-                >
-                  {iconsForObject(selected.object.Name).map((icon) => (
-                    <Icon key={icon} icon={icon} className="h-5 w-5" />
-                  ))}
-                </span>
-                <h2 className="min-w-0 flex-1 truncate text-lg font-semibold">
-                  {selected.label}
-                </h2>
-                <span className="shrink-0 font-mono text-xs text-zinc-500">
-                  {selected.object.GUID}
-                </span>
-              </header>
-
-              {Viewer && (
-                <ErrorBoundary>
-                  <Suspense
-                    fallback={
-                      <div className="flex h-80 items-center justify-center text-sm text-zinc-500">
-                        Loading viewer…
-                      </div>
-                    }
-                  >
-                    {/* Key by selection path so the Canvas remounts and the
-                        camera refits to the newly selected object. */}
-                    <Viewer key={selectedPath} object={selected.object} />
-                  </Suspense>
-                </ErrorBoundary>
-              )}
-            </>
-          ) : (
-            <p className="text-sm text-zinc-500">
-              Select an object from the tree to inspect it.
-            </p>
-          )}
-        </section>
-      </div>
+      <section className="h-full min-h-0 flex-1 p-4">
+        {selected && Viewer ? (
+          /* Key by selection path so the Canvas remounts and the camera
+             refits to the newly selected object. */
+          <ErrorBoundary>
+            <Suspense
+              fallback={
+                <div className="flex h-full items-center justify-center text-sm text-zinc-500">
+                  Loading viewer…
+                </div>
+              }
+            >
+              <Viewer key={selectedPath} object={selected.object} fill />
+            </Suspense>
+          </ErrorBoundary>
+        ) : (
+          <div className="flex h-full items-center justify-center text-sm text-zinc-500">
+            Select an object from the tree to inspect it.
+          </div>
+        )}
+      </section>
     </div>
   );
 }